docs/targets.rst

.. _docs-targets:

=======
Targets
=======
Pigweed is designed to be portable to many different hardware platforms.
Pigweed's GN build comes with an extensible target system that allows it to be
configured to build for any number of platforms, which all build simultaneously.

Defining a target
=================
Each Pigweed target built by a project is defined within the GN build as a
toolchain providing the target's build parameters.

In Pigweed, these target toolchains are defined as GN scopes, which are fed into
a ``generate_toolchain`` template to create the complete GN toolchain.

Hierarchical target structure
-----------------------------
The rationale for scope-based toolchains is to make Pigweed targets extensible.
Variables from a toolchain can be forwarded into new scopes and then extended
or overriden. This facilitates the sharing of common configuration options
between toolchains, and allows for hierarchical structures. Upstream Pigweed
makes use of this heavily; it defines basic compiler-only configurations, uses
these as a base for board-specific toolchains, then creates its final targets on
top of those.

.. blockdiag::

  blockdiag {
    default_fontsize = 14;
    orientation = portrait;

    arm_gcc  [label = "arm_gcc"];
    arm_gcc_cortex_m4  [label = "cortex_m4"];
    arm_gcc_cortex_m4f  [label = "cortex_m4f"];
    arm_gcc_cortex_m4f_debug  [label = "cortex_m4f_debug"];
    arm_gcc_cortex_m4f_size_optimized  [label = "cortex_m4f_size_optimized"];
    stm32f429i_disc1_debug  [label = "stm32f429i_disc1_debug"];
    arm_gcc -> arm_gcc_cortex_m4
    arm_gcc -> arm_gcc_cortex_m4f
    arm_gcc_cortex_m4f -> arm_gcc_cortex_m4f_debug
    arm_gcc_cortex_m4f -> arm_gcc_cortex_m4f_size_optimized
    arm_gcc_cortex_m4f_debug -> stm32f429i_disc1_debug
  }

Toolchain target variables
--------------------------
The core of a toolchain is defining the tools it uses. This is done by setting
the variables ``ar``, ``cc``, and ``cxx`` to the appropriate compilers. Pigweed
provides many commonly used compiler configurations in the ``pw_toolchain``
module.

The rest of the a Pigweed target's configuration is listed within a ``defaults``
scope in its toolchain. Every variable in this scope is an override of a GN
build argument defined in Pigweed. Some notable arguments include:

* ``default_configs``: A list of GN configs to apply to every ``pw_*`` GN
  template. This is typically used to set compiler flags, optimization levels,
  global #defines, etc.
* ``default_public_deps``: List of GN targets which are added as a dependency
  to all ``pw_*`` GN targets. This is used to add global module dependencies;
  for example, in upstream, ``pw_polyfill`` is added here to provide C++17
  features in C++11/C++14 code.
* Facade backends: Pigweed defines facades to provide a common interface for
  core system features such as logging without assuming an implementation.
  When building a Pigweed target, the implementations for each of these must be
  chosen. The ``*_BACKEND`` build args that Pigweed defines are used to set
  these.

There are many other build arguments that can be set, some of which are
module-specific. A full list can be seen by running ``gn args --list out``,
and further documentation can be found within their respective modules.

Example Pigweed target
======================
The code below demonstrates how a project might configure one of its Pigweed
targets.

.. code::

  # Prevent gn format from reordering this import.
  import("//build_overrides/pigweed.gni")

  import("$dir_pw_toolchain/arm_gcc/toolchains.gni")
  import("$dir_pw_toolchain/generate_toolchain.gni")

  my_target_scope = {
    # Use Pigweed's Cortex M4 toolchain as a base.
    _toolchain_base = pw_toolchain_arm_gcc.cortex_m4f_debug

    # Forward everything except the defaults scope from that toolchain.
    forward_variables_from(_toolchain_base, "*", [ "defaults" ])

    defaults = {
      # Forward everything from the base toolchain's defaults.
      forward_variables_from(_toolchain_base.defaults, "*")

      # Extend with custom build arguments for the target.
      pw_log_BACKEND = dir_pw_log_tokenized
    }
  }

  # Create the actual GN toolchain from the scope.
  generate_toolchain("my_target") {
    forward_variables_from(my_target_scope, "*")
  }

Upstream targets
================
The following is a list of targets used for upstream Pigweed development.

.. toctree::
  :maxdepth: 1
  :glob:

  targets/*/target_docs