1.. _docs-targets: 2 3======= 4Targets 5======= 6Pigweed is designed to be portable to many different hardware platforms. 7Pigweed's GN build comes with an extensible target system that allows it to be 8configured to build for any number of platforms, which all build simultaneously. 9 10Defining a target 11================= 12Each Pigweed target built by a project is defined within the GN build as a 13toolchain providing the target's build parameters. 14 15In Pigweed, these target toolchains are defined as GN scopes, which are fed into 16a ``generate_toolchain`` template to create the complete GN toolchain. 17 18Hierarchical target structure 19----------------------------- 20The rationale for scope-based toolchains is to make Pigweed targets extensible. 21Variables from a toolchain can be forwarded into new scopes and then extended 22or overriden. This facilitates the sharing of common configuration options 23between toolchains, and allows for hierarchical structures. Upstream Pigweed 24makes use of this heavily; it defines basic compiler-only configurations, uses 25these as a base for board-specific toolchains, then creates its final targets on 26top of those. 27 28.. blockdiag:: 29 30 blockdiag { 31 default_fontsize = 14; 32 orientation = portrait; 33 34 arm_gcc [label = "arm_gcc"]; 35 arm_gcc_cortex_m4 [label = "cortex_m4"]; 36 arm_gcc_cortex_m4f [label = "cortex_m4f"]; 37 arm_gcc_cortex_m4f_debug [label = "cortex_m4f_debug"]; 38 arm_gcc_cortex_m4f_size_optimized [label = "cortex_m4f_size_optimized"]; 39 stm32f429i_disc1_debug [label = "stm32f429i_disc1_debug"]; 40 arm_gcc -> arm_gcc_cortex_m4 41 arm_gcc -> arm_gcc_cortex_m4f 42 arm_gcc_cortex_m4f -> arm_gcc_cortex_m4f_debug 43 arm_gcc_cortex_m4f -> arm_gcc_cortex_m4f_size_optimized 44 arm_gcc_cortex_m4f_debug -> stm32f429i_disc1_debug 45 } 46 47Toolchain target variables 48-------------------------- 49The core of a toolchain is defining the tools it uses. This is done by setting 50the variables ``ar``, ``cc``, and ``cxx`` to the appropriate compilers. Pigweed 51provides many commonly used compiler configurations in the ``pw_toolchain`` 52module. 53 54The rest of the a Pigweed target's configuration is listed within a ``defaults`` 55scope in its toolchain. Every variable in this scope is an override of a GN 56build argument defined in Pigweed. Some notable arguments include: 57 58* ``default_configs``: A list of GN configs to apply to every ``pw_*`` GN 59 template. This is typically used to set compiler flags, optimization levels, 60 global #defines, etc. 61* ``default_public_deps``: List of GN targets which are added as a dependency 62 to all ``pw_*`` GN targets. This is used to add global module dependencies; 63 for example, in upstream, ``pw_polyfill`` is added here to provide C++17 64 features in C++11/C++14 code. 65* Facade backends: Pigweed defines facades to provide a common interface for 66 core system features such as logging without assuming an implementation. 67 When building a Pigweed target, the implementations for each of these must be 68 chosen. The ``*_BACKEND`` build args that Pigweed defines are used to set 69 these. 70 71There are many other build arguments that can be set, some of which are 72module-specific. A full list can be seen by running ``gn args --list out``, 73and further documentation can be found within their respective modules. 74 75Example Pigweed target 76====================== 77The code below demonstrates how a project might configure one of its Pigweed 78targets. 79 80.. code:: 81 82 # Prevent gn format from reordering this import. 83 import("//build_overrides/pigweed.gni") 84 85 import("$dir_pw_toolchain/arm_gcc/toolchains.gni") 86 import("$dir_pw_toolchain/generate_toolchain.gni") 87 88 my_target_scope = { 89 # Use Pigweed's Cortex M4 toolchain as a base. 90 _toolchain_base = pw_toolchain_arm_gcc.cortex_m4f_debug 91 92 # Forward everything except the defaults scope from that toolchain. 93 forward_variables_from(_toolchain_base, "*", [ "defaults" ]) 94 95 defaults = { 96 # Forward everything from the base toolchain's defaults. 97 forward_variables_from(_toolchain_base.defaults, "*") 98 99 # Extend with custom build arguments for the target. 100 pw_log_BACKEND = dir_pw_log_tokenized 101 } 102 } 103 104 # Create the actual GN toolchain from the scope. 105 generate_toolchain("my_target") { 106 forward_variables_from(my_target_scope, "*") 107 } 108 109Upstream targets 110================ 111The following is a list of targets used for upstream Pigweed development. 112 113.. toctree:: 114 :maxdepth: 1 115 :glob: 116 117 targets/*/target_docs 118