[PATCH] ref-manual: correctly document the difference between auto.conf and newly added toolcfg.conf

[PATCH] ref-manual: correctly document the difference between auto.conf and newly added toolcfg.conf

[Alexander Kanavin]

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
---
 documentation/ref-manual/fragments.rst |  4 ++--
 documentation/ref-manual/structure.rst | 15 ++++++++++++---
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/documentation/ref-manual/fragments.rst b/documentation/ref-manual/fragments.rst
index c0118876c..7fd08656d 100644
--- a/documentation/ref-manual/fragments.rst
+++ b/documentation/ref-manual/fragments.rst
@@ -94,7 +94,7 @@ Note that in this case, the fragment will be defined twice in
 :term:`OE_FRAGMENTS`, and the last value is taken into account:
 
 .. code-block::
-   :caption: build/conf/auto.conf
+   :caption: build/conf/toolcfg.conf
 
    OE_FRAGMENTS += " ... machine/qemuarm64 machine/qemux86-64"
 
@@ -103,7 +103,7 @@ In the above example, the value of :term:`MACHINE` is thus equal to
 
 When a fragment is enabled with :ref:`ref-bitbake-config-build-enable-fragment`,
 its name is automatically appended to the :term:`OE_FRAGMENTS` variable in
-:ref:`structure-build-conf-auto.conf`.
+:ref:`structure-build-conf-toolcfg.conf`.
 
 .. note::
 
diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
index 1aaafcf79..0ef51fa4f 100644
--- a/documentation/ref-manual/structure.rst
+++ b/documentation/ref-manual/structure.rst
@@ -356,15 +356,24 @@ This configuration file is generated by :doc:`bblock </dev-manual/bblock>` and
 contains the signatures locked by ``bblock``. By default, it does not exist
 and will be created upon the first invocation of ``bblock``.
 
-.. _structure-build-conf-auto.conf:
+.. _structure-build-conf-toolcfg.conf:
 
-``build/conf/auto.conf``
-------------------------
+``build/conf/toolcfg.conf``
+---------------------------
 
 This file contains configuration variables that are automatically modified by
 tools such as :oe_git:`bitbake-config-build </bitbake/tree/bin/bitbake-config-build>`.
 This file should not be modified manually.
 
+.. _structure-build-conf-auto.conf:
+
+``build/conf/auto.conf``
+------------------------
+
+This file is intended for use by continuous integration environments, such as the
+Yocto Project's autobuilder. It should not be created or modified when running
+local builds.
+
 .. _structure-build-downloads:
 
 ``build/downloads/``
-- 
2.39.5

Re: [docs] [PATCH] ref-manual: correctly document the difference between auto.conf and newly added toolcfg.conf

[Antonin Godard]

On Mon Oct 6, 2025 at 3:47 PM CEST, Alexander Kanavin via lists.yoctoproject.org wrote:
> Signed-off-by: Alexander Kanavin <alex@linutronix.de>
> ---
>  documentation/ref-manual/fragments.rst |  4 ++--
>  documentation/ref-manual/structure.rst | 15 ++++++++++++---
>  2 files changed, 14 insertions(+), 5 deletions(-)
>
> diff --git a/documentation/ref-manual/fragments.rst b/documentation/ref-manual/fragments.rst
> index c0118876c..7fd08656d 100644
> --- a/documentation/ref-manual/fragments.rst
> +++ b/documentation/ref-manual/fragments.rst
> @@ -94,7 +94,7 @@ Note that in this case, the fragment will be defined twice in
>  :term:`OE_FRAGMENTS`, and the last value is taken into account:
>  
>  .. code-block::
> -   :caption: build/conf/auto.conf
> +   :caption: build/conf/toolcfg.conf
>  
>     OE_FRAGMENTS += " ... machine/qemuarm64 machine/qemux86-64"
>  
> @@ -103,7 +103,7 @@ In the above example, the value of :term:`MACHINE` is thus equal to
>  
>  When a fragment is enabled with :ref:`ref-bitbake-config-build-enable-fragment`,
>  its name is automatically appended to the :term:`OE_FRAGMENTS` variable in
> -:ref:`structure-build-conf-auto.conf`.
> +:ref:`structure-build-conf-toolcfg.conf`.
>  
>  .. note::
>  
> diff --git a/documentation/ref-manual/structure.rst b/documentation/ref-manual/structure.rst
> index 1aaafcf79..0ef51fa4f 100644
> --- a/documentation/ref-manual/structure.rst
> +++ b/documentation/ref-manual/structure.rst
> @@ -356,15 +356,24 @@ This configuration file is generated by :doc:`bblock </dev-manual/bblock>` and
>  contains the signatures locked by ``bblock``. By default, it does not exist
>  and will be created upon the first invocation of ``bblock``.
>  
> -.. _structure-build-conf-auto.conf:
> +.. _structure-build-conf-toolcfg.conf:
>  
> -``build/conf/auto.conf``
> -------------------------
> +``build/conf/toolcfg.conf``
> +---------------------------
>  
>  This file contains configuration variables that are automatically modified by
>  tools such as :oe_git:`bitbake-config-build </bitbake/tree/bin/bitbake-config-build>`.
>  This file should not be modified manually.
>  
> +.. _structure-build-conf-auto.conf:
> +
> +``build/conf/auto.conf``
> +------------------------
> +
> +This file is intended for use by continuous integration environments, such as the
> +Yocto Project's autobuilder. It should not be created or modified when running
> +local builds.
> +
>  .. _structure-build-downloads:
>  
>  ``build/downloads/``

We also need to update the auto.conf reference in the fragments documentation.
Do you want to send a patch?

But otherwise this change looks good to me, thank you!

Antonin

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

Re: [docs] [PATCH] ref-manual: correctly document the difference between auto.conf and newly added toolcfg.conf

[Alexander Kanavin]

On Mon, 6 Oct 2025 at 18:14, Antonin Godard <antonin.godard@bootlin.com> wrote:

> We also need to update the auto.conf reference in the fragments documentation.
> Do you want to send a patch?

I am unable to find any other auto.conf references, other than the
ones the patch is fixing. Can you point me to them please?

Alex

Re: [docs] [PATCH] ref-manual: correctly document the difference between auto.conf and newly added toolcfg.conf

[Antonin Godard]

On Mon Oct 6, 2025 at 6:27 PM CEST, Alexander Kanavin via lists.yoctoproject.org wrote:
> On Mon, 6 Oct 2025 at 18:14, Antonin Godard <antonin.godard@bootlin.com> wrote:
>
>> We also need to update the auto.conf reference in the fragments documentation.
>> Do you want to send a patch?
>
> I am unable to find any other auto.conf references, other than the
> ones the patch is fixing. Can you point me to them please?

Hi Alex,

Indeed, for some reason (tired probably), I missed this part of your patch.
Sorry about that.

The patch looks good to me.

Thanks,
Antonin

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

Re: [PATCH] ref-manual: correctly document the difference between auto.conf and newly added toolcfg.conf

[Antonin Godard]

Applied, thanks!

[1/1] ref-manual: correctly document the difference between auto.conf and newly added toolcfg.conf
      commit: f23b93594dbe7e5df9ec55371e4aab4b7b8c50b9

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