Scott James Remnant | aa00a15 | 2021-07-30 11:39:37 -0700 | [diff] [blame] | 1 | .. _module-pw_android_toolchain: |
| 2 | |
| 3 | -------------------- |
| 4 | pw_android_toolchain |
| 5 | -------------------- |
| 6 | Android toolchains differ from ``pw_toolchain`` in that the latter defines the |
| 7 | tool names and paths at the lowest level, with customisation added at higher |
| 8 | levels, while in ``pw_android_toolchain`` the tool names and paths are derived |
| 9 | from build args and defaults so are defined last by calling |
| 10 | ``pw_generate_android_toolchain``. |
| 11 | |
| 12 | Setup |
| 13 | ===== |
| 14 | You must first download and unpack a copy of the `Android NDK`_ and let Pigweed |
| 15 | know where that is located using the ``pw_android_toolchain_NDK_PATH`` build |
| 16 | arg. |
| 17 | |
| 18 | .. _Android NDK: https://developer.android.com/ndk |
| 19 | |
| 20 | You can set Pigweed build options using ``gn args out``. |
| 21 | |
| 22 | Toolchains |
| 23 | ========== |
| 24 | ``pw_android_toolchain`` provides GN toolchains that may be used to build |
| 25 | Pigweed against an Android NDK. The following toolchains are defined: |
| 26 | |
| 27 | - arm_android_debug |
| 28 | - arm_android_size_optimized |
| 29 | - arm_android_speed_optimized |
| 30 | - arm64_android_debug |
| 31 | - arm64_android_size_optimized |
| 32 | - arm64_android_speed_optimized |
| 33 | - x64_android_debug |
| 34 | - x64_android_size_optimized |
| 35 | - x64_android_speed_optimized |
| 36 | - x86_android_debug |
| 37 | - x86_android_size_optimized |
| 38 | - x86_android_speed_optimized |
| 39 | |
| 40 | .. note:: |
| 41 | The documentation for this module is currently incomplete. |
| 42 | |
| 43 | Defining Toolchains |
| 44 | =================== |
| 45 | Defining Android NDK toolchains is similar to ``pw_toolchain`` except that |
| 46 | instead of using ``generate_toolchain`` use ``pw_generate_android_toolchain``, |
| 47 | and ensure that ``current_cpu`` is set in the toolchain ``defaults``. |
| 48 | |
| 49 | For example: |
| 50 | |
| 51 | .. code:: |
| 52 | |
| 53 | import("//build_overrides/pigweed.gni") |
| 54 | |
| 55 | import("$dir_pw_android_toolchain/toolchains.gni") |
| 56 | import("$dir_pw_android_toolchain/generate_toolchain.gni") |
| 57 | |
| 58 | my_target_scope = { |
| 59 | # Use Pigweed's Android toolchain as a base. |
| 60 | _toolchain_base = pw_toolchain_android.debug |
| 61 | |
| 62 | # Forward everything except the defaults scope from that toolchain. |
| 63 | forward_variables_from(_toolchain_base, "*", [ "defaults" ]) |
| 64 | |
| 65 | defaults = { |
| 66 | # Forward everything from the base toolchain's defaults. |
| 67 | forward_variables_from(_toolchain_base.defaults, "*") |
| 68 | |
| 69 | # Build for 64-bit AArch64 Android devices. |
| 70 | current_cpu = "arm64" |
| 71 | |
| 72 | # Extend with custom build arguments for the target. |
| 73 | pw_log_BACKEND = dir_pw_log_tokenized |
| 74 | } |
| 75 | } |
| 76 | |
| 77 | # Create the actual GN toolchain from the scope. |
| 78 | pw_generate_android_toolchain("my_target") { |
| 79 | forward_variables_from(my_target_scope, "*") |
| 80 | } |
| 81 | |
| 82 | Since Android NDKs contain toolchains for all supported targets, as a |
| 83 | convenience, ``pw_generate_android_toolchains`` does not require that |
| 84 | ``current_cpu`` is set. If any toolchain scope in the list does not set it, a |
| 85 | toolchain for each supported target will be generated. |
| 86 | |
| 87 | .. code:: |
| 88 | |
| 89 | # Generate arm_*, arm64_*, x64_*, and x86_* for each scope in the list. |
| 90 | pw_generate_android_toolchains("target_toolchains) { |
| 91 | toolchains = pw_toolchain_android_list |
| 92 | } |
| 93 | |
| 94 | Customization |
| 95 | ------------- |
| 96 | The Android SDK target version defaults to the value of the |
| 97 | ``pw_android_toolchain_API_LEVEL`` build arg. You can override this on global |
| 98 | level, or on a per-toolchain level by setting ``api_level`` in the toolchain |
| 99 | defaults. |