| .. _module-pw_toolchain: |
| |
| ------------ |
| pw_toolchain |
| ------------ |
| GN toolchains function both as a set of tools for compilation and as a workspace |
| for evaluating build files. The same compilations and actions can be executed by |
| different toolchains. Each toolchain maintains its own set of build args, and |
| build steps from all toolchains can be executed in parallel. |
| |
| Toolchains |
| ========== |
| ``pw_toolchain`` provides GN toolchains that may be used to build Pigweed. The |
| following toolchains are defined: |
| |
| - pw_toolchain_arm_clang.cortex_m0plus_debug |
| - pw_toolchain_arm_clang.cortex_m0plus_speed_optimized |
| - pw_toolchain_arm_clang.cortex_m0plus_size_optimized |
| - pw_toolchain_arm_clang.cortex_m3_debug |
| - pw_toolchain_arm_clang.cortex_m3_speed_optimized |
| - pw_toolchain_arm_clang.cortex_m3_size_optimized |
| - pw_toolchain_arm_clang.cortex_m4_debug |
| - pw_toolchain_arm_clang.cortex_m4_speed_optimized |
| - pw_toolchain_arm_clang.cortex_m4_size_optimized |
| - pw_toolchain_arm_clang.cortex_m4f_debug |
| - pw_toolchain_arm_clang.cortex_m4f_speed_optimized |
| - pw_toolchain_arm_clang.cortex_m4f_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m0plus_debug |
| - pw_toolchain_arm_gcc.cortex_m0plus_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m0plus_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m3_debug |
| - pw_toolchain_arm_gcc.cortex_m3_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m3_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m4_debug |
| - pw_toolchain_arm_gcc.cortex_m4_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m4_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m4f_debug |
| - pw_toolchain_arm_gcc.cortex_m4f_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m4f_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m7_debug |
| - pw_toolchain_arm_gcc.cortex_m7_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m7_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m7f_debug |
| - pw_toolchain_arm_gcc.cortex_m7f_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m7f_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m33_debug |
| - pw_toolchain_arm_gcc.cortex_m33_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m33_size_optimized |
| - pw_toolchain_arm_gcc.cortex_m33f_debug |
| - pw_toolchain_arm_gcc.cortex_m33f_speed_optimized |
| - pw_toolchain_arm_gcc.cortex_m33f_size_optimized |
| - pw_toolchain_host_clang.debug |
| - pw_toolchain_host_clang.speed_optimized |
| - pw_toolchain_host_clang.size_optimized |
| - pw_toolchain_host_clang.fuzz |
| - pw_toolchain_host_gcc.debug |
| - pw_toolchain_host_gcc.speed_optimized |
| - pw_toolchain_host_gcc.size_optimized |
| |
| .. note:: |
| The documentation for this module is currently incomplete. |
| |
| Non-C/C++ toolchains |
| ==================== |
| ``pw_toolchain/non_c_toolchain.gni`` provides the ``pw_non_c_toolchain`` |
| template. This template creates toolchains that cannot compile C/C++ source |
| code. These toolchains may only be used to execute GN actions or declare groups |
| of targets in other toolchains. Attempting to compile C/C++ code with either of |
| these toolchains results in errors. |
| |
| Non-C/C++ toolchains can be used to consolidate actions that should only occur |
| once in a multi-toolchain build. Build targets from all toolchains can refer to |
| these actions in a non-C/C++ toolchain so they only execute once instead of once |
| per toolchain. |
| |
| For example, Pigweed runs protobuf compilation and Python package actions like |
| installation and Pylint in toolchains created with ``pw_non_c_toolchain``. This |
| allows all toolchains to cleanly share the same protobuf and Python declarations |
| without any duplicated work. |
| |
| Testing other compiler versions |
| =============================== |
| The clang-based toolchain provided by Pigweed can be substituted with another |
| version by modifying the ``pw_toolchain_CLANG_PREFIX`` GN build argument to |
| point to the directory that contains the desired clang, clang++, and llvm-ar |
| binaries. This should only be used for debugging purposes. Pigweed does not |
| officially support any compilers other than those provided by Pigweed. |
| |
| Running static analysis checks |
| ============================== |
| ``clang-tidy`` can be run as a compiler replacement, to analyze all sources |
| built for a target. ``pw_toolchain/static_analysis_toolchain.gni`` provides |
| the ``pw_static_analysis_toolchain`` template. This template creates toolchains |
| that execute ``clang-tidy`` for C/C++ sources, and mock implementations of |
| the ``link``, ``alink`` and ``solink`` tools. |
| |
| Additionally, ``generate_toolchain`` implements a boolean flag |
| ``static_analysis`` (default ``false``) which generates the derived |
| toolchain ``${target_name}.static_analysis`` using |
| ``pw_generate_static_analysis_toolchain`` and the toolchain options. |
| |
| Excluding files from checks |
| --------------------------- |
| The build argument ``pw_toolchain_STATIC_ANALYSIS_SKIP_SOURCES_RES`` is used |
| used to exclude source files from the analysis. The list must contain regular |
| expressions matching individual files, rather than directories. For example, |
| provide ``"the_path/.*"`` to exclude all files in all directories under |
| ``the_path``. |
| |
| The build argument ``pw_toolchain_STATIC_ANALYSIS_SKIP_INCLUDE_PATHS`` is used |
| used to exclude header files from the analysis. This argument must be a list of |
| POSIX-style path suffixes for include paths, or regular expressions. For |
| example, passing ``the_path/include`` excludes all header files that are |
| accessed from include paths ending in ``the_path/include``, while passing |
| ``.*/third_party/.*`` excludes all third-party header files. |
| |
| Provided toolchains |
| ------------------- |
| ``pw_toolchain`` provides static analysis GN toolchains that may be used to |
| test host targets: |
| |
| - pw_toolchain_host_clang.debug.static_analysis |
| - pw_toolchain_host_clang.speed_optimized.static_analysis |
| - pw_toolchain_host_clang.size_optimized.static_analysis |
| - pw_toolchain_host_clang.fuzz.static_analysis |
| (if pw_toolchain_OSS_FUZZ_ENABLED is false) |
| - pw_toolchain_arm_clang.debug.static_analysis |
| - pw_toolchain_arm_clang.speed_optimized.static_analysis |
| - pw_toolchain_arm_clang.size_optimized.static_analysis |
| |
| For example, to run ``clang-tidy`` on all source dependencies of the |
| ``default`` target: |
| |
| .. code-block:: |
| |
| generate_toolchain("my_toolchain") { |
| .. |
| static_analysis = true |
| } |
| |
| group("static_analysis") { |
| deps = [ ":default(my_toolchain.static_analysis)" ] |
| } |
| |
| .. warning:: |
| The status of the static analysis checks might change when |
| any relevant .clang-tidy file is updated. You should |
| clean the output directory before invoking |
| ``clang-tidy``. |