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 // List of cc_library_headers dependencies needed to support 121 // #include directives in the module's header files. 122 ], 123 export_header_lib_headers: [ 124 // List of cc_library_headers dependencies needed to support #include 125 // directives in the module's public header files. 126 // These entries must also be present in header_libs. 127 ], 128 whole_static_libs: [ 129 // List of cc_library_static dependencies, listed as whole libraries 130 // to avoid dropping symbols in transitive dependencies. 131 ], 132 export_static_lib_headers: [ 133 // List of cc_library_static dependencies needed to support #include 134 // directives in the module's public header files. 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.. warning:: 159 160 Do not include ``vendor_available: true`` or other similar flags in a 161 ``cc_defaults`` as this will conflict with downstream users of the defaults. 162 163.. code-block:: androidbp 164 165 filegroup { 166 name: "pw_<MODULE_NAME>_src_files", 167 srcs: [ 168 // List of source (.cc) files. 169 ], 170 } 171 172 cc_library_headers { 173 name: "pw_<MODULE_NAME>_include_dirs", 174 export_include_dirs: [ 175 "public", 176 ], 177 vendor_available: true, 178 host_supported: true, 179 } 180 181 cc_defaults { 182 name: "pw_<MODULE_NAME>_no_backends", 183 cpp_std: "c++20", 184 185 header_libs: [ 186 // Header library list for all the libraries in #include directives. 187 "pw_<MODULE_NAME>_include_dirs" 188 ], 189 export_header_lib_headers: [ 190 // Header library list for all the libraries in #include directives 191 // in public header files only. 192 // These entries must also be present in header_libs. 193 ], 194 whole_static_libs: [ 195 // Static library list for all static library dependencies, listed as 196 // whole libraries to avoid dropping symbols in transitive 197 // dependencies. 198 ], 199 export_static_lib_headers: [ 200 // Static library list for static libraries in #include directives in 201 // public header files only. 202 // These entries must also be present in whole_static_libs. 203 ], 204 srcs: [ 205 "pw_<MODULE_NAME>_src_files", 206 ], 207 } 208 209 cc_library_static { 210 name: "pw_<MODULE_NAME>", 211 cpp_std: "c++20", 212 export_include_dirs: ["public"], 213 defaults: [ 214 "pw_android_common_backends", 215 "pw_<MODULE_NAME>_no_backends", 216 ], 217 vendor_available: true, 218 host_supported: true, 219 } 220 221Module libraries with configurable build flags 222---------------------------------------------- 223If a Pigweed module provides user-configurable build flags it should be defined 224as a ``cc_defaults`` rule following the ``pw_<MODULE_NAME>_defaults`` name 225format. This hints the user that the rule must be initialized with the desired 226build flag values. Source files must be listed in a ``filegroup`` following the 227``pw_<MODULE_NAME>_src_files`` name format and the include directories defined 228as a ``cc_library_headers`` following the ``pw_<MODULE_NAME>_include_dirs`` name 229format. 230 231.. code-block:: androidbp 232 233 filegroup { 234 name: "pw_<MODULE_NAME>_src_files", 235 srcs: [ 236 // List of source (.cc) files. 237 ], 238 } 239 240 cc_library_headers { 241 name: "pw_<MODULE_NAME>_include_dirs", 242 export_include_dirs: [ 243 "public", 244 ], 245 vendor_available: true, 246 host_supported: true, 247 } 248 249 cc_defaults { 250 name: "pw_<MODULE_NAME>_defaults", 251 cpp_std: "c++20", 252 253 header_libs: [ 254 // Header library list for all the libraries in #include directives. 255 "pw_<MODULE_NAME>_include_dirs" 256 ], 257 export_header_lib_headers: [ 258 // Header library list for all the libraries in #include directives 259 // in public header files only. 260 // These entries must also be present in header_libs. 261 ], 262 whole_static_libs: [ 263 // Static library list for all static library dependencies, listed as 264 // whole libraries to avoid dropping symbols in transitive 265 // dependencies. 266 ], 267 export_static_lib_headers: [ 268 // Static library list for static libraries in #include directives in 269 // public header files only. 270 // These entries must also be present in whole_static_libs. 271 ], 272 srcs: [ 273 "pw_<MODULE_NAME>_src_files", 274 ], 275 } 276 277A downstream user can instantiate the ``pw_<MODULE_NAME>_defaults`` rule as 278follows. 279 280.. note:: 281 282 To avoid collisions the rule using the ``cc_defaults`` must have a unique 283 name that distinguishes it from other rule names in Pigweed and other 284 projects. It is recommended to suffix the project name. 285 286.. code-block:: androidbp 287 288 cc_library_static { 289 name: "pw_<MODULE_NAME>_<PROJECT_NAME>", 290 cflags: [ 291 "-DPW_<MODULE_NAME>_<FLAG_NAME>=<FLAG_VALUE>", 292 ], 293 defaults: [ 294 "pw_<MODULE_NAME>_defaults", 295 ], 296 } 297 298------- 299Facades 300------- 301All facades must be defined as ``cc_library_headers`` if they don’t have 302``srcs`` list. The facade names follow the ``pw_<MODULE_NAME>.<FACADE_NAME>``. 303In the case there is only one facade in the module or ``<MODULE_NAME>`` is 304the same as ``<FACADE_NAME>`` follow ``pw_<MODULE_NAME>``, e.g. ``pw_log``. 305 306.. note:: 307 Facade names should not be suffixed with ``_headers``. 308 309.. code-block:: androidbp 310 311 cc_library_headers { 312 name: "pw_<MODULE_NAME>.<FACADE_NAME>", 313 cpp_std: "c++20", 314 vendor_available: true, 315 host_supported: true, 316 export_include_dirs: ["public"], 317 } 318 319If a facade requires a ``srcs`` list, it must be defined as a ``cc_defaults`` 320rule instead, with the source files listed in a ``filegroup`` following the 321``pw_<MODULE_NAME>.<FACADE_NAME>_files`` name format or 322``pw_<MODULE_NAME>_files`` if applicable. 323 324.. note:: 325 326 ``filegroup`` captures the absolute paths of the listed source files, so they 327 can be addressed properly when the ``cc_defaults`` rule is used. 328 329.. note:: 330 331 Facades cannot be defined as ``cc_static_library`` because it wouldn’t be 332 possible to build the facade without a backend. 333 334.. code-block:: androidbp 335 336 filegroup { 337 name: "pw_<MODULE_NAME>.<FACADE_NAME>_files", 338 srcs: [ 339 // List of source (.cc) files. 340 ], 341 } 342 343 cc_defaults { 344 name: "pw_<MODULE_NAME>.<FACADE_NAME>", 345 cpp_std: "c++20", 346 export_include_dirs: ["public"], 347 srcs: [ 348 "pw_<MODULE_NAME>.<FACADE_NAME>_files", 349 ], 350 } 351 352To assign a backend to a facade defined as ``cc_defaults`` the ``cc_defaults`` 353rule can be placed in the ``defaults`` list of a ``cc_static_library`` rule or 354binary rule that lists the facade's backend as a dependency. 355 356.. code-block:: androidbp 357 358 cc_static_library { 359 name: "user_of_pw_<MODULE_NAME>.<FACADE_NAME>", 360 cpp_std: "c++20", 361 vendor_available: true, 362 host_supported: true, 363 defaults: [ 364 "pw_<MODULE_NAME>.<FACADE_NAME>", 365 ], 366 static_libs: [ 367 "backend_of_pw_<MODULE_NAME>.<FACADE_NAME>", 368 ], 369 } 370 371Alternatively, the ``cc_defaults`` rule can be placed in the ``defaults`` list 372of another ``cc_defaults`` rule where the latter rule may or may not list the 373facade's backend. ``cc_defaults`` rules can be inherited many times. Facades 374can be used as long as the backends are assigned in ``cc_static_library`` or 375binary rules using the final ``cc_defaults`` as explained above. 376 377-------- 378Backends 379-------- 380Backends are defined the same way as 381:ref:`module-pw_build_android-module-libraries`. They must follow the 382``pw_<MODULE_NAME>.<FACADE_NAME>_<BACKEND_NAME>`` name format or 383``pw_<MODULE_NAME>_<BACKEND_NAME>`` if applicable. 384 385----------- 386Build flags 387----------- 388Some build flags should be set for all Android targets; these flags are 389specified in ``pw_android_common_backends``. These flags are as follows: 390 391``PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION`` 392----------------------------------------- 393As discussed in :ref:`module-pw_function-dynamic-allocation`, this flag enables 394dynamic allocation of :cpp:type:`pw::Function`, allowing it to exceed the 395inline size limit. 396 397Android targets support dynamic allocation since the Android environment is not 398memory constrained. Thus, ``PW_FUNCTION_ENABLE_DYNAMIC_ALLOCATION`` is enabled 399in ``pw_android_common_backends``. Components built with dynamic allocation 400disabled cannot be linked against components with dynamic allocation enabled. 401