aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-09-19 12:30:02 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-09-28 15:02:31 +0100
commit38278f0a2162fbb0fda6d5b00d73495906acb968 (patch)
tree6d097fefa6c747605e4327c3e978f9795df2b306
parent54a10ca4b239909f948f7386c88dec03821c83e6 (diff)
downloadopenembedded-core-contrib-38278f0a2162fbb0fda6d5b00d73495906acb968.tar.gz
sdk-manual: Added the devtool upgrade command flow to the manual.
I needed a new figure and a new section. (From yocto-docs rev: d413ca7b9b946450af7c2c15ab0e68e9181517e9) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.pngbin0 -> 139827 bytes
-rw-r--r--documentation/sdk-manual/sdk-extensible.xml164
2 files changed, 164 insertions, 0 deletions
diff --git a/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
new file mode 100644
index 0000000000..65474dad02
--- /dev/null
+++ b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png
Binary files differ
diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index bb51683a44..67df1b0975 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -604,6 +604,170 @@
</orderedlist>
</para>
</section>
+
+ <section id='sdk-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/sdk-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>Finish Your Work With the Recipe</emphasis>:
+ The <filename>devtool finish</filename> command creates
+ any patches corresponding to commits in the local
+ Git repository, updates the recipe to point to them
+ (or creates a <filename>.bbappend</filename> file to do
+ so, depending on the specified destination layer), and
+ then resets the recipe so that the recipe is built normally
+ rather than from the workspace.
+ <literallayout class='monospaced'>
+ $ devtool finish <replaceable>recipe layer</replaceable>
+ </literallayout>
+ <note>
+ Any changes you want to turn into patches must be
+ committed to the Git repository in the source tree.
+ </note></para>
+ <para>Because there is no need to move the recipe,
+ <filename>devtool finish</filename> either updates the
+ original recipe in the original layer or the command
+ creates a <filename>.bbappend</filename> in a different
+ layer as provided by <replaceable>layer</replaceable>.
+ </para>
+ <para>As a final process of the
+ <filename>devtool finish</filename> 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.
+ <note>
+ You can use the <filename>devtool reset</filename>
+ 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.
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
</section>
<section id='sdk-a-closer-look-at-devtool-add'>