| Message ID | 20251021182834.11403-2-adam.blank.g@gmail.com |
|---|---|
| State | New |
| Headers | show |
| Series | Describe AUTOREV and SRCREV_FORMAT roles in fetching | expand |
On Tue, 21 Oct 2025 at 20:29, Adam Blank via lists.openembedded.org <adam.blank.g=gmail.com@lists.openembedded.org> wrote: > --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst > +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst > @@ -1697,3 +1697,7 @@ overview of their function and contents. > :term:`TOPDIR` > Points to the build directory. BitBake automatically sets this > variable. > + > + :term:`UNPACKDIR` > + The directory into which recipe's downloads are unpacked during its > + build process. Adding this to bitbake manual is incorrect. UNPACKDIR is specific to openembedded-core (defined in bitbake.conf and used in base.bbclass if memory serves) and is not used anywhere in bitbake. UNPACKDIR is used in bitbake manual in examples of how to use the fecher, but this doesn't mean it is a part of bitbake, and it is already documented in yocto's manual in ref-manual/variables.rst. Alex
Yes, of course you are right. That being said, I must say it is truly difficult to grasp the convention used in Bitbake's manual. One time an oe-core class is referenced by name in a note, or an example, the other time the same thing is explicitly discouraged :-) One time an abstract, non oe-core example is requested, the other time a specific oe-core variable is used, while an abstract one would fit just as well. Thanks, Adam On Tue, 21 Oct 2025, 20:52 Alexander Kanavin, <alex.kanavin@gmail.com> wrote: > On Tue, 21 Oct 2025 at 20:29, Adam Blank via lists.openembedded.org > <adam.blank.g=gmail.com@lists.openembedded.org> wrote: > > > --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst > > +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst > > @@ -1697,3 +1697,7 @@ overview of their function and contents. > > :term:`TOPDIR` > > Points to the build directory. BitBake automatically sets this > > variable. > > + > > + :term:`UNPACKDIR` > > + The directory into which recipe's downloads are unpacked during > its > > + build process. > > Adding this to bitbake manual is incorrect. UNPACKDIR is specific to > openembedded-core (defined in bitbake.conf and used in base.bbclass if > memory serves) and is not used anywhere in bitbake. > > UNPACKDIR is used in bitbake manual in examples of how to use the > fecher, but this doesn't mean it is a part of bitbake, and it is > already documented in yocto's manual in ref-manual/variables.rst. > > Alex >
On Tue, 21 Oct 2025 at 20:59, Adam Blank <adam.blank.g@gmail.com> wrote:
> Yes, of course you are right. That being said, I must say it is truly difficult to grasp the convention used in Bitbake's manual. One time an oe-core class is referenced by name in a note, or an example, the other time the same thing is explicitly discouraged :-) One time an abstract, non oe-core example is requested, the other time a specific oe-core variable is used, while an abstract one would fit just as well.
Yes, the documentation is not perfect. Neverthless, bitbake docs
should describe only what is implemented in bitbake itself, and strive
to use abstract examples.
Alex
Heh :-) Now I would be tempted to change this patch, so that it merely improves this "non-compliant" example, but I have a gut feeling, that "as long as nobody complains about it, there's no reason to touch it". Thanks, Adam On Tue, 21 Oct 2025, 21:13 Alexander Kanavin, <alex.kanavin@gmail.com> wrote: > On Tue, 21 Oct 2025 at 20:59, Adam Blank <adam.blank.g@gmail.com> wrote: > > Yes, of course you are right. That being said, I must say it is truly > difficult to grasp the convention used in Bitbake's manual. One time an > oe-core class is referenced by name in a note, or an example, the other > time the same thing is explicitly discouraged :-) One time an abstract, non > oe-core example is requested, the other time a specific oe-core variable is > used, while an abstract one would fit just as well. > > Yes, the documentation is not perfect. Neverthless, bitbake docs > should describe only what is implemented in bitbake itself, and strive > to use abstract examples. > > Alex >
diff --git a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst index f357765b7..d10d2f611 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-fetching.rst @@ -42,7 +42,7 @@ The instantiation of the fetch class is usually followed by:: rootdir = l.getVar('UNPACKDIR') fetcher.unpack(rootdir) -This code unpacks the downloaded files to the specified by ``UNPACKDIR``. +This code unpacks the downloaded files to the specified :term:`UNPACKDIR`. .. note:: @@ -51,7 +51,7 @@ This code unpacks the downloaded files to the specified by ``UNPACKDIR``. examine the OpenEmbedded class file ``base.bbclass`` . -The :term:`SRC_URI` and ``UNPACKDIR`` variables are not hardcoded into the +The :term:`SRC_URI` and :term:`UNPACKDIR` variables are not hardcoded into the fetcher, since those fetcher methods can be (and are) called with different variable names. In OpenEmbedded for example, the shared state (sstate) code uses the fetch module to fetch the sstate files. @@ -606,7 +606,9 @@ password, and fetches a Revision based on a Label:: .. note:: - You should always set S to "${UNPACKDIR}/p4" in your recipe. + Your recipe should always set S as shown in the following example:: + + S = "${UNPACKDIR}/p4" By default, the fetcher strips the depot location from the local file paths. In the above example, the content of ``example-depot/main/source/`` will be placed diff --git a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst index 810f88689..e50b71380 100644 --- a/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst +++ b/doc/bitbake-user-manual/bitbake-user-manual-ref-variables.rst @@ -1697,3 +1697,7 @@ overview of their function and contents. :term:`TOPDIR` Points to the build directory. BitBake automatically sets this variable. + + :term:`UNPACKDIR` + The directory into which recipe's downloads are unpacked during its + build process.
Signed-off-by: Adam Blank <adam.blank.g@gmail.com> --- doc/bitbake-user-manual/bitbake-user-manual-fetching.rst | 8 +++++--- .../bitbake-user-manual-ref-variables.rst | 4 ++++ 2 files changed, 9 insertions(+), 3 deletions(-)