1.. _module-pw_toolchain: 2 3------------ 4pw_toolchain 5------------ 6GN toolchains function both as a set of tools for compilation and as a workspace 7for evaluating build files. The same compilations and actions can be executed by 8different toolchains. Each toolchain maintains its own set of build args, and 9build steps from all toolchains can be executed in parallel. 10 11Toolchains 12========== 13``pw_toolchain`` provides GN toolchains that may be used to build Pigweed. The 14following toolchains are defined: 15 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 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 59 60 .. note:: 61 The documentation for this module is currently incomplete. 62 63Non-C/C++ toolchains 64==================== 65``pw_toolchain/non_c_toolchain.gni`` provides the ``pw_non_c_toolchain`` 66template. This template creates toolchains that cannot compile C/C++ source 67code. These toolchains may only be used to execute GN actions or declare groups 68of targets in other toolchains. Attempting to compile C/C++ code with either of 69these toolchains results in errors. 70 71Non-C/C++ toolchains can be used to consolidate actions that should only occur 72once in a multi-toolchain build. Build targets from all toolchains can refer to 73these actions in a non-C/C++ toolchain so they only execute once instead of once 74per toolchain. 75 76For example, Pigweed runs protobuf compilation and Python package actions like 77installation and Pylint in toolchains created with ``pw_non_c_toolchain``. This 78allows all toolchains to cleanly share the same protobuf and Python declarations 79without any duplicated work. 80 81Testing other compiler versions 82=============================== 83The clang-based toolchain provided by Pigweed can be substituted with another 84version by modifying the ``pw_toolchain_CLANG_PREFIX`` GN build argument to 85point to the directory that contains the desired clang, clang++, and llvm-ar 86binaries. This should only be used for debugging purposes. Pigweed does not 87officially support any compilers other than those provided by Pigweed. 88 89Running static analysis checks 90============================== 91``clang-tidy`` can be run as a compiler replacement, to analyze all sources 92built for a target. ``pw_toolchain/static_analysis_toolchain.gni`` provides 93the ``pw_static_analysis_toolchain`` template. This template creates toolchains 94that execute ``clang-tidy`` for C/C++ sources, and mock implementations of 95the ``link``, ``alink`` and ``solink`` tools. 96 97Additionally, ``generate_toolchain`` implements a boolean flag 98``static_analysis`` (default ``false``) which generates the derived 99toolchain ``${target_name}.static_analysis`` using 100``pw_generate_static_analysis_toolchain`` and the toolchain options. 101 102Excluding files from checks 103--------------------------- 104The build argument ``pw_toolchain_STATIC_ANALYSIS_SKIP_SOURCES_RES`` is used 105used to exclude source files from the analysis. The list must contain regular 106expressions matching individual files, rather than directories. For example, 107provide ``"the_path/.*"`` to exclude all files in all directories under 108``the_path``. 109 110The build argument ``pw_toolchain_STATIC_ANALYSIS_SKIP_INCLUDE_PATHS`` is used 111used to exclude header files from the analysis. This argument must be a list of 112POSIX-style path suffixes for include paths, or regular expressions. For 113example, passing ``the_path/include`` excludes all header files that are 114accessed from include paths ending in ``the_path/include``, while passing 115``.*/third_party/.*`` excludes all third-party header files. 116 117Provided toolchains 118------------------- 119``pw_toolchain`` provides static analysis GN toolchains that may be used to 120test 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) 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 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 } 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``. 150