@@ -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``
@@ -7331,6 +7331,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 <ref-classes-toolchain-gcc>` (default): the GCC/Binutils toolchain.
+ - :ref:`clang <ref-classes-toolchain-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
+ </openembedded-core/tree/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
@@ -10131,6 +10182,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 </openembedded-core/tree/meta/recipes-devtools/pseudo/pseudo_git.bb>`
+ 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
@@ -10186,6 +10252,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
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. Signed-off-by: Antonin Godard <antonin.godard@bootlin.com> --- Changes in v2: - Apply corrections/suggestions from Quentin Schulz (thanks!) - Link to v1: https://lore.kernel.org/r/20250718-new-toolchain-variables-v1-1-28c6b7054f73@bootlin.com --- documentation/ref-manual/classes.rst | 80 ++++++++++++++++++++++++++++++++++ documentation/ref-manual/variables.rst | 78 +++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+) --- base-commit: f9f1c87424d307d2df60024bc448bd6778605cf8 change-id: 20250718-new-toolchain-variables-b92155294976 Best regards, -- Antonin Godard <antonin.godard@bootlin.com>