From d39e9d1451c316083aee809fee22c539d4b8869d Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Tue, 19 Jan 2016 05:26:02 -0800 Subject: ref-manual: Rewrite of "Image Generation" and devtool text. Rewrite of devtool reference section. This was a separate commit but got squashed wrong so it ended up with this commit. The changes to "Image Generation" section reflect the new, more detailed image generation figure (From yocto-docs rev: 827c6872b88c17d2d0c8d44b1024fff19076e505) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/dev-manual/dev-manual-model.xml | 185 +++++++++++++++++++++++++- documentation/ref-manual/closer-look.xml | 103 +++++++++----- 2 files changed, 250 insertions(+), 38 deletions(-) (limited to 'documentation') 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 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. - After the root filesystem has been constructed, the image - generation process turns everything into an image file or - a set of image 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 -- cgit 1.2.3-korg