1Introduction 2============ 3 4This guide provides a list of the backwards-incompatible changes you 5might need to adapt to in your existing Yocto Project configuration 6when upgrading to a new release. 7 8If you are upgrading over multiple releases, you will need to follow 9the sections from the version following the one you were previously 10using up to the new version you are upgrading to. 11 12 13General Migration Considerations 14-------------------------------- 15 16Some considerations are not tied to a specific Yocto Project release. 17This section presents information you should consider when migrating to 18any new Yocto Project release. 19 20- *Dealing with Customized Recipes*: 21 22 Issues could arise if you take 23 older recipes that contain customizations and simply copy them 24 forward expecting them to work after you migrate to new Yocto Project 25 metadata. For example, suppose you have a recipe in your layer that 26 is a customized version of a core recipe copied from the earlier 27 release, rather than through the use of an append file. When you 28 migrate to a newer version of Yocto Project, the metadata (e.g. 29 perhaps an include file used by the recipe) could have changed in a 30 way that would break the build. Say, for example, a function is 31 removed from an include file and the customized recipe tries to call 32 that function. 33 34 You could "forward-port" all your customizations in your recipe so 35 that everything works for the new release. However, this is not the 36 optimal solution as you would have to repeat this process with each 37 new release if changes occur that give rise to problems. 38 39 The better solution (where practical) is to use append files 40 (``*.bbappend``) to capture any customizations you want to make to a 41 recipe. Doing so isolates your changes from the main recipe, making 42 them much more manageable. However, sometimes it is not practical to 43 use an append file. A good example of this is when introducing a 44 newer or older version of a recipe in another layer. 45 46 47- *Updating Append Files*: 48 49 Since append (``.bbappend``) files generally only contain 50 your customizations, they often do not need to be adjusted for new 51 releases. However, if the append file is specific to a 52 particular version of the recipe (i.e. its name does not use the % 53 wildcard) and the version of the recipe to which it is appending has 54 changed, then you will at a minimum need to rename the append file to 55 match the name of the recipe file. A mismatch between an append file 56 and its corresponding recipe file (``.bb``) will trigger an error 57 during parsing. 58 59 Depending on the type of customization the append file applies, other 60 incompatibilities might occur when you upgrade. For example, if your 61 append file applies a patch and the recipe to which it is appending 62 is updated to a newer version, the patch might no longer apply. If 63 this is the case and assuming the patch is still needed, you must 64 modify the patch file so that it does apply. 65 66 .. tip:: 67 68 You can list all append files used in your configuration by running: 69 70 bitbake-layers show-appends 71 72 73