mirror of
git://git.yoctoproject.org/poky.git
synced 2025-07-19 12:59:02 +02:00
8b1909aa6f
Now that .bbclass is removed from class section titles. We can now have, for example, :ref:`ref-classes-insane` instead of :ref:`insane <ref-classes-insane>`. Then, when necessary, rework paragraphs so that they have lines of even length, not exceeding 80 characters. (From yocto-docs rev: e76190e3be78c1e483bec0469f1e437dbf8f3791) Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com> Suggested-by: Quentin Schulz <foss+yocto@0leil.net> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
109 lines
4.6 KiB
ReStructuredText
109 lines
4.6 KiB
ReStructuredText
.. 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
|
|
any new Yocto Project release.
|
|
|
|
- *Dealing with Customized Recipes*:
|
|
|
|
Issues could arise if you take
|
|
older recipes that contain customizations and simply copy them
|
|
forward expecting them to work after you migrate to new Yocto Project
|
|
metadata. For example, suppose you have a recipe in your layer that
|
|
is a customized version of a core recipe copied from the earlier
|
|
release, rather than through the use of an append file. When you
|
|
migrate to a newer version of Yocto Project, the metadata (e.g.
|
|
perhaps an include file used by the recipe) could have changed in a
|
|
way that would break the build. Say, for example, a function is
|
|
removed from an include file and the customized recipe tries to call
|
|
that function.
|
|
|
|
You could "forward-port" all your customizations in your recipe so
|
|
that everything works for the new release. However, this is not the
|
|
optimal solution as you would have to repeat this process with each
|
|
new release if changes occur that give rise to problems.
|
|
|
|
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
|
|
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 (``.bbappend``) files generally only contain
|
|
your customizations, they often do not need to be adjusted for new
|
|
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
|
|
match the name of the recipe file. A mismatch between an append file
|
|
and its corresponding recipe file (``.bb``) will trigger an error
|
|
during parsing.
|
|
|
|
Depending on the type of customization the append file applies, other
|
|
incompatibilities might occur when you upgrade. For example, if your
|
|
append file applies a patch and the recipe to which it is appending
|
|
is updated to a newer version, the patch might no longer apply. If
|
|
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`.
|