diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 745e1c0ab6..8264331dd1 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -4068,6 +4068,462 @@ +
+ Upgrading Recipes + + + Over time, upstream developers publish new versions for software + built by layer recipes. + It is recommended to keep recipes up-to-date with upstream + version releases. + You can use the Automated Upgrade Helper (AUH) to set up + automatic version upgrades. + Alternatively, you can use devtool upgrade + to set up semi-automatic version upgrades. + Finally, you can even manually upgrade a recipe by editing the + recipe itself. + + +
+ Using the Auto Upgrade Helper (AUH) + + + The AUH utility works in conjunction with the + OpenEmbedded build system in order to automatically generate + upgrades for recipes based on new versions being + published upstream. + Use AUH when you want to create a service that performs the + upgrades automatically and optionally sends you an email with + the results. + + + + AUH allows you to update several recipes with a single use. + You can also optionally perform build and integration tests + using images with the results saved to your hard drive and + emails of results optionally sent to recipe maintainers. + Finally, AUH creates Git commits with appropriate commit + messages in the layer's tree for the changes made to recipes. + + Conditions do exist when you should not use AUH to upgrade + recipes and you should instead use either + devtool upgrade or upgrade your + recipes manually: + + + When AUH cannot complete the upgrade sequence. + This situation usually results because custom + patches carried by the recipe cannot be + automatically rebased to the new version. + In this case, devtool upgrade + allows you to manually resolve conflicts. + + + When for any reason you want fuller control over + the upgrade process. + For example, when you want special arrangements + for testing. + + + + + + + The following steps describe how to set up the AUH utility: + + + Be Sure the Development Host is Set Up: + You need to be sure that your development host is + set up to use the Yocto Project. + For information on how to set up your host, see the + "Setting Up the Development Host to Use the Yocto Project" + section in the Yocto Project Development Tasks Manual. + + + Make Sure Git is Configured: + The AUH utility requires Git to be configured because + AUH uses Git to save upgrades. + Thus, you must have Git user and email configured. + The following command shows your configurations: + + $ git config --list + + If you do not have the user and email configured, you + can use the following commands to do so: + + $ git config --global user.name some_name + $ git config --global user.email username@domain.com + + + + Clone the AUH Respository: + To use AUH, you must clone the repository onto your + development host. + The following command uses Git to create a local + copy of the repository on your system: + + $ git clone git://git.yoctoproject.org/auto-upgrade-helper + Cloning into 'auto-upgrade-helper'... + remote: Counting objects: 768, done. + remote: Compressing objects: 100% (300/300), done. + remote: Total 768 (delta 499), reused 703 (delta 434) + Receiving objects: 100% (768/768), 191.47 KiB | 98.00 KiB/s, done. + Resolving deltas: 100% (499/499), done. + Checking connectivity... done. + + AUH is not part of the + OpenEmbedded-Core (OE-Core) + or + Poky + repositories. + + + Create a Dedicated Build Directory: + Run the + oe-init-build-env + script to create a fresh build directory that you + use exclusively for running the AUH utility: + + $ cd ~/poky + $ source oe-init-build-env your_AUH_build_directory + + Re-using an existing build directory and its + configurations is not recommended as existing settings + could cause AUH to fail or behave undesirably. + + + Make Configurations in Your Local Configuration File: + Several settings need to exist in the + local.conf file in the build + directory you just created for AUH. + Make these following configurations: + + + Enable "distrodata" as follows: + + INHERIT =+ "distrodata" + + + + If you want to enable + Build History, + which is optional, you need the following + lines in the + conf/local.conf file: + + INHERIT =+ "buildhistory" + BUILDHISTORY_COMMIT = "1" + + With this configuration and a successful + upgrade, a build history "diff" file appears in + the + upgrade-helper/work/recipe/buildhistory-diff.txt + file found in your build directory. + + + If you want to enable testing through the + testimage + class, which is optional, you need to have the + following set in your + conf/local.conf file: + + INHERIT += "testimage" + + + If your distro does not enable by default + ptest, which Poky does, you need the + following in your + local.conf file: + + DISTRO_FEATURES_append = " ptest" + + + + + + + Optionally Start a vncserver: + If you are running in a server without an X11 session, + you need to start a vncserver: + + $ vncserver :1 + $ export DISPLAY=:1 + + + + Create and Edit an AUH Configuration File: + You need to have the + upgrade-helper/upgrade-helper.conf + configuration file in your build directory. + You can find a sample configuration file in the + AUH source repository. + + + Read through the sample file and make + configurations as needed. + For example, if you enabled build history in your + local.conf as described earlier, + you must enable it in + upgrade-helper.conf. + + Also, if you are using the default + maintainers.inc file supplied + with Poky and located in + meta-yocto and you do not set a + "maintainers_whitelist" or "global_maintainer_override" + in the upgrade-helper.conf + configuration, and you specify "-e all" on the + AUH command-line, the utility automatically sends out + emails to all the default maintainers. + Please avoid this. + + + + + + This next set of examples describes how to use the AUH: + + + Upgrading a Specific Recipe: + To upgrade a specific recipe, use the following + form: + + $ upgrade-helper.py recipe_name + + For example, this command upgrades the + xmodmap recipe: + + $ upgrade-helper.py xmodmap + + + + Upgrading a Specific Recipe to a Particular Version: + To upgrade a specific recipe to a particular version, + use the following form: + + $ upgrade-helper.py recipe_name -t version + + For example, this command upgrades the + xmodmap recipe to version + 1.2.3: + + $ upgrade-helper.py xmodmap -t 1.2.3 + + + + Upgrading all Recipes to the Latest Versions and Suppressing Email Notifications: + To upgrade all recipes to their most recent versions + and suppress the email notifications, use the following + command: + + $ upgrade-helper.py all + + + + Upgrading all Recipes to the Latest Versions and Send Email Notifications: + To upgrade all recipes to their most recent versions + and send email messages to maintainers for each + attempted recipe as well as a status email, use the + following command: + + $ upgrade-helper.py -e all + + + + + + + Once you have run the AUH utility, you can find the results + in the AUH build directory: + + ${BUILDDIR}/upgrade-helper/timestamp + + The AUH utility also creates recipe update commits from + successful upgrade attempts in the layer tree. + + + + You can easily set up to run the AUH utility on a regular + basis by using a cron job. + See the + weeklyjob.sh + file distributed with the utility for an example. + +
+ +
+ Using <filename>devtool upgrade</filename> + + + As mentioned earlier, an alternative method for upgrading + recipes to newer versions is to use + devtool upgrade. + You can read about devtool upgrade in + general in the + "Use devtool upgrade to Create a Version of the Recipe that Supports a Newer Version of the Software" + section in the Yocto Project Application Development and the + Extensible Software Development Kit (eSDK) Manual. + + + + To see all the command-line options available with + devtool upgrade, use the following help + command: + + $ devtool upgrade -h + + + + + If you want to find out what version a recipe is currently at + upstream without any attempt to upgrade your local version of + the recipe, you can use the following command: + + $ devtool latest-version recipe_name + + + + + As mentioned in the previous section describing AUH, + devtool upgrade works in a + less-automated manner than AUH. + Specifically, devtool upgrade only + works on a single recipe that you name on the command line, + cannot perform build and integration testing using images, + and does not automatically generate commits for changes in + the source tree. + Despite all these "limitations", + devtool upgrade updates the recipe file + to the new upstream version and attempts to rebase custom + patches contained by the recipe as needed. + + AUH uses much of devtool upgrade + behind the scenes making AUH somewhat of a "wrapper" + application for devtool upgrade. + + + + + A typical scenario involves having used Git to clone an + upstream repository that you use during build operations. + Because you are (or have) built the recipe in the past, the + layer is likely added to your configuration already. + If for some reason, the layer is not added, you could add + it easily using the + bitbake-layers + script. + For example, suppose you use the nano.bb + recipe from the meta-oe layer in the + meta-openembedded repository. + For this example, assume that the layer has been cloned into + following area: + + /home/scottrif/meta-openembedded + + The following command from your + Build Directory + adds the layer to your build configuration (i.e. + ${BUILDDIR}/conf/bblayers.conf): + + $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe + NOTE: Starting bitbake server... + Parsing recipes: 100% |##########################################| Time: 0:00:55 + Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors. + Removing 12 recipes from the x86_64 sysroot: 100% |##############| Time: 0:00:00 + Removing 1 recipes from the x86_64_i586 sysroot: 100% |##########| Time: 0:00:00 + Removing 5 recipes from the i586 sysroot: 100% |#################| Time: 0:00:00 + Removing 5 recipes from the qemux86 sysroot: 100% |##############| Time: 0:00:00 + + For this example, assume that the nano.bb + recipe that is upstream has a 2.9.3 version number. + However, the version in the local repository is 2.7.4. + The following command from your build directory automatically + upgrades the recipe for you: + + Using the -V option is not necessary. + Omitting the version number causes + devtool upgrade to upgrade the recipe + to the most recent version. + + + $ devtool upgrade nano -V 2.9.3 + NOTE: Starting bitbake server... + NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace + Parsing recipes: 100% |##########################################| Time: 0:00:46 + Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors. + NOTE: Extracting current version source... + NOTE: Resolving any missing task queue dependencies + . + . + . + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded. + Adding changed files: 100% |#####################################| Time: 0:00:00 + NOTE: Upgraded source extracted to /home/scottrif/poky/build/workspace/sources/nano + NOTE: New recipe is /home/scottrif/poky/build/workspace/recipes/nano/nano_2.9.3.bb + + Continuing with this example, you can use + devtool build to build the newly upgraded + recipe: + + $ devtool build nano + NOTE: Starting bitbake server... + Loading cache: 100% |################################################################################################| Time: 0:00:01 + Loaded 2040 entries from dependency cache. + Parsing recipes: 100% |##############################################################################################| Time: 0:00:00 + Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors. + NOTE: Resolving any missing task queue dependencies + . + . + . + NOTE: Executing SetScene Tasks + NOTE: Executing RunQueue Tasks + NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano + NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded. + + Within the devtool upgrade workflow, + opportunity exists to deploy and test your rebuilt software. + For this example, however, running + devtool finish cleans up the workspace + once the source in your workspace is clean. + This usually means using Git to stage and submit commits + for the changes generated by the upgrade process. + + + + Once the tree is clean, you can clean things up in this + example with the following command from the + ${BUILDDIR}/workspace/sources/nano + directory: + + $ devtool finish nano meta-oe + NOTE: Starting bitbake server... + Loading cache: 100% |################################################################################################| Time: 0:00:00 + Loaded 2040 entries from dependency cache. + Parsing recipes: 100% |##############################################################################################| Time: 0:00:01 + Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors. + NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch + NOTE: Updating recipe nano_2.9.3.bb + NOTE: Removing file /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb + NOTE: Moving recipe file to /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano + NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually + + Using the devtool finish command cleans + up the workspace and creates a patch file based on your + commits. + The tool puts all patch files back into the source directory + in a sub-directory named nano in this + case. + +
+ +
+ Manually Upgrading a Recipe + +
+
+
Finding Temporary Source Code