Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _docs-targets: |
Armando Montanez | bcc194b | 2020-03-10 10:23:18 -0700 | [diff] [blame] | 2 | |
Armando Montanez | 0874558 | 2019-12-12 10:51:50 -0800 | [diff] [blame] | 3 | ======= |
| 4 | Targets |
| 5 | ======= |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 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 |
Ali Zhang | f22f1f1 | 2021-04-02 18:59:28 -0700 | [diff] [blame] | 50 | the variables ``ar``, ``cc``, and ``cxx`` to the appropriate compilers. Pigweed |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 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 |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 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. |
Armando Montanez | 0874558 | 2019-12-12 10:51:50 -0800 | [diff] [blame] | 112 | |
| 113 | .. toctree:: |
| 114 | :maxdepth: 1 |
| 115 | :glob: |
| 116 | |
| 117 | targets/*/target_docs |