diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2016-09-19 12:30:02 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2016-09-28 15:02:31 +0100 |
commit | 38278f0a2162fbb0fda6d5b00d73495906acb968 (patch) | |
tree | 6d097fefa6c747605e4327c3e978f9795df2b306 | |
parent | 54a10ca4b239909f948f7386c88dec03821c83e6 (diff) | |
download | openembedded-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.png | bin | 0 -> 139827 bytes | |||
-rw-r--r-- | documentation/sdk-manual/sdk-extensible.xml | 164 |
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 Binary files differnew file mode 100644 index 0000000000..65474dad02 --- /dev/null +++ b/documentation/sdk-manual/figures/sdk-devtool-upgrade-flow.png 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'> |