blob: 0f0408e51fb7bc83849cb08b5b9cc92f7a77d09b [file] [log] [blame]
Andrew Geisslereff27472021-10-29 15:35:00 -05001Introduction
2============
3
4This guide provides a list of the backwards-incompatible changes you
5might need to adapt to in your existing Yocto Project configuration
6when upgrading to a new release.
7
8If you are upgrading over multiple releases, you will need to follow
9the sections from the version following the one you were previously
10using up to the new version you are upgrading to.
11
12
Andrew Geisslerc9f78652020-09-18 14:11:35 -050013General Migration Considerations
Andrew Geisslereff27472021-10-29 15:35:00 -050014--------------------------------
Andrew Geisslerc9f78652020-09-18 14:11:35 -050015
16Some considerations are not tied to a specific Yocto Project release.
17This section presents information you should consider when migrating to
18any new Yocto Project release.
19
20- *Dealing with Customized Recipes*:
21
22 Issues could arise if you take
23 older recipes that contain customizations and simply copy them
24 forward expecting them to work after you migrate to new Yocto Project
25 metadata. For example, suppose you have a recipe in your layer that
26 is a customized version of a core recipe copied from the earlier
27 release, rather than through the use of an append file. When you
28 migrate to a newer version of Yocto Project, the metadata (e.g.
29 perhaps an include file used by the recipe) could have changed in a
30 way that would break the build. Say, for example, a function is
31 removed from an include file and the customized recipe tries to call
32 that function.
33
34 You could "forward-port" all your customizations in your recipe so
35 that everything works for the new release. However, this is not the
36 optimal solution as you would have to repeat this process with each
37 new release if changes occur that give rise to problems.
38
39 The better solution (where practical) is to use append files
40 (``*.bbappend``) to capture any customizations you want to make to a
Andrew Geisslereff27472021-10-29 15:35:00 -050041 recipe. Doing so isolates your changes from the main recipe, making
Andrew Geisslerc9f78652020-09-18 14:11:35 -050042 them much more manageable. However, sometimes it is not practical to
43 use an append file. A good example of this is when introducing a
44 newer or older version of a recipe in another layer.
45
Andrew Geisslereff27472021-10-29 15:35:00 -050046
Andrew Geisslerc9f78652020-09-18 14:11:35 -050047- *Updating Append Files*:
48
Andrew Geisslereff27472021-10-29 15:35:00 -050049 Since append (``.bbappend``) files generally only contain
Andrew Geisslerc9f78652020-09-18 14:11:35 -050050 your customizations, they often do not need to be adjusted for new
Andrew Geisslereff27472021-10-29 15:35:00 -050051 releases. However, if the append file is specific to a
Andrew Geisslerc9f78652020-09-18 14:11:35 -050052 particular version of the recipe (i.e. its name does not use the %
53 wildcard) and the version of the recipe to which it is appending has
54 changed, then you will at a minimum need to rename the append file to
55 match the name of the recipe file. A mismatch between an append file
56 and its corresponding recipe file (``.bb``) will trigger an error
57 during parsing.
58
59 Depending on the type of customization the append file applies, other
60 incompatibilities might occur when you upgrade. For example, if your
61 append file applies a patch and the recipe to which it is appending
62 is updated to a newer version, the patch might no longer apply. If
63 this is the case and assuming the patch is still needed, you must
64 modify the patch file so that it does apply.
65
Andrew Geisslereff27472021-10-29 15:35:00 -050066 .. tip::
67
68 You can list all append files used in your configuration by running:
69
70 bitbake-layers show-appends
Andrew Geisslerc9f78652020-09-18 14:11:35 -050071
72
Patrick Williams975a06f2022-10-21 14:42:47 -050073.. _migration-general-buildhistory:
74
75- *Checking Image / SDK Changes*:
76
77 The :ref:`buildhistory <ref-classes-buildhistory>` class can be used
78 if you wish to check the impact of changes to images / SDKs across
79 the migration (e.g. added/removed packages, added/removed files, size
80 changes etc.). To do this, follow these steps:
81
82 1. Enable buildhistory before the migration
83
84 2. Run a pre-migration build
85
86 3. Capture the buildhistory output (as specified by :term:`BUILDHISTORY_DIR`)
87 and ensure it is preserved for subsequent builds. How you would do this
88 depends on how you are running your builds - if you are doing this all on
89 one workstation in the same build directory you may not need to do
90 anything other than not deleting the buildhistory output directory. For
91 builds in a pipeline it may be more complicated.
92
93 4. Set a tag in the buildhistory output (which is a git repository) before
94 migration, to make the commit from the pre-migration build easy to find
95 as you may end up running multiple builds during the migration.
96
97 5. Perform the migration
98
99 6. Run a build
100
101 7. Check the output changes between the previously set tag and HEAD in the
102 buildhistory output using ``git diff`` or ``buildhistory-diff``.
103
104 For more information on using buildhistory, see
105 :ref:`dev-manual/common-tasks:maintaining build output quality`.