diff --git a/documentation/sdk-manual/sdk-extensible.xml b/documentation/sdk-manual/sdk-extensible.xml
index 4303054cba..3a99b3791b 100644
--- a/documentation/sdk-manual/sdk-extensible.xml
+++ b/documentation/sdk-manual/sdk-extensible.xml
@@ -520,21 +520,20 @@
The devtool modify command prepares the
- way to work on existing code that already has a recipe in
- place.
- The command is flexible enough to allow you to extract code,
- specify the existing recipe, and keep track of and gather any
- patch files from other developers that are
- associated with the code.
+ way to work on existing code that already has a local recipe in
+ place that is used to build the software.
+ The command is flexible enough to allow you to extract code
+ from an upstream source, specify the existing recipe, and
+ keep track of and gather any patch files from other developers
+ that are associated with the code.
Depending on your particular scenario, the arguments and options
you use with devtool modify form different
combinations.
- The following diagram shows common development flows
- you would use with the devtool modify
- command:
+ The following diagram shows common development flows for the
+ devtool modify command:
@@ -543,140 +542,165 @@
- Preparing to Modify the Code:
+
+ Preparing to Modify the Code:
The top part of the flow shows three scenarios by which
you could use devtool modify to
prepare to work on source files.
Each scenario assumes the following:
- The recipe exists in some layer external
+
+ The recipe exists locally in a layer external
to the devtool workspace.
- The source files exist upstream in an
+
+ The source files exist either upstream in an
un-extracted state or locally in a previously
extracted state.
The typical situation is where another developer has
- created some layer for use with the Yocto Project and
+ created a layer for use with the Yocto Project and
their recipe already resides in that layer.
Furthermore, their source code is readily available
either upstream or locally.
- Left:
- The left scenario represents a common situation
- where the source code does not exist locally
- and needs to be extracted.
+
+ Left:
+ The left scenario in the figure represents a
+ common situation where the source code does
+ not exist locally and it needs to be extracted
+ from an upstream source.
In this situation, the source is extracted
- into the default workspace location.
+ into the default devtool
+ workspace location.
The recipe, in this scenario, is in its own
layer outside the workspace
(i.e.
meta-layername).
- The following command identifies the recipe
- and by default extracts the source files:
+ The following command identifies the
+ recipe and, by default, extracts the source
+ files:
$ devtool modify recipe
- Once devtoollocates the recipe,
- it uses the
+ Once devtoollocates the
+ recipe, devtool uses the
+ recipe's
SRC_URI
- variable to locate the source code and
- any local patch files from other developers are
- located.
-
- You cannot provide an URL for
- srctree when using the
- devtool modify command.
-
- With this scenario, however, since no
- srctree argument exists, the
- devtool modify command by default
- extracts the source files to a Git structure.
- Furthermore, the location for the extracted source is the
- default area within the workspace.
- The result is that the command sets up both the source
- code and an append file within the workspace with the
- recipe remaining in its original location.
+ statements to locate the source code and any
+ local patch files from other developers.
+
+ With this scenario, no
+ srctree argument
+ exists.
+ Consequently, the default behavior of the
+ devtool modify command is
+ to extract the source files pointed to by the
+ SRC_URI statements into a
+ local Git structure.
+ Furthermore, the location for the extracted
+ source is the default area within the
+ devtool workspace.
+ The result is that the command sets up both
+ the source code and an append file within the
+ workspace while the recipe remains in its
+ original location.
- Middle:
- The middle scenario represents a situation where
- the source code also does not exist locally.
+
+ Middle:
+ The middle scenario in the figure represents a
+ situation where the source code also does not
+ exist locally.
In this case, the code is again upstream
and needs to be extracted to some
local area as a Git repository.
- The recipe, in this scenario, is again in its own
- layer outside the workspace.
+ The recipe, in this scenario, is again local
+ and in its own layer outside the workspace.
+
The following command tells
devtool what recipe with
- which to work and, in this case, identifies a local
- area for the extracted source files that is outside
- of the default workspace:
+ which to work and, in this case, identifies a
+ local area for the extracted source files that
+ is outside of the default
+ devtool workspace:
$ devtool modify recipe srctree
+
+ You cannot provide a URL for
+ srctree using
+ the devtool command.
+
As with all extractions, the command uses
- the recipe's SRC_URI to locate the
- source files.
- Once the files are located, the command by default
- extracts them.
- Providing the srctree
- argument instructs devtool where
- to place the extracted source.
+ the recipe's SRC_URI
+ statements to locate the source files and any
+ associated patch files.
+ Once the files are located, the command by
+ default extracts them into
+ srctree.
- Within workspace, devtool
- creates an append file for the recipe.
+ Within workspace,
+ devtool creates an append
+ file for the recipe.
The recipe remains in its original location but
- the source files are extracted to the location you
- provided with srctree.
+ the source files are extracted to the location
+ you provide with
+ srctree.
- Right:
- The right scenario represents a situation
- where the source tree
- (srctree) exists as a
- previously extracted Git structure outside of
- the devtool workspace.
+
+ Right:
+ The right scenario in the figure represents a
+ situation where the source tree
+ (srctree) already
+ exists locally as a previously extracted Git
+ structure outside of the
+ devtool workspace.
In this example, the recipe also exists
- elsewhere in its own layer.
+ elsewhere locally in its own layer.
The following command tells
devtool the recipe
- with which to work, uses the "-n" option to indicate
- source does not need to be extracted, and uses
- srctree to point to the
- previously extracted source files:
+ with which to work, uses the "-n" option to
+ indicate source does not need to be extracted,
+ and uses srctree to
+ point to the previously extracted source files:
$ devtool modify -n recipe srctree
Once the command finishes, it creates only
- an append file for the recipe in the workspace.
+ an append file for the recipe in the
+ devtool workspace.
The recipe and the source code remain in their
original locations.
- Edit the Source:
- Once you have used the devtool modify
- command, you are free to make changes to the source
- files.
+
+ Edit the Source:
+ Once you have used the
+ devtool modify command, you are
+ free to make changes to the source files.
You can use any editor you like to make and save
your source code modifications.
- Build the Recipe:
+
+ Build the Recipe:
Once you have updated the source files, you can build
the recipe.
- Deploy the Build Output:
+
+ Deploy the Build Output:
When you use the devtool build
- command 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.
This step assumes you have a previously built
image that is already either running in QEMU or
@@ -686,19 +710,22 @@
the image is running on real hardware that you have
network access to and from your development machine.
- You can deploy your build output to that target hardware by
- using the devtool deploy-target command:
+ You can deploy your build output to that target
+ hardware by using the
+ devtool deploy-target command:
$ devtool deploy-target recipe target
- The target is a live target machine
- running as an SSH server.
+ The target is a live target
+ machine running as an SSH server.
- You can, of course, also deploy the image you build
- using the devtool build-image command
- to actual hardware.
- However, devtool does not provide a
- specific command that allows you to do this.
+ You can, of course, use other methods to deploy
+ the image you built using the
+ devtool build-image command to
+ actual hardware.
+ devtool does not provide
+ a specific command to deploy the image to actual
+ hardware.
Finish Your Work With the Recipe:
@@ -707,28 +734,30 @@
Git repository, updates the recipe to point to them
(or creates a .bbappend 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.
+ then resets the recipe so that the recipe is built
+ normally rather than from the workspace.
$ devtool finish recipe layer
Any changes you want to turn into patches must be
- committed to the Git repository in the source tree.
+ staged and committed within the local Git
+ repository before you use the
+ devtool finish command.
Because there is no need to move the recipe,
devtool finish either updates the
original recipe in the original layer or the command
- creates a .bbappend in a different
- layer as provided by layer.
-
+ creates a .bbappend file in a
+ different layer as provided by
+ layer.
As a final process of the
devtool finish 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.
+ areas rather than from the workspace.
You can use the devtool reset
command to put things back should you decide you