Wyatt Hepler | f9fb90f | 2020-09-30 18:59:33 -0700 | [diff] [blame] | 1 | .. _module-pw_toolchain: |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 2 | |
| 3 | ------------ |
| 4 | pw_toolchain |
| 5 | ------------ |
Wyatt Hepler | f6f74f4 | 2021-04-13 19:26:20 -0700 | [diff] [blame] | 6 | GN toolchains function both as a set of tools for compilation and as a workspace |
| 7 | for evaluating build files. The same compilations and actions can be executed by |
| 8 | different toolchains. Each toolchain maintains its own set of build args, and |
| 9 | build steps from all toolchains can be executed in parallel. |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 10 | |
Wyatt Hepler | f6f74f4 | 2021-04-13 19:26:20 -0700 | [diff] [blame] | 11 | Toolchains |
| 12 | ========== |
| 13 | ``pw_toolchain`` provides GN toolchains that may be used to build Pigweed. The |
| 14 | following toolchains are defined: |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 15 | |
Armando Montanez | b175a42 | 2021-10-06 11:35:20 -0700 | [diff] [blame] | 16 | - pw_toolchain_arm_clang.cortex_m0plus_debug |
| 17 | - pw_toolchain_arm_clang.cortex_m0plus_speed_optimized |
| 18 | - pw_toolchain_arm_clang.cortex_m0plus_size_optimized |
| 19 | - pw_toolchain_arm_clang.cortex_m3_debug |
| 20 | - pw_toolchain_arm_clang.cortex_m3_speed_optimized |
| 21 | - pw_toolchain_arm_clang.cortex_m3_size_optimized |
| 22 | - pw_toolchain_arm_clang.cortex_m4_debug |
| 23 | - pw_toolchain_arm_clang.cortex_m4_speed_optimized |
| 24 | - pw_toolchain_arm_clang.cortex_m4_size_optimized |
| 25 | - pw_toolchain_arm_clang.cortex_m4f_debug |
| 26 | - pw_toolchain_arm_clang.cortex_m4f_speed_optimized |
| 27 | - pw_toolchain_arm_clang.cortex_m4f_size_optimized |
Henri Chataing | 19e41f0 | 2021-08-10 11:04:30 +0200 | [diff] [blame] | 28 | - pw_toolchain_arm_gcc.cortex_m0plus_debug |
| 29 | - pw_toolchain_arm_gcc.cortex_m0plus_speed_optimized |
| 30 | - pw_toolchain_arm_gcc.cortex_m0plus_size_optimized |
| 31 | - pw_toolchain_arm_gcc.cortex_m3_debug |
| 32 | - pw_toolchain_arm_gcc.cortex_m3_speed_optimized |
| 33 | - pw_toolchain_arm_gcc.cortex_m3_size_optimized |
| 34 | - pw_toolchain_arm_gcc.cortex_m4_debug |
| 35 | - pw_toolchain_arm_gcc.cortex_m4_speed_optimized |
| 36 | - pw_toolchain_arm_gcc.cortex_m4_size_optimized |
| 37 | - pw_toolchain_arm_gcc.cortex_m4f_debug |
| 38 | - pw_toolchain_arm_gcc.cortex_m4f_speed_optimized |
| 39 | - pw_toolchain_arm_gcc.cortex_m4f_size_optimized |
| 40 | - pw_toolchain_arm_gcc.cortex_m7_debug |
| 41 | - pw_toolchain_arm_gcc.cortex_m7_speed_optimized |
| 42 | - pw_toolchain_arm_gcc.cortex_m7_size_optimized |
| 43 | - pw_toolchain_arm_gcc.cortex_m7f_debug |
| 44 | - pw_toolchain_arm_gcc.cortex_m7f_speed_optimized |
| 45 | - pw_toolchain_arm_gcc.cortex_m7f_size_optimized |
| 46 | - pw_toolchain_arm_gcc.cortex_m33_debug |
| 47 | - pw_toolchain_arm_gcc.cortex_m33_speed_optimized |
| 48 | - pw_toolchain_arm_gcc.cortex_m33_size_optimized |
| 49 | - pw_toolchain_arm_gcc.cortex_m33f_debug |
| 50 | - pw_toolchain_arm_gcc.cortex_m33f_speed_optimized |
| 51 | - pw_toolchain_arm_gcc.cortex_m33f_size_optimized |
| 52 | - pw_toolchain_host_clang.debug |
| 53 | - pw_toolchain_host_clang.speed_optimized |
| 54 | - pw_toolchain_host_clang.size_optimized |
| 55 | - pw_toolchain_host_clang.fuzz |
| 56 | - pw_toolchain_host_gcc.debug |
| 57 | - pw_toolchain_host_gcc.speed_optimized |
| 58 | - pw_toolchain_host_gcc.size_optimized |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 59 | |
Henri Chataing | 19e41f0 | 2021-08-10 11:04:30 +0200 | [diff] [blame] | 60 | .. note:: |
Armando Montanez | 0054a9b | 2020-03-13 13:06:24 -0700 | [diff] [blame] | 61 | The documentation for this module is currently incomplete. |
Wyatt Hepler | f6f74f4 | 2021-04-13 19:26:20 -0700 | [diff] [blame] | 62 | |
| 63 | Non-C/C++ toolchains |
| 64 | ==================== |
| 65 | ``pw_toolchain/non_c_toolchain.gni`` provides the ``pw_non_c_toolchain`` |
| 66 | template. This template creates toolchains that cannot compile C/C++ source |
| 67 | code. These toolchains may only be used to execute GN actions or declare groups |
| 68 | of targets in other toolchains. Attempting to compile C/C++ code with either of |
| 69 | these toolchains results in errors. |
| 70 | |
| 71 | Non-C/C++ toolchains can be used to consolidate actions that should only occur |
| 72 | once in a multi-toolchain build. Build targets from all toolchains can refer to |
| 73 | these actions in a non-C/C++ toolchain so they only execute once instead of once |
| 74 | per toolchain. |
| 75 | |
| 76 | For example, Pigweed runs protobuf compilation and Python package actions like |
| 77 | installation and Pylint in toolchains created with ``pw_non_c_toolchain``. This |
| 78 | allows all toolchains to cleanly share the same protobuf and Python declarations |
| 79 | without any duplicated work. |
Armando Montanez | 9a53d6c | 2021-04-29 15:40:11 -0700 | [diff] [blame] | 80 | |
| 81 | Testing other compiler versions |
| 82 | =============================== |
| 83 | The clang-based toolchain provided by Pigweed can be substituted with another |
| 84 | version by modifying the ``pw_toolchain_CLANG_PREFIX`` GN build argument to |
| 85 | point to the directory that contains the desired clang, clang++, and llvm-ar |
| 86 | binaries. This should only be used for debugging purposes. Pigweed does not |
| 87 | officially support any compilers other than those provided by Pigweed. |
Henri Chataing | 19e41f0 | 2021-08-10 11:04:30 +0200 | [diff] [blame] | 88 | |
| 89 | Running static analysis checks |
| 90 | ============================== |
| 91 | ``clang-tidy`` can be run as a compiler replacement, to analyze all sources |
| 92 | built for a target. ``pw_toolchain/static_analysis_toolchain.gni`` provides |
| 93 | the ``pw_static_analysis_toolchain`` template. This template creates toolchains |
| 94 | that execute ``clang-tidy`` for C/C++ sources, and mock implementations of |
| 95 | the ``link``, ``alink`` and ``solink`` tools. |
| 96 | |
| 97 | Additionally, ``generate_toolchain`` implements a boolean flag |
| 98 | ``static_analysis`` (default ``false``) which generates the derived |
| 99 | toolchain ``${target_name}.static_analysis`` using |
| 100 | ``pw_generate_static_analysis_toolchain`` and the toolchain options. |
| 101 | |
Wyatt Hepler | 5e9f7a6 | 2021-10-08 21:04:10 -0700 | [diff] [blame] | 102 | Excluding files from checks |
| 103 | --------------------------- |
Ted Pudlik | 73d948c | 2021-10-26 19:44:17 +0000 | [diff] [blame] | 104 | The build argument ``pw_toolchain_STATIC_ANALYSIS_SKIP_SOURCES_RES`` is used |
| 105 | used to exclude source files from the analysis. The list must contain regular |
| 106 | expressions matching individual files, rather than directories. For example, |
| 107 | provide ``"the_path/.*"`` to exclude all files in all directories under |
Wyatt Hepler | 5e9f7a6 | 2021-10-08 21:04:10 -0700 | [diff] [blame] | 108 | ``the_path``. |
Henri Chataing | 19e41f0 | 2021-08-10 11:04:30 +0200 | [diff] [blame] | 109 | |
Wyatt Hepler | 5e9f7a6 | 2021-10-08 21:04:10 -0700 | [diff] [blame] | 110 | The build argument ``pw_toolchain_STATIC_ANALYSIS_SKIP_INCLUDE_PATHS`` is used |
| 111 | used to exclude header files from the analysis. This argument must be a list of |
Scott James Remnant | 4d28e22 | 2022-02-16 12:01:25 -0800 | [diff] [blame] | 112 | POSIX-style path suffixes for include paths, or regular expressions. For |
| 113 | example, passing ``the_path/include`` excludes all header files that are |
| 114 | accessed from include paths ending in ``the_path/include``, while passing |
| 115 | ``.*/third_party/.*`` excludes all third-party header files. |
Wyatt Hepler | 5e9f7a6 | 2021-10-08 21:04:10 -0700 | [diff] [blame] | 116 | |
| 117 | Provided toolchains |
| 118 | ------------------- |
Henri Chataing | 19e41f0 | 2021-08-10 11:04:30 +0200 | [diff] [blame] | 119 | ``pw_toolchain`` provides static analysis GN toolchains that may be used to |
| 120 | test host targets: |
| 121 | |
| 122 | - pw_toolchain_host_clang.debug.static_analysis |
| 123 | - pw_toolchain_host_clang.speed_optimized.static_analysis |
| 124 | - pw_toolchain_host_clang.size_optimized.static_analysis |
| 125 | - pw_toolchain_host_clang.fuzz.static_analysis |
| 126 | (if pw_toolchain_OSS_FUZZ_ENABLED is false) |
Henri Chataing | dd46587 | 2021-09-01 15:41:21 +0000 | [diff] [blame] | 127 | - pw_toolchain_arm_clang.debug.static_analysis |
| 128 | - pw_toolchain_arm_clang.speed_optimized.static_analysis |
| 129 | - pw_toolchain_arm_clang.size_optimized.static_analysis |
Henri Chataing | 19e41f0 | 2021-08-10 11:04:30 +0200 | [diff] [blame] | 130 | |
| 131 | For example, to run ``clang-tidy`` on all source dependencies of the |
| 132 | ``default`` target: |
| 133 | |
| 134 | .. code-block:: |
| 135 | |
| 136 | generate_toolchain("my_toolchain") { |
| 137 | .. |
| 138 | static_analysis = true |
| 139 | } |
| 140 | |
| 141 | group("static_analysis") { |
| 142 | deps = [ ":default(my_toolchain.static_analysis)" ] |
| 143 | } |
Henri Chataing | dd46587 | 2021-09-01 15:41:21 +0000 | [diff] [blame] | 144 | |
| 145 | .. warning:: |
| 146 | The status of the static analysis checks might change when |
| 147 | any relevant .clang-tidy file is updated. You should |
| 148 | clean the output directory before invoking |
| 149 | ``clang-tidy``. |