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