1 files changed, 190 insertions, 22 deletions
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index d71021da36..ff74063fc3 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -6,10 +6,6 @@
 <title>Common Development Models</title>
-<para role='writernotes'>
-    Test paragraph.
-</para>
 <para>
    Many development models exist for which you can use the Yocto Project.
    This chapter overviews simple methods that use tools provided by the
@@ -2219,6 +2215,175 @@
                </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>
+                        </literallayout>
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
    </section>
    <section id='devtool-quick-reference'>
@@ -2256,24 +2421,27 @@
       -h, --help           show this help message and exit
     subcommands:
-       &lt;subcommand&gt;
+       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 &lt;subcommand&gt; --help to get help on a specific command
                </literallayout>
            </para>

diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml index d71021da36..ff74063fc3 100644 --- a/documentation/dev-manual/dev-manual-model.xml +++ b/documentation/dev-manual/dev-manual-model.xml
@@ -6,10 +6,6 @@
6		6
7	<title>Common Development Models</title>	7	<title>Common Development Models</title>
8		8
9	<para role='writernotes'>
10	Test paragraph.
11	</para>
12
13	<para>	9	<para>
14	Many development models exist for which you can use the Yocto Project.	10	Many development models exist for which you can use the Yocto Project.
15	This chapter overviews simple methods that use tools provided by the	11	This chapter overviews simple methods that use tools provided by the
@@ -2219,6 +2215,175 @@
2219	</orderedlist>	2215	</orderedlist>
2220	</para>	2216	</para>
2221	</section>	2217	</section>
		2218
		2219	<section id='devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>
		2220	<title>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</title>
		2221
		2222	<para>
		2223	The <filename>devtool upgrade</filename> command updates
		2224	an existing recipe so that you can build it for an updated
		2225	set of source files.
		2226	The command is flexible enough to allow you to specify
		2227	source code revision and versioning schemes, extract code into
		2228	or out of the <filename>devtool</filename> workspace, and
		2229	work with any source file forms that the fetchers support.
		2230	</para>
		2231
		2232	<para>
		2233	Depending on your particular scenario, the arguments and options
		2234	you use with <filename>devtool upgrade</filename> form different
		2235	combinations.
		2236	The following diagram shows a common development flow
		2237	you would use with the <filename>devtool modify</filename>
		2238	command:
		2239	</para>
		2240
		2241	<para>
		2242	<imagedata fileref="figures/devtool-upgrade-flow.png" align="center" />
		2243	</para>
		2244
		2245	<para>
		2246	<orderedlist>
		2247	<listitem><para><emphasis>Initiate the Upgrade</emphasis>:
		2248	The top part of the flow shows a typical scenario by which
		2249	you could use <filename>devtool upgrade</filename>.
		2250	The following conditions exist:
		2251	<itemizedlist>
		2252	<listitem><para>The recipe exists in some layer external
		2253	to the <filename>devtool</filename> workspace.
		2254	</para></listitem>
		2255	<listitem><para>The source files for the new release
		2256	exist adjacent to the same location pointed to by
		2257	<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
		2258	in the recipe (e.g. a tarball with the new version
		2259	number in the name, or as a different revision in
		2260	the upstream Git repository).
		2261	</para></listitem>
		2262	</itemizedlist>
		2263	A common situation is where third-party software has
		2264	undergone a revision so that it has been upgraded.
		2265	The recipe you have access to is likely in your own layer.
		2266	Thus, you need to upgrade the recipe to use the
		2267	newer version of the software:
		2268	<literallayout class='monospaced'>
		2269	$ devtool upgrade -V <replaceable>version recipe</replaceable>
		2270	</literallayout>
		2271	By default, the <filename>devtool upgrade</filename> command
		2272	extracts source code into the <filename>sources</filename>
		2273	directory in the workspace.
		2274	If you want the code extracted to any other location, you
		2275	need to provide the <replaceable>srctree</replaceable>
		2276	positional argument with the command as follows:
		2277	<literallayout class='monospaced'>
		2278	$ devtool upgrade -V <replaceable>version recipe srctree</replaceable>
		2279	</literallayout>
		2280	Also, in this example, the "-V" option is used to specify
		2281	the new version.
		2282	If the source files pointed to by the
		2283	<filename>SRC_URI</filename> statement in the recipe are
		2284	in a Git repository, you must provide the "-S" option and
		2285	specify a revision for the software.</para>
		2286
		2287	<para>Once <filename>devtool</filename> locates the recipe,
		2288	it uses the <filename>SRC_URI</filename> variable to locate
		2289	the source code and any local patch files from other
		2290	developers are located.
		2291	The result is that the command sets up the source
		2292	code, the new version of the recipe, and an append file
		2293	all within the workspace.
		2294	</para></listitem>
		2295	<listitem><para><emphasis>Resolve any Conflicts created by the Upgrade</emphasis>:
		2296	At this point, there could be some conflicts due to the
		2297	software being upgraded to a new version.
		2298	This would occur if your recipe specifies some patch files in
		2299	<filename>SRC_URI</filename> that conflict with changes
		2300	made in the new version of the software.
		2301	If this is the case, you need to resolve the conflicts
		2302	by editing the source and following the normal
		2303	<filename>git rebase</filename> conflict resolution
		2304	process.</para>
		2305
		2306	<para>Before moving onto the next step, be sure to resolve any
		2307	such conflicts created through use of a newer or different
		2308	version of the software.
		2309	</para></listitem>
		2310	<listitem><para><emphasis>Build the Recipe</emphasis>:
		2311	Once you have your recipe in order, you can build it.
		2312	You can either use <filename>devtool build</filename> or
		2313	<filename>bitbake</filename>.
		2314	Either method produces build output that is stored
		2315	in
		2316	<ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>.
		2317	</para></listitem>
		2318	<listitem><para><emphasis>Deploy the Build Output</emphasis>:
		2319	When you use the <filename>devtool build</filename>
		2320	command or <filename>bitbake</filename> to build out your
		2321	recipe, you probably want to see if the resulting build
		2322	output works as expected on target hardware.
		2323	<note>
		2324	This step assumes you have a previously built
		2325	image that is already either running in QEMU or
		2326	running on actual hardware.
		2327	Also, it is assumed that for deployment of the image
		2328	to the target, SSH is installed in the image and if
		2329	the image is running on real hardware that you have
		2330	network access to and from your development machine.
		2331	</note>
		2332	You can deploy your build output to that target hardware by
		2333	using the <filename>devtool deploy-target</filename> command:
		2334	<literallayout class='monospaced'>
		2335	$ devtool deploy-target <replaceable>recipe target</replaceable>
		2336	</literallayout>
		2337	The <replaceable>target</replaceable> is a live target machine
		2338	running as an SSH server.</para>
		2339
		2340	<para>You can, of course, also deploy the image you build
		2341	using the <filename>devtool build-image</filename> command
		2342	to actual hardware.
		2343	However, <filename>devtool</filename> does not provide a
		2344	specific command that allows you to do this.
		2345	</para></listitem>
		2346	<listitem><para><emphasis>Optionally Create Patch Files for Your Changes</emphasis>:
		2347	After you have debugged your changes, you can
		2348	use <filename>devtool update-recipe</filename> to
		2349	generate patch files for all the commits you have
		2350	made.
		2351	<note>
		2352	Patch files are generated only for changes
		2353	you have committed.
		2354	</note>
		2355	<literallayout class='monospaced'>
		2356	$ devtool update-recipe <replaceable>recipe</replaceable>
		2357	</literallayout>
		2358	By default, the
		2359	<filename>devtool update-recipe</filename> command
		2360	creates the patch files in a folder named the same
		2361	as the recipe beneath the folder in which the recipe
		2362	resides, and updates the recipe's
		2363	<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
		2364	statement to point to the generated patch files.
		2365	</para></listitem>
		2366	<listitem><para><emphasis>Move the Recipe to its Permanent Layer</emphasis>:
		2367	Before cleaning up the workspace, you need to move the
		2368	final recipe to its permanent layer.
		2369	You can either overwrite the original recipe or you can
		2370	overlay the upgraded recipe into a separate layer.
		2371	You must do this before using the
		2372	<filename>devtool reset</filename> command if you want to
		2373	retain the upgraded recipe.
		2374	</para></listitem>
		2375	<listitem><para><emphasis>Restore the Workspace</emphasis>:
		2376	The <filename>devtool reset</filename> restores the
		2377	state so that standard layers and upstream sources are
		2378	used to build the recipe rather than what is in the
		2379	workspace.
		2380	<literallayout class='monospaced'>
		2381	$ devtool reset <replaceable>recipe</replaceable>
		2382	</literallayout>
		2383	</para></listitem>
		2384	</orderedlist>
		2385	</para>
		2386	</section>
2222	</section>	2387	</section>
2223		2388
2224	<section id='devtool-quick-reference'>	2389	<section id='devtool-quick-reference'>
@@ -2256,24 +2421,27 @@
2256	-h, --help show this help message and exit	2421	-h, --help show this help message and exit
2257		2422
2258	subcommands:	2423	subcommands:
2259	<subcommand>	2424	Beginning work on a recipe:
2260	create-workspace Set up workspace in an alternative location	2425	add Add a new recipe
2261	upgrade Upgrade an existing recipe	2426	modify Modify the source for an existing recipe
2262	deploy-target Deploy recipe output files to live target machine	2427	upgrade Upgrade an existing recipe
2263	undeploy-target Undeploy recipe output files in live target machine	2428	Getting information:
2264	search Search available recipes	2429	status Show workspace status
2265	build Build a recipe	2430	search Search available recipes
2266	edit-recipe Edit a recipe file in your workspace	2431	Working on a recipe in the workspace:
2267	configure-help Get help on configure script options	2432	build Build a recipe
2268	add Add a new recipe	2433	edit-recipe Edit a recipe file in your workspace
2269	modify Modify the source for an existing recipe	2434	configure-help Get help on configure script options
2270	extract Extract the source for an existing recipe	2435	update-recipe Apply changes from external source tree to recipe
2271	sync Synchronize the source tree for an existing recipe	2436	reset Remove a recipe from your workspace
2272	update-recipe Apply changes from external source tree to recipe	2437	Testing changes on target:
2273	status Show workspace status	2438	deploy-target Deploy recipe output files to live target machine
2274	reset Remove a recipe from your workspace	2439	undeploy-target Undeploy recipe output files in live target machine
2275	build-image Build image including workspace recipe packages	2440	build-image Build image including workspace recipe packages
2276		2441	Advanced:
		2442	create-workspace Set up workspace in an alternative location
		2443	extract Extract the source for an existing recipe
		2444	sync Synchronize the source tree for an existing recipe
2277	Use devtool <subcommand> --help to get help on a specific command	2445	Use devtool <subcommand> --help to get help on a specific command
2278	</literallayout>	2446	</literallayout>
2279	</para>	2447	</para>