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'>

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 @@
604	</orderedlist>	604	</orderedlist>
605	</para>	605	</para>
606	</section>	606	</section>
		607
		608	<section id='sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
		609	<title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
		610
		611	<para>
		612	The <filename>devtool upgrade</filename> command updates
		613	an existing recipe so that you can build it for an updated
		614	set of source files.
		615	The command is flexible enough to allow you to specify
		616	source code revision and versioning schemes, extract code into
		617	or out of the <filename>devtool</filename> workspace, and
		618	work with any source file forms that the fetchers support.
		619	</para>
		620
		621	<para>
		622	Depending on your particular scenario, the arguments and options
		623	you use with <filename>devtool upgrade</filename> form different
		624	combinations.
		625	The following diagram shows a common development flow
		626	you would use with the <filename>devtool modify</filename>
		627	command:
		628	</para>
		629
		630	<para>
		631	<imagedata fileref="figures/sdk-devtool-upgrade-flow.png" align="center" />
		632	</para>
		633
		634	<para>
		635	<orderedlist>
		636	<listitem><para><emphasis>Initiate the Upgrade</emphasis>:
		637	The top part of the flow shows a typical scenario by which
		638	you could use <filename>devtool upgrade</filename>.
		639	The following conditions exist:
		640	<itemizedlist>
		641	<listitem><para>The recipe exists in some layer external
		642	to the <filename>devtool</filename> workspace.
		643	</para></listitem>
		644	<listitem><para>The source files for the new release
		645	exist adjacent to the same location pointed to by
		646	<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
		647	in the recipe (e.g. a tarball with the new version
		648	number in the name, or as a different revision in
		649	the upstream Git repository).
		650	</para></listitem>
		651	</itemizedlist>
		652	A common situation is where third-party software has
		653	undergone a revision so that it has been upgraded.
		654	The recipe you have access to is likely in your own layer.
		655	Thus, you need to upgrade the recipe to use the
		656	newer version of the software:
		657	<literallayout class='monospaced'>
		658	$ devtool upgrade -V <replaceable>version recipe</replaceable>
		659	</literallayout>
		660	By default, the <filename>devtool upgrade</filename> command
		661	extracts source code into the <filename>sources</filename>
		662	directory in the workspace.
		663	If you want the code extracted to any other location, you
		664	need to provide the <replaceable>srctree</replaceable>
		665	positional argument with the command as follows:
		666	<literallayout class='monospaced'>
		667	$ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
		668	</literallayout>
		669	Also, in this example, the "-V" option is used to specify
		670	the new version.
		671	If the source files pointed to by the
		672	<filename>SRC_URI</filename> statement in the recipe are
		673	in a Git repository, you must provide the "-S" option and
		674	specify a revision for the software.</para>
		675
		676	<para>Once <filename>devtool</filename> locates the recipe,
		677	it uses the <filename>SRC_URI</filename> variable to locate
		678	the source code and any local patch files from other
		679	developers are located.
		680	The result is that the command sets up the source
		681	code, the new version of the recipe, and an append file
		682	all within the workspace.
		683	</para></listitem>
		684	<listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
		685	At this point, there could be some conflicts due to the
		686	software being upgraded to a new version.
		687	This would occur if your recipe specifies some patch files in
		688	<filename>SRC_URI</filename> that conflict with changes
		689	made in the new version of the software.
		690	If this is the case, you need to resolve the conflicts
		691	by editing the source and following the normal
		692	<filename>git rebase</filename> conflict resolution
		693	process.</para>
		694	<para>Before moving onto the next step, be sure to resolve any
		695	such conflicts created through use of a newer or different
		696	version of the software.
		697	</para></listitem>
		698	<listitem><para><emphasis>Build the Recipe</emphasis>:
		699	Once you have your recipe in order, you can build it.
		700	You can either use <filename>devtool build</filename> or
		701	<filename>bitbake</filename>.
		702	Either method produces build output that is stored
		703	in
		704	<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
		705	</para></listitem>
		706	<listitem><para><emphasis>Deploy the Build Output</emphasis>:
		707	When you use the <filename>devtool build</filename>
		708	command or <filename>bitbake</filename> to build out your
		709	recipe, you probably want to see if the resulting build
		710	output works as expected on target hardware.
		711	<note>
		712	This step assumes you have a previously built
		713	image that is already either running in QEMU or
		714	running on actual hardware.
		715	Also, it is assumed that for deployment of the image
		716	to the target, SSH is installed in the image and if
		717	the image is running on real hardware that you have
		718	network access to and from your development machine.
		719	</note>
		720	You can deploy your build output to that target hardware by
		721	using the <filename>devtool deploy-target</filename> command:
		722	<literallayout class='monospaced'>
		723	$ devtool deploy-target <replaceable>recipe target</replaceable>
		724	</literallayout>
		725	The <replaceable>target</replaceable> is a live target machine
		726	running as an SSH server.</para>
		727	<para>You can, of course, also deploy the image you build
		728	using the <filename>devtool build-image</filename> command
		729	to actual hardware.
		730	However, <filename>devtool</filename> does not provide a
		731	specific command that allows you to do this.
		732	</para></listitem>
		733	<listitem><para>
		734	<emphasis>Finish Your Work With the Recipe</emphasis>:
		735	The <filename>devtool finish</filename> command creates
		736	any patches corresponding to commits in the local
		737	Git repository, updates the recipe to point to them
		738	(or creates a <filename>.bbappend</filename> file to do
		739	so, depending on the specified destination layer), and
		740	then resets the recipe so that the recipe is built normally
		741	rather than from the workspace.
		742	<literallayout class='monospaced'>
		743	$ devtool finish <replaceable>recipe layer</replaceable>
		744	</literallayout>
		745	<note>
		746	Any changes you want to turn into patches must be
		747	committed to the Git repository in the source tree.
		748	</note></para>
		749	<para>Because there is no need to move the recipe,
		750	<filename>devtool finish</filename> either updates the
		751	original recipe in the original layer or the command
		752	creates a <filename>.bbappend</filename> in a different
		753	layer as provided by <replaceable>layer</replaceable>.
		754	</para>
		755	<para>As a final process of the
		756	<filename>devtool finish</filename> command, the state
		757	of the standard layers and the upstream source is
		758	restored so that you can build the recipe from those
		759	areas rather than the workspace.
		760	<note>
		761	You can use the <filename>devtool reset</filename>
		762	command to put things back should you decide you
		763	do not want to proceed with your work.
		764	If you do use this command, realize that the source
		765	tree is preserved.
		766	</note>
		767	</para></listitem>
		768	</orderedlist>
		769	</para>
		770	</section>
607	</section>	771	</section>
608		772
609	<section id='sdk-a-closer-look-at-devtool-add'>	773	<section id='sdk-a-closer-look-at-devtool-add'>