diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
index ec11824a56..f82a489fac 100644
--- a/documentation/dev-manual/dev-manual-model.xml
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -2113,6 +2113,55 @@
+
+ Extracting the Source for an Existing Recipe
+
+
+ Use the devtool extract command to
+ extract the source for an existing recipe.
+ When you use this command, you must supply the root name
+ of the recipe (i.e. no version, paths, or extensions), and
+ you must supply the directory to which you want the source
+ extracted.
+
+
+
+ Additional command options let you control the name of a
+ development branch into which you can checkout the source
+ and whether or not to keep a temporary directory, which is
+ useful for debugging.
+
+ For complete syntax, use the
+ devtool extract --help command.
+
+
+
+
+
+ Synchronizing a Recipe's Extracted Source Tree
+
+
+ Use the devtool sync command to
+ synchronize a previously extracted source tree for an
+ existing recipe.
+ When you use this command, you must supply the root name
+ of the recipe (i.e. no version, paths, or extensions), and
+ you must supply the directory to which you want the source
+ extracted.
+
+
+
+ Additional command options let you control the name of a
+ development branch into which you can checkout the source
+ and whether or not to keep a temporary directory, which is
+ useful for debugging.
+
+ For complete syntax, use the
+ devtool sync --help command.
+
+
+
+
Modifying an Existing Recipe
@@ -2146,6 +2195,33 @@
+
+ Edit an Existing Recipe
+
+
+ Use the devtool edit-recipe command
+ to run the default editor, which is identified using the
+ EDITOR variable, on the specified recipe.
+
+
+
+ When you use the devtool edit-recipe
+ command, you must supply the root name of the recipe
+ (i.e. no version, paths, or extensions).
+ Also, the recipe file itself must reside in the workspace
+ as a result of the devtool add or
+ devtool upgrade commands.
+ However, you can override that requirement by using the
+ "-a" or "--any-recipe" option.
+ Using either of these options allows you to edit any recipe
+ regardless of its location.
+
+ For complete syntax, use the
+ devtool edit-recipe --help command.
+
+
+
+
Updating a Recipe
@@ -2199,6 +2275,36 @@
+
+ Upgrading a Recipe
+
+
+ Use the devtool upgrade command
+ to upgrade an existing recipe to a new upstream version.
+ The command puts the upgraded recipe file into the
+ workspace along with any associated files, and extracts
+ the source tree to a specified location should patches
+ need rebased or added to as a result of the upgrade.
+
+
+
+ When you use the devtool upgrade command,
+ you must supply the root name of the recipe (i.e. no version,
+ paths, or extensions), and you must supply the directory
+ to which you want the source extracted.
+ Additional command options let you control things such as
+ the version number to which you want to upgrade (i.e. the
+ PV),
+ the source revision to which you want to upgrade (i.e. the
+ SRCREV,
+ whether or not to apply patches, and so forth.
+
+ For complete syntax, use the
+ devtool upgrade --help command.
+
+
+
+
Resetting a Recipe
@@ -2227,15 +2333,22 @@
-
- Building Your Software
+
+ Building Your Recipe
Use the devtool build command to cause the
- OpenEmbedded build system to build your software based
- on the recipe file.
+ OpenEmbedded build system to build your recipe.
The devtool build command is equivalent to
bitbake -c populate_sysroot.
+
+
+
+ When you use the devtool build command,
+ you must supply the root name of the recipe (i.e. no version,
+ paths, or extensions).
+ You can use either the "-s" or the "--disable-parallel-make"
+ option to disable parallel makes during the build.
Here is an example:
$ devtool build recipe
@@ -2244,8 +2357,25 @@
For complete syntax, use the
devtool build --help command.
- Building your software using devtool build
- is identical to using BitBake to build the software.
+
+
+
+
+ Building Your Image
+
+
+ Use the devtool build-image command
+ to build an image, extending it to include packages from
+ recipes in the workspace.
+
+
+
+ When you use the devtool build-image
+ command, you must supply the name of the image.
+ This command has no command line options:
+
+ $ devtool build-image image
+
@@ -2345,6 +2475,49 @@
+
+
+ Get the Status of the Recipes in Your Workspace
+
+
+ Use the devtool status command to
+ list the recipes currently in your workspace.
+ Information includes the paths to their respective
+ external source trees.
+
+
+
+ The devtool status command has no
+ command-line options:
+
+ devtool status
+
+
+
+
+
+ Search for Available Target Recipes
+
+
+ Use the devtool search command to
+ search for available target recipes.
+ The command matches the recipe name, package name,
+ description, and installed files.
+ The command displays the recipe name as a result of a
+ match.
+
+
+
+ When you use the devtool search command,
+ you must supply a keyword.
+ The command uses the keyword when
+ searching for a match.
+
+ For complete syntax, use the
+ devtool search --help command.
+
+
+
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index bb7624c9e8..c05972e9ec 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -993,11 +993,13 @@
The image generation process consists of several stages and
- depends on many variables.
+ depends on several tasks and variables.
The
do_rootfs
- task uses these key variables
- to help create the list of packages to actually install:
+ task creates the root filesystem (file and directory structure)
+ for an image.
+ This task uses several key variables to help create the list
+ of packages to actually install:
IMAGE_INSTALL:
Lists out the base set of packages to install from
@@ -1017,9 +1019,22 @@
Determines the language(s) for which additional
language support packages are installed.
+ PACKAGE_INSTALL:
+ The final list of packages passed to the package manager
+ for installation into the image.
+
+
+ With
+ IMAGE_ROOTFS
+ pointing to the location of the filesystem under construction and
+ the PACKAGE_INSTALL variable providing the
+ final list of packages to install, the root file system is
+ created.
+
+
Package installation is under control of the package manager
(e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
@@ -1027,13 +1042,11 @@
At the end of the process, if package management is not
enabled for the target, the package manager's data files
are deleted from the root filesystem.
-
-
-
- During image generation, the build system attempts to run
- all post-installation scripts.
- Any that fail to run on the build host are run on the
- target when the target system is first booted.
+ As part of the final stage of package installation, postinstall
+ scripts that are part of the packages are run.
+ Any scripts that fail to run
+ on the build host are run on the target when the target system
+ is first booted.
If you are using a
read-only root filesystem,
all the post installation scripts must succeed during the
@@ -1042,24 +1055,17 @@
- During Optimization, optimizing processes are run across
- the image.
- These processes include mklibs and
- prelink.
- The mklibs process optimizes the size
- of the libraries.
- A prelink process optimizes the dynamic
- linking of shared libraries to reduce start up time of
- executables.
+ The final stages of the do_rootfs task
+ handle post processing.
+ Post processing includes creation of a manifest file and
+ optimizations.
- Along with writing out the root filesystem image, the
- do_rootfs task creates a manifest file
- (.manifest) in the same directory as
- the root filesystem image that lists out, line-by-line, the
- installed packages.
- This manifest file is useful for the
+ The manifest file (.manifest) resides
+ in the same directory as the root filesystem image.
+ This file lists out, line-by-line, the installed packages.
+ The manifest file is useful for the
testimage
class, for example, to determine whether or not to run
specific tests.
@@ -1069,21 +1075,54 @@
- Part of the image generation process includes compressing the
- root filesystem image.
- Compression is accomplished through several optimization
- routines designed to reduce the overall size of the image.
+ Optimizing processes run across the image include
+ mklibs, prelink,
+ and any other post-processing commands as defined by the
+ ROOTFS_POSTPROCESS_COMMAND
+ variable.
+ The mklibs process optimizes the size
+ of the libraries, while the
+ prelink process optimizes the dynamic
+ linking of shared libraries to reduce start up time of
+ executables.
- After the root filesystem has been constructed, the image
- generation process turns everything into an image file or
- a set of image files.
+ After the root filesystem is built, processing begins on
+ the image through the do_image task.
+ The build system runs any pre-processing commands as defined
+ by the
+ IMAGE_PREPROCESS_COMMAND
+ variable.
+ This variable specifies a list of functions to call before
+ the OpenEmbedded build system creates the final image output
+ files.
+
+
+
+ The do_image task dynamically creates
+ other do_image_* tasks as needed, which
+ include compressing the root filesystem image to reduce the
+ overall size of the image.
+ The process turns everything into an image file or a set of
+ image files.
The formats used for the root filesystem depend on the
IMAGE_FSTYPES
variable.
+
+ The final task involved in image creation is the
+ do_image_complete task.
+ This task completes the image by applying any image
+ post processing as defined through the
+ IMAGE_POSTPROCESS_COMMAND
+ variable.
+ The variable specifies a list of functions to call once the
+ OpenEmbedded build system has created the final image output
+ files.
+
+
The entire image generation process is run under Pseudo.
Running under Pseudo ensures that the files in the root