third_party/pigweed/repo/docs/targets.rst

   1 .. _docs-targets:
   2
   3 =======
   4 Targets
   5 =======
   6 Pigweed is designed to be portable to many different hardware platforms.
   7 Pigweed's GN build comes with an extensible target system that allows it to be
   8 configured to build for any number of platforms, which all build simultaneously.
   9
  10 Defining a target
  11 =================
  12 Each Pigweed target built by a project is defined within the GN build as a
  13 toolchain providing the target's build parameters.
  14
  15 In Pigweed, these target toolchains are defined as GN scopes, which are fed into
  16 a ``generate_toolchain`` template to create the complete GN toolchain.
  17
  18 Hierarchical target structure
  19 -----------------------------
  20 The rationale for scope-based toolchains is to make Pigweed targets extensible.
  21 Variables from a toolchain can be forwarded into new scopes and then extended
  22 or overriden. This facilitates the sharing of common configuration options
  23 between toolchains, and allows for hierarchical structures. Upstream Pigweed
  24 makes use of this heavily; it defines basic compiler-only configurations, uses
  25 these as a base for board-specific toolchains, then creates its final targets on
  26 top 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
  47 Toolchain target variables
  48 --------------------------
  49 The core of a toolchain is defining the tools it uses. This is done by setting
  50 the variables ``ar``, ``cc``, and ``cxx`` to the appropirate compilers. Pigweed
  51 provides many commonly used compiler configurations in the ``pw_toolchain``
  52 module.
  53
  54 The rest of the a Pigweed target's configuration is listed within a ``defaults``
  55 scope in its toolchain. Every variable in this scope is an override of a GN
  56 build 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
  71 There are many other build arguments that can be set, some of which are
  72 module-specific. A full list can be seen by running ``gn args --list out``,
  73 and further documentation can be found within their respective modules.
  74
  75 Example Pigweed target
  76 ======================
  77 The code below demonstrates how a project might configure one of its Pigweed
  78 targets.
  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
 109 Upstream targets
 110 ================
 111 The following is a list of targets used for upstream Pigweed development.
 112
 113 .. toctree::
 114   :maxdepth: 1
 115   :glob:
 116
 117   targets/*/target_docs