dev-manual: Created devtool upgrade section.
Created the new section for the devtool upgrade flow. (From yocto-docs rev: f3a7f78305ce5045604d9892e18b31b7eabcba62) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
parent
b2b22d5eda
commit
70c7e36cb4
|
@ -6,10 +6,6 @@
|
||||||
|
|
||||||
<title>Common Development Models</title>
|
<title>Common Development Models</title>
|
||||||
|
|
||||||
<para role='writernotes'>
|
|
||||||
Test paragraph.
|
|
||||||
</para>
|
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Many development models exist for which you can use the Yocto Project.
|
Many development models exist for which you can use the Yocto Project.
|
||||||
This chapter overviews simple methods that use tools provided by the
|
This chapter overviews simple methods that use tools provided by the
|
||||||
|
@ -2213,6 +2209,175 @@
|
||||||
used to build the recipe rather than what is in the
|
used to build the recipe rather than what is in the
|
||||||
workspace.
|
workspace.
|
||||||
<literallayout class='monospaced'>
|
<literallayout class='monospaced'>
|
||||||
|
$ devtool reset <replaceable>recipe</replaceable>
|
||||||
|
</literallayout>
|
||||||
|
</para></listitem>
|
||||||
|
</orderedlist>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id='devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
|
||||||
|
<title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
The <filename>devtool upgrade</filename> command updates
|
||||||
|
an existing recipe so that you can build it for an updated
|
||||||
|
set of source files.
|
||||||
|
The command is flexible enough to allow you to specify
|
||||||
|
source code revision and versioning schemes, extract code into
|
||||||
|
or out of the <filename>devtool</filename> workspace, and
|
||||||
|
work with any source file forms that the fetchers support.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Depending on your particular scenario, the arguments and options
|
||||||
|
you use with <filename>devtool upgrade</filename> form different
|
||||||
|
combinations.
|
||||||
|
The following diagram shows a common development flow
|
||||||
|
you would use with the <filename>devtool modify</filename>
|
||||||
|
command:
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<imagedata fileref="figures/devtool-upgrade-flow.png" align="center" />
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<orderedlist>
|
||||||
|
<listitem><para><emphasis>Initiate the Upgrade</emphasis>:
|
||||||
|
The top part of the flow shows a typical scenario by which
|
||||||
|
you could use <filename>devtool upgrade</filename>.
|
||||||
|
The following conditions exist:
|
||||||
|
<itemizedlist>
|
||||||
|
<listitem><para>The recipe exists in some layer external
|
||||||
|
to the <filename>devtool</filename> workspace.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para>The source files for the new release
|
||||||
|
exist adjacent to the same location pointed to by
|
||||||
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
||||||
|
in the recipe (e.g. a tarball with the new version
|
||||||
|
number in the name, or as a different revision in
|
||||||
|
the upstream Git repository).
|
||||||
|
</para></listitem>
|
||||||
|
</itemizedlist>
|
||||||
|
A common situation is where third-party software has
|
||||||
|
undergone a revision so that it has been upgraded.
|
||||||
|
The recipe you have access to is likely in your own layer.
|
||||||
|
Thus, you need to upgrade the recipe to use the
|
||||||
|
newer version of the software:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ devtool upgrade -V <replaceable>version recipe</replaceable>
|
||||||
|
</literallayout>
|
||||||
|
By default, the <filename>devtool upgrade</filename> command
|
||||||
|
extracts source code into the <filename>sources</filename>
|
||||||
|
directory in the workspace.
|
||||||
|
If you want the code extracted to any other location, you
|
||||||
|
need to provide the <replaceable>srctree</replaceable>
|
||||||
|
positional argument with the command as follows:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
|
||||||
|
</literallayout>
|
||||||
|
Also, in this example, the "-V" option is used to specify
|
||||||
|
the new version.
|
||||||
|
If the source files pointed to by the
|
||||||
|
<filename>SRC_URI</filename> statement in the recipe are
|
||||||
|
in a Git repository, you must provide the "-S" option and
|
||||||
|
specify a revision for the software.</para>
|
||||||
|
|
||||||
|
<para>Once <filename>devtool</filename> locates the recipe,
|
||||||
|
it uses the <filename>SRC_URI</filename> variable to locate
|
||||||
|
the source code and any local patch files from other
|
||||||
|
developers are located.
|
||||||
|
The result is that the command sets up the source
|
||||||
|
code, the new version of the recipe, and an append file
|
||||||
|
all within the workspace.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
|
||||||
|
At this point, there could be some conflicts due to the
|
||||||
|
software being upgraded to a new version.
|
||||||
|
This would occur if your recipe specifies some patch files in
|
||||||
|
<filename>SRC_URI</filename> that conflict with changes
|
||||||
|
made in the new version of the software.
|
||||||
|
If this is the case, you need to resolve the conflicts
|
||||||
|
by editing the source and following the normal
|
||||||
|
<filename>git rebase</filename> conflict resolution
|
||||||
|
process.</para>
|
||||||
|
|
||||||
|
<para>Before moving onto the next step, be sure to resolve any
|
||||||
|
such conflicts created through use of a newer or different
|
||||||
|
version of the software.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para><emphasis>Build the Recipe</emphasis>:
|
||||||
|
Once you have your recipe in order, you can build it.
|
||||||
|
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>Deploy the Build Output</emphasis>:
|
||||||
|
When you use the <filename>devtool build</filename>
|
||||||
|
command or <filename>bitbake</filename> to build out your
|
||||||
|
recipe, you probably want to see if the resulting build
|
||||||
|
output works as expected on target hardware.
|
||||||
|
<note>
|
||||||
|
This step assumes you have a previously built
|
||||||
|
image that is already either running in QEMU or
|
||||||
|
running on actual hardware.
|
||||||
|
Also, it is assumed that for deployment of the image
|
||||||
|
to the target, SSH is installed in the image and if
|
||||||
|
the image is running on real hardware that you have
|
||||||
|
network access to and from your development machine.
|
||||||
|
</note>
|
||||||
|
You can deploy your build output to that target hardware by
|
||||||
|
using the <filename>devtool deploy-target</filename> command:
|
||||||
|
<literallayout class='monospaced'>
|
||||||
|
$ devtool deploy-target <replaceable>recipe target</replaceable>
|
||||||
|
</literallayout>
|
||||||
|
The <replaceable>target</replaceable> is a live target machine
|
||||||
|
running as an SSH server.</para>
|
||||||
|
|
||||||
|
<para>You can, of course, also deploy the image you build
|
||||||
|
using the <filename>devtool build-image</filename> command
|
||||||
|
to actual hardware.
|
||||||
|
However, <filename>devtool</filename> does not provide a
|
||||||
|
specific command that allows you to do this.
|
||||||
|
</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, the
|
||||||
|
<filename>devtool update-recipe</filename> command
|
||||||
|
creates the patch files in a folder named the same
|
||||||
|
as the recipe beneath the folder in which the recipe
|
||||||
|
resides, and updates the recipe's
|
||||||
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
||||||
|
statement to point to the generated patch files.
|
||||||
|
</para></listitem>
|
||||||
|
<listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
|
||||||
|
Before cleaning up the workspace, you need to move the
|
||||||
|
final recipe to its permanent layer.
|
||||||
|
You can either overwrite the original recipe or you can
|
||||||
|
overlay the upgraded recipe into a separate layer.
|
||||||
|
You must do this before using the
|
||||||
|
<filename>devtool reset</filename> command if you want to
|
||||||
|
retain the upgraded recipe.
|
||||||
|
</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.
|
||||||
|
<literallayout class='monospaced'>
|
||||||
$ devtool reset <replaceable>recipe</replaceable>
|
$ devtool reset <replaceable>recipe</replaceable>
|
||||||
</literallayout>
|
</literallayout>
|
||||||
</para></listitem>
|
</para></listitem>
|
||||||
|
@ -2256,24 +2421,27 @@
|
||||||
-h, --help show this help message and exit
|
-h, --help show this help message and exit
|
||||||
|
|
||||||
subcommands:
|
subcommands:
|
||||||
<subcommand>
|
Beginning work on a recipe:
|
||||||
create-workspace Set up workspace in an alternative location
|
add Add a new recipe
|
||||||
upgrade Upgrade an existing recipe
|
modify Modify the source for an existing recipe
|
||||||
deploy-target Deploy recipe output files to live target machine
|
upgrade Upgrade an existing recipe
|
||||||
undeploy-target Undeploy recipe output files in live target machine
|
Getting information:
|
||||||
search Search available recipes
|
status Show workspace status
|
||||||
build Build a recipe
|
search Search available recipes
|
||||||
edit-recipe Edit a recipe file in your workspace
|
Working on a recipe in the workspace:
|
||||||
configure-help Get help on configure script options
|
build Build a recipe
|
||||||
add Add a new recipe
|
edit-recipe Edit a recipe file in your workspace
|
||||||
modify Modify the source for an existing recipe
|
configure-help Get help on configure script options
|
||||||
extract Extract the source for an existing recipe
|
update-recipe Apply changes from external source tree to recipe
|
||||||
sync Synchronize the source tree for an existing recipe
|
reset Remove a recipe from your workspace
|
||||||
update-recipe Apply changes from external source tree to recipe
|
Testing changes on target:
|
||||||
status Show workspace status
|
deploy-target Deploy recipe output files to live target machine
|
||||||
reset Remove a recipe from your workspace
|
undeploy-target Undeploy recipe output files in live target machine
|
||||||
build-image Build image including workspace recipe packages
|
build-image Build image including workspace recipe packages
|
||||||
|
Advanced:
|
||||||
|
create-workspace Set up workspace in an alternative location
|
||||||
|
extract Extract the source for an existing recipe
|
||||||
|
sync Synchronize the source tree for an existing recipe
|
||||||
Use devtool <subcommand> --help to get help on a specific command
|
Use devtool <subcommand> --help to get help on a specific command
|
||||||
</literallayout>
|
</literallayout>
|
||||||
</para>
|
</para>
|
||||||
|
|
Loading…
Reference in New Issue