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