.. _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_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.

The build argument ``pw_toolchain_STATIC_ANALYSIS_SOURCE_FILTER`` may be
used to select and/or exclude source files to output diagnostics from.

``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)

 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)" ]
  }