diff mbox series

dev-manual/new-recipe.rst: rework Unpacking Code section

Message ID 20260416-unpacking-code-v1-1-19bc7d4fd7ee@bootlin.com
State Under Review
Headers show
Series dev-manual/new-recipe.rst: rework Unpacking Code section | expand

Commit Message

Antonin Godard April 16, 2026, 2:03 p.m. UTC 
There were recent changes to how Bitbake/OECore unpacks code.
Importantly we no longer need to set S when fetching with the Git or
other fetchers. Rework this section and mention UNPACKDIR/BP.

[YOCTO #16049]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/dev-manual/new-recipe.rst          | 24 +++++++++++++-----------
 documentation/migration-guides/migration-5.3.rst |  2 ++
 2 files changed, 15 insertions(+), 11 deletions(-)


---
base-commit: 560bc33c0c2ecd60d68ba06a2edff8c25b9a3f90
change-id: 20260416-unpacking-code-acfdba02fbc8
diff mbox series

Patch

diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst
index 5e9498afc..82c7ff4b2 100644
--- a/documentation/dev-manual/new-recipe.rst
+++ b/documentation/dev-manual/new-recipe.rst
@@ -408,17 +408,19 @@  During the build, the
 the source with ``${``\ :term:`S`\ ``}``
 pointing to where it is unpacked.
 
-If you are fetching your source files from an upstream source archived
-tarball and the tarball's internal structure matches the common
-convention of a top-level subdirectory named
-``${``\ :term:`BPN`\ ``}-${``\ :term:`PV`\ ``}``,
-then you do not need to set :term:`S`. However, if :term:`SRC_URI` specifies to
-fetch source from an archive that does not use this convention, or from
-an SCM like Git or Subversion, your recipe needs to define :term:`S`.
-
-If processing your recipe using BitBake successfully unpacks the source
-files, you need to be sure that the directory pointed to by ``${S}``
-matches the structure of the source.
+By default, the value of ``${``\ :term:`S`\ ``}`` is already set to where the
+:term:`OpenEmbedded Build System` will unpack the source code, by using the
+value of :term:`UNPACKDIR` and :term:`BP`.
+
+You typically don't need to set :term:`S` explicitly. If processing your recipe
+using BitBake successfully unpacks the source files, you can verify that the
+directory pointed to by ``${S}`` is the root of your source code.
+
+.. note::
+
+   It used to be that when fetching with Git, recipes should explicitly set
+   :term:`S` to ``${WORKDIR}/git``: this is no longer the case. See
+   :ref:`ref-migration-5-3-s-workdir-git` for more information.
 
 Patching Code
 =============
diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
index 464006aaa..8746141cd 100644
--- a/documentation/migration-guides/migration-5.3.rst
+++ b/documentation/migration-guides/migration-5.3.rst
@@ -54,6 +54,8 @@  changed to::
 
    S = "${UNPACKDIR}/something"
 
+.. _ref-migration-5-3-s-workdir-git:
+
 ``S = ${WORKDIR}/git`` and ``S = ${UNPACKDIR}/git`` should be removed
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^