summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual/migration-general.rst
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/ref-manual/migration-general.rst')
-rw-r--r--documentation/ref-manual/migration-general.rst54
1 files changed, 0 insertions, 54 deletions
diff --git a/documentation/ref-manual/migration-general.rst b/documentation/ref-manual/migration-general.rst
deleted file mode 100644
index 182482ec43..0000000000
--- a/documentation/ref-manual/migration-general.rst
+++ /dev/null
@@ -1,54 +0,0 @@
1General Migration Considerations
2================================
3
4Some considerations are not tied to a specific Yocto Project release.
5This section presents information you should consider when migrating to
6any new Yocto Project release.
7
8- *Dealing with Customized Recipes*:
9
10 Issues could arise if you take
11 older recipes that contain customizations and simply copy them
12 forward expecting them to work after you migrate to new Yocto Project
13 metadata. For example, suppose you have a recipe in your layer that
14 is a customized version of a core recipe copied from the earlier
15 release, rather than through the use of an append file. When you
16 migrate to a newer version of Yocto Project, the metadata (e.g.
17 perhaps an include file used by the recipe) could have changed in a
18 way that would break the build. Say, for example, a function is
19 removed from an include file and the customized recipe tries to call
20 that function.
21
22 You could "forward-port" all your customizations in your recipe so
23 that everything works for the new release. However, this is not the
24 optimal solution as you would have to repeat this process with each
25 new release if changes occur that give rise to problems.
26
27 The better solution (where practical) is to use append files
28 (``*.bbappend``) to capture any customizations you want to make to a
29 recipe. Doing so, isolates your changes from the main recipe making
30 them much more manageable. However, sometimes it is not practical to
31 use an append file. A good example of this is when introducing a
32 newer or older version of a recipe in another layer.
33
34- *Updating Append Files*:
35
36 Since append files generally only contain
37 your customizations, they often do not need to be adjusted for new
38 releases. However, if the ``.bbappend`` file is specific to a
39 particular version of the recipe (i.e. its name does not use the %
40 wildcard) and the version of the recipe to which it is appending has
41 changed, then you will at a minimum need to rename the append file to
42 match the name of the recipe file. A mismatch between an append file
43 and its corresponding recipe file (``.bb``) will trigger an error
44 during parsing.
45
46 Depending on the type of customization the append file applies, other
47 incompatibilities might occur when you upgrade. For example, if your
48 append file applies a patch and the recipe to which it is appending
49 is updated to a newer version, the patch might no longer apply. If
50 this is the case and assuming the patch is still needed, you must
51 modify the patch file so that it does apply.
52
53
54