mirrors/poky
1
0
Fork 0
mirror of https://git.yoctoproject.org/poky synced 2026-05-30 12:29:55 +00:00
Code Issues Projects Releases Wiki Activity

sdk-manual: Updated devtool modify workflow section.

Browse Source 
I found this section a bit loosely worded and could result in
confusion to a user ramping up with YP.  I have done an extensive
rewrite focusing on exact wordings.

(From yocto-docs rev: af64c07d259e06fb13572fc224636ed240037b57)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
2018-05-03 14:29:25 -07:00
committed by Richard Purdie
parent d77de6b09f
commit dd0e423bfd
1 changed files with 124 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
documentation/sdk-manual/sdk-extensible.xml
+124 -95
View File
@@ -520,21 +520,20 @@
<para> <para>
The <filename>devtool modify</filename> command prepares the The <filename>devtool modify</filename> command prepares the
way to work on existing code that already has a recipe in way to work on existing code that already has a local recipe in
place. place that is used to build the software.
The command is flexible enough to allow you to extract code, The command is flexible enough to allow you to extract code
specify the existing recipe, and keep track of and gather any from an upstream source, specify the existing recipe, and
patch files from other developers that are keep track of and gather any patch files from other developers
associated with the code. that are associated with the code.
</para> </para>
<para> <para>
Depending on your particular scenario, the arguments and options Depending on your particular scenario, the arguments and options
you use with <filename>devtool modify</filename> form different you use with <filename>devtool modify</filename> form different
combinations. combinations.
The following diagram shows common development flows The following diagram shows common development flows for the
you would use with the <filename>devtool modify</filename> <filename>devtool modify</filename> command:
command:
</para> </para>
<para> <para>
@@ -543,140 +542,165 @@
<para> <para>
<orderedlist> <orderedlist>
<listitem><para><emphasis>Preparing to Modify the Code</emphasis>: <listitem><para>
<emphasis>Preparing to Modify the Code</emphasis>:
The top part of the flow shows three scenarios by which The top part of the flow shows three scenarios by which
you could use <filename>devtool modify</filename> to you could use <filename>devtool modify</filename> to
prepare to work on source files. prepare to work on source files.
Each scenario assumes the following: Each scenario assumes the following:
<itemizedlist> <itemizedlist>
<listitem><para>The recipe exists in some layer external <listitem><para>
The recipe exists locally in a layer external
to the <filename>devtool</filename> workspace. to the <filename>devtool</filename> workspace.
</para></listitem> </para></listitem>
<listitem><para>The source files exist upstream in an <listitem><para>
The source files exist either upstream in an
un-extracted state or locally in a previously un-extracted state or locally in a previously
extracted state. extracted state.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
The typical situation is where another developer has The typical situation is where another developer has
created some layer for use with the Yocto Project and created a layer for use with the Yocto Project and
their recipe already resides in that layer. their recipe already resides in that layer.
Furthermore, their source code is readily available Furthermore, their source code is readily available
either upstream or locally. either upstream or locally.
<itemizedlist> <itemizedlist>
<listitem><para><emphasis>Left</emphasis>: <listitem><para>
The left scenario represents a common situation <emphasis>Left</emphasis>:
where the source code does not exist locally The left scenario in the figure represents a
and needs to be extracted. 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 In this situation, the source is extracted
into the default workspace location. into the default <filename>devtool</filename>
workspace location.
The recipe, in this scenario, is in its own The recipe, in this scenario, is in its own
layer outside the workspace layer outside the workspace
(i.e. (i.e.
<filename>meta-</filename><replaceable>layername</replaceable>). <filename>meta-</filename><replaceable>layername</replaceable>).
</para> </para>
<para>The following command identifies the recipe <para>The following command identifies the
and by default extracts the source files: recipe and, by default, extracts the source
files:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ devtool modify <replaceable>recipe</replaceable> $ devtool modify <replaceable>recipe</replaceable>
</literallayout> </literallayout>
Once <filename>devtool</filename>locates the recipe, Once <filename>devtool</filename>locates the
it uses the recipe, <filename>devtool</filename> uses the
recipe's
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
variable to locate the source code and statements to locate the source code and any
any local patch files from other developers are local patch files from other developers.</para>
located.
<note> <para>With this scenario, no
You cannot provide an URL for <replaceable>srctree</replaceable> argument
<replaceable>srctree</replaceable> when using the exists.
<filename>devtool modify</filename> command. Consequently, the default behavior of the
</note> <filename>devtool modify</filename> command is
With this scenario, however, since no to extract the source files pointed to by the
<replaceable>srctree</replaceable> argument exists, the <filename>SRC_URI</filename> statements into a
<filename>devtool modify</filename> command by default local Git structure.
extracts the source files to a Git structure. Furthermore, the location for the extracted
Furthermore, the location for the extracted source is the source is the default area within the
default area within the workspace. <filename>devtool</filename> workspace.
The result is that the command sets up both the source The result is that the command sets up both
code and an append file within the workspace with the the source code and an append file within the
recipe remaining in its original location. workspace while the recipe remains in its
original location.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Middle</emphasis>: <listitem><para>
The middle scenario represents a situation where <emphasis>Middle</emphasis>:
the source code also does not exist locally. 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 In this case, the code is again upstream
and needs to be extracted to some and needs to be extracted to some
local area as a Git repository. local area as a Git repository.
The recipe, in this scenario, is again in its own The recipe, in this scenario, is again local
layer outside the workspace.</para> and in its own layer outside the workspace.
</para>
<para>The following command tells <para>The following command tells
<filename>devtool</filename> what recipe with <filename>devtool</filename> what recipe with
which to work and, in this case, identifies a local which to work and, in this case, identifies a
area for the extracted source files that is outside local area for the extracted source files that
of the default workspace: is outside of the default
<filename>devtool</filename> workspace:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ devtool modify <replaceable>recipe srctree</replaceable> $ devtool modify <replaceable>recipe srctree</replaceable>
</literallayout> </literallayout>
<note>
You cannot provide a URL for
<replaceable>srctree</replaceable> using
the <filename>devtool</filename> command.
</note>
As with all extractions, the command uses As with all extractions, the command uses
the recipe's <filename>SRC_URI</filename> to locate the the recipe's <filename>SRC_URI</filename>
source files. statements to locate the source files and any
Once the files are located, the command by default associated patch files.
extracts them. Once the files are located, the command by
Providing the <replaceable>srctree</replaceable> default extracts them into
argument instructs <filename>devtool</filename> where <replaceable>srctree</replaceable>.</para>
to place the extracted source.</para>
<para>Within workspace, <filename>devtool</filename> <para>Within workspace,
creates an append file for the recipe. <filename>devtool</filename> creates an append
file for the recipe.
The recipe remains in its original location but The recipe remains in its original location but
the source files are extracted to the location you the source files are extracted to the location
provided with <replaceable>srctree</replaceable>. you provide with
<replaceable>srctree</replaceable>.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Right</emphasis>: <listitem><para>
The right scenario represents a situation <emphasis>Right</emphasis>:
where the source tree The right scenario in the figure represents a
(<replaceable>srctree</replaceable>) exists as a situation where the source tree
previously extracted Git structure outside of (<replaceable>srctree</replaceable>) already
the <filename>devtool</filename> workspace. exists locally as a previously extracted Git
structure outside of the
<filename>devtool</filename> workspace.
In this example, the recipe also exists In this example, the recipe also exists
elsewhere in its own layer. elsewhere locally in its own layer.
</para> </para>
<para>The following command tells <para>The following command tells
<filename>devtool</filename> the recipe <filename>devtool</filename> the recipe
with which to work, uses the "-n" option to indicate with which to work, uses the "-n" option to
source does not need to be extracted, and uses indicate source does not need to be extracted,
<replaceable>srctree</replaceable> to point to the and uses <replaceable>srctree</replaceable> to
previously extracted source files: point to the previously extracted source files:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ devtool modify -n <replaceable>recipe srctree</replaceable> $ devtool modify -n <replaceable>recipe srctree</replaceable>
</literallayout> </literallayout>
</para> </para>
<para>Once the command finishes, it creates only <para>Once the command finishes, it creates only
an append file for the recipe in the workspace. an append file for the recipe in the
<filename>devtool</filename> workspace.
The recipe and the source code remain in their The recipe and the source code remain in their
original locations. original locations.
</para></listitem> </para></listitem>
</itemizedlist> </itemizedlist>
</para></listitem> </para></listitem>
<listitem><para><emphasis>Edit the Source</emphasis>: <listitem><para>
Once you have used the <filename>devtool modify</filename> <emphasis>Edit the Source</emphasis>:
command, you are free to make changes to the source Once you have used the
files. <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 You can use any editor you like to make and save
your source code modifications. your source code modifications.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Build the Recipe</emphasis>: <listitem><para>
<emphasis>Build the Recipe</emphasis>:
Once you have updated the source files, you can build Once you have updated the source files, you can build
the recipe. the recipe.
</para></listitem> </para></listitem>
<listitem><para><emphasis>Deploy the Build Output</emphasis>: <listitem><para>
<emphasis>Deploy the Build Output</emphasis>:
When you use the <filename>devtool build</filename> When you use the <filename>devtool build</filename>
command to build out your recipe, you probably want to see command to build out your recipe, you probably want to
if the resulting build output works as expected on target see if the resulting build output works as expected
hardware. on target hardware.
<note> <note>
This step assumes you have a previously built This step assumes you have a previously built
image that is already either running in QEMU or image that is already either running in QEMU or
@@ -686,19 +710,22 @@
the image is running on real hardware that you have the image is running on real hardware that you have
network access to and from your development machine. network access to and from your development machine.
</note> </note>
You can deploy your build output to that target hardware by You can deploy your build output to that target
using the <filename>devtool deploy-target</filename> command: hardware by using the
<filename>devtool deploy-target</filename> command:
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ devtool deploy-target <replaceable>recipe target</replaceable> $ devtool deploy-target <replaceable>recipe target</replaceable>
</literallayout> </literallayout>
The <replaceable>target</replaceable> is a live target machine The <replaceable>target</replaceable> is a live target
running as an SSH server.</para> machine running as an SSH server.</para>
<para>You can, of course, also deploy the image you build <para>You can, of course, use other methods to deploy
using the <filename>devtool build-image</filename> command the image you built using the
to actual hardware. <filename>devtool build-image</filename> command to
However, <filename>devtool</filename> does not provide a actual hardware.
specific command that allows you to do this. <filename>devtool</filename> does not provide
a specific command to deploy the image to actual
hardware.
</para></listitem> </para></listitem>
<listitem><para> <listitem><para>
<emphasis>Finish Your Work With the Recipe</emphasis>: <emphasis>Finish Your Work With the Recipe</emphasis>:
@@ -707,28 +734,30 @@
Git repository, updates the recipe to point to them Git repository, updates the recipe to point to them
(or creates a <filename>.bbappend</filename> file to do (or creates a <filename>.bbappend</filename> file to do
so, depending on the specified destination layer), and so, depending on the specified destination layer), and
then resets the recipe so that the recipe is built normally then resets the recipe so that the recipe is built
rather than from the workspace. normally rather than from the workspace.
<literallayout class='monospaced'> <literallayout class='monospaced'>
$ devtool finish <replaceable>recipe layer</replaceable> $ devtool finish <replaceable>recipe layer</replaceable>
</literallayout> </literallayout>
<note> <note>
Any changes you want to turn into patches must be Any changes you want to turn into patches must be
committed to the Git repository in the source tree. staged and committed within the local Git
repository before you use the
<filename>devtool finish</filename> command.
</note></para> </note></para>
<para>Because there is no need to move the recipe, <para>Because there is no need to move the recipe,
<filename>devtool finish</filename> either updates the <filename>devtool finish</filename> either updates the
original recipe in the original layer or the command original recipe in the original layer or the command
creates a <filename>.bbappend</filename> in a different creates a <filename>.bbappend</filename> file in a
layer as provided by <replaceable>layer</replaceable>. different layer as provided by
</para> <replaceable>layer</replaceable>.</para>
<para>As a final process of the <para>As a final process of the
<filename>devtool finish</filename> command, the state <filename>devtool finish</filename> command, the state
of the standard layers and the upstream source is of the standard layers and the upstream source is
restored so that you can build the recipe from those restored so that you can build the recipe from those
areas rather than the workspace. areas rather than from the workspace.
<note> <note>
You can use the <filename>devtool reset</filename> You can use the <filename>devtool reset</filename>
command to put things back should you decide you command to put things back should you decide you