WOKRDIR change transition guide/notes

WOKRDIR change transition guide/notes

[Richard Purdie]

Now that there is a roughly ready patchset for this I wanted to write
down a quick guide to converting recipes.

S = ${WORKDIR}
==============

If a recipe has S set to be WORKDIR this is no longer supported.
Currently you'll see warnings, those will become errors very soon and
even now, the code probably isn't safe to work like that. The recipe
should be changed to:

S = "${WORKDIR}/sources"
UNPACKDIR = "${S}"

Any WORKDIR references where files from SRC_URI are referenced should
be changed to S. These are commonly in do_compile, do_install and
LIC_FILES_CHKSUM.


WORKDIR references in the recipe
================================

WORKDIR references in other recipes need auditing. If they reference
files from SRC_URI, they likely need changing to UNPACKDIR. These are
commonly in do_compile and do_install for things like service or
configuration files.

One unusual one is ${WORKDIR}/${BP} should probably be ${S}.

References to "../" in LIC_FILES_CHKSUM or elsewhere may need changing
to UNPACKDIR.

References to WORKDIR in sed commands are usually left as they are now.


General notes
=============

Files from do_unpack now unpack to WORKDIR/sources-unpack/ rather than
WORKDIR/. 

If S is set to a subdirectory under WORKDIR and that subdirectory
exists in sources-unpack after do_unpack runs, it is moved to WORKDIR.
This means S = "${WORKDIR}/${BP}", S = "${WORKDIR}/git" and also deeper
paths continue to work as expected without changes. We cannot use
symlinks to do this as it breaks autotools based recipes in weird and
interesting ways I didn't feel like exploring.

At this time, keeping all sources under sources-unpack isn't being
considered as it means more invasive recipes changes. The key issue is
separating the unpack task output from WORKDIR which this change
achieves.

Previously, S was always created but after the recent changes it is
not. This means the check in do_unpack_qa triggers where S is not
created by a recipe where as it did not before. This can mean adding a
S definition to a recipe that only uses file:// SRC_URI entries.

Building C files from UNPACKDIR without setting S to point at it does
not work as our debug prefix mapping doesn't handle that. 

devtool and recipetool have been updated to handle this and their
support for S = WORKDIR and oe-local-files has been removed.


Cheers,

Richard

Re: [docs] WOKRDIR change transition guide/notes

[Michael Opdenacker]

Hi Richard,

On 5/15/24 at 15:12, Richard Purdie wrote:
> Now that there is a roughly ready patchset for this I wanted to write
> down a quick guide to converting recipes.
>
> S = ${WORKDIR}
> ==============
>
> If a recipe has S set to be WORKDIR this is no longer supported.
> Currently you'll see warnings, those will become errors very soon and
> even now, the code probably isn't safe to work like that. The recipe
> should be changed to:
>
> S = "${WORKDIR}/sources"
> UNPACKDIR = "${S}"
>
> Any WORKDIR references where files from SRC_URI are referenced should
> be changed to S. These are commonly in do_compile, do_install and
> LIC_FILES_CHKSUM.
>
>
> WORKDIR references in the recipe
> ================================
>
> WORKDIR references in other recipes need auditing. If they reference
> files from SRC_URI, they likely need changing to UNPACKDIR. These are
> commonly in do_compile and do_install for things like service or
> configuration files.
>
> One unusual one is ${WORKDIR}/${BP} should probably be ${S}.
>
> References to "../" in LIC_FILES_CHKSUM or elsewhere may need changing
> to UNPACKDIR.
>
> References to WORKDIR in sed commands are usually left as they are now.
>
>
> General notes
> =============
>
> Files from do_unpack now unpack to WORKDIR/sources-unpack/ rather than
> WORKDIR/.
>
> If S is set to a subdirectory under WORKDIR and that subdirectory
> exists in sources-unpack after do_unpack runs, it is moved to WORKDIR.
> This means S = "${WORKDIR}/${BP}", S = "${WORKDIR}/git" and also deeper
> paths continue to work as expected without changes. We cannot use
> symlinks to do this as it breaks autotools based recipes in weird and
> interesting ways I didn't feel like exploring.
>
> At this time, keeping all sources under sources-unpack isn't being
> considered as it means more invasive recipes changes. The key issue is
> separating the unpack task output from WORKDIR which this change
> achieves.
>
> Previously, S was always created but after the recent changes it is
> not. This means the check in do_unpack_qa triggers where S is not
> created by a recipe where as it did not before. This can mean adding a
> S definition to a recipe that only uses file:// SRC_URI entries.
>
> Building C files from UNPACKDIR without setting S to point at it does
> not work as our debug prefix mapping doesn't handle that.
>
> devtool and recipetool have been updated to handle this and their
> support for S = WORKDIR and oe-local-files has been removed.


Thanks for these guidelines.
I will first submit a patch to start migration and release notes for 
5.1, and then will add your notes to the new migration notes.

Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com