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

["Antonin Godard" <antonin.godard@bootlin.com>]

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