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

[Quentin Schulz <quentin.schulz@cherry.de>]

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