The devtool modify
command prepares the
way to work on existing code that already has a local recipe in
place that is used to build the software.
The command is flexible enough to allow you to extract code
from an upstream source, specify the existing recipe, and
keep track of and gather any patch files from other developers
that are associated with the code.
Depending on your particular scenario, the arguments and options
you use with devtool modify
form different
combinations.
The following diagram shows common development flows for the
devtool modify
command:
Preparing to Modify the Code:
The top part of the flow shows three scenarios by which
you could use devtool modify
to
prepare to work on source files.
Each scenario assumes the following:
The recipe exists locally in a layer external
to the devtool
workspace.
The source files exist either upstream in an un-extracted state or locally in a previously extracted state.
The typical situation is where another developer has created a layer for use with the Yocto Project and their recipe already resides in that layer. Furthermore, their source code is readily available either upstream or locally.
Left:
The left scenario in the figure represents a
common situation where the source code does
not exist locally and it needs to be extracted
from an upstream source.
In this situation, the source is extracted
into the default devtool
workspace location.
The recipe, in this scenario, is in its own
layer outside the workspace
(i.e.
meta-
layername
).
The following command identifies the recipe and, by default, extracts the source files:
$ devtool modify recipe
Once devtool
locates the
recipe, devtool
uses the
recipe's
SRC_URI
statements to locate the source code and any
local patch files from other developers.
With this scenario, no
srctree
argument
exists.
Consequently, the default behavior of the
devtool modify
command is
to extract the source files pointed to by the
SRC_URI
statements into a
local Git structure.
Furthermore, the location for the extracted
source is the default area within the
devtool
workspace.
The result is that the command sets up both
the source code and an append file within the
workspace while the recipe remains in its
original location.
Middle: The middle scenario in the figure represents a situation where the source code also does not exist locally. In this case, the code is again upstream and needs to be extracted to some local area as a Git repository. The recipe, in this scenario, is again local and in its own layer outside the workspace.
The following command tells
devtool
what recipe with
which to work and, in this case, identifies a
local area for the extracted source files that
is outside of the default
devtool
workspace:
$ devtool modify recipe srctree
srctree
using
the devtool
command.
As with all extractions, the command uses
the recipe's SRC_URI
statements to locate the source files and any
associated patch files.
Once the files are located, the command by
default extracts them into
srctree
.
Within workspace,
devtool
creates an append
file for the recipe.
The recipe remains in its original location but
the source files are extracted to the location
you provide with
srctree
.
Right:
The right scenario in the figure represents a
situation where the source tree
(srctree
) already
exists locally as a previously extracted Git
structure outside of the
devtool
workspace.
In this example, the recipe also exists
elsewhere locally in its own layer.
The following command tells
devtool
the recipe
with which to work, uses the "-n" option to
indicate source does not need to be extracted,
and uses srctree
to
point to the previously extracted source files:
$ devtool modify -n recipe srctree
Once the command finishes, it creates only
an append file for the recipe in the
devtool
workspace.
The recipe and the source code remain in their
original locations.
Edit the Source:
Once you have used the
devtool modify
command, you are
free to make changes to the source files.
You can use any editor you like to make and save
your source code modifications.
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 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, use other methods to deploy
the image you built using the
devtool build-image
command to
actual hardware.
devtool
does not provide
a specific command to deploy the image to actual
hardware.
Finish Your Work With the Recipe:
The devtool finish
command creates
any patches corresponding to commits in the local
Git repository, updates the recipe to point to them
(or creates a .bbappend
file to do
so, depending on the specified destination layer), and
then resets the recipe so that the recipe is built
normally rather than from the workspace.
$ devtool finish recipe layer
devtool finish
command.
Because there is no need to move the recipe,
devtool finish
either updates the
original recipe in the original layer or the command
creates a .bbappend
file in a
different layer as provided by
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 from 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.