2.4.3. Use devtool upgrade to Create a Version of the Recipe that Supports a Newer Version of the Software

The devtool upgrade command upgrades an existing recipe to that of a more up-to-date version found upstream. Throughout the life of software, recipes continually undergo version upgrades by their upstream publishers. You can use the devtool upgrade workflow to make sure your recipes you are using for builds are up-to-date with their upstream counterparts.

Note

Several methods exist by which you can upgrade recipes - devtool upgrade happens to be one. You can read about all the methods by which you can upgrade recipes in the "Upgrading Recipes" section of the Yocto Project Development Tasks Manual.

The devtool upgrade command is flexible enough to allow you to specify source code revision and versioning schemes, extract code into or out of the devtool workspace, and work with any source file forms that the fetchers support.

The following diagram shows the common development flow used with the devtool upgrade command:

  1. Initiate the Upgrade: The top part of the flow shows the typical scenario by which you use the devtool upgrade command. The following conditions exist:

    • The recipe exists in a local layer external to the devtool workspace.

    • The source files for the new release exist in the same location pointed to by SRC_URI in the recipe (e.g. a tarball with the new version number in the name, or as a different revision in the upstream Git repository).

    A common situation is where third-party software has undergone a revision so that it has been upgraded. The recipe you have access to is likely in your own layer. Thus, you need to upgrade the recipe to use the newer version of the software:

         $ devtool upgrade -V version recipe
                            

    By default, the devtool upgrade command extracts source code into the sources directory in the workspace. If you want the code extracted to any other location, you need to provide the srctree positional argument with the command as follows:

         $ devtool upgrade -V version recipe srctree
                            

    Note

    In this example, the "-V" option specifies the new version. If you don't use "-V", the command upgrades the recipe to the latest version.

    If the source files pointed to by the SRC_URI statement in the recipe are in a Git repository, you must provide the "-S" option and specify a revision for the software.

    Once devtool locates the recipe, it uses the SRC_URI variable to locate the source code and any local patch files from other developers. The result is that the command sets up the source code, the new version of the recipe, and an append file all within the workspace.

  2. Resolve any Conflicts created by the Upgrade: Conflicts could exist due to the software being upgraded to a new version. Conflicts occur if your recipe specifies some patch files in SRC_URI that conflict with changes made in the new version of the software. For such cases, you need to resolve the conflicts by editing the source and following the normal git rebase conflict resolution process.

    Before moving onto the next step, be sure to resolve any such conflicts created through use of a newer or different version of the software.

  3. Build the Recipe or Rebuild the Image: The next step you take depends on what you are going to do with the new code.

    If you need to eventually move the build output to the target hardware, use the following devtool command:

         $ devtool build recipe
                            

    On the other hand, if you want an image to contain the recipe's packages from the workspace for immediate deployment onto a device (e.g. for testing purposes), you can use the devtool build-image command:

         $ devtool build-image image
                            

  4. Deploy the Build Output: When you use the devtool build command or bitbake to build your recipe, you probably want to see if the resulting build output works as expected on target hardware.

    Note

    This step assumes you have a previously built image that is already either running in QEMU or running on actual hardware. Also, it is assumed that for deployment of the image to the target, SSH is installed in the image and if the image is running on real hardware that you have network access to and from your development machine.

    You can deploy your build output to that target hardware by using the devtool deploy-target command:

         $ devtool deploy-target recipe target
                            

    The target is a live target machine running as an SSH server.

    You can, of course, also deploy the image you build using the devtool build-image command to actual hardware. However, devtool does not provide a specific command that allows you to do this.

  5. Finish Your Work With the Recipe: The devtool finish command creates any patches corresponding to commits in the local Git repository, moves the new recipe to a more permanent layer, and then resets the recipe so that the recipe is built normally rather than from the workspace. If you specify a destination layer that is the same as the original source, then the old version of the recipe and associated files will be removed prior to adding the new version.

         $ devtool finish recipe layer
                            

    Note

    Any changes you want to turn into patches must be committed to the Git repository in the source tree.

    As a final process of the devtool finish command, the state of the standard layers and the upstream source is restored so that you can build the recipe from those areas rather than the workspace.

    Note

    You can use the devtool reset command to put things back should you decide you do not want to proceed with your work. If you do use this command, realize that the source tree is preserved.