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