path: root/documentation/ref-manual/migration.xml
diff options
authorScott Rifenbark <>2014-06-16 21:11:02 +0300
committerRichard Purdie <>2014-06-18 10:30:50 +0100
commit99caeda1a1113b96b56109ba26b344d07cc34ed9 (patch)
tree37b9d9ced32c2232509eb94dd5c6bbb06f4abebc /documentation/ref-manual/migration.xml
parent7dd70a879d67f2cd64d5dd12e54807ea18bf0e22 (diff)
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 <> Signed-off-by: Richard Purdie <>
Diffstat (limited to 'documentation/ref-manual/migration.xml')
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 @@
release notes for a given release.
+<section id='general-migration-considerations'>
+ <title>General Migration Considerations</title>
+ <para>
+ 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.
+ <itemizedlist>
+ <listitem><para><emphasis>Dealing with Customized Recipes</emphasis>:
+ 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.
+ </para>
+ <para>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.</para>
+ <para>The better solution (where practical) is to use append
+ files (<filename>*.bbappend</filename>) 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.</para>
+ </listitem>
+ <listitem><para><emphasis>Updating Append Files</emphasis>:
+ Since append files generally only contain your customizations,
+ they often do not need to be adjusted for new releases.
+ However, if the <filename>.bbappend</filename> 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 (<filename>.bb</filename>) will
+ trigger an error during parsing.</para>
+ <para>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.
+ </para></listitem>
+ </itemizedlist>
+ </para>
<section id='moving-to-the-yocto-project-1.3-release'>
<title>Moving to the Yocto Project 1.3 Release</title>