The devtool add
command generates
a new recipe based on existing source code.
This command takes advantage of the
workspace
layer that many devtool
commands
use.
The command is flexible enough to allow you to extract source
code into both the workspace or a separate local Git repository
and to use existing code that does not need to be extracted.
Depending on your particular scenario, the arguments and options
you use with devtool add
form different
combinations.
The following diagram shows common development flows
you would use with the devtool add
command:
Generating the New Recipe:
The top part of the flow shows three scenarios by which
you could use devtool add
to
generate a recipe based on existing source code.
In a shared development environment, it is typical for other developers to be responsible for various areas of source code. As a developer, you are probably interested in using that source code as part of your development within the Yocto Project. All you need is access to the code, a recipe, and a controlled area in which to do your work.
Within the diagram, three possible scenarios
feed into the devtool add
workflow:
Left: The left scenario in the figure represents a common situation where the source code does not exist locally and needs to be extracted. In this situation, the source code is extracted to the default workspace - you do not want the files in some specific location outside of the workspace. Thus, everything you need will be located in the workspace:
$ devtool add recipe fetchuri
With this command, devtool
extracts the upstream source files into a local
Git repository within the
sources
folder.
The command then creates a recipe named
recipe
and a
corresponding append file in the workspace.
If you do not provide
recipe
, the command
makes an attempt to determine the recipe name.
Middle: The middle scenario in the figure also represents a situation where the source code does not exist locally. In this case, the code is again upstream and needs to be extracted to some local area - this time outside of the default workspace.
devtool
always creates
a Git repository locally during the
extraction.
Furthermore, the first positional argument
srctree
in this
case identifies where the
devtool add
command
will locate the extracted code outside of the
workspace.
You need to specify an empty directory:
$ devtool add recipe srctree fetchuri
In summary, the source code is pulled from
fetchuri
and
extracted into the location defined by
srctree
as a local
Git repository.
Within workspace,
devtool
creates a
recipe named recipe
along with an associated append file.
Right:
The right scenario in the figure represents a
situation where the
srctree
has been
previously prepared outside of the
devtool
workspace.
The following command provides a new recipe name and identifies the existing source tree location:
$ devtool add recipe srctree
The command examines the source code and
creates a recipe named
recipe
for the code
and places the recipe into the workspace.
Because the extracted source code already
exists, devtool
does not
try to relocate the source code into the
workspace - only the new recipe is placed
in the workspace.
Aside from a recipe folder, the command
also creates an associated append folder and
places an initial
*.bbappend
file within.
Edit the Recipe:
You can use devtool edit-recipe
to open up the editor as defined by the
$EDITOR
environment variable
and modify the file:
$ devtool edit-recipe recipe
From within the editor, you can make modifications to the recipe that take affect when you build it later.
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 the 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 to actual hardware by using the
devtool build-image
command.
However, devtool
does not provide
a specific command that allows you 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, 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.
$ devtool finish recipe layer
As mentioned, the
devtool finish
command moves the
final recipe to its permanent 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.