[PATCH v3 0/6] Document missing toolchain related variables

[PATCH v3 0/6] 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>
---
Changes in v3:
- Review by Quentin (thank you!):
  - Include section number for manpage links.
  - For BUILD_* variables, be more precise about the fact that we should
    not override it from recipes but we can sometimes use them to refer
    to a host tool from a target recipe context.
- Link to v2: https://lore.kernel.org/r/20250326-cc-vars-v2-0-36b80c64c4a9@bootlin.com

Changes in v2:
- Add a patch to define a manpage url, for giving manpage links in the
  docs.
- Reformulate the BUILD_* definitions to explicitely say that we are not
  supposed to set these variables or use them directly in recipes.
- Link to v1: https://lore.kernel.org/r/20250317-cc-vars-v1-0-25edbadfd054@bootlin.com

---
Antonin Godard (6):
      documentation/conf.py: define a manpage url
      ref-manual/variables.rst: add manpage links for toolchain variables
      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/conf.py                      |   3 +
 documentation/overview-manual/concepts.rst |   2 +-
 documentation/overview-manual/yp-intro.rst |   2 +-
 documentation/ref-manual/variables.rst     | 319 ++++++++++++++++++++++++++---
 4 files changed, 291 insertions(+), 35 deletions(-)
---
base-commit: ee6b3698da044e290dbc4fbb852f3cc37638e689
change-id: 20250317-cc-vars-e2cd2076a3a6

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

[PATCH v3 1/6] documentation/conf.py: define a manpage url

[Antonin Godard]

By defining the manpages_url we can use the :manpage: role in the
documentation for providing links to manpages. See:
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url

Replace existing manpages links to use this role.

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/conf.py                      | 3 +++
 documentation/overview-manual/concepts.rst | 2 +-
 documentation/overview-manual/yp-intro.rst | 2 +-
 documentation/ref-manual/variables.rst     | 4 ++--
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/documentation/conf.py b/documentation/conf.py
index 477e75112a..0352bbef20 100644
--- a/documentation/conf.py
+++ b/documentation/conf.py
@@ -111,6 +111,9 @@ extlinks = {
     'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
 }
 
+# To able to use :manpage:`<something>` in the docs.
+manpages_url = 'https://manpages.debian.org/{path}'
+
 # Intersphinx config to use cross reference with BitBake user manual
 intersphinx_mapping = {
     'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None)
diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
index e4d806f98f..416c28f0d9 100644
--- a/documentation/overview-manual/concepts.rst
+++ b/documentation/overview-manual/concepts.rst
@@ -2204,7 +2204,7 @@ require root privileges, the fact that some earlier steps ran in a fake
 root environment does not cause problems.
 
 The capability to run tasks in a fake root environment is known as
-"`fakeroot <http://man.he.net/man1/fakeroot>`__", which is derived from
+":manpage:`fakeroot <fakeroot(1)>`", which is derived from
 the BitBake keyword/variable flag that requests a fake root environment
 for a task.
 
diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
index 4a27e12e01..11e6d99e32 100644
--- a/documentation/overview-manual/yp-intro.rst
+++ b/documentation/overview-manual/yp-intro.rst
@@ -400,7 +400,7 @@ Yocto Project:
    Autobuilder :doc:`here </test-manual/understand-autobuilder>`.
 
 -  *Pseudo:* Pseudo is the Yocto Project implementation of
-   `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run
+   :manpage:`fakeroot <fakeroot(1)>`, which is used to run
    commands in an environment that seemingly has root privileges.
 
    During a build, it can be necessary to perform operations that
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 41bda5d0d6..4e675b6bfb 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -4514,8 +4514,8 @@ system and gives an overview of their function and contents.
 
       The value in :term:`INITSCRIPT_PARAMS` is passed through to the
       ``update-rc.d`` command. For more information on valid parameters,
-      please see the ``update-rc.d`` manual page at
-      https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
+      please see the ``update-rc.d`` manual page at :manpage:`update-rc.d
+      <update-rc.d(8)>`.
 
    :term:`INSANE_SKIP`
       Specifies the QA checks to skip for a specific package within a

-- 
2.47.0

[PATCH v3 2/6] ref-manual/variables.rst: add manpage links for toolchain variables

[Antonin Godard]

Use the :manpage: role to provide links to common toolchain utilities.

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

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 4e675b6bf..d98721818 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -143,7 +143,7 @@ system and gives an overview of their function and contents.
       information on how this variable is used.
 
    :term:`AR`
-      The minimal command and arguments used to run ``ar``.
+      The minimal command and arguments used to run :manpage:`ar <ar(1)>`.
 
    :term:`ARCHIVER_MODE`
       When used with the :ref:`ref-classes-archiver` class,
@@ -165,7 +165,8 @@ system and gives an overview of their function and contents.
       ``meta/classes/archiver.bbclass`` file in the :term:`Source Directory`.
 
    :term:`AS`
-      Minimal command and arguments needed to run the assembler.
+      Minimal command and arguments needed to run the :manpage:`assembler
+      <as(1)>`.
 
    :term:`ASSUME_PROVIDED`
       Lists recipe names (:term:`PN` values) BitBake does not
@@ -5165,7 +5166,8 @@ system and gives an overview of their function and contents.
       ``LAYERVERSION_mylayer``).
 
    :term:`LD`
-      The minimal command and arguments used to run the linker.
+      The minimal command and arguments used to run the :manpage:`linker
+      <ld(1)>`.
 
    :term:`LDFLAGS`
       Specifies the flags to pass to the linker. This variable is exported
@@ -5771,7 +5773,7 @@ system and gives an overview of their function and contents.
       variable is set.
 
    :term:`NM`
-      The minimal command and arguments to run ``nm``.
+      The minimal command and arguments to run :manpage:`nm <nm(1)>`.
 
    :term:`NO_GENERIC_LICENSE`
       Avoids QA errors when you use a non-common, non-CLOSED license in a
@@ -5860,10 +5862,10 @@ system and gives an overview of their function and contents.
           NVDCVE_API_KEY = "fe753&7a2-1427-347d-23ff-b2e2b7ca5f3"
 
    :term:`OBJCOPY`
-      The minimal command and arguments to run ``objcopy``.
+      The minimal command and arguments to run :manpage:`objcopy <objcopy(1)>`.
 
    :term:`OBJDUMP`
-      The minimal command and arguments to run ``objdump``.
+      The minimal command and arguments to run :manpage:`objdump <objdump(1)>`.
 
    :term:`OE_BINCONFIG_EXTRA_MANGLE`
       When inheriting the :ref:`ref-classes-binconfig` class,
@@ -7174,7 +7176,7 @@ system and gives an overview of their function and contents.
          QA_EMPTY_DIRS_RECOMMENDATION:/dev = "but all devices must be created at runtime"
 
    :term:`RANLIB`
-      The minimal command and arguments to run ``ranlib``.
+      The minimal command and arguments to run :manpage:`ranlib <ranlib(1)>`.
 
    :term:`RCONFLICTS`
       The list of packages that conflict with packages. Note that packages
@@ -8914,8 +8916,8 @@ system and gives an overview of their function and contents.
       places stamps. The default directory is ``${TMPDIR}/stamps``.
 
    :term:`STRIP`
-      The minimal command and arguments to run ``strip``, which is used to
-      strip symbols.
+      The minimal command and arguments to run :manpage:`strip <strip(1)>`,
+      which is used to strip symbols.
 
    :term:`SUMMARY`
       The short (72 characters or less) summary of the binary package for

-- 
2.47.0

[PATCH v3 3/6] 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.

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 | 250 ++++++++++++++++++++++++++++++---
 1 file changed, 230 insertions(+), 20 deletions(-)

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index d98721818..0516c1816 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -986,55 +986,165 @@ 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 :manpage:`archiver <ar(1)>` for the
+      build host, and its default definition is derived in part from
+      :term:`BUILD_PREFIX`::
+
+         BUILD_AR = "${BUILD_PREFIX}ar"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`AR` is set to the
+      value of this variable by default.
+
+      The :term:`BUILD_AR` variable should not be set manually, and is rarely
+      used in recipes as :term:`AR` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the :manpage:`archiver <ar(1)>` from the build
+      host at some point during the build.
+
    :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
       machine name reported by the ``uname`` command.
 
+   :term:`BUILD_AS`
+      Specifies the architecture-specific :manpage:`assembler <as(1)>` for the
+      build host, and its default definition is derived in part from
+      :term:`BUILD_PREFIX`::
+
+         BUILD_AS = "${BUILD_PREFIX}as"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`AS` is set to the
+      value of this variable by default.
+
+      The :term:`BUILD_AS` variable should not be set manually, and is rarely
+      used in recipes as :term:`AS` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the :manpage:`assembler <as(1)>` from the build
+      host at some point during the build.
+
    :term:`BUILD_AS_ARCH`
       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,
+      and its default definition is derived in part from :term:`BUILD_PREFIX`
+      and :term:`BUILD_CC_ARCH`::
+
+         BUILD_CC = "${CCACHE}${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`CC` is set to the
+      value of this variable by default.
+
+      The :term:`BUILD_CC` variable should not be set manually, and is rarely
+      used in recipes as :term:`CC` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the compiler from the build host at some point
+      during the build.
+
    :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.
 
    :term:`BUILD_CCLD`
-      Specifies the linker command to be used for the build host when the C
-      compiler is being used as the linker. By default, :term:`BUILD_CCLD`
-      points to GCC and passes as arguments the value of
-      :term:`BUILD_CC_ARCH`, assuming
-      :term:`BUILD_CC_ARCH` is set.
+      Specifies the :manpage:`linker <ld(1)>` command to be used for the build
+      host when the C compiler is being used as the linker, and its default
+      definition is derived in part from :term:`BUILD_PREFIX` and
+      :term:`BUILD_CC_ARCH`::
+
+         BUILD_CCLD = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH}"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`CCLD` is set to
+      the value of this variable by default.
+
+      The :term:`BUILD_CCLD` variable should not be set manually, and is rarely
+      used in recipes as :term:`CCLD` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the :manpage:`linker <ld(1)>` from the build host
+      at some point during the build.
 
    :term:`BUILD_CFLAGS`
       Specifies the flags to pass to the C compiler when building for the
-      build host. When building in the ``-native`` context,
+      build host. When building a :ref:`ref-classes-native` recipe,
       :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, and its default definition is derived in
+      part from :term:`BUILD_PREFIX` and :term:`BUILD_CC_ARCH`::
+
+         BUILD_CPP = "${BUILD_PREFIX}gcc ${BUILD_CC_ARCH} -E"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`CPP` is set to
+      the value of this variable by default.
+
+      The :term:`BUILD_CPP` variable should not be set manually, and is rarely
+      used in recipes as :term:`CPP` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the preprocessor from the build host at some
+      point during the build.
+
    :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,
+      and its default definition is derived in part from :term:`BUILD_PREFIX`
+      and :term:`BUILD_CC_ARCH`::
+
+         BUILD_CXX = "${CCACHE}${BUILD_PREFIX}g++ ${BUILD_CC_ARCH}"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`CXX` is set to
+      the value of this variable by default.
+
+      The :term:`BUILD_CXX` variable should not be set manually, and is rarely
+      used in recipes as :term:`CXX` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the C++ compiler from the build host at some
+      point during the build.
+
    :term:`BUILD_CXXFLAGS`
       Specifies the flags to pass to the C++ compiler when building for the
-      build host. When building in the ``-native`` context,
+      build host. When building a :ref:`ref-classes-native` recipe,
       :term:`CXXFLAGS` is set to the value of this variable
       by default.
 
    :term:`BUILD_FC`
-      Specifies the Fortran compiler command for the build host. By
-      default, :term:`BUILD_FC` points to Gfortran and passes as arguments the
-      value of :term:`BUILD_CC_ARCH`, assuming
-      :term:`BUILD_CC_ARCH` is set.
+      Specifies the Fortran compiler command for the build host, and its default
+      definition is derived in part from :term:`BUILD_PREFIX` and
+      :term:`BUILD_CC_ARCH`::
+
+         BUILD_FC = "${BUILD_PREFIX}gfortran ${BUILD_CC_ARCH}"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`FC` is set to the
+      value of this variable by default.
+
+      The :term:`BUILD_FC` variable should not be set manually, and is rarely
+      used in recipes as :term:`FC` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the Fortran compiler from the build host at some
+      point during the build.
 
    :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.
+      Specifies the linker command for the build host, and its default
+      definition is derived in part from :term:`BUILD_PREFIX` and
+      :term:`BUILD_LD_ARCH`::
+
+         BUILD_LD = "${BUILD_PREFIX}ld ${BUILD_LD_ARCH}"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`LD` is set to the
+      value of this variable by default.
+
+      The :term:`BUILD_LD` variable should not be set manually, and is rarely
+      used in recipes as :term:`LD` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the linker from the build host at some point
+      during the build.
 
    :term:`BUILD_LD_ARCH`
       Specifies architecture-specific linker flags for the build host. By
@@ -1042,10 +1152,58 @@ system and gives an overview of their function and contents.
 
    :term:`BUILD_LDFLAGS`
       Specifies the flags to pass to the linker when building for the build
-      host. When building in the ``-native`` context,
+      host. When building a :ref:`ref-classes-native` recipe,
       :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, and its default definition is derived in part
+      from :term:`BUILD_PREFIX`::
+
+         BUILD_NM = "${BUILD_PREFIX}nm"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`NM` is set to the
+      value of this variable by default.
+
+      The :term:`BUILD_NM` variable should not be set manually, and is rarely
+      used in recipes as :term:`NM` contains the appropriate value depending on
+      the context (native or target recipes). Exception be made for target
+      recipes that need to use the utility from the build host at some point
+      during the build.
+
+   :term:`BUILD_OBJCOPY`
+      Specifies the architecture-specific utility to copy object files for the
+      build host, and its default definition is derived in part from
+      :term:`BUILD_PREFIX`::
+
+         BUILD_OBJCOPY = "${BUILD_PREFIX}objcopy"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`OBJCOPY` is set
+      to the value of this variable by default.
+
+      The :term:`BUILD_OBJCOPY` variable should not be set manually, and is
+      rarely used in recipes as :term:`OBJCOPY` contains the appropriate value
+      depending on the context (native or target recipes). Exception be made for
+      target recipes that need to use the utility from the build host at some
+      point during the build.
+
+   :term:`BUILD_OBJDUMP`
+      Specifies the architecture-specific utility to display object files
+      information for the build host, and its default definition is derived in
+      part from :term:`BUILD_PREFIX`::
+
+         BUILD_OBJDUMP = "${BUILD_PREFIX}objdump"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`OBJDUMP` is set
+      to the value of this variable by default.
+
+      The :term:`BUILD_OBJDUMP` variable should not be set manually, and is
+      rarely used in recipes as :term:`OBJDUMP` contains the appropriate value
+      depending on the context (native or target recipes). Exception be made for
+      target recipes that need to use the utility from the build host at some
+      point during the build.
+
    :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
@@ -1066,11 +1224,53 @@ 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, and its default definition is derived in part
+      from :term:`BUILD_PREFIX`::
+
+         BUILD_RANLIB = "${BUILD_PREFIX}ranlib -D"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`RANLIB` is set to
+      the value of this variable by default.
+
+      The :term:`BUILD_RANLIB` variable should not be set manually, and is
+      rarely used in recipes as :term:`RANLIB` contains the appropriate value
+      depending on the context (native or target recipes). Exception be made for
+      target recipes that need to use the utility from the build host at some
+      point during the build.
+
+   :term:`BUILD_READELF`
+      Specifies the architecture-specific utility to display information about
+      ELF files for the build host, and its default definition is derived in
+      part from :term:`BUILD_PREFIX`::
+
+         BUILD_READELF = "${BUILD_PREFIX}readelf"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`READELF` is set
+      to the value of this variable by default.
+
+      The :term:`BUILD_READELF` variable should not be set manually, and is
+      rarely used in recipes as :term:`READELF` contains the appropriate value
+      depending on the context (native or target recipes). Exception be made for
+      target recipes that need to use the utility from the build host at some
+      point during the build.
+
    :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``.
+      Specifies the command to be used to strip debugging symbols from binaries
+      produced for the build host, and its default definition is derived in part
+      from :term:`BUILD_PREFIX`::
+
+         BUILD_STRIP = "${BUILD_PREFIX}strip"
+
+      When building a :ref:`ref-classes-native` recipe, :term:`STRIP` is set to
+      the value of this variable by default.
+
+      The :term:`BUILD_STRIP` variable should not be set manually, and is
+      rarely used in recipes as :term:`STRIP` contains the appropriate value
+      depending on the context (native or target recipes). Exception be made for
+      target recipes that need to use the utility from the build host at some
+      point during the build.
 
    :term:`BUILD_SYS`
       Specifies the system, including the architecture and the operating
@@ -1275,6 +1475,10 @@ system and gives an overview of their function and contents.
    :term:`CC`
       The minimal command and arguments used to run the C compiler.
 
+   :term:`CCLD`
+      The minimal command and arguments used to run the linker when the C
+      compiler is being used as the linker.
+
    :term:`CFLAGS`
       Specifies the flags to pass to the C compiler. This variable is
       exported to an environment variable and thus made visible to the
@@ -2819,6 +3023,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`.
@@ -7313,6 +7520,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 :manpage:`readelf <readelf(1)>`.
+
    :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 v3 4/6] 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.

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
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 0516c1816..4cb416bd0 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -7920,11 +7920,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`
@@ -8006,6 +8016,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 v3 5/6] 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.

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
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 4cb416bd0..c3ed1a106 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3673,6 +3673,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.
@@ -3689,6 +3703,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 v3 6/6] 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.

Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de>
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 c3ed1a106..65dac9aa9 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -3700,8 +3700,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 v3 1/6] documentation/conf.py: define a manpage url

[Mark Hatle]

I'm going to be a bit pedantic below, I'm not sure it matters at this point but 
I want to clarify one thing.

On 3/27/25 4:07 AM, Antonin Godard via lists.yoctoproject.org wrote:
> By defining the manpages_url we can use the :manpage: role in the
> documentation for providing links to manpages. See:
> https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
> 
> Replace existing manpages links to use this role.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/conf.py                      | 3 +++
>   documentation/overview-manual/concepts.rst | 2 +-
>   documentation/overview-manual/yp-intro.rst | 2 +-
>   documentation/ref-manual/variables.rst     | 4 ++--
>   4 files changed, 7 insertions(+), 4 deletions(-)
> 
> diff --git a/documentation/conf.py b/documentation/conf.py
> index 477e75112a..0352bbef20 100644
> --- a/documentation/conf.py
> +++ b/documentation/conf.py
> @@ -111,6 +111,9 @@ extlinks = {
>       'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
>   }
>   
> +# To able to use :manpage:`<something>` in the docs.
> +manpages_url = 'https://manpages.debian.org/{path}'
> +
>   # Intersphinx config to use cross reference with BitBake user manual
>   intersphinx_mapping = {
>       'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None)
> diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
> index e4d806f98f..416c28f0d9 100644
> --- a/documentation/overview-manual/concepts.rst
> +++ b/documentation/overview-manual/concepts.rst
> @@ -2204,7 +2204,7 @@ require root privileges, the fact that some earlier steps ran in a fake
>   root environment does not cause problems.
>   
>   The capability to run tasks in a fake root environment is known as
> -"`fakeroot <http://man.he.net/man1/fakeroot>`__", which is derived from
> +":manpage:`fakeroot <fakeroot(1)>`", which is derived from
>   the BitBake keyword/variable flag that requests a fake root environment
>   for a task.
>   
> diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
> index 4a27e12e01..11e6d99e32 100644
> --- a/documentation/overview-manual/yp-intro.rst
> +++ b/documentation/overview-manual/yp-intro.rst
> @@ -400,7 +400,7 @@ Yocto Project:
>      Autobuilder :doc:`here </test-manual/understand-autobuilder>`.
>   
>   -  *Pseudo:* Pseudo is the Yocto Project implementation of
> -   `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run
> +   :manpage:`fakeroot <fakeroot(1)>`, which is used to run
>      commands in an environment that seemingly has root privileges.


psuedo is an implementation of three separate items:

fakeroot
fakechroot
fakepasswd (which was never a debian tool or widely used - it emulates 
/etc/passwd and /etc/group that do not match the running system)

--Mark

>      During a build, it can be necessary to perform operations that
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 41bda5d0d6..4e675b6bfb 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4514,8 +4514,8 @@ system and gives an overview of their function and contents.
>   
>         The value in :term:`INITSCRIPT_PARAMS` is passed through to the
>         ``update-rc.d`` command. For more information on valid parameters,
> -      please see the ``update-rc.d`` manual page at
> -      https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
> +      please see the ``update-rc.d`` manual page at :manpage:`update-rc.d
> +      <update-rc.d(8)>`.
>   
>      :term:`INSANE_SKIP`
>         Specifies the QA checks to skip for a specific package within a
> 
> 
> 
> -=-=-=-=-=-=-=-=-=-=-=-
> Links: You receive all messages sent to this group.
> View/Reply Online (#6647): https://lists.yoctoproject.org/g/docs/message/6647
> Mute This Topic: https://lists.yoctoproject.org/mt/111933087/3616948
> Group Owner: docs+owner@lists.yoctoproject.org
> Unsubscribe: https://lists.yoctoproject.org/g/docs/unsub [mark.hatle@kernel.crashing.org]
> -=-=-=-=-=-=-=-=-=-=-=-
> 

Re: [docs] [PATCH v3 1/6] documentation/conf.py: define a manpage url

[Quentin Schulz]

Hi Antonin,

On 3/27/25 10:07 AM, Antonin Godard via lists.yoctoproject.org wrote:
> By defining the manpages_url we can use the :manpage: role in the
> documentation for providing links to manpages. See:
> https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
> 
> Replace existing manpages links to use this role.
> 
> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
> ---
>   documentation/conf.py                      | 3 +++
>   documentation/overview-manual/concepts.rst | 2 +-
>   documentation/overview-manual/yp-intro.rst | 2 +-
>   documentation/ref-manual/variables.rst     | 4 ++--
>   4 files changed, 7 insertions(+), 4 deletions(-)
> 
> diff --git a/documentation/conf.py b/documentation/conf.py
> index 477e75112a..0352bbef20 100644
> --- a/documentation/conf.py
> +++ b/documentation/conf.py
> @@ -111,6 +111,9 @@ extlinks = {
>       'wikipedia': ('https://en.wikipedia.org/wiki/%25s', None),
>   }
>   
> +# To able to use :manpage:`<something>` in the docs.

s/To able/To be able/

> +manpages_url = 'https://manpages.debian.org/{path}'
> +
>   # Intersphinx config to use cross reference with BitBake user manual
>   intersphinx_mapping = {
>       'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None)
> diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
> index e4d806f98f..416c28f0d9 100644
> --- a/documentation/overview-manual/concepts.rst
> +++ b/documentation/overview-manual/concepts.rst
> @@ -2204,7 +2204,7 @@ require root privileges, the fact that some earlier steps ran in a fake
>   root environment does not cause problems.
>   
>   The capability to run tasks in a fake root environment is known as
> -"`fakeroot <http://man.he.net/man1/fakeroot>`__", which is derived from
> +":manpage:`fakeroot <fakeroot(1)>`", which is derived from
>   the BitBake keyword/variable flag that requests a fake root environment
>   for a task.
>   
> diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
> index 4a27e12e01..11e6d99e32 100644
> --- a/documentation/overview-manual/yp-intro.rst
> +++ b/documentation/overview-manual/yp-intro.rst
> @@ -400,7 +400,7 @@ Yocto Project:
>      Autobuilder :doc:`here </test-manual/understand-autobuilder>`.
>   
>   -  *Pseudo:* Pseudo is the Yocto Project implementation of
> -   `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run
> +   :manpage:`fakeroot <fakeroot(1)>`, which is used to run
>      commands in an environment that seemingly has root privileges.
>   
>      During a build, it can be necessary to perform operations that
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index 41bda5d0d6..4e675b6bfb 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -4514,8 +4514,8 @@ system and gives an overview of their function and contents.
>   
>         The value in :term:`INITSCRIPT_PARAMS` is passed through to the
>         ``update-rc.d`` command. For more information on valid parameters,
> -      please see the ``update-rc.d`` manual page at
> -      https://manpages.debian.org/buster/init-system-helpers/update-rc.d.8.en.html
> +      please see the ``update-rc.d`` manual page at :manpage:`update-rc.d
> +      <update-rc.d(8)>`.
>   

This will render oddly no? I haven't compiled it but I assume something like

"""
please see the update-rc.d manual page at update-rc.d.
"""
?

If that's the case, maybe simply have:

:manpage:`the update-rc.d manual page<update-rc.d(8)>`.

? What do you think?

Please consider having a separate patch (not necessarily in this series) 
addressing Mark's feedback on fakeroot.

Looks good to me otherwise, with some change for the update-rc.d paragraph:

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

Thanks!
Quentin

Re: [docs] [PATCH v3 2/6] ref-manual/variables.rst: add manpage links for toolchain variables

[Quentin Schulz]

Hi Antonin,

On 3/27/25 10:07 AM, Antonin Godard via lists.yoctoproject.org wrote:
> Use the :manpage: role to provide links to common toolchain utilities.
> 

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

Thanks!
Quentin

Re: [docs] [PATCH v3 3/6] ref-manual/variables.rst: add missing documentation for BUILD_* variables

[Quentin Schulz]

Hi Antonin,

On 3/27/25 10:07 AM, 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.
> 
> 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 | 250 ++++++++++++++++++++++++++++++---
>   1 file changed, 230 insertions(+), 20 deletions(-)
> 
> diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
> index d98721818..0516c1816 100644
> --- a/documentation/ref-manual/variables.rst
> +++ b/documentation/ref-manual/variables.rst
> @@ -986,55 +986,165 @@ 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 :manpage:`archiver <ar(1)>` for the
> +      build host, and its default definition is derived in part from
> +      :term:`BUILD_PREFIX`::
> +
> +         BUILD_AR = "${BUILD_PREFIX}ar"
> +
> +      When building a :ref:`ref-classes-native` recipe, :term:`AR` is set to the
> +      value of this variable by default.
> +
> +      The :term:`BUILD_AR` variable should not be set manually, and is rarely
> +      used in recipes as :term:`AR` contains the appropriate value depending on
> +      the context (native or target recipes). Exception be made for target
> +      recipes that need to use the :manpage:`archiver <ar(1)>` from the build
> +      host at some point during the build.
> +
>      :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
>         machine name reported by the ``uname`` command.
>   
> +   :term:`BUILD_AS`
> +      Specifies the architecture-specific :manpage:`assembler <as(1)>` for the
> +      build host, and its default definition is derived in part from
> +      :term:`BUILD_PREFIX`::
> +
> +         BUILD_AS = "${BUILD_PREFIX}as"
> +

It actually is

${BUILD_PREFIX}as ${BUILD_AS_ARCH}

With that change:

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

Thanks!
Quentin

Re: [docs] [PATCH v3 1/6] documentation/conf.py: define a manpage url

[Antonin Godard]

Hi Mark,

On Thu Mar 27, 2025 at 4:35 PM CET, Mark Hatle wrote:
> I'm going to be a bit pedantic below, I'm not sure it matters at this point but 
> I want to clarify one thing.
>
> On 3/27/25 4:07 AM, Antonin Godard via lists.yoctoproject.org wrote:
>> By defining the manpages_url we can use the :manpage: role in the
>> documentation for providing links to manpages. See:
>> https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-manpages_url
>> 
>> Replace existing manpages links to use this role.
>> 
>> Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
>> ---
>>   documentation/conf.py                      | 3 +++
>>   documentation/overview-manual/concepts.rst | 2 +-
>>   documentation/overview-manual/yp-intro.rst | 2 +-
>>   documentation/ref-manual/variables.rst     | 4 ++--
>>   4 files changed, 7 insertions(+), 4 deletions(-)
>> 
>> diff --git a/documentation/conf.py b/documentation/conf.py
>> index 477e75112a..0352bbef20 100644
>> --- a/documentation/conf.py
>> +++ b/documentation/conf.py
>> @@ -111,6 +111,9 @@ extlinks = {
>>       'wikipedia': ('https://en.wikipedia.org/wiki/%s', None),
>>   }
>>   
>> +# To able to use :manpage:`<something>` in the docs.
>> +manpages_url = 'https://manpages.debian.org/{path}'
>> +
>>   # Intersphinx config to use cross reference with BitBake user manual
>>   intersphinx_mapping = {
>>       'bitbake': ('https://docs.yoctoproject.org/bitbake/' + bitbake_version, None)
>> diff --git a/documentation/overview-manual/concepts.rst b/documentation/overview-manual/concepts.rst
>> index e4d806f98f..416c28f0d9 100644
>> --- a/documentation/overview-manual/concepts.rst
>> +++ b/documentation/overview-manual/concepts.rst
>> @@ -2204,7 +2204,7 @@ require root privileges, the fact that some earlier steps ran in a fake
>>   root environment does not cause problems.
>>   
>>   The capability to run tasks in a fake root environment is known as
>> -"`fakeroot <http://man.he.net/man1/fakeroot>`__", which is derived from
>> +":manpage:`fakeroot <fakeroot(1)>`", which is derived from
>>   the BitBake keyword/variable flag that requests a fake root environment
>>   for a task.
>>   
>> diff --git a/documentation/overview-manual/yp-intro.rst b/documentation/overview-manual/yp-intro.rst
>> index 4a27e12e01..11e6d99e32 100644
>> --- a/documentation/overview-manual/yp-intro.rst
>> +++ b/documentation/overview-manual/yp-intro.rst
>> @@ -400,7 +400,7 @@ Yocto Project:
>>      Autobuilder :doc:`here </test-manual/understand-autobuilder>`.
>>   
>>   -  *Pseudo:* Pseudo is the Yocto Project implementation of
>> -   `fakeroot <http://man.he.net/man1/fakeroot>`__, which is used to run
>> +   :manpage:`fakeroot <fakeroot(1)>`, which is used to run
>>      commands in an environment that seemingly has root privileges.
>
>
> psuedo is an implementation of three separate items:
>
> fakeroot
> fakechroot
> fakepasswd (which was never a debian tool or widely used - it emulates 
> /etc/passwd and /etc/group that do not match the running system)

Thanks for the details. I will try clarifying that later in a separate patch.


Antonin

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