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 | |
Wyatt Hepler | 1d22124 | 2021-09-07 15:42:21 -0700 | [diff] [blame] | 28 | .. mermaid:: |
Wyatt Hepler | 79ea2cf | 2021-09-07 13:24:26 -0700 | [diff] [blame] | 29 | |
Wyatt Hepler | 1d22124 | 2021-09-07 15:42:21 -0700 | [diff] [blame] | 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 |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 36 | |
| 37 | Toolchain target variables |
| 38 | -------------------------- |
| 39 | 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] | 40 | the variables ``ar``, ``cc``, and ``cxx`` to the appropriate compilers. Pigweed |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 41 | provides many commonly used compiler configurations in the ``pw_toolchain`` |
| 42 | module. |
| 43 | |
| 44 | The rest of the a Pigweed target's configuration is listed within a ``defaults`` |
| 45 | scope in its toolchain. Every variable in this scope is an override of a GN |
| 46 | build 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 |
Wyatt Hepler | 0132da5 | 2021-10-11 16:20:11 -0700 | [diff] [blame] | 54 | features in C++14 code. |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 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 | |
| 61 | There are many other build arguments that can be set, some of which are |
| 62 | module-specific. A full list can be seen by running ``gn args --list out``, |
| 63 | and further documentation can be found within their respective modules. |
| 64 | |
| 65 | Example Pigweed target |
| 66 | ====================== |
| 67 | The code below demonstrates how a project might configure one of its Pigweed |
| 68 | targets. |
| 69 | |
Wyatt Hepler | 79ea2cf | 2021-09-07 13:24:26 -0700 | [diff] [blame] | 70 | .. code-block:: |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 71 | |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 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 |
Alexei Frolov | 199045a | 2020-08-28 13:02:30 -0700 | [diff] [blame] | 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 | |
| 98 | Upstream targets |
| 99 | ================ |
| 100 | The following is a list of targets used for upstream Pigweed development. |
Armando Montanez | 0874558 | 2019-12-12 10:51:50 -0800 | [diff] [blame] | 101 | |
| 102 | .. toctree:: |
| 103 | :maxdepth: 1 |
| 104 | :glob: |
| 105 | |
| 106 | targets/*/target_docs |