diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2014-06-16 21:11:02 +0300 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2014-06-18 10:30:50 +0100 |
commit | 99caeda1a1113b96b56109ba26b344d07cc34ed9 (patch) | |
tree | 37b9d9ced32c2232509eb94dd5c6bbb06f4abebc /documentation | |
parent | 7dd70a879d67f2cd64d5dd12e54807ea18bf0e22 (diff) | |
download | ast2050-yocto-poky-99caeda1a1113b96b56109ba26b344d07cc34ed9.zip ast2050-yocto-poky-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')
-rw-r--r-- | documentation/ref-manual/migration.xml | 64 |
1 files changed, 64 insertions, 0 deletions
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml index 9356847..d51bc4d 100644 --- a/documentation/ref-manual/migration.xml +++ b/documentation/ref-manual/migration.xml @@ -11,6 +11,70 @@ release notes for a given release. </para> +<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> + <section id='moving-to-the-yocto-project-1.3-release'> <title>Moving to the Yocto Project 1.3 Release</title> |