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.. mermaid:: 29 30 graph TD 31 arm_gcc --> arm_gcc_cortex_m4 32 arm_gcc --> arm_gcc_cortex_m4f 33 arm_gcc_cortex_m4f --> arm_gcc_cortex_m4f_debug 34 arm_gcc_cortex_m4f --> arm_gcc_cortex_m4f_size_optimized 35 arm_gcc_cortex_m4f_debug --> stm32f429i_disc1_debug 36 37Toolchain target variables 38-------------------------- 39The core of a toolchain is defining the tools it uses. This is done by setting 40the variables ``ar``, ``cc``, and ``cxx`` to the appropriate compilers. Pigweed 41provides many commonly used compiler configurations in the ``pw_toolchain`` 42module. 43 44The rest of the a Pigweed target's configuration is listed within a ``defaults`` 45scope in its toolchain. Every variable in this scope is an override of a GN 46build argument defined in Pigweed. Some notable arguments include: 47 48* ``default_configs``: A list of GN configs to apply to every ``pw_*`` GN 49 template. This is typically used to set compiler flags, optimization levels, 50 global #defines, etc. 51* ``default_public_deps``: List of GN targets which are added as a dependency 52 to all ``pw_*`` GN targets. This is used to add global module dependencies; 53 for example, in upstream, ``pw_polyfill`` is added here to provide C++17 54 features in C++14 code. 55* Facade backends: Pigweed defines facades to provide a common interface for 56 core system features such as logging without assuming an implementation. 57 When building a Pigweed target, the implementations for each of these must be 58 chosen. The ``*_BACKEND`` build args that Pigweed defines are used to set 59 these. 60 61There are many other build arguments that can be set, some of which are 62module-specific. A full list can be seen by running ``gn args --list out``, 63and further documentation can be found within their respective modules. 64 65Example Pigweed target 66====================== 67The code below demonstrates how a project might configure one of its Pigweed 68targets. 69 70.. code-block:: 71 72 import("//build_overrides/pigweed.gni") 73 74 import("$dir_pw_toolchain/arm_gcc/toolchains.gni") 75 import("$dir_pw_toolchain/generate_toolchain.gni") 76 77 my_target_scope = { 78 # Use Pigweed's Cortex M4 toolchain as a base. 79 _toolchain_base = pw_toolchain_arm_gcc.cortex_m4f_debug 80 81 # Forward everything except the defaults scope from that toolchain. 82 forward_variables_from(_toolchain_base, "*", [ "defaults" ]) 83 84 defaults = { 85 # Forward everything from the base toolchain's defaults. 86 forward_variables_from(_toolchain_base.defaults, "*") 87 88 # Extend with custom build arguments for the target. 89 pw_log_BACKEND = dir_pw_log_tokenized 90 } 91 } 92 93 # Create the actual GN toolchain from the scope. 94 generate_toolchain("my_target") { 95 forward_variables_from(my_target_scope, "*") 96 } 97 98Upstream targets 99================ 100The following is a list of targets used for upstream Pigweed development. 101 102.. toctree:: 103 :maxdepth: 1 104 :glob: 105 106 targets/*/target_docs 107