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

The devtool upgrade command updates an existing recipe so that you can build it for an updated set of source files. The 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.

Depending on your particular scenario, the arguments and options you use with devtool upgrade form different combinations. The following diagram shows a common development flow you would use with the devtool modify command:

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

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

    • The source files for the new release exist adjacent to 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
                            

    Also, in this example, the "-V" option is used to specify the new 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 are located. 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: At this point, there could be some conflicts due to the software being upgraded to a new version. This would occur if your recipe specifies some patch files in SRC_URI that conflict with changes made in the new version of the software. If this is the case, 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: Once you have your recipe in order, you can build it. You can either use devtool build or bitbake. Either method produces build output that is stored in TMPDIR.

  4. Deploy the Build Output: When you use the devtool build command or bitbake to build out 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. Optionally Create Patch Files for Your Changes: After you have debugged your changes, you can use devtool update-recipe to generate patch files for all the commits you have made.

    Note

    Patch files are generated only for changes you have committed.

         $ devtool update-recipe recipe
                            

    By default, the devtool update-recipe command creates the patch files in a folder named the same as the recipe beneath the folder in which the recipe resides, and updates the recipe's SRC_URI statement to point to the generated patch files.

  6. Move the Recipe to its Permanent Layer: Before cleaning up the workspace, you need to move the final recipe to its permanent layer. You can either overwrite the original recipe or you can overlay the upgraded recipe into a separate layer. You must do this before using the devtool reset command if you want to retain the upgraded recipe.

  7. Restore the Workspace: The devtool reset restores the state so that standard layers and upstream sources are used to build the recipe rather than what is in the workspace.

         $ devtool reset recipe