[gnome-continuous-yocto/gnomeostree-3.28-rocko: 2648/8267] dev-manual: Updated add and modify flows and text.
- From: Emmanuele Bassi <ebassi src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-continuous-yocto/gnomeostree-3.28-rocko: 2648/8267] dev-manual: Updated add and modify flows and text.
- Date: Sat, 16 Dec 2017 23:31:31 +0000 (UTC)
commit 5ec03cd359332d87f2fd4f4542a58dea1600ec96
Author: Scott Rifenbark <srifenbark gmail com>
Date: Fri Sep 16 09:49:24 2016 -0700
dev-manual: Updated add and modify flows and text.
Updated the devtool add and devtool modify flow diagrams and
supporting text to exactly match those from the SDK manual.
Also, updated the help output generated from the devtool --help
and devtool add --help commands.
(From yocto-docs rev: 002297a8ed3979f012fe228b7edb77514e7528a2)
Signed-off-by: Scott Rifenbark <srifenbark gmail com>
Signed-off-by: Richard Purdie <richard purdie linuxfoundation org>
documentation/dev-manual/dev-manual-model.xml | 161 +++++++++----------
.../dev-manual/figures/devtool-add-flow.png | Bin 179361 -> 177945 bytes
.../dev-manual/figures/devtool-modify-flow.png | Bin 152662 -> 164192 bytes
3 files changed, 76 insertions(+), 85 deletions(-)
---
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index ff44a3f..dcff37e 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -649,13 +649,13 @@
</para>
<section id='use-devtool-to-integrate-new-code'>
- <title>Use <filename>devtool add</filename> to Integrate New Code</title>
+ <title>Use <filename>devtool add</filename> to Add an Application</title>
<para>
The <filename>devtool add</filename> command generates
a new recipe based on existing source code.
This command takes advantage of the
- <link linkend='devtool-the-workspace-layer-structure'>workspace</link>
+ <ulink url='&YOCTO_DOCS_DEV_URL;#devtool-the-workspace-layer-structure'>workspace</ulink>
layer that many <filename>devtool</filename> commands
use.
The command is flexible enough to allow you to extract source
@@ -721,7 +721,8 @@
and needs to be extracted to some
local area - this time outside of the default
workspace.
- As always, if required <filename>devtool</filename> creates
+ If required, <filename>devtool</filename>
+ always creates
a Git repository locally during the extraction.
Furthermore, the first positional argument
<replaceable>srctree</replaceable> in this case
@@ -788,10 +789,6 @@
<para>If you need to take the build output and eventually
move it to the target hardware, you would use
<filename>devtool build</filename>:
- <note>
- You could use <filename>bitbake</filename> to build
- the recipe as well.
- </note>
<literallayout class='monospaced'>
$ devtool build <replaceable>recipe</replaceable>
</literallayout></para>
@@ -831,49 +828,44 @@
However, <filename>devtool</filename> does not provide a
specific command that allows you to do this.
</para></listitem>
- <listitem><para><emphasis>Optionally Update the Recipe With Patch Files</emphasis>:
- Once you are satisfied with the recipe, if you have made
- any changes to the source tree that you want to have
- applied by the recipe, you need to generate patches
- from those changes.
- You do this before moving the recipe
- to its final layer and cleaning up the workspace area
- <filename>devtool</filename> uses.
- This optional step is especially relevant if you are
- using or adding third-party software.</para>
- <para>To convert commits created using Git to patch files,
- use the <filename>devtool update-recipe</filename> command.
+ <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, moves the new recipe to a more permanent
+ 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>As mentioned, the <filename>devtool finish</filename>
+ command moves the final recipe to its permanent layer.
+ </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>
- <literallayout class='monospaced'>
- $ devtool update-recipe <replaceable>recipe</replaceable>
- </literallayout>
- </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 must do this before using the
- <filename>devtool reset</filename> command if you want to
- retain the recipe.
- </para></listitem>
- <listitem><para><emphasis>Reset the Recipe</emphasis>:
- As a final step, you can restore the state such that
- standard layers and the upstream source is used to build
- the recipe rather than data in the workspace.
- To reset the recipe, use the <filename>devtool reset</filename>
- command:
- <literallayout class='monospaced'>
- $ devtool reset <replaceable>recipe</replaceable>
- </literallayout>
</para></listitem>
</orderedlist>
</para>
</section>
<section id='devtool-use-devtool-modify-to-enable-work-on-code-associated-with-an-existing-recipe'>
- <title>Use <filename>devtool modify</filename> to Enable Work on Code Associated with an
Existing Recipe</title>
+ <title>Use <filename>devtool modify</filename> to Modify the Source of an Existing
Component</title>
<para>
The <filename>devtool modify</filename> command prepares the
@@ -1028,17 +1020,12 @@
<listitem><para><emphasis>Build the Recipe</emphasis>:
Once you have updated the source files, you can build
the recipe.
- 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.
+ command 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
@@ -1062,42 +1049,43 @@
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>
+ <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 update-recipe <replaceable>recipe</replaceable>
+ $ devtool finish <replaceable>recipe layer</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.
<note>
- You can use the
- "--append <replaceable>LAYERDIR</replaceable>"
- option to cause the command to create append files
- in a specific layer rather than the default
- recipe layer.
+ 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>
- <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>
@@ -1297,7 +1285,7 @@
OpenEmbedded development tool
- optional arguments:
+ options:
--basepath BASEPATH Base directory of SDK / build directory
--bbpath BBPATH Explicitly specify the BBPATH, rather than getting it
from the metadata
@@ -1315,11 +1303,12 @@
status Show workspace status
search Search available recipes
Working on a recipe in the workspace:
- build Build a recipe
edit-recipe Edit a recipe file in your workspace
configure-help Get help on configure script options
+ build Build a recipe
update-recipe Apply changes from external source tree to recipe
reset Remove a recipe from your workspace
+ finish Finish working on a recipe in your workspace
Testing changes on target:
deploy-target Deploy recipe output files to live target machine
undeploy-target Undeploy recipe output files in live target machine
@@ -1339,14 +1328,14 @@
<literallayout class='monospaced'>
$ devtool add --help
usage: devtool add [-h] [--same-dir | --no-same-dir] [--fetch URI]
- [--version VERSION] [--no-git] [--binary] [--also-native]
- [--src-subdir SUBDIR]
+ [--version VERSION] [--no-git] [--autorev] [--binary]
+ [--also-native] [--src-subdir SUBDIR]
[recipename] [srctree] [fetchuri]
Adds a new recipe to the workspace to build a specified source tree. Can
optionally fetch a remote URI and unpack it to create the source tree.
- positional arguments:
+ arguments:
recipename Name for new recipe to add (just name - no version,
path or extension). If not specified, will attempt to
auto-detect it.
@@ -1357,7 +1346,7 @@
fetchuri Fetch the specified URI and extract it to create the
source tree
- optional arguments:
+ options:
-h, --help show this help message and exit
--same-dir, -s Build in same directory as source
--no-same-dir Force build in a separate build directory
@@ -1368,6 +1357,8 @@
Version to use within recipe (PV)
--no-git, -g If fetching source, do not set up source tree as a git
repository
+ --autorev, -a When fetching from a git repository, set SRCREV in the
+ recipe to a floating revision instead of fixed
--binary, -b Treat the source tree as something that should be
installed verbatim (no compilation, same directory
structure). Useful with binary packages e.g. RPMs.
diff --git a/documentation/dev-manual/figures/devtool-add-flow.png
b/documentation/dev-manual/figures/devtool-add-flow.png
index c09e60e..985ac33 100644
Binary files a/documentation/dev-manual/figures/devtool-add-flow.png and
b/documentation/dev-manual/figures/devtool-add-flow.png differ
diff --git a/documentation/dev-manual/figures/devtool-modify-flow.png
b/documentation/dev-manual/figures/devtool-modify-flow.png
index cd7f4d0..fd684ff 100644
Binary files a/documentation/dev-manual/figures/devtool-modify-flow.png and
b/documentation/dev-manual/figures/devtool-modify-flow.png differ
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
