1.. _module-pw_build_android: 2 3================ 4pw_build_android 5================ 6.. pigweed-module:: 7 :name: pw_build_android 8 9``pw_build_android`` provides simple utilities and guidelines for building with 10Soong. 11 12---------- 13Quickstart 14---------- 15Use the ``pw_android_common_backends`` ``cc_defaults`` in the Pigweed module 16library or binary rule to use a preselected set of backends common to most 17Android platform projects. 18 19.. code-block:: androidbp 20 21 cc_binary { 22 name: "my_app", 23 host_supported: true, 24 vendor: true, 25 defaults: [ 26 "pw_android_common_backends", 27 ], 28 srcs: [ 29 "main.cc", 30 ], 31 } 32 33 34---------------------------- 35Basic blueprint files format 36---------------------------- 37All Pigweed Soong blueprint files must be named ``Android.bp``, and include the 38folowing copyright header with the year adjusted and package. 39 40.. code-block:: androidbp 41 42 // Copyright 2024 The Pigweed Authors 43 // 44 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 45 // use this file except in compliance with the License. You may obtain a copy of 46 // the License at 47 // 48 // https://www.apache.org/licenses/LICENSE-2.0 49 // 50 // Unless required by applicable law or agreed to in writing, software 51 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 52 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 53 // License for the specific language governing permissions and limitations under 54 // the License. 55 56 package { 57 default_applicable_licenses: ["external_pigweed_license"], 58 } 59 60The ``bpfmt`` tool in Android can be used to format a blueprint file, e.g. 61``bpfmt -w Android.bp``. 62 63.. _module-pw_build_android-common-backends: 64 65----------------------- 66Common Android backends 67----------------------- 68Soong doesn't provide a simple way to select custom Pigweed backends, as is 69found in other build systems. Fortunately, most Android platform binaries will 70likely use the same common set of backends. Thus, Pigweed provides a 71``cc_defaults`` rule named ``pw_android_common_backends`` with a selected set of 72common backends for Android platform binaries. This 73``pw_android_common_backends`` rule will be used in all Pigweed modules and 74backends defined using Soong. 75 76This table lists the backends selected by this rule: 77 78.. list-table:: ``pw_android_common_backends`` 79 :align: left 80 :header-rows: 1 81 82 * - Facade 83 - Selected Backend 84 * - :ref:`module-pw_assert` 85 - :ref:`module-pw_assert_log` 86 * - :ref:`module-pw_log` 87 - :ref:`module-pw_log_android` 88 * - :ref:`module-pw_chrono` 89 - :ref:`module-pw_chrono_stl` 90 * - :ref:`module-pw_sync` 91 - :ref:`module-pw_sync_stl` 92 * - :ref:`module-pw_thread` 93 - :ref:`module-pw_thread_stl` 94 95.. _module-pw_build_android-module-libraries: 96 97---------------- 98Module libraries 99---------------- 100Module libraries are defined as ``cc_library_static`` rules and include the 101common Android backends via the ``pw_android_common_backends`` defaults. 102 103.. note:: 104 105 Every dependency has to be added as ``whole_static_libs`` to avoid dropping 106 symbols on transitive dependencies. 107 108.. code-block:: androidbp 109 110 cc_library_static { 111 name: "pw_<MODULE_NAME>", 112 cpp_std: "c++20", 113 export_include_dirs: ["public"], 114 vendor_available: true, 115 host_supported: true, 116 defaults: [ 117 "pw_android_common_backends", 118 ], 119 header_libs: [ 120 // Header library list for all the libraries in #include directives. 121 ], 122 export_header_lib_headers: [ 123 // Header library list for all the libraries in #include directives 124 // in public header files only. 125 // These entries must also be present in header_libs. 126 ], 127 whole_static_libs: [ 128 // Static library list for all static library dependencies, listed as 129 // whole libraries to avoid dropping symbols in transitive 130 // dependencies. 131 ], 132 export_static_lib_headers: [ 133 // Static library list for static libraries in #include directives in 134 // public header files only. 135 // These entries must also be present in whole_static_libs. 136 ], 137 srcs: [ 138 // List of source (.cc) files. 139 ], 140 } 141 142Module libraries with custom backends 143------------------------------------- 144If a Pigweed module needs to be used with a backend different than the common 145Android backend, it should be defined as a ``cc_defaults`` rule following the 146``pw_<MODULE_NAME>_no_backends`` name format, with the source files listed in a 147``filegroup`` following the ``pw_<MODULE_NAME>_src_files`` name format and the 148include directories defined as a ``cc_library_headers`` following the 149``pw_<MODULE_NAME>_include_dirs`` name format. A ``cc_static_library`` with the 150common Android backend should still be provided, which uses the mentioned 151``cc_defaults``. 152 153.. note:: 154 155 ``filegroup`` captures the absolute paths of the listed source files, so they 156 can be addressed properly when the ``cc_defaults`` rule is used. 157 158.. code-block:: androidbp 159 160 filegroup { 161 name: "pw_<MODULE_NAME>_src_files", 162 srcs: [ 163 // List of source (.cc) files. 164 ], 165 } 166 167 cc_library_headers { 168 name: "pw_<MODULE_NAME>_include_dirs", 169 export_include_dirs: [ 170 "public", 171 ], 172 vendor_available: true, 173 host_supported: true, 174 } 175 176 cc_defaults { 177 name: "pw_<MODULE_NAME>_no_backends", 178 cpp_std: "c++20", 179 180 header_libs: [ 181 // Header library list for all the libraries in #include directives. 182 "pw_<MODULE_NAME>_include_dirs" 183 ], 184 export_header_lib_headers: [ 185 // Header library list for all the libraries in #include directives 186 // in public header files only. 187 // These entries must also be present in header_libs. 188 ], 189 whole_static_libs: [ 190 // Static library list for all static library dependencies, listed as 191 // whole libraries to avoid dropping symbols in transitive 192 // dependencies. 193 ], 194 export_static_lib_headers: [ 195 // Static library list for static libraries in #include directives in 196 // public header files only. 197 // These entries must also be present in whole_static_libs. 198 ], 199 srcs: [ 200 "pw_<MODULE_NAME>_src_files", 201 ], 202 } 203 204 cc_library_static { 205 name: "pw_<MODULE_NAME>", 206 cpp_std: "c++20", 207 export_include_dirs: ["public"], 208 defaults: [ 209 "pw_android_common_backends", 210 "pw_<MODULE_NAME>_no_backends", 211 ], 212 vendor_available: true, 213 host_supported: true, 214 } 215 216Module libraries with configurable build flags 217---------------------------------------------- 218If a Pigweed module provides user-configurable build flags it should be defined 219as a ``cc_defaults`` rule following the ``pw_<MODULE_NAME>_defaults`` name 220format. This hints the user that the rule must be initialized with the desired 221build flag values. Source files must be listed in a ``filegroup`` following the 222``pw_<MODULE_NAME>_src_files`` name format and the include directories defined 223as a ``cc_library_headers`` following the ``pw_<MODULE_NAME>_include_dirs`` name 224format. 225 226.. code-block:: androidbp 227 228 filegroup { 229 name: "pw_<MODULE_NAME>_src_files", 230 srcs: [ 231 // List of source (.cc) files. 232 ], 233 } 234 235 cc_library_headers { 236 name: "pw_<MODULE_NAME>_include_dirs", 237 export_include_dirs: [ 238 "public", 239 ], 240 vendor_available: true, 241 host_supported: true, 242 } 243 244 cc_defaults { 245 name: "pw_<MODULE_NAME>_defaults", 246 cpp_std: "c++20", 247 248 header_libs: [ 249 // Header library list for all the libraries in #include directives. 250 "pw_<MODULE_NAME>_include_dirs" 251 ], 252 export_header_lib_headers: [ 253 // Header library list for all the libraries in #include directives 254 // in public header files only. 255 // These entries must also be present in header_libs. 256 ], 257 whole_static_libs: [ 258 // Static library list for all static library dependencies, listed as 259 // whole libraries to avoid dropping symbols in transitive 260 // dependencies. 261 ], 262 export_static_lib_headers: [ 263 // Static library list for static libraries in #include directives in 264 // public header files only. 265 // These entries must also be present in whole_static_libs. 266 ], 267 srcs: [ 268 "pw_<MODULE_NAME>_src_files", 269 ], 270 } 271 272A downstream user can instantiate the ``pw_<MODULE_NAME>_defaults`` rule as 273follows. 274 275.. note:: 276 277 To avoid collisions the rule using the ``cc_defaults`` must have a unique 278 name that distinguishes it from other rule names in Pigweed and other 279 projects. It is recommended to suffix the project name. 280 281.. code-block:: androidbp 282 283 cc_library_static { 284 name: "pw_<MODULE_NAME>_<PROJECT_NAME>", 285 cflags: [ 286 "-DPW_<MODULE_NAME>_<FLAG_NAME>=<FLAG_VALUE>", 287 ], 288 defaults: [ 289 "pw_<MODULE_NAME>_defaults", 290 ], 291 } 292 293------- 294Facades 295------- 296All facades must be defined as ``cc_library_headers`` if they don’t have 297``srcs`` list. The facade names follow the ``pw_<MODULE_NAME>.<FACADE_NAME>``. 298In the case there is only one facade in the module or ``<MODULE_NAME>`` is 299the same as ``<FACADE_NAME>`` follow ``pw_<MODULE_NAME>``, e.g. ``pw_log``. 300 301.. note:: 302 Facade names should not be suffixed with ``_headers``. 303 304.. code-block:: androidbp 305 306 cc_library_headers { 307 name: "pw_<MODULE_NAME>.<FACADE_NAME>", 308 cpp_std: "c++20", 309 vendor_available: true, 310 host_supported: true, 311 export_include_dirs: ["public"], 312 } 313 314If a facade requires a ``srcs`` list, it must be defined as a ``cc_defaults`` 315rule instead, with the source files listed in a ``filegroup`` following the 316``pw_<MODULE_NAME>.<FACADE_NAME>_files`` name format or 317``pw_<MODULE_NAME>_files`` if applicable. 318 319.. note:: 320 321 ``filegroup`` captures the absolute paths of the listed source files, so they 322 can be addressed properly when the ``cc_defaults`` rule is used. 323 324.. note:: 325 326 Facades cannot be defined as ``cc_static_library`` because it wouldn’t be 327 possible to build the facade without a backend. 328 329.. code-block:: androidbp 330 331 filegroup { 332 name: "pw_<MODULE_NAME>.<FACADE_NAME>_files", 333 srcs: [ 334 // List of source (.cc) files. 335 ], 336 } 337 338 cc_defaults { 339 name: "pw_<MODULE_NAME>.<FACADE_NAME>", 340 cpp_std: "c++20", 341 export_include_dirs: ["public"], 342 srcs: [ 343 "pw_<MODULE_NAME>.<FACADE_NAME>_files", 344 ], 345 } 346 347To assign a backend to a facade defined as ``cc_defaults`` the ``cc_defaults`` 348rule can be placed in the ``defaults`` list of a ``cc_static_library`` rule or 349binary rule that lists the facade's backend as a dependency. 350 351.. code-block:: androidbp 352 353 cc_static_library { 354 name: "user_of_pw_<MODULE_NAME>.<FACADE_NAME>", 355 cpp_std: "c++20", 356 vendor_available: true, 357 host_supported: true, 358 defaults: [ 359 "pw_<MODULE_NAME>.<FACADE_NAME>", 360 ], 361 static_libs: [ 362 "backend_of_pw_<MODULE_NAME>.<FACADE_NAME>", 363 ], 364 } 365 366Alternatively, the ``cc_defaults`` rule can be placed in the ``defaults`` list 367of another ``cc_defaults`` rule where the latter rule may or may not list the 368facade's backend. ``cc_defaults`` rules can be inherited many times. Facades 369can be used as long as the backends are assigned in ``cc_static_library`` or 370binary rules using the final ``cc_defaults`` as explained above. 371 372-------- 373Backends 374-------- 375Backends are defined the same way as 376:ref:`module-pw_build_android-module-libraries`. They must follow the 377``pw_<MODULE_NAME>.<FACADE_NAME>_<BACKEND_NAME>`` name format or 378``pw_<MODULE_NAME>_<BACKEND_NAME>`` if applicable. 379 380----------- 381Build flags 382----------- 383Some build flags should be set for all Android targets; these flags are 384specified in ``pw_android_common_backends``. These flags are as follows: 385 386``PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION`` 387----------------------------------------- 388As discussed in :ref:`module-pw_function-dynamic-allocation`, this flag enables 389dynamic allocation of :cpp:type:`pw::Function`, allowing it to exceed the 390inline size limit. 391 392Android targets support dynamic allocation since the Android environment is not 393memory constrained. Thus, ``PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION`` is enabled 394in ``pw_android_common_backends``. Components built with dynamic allocation 395disabled cannot be linked against components with dynamic allocation enabled. 396