diff options
Diffstat (limited to 'documentation/migration-guides/migration-general.rst')
| -rw-r--r-- | documentation/migration-guides/migration-general.rst | 62 |
1 files changed, 58 insertions, 4 deletions
diff --git a/documentation/migration-guides/migration-general.rst b/documentation/migration-guides/migration-general.rst index 182482ec43..1820f5cfd8 100644 --- a/documentation/migration-guides/migration-general.rst +++ b/documentation/migration-guides/migration-general.rst @@ -1,5 +1,19 @@ +.. SPDX-License-Identifier: CC-BY-SA-2.0-UK + +Introduction +============ + +This guide provides a list of the backwards-incompatible changes you +might need to adapt to in your existing Yocto Project configuration +when upgrading to a new release. + +If you are upgrading over multiple releases, you will need to follow +the sections from the version following the one you were previously +using up to the new version you are upgrading to. + + General Migration Considerations -================================ +-------------------------------- Some considerations are not tied to a specific Yocto Project release. This section presents information you should consider when migrating to @@ -26,16 +40,17 @@ any new Yocto Project release. The better solution (where practical) is to use append files (``*.bbappend``) to capture any customizations you want to make to a - recipe. Doing so, isolates your changes from the main recipe making + recipe. Doing so isolates your changes from the main recipe, making them much more manageable. However, sometimes it is not practical to use an append file. A good example of this is when introducing a newer or older version of a recipe in another layer. + - *Updating Append Files*: - Since append files generally only contain + Since append (``.bbappend``) files generally only contain your customizations, they often do not need to be adjusted for new - releases. However, if the ``.bbappend`` file is specific to a + releases. However, if the append file is specific to a particular version of the recipe (i.e. its name does not use the % wildcard) and the version of the recipe to which it is appending has changed, then you will at a minimum need to rename the append file to @@ -50,5 +65,44 @@ any new Yocto Project release. this is the case and assuming the patch is still needed, you must modify the patch file so that it does apply. + .. tip:: + + You can list all append files used in your configuration by running: + + bitbake-layers show-appends + + +.. _migration-general-buildhistory: + +- *Checking Image / SDK Changes*: + + The :ref:`ref-classes-buildhistory` class can be used + if you wish to check the impact of changes to images / SDKs across + the migration (e.g. added/removed packages, added/removed files, size + changes etc.). To do this, follow these steps: + + #. Enable :ref:`ref-classes-buildhistory` before the migration + + #. Run a pre-migration build + + #. Capture the :ref:`ref-classes-buildhistory` output (as + specified by :term:`BUILDHISTORY_DIR`) and ensure it is preserved for + subsequent builds. How you would do this depends on how you are running + your builds - if you are doing this all on one workstation in the same + :term:`Build Directory` you may not need to do anything other than not + deleting the :ref:`ref-classes-buildhistory` output + directory. For builds in a pipeline it may be more complicated. + + #. Set a tag in the :ref:`ref-classes-buildhistory` output (which is a git repository) before + migration, to make the commit from the pre-migration build easy to find + as you may end up running multiple builds during the migration. + + #. Perform the migration + + #. Run a build + #. Check the output changes between the previously set tag and HEAD in the + :ref:`ref-classes-buildhistory` output using ``git diff`` or ``buildhistory-diff``. + For more information on using :ref:`ref-classes-buildhistory`, see + :ref:`dev-manual/build-quality:maintaining build output quality`. |