dev-manual: Added section for devtool modify flow
New figure and some writer notes for now (From yocto-docs rev: 0a627626f5f353e514b0225b468b0bd0fa3ceef3) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
Richard Purdie
parent
1eecaea70d
commit
7699f0ab60
|
|
@ -1952,6 +1952,281 @@
|
|||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
|
||||
<title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an Existing Recipe</title>
|
||||
|
||||
<para>
|
||||
The <filename>devtool modify</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Depending on your particular scenario, the arguments and options
|
||||
you use with <filename>devtool modify</filename> form different
|
||||
combinations.
|
||||
The following diagram shows common development flows
|
||||
you would use with the <filename>devtool modify</filename>
|
||||
command:
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<imagedata fileref="figures/devtool-modify-flow.png" align="center" />
|
||||
</para>
|
||||
|
||||
<para>
|
||||
<orderedlist>
|
||||
<listitem><para><emphasis>Preparing to Modify the Code</emphasis>:
|
||||
The top part of the flow shows three scenarios by which
|
||||
you could use <filename>devtool modify</filename> to
|
||||
prepare to work on source files.
|
||||
Each scenario assumes the following:
|
||||
<itemizedlist>
|
||||
<listitem><para>The recipe exists in some layer external
|
||||
to the <filename>devtool</filename> workspace.
|
||||
</para></listitem>
|
||||
<listitem><para>The source files exist in a Git
|
||||
structure either upstream in an un-extracted
|
||||
state or locally in a previously extracted
|
||||
state.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
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.
|
||||
<itemizedlist>
|
||||
<listitem><para><emphasis>Left</emphasis>:
|
||||
The left scenario represents a situation
|
||||
where the source tree (srctree) exists as a
|
||||
previously extracted Git structure outside of
|
||||
the <filename>devtool</filename> workspace.
|
||||
In this example, the recipe also exists
|
||||
elsewhere in its own layer
|
||||
(i.e. <filename>meta-</filename><replaceable>layername</replaceable>).
|
||||
</para>
|
||||
|
||||
<para>The following command tells
|
||||
<filename>devtool</filename> the recipe
|
||||
with which to work and uses
|
||||
<replaceable>srctree</replaceable> to point to the
|
||||
previously extracted source files:
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool modify <replaceable>recipe srctree</replaceable>
|
||||
</literallayout>
|
||||
Because <filename>devtool</filename> uses the
|
||||
<filename>conf/bblayers.conf</filename> to
|
||||
identify layers in which to look for recipes,
|
||||
you do not have to provide anything beyond a
|
||||
recipe's name with the command.
|
||||
In other words, you do not have to provide a
|
||||
full recipe pathname or provide any file naming
|
||||
extensions for <replaceable>recipe</replaceable>.
|
||||
</para>
|
||||
|
||||
<para>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.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Middle</emphasis>:
|
||||
The middle scenario represents a situation where
|
||||
the source code does not exist locally.
|
||||
In this case, the code is in an upstream Git
|
||||
repository and needs to be extracted to some
|
||||
local area.
|
||||
The recipe, in this scenario, is again in its own
|
||||
layer outside the workspace.</para>
|
||||
|
||||
<para>The following command tells
|
||||
<filename>devtool</filename> what recipe with
|
||||
which to work and also uses the "-x" option to
|
||||
instruct <filename>devtool</filename> to locate and
|
||||
extract the source code:
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool modify -x <replaceable>recipe srctree</replaceable>
|
||||
</literallayout>
|
||||
With the help of the
|
||||
<filename>conf/bblayers.conf</filename> file,
|
||||
<filename>devtool</filename>locates the recipe.
|
||||
Inside the recipe, the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
||||
variable points to where the source code and
|
||||
any local patch files from other developers are
|
||||
located.
|
||||
<note>
|
||||
You cannot provide an URL for
|
||||
<replaceable>srctree</replaceable> when using the
|
||||
<filename>devtool modify</filename> command.
|
||||
</note>
|
||||
Once the files are located, the command extracts
|
||||
them to the location specified by
|
||||
<replaceable>srctree</replaceable>.</para>
|
||||
|
||||
<para>Within workspace, <filename>devtool</filename>
|
||||
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 <replaceable>srctree</replaceable>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Right</emphasis>:
|
||||
The right scenario represents another situation
|
||||
where the source code does not exist locally
|
||||
and again needs to be extracted.
|
||||
However, in this situation, you want to extract the
|
||||
source into the workspace.
|
||||
The recipe, in this scenario, is again in its own
|
||||
layer outside the workspace.</para>
|
||||
|
||||
<para>The following command identifies the recipe
|
||||
and instructs <filename>devtool</filename> to
|
||||
extract the source files using the "-x" option:
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool modify -x <replaceable>recipe</replaceable>
|
||||
</literallayout>
|
||||
As with the previous example, the
|
||||
<filename>conf/bblayers.conf</filename> file
|
||||
helps locate the recipe.
|
||||
And, as with all extractions, the command uses
|
||||
the recipe's <filename>SRC_URI</filename> to locate the
|
||||
source files.
|
||||
With this scenario, however, since no
|
||||
<replaceable>srctree</replaceable> argument exists, the
|
||||
<filename>devtool modify</filename> command extracts the
|
||||
source files to a Git structure using the default
|
||||
location within the workspace.
|
||||
The result is that the command set up both the source
|
||||
code and an append file within the workspace with the
|
||||
recipe remaining in its original location.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Edit the Source</emphasis>:
|
||||
Once you have used the <filename>devtool modify</filename>
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Build the Recipe</emphasis>:
|
||||
Once you have updated the source files, you can build
|
||||
the recipe.
|
||||
You can either use <filename>devtool build</filename> or
|
||||
<filename>bitbake</filename>.
|
||||
Either method produces build output that is stored
|
||||
in
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Test Your Changes</emphasis>:
|
||||
Once your code is built, you can test it for
|
||||
correct operation.
|
||||
If you have actual hardware, you can use the
|
||||
<filename>devtool deploy-target</filename> command
|
||||
to put the build output on the target.
|
||||
If you do not have target hardware, you can deploy
|
||||
the output to QEMU where it can emulate the hardware:
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool deploy-target <replaceable>recipe target</replaceable>
|
||||
</literallayout>
|
||||
Regardless of where you are deploying the build
|
||||
output, the <replaceable>target</replaceable> must
|
||||
be running an SSH server.
|
||||
For example, to run the <filename>dropbear</filename>
|
||||
SSH server in an image you are going to be running on
|
||||
QEMU, be sure this statement is in your
|
||||
<filename>conf/local.conf</filename> file:
|
||||
<literallayout class='monospaced'>
|
||||
EXTRA_IMAGE_FEATURES += "ssh-server-dropbear"
|
||||
</literallayout>
|
||||
Here is a <filename>devtool deploy-target</filename>
|
||||
command example that uses the
|
||||
<filename>busybox</filename> recipe and QEMU as
|
||||
the target:
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool deploy-target busybox root@192.168.7.2
|
||||
</literallayout>
|
||||
<note>
|
||||
It is worth mentioning that you can load an image
|
||||
onto your <replaceable>target</replaceable> and
|
||||
while it is running, deploy your package build
|
||||
output to the target as the image is running.
|
||||
You can also rebuild your image using
|
||||
<filename>bitbake</filename> and it will pick up
|
||||
your new package output.
|
||||
From there, you could re-run the image on QEMU
|
||||
to see the effects of your
|
||||
<filename>devtool build</filename> output.
|
||||
</note>
|
||||
You can continue to change, build, and test your
|
||||
changes until you are satisfied with the code's
|
||||
behavior.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
|
||||
After you have debugged your changes, you can
|
||||
use <filename>devtool update-recipe</filename> to
|
||||
generate patch files for all the commits you have
|
||||
made.
|
||||
<note>
|
||||
Patch files are generated only for changes
|
||||
you have committed.
|
||||
</note>
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool update-recipe <replaceable>recipe</replaceable>
|
||||
</literallayout>
|
||||
By default, <filename>devtool</filename> updates
|
||||
the recipe's <filename>SRC_URI</filename> statement
|
||||
to include the location for the patch files it
|
||||
generates.
|
||||
<note>
|
||||
You can use the
|
||||
"--append <replaceable>LAYERDIR</replaceable>
|
||||
option to cause the command to create append files
|
||||
in a specific layer rather than the default
|
||||
recipe layer.
|
||||
</note>
|
||||
The command also creates a <replaceable>recipe</replaceable>
|
||||
folder beneath the folder in which the recipe resides
|
||||
that contains the actual <filename>*.patch</filename>
|
||||
files.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Make Sure the Recipe is in the Final Layer</emphasis>:
|
||||
Strictly speaking, this step is not necessary if
|
||||
you begin this workflow with the recipe in its own
|
||||
proper layer outside of the <filename>devtool</filename>
|
||||
workspace.
|
||||
However, it is included here so that when you do the
|
||||
final step following this you do not lose the recipe
|
||||
should it be in the workspace, which is possible
|
||||
(e.g. starting with <filename>devtool add</filename> to
|
||||
create a recipe in the workspace).</para>
|
||||
|
||||
<para>You should be sure that the recipe is located
|
||||
outside of the workspace before using the
|
||||
<filename>devtool reset</filename> command described in
|
||||
the next step.
|
||||
</para></listitem>
|
||||
<listitem><para><emphasis>Restore the Workspace</emphasis>:
|
||||
The <filename>devtool reset</filename> restores the
|
||||
state so that standard layers and upstream sources are
|
||||
used to build the recipe rather than what is in the
|
||||
workspace.
|
||||
Restoring the workspace removes all traces of the
|
||||
<replaceable>recipe</replaceable>.
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool reset <replaceable>recipe</replaceable>
|
||||
</literallayout>
|
||||
Once the workspace is restored, you can use it again for
|
||||
working on different code.
|
||||
</para></listitem>
|
||||
</orderedlist>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id='devtool-quick-reference'>
|
||||
|
|
|
|||
Loading…
Reference in New Issue