diff options
author | Michael Opdenacker <michael.opdenacker@bootlin.com> | 2021-06-10 11:26:21 +0200 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2021-06-14 22:45:33 +0100 |
commit | 5f978a6ccacf9f7f9475207c5a2a1af1dc4c3d00 (patch) | |
tree | fa7ba7ced9e17426b72e07c50288163a5d8ba901 /documentation/migration-guides/migration-general.rst | |
parent | dae1e986a0608d899f67f1ae62389d350824235f (diff) | |
download | poky-5f978a6ccacf9f7f9475207c5a2a1af1dc4c3d00.tar.gz |
ref-manual: move migration guides to separate document
This makes the reference manual much lighter by moving
the migration guides to a separate document.
The migration guides are also reordered from last to first,
and they appear directly in the left bar, making them easier
to find in the documentation.
(From yocto-docs rev: 5121b86ee97eb62a0c69c9ad1fc0e3fabbe3e934)
Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/migration-guides/migration-general.rst')
-rw-r--r-- | documentation/migration-guides/migration-general.rst | 54 |
1 files changed, 54 insertions, 0 deletions
diff --git a/documentation/migration-guides/migration-general.rst b/documentation/migration-guides/migration-general.rst new file mode 100644 index 0000000000..182482ec43 --- /dev/null +++ b/documentation/migration-guides/migration-general.rst | |||
@@ -0,0 +1,54 @@ | |||
1 | General Migration Considerations | ||
2 | ================================ | ||
3 | |||
4 | Some considerations are not tied to a specific Yocto Project release. | ||
5 | This section presents information you should consider when migrating to | ||
6 | any 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 | |||