Re: [docs] [PATCH 1/4] ref-manual/variables.rst: add missing documentation for BUILD_* variables

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

Hi Quentin,

On Wed Mar 26, 2025 at 10:49 AM CET, Quentin Schulz wrote:
> Hi Antonin,
>
> On 3/26/25 10:17 AM, Antonin Godard wrote:
>> Hi Quentin,
>> 
>> On Fri Mar 21, 2025 at 5:22 PM CET, Quentin Schulz wrote:
>>> Hi Antonin,
>>>
>>> On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote:
>>>> These toolchain variables are used in a native context. Some of the
>>>> BUILD_* variables missed documentation. Also, some of the base commands
>>>> were also not there so document them (FC and READELF).
>>>>
>>>> Some of existing BUILD_* variable documentation were missing the note
>>>> about their usage in a native context, so add it too so that all BUILD_*
>>>> variables are documented the same way.
>>>>
>>>> [YOCTO #15719]
>>>>
>>>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>>>> ---
>>>>    documentation/ref-manual/variables.rst | 107 +++++++++++++++++++++++++
>>>>    1 file changed, 107 insertions(+)
>>>>
>>>> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
>>>> index 861b04eaa..24b3f7db9 100644
>>>> --- a/documentation/ref-manual/variables.rst
>>>> +++ b/documentation/ref-manual/variables.rst
>>>> @@ -985,6 +985,24 @@ system and gives an overview of their function and contents.
>>>>          variable is a useful pointer in case a bug in the software being
>>>>          built needs to be manually reported.
>>>>    
>>>> +   :term:`BUILD_AR`
>>>> +      Specifies the architecture-specific archiver for the build host,
>>>> +      derived in part from :term:`BUILD_PREFIX`::
>>>> +
>>>> +         BUILD_AR = "${BUILD_PREFIX}ar"
>>>> +
>>>> +      When building in the ``-native`` context, :term:`AR` is set to the value
>>>> +      of this variable by default.
>>>> +
>>>
>>> It's not entirely clear to me from the text, but I believe we should
>>> only be consumer of this variable? Or the toolchain recipe/bbclass needs
>>> to set it accordingly, but otherwise nobody should *modify* it, right?
>> 
>> Actually, users shouldn't even use this variable directly but only AR (see
>> the explanation below).
>> 
>
> Then we should make this very clear in the documentation for the 
> variable. Essentially "treat this as a read-only variable except if 
> you're adding support for a new toolchain" or something like this.

I've found the following wording:

"""
When building a :ref:`ref-classes-native` recipe, :term:`AR` is set to the
value of this variable by default, so there is no need to use
:term:`BUILD_AR` directly.
"""

"No need" is less strict than "never", because there might be some niche cases
where you would use that. What do you think?

Take meta/recipes-devtools/meson/meson_1.7.0.bb: it uses it in
install_templates() which is called from do_install:append:class-nativesdk(), so
here since we know we will always run in a native context, we can use BUILD_*
variables. Although I would assume using regular AR, STRIP, etc. would work as
well.

[...]
>>>
>>> A user question: Should we use BUILD_AR directly? or always AR?
>> 
>> Always AR, to my understanding. The native class takes care of setting AR to the
>> value of BUILD_AR. In your recipe, you can use the AR variable to do your
>> things, and its value will change on whether you're building the native recipe
>> or not.
>> 
>> You would only redefine BUILD_* variables if you were to add
>> a new toolchain, basically. See toolchain/build-gcc.inc in OE-Core, for an
>> example.
>> 
>
> I think we should make this very clear. Essentially:
>
> """
> This is only relevant when adding support for a new toolchain. Users are 
> strongly encouraged to use :term:`AR` when wanting to use the archiver 
> in recipes.
> """
>
> or something along those lines?

See the wording I proposed above (which I will propagate to every BUILD_*
definitions).

> (same remark for all other BUILD_ variables).
>
>>>> +      Specifies the architecture-specific assembler for the build host,
>>>> +      derived in part from from :term:`BUILD_PREFIX`::
>>>> +
>>>> +         BUILD_AS = "${BUILD_PREFIX}ar"
>>>> +
>>>> +      When building in the ``-native`` context, :term:`AS` is set to the value
>>>> +      of this variable by default.
>>>> +
>>>>       :term:`BUILD_ARCH`
>>>>          Specifies the architecture of the build host (e.g. ``i686``). The
>>>>          OpenEmbedded build system sets the value of :term:`BUILD_ARCH` from the
>>>> @@ -994,6 +1012,15 @@ system and gives an overview of their function and contents.
>>>>          Specifies the architecture-specific assembler flags for the build
>>>>          host. By default, the value of :term:`BUILD_AS_ARCH` is empty.
>>>>    
>>>> +   :term:`BUILD_CC`
>>>> +      Specifies the architecture-specific C compiler for the build host,
>>>> +      derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`::
>>>> +
>>>> +         BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}"
>>>> +
>>>
>>> This seems very gcc-specific but I cannot see the same thing for clang,
>>> so I guess it's fine?
>> 
>> I will mention that this is the default value. Indeed if you were to use clang,
>> the definition would be different from this one. I think there will be
>> evolutions on that in the future, because the toolchain/ directory was made
>> to prepare the ground for supporting clang (I think).
>> 
>
> This is actually not the default. It's set by the gcc toolchain, which I 
> assume is the default (and only?) toolchain.

For now, yes, I think it is the only one.

So, saying that this value is the default is not wrong since bitbake.conf does:

require toolchain/gcc.inc
require toolchain/build-gcc.inc

?

> I assume we want to state that you should not modify this variable, 
> except if you are adding support for a new toolchain, but you can use it 
> wherever the CC (for native recipes) or HOSTCC (for target recipes) 
> variables are expected to be set?

I feel like there should even be a separate guide/section to explain how to add
support for a new toolchain at some point? (how common of a task would that be,
though?)

I'm not sure we should in length on adding a new toolchain in the BUILD_*
variable definitions.

But let's see if we can agree on a wording that I'll propagate to every BUILD_*
variable. :)

Thanks,
Antonin

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