summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2014-06-16 21:11:02 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2014-06-18 10:30:50 +0100
commit99caeda1a1113b96b56109ba26b344d07cc34ed9 (patch)
tree37b9d9ced32c2232509eb94dd5c6bbb06f4abebc /documentation/ref-manual
parent7dd70a879d67f2cd64d5dd12e54807ea18bf0e22 (diff)
downloadpoky-99caeda1a1113b96b56109ba26b344d07cc34ed9.tar.gz
ref-manual: Added new section on general migration points.
Fixes [YOCTO #4958] Added a new section to start the Migration chapter. This section will hold general migration issues that are not tied to a specific release. (From yocto-docs rev: e78ae7c64ae5fa7e7a5b1f804fb40b5690a4e899) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/migration.xml64
1 files changed, 64 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
index 9356847b95..d51bc4d8fe 100644
--- a/documentation/ref-manual/migration.xml
+++ b/documentation/ref-manual/migration.xml
@@ -11,6 +11,70 @@
11 release notes for a given release. 11 release notes for a given release.
12 </para> 12 </para>
13 13
14<section id='general-migration-considerations'>
15 <title>General Migration Considerations</title>
16
17 <para>
18 Some considerations are not tied to a specific Yocto Project
19 release.
20 This section presents information you should consider when
21 migrating to any new Yocto Project release.
22 <itemizedlist>
23 <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
24 Issues could arise if you take older recipes that contain
25 customizations and simply copy them forward expecting them
26 to work after you migrate to new Yocto Project metadata.
27 For example, suppose you have a recipe in your layer that is
28 a customized version of a core recipe copied from the earlier
29 release, rather than through the use of an append file.
30 When you migrate to a newer version of Yocto Project, the
31 metadata (e.g. perhaps an include file used by the recipe)
32 could have changed in a way that would break the build.
33 Say, for example, a function is removed from an include file
34 and the customized recipe tries to call that function.
35 </para>
36
37 <para>You could "forward-port" all your customizations in your
38 recipe so that everything works for the new release.
39 However, this is not the optimal solution as you would have
40 to repeat this process with each new release if changes
41 occur that give rise to problems.</para>
42
43 <para>The better solution (where practical) is to use append
44 files (<filename>*.bbappend</filename>) to capture any
45 customizations you want to make to a recipe.
46 Doing so, isolates your changes from the main recipe making
47 them much more manageable.
48 However, sometimes it is not practical to use an append
49 file.
50 A good example of this is when introducing a newer or older
51 version of a recipe in another layer.</para>
52 </listitem>
53 <listitem><para><emphasis>Updating Append Files</emphasis>:
54 Since append files generally only contain your customizations,
55 they often do not need to be adjusted for new releases.
56 However, if the <filename>.bbappend</filename> file is
57 specific to a particular version of the recipe (i.e. its
58 name does not use the % wildcard) and the version of the
59 recipe to which it is appending has changed, then you will
60 at a minimum need to rename the append file to match the
61 name of the recipe file.
62 A mismatch between an append file and its corresponding
63 recipe file (<filename>.bb</filename>) will
64 trigger an error during parsing.</para>
65 <para>Depending on the type of customization the append file
66 applies, other incompatibilities might occur when you
67 upgrade.
68 For example, if your append file applies a patch and the
69 recipe to which it is appending is updated to a newer
70 version, the patch might no longer apply.
71 If this is the case and assuming the patch is still needed,
72 you must modify the patch file so that it does apply.
73 </para></listitem>
74 </itemizedlist>
75 </para>
76</section>
77
14<section id='moving-to-the-yocto-project-1.3-release'> 78<section id='moving-to-the-yocto-project-1.3-release'>
15 <title>Moving to the Yocto Project 1.3 Release</title> 79 <title>Moving to the Yocto Project 1.3 Release</title>
16 80