1.. _docs-targets: 2 3================ 4Hardware targets 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 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* Facade backends: Pigweed defines facades to provide a common interface for 54 core system features such as logging without assuming an implementation. 55 When building a Pigweed target, the implementations for each of these must be 56 chosen. The ``*_BACKEND`` build args that Pigweed defines are used to set 57 these. 58 59There are many other build arguments that can be set, some of which are 60module-specific. A full list can be seen by running ``gn args --list out``, 61and further documentation can be found within their respective modules. 62 63Example Pigweed target 64====================== 65The code below demonstrates how a project might configure one of its Pigweed 66targets. 67 68.. code-block:: 69 70 import("//build_overrides/pigweed.gni") 71 72 import("$dir_pw_toolchain/arm_gcc/toolchains.gni") 73 import("$dir_pw_toolchain/generate_toolchain.gni") 74 75 my_target_scope = { 76 # Use Pigweed's Cortex M4 toolchain as a base. 77 _toolchain_base = pw_toolchain_arm_gcc.cortex_m4f_debug 78 79 # Forward everything except the defaults scope from that toolchain. 80 forward_variables_from(_toolchain_base, "*", [ "defaults" ]) 81 82 defaults = { 83 # Forward everything from the base toolchain's defaults. 84 forward_variables_from(_toolchain_base.defaults, "*") 85 86 # Extend with custom build arguments for the target. 87 pw_log_BACKEND = dir_pw_log_tokenized 88 } 89 } 90 91 # Create the actual GN toolchain from the scope. 92 generate_toolchain("my_target") { 93 forward_variables_from(my_target_scope, "*") 94 } 95 96Upstream targets 97================ 98The following is a list of targets used for upstream Pigweed development. 99 100.. toctree:: 101 :maxdepth: 1 102 :glob: 103 104 targets/*/target_docs 105 106Work-in-progress targets 107------------------------ 108You can see a list of hardware targets that are under development but not 109yet landed `here <https://issues.pigweed.dev/issues/300646347/dependencies>`_. 110