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:
parent
1eecaea70d
commit
7699f0ab60
|
@ -1952,6 +1952,281 @@
|
||||||
</orderedlist>
|
</orderedlist>
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</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>
|
||||||
|
|
||||||
<section id='devtool-quick-reference'>
|
<section id='devtool-quick-reference'>
|
||||||
|
|
Loading…
Reference in New Issue