From bebe947dd5cc087d49967a807807a388dbde1332 Mon Sep 17 00:00:00 2001 From: Michael Opdenacker Date: Thu, 23 May 2024 15:49:13 +0200 Subject: migration-5.1.rst: preliminary description of UNPACKDIR changes (From yocto-docs rev: ac7a35edbd20ba2d1789ff77b53484ad34cc0850) Signed-off-by: Michael Opdenacker Signed-off-by: Richard Purdie --- documentation/migration-guides/migration-5.1.rst | 55 ++++++++++++++++++++++++ 1 file changed, 55 insertions(+) (limited to 'documentation') diff --git a/documentation/migration-guides/migration-5.1.rst b/documentation/migration-guides/migration-5.1.rst index 9bedbfa311..c1cc711a42 100644 --- a/documentation/migration-guides/migration-5.1.rst +++ b/documentation/migration-guides/migration-5.1.rst @@ -11,6 +11,61 @@ Project 5.1 Release (codename "styhead") from the prior release. .. _migration-5.1-supported-kernel-versions: +:term:`WORKDIR` changes +~~~~~~~~~~~~~~~~~~~~~~~ + +S = ${WORKDIR} no longer supported +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If a recipe has :term:`S` set to be :term:`WORKDIR`, this is no longer +supported, and an error will be issued. The recipe should be changed to:: + + S = "${WORKDIR}/sources" + UNPACKDIR = "${S}" + +Any :term:`WORKDIR` references where files from :term:`SRC_URI` are referenced +should be changed to :term:`S`. These are commonly in :ref:`ref-tasks-compile`, +:ref:`ref-tasks-compile`, :ref:`ref-tasks-install` and :term:`LIC_FILES_CHKSUM`. + +:term:`WORKDIR` references in recipes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:term:`WORKDIR` references in other recipes need auditing. If they reference +files from :term:`SRC_URI`, they likely need changing to :term:`UNPACKDIR`. +These are commonly in :ref:`ref-tasks-compile` and :ref:`ref-tasks-install` +for things like service or configuration files. One unusual case is +``${WORKDIR}/${BP}`` which should probably be set to ``${S}``. + +References to ``../`` in :term:`LIC_FILES_CHKSUM` or elsewhere may need changing +to :term:`UNPACKDIR`. References to :term:`WORKDIR` in ``sed`` commands are +usually left as they are. + +General notes +^^^^^^^^^^^^^ + +Files from :ref:`ref-tasks-unpack` now unpack to ``WORKDIR/sources-unpack/`` +rather than ``WORKDIR/``. + +If :term:`S` is set to a subdirectory under :term:`WORKDIR` and that +subdirectory exists in ``sources-unpack`` after :ref:`ref-tasks-unpack` runs, +it is moved to :term:`WORKDIR`. This means that ``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. Keeping all sources under ``sources-unpack`` wasn't considered +as it meant more invasive recipes changes. The key objective was separating the +:ref:`ref-tasks-unpack` task output from :term:`WORKDIR`. + +Previously, :term:`S` was always created but after the recent changes it is no +longer the case. This means the check in ``do_unpack_qa`` triggers where +:term:`S` is not created by a recipe while it didn't happen before. This can +require to add an :term:`S` definition to a recipe that only uses +``file://`` :term:`SRC_URI` entries. Building C files from :term:`UNPACKDIR` +without setting :term:`S` to point at it does not work as the 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. + Supported kernel versions ~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3-54-g00ecf