[PATCH 0/4] Document missing toolchain related variables

[PATCH 0/4] Document missing toolchain related variables

[Antonin Godard]

Document a bunch a toolchain related variables. These follow a naming
scheme to make them easier to deduce from the name. Try clearing this
out for users reading the documentation.

Fixes https://bugzilla.yoctoproject.org/show_bug.cgi?id=15719.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Antonin Godard (4):
      ref-manual/variables.rst: add missing documentation for BUILD_* variables
      ref-manual/variables.rst: document missing SDK_*_ARCH variables
      ref-manual/variables.rst: document HOST_*_ARCH variables
      ref-manual/variables.rst: HOST_CC_ARCH: fix wrong SDK reference

 documentation/ref-manual/variables.rst | 152 ++++++++++++++++++++++++++++++++-
 1 file changed, 150 insertions(+), 2 deletions(-)
---
base-commit: e608902ffae3af5ab0c5308b0550e49a790482f0
change-id: 20250317-cc-vars-e2cd2076a3a6

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

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

[Antonin Godard]

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.
+
+   :term:`BUILD_AS`
+      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}"
+
+      When building in the ``-native`` context, :term:`CC` is set to the value
+      of this variable by default.
+
    :term:`BUILD_CC_ARCH`
       Specifies the architecture-specific C compiler flags for the build
       host. By default, the value of :term:`BUILD_CC_ARCH` is empty.
@@ -1011,12 +1038,31 @@ system and gives an overview of their function and contents.
       :term:`CFLAGS` is set to the value of this variable by
       default.
 
+   :term:`BUILD_CPP`
+      Specifies the C preprocessor command (to both the C and the C++ compilers)
+      when building for the build host, derived in part from
+      :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`::
+
+         BUILD_CPP = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH} -E"
+
+      When building in the ``-native`` context, :term:`CPP` is set to the value
+      of this variable by default.
+
    :term:`BUILD_CPPFLAGS`
       Specifies the flags to pass to the C preprocessor (i.e. to both the C
       and the C++ compilers) when building for the build host. When
       building in the ``-native`` context, :term:`CPPFLAGS`
       is set to the value of this variable by default.
 
+   :term:`BUILD_CXX`
+      Specifies the architecture-specific C++ compiler for the build host,
+      derived in part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`::
+
+         BUILD_CXX = "${CCACHE}${BUILD_PREFIX}g++ ${BUILD_CC_ARCH}"
+
+      When building in the ``-native`` context, :term:`CXX` is set to the value
+      of this variable by default.
+
    :term:`BUILD_CXXFLAGS`
       Specifies the flags to pass to the C++ compiler when building for the
       build host. When building in the ``-native`` context,
@@ -1029,12 +1075,18 @@ system and gives an overview of their function and contents.
       value of :term:`BUILD_CC_ARCH`, assuming
       :term:`BUILD_CC_ARCH` is set.
 
+      When building in the ``-native`` context, :term:`FC` is set to the value
+      of this variable by default.
+
    :term:`BUILD_LD`
       Specifies the linker command for the build host. By default,
       :term:`BUILD_LD` points to the GNU linker (ld) and passes as arguments
       the value of :term:`BUILD_LD_ARCH`, assuming
       :term:`BUILD_LD_ARCH` is set.
 
+      When building in the ``-native`` context, :term:`LD` is set to the value
+      of this variable by default.
+
    :term:`BUILD_LD_ARCH`
       Specifies architecture-specific linker flags for the build host. By
       default, the value of :term:`BUILD_LD_ARCH` is empty.
@@ -1045,6 +1097,34 @@ system and gives an overview of their function and contents.
       :term:`LDFLAGS` is set to the value of this variable
       by default.
 
+   :term:`BUILD_NM`
+      Specifies the architecture-specific utility to list symbols from object
+      files for the build host, derived in part from :term:`BUILD_PREFIX`::
+
+         BUILD_NM = "${BUILD_PREFIX}nm"
+
+      When building in the ``-native`` context, :term:`NM` is set to the
+      value of this variable by default.
+
+   :term:`BUILD_OBJCOPY`
+      Specifies the architecture-specific utility to copy object files for the
+      build host, derived in part from :term:`BUILD_PREFIX`::
+
+         BUILD_OBJCOPY = "${BUILD_PREFIX}objcopy"
+
+      When building in the ``-native`` context, :term:`OBJCOPY` is set to the
+      value of this variable by default.
+
+   :term:`BUILD_OBJDUMP`
+      Specifies the architecture-specific utility to display object files
+      information for the build host, derived in part from
+      :term:`BUILD_PREFIX`::
+
+         BUILD_OBJDUMP = "${BUILD_PREFIX}objdump"
+
+      When building in the ``-native`` context, :term:`OBJDUMP` is set to the
+      value of this variable by default.
+
    :term:`BUILD_OPTIMIZATION`
       Specifies the optimization flags passed to the C compiler when
       building for the build host or the SDK. The flags are passed through
@@ -1065,12 +1145,33 @@ system and gives an overview of their function and contents.
       build system uses the :term:`BUILD_PREFIX` value to set the
       :term:`TARGET_PREFIX` when building for :ref:`ref-classes-native` recipes.
 
+   :term:`BUILD_RANLIB`
+      Specifies the architecture-specific utility to generate indexes for
+      archives for the build host, derived in part from :term:`BUILD_PREFIX`::
+
+         BUILD_RANLIB = "${BUILD_PREFIX}ranlib -D"
+
+      When building in the ``-native`` context, :term:`RANLIB` is set to the
+      value of this variable by default.
+
+   :term:`BUILD_READELF`
+      Specifies the architecture-specific utility to display information about
+      ELF files for the build host, derived in part from :term:`BUILD_PREFIX`::
+
+         BUILD_READELF = "${BUILD_PREFIX}readelf"
+
+      When building in the ``-native`` context, :term:`READELF` is set to the
+      value of this variable by default.
+
    :term:`BUILD_STRIP`
       Specifies the command to be used to strip debugging symbols from
       binaries produced for the build host. By default, :term:`BUILD_STRIP`
       points to
       ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
 
+      When building in the ``-native`` context, :term:`STRIP` is set to the
+      value of this variable by default.
+
    :term:`BUILD_SYS`
       Specifies the system, including the architecture and the operating
       system, to use when building for the build host (i.e. when building
@@ -2818,6 +2919,9 @@ system and gives an overview of their function and contents.
    :term:`FAKEROOTNOENV`
       See :term:`bitbake:FAKEROOTNOENV` in the BitBake manual.
 
+   :term:`FC`
+      The minimal command and arguments used to run the Fortran compiler.
+
    :term:`FEATURE_PACKAGES`
       Defines one or more packages to include in an image when a specific
       item is included in :term:`IMAGE_FEATURES`.
@@ -7289,6 +7393,9 @@ system and gives an overview of their function and contents.
       ":ref:`bitbake-user-manual/bitbake-user-manual-execution:dependencies`" sections in the
       BitBake User Manual for additional information on tasks and dependencies.
 
+   :term:`READELF`
+      The minimal command and arguments to run ``readelf``.
+
    :term:`RECIPE_MAINTAINER`
       This variable defines the name and e-mail address of the maintainer of a
       recipe. Such information can be used by human users submitted changes,

-- 
2.47.0

[PATCH 2/4] ref-manual/variables.rst: document missing SDK_*_ARCH variables

[Antonin Godard]

These variables control the flags for the assembler, compiler and linker
when building for nativesdk recipes.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/variables.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 24b3f7db9..4063fda8c 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7793,11 +7793,21 @@ system and gives an overview of their function and contents.
 
       Only one archive type can be specified.
 
+   :term:`SDK_AS_ARCH`
+      Specifies architecture-specific assembler flags when building
+      :ref:`ref-classes-nativesdk` recipes. By default, the value of
+      :term:`SDK_AS_ARCH` equals the one of :term:`BUILD_AS_ARCH`.
+
    :term:`SDK_BUILDINFO_FILE`
       When using the :ref:`ref-classes-image-buildinfo` class,
       specifies the file in the SDK to write the build information into. The
       default value is "``/buildinfo``".
 
+   :term:`SDK_CC_ARCH`
+      Specifies the architecture-specific C compiler flags when building
+      :ref:`ref-classes-nativesdk` recipes. By default, the value of
+      :term:`SDK_CC_ARCH` equals the one of :term:`BUILD_CC_ARCH`.
+
    :term:`SDK_CUSTOM_TEMPLATECONF`
       When building the extensible SDK, if :term:`SDK_CUSTOM_TEMPLATECONF` is set to
       "1" and a ``conf/templateconf.cfg`` file exists in the :term:`Build Directory`
@@ -7879,6 +7889,11 @@ system and gives an overview of their function and contents.
       :term:`SDK_EXT_TYPE` is set to "minimal", and defaults to "1" if
       :term:`SDK_EXT_TYPE` is set to "full".
 
+   :term:`SDK_LD_ARCH`
+      Specifies architecture-specific linker flags when building
+      :ref:`ref-classes-nativesdk` recipes. By default, the value of
+      :term:`SDK_LD_ARCH` equals the one of :term:`BUILD_LD_ARCH`.
+
    :term:`SDK_NAME`
       The base name for SDK output files. The default value (as set in
       ``meta-poky/conf/distro/poky.conf``) is derived from the

-- 
2.47.0

[PATCH 3/4] ref-manual/variables.rst: document HOST_*_ARCH variables

[Antonin Godard]

These variables control the flags for the assembler, compiler and
linker, but depend on the context.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/variables.rst | 27 ++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 4063fda8c..f339e409e 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3547,6 +3547,20 @@ system and gives an overview of their function and contents.
       - mips
       - mipsel
 
+   :term:`HOST_AS_ARCH`
+      Specifies architecture-specific assembler flags.
+
+      Default initialization for :term:`HOST_AS_ARCH` varies depending on what
+      is being built:
+
+      -  :term:`TARGET_AS_ARCH` when building for the
+         target
+
+      -  :term:`BUILD_AS_ARCH` when building for the build host (i.e.
+         ``-native``)
+
+      -  :term:`SDK_AS_ARCH` when building for an SDK (i.e. ``nativesdk-``)
+
    :term:`HOST_CC_ARCH`
       Specifies architecture-specific compiler flags that are passed to the
       C compiler.
@@ -3563,6 +3577,19 @@ system and gives an overview of their function and contents.
       -  ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
          ``nativesdk-``)
 
+   :term:`HOST_LD_ARCH`
+      Specifies architecture-specific linker flags.
+
+      Default initialization for :term:`HOST_LD_ARCH` varies depending on what
+      is being built:
+
+      -  :term:`TARGET_LD_ARCH` when building for the target
+
+      -  :term:`BUILD_LD_ARCH` when building for the build host (i.e.
+         ``-native``)
+
+      -  :term:`SDK_LD_ARCH` when building for an SDK (i.e. ``nativesdk-``)
+
    :term:`HOST_OS`
       Specifies the name of the target operating system, which is normally
       the same as the :term:`TARGET_OS`. The variable can

-- 
2.47.0

[PATCH 4/4] ref-manual/variables.rst: HOST_CC_ARCH: fix wrong SDK reference

[Antonin Godard]

When building for nativesdk recipes, HOST_CC_ARCH equals SDK_CC_ARCH,
not BUILDSDK_CC_ARCH which doesn't exist.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/ref-manual/variables.rst | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index f339e409e..20f78a7ab 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3574,8 +3574,7 @@ system and gives an overview of their function and contents.
       -  :term:`BUILD_CC_ARCH` when building for the build host (i.e.
          ``-native``)
 
-      -  ``BUILDSDK_CC_ARCH`` when building for an SDK (i.e.
-         ``nativesdk-``)
+      -  :term:`SDK_CC_ARCH` when building for an SDK (i.e. ``nativesdk-``)
 
    :term:`HOST_LD_ARCH`
       Specifies architecture-specific linker flags.

-- 
2.47.0

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

[Antonin Godard]

On Mon Mar 17, 2025 at 5:03 PM CET, 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.
> +
> +   :term:`BUILD_AS`
> +      Specifies the architecture-specific assembler for the build host,
> +      derived in part from from :term:`BUILD_PREFIX`::
> +
> +         BUILD_AS = "${BUILD_PREFIX}ar"

Should be "${BUILD_PREFIX}as", will fix in v2.

Antonin

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

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

[Quentin Schulz]

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?

I don't know what an archiver is, would there be a link we could provide 
to give hints to people maybe?

Can suggest:

"""
When building a native recipe, :term:`AR` ...
"""

I would love to add a link to what a native recipe is but my grep-fu 
failed me today and couldn't find anything satisfying, do you have a 
suggestion maybe?

A user question: Should we use BUILD_AR directly? or always AR?

s/build host/:term:`Build Host`/ ?

Same remarks for other BUILD_ addition in this patch.

> +   :term:`BUILD_AS`

This is not alphabetically ordered though, since the next one is 
BUILD_ARCH, which should be before BUILD_AS.

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

[...]

>      :term:`BUILD_STRIP`
>         Specifies the command to be used to strip debugging symbols from
>         binaries produced for the build host. By default, :term:`BUILD_STRIP`
>         points to
>         ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
>   

thought: maybe have consistency with the way you expose the default 
value of the variable for the variables added in this patch?

e.g.

"""
derived in part from :term:`BUILD_PREFIX`::

          BUILD_STRIP = "${BUILD_PREFIX}strip"
"""

Cheers,
Quentin

Re: [docs] [PATCH 3/4] ref-manual/variables.rst: document HOST_*_ARCH variables

[Quentin Schulz]

Hi Antonin,

On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote:
> These variables control the flags for the assembler, compiler and
> linker, but depend on the context.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

Re: [docs] [PATCH 4/4] ref-manual/variables.rst: HOST_CC_ARCH: fix wrong SDK reference

[Quentin Schulz]

On 3/17/25 5:03 PM, Antonin Godard via lists.yoctoproject.org wrote:
> When building for nativesdk recipes, HOST_CC_ARCH equals SDK_CC_ARCH,
> not BUILDSDK_CC_ARCH which doesn't exist.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>

Thanks!
Quentin

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

[Antonin Godard]

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

> I don't know what an archiver is, would there be a link we could provide 
> to give hints to people maybe?
>
> Can suggest:
>
> """
> When building a native recipe, :term:`AR` ...
> """
>
> I would love to add a link to what a native recipe is but my grep-fu 
> failed me today and couldn't find anything satisfying, do you have a 
> suggestion maybe?

:ref:`ref-classes-native`?

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

> s/build host/:term:`Build Host`/ ?

Yes, thanks.

> Same remarks for other BUILD_ addition in this patch.
>
>> +   :term:`BUILD_AS`
>
> This is not alphabetically ordered though, since the next one is 
> BUILD_ARCH, which should be before BUILD_AS.

Well spotted, thank you!

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

> [...]
>
>>      :term:`BUILD_STRIP`
>>         Specifies the command to be used to strip debugging symbols from
>>         binaries produced for the build host. By default, :term:`BUILD_STRIP`
>>         points to
>>         ``${``\ :term:`BUILD_PREFIX`\ ``}strip``.
>>   
>
> thought: maybe have consistency with the way you expose the default 
> value of the variable for the variables added in this patch?
>
> e.g.
>
> """
> derived in part from :term:`BUILD_PREFIX`::
>
>           BUILD_STRIP = "${BUILD_PREFIX}strip"
> """

Yes, I was aiming at that, but missed this one - thanks!

Antonin

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

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

[Quentin Schulz]

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 don't know what an archiver is, would there be a link we could provide
>> to give hints to people maybe?
>>
>> Can suggest:
>>
>> """
>> When building a native recipe, :term:`AR` ...
>> """
>>
>> I would love to add a link to what a native recipe is but my grep-fu
>> failed me today and couldn't find anything satisfying, do you have a
>> suggestion maybe?
> 
> :ref:`ref-classes-native`?
> 

Works for me!

>>
>> 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?

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

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?

Cheers,
Quentin

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

[Antonin Godard]

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

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

[Quentin Schulz]

Hi Antonin,

On 3/26/25 11:33 AM, Antonin Godard wrote:
> 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.
> 

Seems like cargo and rust classes also need to specify BUILD_AR explicitly.

So I rescind my comment on not using BUILD_AR directly, you just 
essentially don't need to set it and only need to use it in target 
recipes when wanting to point at the build host `ar`.

Same for the other BUILD_* variables.

> [...]
>>>>
>>>> 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
> 
> ?
> 

Well yeah ok, that's the default then :)

Not entirely sure how meta/conf/toolchain/clang.inc should be used, but 
I guess it'll eventually come :)

Fine with me, rescinding this comment as well. "default" term is fine.

>> 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?)
> 

Considering we still don't have a second toolchain for the very popular 
clang, I'm not sure we'll have a third one soon :) But doesn't hurt to 
document the findings for when the second toolchain will be added, so 
that a third one would be easier to support.

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

Fair. We can point at the terms from that yet-to-be-written "how to add 
a toolchain" section.

Cheers,
Quentin