diff options
Diffstat (limited to 'documentation/ref-manual/migration.xml')
| -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 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. </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> |