Re: [docs] WOKRDIR change transition guide/notes

[Michael Opdenacker <michael.opdenacker@bootlin.com>]

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