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.
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:
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
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.
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.
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
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.
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.
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
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.
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.