150 lines
6.3 KiB
ReStructuredText
150 lines
6.3 KiB
ReStructuredText
.. _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``.
|