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

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

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