From 649c93080f1e6db1f5c8c8436a797038a5c12c87 Mon Sep 17 00:00:00 2001 From: Antonin Godard Date: Tue, 22 Jul 2025 15:33:37 +0200 Subject: ref-manual: document new toolchain classes and variables Document the new classes under classes/toolchain as well as PREFERRED_TOOLCHAIN* and TOOLCHAIN variables, which allow selecting the toolchain. For now there's "gcc" and "clang" as available toolchain. (From yocto-docs rev: 69a9568f8bd7ed57efddab507a4294ad3408f4dd) Signed-off-by: Antonin Godard Signed-off-by: Richard Purdie --- documentation/ref-manual/classes.rst | 80 ++++++++++++++++++++++++++++++++++ documentation/ref-manual/variables.rst | 78 +++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) (limited to 'documentation/ref-manual') diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst index 4705ca3f4d..ff41c84a73 100644 --- a/documentation/ref-manual/classes.rst +++ b/documentation/ref-manual/classes.rst @@ -3443,6 +3443,86 @@ This class is not intended to be used directly. The :ref:`ref-classes-toolchain-scripts` class provides the scripts used for setting up the environment for installed SDKs. +.. _ref-classes-toolchain-clang: + +``toolchain/clang`` +=================== + +The :ref:`ref-classes-toolchain-clang` class defines commands for building +recipes with Clang/LLVM compiler and utilities. + +This class is not meant to be inherited directly. Instead, you should either: + +- set the :term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` + or :term:`PREFERRED_TOOLCHAIN_SDK` variables to "clang" from a + :term:`Configuration File`. This will make the :ref:`ref-classes-base` class + use the :ref:`ref-classes-toolchain-clang` accordingly. All recipes will + be built with the Clang/LLVM toolchain, exception be made for recipes that + override the value of :term:`TOOLCHAIN` or :term:`TOOLCHAIN_NATIVE` to + another value. + +- set :term:`TOOLCHAIN` or :term:`TOOLCHAIN_NATIVE` to "clang" from a recipe + when the recipe needs to override the default toolchain set by + :term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or + :term:`PREFERRED_TOOLCHAIN_SDK`. + +.. _ref-classes-toolchain-clang-native: + +``toolchain/clang-native`` +========================== + +The :ref:`ref-classes-toolchain-clang-native` class defines commands for +building :ref:`ref-classes-native` recipes with Clang/LLVM compiler and +utilities independently of the build context. + +The :ref:`ref-classes-toolchain-gcc-native` class defines :term:`BUILD_CC`, +:term:`BUILD_CXX` and other such variables which are rarely used in recipes. +Exception be made for target recipes that need to use the compiler from the +build host at some point during the build. + +This class should not be inherited directly. It is inherited by the +:ref:`ref-classes-base` class if :term:`TOOLCHAIN_NATIVE` is set to "clang". + +.. _ref-classes-toolchain-gcc: + +``toolchain/gcc`` +================= + +The :ref:`ref-classes-toolchain-gcc` class defines commands for building +recipes with GCC/Binutils compiler and utilities. + +This class is not meant to be inherited directly. Instead, you should either: + +- set the :term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` + or :term:`PREFERRED_TOOLCHAIN_SDK` variables to "gcc" from a + :term:`Configuration File`. This will make the :ref:`ref-classes-base` class + use the :ref:`ref-classes-toolchain-gcc` accordingly. All recipes will + be built with the GCC/Binutils toolchain, exception be made for recipes that + override the value of :term:`TOOLCHAIN` or :term:`TOOLCHAIN_NATIVE` to + another value. + +- set :term:`TOOLCHAIN` or :term:`TOOLCHAIN_NATIVE` to "gcc" from a recipe + when the recipe needs to override the default toolchain set by + :term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or + :term:`PREFERRED_TOOLCHAIN_SDK`. + +.. _ref-classes-toolchain-gcc-native: + +``toolchain/gcc-native`` +======================== + +The :ref:`ref-classes-toolchain-gcc-native` class defines commands for building +:ref:`ref-classes-native` recipes with GCC/Binutils compiler and utilities +independently of the build context. + +The :ref:`ref-classes-toolchain-gcc-native` class defines :term:`BUILD_CC`, +:term:`BUILD_CXX` and other such variables which are rarely used in recipes. +Exception be made for target recipes that need to use the compiler from the build +host at some point during the build. + +This class should not be inherited directly. It is inherited by the +:ref:`ref-classes-base` class if :term:`TOOLCHAIN_NATIVE` is set to "gcc". + .. _ref-classes-typecheck: ``typecheck`` diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst index 7e4f7e58ad..038e5541ef 100644 --- a/documentation/ref-manual/variables.rst +++ b/documentation/ref-manual/variables.rst @@ -7325,6 +7325,57 @@ system and gives an overview of their function and contents. ":ref:`dev-manual/new-recipe:using virtual providers`" section in the Yocto Project Development Tasks Manual. + :term:`PREFERRED_TOOLCHAIN` + The :term:`PREFERRED_TOOLCHAIN` variable selects the toolchain to use for + compiling recipes. This variable is not meant to be overridden globally. + Instead, the values of :term:`PREFERRED_TOOLCHAIN_TARGET`, + :term:`PREFERRED_TOOLCHAIN_NATIVE` and :term:`PREFERRED_TOOLCHAIN_SDK` + should be overridden. + + :term:`PREFERRED_TOOLCHAIN_NATIVE` + This variable controls the toolchain used for compiling + :ref:`ref-classes-native` recipes. + + This variable should be set globally from a :term:`configuration file`. + + See :term:`PREFERRED_TOOLCHAIN_TARGET` for more details on the possible + values for this variable. + + A recipe that does not support the toolchain specified by + :term:`PREFERRED_TOOLCHAIN_NATIVE` can override it locally with + :term:`TOOLCHAIN_NATIVE`. + + :term:`PREFERRED_TOOLCHAIN_SDK` + This variable controls the toolchain used for compiling + :ref:`ref-classes-nativesdk` recipes. + + This variable should be set globally from a :term:`configuration file`. + + See :term:`PREFERRED_TOOLCHAIN_TARGET` for more details on the possible + values for this variable. + + :term:`PREFERRED_TOOLCHAIN_TARGET` + This variable controls the toolchain used for compiling recipes in the + architecture of the target :term:`MACHINE`. + + There are two possible values for this variable at the moment: + + - :ref:`gcc ` (default): the GCC/Binutils toolchain. + - :ref:`clang `: the Clang/LLVM toolchain. + + :term:`PREFERRED_TOOLCHAIN_TARGET` will make the :ref:`ref-classes-base` + class inherit one of the toolchain classes defined in + :oe_git:`meta/classes/toolchain + `. As a consequence, this + variable should be set globally from a :term:`configuration file`. + + These classes define commands used for cross-compiling such as :term:`CC`, + :term:`CXX`, :term:`LD` and so on. + + A recipe that does not support the toolchain specified by + :term:`PREFERRED_TOOLCHAIN_TARGET` can override it locally with + :term:`TOOLCHAIN`. + :term:`PREFERRED_VERSION` If there are multiple versions of a recipe available, this variable determines which version should be given preference. You must always @@ -10125,6 +10176,21 @@ system and gives an overview of their function and contents. implementations, NFS does not meet this minimum requirement. Consequently, :term:`TMPDIR` cannot be on NFS. + :term:`TOOLCHAIN` + The :term:`TOOLCHAIN` variable can be used to override the toolchain used + by a recipe. + + The default value for this variable is the value of + :term:`PREFERRED_TOOLCHAIN`. See the description of + :term:`PREFERRED_TOOLCHAIN` to know the list of possible values for + :term:`TOOLCHAIN`. + + It is possible to override the value of this variable from a recipe if + this recipe is known to support only a specific toolchain. For example, + the :oe_git:`Pseudo ` + recipe overrides this variable to "gcc", because Pseudo uses GCC compiler + built-ins options that the Clang/LLVM compiler does not provide. + :term:`TOOLCHAIN_HOST_TASK` This variable lists packages the OpenEmbedded build system uses when building an SDK, which contains a cross-development environment. The @@ -10180,6 +10246,18 @@ system and gives an overview of their function and contents. :term:`SDK_VERSION` variables for additional information. + :term:`TOOLCHAIN_NATIVE` + The :term:`TOOLCHAIN_NATIVE` variable can be used to override the + toolchain used by a :ref:`ref-classes-native` recipe. + + The default value for this variable is the value of + :term:`PREFERRED_TOOLCHAIN` (in :ref:`ref-classes-native` contexts). See + the description of :term:`PREFERRED_TOOLCHAIN` to know the list of + possible values for :term:`TOOLCHAIN_NATIVE`. + + It is possible to override the value of this variable from a recipe if + this recipe is known to support only a specific toolchain. + :term:`TOOLCHAIN_TARGET_TASK` This variable lists packages the OpenEmbedded build system uses when it creates the target part of an SDK (i.e. the part built for the -- cgit v1.2.3-54-g00ecf