3.5.2. Using devtool upgrade

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.

Note

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:

Note

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.