The devtool modify
command prepares the
way to work on existing code that already has a recipe in
place.
The command is flexible enough to allow you to extract code,
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
you would use with 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 in some layer external
to the devtool
workspace.
The source files exist upstream in an un-extracted state or locally in a previously extracted state.
The typical situation is where another developer has created some 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 represents a common situation
where the source code does not exist locally
and needs to be extracted.
In this situation, the source is extracted
into the default 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,
it uses the
SRC_URI
variable to locate the source code and
any local patch files from other developers are
located.
srctree
when using the
devtool modify
command.
With this scenario, however, since no
srctree
argument exists, the
devtool modify
command by default
extracts the source files to a Git structure.
Furthermore, the location for the extracted source is the
default area within the workspace.
The result is that the command sets up both the source
code and an append file within the workspace with the
recipe remaining in its original location.
Middle: The middle scenario 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 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 workspace:
$ devtool modify recipe srctree
As with all extractions, the command uses
the recipe's SRC_URI
to locate the
source files.
Once the files are located, the command by default
extracts them.
Providing the srctree
argument instructs devtool
where
place the extracted source.
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
provided with srctree
.
Right:
The right scenario represents a situation
where the source tree
(srctree
) exists as a
previously extracted Git structure outside of
the devtool
workspace.
In this example, the recipe also exists
elsewhere 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 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: Once you have updated the source files, you can build the recipe.
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, 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, 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
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
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 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.