[PATCH 0/2] migration-guides/migration-5.3.rst: add guidance for breaking WORKDIR changes

[PATCH 0/2] migration-guides/migration-5.3.rst: add guidance for breaking WORKDIR changes

[Antonin Godard]

Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
Alexander Kanavin (1):
      migration-guides/migration-5.3.rst: add guidance for breaking WORKDIR changes

Antonin Godard (1):
      ref-manual/variables.rst: document BB_GIT_DEFAULT_DESTSUFFIX

 documentation/migration-guides/migration-5.3.rst | 50 ++++++++++++++++++++++++
 documentation/ref-manual/variables.rst           |  7 ++++
 2 files changed, 57 insertions(+)
---
base-commit: 8a64ef83efcd5df70706a651751c8198f7c27c13
change-id: 20250624-migration-5-3-unpackdir-9e2e7bcfee1d

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

[PATCH 1/2] ref-manual/variables.rst: document BB_GIT_DEFAULT_DESTSUFFIX

[Antonin Godard]

Recently added in BitBake with 378db0fdd95f ("fetch2/git: allow
overriding default unpack directory with a variable").

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

diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 0a748c918..ae6402220 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -560,6 +560,13 @@ system and gives an overview of their function and contents.
    :term:`BB_GENERATE_SHALLOW_TARBALLS`
       See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual.
 
+   :term:`BB_GIT_DEFAULT_DESTSUFFIX`
+      See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual.
+
+      In :term:`OpenEmbedded-Core (OE-Core)`, this variable is set to
+      :term:`BP` by default in :oe_git:`bitbake.conf
+      </openembedded-core/tree/meta/conf/bitbake.conf>`.
+
    :term:`BB_GIT_SHALLOW`
       See :term:`bitbake:BB_GIT_SHALLOW` in the BitBake manual.
 

-- 
2.49.0

Re: [docs] [PATCH 1/2] ref-manual/variables.rst: document BB_GIT_DEFAULT_DESTSUFFIX

[Alexander Kanavin]

On Tue, 24 Jun 2025 at 11:55, Antonin Godard via
lists.yoctoproject.org
<antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
> +   :term:`BB_GIT_DEFAULT_DESTSUFFIX`
> +      See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual.

Incorrect copy-paste.

Alex

Re: [docs] [PATCH 1/2] ref-manual/variables.rst: document BB_GIT_DEFAULT_DESTSUFFIX

[Antonin Godard]

On Tue Jun 24, 2025 at 12:10 PM CEST, Alexander Kanavin wrote:
> On Tue, 24 Jun 2025 at 11:55, Antonin Godard via
> lists.yoctoproject.org
> <antonin.godard=bootlin.com@lists.yoctoproject.org> wrote:
>> +   :term:`BB_GIT_DEFAULT_DESTSUFFIX`
>> +      See :term:`bitbake:BB_GENERATE_SHALLOW_TARBALLS` in the BitBake manual.
>
> Incorrect copy-paste.

Ha, well spotted thanks.

Antonin

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

[PATCH 2/2] migration-guides/migration-5.3.rst: add guidance for breaking WORKDIR changes

[Antonin Godard]

From: Alexander Kanavin <alex@linutronix.de>

Signed-off-by: Alexander Kanavin <alex@linutronix.de>
Signed-off-by: Antonin Godard <antonin.godard@bootlin.com>
---
 documentation/migration-guides/migration-5.3.rst | 50 ++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/documentation/migration-guides/migration-5.3.rst b/documentation/migration-guides/migration-5.3.rst
index 09095c7bb..4d2e1763c 100644
--- a/documentation/migration-guides/migration-5.3.rst
+++ b/documentation/migration-guides/migration-5.3.rst
@@ -14,6 +14,56 @@ Migration notes for |yocto-ver| (|yocto-codename|)
 This section provides migration information for moving to the Yocto
 Project |yocto-ver| Release (codename "|yocto-codename|") from the prior release.
 
+:term:`WORKDIR` changes
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``S = ${WORKDIR}/something`` no longer supported
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If a recipe has :term:`S` set to be ``${``\ :term:`WORKDIR`\ ``}/something``,
+this is no longer supported, and an error will be issued. The recipe should be
+changed to::
+
+   S = "${UNPACKDIR}/something"
+
+``S = ${WORKDIR}/git`` and ``S = ${UNPACKDIR}/git`` should be removed
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Git fetcher now unpacks into the :term:`BB_GIT_DEFAULT_DESTSUFFIX` directory
+rather than the ``git/`` directory under :term:`UNPACKDIR`.
+:term:`BB_GIT_DEFAULT_DESTSUFFIX` is set in :term:`OpenEmbedded-Core
+(OE-Core)`'s :oe_git:`bitbake.conf
+</openembedded-core/tree/meta/conf/bitbake.conf>` to :term:`BP`.
+
+This location matches the default value of :term:`S` set by bitbake.conf, so :term:`S`
+setting in recipes can and should be removed.
+
+Note that when :term:`S` is set to a subdirectory of the git checkout, then it
+should be instead adjusted according to the previous point::
+
+   S = "${UNPACKDIR}/${BP}/something"
+
+Note that "git" as the source checkout location can be hardcoded
+in other places in recipes; when it's in :term:`SRC_URI`, replace with
+:term:`BB_GIT_DEFAULT_DESTSUFFIX`, otherwise replace with :term:`BP`.
+
+How to make those adjustments without tedious manual editing
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following sed command can be used to remove S = "${WORKDIR}/git
+across a whole layer::
+
+   sed -i "/^S = \"\${WORKDIR}\/git\"/d" `find . -name *.bb -o -name *.inc -o -name *.bbclass`
+
+Then, the following command can tweak the remaining :term:`S` assignments to
+refer to :term:`UNPACKDIR` instead of :term:`WORKDIR`::
+
+   sed -i "s/^S = \"\${WORKDIR}\//S = \"\${UNPACKDIR}\//g" `find . -name *.bb -o -name *.inc -o -name *.bbclass`
+
+The first change can introduce a lot of consecutive empty lines, so those can be removed with::
+
+   sed -i -z -E 's/([ \t\f\v\r]*\n){3,}/\n\n/g' `find . -name *.bb -o -name *.inc`
+
 Supported kernel versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 

-- 
2.49.0