mirror of
https://git.yoctoproject.org/poky
synced 2026-04-26 09:32:14 +02:00
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 <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark
committed by
Richard Purdie
Richard Purdie
parent
1e7735e290
commit
d39e9d1451
@@ -2113,6 +2113,55 @@
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-extracting-the-source-for-an-existing-recipe'>
|
||||
<title>Extracting the Source for an Existing Recipe</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool extract</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
<note>
|
||||
For complete syntax, use the
|
||||
<filename>devtool extract --help</filename> command.
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-synchronizing-a-recipes-extracted-source-tree'>
|
||||
<title>Synchronizing a Recipe's Extracted Source Tree</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool sync</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
<note>
|
||||
For complete syntax, use the
|
||||
<filename>devtool sync --help</filename> command.
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-modifying-a-recipe'>
|
||||
<title>Modifying an Existing Recipe</title>
|
||||
|
||||
@@ -2146,6 +2195,33 @@
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-edit-an-existing-recipe'>
|
||||
<title>Edit an Existing Recipe</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool edit-recipe</filename> command
|
||||
to run the default editor, which is identified using the
|
||||
<filename>EDITOR</filename> variable, on the specified recipe.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you use the <filename>devtool edit-recipe</filename>
|
||||
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 <filename>devtool add</filename> or
|
||||
<filename>devtool upgrade</filename> 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.
|
||||
<note>
|
||||
For complete syntax, use the
|
||||
<filename>devtool edit-recipe --help</filename> command.
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-updating-a-recipe'>
|
||||
<title>Updating a Recipe</title>
|
||||
|
||||
@@ -2199,6 +2275,36 @@
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-upgrading-a-recipe'>
|
||||
<title>Upgrading a Recipe</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool upgrade</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you use the <filename>devtool upgrade</filename> 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
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>),
|
||||
the source revision to which you want to upgrade (i.e. the
|
||||
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>,
|
||||
whether or not to apply patches, and so forth.
|
||||
<note>
|
||||
For complete syntax, use the
|
||||
<filename>devtool upgrade --help</filename> command.
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-resetting-a-recipe'>
|
||||
<title>Resetting a Recipe</title>
|
||||
|
||||
@@ -2227,15 +2333,22 @@
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-building-your-software'>
|
||||
<title>Building Your Software</title>
|
||||
<section id='devtool-building-your-recipe'>
|
||||
<title>Building Your Recipe</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool build</filename> command to cause the
|
||||
OpenEmbedded build system to build your software based
|
||||
on the recipe file.
|
||||
OpenEmbedded build system to build your recipe.
|
||||
The <filename>devtool build</filename> command is equivalent to
|
||||
<filename>bitbake -c populate_sysroot</filename>.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you use the <filename>devtool build</filename> 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:
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool build <replaceable>recipe</replaceable>
|
||||
@@ -2244,8 +2357,25 @@
|
||||
For complete syntax, use the
|
||||
<filename>devtool build --help</filename> command.
|
||||
</note>
|
||||
Building your software using <filename>devtool build</filename>
|
||||
is identical to using BitBake to build the software.
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-building-your-image'>
|
||||
<title>Building Your Image</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool build-image</filename> command
|
||||
to build an image, extending it to include packages from
|
||||
recipes in the workspace.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you use the <filename>devtool build-image</filename>
|
||||
command, you must supply the name of the image.
|
||||
This command has no command line options:
|
||||
<literallayout class='monospaced'>
|
||||
$ devtool build-image <replaceable>image</replaceable>
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
@@ -2345,6 +2475,49 @@
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-get-the-status-of-the-recipes-in-your-workspace'>
|
||||
<title>Get the Status of the Recipes in Your Workspace</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool status</filename> command to
|
||||
list the recipes currently in your workspace.
|
||||
Information includes the paths to their respective
|
||||
external source trees.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>devtool status</filename> command has no
|
||||
command-line options:
|
||||
<literallayout class='monospaced'>
|
||||
devtool status
|
||||
</literallayout>
|
||||
</para>
|
||||
</section>
|
||||
|
||||
<section id='devtool-search-for-available-target-recipes'>
|
||||
<title>Search for Available Target Recipes</title>
|
||||
|
||||
<para>
|
||||
Use the <filename>devtool search</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
When you use the <filename>devtool search</filename> command,
|
||||
you must supply a <replaceable>keyword</replaceable>.
|
||||
The command uses the <replaceable>keyword</replaceable> when
|
||||
searching for a match.
|
||||
<note>
|
||||
For complete syntax, use the
|
||||
<filename>devtool search --help</filename> command.
|
||||
</note>
|
||||
</para>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section id="using-a-quilt-workflow">
|
||||
|
||||
@@ -993,11 +993,13 @@
|
||||
|
||||
<para>
|
||||
The image generation process consists of several stages and
|
||||
depends on many variables.
|
||||
depends on several tasks and variables.
|
||||
The
|
||||
<link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
|
||||
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:
|
||||
<itemizedlist>
|
||||
<listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
|
||||
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.
|
||||
</para></listitem>
|
||||
<listitem><para><link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>:
|
||||
The final list of packages passed to the package manager
|
||||
for installation into the image.
|
||||
</para></listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
|
||||
<para>
|
||||
With
|
||||
<link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
|
||||
pointing to the location of the filesystem under construction and
|
||||
the <filename>PACKAGE_INSTALL</filename> variable providing the
|
||||
final list of packages to install, the root file system is
|
||||
created.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
|
||||
all the post installation scripts must succeed during the
|
||||
@@ -1042,24 +1055,17 @@
|
||||
</para>
|
||||
|
||||
<para>
|
||||
During Optimization, optimizing processes are run across
|
||||
the image.
|
||||
These processes include <filename>mklibs</filename> and
|
||||
<filename>prelink</filename>.
|
||||
The <filename>mklibs</filename> process optimizes the size
|
||||
of the libraries.
|
||||
A <filename>prelink</filename> process optimizes the dynamic
|
||||
linking of shared libraries to reduce start up time of
|
||||
executables.
|
||||
The final stages of the <filename>do_rootfs</filename> task
|
||||
handle post processing.
|
||||
Post processing includes creation of a manifest file and
|
||||
optimizations.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Along with writing out the root filesystem image, the
|
||||
<filename>do_rootfs</filename> task creates a manifest file
|
||||
(<filename>.manifest</filename>) 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 (<filename>.manifest</filename>) 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
|
||||
<link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
|
||||
class, for example, to determine whether or not to run
|
||||
specific tests.
|
||||
@@ -1069,21 +1075,54 @@
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
<filename>mklibs</filename>, <filename>prelink</filename>,
|
||||
and any other post-processing commands as defined by the
|
||||
<link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>
|
||||
variable.
|
||||
The <filename>mklibs</filename> process optimizes the size
|
||||
of the libraries, while the
|
||||
<filename>prelink</filename> process optimizes the dynamic
|
||||
linking of shared libraries to reduce start up time of
|
||||
executables.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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 <filename>do_image</filename> task.
|
||||
The build system runs any pre-processing commands as defined
|
||||
by the
|
||||
<link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link>
|
||||
variable.
|
||||
This variable specifies a list of functions to call before
|
||||
the OpenEmbedded build system creates the final image output
|
||||
files.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The <filename>do_image</filename> task dynamically creates
|
||||
other <filename>do_image_*</filename> 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
|
||||
<link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
|
||||
variable.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The final task involved in image creation is the
|
||||
<filename>do_image_complete</filename> task.
|
||||
This task completes the image by applying any image
|
||||
post processing as defined through the
|
||||
<link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>
|
||||
variable.
|
||||
The variable specifies a list of functions to call once the
|
||||
OpenEmbedded build system has created the final image output
|
||||
files.
|
||||
</para>
|
||||
|
||||
<note>
|
||||
The entire image generation process is run under Pseudo.
|
||||
Running under Pseudo ensures that the files in the root
|
||||
|
||||
Reference in New Issue
Block a user