1.. _module-pw_android_toolchain: 2 3-------------------- 4pw_android_toolchain 5-------------------- 6Android toolchains differ from ``pw_toolchain`` in that the latter defines the 7tool names and paths at the lowest level, with customisation added at higher 8levels, while in ``pw_android_toolchain`` the tool names and paths are derived 9from build args and defaults so are defined last by calling 10``pw_generate_android_toolchain``. 11 12Setup 13===== 14You must first download and unpack a copy of the `Android NDK`_ and let Pigweed 15know where that is located using the ``pw_android_toolchain_NDK_PATH`` build 16arg. 17 18.. _Android NDK: https://developer.android.com/ndk 19 20You can set Pigweed build options using ``gn args out``. 21 22Toolchains 23========== 24``pw_android_toolchain`` provides GN toolchains that may be used to build 25Pigweed 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 43Defining Toolchains 44=================== 45Defining Android NDK toolchains is similar to ``pw_toolchain`` except that 46instead of using ``generate_toolchain`` use ``pw_generate_android_toolchain``, 47and ensure that ``current_cpu`` is set in the toolchain ``defaults``. 48 49For 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 82Since Android NDKs contain toolchains for all supported targets, as a 83convenience, ``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 85toolchain 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 94Customization 95------------- 96The Android SDK target version defaults to the value of the 97``pw_android_toolchain_API_LEVEL`` build arg. You can override this on global 98level, or on a per-toolchain level by setting ``api_level`` in the toolchain 99defaults. 100