|author||Scott Rifenbark <email@example.com>||2014-06-16 21:11:02 +0300|
|committer||Richard Purdie <firstname.lastname@example.org>||2014-06-18 10:30:50 +0100|
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 <email@example.com> Signed-off-by: Richard Purdie <firstname.lastname@example.org>
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
@@ -11,6 +11,70 @@
release notes for a given release.
+ <title>General Migration Considerations</title>
+ Some considerations are not tied to a specific Yocto Project
+ This section presents information you should consider when
+ migrating to any new Yocto Project release.
+ <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>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
+ A good example of this is when introducing a newer or older
+ version of a recipe in another layer.</para>
+ <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
+ 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.
<title>Moving to the Yocto Project 1.3 Release</title>