[PATCH] ref-manual: document new toolchain classes and variables

[PATCH] ref-manual: document new toolchain classes and variables

[Antonin Godard]

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>
---
 documentation/ref-manual/classes.rst   | 43 ++++++++++++++++++++++++
 documentation/ref-manual/variables.rst | 60 ++++++++++++++++++++++++++++++++++
 2 files changed, 103 insertions(+)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index 4705ca3f4..14f14b742 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -3443,6 +3443,49 @@ 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 and LLVM compiler and utilities. This class is not meant to
+be used directly in recipes. Instead, you should specific the
+:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
+:term:`PREFERRED_TOOLCHAIN_SDK` variables to "clang". This will make the
+:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-clang`
+accordingly.
+
+.. _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 used directly in recipes. Instead, you should specific the
+:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
+:term:`PREFERRED_TOOLCHAIN_SDK` variables to "gcc". This will make the
+:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-gcc`
+accordingly.
+
+.. _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 in 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 by default.
+
 .. _ref-classes-typecheck:
 
 ``typecheck``
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index d079e4b59..2bad5cda0 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7331,6 +7331,51 @@ 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
+      cross-compiling recipes. This variable is not meant to be overidden
+      globally. Instead, the values of :term:`PREFERRED_TOOLCHAIN_TARGET`,
+      :term:`PREFERRED_TOOLCHAIN_NATIVE` and :term:`PREFERRED_TOOLCHAIN_SDK`
+      should be overridden independently.
+
+      The value of this variable is the value :term:`PREFERRED_TOOLCHAIN_TARGET`.
+
+   :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.
+
+   :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.
+
+      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.
+
+      Selecting a value for this class will make the :ref:`ref-classes-base`
+      class inherit one of the toolchain class 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.
+
    :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 +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 :ref:`ref-classes-kernel-arch` class overrides this variable to "gcc",
+      because the Linux Kernel does not support toolchains other than
+      Gcc/Binutils for compiling.
+
    :term:`TOOLCHAIN_HOST_TASK`
       This variable lists packages the OpenEmbedded build system uses when
       building an SDK, which contains a cross-development environment. The

---
base-commit: f9f1c87424d307d2df60024bc448bd6778605cf8
change-id: 20250718-new-toolchain-variables-b92155294976

Best regards,
--  
Antonin Godard <antonin.godard@bootlin.com>

Re: [docs] [PATCH] ref-manual: document new toolchain classes and variables

[Quentin Schulz]

Hi Antonin,

On 7/18/25 10:22 AM, Antonin Godard via lists.yoctoproject.org wrote:
> 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>
> ---
>   documentation/ref-manual/classes.rst   | 43 ++++++++++++++++++++++++
>   documentation/ref-manual/variables.rst | 60 ++++++++++++++++++++++++++++++++++
>   2 files changed, 103 insertions(+)
> 
> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
> index 4705ca3f4..14f14b742 100644
> --- a/documentation/ref-manual/classes.rst
> +++ b/documentation/ref-manual/classes.rst
> @@ -3443,6 +3443,49 @@ 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 and LLVM compiler and utilities. This class is not meant to
> +be used directly in recipes. Instead, you should specific the

s/specific/set/

Should this be set globally in a conf file (distro I assume?)? Can this 
be overridden from a recipe if requested (e.g. recipes which can only be 
built with gcc or clang?). I see you document how to do this in the 
variable glossary, do you think it makes sense to duplicate the info in 
the class as well? I typically dislike doing this but I was wondering 
while reading the diff and got the info because it's in the same patch, 
maybe users won't think of this? /me shrugs

> +:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
> +:term:`PREFERRED_TOOLCHAIN_SDK` variables to "clang". This will make the
> +:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-clang`
> +accordingly.
> +

No toolchain/clang-native documented here?

> +.. _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 used directly in recipes. Instead, you should specific the

s/specific/set/

> +:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
> +:term:`PREFERRED_TOOLCHAIN_SDK` variables to "gcc". This will make the
> +:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-gcc`
> +accordingly.
> +
> +.. _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

s/Gcc/GCC/

c.f. https://gcc.gnu.org/

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

Odd comma there, I would remove it.

> +Exception be made in target recipes that need to use the compiler from the build

Not native but I would have done s/in/of/ here.

> +host at some point during the build.
> +
> +This class should not be inherited directly. It is inherited by the
> +:ref:`ref-classes-base` class by default.

Only when PREFERRED_TOOLCHAIN_NATIVE or TOOLCHAIN_NATIVE is set to gcc? 
Which is the default yes, but could be changed if a recipe/conf file 
changes that value?

> +
>   .. _ref-classes-typecheck:
>   
>   ``typecheck``
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index d079e4b59..2bad5cda0 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -7331,6 +7331,51 @@ 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
> +      cross-compiling recipes. This variable is not meant to be overidden

s/overidden/overridden/

Are you sure it's only for cross-compiling recipes? 
PREFERRED_TOOLCHAIN:class-native exists in 
meta/classes-global/base.bbclass and it's not for cross-compiling?

> +      globally. Instead, the values of :term:`PREFERRED_TOOLCHAIN_TARGET`,
> +      :term:`PREFERRED_TOOLCHAIN_NATIVE` and :term:`PREFERRED_TOOLCHAIN_SDK`
> +      should be overridden independently.
> +

Not sure what you wanted to convey with "independently" here?

> +      The value of this variable is the value :term:`PREFERRED_TOOLCHAIN_TARGET`.

No? It differs depending for what you're building (native, target, 
cross, crosssdk, nativesdk) from what I could read.

> +
> +   :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.
> +
> +   :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.
> +

Maybe add "machine" at the end of the sentence to highlight what a 
target is?

> +      There are two possible values for this variable at the moment:
> +
> +      -  :ref:`gcc <ref-classes-toolchain-gcc>` (default): the Gcc/Binutils toolchain.

s/Gcc/GCC/

> +      -  :ref:`clang <ref-classes-toolchain-clang>`: the Clang/LLVM toolchain.
> +
> +      Selecting a value for this class will make the :ref:`ref-classes-base`

S/Selecting a value for this class/:term:`PREFERRED_TOOLCHAIN_TARGET`/

> +      class inherit one of the toolchain class 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`.
> +

What happens for a recipe that only supports one toolchain and not the 
other? e.g. trusted-firmware-a for Rockchip RK3399 requires gcc right now.

> +      These classes define commands used for cross-compiling such as :term:`CC`,
> +      :term:`CXX`, :term:`LD` and so on.
> +
>      :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 +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.
> +

Aaaah, this way :) What about adding a small mention to the other 
PREFERRED_TOOLCHAIN_* variables so we know what to do if we want to 
override it for 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 :ref:`ref-classes-kernel-arch` class overrides this variable to "gcc",
> +      because the Linux Kernel does not support toolchains other than
> +      Gcc/Binutils for compiling.
> +

s/Gcc/GCC/

I was not convinced this was still true, but 
https://www.kernel.org/doc/html/latest/kbuild/llvm.html still says it is 
"ongoing work" so I guess it's not fully covered right now (and/or our 
classes/recipes do not support using clang for the kernel right now).

Missing a :term:`TOOLCHAIN_NATIVE` entry here (actually probably a few 
more lines below) maybe as well?

Cheers,
Quentin

Re: [docs] [PATCH] ref-manual: document new toolchain classes and variables

[Antonin Godard]

On Fri Jul 18, 2025 at 4:22 PM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 7/18/25 10:22 AM, Antonin Godard via lists.yoctoproject.org wrote:
>> 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>
>> ---
>>   documentation/ref-manual/classes.rst   | 43 ++++++++++++++++++++++++
>>   documentation/ref-manual/variables.rst | 60 ++++++++++++++++++++++++++++++++++
>>   2 files changed, 103 insertions(+)
>> 
>> diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
>> index 4705ca3f4..14f14b742 100644
>> --- a/documentation/ref-manual/classes.rst
>> +++ b/documentation/ref-manual/classes.rst
>> @@ -3443,6 +3443,49 @@ 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 and LLVM compiler and utilities. This class is not meant to
>> +be used directly in recipes. Instead, you should specific the
>
> s/specific/set/

Thanks for catching this

> Should this be set globally in a conf file (distro I assume?)? Can this 
> be overridden from a recipe if requested (e.g. recipes which can only be 
> built with gcc or clang?). I see you document how to do this in the 
> variable glossary, do you think it makes sense to duplicate the info in 
> the class as well? I typically dislike doing this but I was wondering 
> while reading the diff and got the info because it's in the same patch, 
> maybe users won't think of this? /me shrugs

You're right I should probably duplicate here to avoid confusion. Basically:

- Set PREFERRED_TOOLCHAIN_{SDK,TARGET,NATIVE} from distro conf
or
- Set TOOLCHAIN from recipe (overrides the distro setting)

Is my understanding and is what Khem told me on IRC.

Right now, setting PREFERRED_TOOLCHAIN_{SDK,NATIVE} to clang fails for me, even
though I believe it should be supported in the future which is why I haven't
mentioned it here.

>> +:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
>> +:term:`PREFERRED_TOOLCHAIN_SDK` variables to "clang". This will make the
>> +:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-clang`
>> +accordingly.
>> +
>
> No toolchain/clang-native documented here?

Good question, but there is none actually, only gcc-native. Perhaps related to
what I mentioned above or something is missing in OE-Core.

>> +.. _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 used directly in recipes. Instead, you should specific the
>
> s/specific/set/
>
>> +:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
>> +:term:`PREFERRED_TOOLCHAIN_SDK` variables to "gcc". This will make the
>> +:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-gcc`
>> +accordingly.
>> +
>> +.. _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
>
> s/Gcc/GCC/
>
> c.f. https://gcc.gnu.org/
>
>> +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.
>
> Odd comma there, I would remove it.

Yep, agreed

>> +Exception be made in target recipes that need to use the compiler from the build
>
> Not native but I would have done s/in/of/ here.

Actually should be "for". that same phrasing is used in the description of
BUILD_CC, and was suggested by you IIRC :)

>> +host at some point during the build.
>> +
>> +This class should not be inherited directly. It is inherited by the
>> +:ref:`ref-classes-base` class by default.
>
> Only when PREFERRED_TOOLCHAIN_NATIVE or TOOLCHAIN_NATIVE is set to gcc? 
> Which is the default yes, but could be changed if a recipe/conf file 
> changes that value?

Nope, this one is unconditionally inherited. Again, a bit strange, maybe an
error, maybe voluntary (hoping to gets comments here from Khem / Richard :)).

>> +
>>   .. _ref-classes-typecheck:
>>   
>>   ``typecheck``
>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>> index d079e4b59..2bad5cda0 100644
>> --- a/documentation/ref-manual/variables.rst
>> +++ b/documentation/ref-manual/variables.rst
>> @@ -7331,6 +7331,51 @@ 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
>> +      cross-compiling recipes. This variable is not meant to be overidden
>
> s/overidden/overridden/

Gah, always this one - thanks.

> Are you sure it's only for cross-compiling recipes? 
> PREFERRED_TOOLCHAIN:class-native exists in 
> meta/classes-global/base.bbclass and it's not for cross-compiling?

True, you're right, in a native context it's not cross-compiling. Thanks!

>> +      globally. Instead, the values of :term:`PREFERRED_TOOLCHAIN_TARGET`,
>> +      :term:`PREFERRED_TOOLCHAIN_NATIVE` and :term:`PREFERRED_TOOLCHAIN_SDK`
>> +      should be overridden independently.
>> +
>
> Not sure what you wanted to convey with "independently" here?

Yeah maybe bad/useless word here, I just wanted to say that these three should
be set, not PREFERRED_TOOLCHAIN directly.

>> +      The value of this variable is the value :term:`PREFERRED_TOOLCHAIN_TARGET`.
>
> No? It differs depending for what you're building (native, target, 
> cross, crosssdk, nativesdk) from what I could read.

You're right, my bad.

>> +
>> +   :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.
>> +
>> +   :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.
>> +
>
> Maybe add "machine" at the end of the sentence to highlight what a 
> target is?

Yes, thanks

>> +      There are two possible values for this variable at the moment:
>> +
>> +      -  :ref:`gcc <ref-classes-toolchain-gcc>` (default): the Gcc/Binutils toolchain.
>
> s/Gcc/GCC/
>
>> +      -  :ref:`clang <ref-classes-toolchain-clang>`: the Clang/LLVM toolchain.
>> +
>> +      Selecting a value for this class will make the :ref:`ref-classes-base`
>
> S/Selecting a value for this class/:term:`PREFERRED_TOOLCHAIN_TARGET`/
>
>> +      class inherit one of the toolchain class 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`.
>> +
>
> What happens for a recipe that only supports one toolchain and not the 
> other? e.g. trusted-firmware-a for Rockchip RK3399 requires gcc right now.
>
>> +      These classes define commands used for cross-compiling such as :term:`CC`,
>> +      :term:`CXX`, :term:`LD` and so on.
>> +
>>      :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 +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.
>> +
>
> Aaaah, this way :) What about adding a small mention to the other 
> PREFERRED_TOOLCHAIN_* variables so we know what to do if we want to 
> override it for a recipe?

Sure! Good point.

>> +      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 :ref:`ref-classes-kernel-arch` class overrides this variable to "gcc",
>> +      because the Linux Kernel does not support toolchains other than
>> +      Gcc/Binutils for compiling.
>> +
>
> s/Gcc/GCC/
>
> I was not convinced this was still true, but 
> https://www.kernel.org/doc/html/latest/kbuild/llvm.html still says it is 
> "ongoing work" so I guess it's not fully covered right now (and/or our 
> classes/recipes do not support using clang for the kernel right now).

Maybe not the best example then, I also doubted this a bit.. Will try to find
another example.

> Missing a :term:`TOOLCHAIN_NATIVE` entry here (actually probably a few 
> more lines below) maybe as well?

I can't find any reference to that variable anywhere across OE-Core, not sure it
exists?

Thanks!
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com

Re: [docs] [PATCH] ref-manual: document new toolchain classes and variables

[Quentin Schulz]

Hi Antonin,

On 7/18/25 4:36 PM, Antonin Godard wrote:
> On Fri Jul 18, 2025 at 4:22 PM CEST, Quentin Schulz wrote:
>> Hi Antonin,
>>
>> On 7/18/25 10:22 AM, Antonin Godard via lists.yoctoproject.org wrote:
[...]
>> Should this be set globally in a conf file (distro I assume?)? Can this
>> be overridden from a recipe if requested (e.g. recipes which can only be
>> built with gcc or clang?). I see you document how to do this in the
>> variable glossary, do you think it makes sense to duplicate the info in
>> the class as well? I typically dislike doing this but I was wondering
>> while reading the diff and got the info because it's in the same patch,
>> maybe users won't think of this? /me shrugs
> 
> You're right I should probably duplicate here to avoid confusion. Basically:
> 
> - Set PREFERRED_TOOLCHAIN_{SDK,TARGET,NATIVE} from distro conf
> or
> - Set TOOLCHAIN from recipe (overrides the distro setting)
> 
> Is my understanding and is what Khem told me on IRC.
> 

Makes sense to me :)

> Right now, setting PREFERRED_TOOLCHAIN_{SDK,NATIVE} to clang fails for me, even
> though I believe it should be supported in the future which is why I haven't
> mentioned it here.
> 

I've seen some patches from Khem today related to libcxx and clang, 
maybe that would help. Maybe you can give a bit more info here than "it 
fails for me" so Khem/anyone may be able to help?

>>> +:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
>>> +:term:`PREFERRED_TOOLCHAIN_SDK` variables to "clang". This will make the
>>> +:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-clang`
>>> +accordingly.
>>> +
>>
>> No toolchain/clang-native documented here?
> 
> Good question, but there is none actually, only gcc-native. Perhaps related to
> what I mentioned above or something is missing in OE-Core.
> 

Isn't there?

$ git show-ref HEAD
f209f127e654df7424adf41de07f88714d7952ab refs/remotes/origin/HEAD

$ ls -l meta/classes/toolchain/clang-native.bbclass
-rw-r--r--. 1 qschulz qschulz 789 Jul 15 14:28 
meta/classes/toolchain/clang-native.bbclass

Triple check you pulled OE-Core recently and/or you don't have a dirty repo?

[...]
>>> +Exception be made in target recipes that need to use the compiler from the build
>>
>> Not native but I would have done s/in/of/ here.
> 
> Actually should be "for". that same phrasing is used in the description of
> BUILD_CC, and was suggested by you IIRC :)
> 

Oh well, the joy of trusting your intuition and not being native, 
there's sometimes different outcomes when I'm not too sure :D

>>> +host at some point during the build.
>>> +
>>> +This class should not be inherited directly. It is inherited by the
>>> +:ref:`ref-classes-base` class by default.
>>
>> Only when PREFERRED_TOOLCHAIN_NATIVE or TOOLCHAIN_NATIVE is set to gcc?
>> Which is the default yes, but could be changed if a recipe/conf file
>> changes that value?
> 
> Nope, this one is unconditionally inherited. Again, a bit strange, maybe an
> error, maybe voluntary (hoping to gets comments here from Khem / Richard :)).
> 

This seems fine now?

meta/classes-global/base.bbclass

has

inherit_defer toolchain/${TOOLCHAIN_NATIVE}-native
inherit_defer toolchain/${TOOLCHAIN}

>>> +
>>>    .. _ref-classes-typecheck:
>>>    
>>>    ``typecheck``
>>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>>> index d079e4b59..2bad5cda0 100644
>>> --- a/documentation/ref-manual/variables.rst
>>> +++ b/documentation/ref-manual/variables.rst
>>> @@ -7331,6 +7331,51 @@ 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
>>> +      cross-compiling recipes. This variable is not meant to be overidden
>>
>> s/overidden/overridden/
> 
> Gah, always this one - thanks.
> 

If you use vim/nvim for writing this, you can use :set spell 
spelllang=en_us for example :)

[...]
>>> +      globally. Instead, the values of :term:`PREFERRED_TOOLCHAIN_TARGET`,
>>> +      :term:`PREFERRED_TOOLCHAIN_NATIVE` and :term:`PREFERRED_TOOLCHAIN_SDK`
>>> +      should be overridden independently.
>>> +
>>
>> Not sure what you wanted to convey with "independently" here?
> 
> Yeah maybe bad/useless word here, I just wanted to say that these three should
> be set, not PREFERRED_TOOLCHAIN directly.
> 

"instead" would be enough I believe, and that's how you start your 
sentence so I would just remove "independently"?

[...]

>> Missing a :term:`TOOLCHAIN_NATIVE` entry here (actually probably a few
>> more lines below) maybe as well?
> 
> I can't find any reference to that variable anywhere across OE-Core, not sure it
> exists?
> 

Added a week ago via ef31bc3074fa in poky, so I think your OE-Core/poky 
master branch is a bit behind :)

Cheers,
Quentin

Re: [docs] [PATCH] ref-manual: document new toolchain classes and variables

[Antonin Godard]

On Fri Jul 18, 2025 at 4:50 PM CEST, Quentin Schulz wrote:
> Hi Antonin,
>
> On 7/18/25 4:36 PM, Antonin Godard wrote:
>> On Fri Jul 18, 2025 at 4:22 PM CEST, Quentin Schulz wrote:
>>> Hi Antonin,
>>>
>>> On 7/18/25 10:22 AM, Antonin Godard via lists.yoctoproject.org wrote:
> [...]
>>> Should this be set globally in a conf file (distro I assume?)? Can this
>>> be overridden from a recipe if requested (e.g. recipes which can only be
>>> built with gcc or clang?). I see you document how to do this in the
>>> variable glossary, do you think it makes sense to duplicate the info in
>>> the class as well? I typically dislike doing this but I was wondering
>>> while reading the diff and got the info because it's in the same patch,
>>> maybe users won't think of this? /me shrugs
>> 
>> You're right I should probably duplicate here to avoid confusion. Basically:
>> 
>> - Set PREFERRED_TOOLCHAIN_{SDK,TARGET,NATIVE} from distro conf
>> or
>> - Set TOOLCHAIN from recipe (overrides the distro setting)
>> 
>> Is my understanding and is what Khem told me on IRC.
>> 
>
> Makes sense to me :)
>
>> Right now, setting PREFERRED_TOOLCHAIN_{SDK,NATIVE} to clang fails for me, even
>> though I believe it should be supported in the future which is why I haven't
>> mentioned it here.
>> 
>
> I've seen some patches from Khem today related to libcxx and clang, 
> maybe that would help. Maybe you can give a bit more info here than "it 
> fails for me" so Khem/anyone may be able to help?

I did not dig much into it knowing the implementation is WIP, so I'll building
again with the recent changes around that.

>>>> +:term:`PREFERRED_TOOLCHAIN_TARGET`, :term:`PREFERRED_TOOLCHAIN_NATIVE` or
>>>> +:term:`PREFERRED_TOOLCHAIN_SDK` variables to "clang". This will make the
>>>> +:ref:`ref-classes-base` class use the :ref:`ref-classes-toolchain-clang`
>>>> +accordingly.
>>>> +
>>>
>>> No toolchain/clang-native documented here?
>> 
>> Good question, but there is none actually, only gcc-native. Perhaps related to
>> what I mentioned above or something is missing in OE-Core.
>> 
>
> Isn't there?
>
> $ git show-ref HEAD
> f209f127e654df7424adf41de07f88714d7952ab refs/remotes/origin/HEAD
>
> $ ls -l meta/classes/toolchain/clang-native.bbclass
> -rw-r--r--. 1 qschulz qschulz 789 Jul 15 14:28 
> meta/classes/toolchain/clang-native.bbclass
>
> Triple check you pulled OE-Core recently and/or you don't have a dirty repo?

Yeah, my bad, my repository was slightly updated and I missed that.

> [...]
>>>> +Exception be made in target recipes that need to use the compiler from the build
>>>
>>> Not native but I would have done s/in/of/ here.
>> 
>> Actually should be "for". that same phrasing is used in the description of
>> BUILD_CC, and was suggested by you IIRC :)
>> 
>
> Oh well, the joy of trusting your intuition and not being native, 
> there's sometimes different outcomes when I'm not too sure :D
>
>>>> +host at some point during the build.
>>>> +
>>>> +This class should not be inherited directly. It is inherited by the
>>>> +:ref:`ref-classes-base` class by default.
>>>
>>> Only when PREFERRED_TOOLCHAIN_NATIVE or TOOLCHAIN_NATIVE is set to gcc?
>>> Which is the default yes, but could be changed if a recipe/conf file
>>> changes that value?
>> 
>> Nope, this one is unconditionally inherited. Again, a bit strange, maybe an
>> error, maybe voluntary (hoping to gets comments here from Khem / Richard :)).
>> 
>
> This seems fine now?
>
> meta/classes-global/base.bbclass
>
> has
>
> inherit_defer toolchain/${TOOLCHAIN_NATIVE}-native
> inherit_defer toolchain/${TOOLCHAIN}
>
>>>> +
>>>>    .. _ref-classes-typecheck:
>>>>    
>>>>    ``typecheck``
>>>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>>>> index d079e4b59..2bad5cda0 100644
>>>> --- a/documentation/ref-manual/variables.rst
>>>> +++ b/documentation/ref-manual/variables.rst
>>>> @@ -7331,6 +7331,51 @@ 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
>>>> +      cross-compiling recipes. This variable is not meant to be overidden
>>>
>>> s/overidden/overridden/
>> 
>> Gah, always this one - thanks.
>> 
>
> If you use vim/nvim for writing this, you can use :set spell 
> spelllang=en_us for example :)

I do have spelllang enabled though, just missed that :/

> [...]
>>>> +      globally. Instead, the values of :term:`PREFERRED_TOOLCHAIN_TARGET`,
>>>> +      :term:`PREFERRED_TOOLCHAIN_NATIVE` and :term:`PREFERRED_TOOLCHAIN_SDK`
>>>> +      should be overridden independently.
>>>> +
>>>
>>> Not sure what you wanted to convey with "independently" here?
>> 
>> Yeah maybe bad/useless word here, I just wanted to say that these three should
>> be set, not PREFERRED_TOOLCHAIN directly.
>> 
>
> "instead" would be enough I believe, and that's how you start your 
> sentence so I would just remove "independently"?

Agreed

> [...]
>
>>> Missing a :term:`TOOLCHAIN_NATIVE` entry here (actually probably a few
>>> more lines below) maybe as well?
>> 
>> I can't find any reference to that variable anywhere across OE-Core, not sure it
>> exists?
>> 
>
> Added a week ago via ef31bc3074fa in poky, so I think your OE-Core/poky 
> master branch is a bit behind :)

Thanks,
Antonin

-- 
Antonin Godard, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com