Yocto 2.5
Move OpenBMC to Yocto 2.5(sumo)
Signed-off-by: Brad Bishop <bradleyb@fuzziesquirrel.com>
Change-Id: I5c5ad6904a16e14c1c397f0baf10c9d465594a78
diff --git a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml
index 0081738..fe1bfba 100644
--- a/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/import-layers/yocto-poky/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -22,90 +22,24 @@
multiple layers.
Layers allow you to isolate different types of customizations from
each other.
- You might find it tempting to keep everything in one layer when
- working on a single project.
- However, the more modular your Metadata, the easier
- it is to cope with future changes.
+ For introductory information on the Yocto Project Layer Model,
+ see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#the-yocto-project-layer-model'>The Yocto Project Layer Model</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
- <para>
- To illustrate how layers are used to keep things modular, consider
- machine customizations.
- These types of customizations typically reside in a special layer,
- rather than a general layer, called a Board Support Package (BSP)
- Layer.
- Furthermore, the machine customizations should be isolated from
- recipes and Metadata that support a new GUI environment,
- for example.
- This situation gives you a couple of layers: one for the machine
- configurations, and one for the GUI environment.
- It is important to understand, however, that the BSP layer can
- still make machine-specific additions to recipes within the GUI
- environment layer without polluting the GUI layer itself
- with those machine-specific changes.
- You can accomplish this through a recipe that is a BitBake append
- (<filename>.bbappend</filename>) file, which is described later
- in this section.
- <note>
- For general information on BSP layer structure, see the
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp'>Board Support Packages (BSP) - Developer's Guide</ulink>.
- </note>
- </para>
-
- <para>
- </para>
-
- <section id='yocto-project-layers'>
- <title>Layers</title>
-
- <para>
- The <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- contains both general layers and BSP
- layers right out of the box.
- You can easily identify layers that ship with a
- Yocto Project release in the Source Directory by their
- folder names.
- Folders that represent layers typically have names that begin with
- the string <filename>meta-</filename>.
- <note>
- It is not a requirement that a layer name begin with the
- prefix <filename>meta-</filename>, but it is a commonly
- accepted standard in the Yocto Project community.
- </note>
- For example, when you set up the Source Directory structure,
- you will see several layers:
- <filename>meta</filename>,
- <filename>meta-skeleton</filename>,
- <filename>meta-selftest</filename>,
- <filename>meta-poky</filename>, and
- <filename>meta-yocto-bsp</filename>.
- Each of these folders represents a distinct layer.
- </para>
-
- <para>
- As another example, if you set up a local copy of the
- <filename>meta-intel</filename> Git repository
- and then explore the folder of that general layer,
- you will discover many Intel-specific BSP layers inside.
- For more information on BSP layers, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
- section in the Yocto Project Board Support Package (BSP)
- Developer's Guide.
- </para>
- </section>
-
<section id='creating-your-own-layer'>
<title>Creating Your Own Layer</title>
<para>
It is very easy to create your own layers to use with the
OpenEmbedded build system.
- The Yocto Project ships with scripts that speed up creating
- general layers and BSP layers.
+ The Yocto Project ships with tools that speed up creating
+ layers.
This section describes the steps you perform by hand to create
- a layer so that you can better understand them.
- For information about the layer-creation scripts, see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
+ layers so that you can better understand them.
+ For information about the layer-creation tools, see the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
section in the Yocto Project Board Support Package (BSP)
Developer's Guide and the
"<link linkend='creating-a-general-layer-using-the-bitbake-layers-script'>Creating a General Layer Using the <filename>bitbake-layers</filename> Script</link>"
@@ -113,40 +47,70 @@
</para>
<para>
- Follow these general steps to create your layer without the aid of a script:
+ Follow these general steps to create your layer without using
+ tools:
<orderedlist>
- <listitem><para><emphasis>Check Existing Layers:</emphasis>
+ <listitem><para>
+ <emphasis>Check Existing Layers:</emphasis>
Before creating a new layer, you should be sure someone
has not already created a layer containing the Metadata
you need.
You can see the
- <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
+ <ulink url='http://layers.openembedded.org/layerindex/layers/'>OpenEmbedded Metadata Index</ulink>
for a list of layers from the OpenEmbedded community
that can be used in the Yocto Project.
+ You could find a layer that is identical or close to
+ what you need.
</para></listitem>
- <listitem><para><emphasis>Create a Directory:</emphasis>
+ <listitem><para>
+ <emphasis>Create a Directory:</emphasis>
Create the directory for your layer.
- While not strictly required, prepend the name of the
- folder with the string <filename>meta-</filename>.
+ When you create the layer, be sure to create the
+ directory in an area not associated with the
+ Yocto Project
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (e.g. the cloned <filename>poky</filename> repository).
+ </para>
+
+ <para>While not strictly required, prepend the name of
+ the directory with the string "meta-".
For example:
<literallayout class='monospaced'>
meta-mylayer
meta-GUI_xyz
meta-mymachine
</literallayout>
+ With rare exceptions, a layer's name follows this
+ form:
+ <literallayout class='monospaced'>
+ meta-<replaceable>root_name</replaceable>
+ </literallayout>
+ Following this layer naming convention can
+ save you trouble later when tools, components, or
+ variables "assume" your layer name begins with "meta-".
+ A notable example is in configuration files as
+ shown in the following step where layer names without
+ the "meta-" string are appended
+ to several variables used in the configuration.
</para></listitem>
- <listitem><para><emphasis>Create a Layer Configuration
- File:</emphasis>
- Inside your new layer folder, you need to create a
- <filename>conf/layer.conf</filename> file.
- It is easiest to take an existing layer configuration
- file and copy that to your layer's
- <filename>conf</filename> directory and then modify the
- file as needed.</para>
- <para>The
- <filename>meta-yocto-bsp/conf/layer.conf</filename> file
- demonstrates the required syntax:
- <literallayout class='monospaced'>
+ <listitem><para id='dev-layer-config-file-description'>
+ <emphasis>Create a Layer Configuration File:</emphasis>
+ Inside your new layer folder, you need to create a
+ <filename>conf/layer.conf</filename> file.
+ It is easiest to take an existing layer configuration
+ file and copy that to your layer's
+ <filename>conf</filename> directory and then modify the
+ file as needed.</para>
+
+ <para>The
+ <filename>meta-yocto-bsp/conf/layer.conf</filename> file
+ in the Yocto Project
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta-yocto-bsp/conf'>Source Repositories</ulink>
+ demonstrates the required syntax.
+ For your layer, you need to replace "yoctobsp" with
+ a unique identifier for your layer (e.g. "machinexyz"
+ for a layer named "meta-machinexyz"):
+ <literallayout class='monospaced'>
# We have a conf and classes directory, add to BBPATH
BBPATH .= ":${LAYERDIR}"
@@ -157,75 +121,82 @@
BBFILE_COLLECTIONS += "yoctobsp"
BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
BBFILE_PRIORITY_yoctobsp = "5"
- LAYERVERSION_yoctobsp = "3"
- </literallayout></para>
- <para>Here is an explanation of the example:
+ LAYERVERSION_yoctobsp = "4"
+ LAYERSERIES_COMPAT_yoctobsp = "&DISTRO_NAME_NO_CAP;"
+ </literallayout>
+ Following is an explanation of the layer configuration
+ file:
<itemizedlist>
- <listitem><para>The configuration and
- classes directory is appended to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
- <note>
- All non-distro layers, which include all BSP
- layers, are expected to append the layer
- directory to the
- <filename>BBPATH</filename>.
- On the other hand, distro layers, such as
- <filename>meta-poky</filename>, can choose
- to enforce their own precedence over
- <filename>BBPATH</filename>.
- For an example of that syntax, see the
- <filename>layer.conf</filename> file for
- the <filename>meta-poky</filename> layer.
- </note></para></listitem>
- <listitem><para>The recipes for the layers are
- appended to
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>:
+ Adds the layer's root directory to BitBake's
+ search path.
+ Through the use of the
+ <filename>BBPATH</filename> variable, BitBake
+ locates class files
+ (<filename>.bbclass</filename>),
+ configuration files, and files that are
+ included with <filename>include</filename> and
+ <filename>require</filename> statements.
+ For these cases, BitBake uses the first file
+ that matches the name found in
+ <filename>BBPATH</filename>.
+ This is similar to the way the
+ <filename>PATH</filename> variable is used for
+ binaries.
+ It is recommended, therefore, that you use
+ unique class and configuration filenames in
+ your custom layer.
</para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
- variable is then appended with the layer name.
- </para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
- variable is set to a regular expression and is
- used to match files from
- <filename>BBFILES</filename> into a particular
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'><filename>BBFILES</filename></ulink>:
+ Defines the location for all recipes in the
layer.
- In this case,
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
- is used to make <filename>BBFILE_PATTERN</filename> match within the
- layer's path.</para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
- variable then assigns a priority to the layer.
- Applying priorities is useful in situations
- where the same recipe might appear in multiple
- layers and allows you to choose the layer
- that takes precedence.</para></listitem>
- <listitem><para>The
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
- variable optionally specifies the version of a
- layer as a single number.</para></listitem>
- </itemizedlist></para>
- <para>Note the use of the
- <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
- variable, which expands to the directory of the current
- layer.</para>
- <para>Through the use of the <filename>BBPATH</filename>
- variable, BitBake locates class files
- (<filename>.bbclass</filename>),
- configuration files, and files that are included
- with <filename>include</filename> and
- <filename>require</filename> statements.
- For these cases, BitBake uses the first file that
- matches the name found in <filename>BBPATH</filename>.
- This is similar to the way the <filename>PATH</filename>
- variable is used for binaries.
- It is recommended, therefore, that you use unique
- class and configuration
- filenames in your custom layer.</para></listitem>
- <listitem><para><emphasis>Add Content:</emphasis> Depending
- on the type of layer, add the content.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'><filename>BBFILE_COLLECTIONS</filename></ulink>:
+ Establishes the current layer through a
+ unique identifier that is used throughout the
+ OpenEmbedded build system to refer to the layer.
+ In this example, the identifier "yoctobsp" is
+ the representation for the container layer
+ named "meta-yocto-bsp".
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'><filename>BBFILE_PATTERN</filename></ulink>:
+ Expands immediately during parsing to
+ provide the directory of the layer.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>:
+ Establishes a priority to use for
+ recipes in the layer when the OpenEmbedded build
+ finds recipes of the same name in different
+ layers.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'><filename>LAYERVERSION</filename></ulink>:
+ Establishes a version number for the layer.
+ You can use this version number to specify this
+ exact version of the layer as a dependency when
+ using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></ulink>
+ variable.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERSERIES_COMPAT'><filename>LAYERSERIES_COMPAT</filename></ulink>:
+ Lists the
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Releases'>Yocto Project</ulink>
+ releases for which the current version is
+ compatible.
+ This variable is a good way to indicate how
+ up-to-date your particular layer is.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Add Content:</emphasis>
+ Depending on the type of layer, add the content.
If the layer adds support for a machine, add the machine
configuration in a <filename>conf/machine/</filename>
file within the layer.
@@ -235,9 +206,13 @@
If the layer introduces new recipes, put the recipes
you need in <filename>recipes-*</filename>
subdirectories within the layer.
- <note>In order to be compliant with the Yocto Project,
- a layer must contain a
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
+ <note>
+ For an explanation of layer hierarchy that
+ is compliant with the Yocto Project, see
+ the
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
+ section in the Yocto Project Board
+ Support Package (BSP) Developer's Guide.
</note>
</para></listitem>
<listitem><para>
@@ -492,7 +467,7 @@
acceptable explanation for any questions answered "No".
</para></listitem>
<listitem><para>
- You need to be a Yocto Project Member Organization.
+ Be a Yocto Project Member Organization.
</para></listitem>
</itemizedlist>
</para>
@@ -562,7 +537,7 @@
</para>
<para>
- The script divides tests into three areas: COMMON, BSD,
+ The script divides tests into three areas: COMMON, BSP,
and DISTRO.
For example, given a distribution layer (DISTRO), the
layer must pass both the COMMON and DISTRO related tests.
@@ -646,23 +621,26 @@
The following example shows how to enable a layer named
<filename>meta-mylayer</filename>:
<literallayout class='monospaced'>
- LCONF_VERSION = "6"
+ # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
+ # changes incompatibly
+ POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
BBLAYERS ?= " \
- $HOME/poky/meta \
- $HOME/poky/meta-poky \
- $HOME/poky/meta-yocto-bsp \
- $HOME/poky/meta-mylayer \
+ /home/<replaceable>user</replaceable>/poky/meta \
+ /home/<replaceable>user</replaceable>/poky/meta-poky \
+ /home/<replaceable>user</replaceable>/poky/meta-yocto-bsp \
+ /home/<replaceable>user</replaceable>/poky/meta-mylayer \
"
</literallayout>
</para>
<para>
BitBake parses each <filename>conf/layer.conf</filename> file
- as specified in the <filename>BBLAYERS</filename> variable
+ from the top down as specified in the
+ <filename>BBLAYERS</filename> variable
within the <filename>conf/bblayers.conf</filename> file.
During the processing of each
<filename>conf/layer.conf</filename> file, BitBake adds the
@@ -840,8 +818,7 @@
<para>
To specify the layer's priority manually, use the
<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
- variable.
- For example:
+ variable and append the layer's root name:
<literallayout class='monospaced'>
BBFILE_PRIORITY_mylayer = "1"
</literallayout>
@@ -862,7 +839,8 @@
<title>Managing Layers</title>
<para>
- You can use the BitBake layer management tool to provide a view
+ You can use the BitBake layer management tool
+ <filename>bitbake-layers</filename> to provide a view
into the structure of recipes across a multi-layer project.
Being able to generate output that reports on configured layers
with their paths and priorities and on
@@ -871,42 +849,88 @@
</para>
<para>
- Use the following form when running the layer management tool.
+ For help on the BitBake layer management tool, use the
+ following command:
<literallayout class='monospaced'>
- $ bitbake-layers <replaceable>command</replaceable> [<replaceable>arguments</replaceable>]
+ $ bitbake-layers --help
+ NOTE: Starting bitbake server...
+ usage: bitbake-layers [-d] [-q] [-F] [--color COLOR] [-h] <subcommand> ...
+
+ BitBake layers utility
+
+ optional arguments:
+ -d, --debug Enable debug output
+ -q, --quiet Print only errors
+ -F, --force Force add without recipe parse verification
+ --color COLOR Colorize output (where COLOR is auto, always, never)
+ -h, --help show this help message and exit
+
+ subcommands:
+ <subcommand>
+ show-layers show current configured layers.
+ show-overlayed list overlayed recipes (where the same recipe exists
+ in another layer)
+ show-recipes list available recipes, showing the layer they are
+ provided by
+ show-appends list bbappend files and recipe files they apply to
+ show-cross-depends Show dependencies between recipes that cross layer
+ boundaries.
+ add-layer Add one or more layers to bblayers.conf.
+ remove-layer Remove one or more layers from bblayers.conf.
+ flatten flatten layer configuration into a separate output
+ directory.
+ layerindex-fetch Fetches a layer from a layer index along with its
+ dependent layers, and adds them to conf/bblayers.conf.
+ layerindex-show-depends
+ Find layer dependencies from layer index.
+ create-layer Create a basic layer
+
+ Use bitbake-layers <subcommand> --help to get help on a specific command
</literallayout>
+ </para>
+
+ <para>
The following list describes the available commands:
<itemizedlist>
- <listitem><para><filename><emphasis>help:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>help:</filename></emphasis>
Displays general help or help on a specified command.
</para></listitem>
- <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-layers:</filename></emphasis>
Shows the current configured layers.
</para></listitem>
- <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
- Lists available recipes and the layers that provide them.
- </para></listitem>
- <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-overlayed:</filename></emphasis>
Lists overlayed recipes.
A recipe is overlayed when a recipe with the same name
exists in another layer that has a higher layer
priority.
</para></listitem>
- <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-recipes:</filename></emphasis>
+ Lists available recipes and the layers that provide them.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>show-appends:</filename></emphasis>
Lists <filename>.bbappend</filename> files and the
recipe files to which they apply.
</para></listitem>
- <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>show-cross-depends:</filename></emphasis>
Lists dependency relationships between recipes that
cross layer boundaries.
</para></listitem>
- <listitem><para><filename><emphasis>add-layer:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>add-layer:</filename></emphasis>
Adds a layer to <filename>bblayers.conf</filename>.
</para></listitem>
- <listitem><para><filename><emphasis>remove-layer:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>remove-layer:</filename></emphasis>
Removes a layer from <filename>bblayers.conf</filename>
</para></listitem>
- <listitem><para><filename><emphasis>flatten:</emphasis></filename>
+ <listitem><para>
+ <emphasis><filename>flatten:</filename></emphasis>
Flattens the layer configuration into a separate output
directory.
Flattening your layer configuration builds a "flattened"
@@ -917,18 +941,21 @@
You might have to perform some manual cleanup of the
flattened layer as follows:
<itemizedlist>
- <listitem><para>Non-recipe files (such as patches)
+ <listitem><para>
+ Non-recipe files (such as patches)
are overwritten.
The flatten command shows a warning for these
files.
</para></listitem>
- <listitem><para>Anything beyond the normal layer
+ <listitem><para>
+ Anything beyond the normal layer
setup has been added to the
<filename>layer.conf</filename> file.
Only the lowest priority layer's
<filename>layer.conf</filename> is used.
</para></listitem>
- <listitem><para>Overridden and appended items from
+ <listitem><para>
+ Overridden and appended items from
<filename>.bbappend</filename> files need to be
cleaned up.
The contents of each
@@ -1000,13 +1027,13 @@
Developer's Guide.
</para></listitem>
<listitem><para>
- The <filename>bitbake-layers</filename> script
- replaces the <filename>yocto-layer</filename>
- script, which is deprecated in the Yocto Project
- 2.4 release.
- The <filename>yocto-layer</filename> script
- continues to function as part of the 2.4 release
- but will be removed post 2.4.
+ In order to use a layer with the OpenEmbedded
+ build system, you need to add the layer to your
+ <filename>bblayers.conf</filename> configuration
+ file.
+ See the
+ "<link linkend='adding-a-layer-using-the-bitbake-layers-script'>Adding a Layer Using the <filename>bitbake-layers</filename> Script</link>"
+ section for more information.
</para></listitem>
</itemizedlist>
</note>
@@ -1047,6 +1074,14 @@
<literallayout class='monospaced'>
$ bitbake-layers create-layer <replaceable>your_layer_name</replaceable>
</literallayout>
+ As an example, the following command creates a layer named
+ <filename>meta-scottrif</filename> in your home directory:
+ <literallayout class='monospaced'>
+ $ cd /usr/home
+ $ bitbake-layers create-layer meta-scottrif
+ NOTE: Starting bitbake server...
+ Add your new layer with 'bitbake-layers add-layer meta-scottrif'
+ </literallayout>
</para>
<para>
@@ -1089,26 +1124,36 @@
Filename of the example recipe
</literallayout>
</para>
+ </section>
+
+ <section id='adding-a-layer-using-the-bitbake-layers-script'>
+ <title>Adding a Layer Using the <filename>bitbake-layers</filename> Script</title>
<para>
Once you create your general layer, you must add it to your
<filename>bblayers.conf</filename> file.
- You can add your layer by using the
+ Adding the layer to this configuration file makes the
+ OpenEmbedded build system aware of your layer so that it can
+ search it for metadata.
+ </para>
+
+ <para>
+ Add your layer by using the
<filename>bitbake-layers add-layer</filename> command:
<literallayout class='monospaced'>
$ bitbake-layers add-layer <replaceable>your_layer_name</replaceable>
</literallayout>
- Here is an example where a layer named
- <filename>meta-scottrif</filename> is added and then the
- layers are shown using the
- <filename>bitbake-layers show-layers</filename> command:
+ Here is an example that adds a layer named
+ <filename>meta-scottrif</filename> to the configuration file.
+ Following the command that adds the layer is another
+ <filename>bitbake-layers</filename> command that shows the
+ layers that are in your <filename>bblayers.conf</filename>
+ file:
<literallayout class='monospaced'>
$ bitbake-layers add-layer meta-scottrif
NOTE: Starting bitbake server...
- Loading cache: 100% |############################################| Time: 0:00:00
- Loaded 1275 entries from dependency cache.
- Parsing recipes: 100% |##########################################| Time: 0:00:00
- Parsing of 819 .bb files complete (817 cached, 2 parsed). 1276 targets, 44 skipped, 0 masked, 0 errors.
+ Parsing recipes: 100% |##########################################################| Time: 0:00:49
+ Parsing of 1441 .bb files complete (0 cached, 1441 parsed). 2055 targets, 56 skipped, 0 masked, 0 errors.
$ bitbake-layers show-layers
NOTE: Starting bitbake server...
layer path priority
@@ -1116,12 +1161,16 @@
meta /home/scottrif/poky/meta 5
meta-poky /home/scottrif/poky/meta-poky 5
meta-yocto-bsp /home/scottrif/poky/meta-yocto-bsp 5
- meta-mylayer /home/scottrif/meta-mylayer 6
workspace /home/scottrif/poky/build/workspace 99
meta-scottrif /home/scottrif/poky/build/meta-scottrif 6
</literallayout>
Adding the layer to this file enables the build system to
locate the layer during the build.
+ <note>
+ During a build, the OpenEmbedded build system looks in
+ the layers from the top of the list down to the bottom
+ in that order.
+ </note>
</para>
</section>
</section>
@@ -1222,8 +1271,8 @@
To understand how these features work, the best reference is
<filename>meta/classes/core-image.bbclass</filename>.
This class lists out the available
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
- of which most map to package groups while some, such as
+ <filename>IMAGE_FEATURES</filename> of which most map to
+ package groups while some, such as
<filename>debug-tweaks</filename> and
<filename>read-only-rootfs</filename>, resolve as general
configuration settings.
@@ -1520,8 +1569,8 @@
</itemizedlist>
<note>
For information on recipe syntax, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#recipe-syntax'>Recipe Syntax</ulink>"
- section in the Yocto Project Reference Manual.
+ "<link linkend='recipe-syntax'>Recipe Syntax</link>"
+ section.
</note>
</para>
@@ -1572,47 +1621,43 @@
and have sourced the build environment setup script
(i.e.
<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>).
- Here is the basic <filename>recipetool</filename> syntax:
- <note>
- Running <filename>recipetool -h</filename> or
- <filename>recipetool create -h</filename> produces the
- Python-generated help, which presented differently
- than what follows here.
- </note>
+ To get help on the tool, use the following command:
<literallayout class='monospaced'>
- recipetool -h
- recipetool create [-h]
- recipetool [-d] [-q] [--color auto | always | never ] create -o <replaceable>OUTFILE</replaceable> [-m] [-x <replaceable>EXTERNALSRC</replaceable>] <replaceable>source</replaceable>
+ $ recipetool -h
+ NOTE: Starting bitbake server...
+ usage: recipetool [-d] [-q] [--color COLOR] [-h] <subcommand> ...
- -d Enables debug output.
- -q Outputs only errors (quiet mode).
- --color Colorizes the output automatically, always, or never.
- -h Displays Python generated syntax for recipetool.
- create Causes recipetool to create a base recipe. The create
- command is further defined with these options:
+ OpenEmbedded recipe tool
- -o <replaceable>OUTFILE</replaceable> Specifies the full path and filename for the generated
- recipe.
- -m Causes the recipe to be machine-specific rather than
- architecture-specific (default).
- -x <replaceable>EXTERNALSRC</replaceable> Fetches and extracts source files from <replaceable>source</replaceable>
- and places them in <replaceable>EXTERNALSRC</replaceable>.
- <replaceable>source</replaceable> must be a URL.
- -h Displays Python-generated syntax for create.
- <replaceable>source</replaceable> Specifies the source code on which to base the
- recipe.
+ options:
+ -d, --debug Enable debug output
+ -q, --quiet Print only errors
+ --color COLOR Colorize output (where COLOR is auto, always, never)
+ -h, --help show this help message and exit
+
+ subcommands:
+ create Create a new recipe
+ newappend Create a bbappend for the specified target in the specified
+ layer
+ setvar Set a variable within a recipe
+ appendfile Create/update a bbappend to replace a target file
+ appendsrcfiles Create/update a bbappend to add or replace source files
+ appendsrcfile Create/update a bbappend to add or replace a source file
+ Use recipetool <subcommand> --help to get help on a specific command
</literallayout>
</para>
<para>
- Running <filename>recipetool create -o</filename> <replaceable>OUTFILE</replaceable>
+ Running
+ <filename>recipetool create -o</filename> <replaceable>OUTFILE</replaceable>
creates the base recipe and locates it properly in the
layer that contains your source files.
Following are some syntax examples:
</para>
<para>
- Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
+ Use this syntax to generate a recipe based on
+ <replaceable>source</replaceable>.
Once generated, the recipe resides in the existing source
code layer:
<literallayout class='monospaced'>
@@ -1625,7 +1670,8 @@
<literallayout class='monospaced'>
recipetool create -o <replaceable>OUTFILE</replaceable> -x <replaceable>EXTERNALSRC</replaceable> <replaceable>source</replaceable>
</literallayout>
- Use this syntax to generate a recipe based on <replaceable>source</replaceable>.
+ Use this syntax to generate a recipe based on
+ <replaceable>source</replaceable>.
The options direct <filename>recipetool</filename> to
generate debugging information.
Once generated, the recipe resides in the existing source
@@ -1646,7 +1692,7 @@
The Yocto Project and OpenEmbedded communities maintain many
recipes that might be candidates for what you are doing.
You can find a good central index of these recipes in the
- <ulink url='http://layers.openembedded.org'>OpenEmbedded metadata index</ulink>.
+ <ulink url='http://layers.openembedded.org'>OpenEmbedded Layer Index</ulink>.
</para>
<para>
@@ -1811,8 +1857,8 @@
<para>
You can find more information about the build process in
- "<ulink url='&YOCTO_DOCS_REF_URL;#ref-development-environment'>The Yocto Project Development Environment</ulink>"
- chapter of the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#overview-development-environment'>The Yocto Project Development Environment</ulink>"
+ chapter of the Yocto Project Overview and Concepts Manual.
</para>
</section>
@@ -1828,8 +1874,8 @@
Your recipe must have a <filename>SRC_URI</filename> variable
that points to where the source is located.
For a graphical representation of source locations, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#sources-dev-environment'>Sources</ulink>"
- section in the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#sources-dev-environment'>Sources</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
</para>
<para>
@@ -2141,8 +2187,9 @@
containing the current checksum.
For more explanation and examples of how to set the
<filename>LIC_FILES_CHKSUM</filename> variable, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>"
- section in the Yocto Project Reference Manual.</para>
+ "<link link='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>"
+ section.</para>
+
<para>To determine the correct checksum string, you
can list the appropriate files in the
<filename>LIC_FILES_CHKSUM</filename> variable with
@@ -2288,8 +2335,9 @@
automatically add a runtime dependency to "mypackage" on
"example").
See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
- in the Yocto Project Reference Manual for further details.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for
+ further details.
</para>
</section>
@@ -2977,6 +3025,133 @@
</para>
</section>
+ <section id='metadata-virtual-providers'>
+ <title>Using Virtual Providers</title>
+
+ <para>
+ Prior to a build, if you know that several different recipes
+ provide the same functionality, you can use a virtual provider
+ (i.e. <filename>virtual/*</filename>) as a placeholder for the
+ actual provider.
+ The actual provider is determined at build-time.
+ </para>
+
+ <para>
+ A common scenario where a virtual provider is used would be
+ for the kernel recipe.
+ Suppose you have three kernel recipes whose
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
+ values map to <filename>kernel-big</filename>,
+ <filename>kernel-mid</filename>, and
+ <filename>kernel-small</filename>.
+ Furthermore, each of these recipes in some way uses a
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
+ statement that essentially identifies itself as being able
+ to provide <filename>virtual/kernel</filename>.
+ Here is one way through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-kernel'><filename>kernel</filename></ulink>
+ class:
+ <literallayout class='monospaced'>
+ PROVIDES += "${@ "virtual/kernel" if (d.getVar("KERNEL_PACKAGE_NAME") == "kernel") else "" }"
+ </literallayout>
+ Any recipe that inherits the <filename>kernel</filename> class
+ is going to utilize a <filename>PROVIDES</filename> statement
+ that identifies that recipe as being able to provide the
+ <filename>virtual/kernel</filename> item.
+ </para>
+
+ <para>
+ Now comes the time to actually build an image and you need a
+ kernel recipe, but which one?
+ You can configure your build to call out the kernel recipe
+ you want by using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+ variable.
+ As an example, consider the
+ <ulink url='https://git.yoctoproject.org/cgit/cgit.cgi/poky/tree/meta/conf/machine/include/x86-base.inc'><filename>x86-base.inc</filename></ulink>
+ include file, which is a machine
+ (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>)
+ configuration file.
+ This include file is the reason all x86-based machines use the
+ <filename>linux-yocto</filename> kernel.
+ Here are the relevant lines from the include file:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel ??= "linux-yocto"
+ PREFERRED_VERSION_linux-yocto ??= "4.15%"
+ </literallayout>
+ </para>
+
+ <para>
+ When you use a virtual provider, you do not have to
+ "hard code" a recipe name as a build dependency.
+ You can use the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+ variable to state the build is dependent on
+ <filename>virtual/kernel</filename> for example:
+ <literallayout class='monospaced'>
+ DEPENDS = "virtual/kernel"
+ </literallayout>
+ During the build, the OpenEmbedded build system picks
+ the correct recipe needed for the
+ <filename>virtual/kernel</filename> dependency based on the
+ <filename>PREFERRED_PROVIDER</filename> variable.
+ If you want to use the small kernel mentioned at the beginning
+ of this section, configure your build as follows:
+ <literallayout class='monospaced'>
+ PREFERRED_PROVIDER_virtual/kernel ??= "kernel-small"
+ </literallayout>
+ <note>
+ Any recipe that
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PROVIDES'><filename>PROVIDES</filename></ulink>
+ a <filename>virtual/*</filename> item that is ultimately
+ not selected through
+ <filename>PREFERRED_PROVIDER</filename> does not get built.
+ Preventing these recipes from building is usually the
+ desired behavior since this mechanism's purpose is to
+ select between mutually exclusive alternative providers.
+ </note>
+ </para>
+
+ <para>
+ The following lists specific examples of virtual providers:
+ <itemizedlist>
+ <listitem><para>
+ <filename>virtual/kernel</filename>:
+ Provides the name of the kernel recipe to use when
+ building a kernel image.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/bootloader</filename>:
+ Provides the name of the bootloader to use when
+ building an image.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/mesa</filename>:
+ Provides <filename>gbm.pc</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/egl</filename>:
+ Provides <filename>egl.pc</filename> and possibly
+ <filename>wayland-egl.pc</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/libgl</filename>:
+ Provides <filename>gl.pc</filename> (i.e. libGL).
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/libgles1</filename>:
+ Provides <filename>glesv1_cm.pc</filename>
+ (i.e. libGLESv1_CM).
+ </para></listitem>
+ <listitem><para>
+ <filename>virtual/libgles2</filename>:
+ Provides <filename>glesv2.pc</filename>
+ (i.e. libGLESv2).
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
<section id='properly-versioning-pre-release-recipes'>
<title>Properly Versioning Pre-Release Recipes</title>
@@ -3224,8 +3399,10 @@
The variable
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
is used to track source license changes as described in the
- "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
- You can quickly create Autotool-based recipes in a manner similar to the previous example.
+ "<link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</link>"
+ section in the Yocto Project Overview and Concepts Manual.
+ You can quickly create Autotool-based recipes in a manner
+ similar to the previous example.
</para>
</section>
@@ -3430,9 +3607,9 @@
allows runtime dependencies between packages
to be added automatically.
See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
- section in the Yocto Project Reference Manual
- for more information.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
+ section in the Yocto Project Overview and
+ Concepts Manual for more information.
</para></listitem>
</itemizedlist>
</note>
@@ -3517,6 +3694,330 @@
style.
</para>
</section>
+
+ <section id='recipe-syntax'>
+ <title>Recipe Syntax</title>
+
+ <para>
+ Understanding recipe file syntax is important for writing
+ recipes.
+ The following list overviews the basic items that make up a
+ BitBake recipe file.
+ For more complete BitBake syntax descriptions, see the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>"
+ chapter of the BitBake User Manual.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Variable Assignments and Manipulations:</emphasis>
+ Variable assignments allow a value to be assigned to a
+ variable.
+ The assignment can be static text or might include
+ the contents of other variables.
+ In addition to the assignment, appending and prepending
+ operations are also supported.</para>
+
+ <para>The following example shows some of the ways
+ you can use variables in recipes:
+ <literallayout class='monospaced'>
+ S = "${WORKDIR}/postfix-${PV}"
+ CFLAGS += "-DNO_ASM"
+ SRC_URI_append = " file://fixup.patch"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Functions:</emphasis>
+ Functions provide a series of actions to be performed.
+ You usually use functions to override the default
+ implementation of a task function or to complement
+ a default function (i.e. append or prepend to an
+ existing function).
+ Standard functions use <filename>sh</filename> shell
+ syntax, although access to OpenEmbedded variables and
+ internal methods are also available.</para>
+
+ <para>The following is an example function from the
+ <filename>sed</filename> recipe:
+ <literallayout class='monospaced'>
+ do_install () {
+ autotools_do_install
+ install -d ${D}${base_bindir}
+ mv ${D}${bindir}/sed ${D}${base_bindir}/sed
+ rmdir ${D}${bindir}/
+ }
+ </literallayout>
+ It is also possible to implement new functions that
+ are called between existing tasks as long as the
+ new functions are not replacing or complementing the
+ default functions.
+ You can implement functions in Python
+ instead of shell.
+ Both of these options are not seen in the majority of
+ recipes.
+ </para></listitem>
+ <listitem><para><emphasis>Keywords:</emphasis>
+ BitBake recipes use only a few keywords.
+ You use keywords to include common
+ functions (<filename>inherit</filename>), load parts
+ of a recipe from other files
+ (<filename>include</filename> and
+ <filename>require</filename>) and export variables
+ to the environment (<filename>export</filename>).
+ </para>
+
+ <para>The following example shows the use of some of
+ these keywords:
+ <literallayout class='monospaced'>
+ export POSTCONF = "${STAGING_BINDIR}/postconf"
+ inherit autoconf
+ require otherfile.inc
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Comments (#):</emphasis>
+ Any lines that begin with the hash character
+ (<filename>#</filename>) are treated as comment lines
+ and are ignored:
+ <literallayout class='monospaced'>
+ # This is a comment
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ This next list summarizes the most important and most commonly
+ used parts of the recipe syntax.
+ For more information on these parts of the syntax, you can
+ reference the
+ <ulink url='&YOCTO_DOCS_BB_URL;#bitbake-user-manual-metadata'>Syntax and Operators</ulink>
+ chapter in the BitBake User Manual.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Line Continuation (\):</emphasis>
+ Use the backward slash (<filename>\</filename>)
+ character to split a statement over multiple lines.
+ Place the slash character at the end of the line that
+ is to be continued on the next line:
+ <literallayout class='monospaced'>
+ VAR = "A really long \
+ line"
+ </literallayout>
+ <note>
+ You cannot have any characters including spaces
+ or tabs after the slash character.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Using Variables (${<replaceable>VARNAME</replaceable>}):</emphasis>
+ Use the <filename>${<replaceable>VARNAME</replaceable>}</filename>
+ syntax to access the contents of a variable:
+ <literallayout class='monospaced'>
+ SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"
+ </literallayout>
+ <note>
+ It is important to understand that the value of a
+ variable expressed in this form does not get
+ substituted automatically.
+ The expansion of these expressions happens
+ on-demand later (e.g. usually when a function that
+ makes reference to the variable executes).
+ This behavior ensures that the values are most
+ appropriate for the context in which they are
+ finally used.
+ On the rare occasion that you do need the variable
+ expression to be expanded immediately, you can use
+ the <filename>:=</filename> operator instead of
+ <filename>=</filename> when you make the
+ assignment, but this is not generally needed.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Quote All Assignments ("<replaceable>value</replaceable>"):</emphasis>
+ Use double quotes around values in all variable
+ assignments (e.g.
+ <filename>"<replaceable>value</replaceable>"</filename>).
+ Following is an example:
+ <literallayout class='monospaced'>
+ VAR1 = "${OTHERVAR}"
+ VAR2 = "The version is ${PV}"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Conditional Assignment (?=):</emphasis>
+ Conditional assignment is used to assign a
+ value to a variable, but only when the variable is
+ currently unset.
+ Use the question mark followed by the equal sign
+ (<filename>?=</filename>) to make a "soft" assignment
+ used for conditional assignment.
+ Typically, "soft" assignments are used in the
+ <filename>local.conf</filename> file for variables
+ that are allowed to come through from the external
+ environment.
+ </para>
+
+ <para>Here is an example where
+ <filename>VAR1</filename> is set to "New value" if
+ it is currently empty.
+ However, if <filename>VAR1</filename> has already been
+ set, it remains unchanged:
+ <literallayout class='monospaced'>
+ VAR1 ?= "New value"
+ </literallayout>
+ In this next example, <filename>VAR1</filename>
+ is left with the value "Original value":
+ <literallayout class='monospaced'>
+ VAR1 = "Original value"
+ VAR1 ?= "New value"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Appending (+=):</emphasis>
+ Use the plus character followed by the equals sign
+ (<filename>+=</filename>) to append values to existing
+ variables.
+ <note>
+ This operator adds a space between the existing
+ content of the variable and the new content.
+ </note></para>
+
+ <para>Here is an example:
+ <literallayout class='monospaced'>
+ SRC_URI += "file://fix-makefile.patch"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Prepending (=+):</emphasis>
+ Use the equals sign followed by the plus character
+ (<filename>=+</filename>) to prepend values to existing
+ variables.
+ <note>
+ This operator adds a space between the new content
+ and the existing content of the variable.
+ </note></para>
+
+ <para>Here is an example:
+ <literallayout class='monospaced'>
+ VAR =+ "Starts"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Appending (_append):</emphasis>
+ Use the <filename>_append</filename> operator to
+ append values to existing variables.
+ This operator does not add any additional space.
+ Also, the operator is applied after all the
+ <filename>+=</filename>, and
+ <filename>=+</filename> operators have been applied and
+ after all <filename>=</filename> assignments have
+ occurred.
+ </para>
+
+ <para>The following example shows the space being
+ explicitly added to the start to ensure the appended
+ value is not merged with the existing value:
+ <literallayout class='monospaced'>
+ SRC_URI_append = " file://fix-makefile.patch"
+ </literallayout>
+ You can also use the <filename>_append</filename>
+ operator with overrides, which results in the actions
+ only being performed for the specified target or
+ machine:
+ <literallayout class='monospaced'>
+ SRC_URI_append_sh4 = " file://fix-makefile.patch"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Prepending (_prepend):</emphasis>
+ Use the <filename>_prepend</filename> operator to
+ prepend values to existing variables.
+ This operator does not add any additional space.
+ Also, the operator is applied after all the
+ <filename>+=</filename>, and
+ <filename>=+</filename> operators have been applied and
+ after all <filename>=</filename> assignments have
+ occurred.
+ </para>
+
+ <para>The following example shows the space being
+ explicitly added to the end to ensure the prepended
+ value is not merged with the existing value:
+ <literallayout class='monospaced'>
+ CFLAGS_prepend = "-I${S}/myincludes "
+ </literallayout>
+ You can also use the <filename>_prepend</filename>
+ operator with overrides, which results in the actions
+ only being performed for the specified target or
+ machine:
+ <literallayout class='monospaced'>
+ CFLAGS_prepend_sh4 = "-I${S}/myincludes "
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Overrides:</emphasis>
+ You can use overrides to set a value conditionally,
+ typically based on how the recipe is being built.
+ For example, to set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink>
+ variable's value to "standard/base" for any target
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
+ except for qemuarm where it should be set to
+ "standard/arm-versatile-926ejs", you would do the
+ following:
+ <literallayout class='monospaced'>
+ KBRANCH = "standard/base"
+ KBRANCH_qemuarm = "standard/arm-versatile-926ejs"
+ </literallayout>
+ Overrides are also used to separate alternate values
+ of a variable in other situations.
+ For example, when setting variables such as
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
+ that are specific to individual packages produced by
+ a recipe, you should always use an override that
+ specifies the name of the package.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Indentation:</emphasis>
+ Use spaces for indentation rather than than tabs.
+ For shell functions, both currently work.
+ However, it is a policy decision of the Yocto Project
+ to use tabs in shell functions.
+ Realize that some layers have a policy to use spaces
+ for all indentation.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Using Python for Complex Operations:</emphasis>
+ For more advanced processing, it is possible to use
+ Python code during variable assignments (e.g.
+ search and replacement on a variable).</para>
+
+ <para>You indicate Python code using the
+ <filename>${@<replaceable>python_code</replaceable>}</filename>
+ syntax for the variable assignment:
+ <literallayout class='monospaced'>
+ SRC_URI = "ftp://ftp.info-zip.org/pub/infozip/src/zip${@d.getVar('PV',1).replace('.', '')}.tgz
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Shell Function Syntax:</emphasis>
+ Write shell functions as if you were writing a shell
+ script when you describe a list of actions to take.
+ You should ensure that your script works with a generic
+ <filename>sh</filename> and that it does not require
+ any <filename>bash</filename> or other shell-specific
+ functionality.
+ The same considerations apply to various system
+ utilities (e.g. <filename>sed</filename>,
+ <filename>grep</filename>, <filename>awk</filename>,
+ and so forth) that you might wish to use.
+ If in doubt, you should check with multiple
+ implementations - including those from BusyBox.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
</section>
<section id="platdev-newmachine">
@@ -3538,8 +4039,9 @@
<para>
For a complete example that shows how to add a new machine,
see the
- "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
- section in the Yocto Project Board Support Package (BSP) Developer's Guide.
+ "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'>Creating a New BSP Layer Using the <filename>bitbake-layers</filename> Script</ulink>"
+ section in the Yocto Project Board Support Package (BSP)
+ Developer's Guide.
</para>
<section id="platdev-newmachine-conffile">
@@ -3694,6 +4196,562 @@
</section>
</section>
+ <section id='gs-upgrading-recipes'>
+ <title>Upgrading Recipes</title>
+
+ <para>
+ Over time, upstream developers publish new versions for software
+ built by layer recipes.
+ It is recommended to keep recipes up-to-date with upstream
+ version releases.
+ You can use the Automated Upgrade Helper (AUH) to set up
+ automatic version upgrades.
+ Alternatively, you can use <filename>devtool upgrade</filename>
+ to set up semi-automatic version upgrades.
+ Finally, you can even manually upgrade a recipe by editing the
+ recipe itself.
+ </para>
+
+ <section id='gs-using-the-auto-upgrade-helper'>
+ <title>Using the Auto Upgrade Helper (AUH)</title>
+
+ <para>
+ The AUH utility works in conjunction with the
+ OpenEmbedded build system in order to automatically generate
+ upgrades for recipes based on new versions being
+ published upstream.
+ Use AUH when you want to create a service that performs the
+ upgrades automatically and optionally sends you an email with
+ the results.
+ </para>
+
+ <para>
+ AUH allows you to update several recipes with a single use.
+ You can also optionally perform build and integration tests
+ using images with the results saved to your hard drive and
+ emails of results optionally sent to recipe maintainers.
+ Finally, AUH creates Git commits with appropriate commit
+ messages in the layer's tree for the changes made to recipes.
+ <note>
+ Conditions do exist when you should not use AUH to upgrade
+ recipes and you should instead use either
+ <filename>devtool upgrade</filename> or upgrade your
+ recipes manually:
+ <itemizedlist>
+ <listitem><para>
+ When AUH cannot complete the upgrade sequence.
+ This situation usually results because custom
+ patches carried by the recipe cannot be
+ automatically rebased to the new version.
+ In this case, <filename>devtool upgrade</filename>
+ allows you to manually resolve conflicts.
+ </para></listitem>
+ <listitem><para>
+ When for any reason you want fuller control over
+ the upgrade process.
+ For example, when you want special arrangements
+ for testing.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The following steps describe how to set up the AUH utility:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Be Sure the Development Host is Set Up:</emphasis>
+ You need to be sure that your development host is
+ set up to use the Yocto Project.
+ For information on how to set up your host, see the
+ "<link linkend='setting-up-the-development-host-to-use-the-yocto-project'>Preparing the Build Host</link>"
+ section.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure Git is Configured:</emphasis>
+ The AUH utility requires Git to be configured because
+ AUH uses Git to save upgrades.
+ Thus, you must have Git user and email configured.
+ The following command shows your configurations:
+ <literallayout class='monospaced'>
+ $ git config --list
+ </literallayout>
+ If you do not have the user and email configured, you
+ can use the following commands to do so:
+ <literallayout class='monospaced'>
+ $ git config --global user.name <replaceable>some_name</replaceable>
+ $ git config --global user.email <replaceable>username</replaceable>@<replaceable>domain</replaceable>.com
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Clone the AUH Repository:</emphasis>
+ To use AUH, you must clone the repository onto your
+ development host.
+ The following command uses Git to create a local
+ copy of the repository on your system:
+ <literallayout class='monospaced'>
+ $ git clone git://git.yoctoproject.org/auto-upgrade-helper
+ Cloning into 'auto-upgrade-helper'...
+ remote: Counting objects: 768, done.
+ remote: Compressing objects: 100% (300/300), done.
+ remote: Total 768 (delta 499), reused 703 (delta 434)
+ Receiving objects: 100% (768/768), 191.47 KiB | 98.00 KiB/s, done.
+ Resolving deltas: 100% (499/499), done.
+ Checking connectivity... done.
+ </literallayout>
+ AUH is not part of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#oe-core'>OpenEmbedded-Core (OE-Core)</ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#poky'>Poky</ulink>
+ repositories.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Dedicated Build Directory:</emphasis>
+ Run the
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>oe-init-build-env</filename></ulink>
+ script to create a fresh build directory that you
+ use exclusively for running the AUH utility:
+ <literallayout class='monospaced'>
+ $ cd ~/poky
+ $ source oe-init-build-env <replaceable>your_AUH_build_directory</replaceable>
+ </literallayout>
+ Re-using an existing build directory and its
+ configurations is not recommended as existing settings
+ could cause AUH to fail or behave undesirably.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Configurations in Your Local Configuration File:</emphasis>
+ Several settings need to exist in the
+ <filename>local.conf</filename> file in the build
+ directory you just created for AUH.
+ Make these following configurations:
+ <itemizedlist>
+ <listitem><para>
+ Enable "distrodata" as follows:
+ <literallayout class='monospaced'>
+ INHERIT =+ "distrodata"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ If you want to enable
+ <ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-build-output-quality'>Build History</ulink>,
+ which is optional, you need the following
+ lines in the
+ <filename>conf/local.conf</filename> file:
+ <literallayout class='monospaced'>
+ INHERIT =+ "buildhistory"
+ BUILDHISTORY_COMMIT = "1"
+ </literallayout>
+ With this configuration and a successful
+ upgrade, a build history "diff" file appears in
+ the
+ <filename>upgrade-helper/work/recipe/buildhistory-diff.txt</filename>
+ file found in your build directory.
+ </para></listitem>
+ <listitem><para>
+ If you want to enable testing through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage*'><filename>testimage</filename></ulink>
+ class, which is optional, you need to have the
+ following set in your
+ <filename>conf/local.conf</filename> file:
+ <literallayout class='monospaced'>
+ INHERIT += "testimage"
+ </literallayout>
+ <note>
+ If your distro does not enable by default
+ ptest, which Poky does, you need the
+ following in your
+ <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ DISTRO_FEATURES_append = " ptest"
+ </literallayout>
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Start a vncserver:</emphasis>
+ If you are running in a server without an X11 session,
+ you need to start a vncserver:
+ <literallayout class='monospaced'>
+ $ vncserver :1
+ $ export DISPLAY=:1
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create and Edit an AUH Configuration File:</emphasis>
+ You need to have the
+ <filename>upgrade-helper/upgrade-helper.conf</filename>
+ configuration file in your build directory.
+ You can find a sample configuration file in the
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/'>AUH source repository</ulink>.
+ </para>
+
+ <para>Read through the sample file and make
+ configurations as needed.
+ For example, if you enabled build history in your
+ <filename>local.conf</filename> as described earlier,
+ you must enable it in
+ <filename>upgrade-helper.conf</filename>.</para>
+
+ <para>Also, if you are using the default
+ <filename>maintainers.inc</filename> file supplied
+ with Poky and located in
+ <filename>meta-yocto</filename> and you do not set a
+ "maintainers_whitelist" or "global_maintainer_override"
+ in the <filename>upgrade-helper.conf</filename>
+ configuration, and you specify "-e all" on the
+ AUH command-line, the utility automatically sends out
+ emails to all the default maintainers.
+ Please avoid this.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ This next set of examples describes how to use the AUH:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Upgrading a Specific Recipe:</emphasis>
+ To upgrade a specific recipe, use the following
+ form:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py <replaceable>recipe_name</replaceable>
+ </literallayout>
+ For example, this command upgrades the
+ <filename>xmodmap</filename> recipe:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py xmodmap
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Upgrading a Specific Recipe to a Particular Version:</emphasis>
+ To upgrade a specific recipe to a particular version,
+ use the following form:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py <replaceable>recipe_name</replaceable> -t <replaceable>version</replaceable>
+ </literallayout>
+ For example, this command upgrades the
+ <filename>xmodmap</filename> recipe to version
+ 1.2.3:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py xmodmap -t 1.2.3
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Upgrading all Recipes to the Latest Versions and Suppressing Email Notifications:</emphasis>
+ To upgrade all recipes to their most recent versions
+ and suppress the email notifications, use the following
+ command:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py all
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Upgrading all Recipes to the Latest Versions and Send Email Notifications:</emphasis>
+ To upgrade all recipes to their most recent versions
+ and send email messages to maintainers for each
+ attempted recipe as well as a status email, use the
+ following command:
+ <literallayout class='monospaced'>
+ $ upgrade-helper.py -e all
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Once you have run the AUH utility, you can find the results
+ in the AUH build directory:
+ <literallayout class='monospaced'>
+ ${BUILDDIR}/upgrade-helper/<replaceable>timestamp</replaceable>
+ </literallayout>
+ The AUH utility also creates recipe update commits from
+ successful upgrade attempts in the layer tree.
+ </para>
+
+ <para>
+ You can easily set up to run the AUH utility on a regular
+ basis by using a cron job.
+ See the
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/auto-upgrade-helper/tree/weeklyjob.sh'><filename>weeklyjob.sh</filename></ulink>
+ file distributed with the utility for an example.
+ </para>
+ </section>
+
+ <section id='gs-using-devtool-upgrade'>
+ <title>Using <filename>devtool upgrade</filename></title>
+
+ <para>
+ As mentioned earlier, an alternative method for upgrading
+ recipes to newer versions is to use
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-devtool-reference'><filename>devtool upgrade</filename></ulink>.
+ You can read about <filename>devtool upgrade</filename> in
+ general in the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#sdk-devtool-use-devtool-upgrade-to-create-a-version-of-the-recipe-that-supports-a-newer-version-of-the-software'>Use <filename>devtool upgrade</filename> to Create a Version of the Recipe that Supports a Newer Version of the Software</ulink>"
+ section in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) Manual.
+ </para>
+
+ <para>
+ To see all the command-line options available with
+ <filename>devtool upgrade</filename>, use the following help
+ command:
+ <literallayout class='monospaced'>
+ $ devtool upgrade -h
+ </literallayout>
+ </para>
+
+ <para>
+ If you want to find out what version a recipe is currently at
+ upstream without any attempt to upgrade your local version of
+ the recipe, you can use the following command:
+ <literallayout class='monospaced'>
+ $ devtool latest-version <replaceable>recipe_name</replaceable>
+ </literallayout>
+ </para>
+
+ <para>
+ As mentioned in the previous section describing AUH,
+ <filename>devtool upgrade</filename> works in a
+ less-automated manner than AUH.
+ Specifically, <filename>devtool upgrade</filename> only
+ works on a single recipe that you name on the command line,
+ cannot perform build and integration testing using images,
+ and does not automatically generate commits for changes in
+ the source tree.
+ Despite all these "limitations",
+ <filename>devtool upgrade</filename> updates the recipe file
+ to the new upstream version and attempts to rebase custom
+ patches contained by the recipe as needed.
+ <note>
+ AUH uses much of <filename>devtool upgrade</filename>
+ behind the scenes making AUH somewhat of a "wrapper"
+ application for <filename>devtool upgrade</filename>.
+ </note>
+ </para>
+
+ <para>
+ A typical scenario involves having used Git to clone an
+ upstream repository that you use during build operations.
+ Because you are (or have) built the recipe in the past, the
+ layer is likely added to your configuration already.
+ If for some reason, the layer is not added, you could add
+ it easily using the
+ <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-bitbake-layers-script'><filename>bitbake-layers</filename></ulink>
+ script.
+ For example, suppose you use the <filename>nano.bb</filename>
+ recipe from the <filename>meta-oe</filename> layer in the
+ <filename>meta-openembedded</filename> repository.
+ For this example, assume that the layer has been cloned into
+ following area:
+ <literallayout class='monospaced'>
+ /home/scottrif/meta-openembedded
+ </literallayout>
+ The following command from your
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ adds the layer to your build configuration (i.e.
+ <filename>${BUILDDIR}/conf/bblayers.conf</filename>):
+ <literallayout class='monospaced'>
+ $ bitbake-layers add-layer /home/scottrif/meta-openembedded/meta-oe
+ NOTE: Starting bitbake server...
+ Parsing recipes: 100% |##########################################| Time: 0:00:55
+ Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
+ Removing 12 recipes from the x86_64 sysroot: 100% |##############| Time: 0:00:00
+ Removing 1 recipes from the x86_64_i586 sysroot: 100% |##########| Time: 0:00:00
+ Removing 5 recipes from the i586 sysroot: 100% |#################| Time: 0:00:00
+ Removing 5 recipes from the qemux86 sysroot: 100% |##############| Time: 0:00:00
+ </literallayout>
+ For this example, assume that the <filename>nano.bb</filename>
+ recipe that is upstream has a 2.9.3 version number.
+ However, the version in the local repository is 2.7.4.
+ The following command from your build directory automatically
+ upgrades the recipe for you:
+ <note>
+ Using the <filename>-V</filename> option is not necessary.
+ Omitting the version number causes
+ <filename>devtool upgrade</filename> to upgrade the recipe
+ to the most recent version.
+ </note>
+ <literallayout class='monospaced'>
+ $ devtool upgrade nano -V 2.9.3
+ NOTE: Starting bitbake server...
+ NOTE: Creating workspace layer in /home/scottrif/poky/build/workspace
+ Parsing recipes: 100% |##########################################| Time: 0:00:46
+ Parsing of 1431 .bb files complete (0 cached, 1431 parsed). 2040 targets, 56 skipped, 0 masked, 0 errors.
+ NOTE: Extracting current version source...
+ NOTE: Resolving any missing task queue dependencies
+ .
+ .
+ .
+ NOTE: Executing SetScene Tasks
+ NOTE: Executing RunQueue Tasks
+ NOTE: Tasks Summary: Attempted 74 tasks of which 72 didn't need to be rerun and all succeeded.
+ Adding changed files: 100% |#####################################| Time: 0:00:00
+ NOTE: Upgraded source extracted to /home/scottrif/poky/build/workspace/sources/nano
+ NOTE: New recipe is /home/scottrif/poky/build/workspace/recipes/nano/nano_2.9.3.bb
+ </literallayout>
+ Continuing with this example, you can use
+ <filename>devtool build</filename> to build the newly upgraded
+ recipe:
+ <literallayout class='monospaced'>
+ $ devtool build nano
+ NOTE: Starting bitbake server...
+ Loading cache: 100% |################################################################################################| Time: 0:00:01
+ Loaded 2040 entries from dependency cache.
+ Parsing recipes: 100% |##############################################################################################| Time: 0:00:00
+ Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
+ NOTE: Resolving any missing task queue dependencies
+ .
+ .
+ .
+ NOTE: Executing SetScene Tasks
+ NOTE: Executing RunQueue Tasks
+ NOTE: nano: compiling from external source tree /home/scottrif/poky/build/workspace/sources/nano
+ NOTE: Tasks Summary: Attempted 520 tasks of which 304 didn't need to be rerun and all succeeded.
+ </literallayout>
+ Within the <filename>devtool upgrade</filename> workflow,
+ opportunity exists to deploy and test your rebuilt software.
+ For this example, however, running
+ <filename>devtool finish</filename> cleans up the workspace
+ once the source in your workspace is clean.
+ This usually means using Git to stage and submit commits
+ for the changes generated by the upgrade process.
+ </para>
+
+ <para>
+ Once the tree is clean, you can clean things up in this
+ example with the following command from the
+ <filename>${BUILDDIR}/workspace/sources/nano</filename>
+ directory:
+ <literallayout class='monospaced'>
+ $ devtool finish nano meta-oe
+ NOTE: Starting bitbake server...
+ Loading cache: 100% |################################################################################################| Time: 0:00:00
+ Loaded 2040 entries from dependency cache.
+ Parsing recipes: 100% |##############################################################################################| Time: 0:00:01
+ Parsing of 1432 .bb files complete (1431 cached, 1 parsed). 2041 targets, 56 skipped, 0 masked, 0 errors.
+ NOTE: Adding new patch 0001-nano.bb-Stuff-I-changed-when-upgrading-nano.bb.patch
+ NOTE: Updating recipe nano_2.9.3.bb
+ NOTE: Removing file /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano/nano_2.7.4.bb
+ NOTE: Moving recipe file to /home/scottrif/meta-openembedded/meta-oe/recipes-support/nano
+ NOTE: Leaving source tree /home/scottrif/poky/build/workspace/sources/nano as-is; if you no longer need it then please delete it manually
+ </literallayout>
+ Using the <filename>devtool finish</filename> command cleans
+ up the workspace and creates a patch file based on your
+ commits.
+ The tool puts all patch files back into the source directory
+ in a sub-directory named <filename>nano</filename> in this
+ case.
+ </para>
+ </section>
+
+ <section id='dev-manually-upgrading-a-recipe'>
+ <title>Manually Upgrading a Recipe</title>
+
+ <para>
+ If for some reason you choose not to upgrade recipes using the
+ <link linkend='gs-using-the-auto-upgrade-helper'>Auto Upgrade Helper (AUH)</link>
+ or by using
+ <link linkend='gs-using-devtool-upgrade'><filename>devtool upgrade</filename></link>,
+ you can manually edit the recipe files to upgrade the versions.
+ <note><title>Caution</title>
+ Manually updating multiple recipes scales poorly and
+ involves many steps.
+ The recommendation to upgrade recipe versions is through
+ AUH or <filename>devtool upgrade</filename>, both of which
+ automate some steps and provide guidance for others needed
+ for the manual process.
+ </note>
+ </para>
+
+ <para>
+ To manually upgrade recipe versions, follow these general steps:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Change the Version:</emphasis>
+ Rename the recipe such that the version (i.e. the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+ part of the recipe name) changes appropriately.
+ If the version is not part of the recipe name, change
+ the value as it is set for <filename>PV</filename>
+ within the recipe itself.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Update <filename>SRCREV</filename> if Needed:</emphasis>
+ If the source code your recipe builds is fetched from
+ Git or some other version control system, update
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ to point to the commit hash that matches the new
+ version.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Software:</emphasis>
+ Try to build the recipe using BitBake.
+ Typical build failures include the following:
+ <itemizedlist>
+ <listitem><para>
+ License statements were updated for the new
+ version.
+ For this case, you need to review any changes
+ to the license and update the values of
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
+ as needed.
+ <note>
+ License changes are often inconsequential.
+ For example, the license text's copyright
+ year might have changed.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Custom patches carried by the older version of
+ the recipe might fail to apply to the new
+ version.
+ For these cases, you need to review the
+ failures.
+ Patches might not be necessary for the new
+ version of the software if the upgraded version
+ has fixed those issues.
+ If a patch is necessary and failing, you need
+ to rebase it into the new version.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Attempt to Build for Several Architectures:</emphasis>
+ Once you successfully build the new software for a
+ given architecture, you could test the build for
+ other architectures by changing the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ variable and rebuilding the software.
+ This optional step is especially important if the
+ recipe is to be released publicly.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Check the Upstream Change Log or Release Notes:</emphasis>
+ Checking both these reveals if new features exist that
+ could break backwards-compatibility.
+ If so, you need to take steps to mitigate or eliminate
+ that situation.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Create a Bootable Image and Test:</emphasis>
+ If you want, you can test the new software by booting
+ it onto actual hardware.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Commit with the Change in the Layer Repository:</emphasis>
+ After all builds work and any testing is successful,
+ you can create commits for any changes in the layer
+ holding your upgraded recipe.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+
<section id='finding-the-temporary-source-code'>
<title>Finding Temporary Source Code</title>
@@ -3888,8 +4946,8 @@
Modifications will also disappear if you use the
<filename>rm_work</filename> feature as described
in the
- "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>"
- section of the Yocto Project Quick Start.
+ "<ulink url='&YOCTO_DOCS_DEV_URL;#dev-saving-memory-during-a-build'>Conserving Disk Space During Builds</ulink>"
+ section.
</note>
</para></listitem>
<listitem><para>
@@ -4105,102 +5163,1224 @@
</para>
</section>
- <section id='platdev-building-targets-with-multiple-configurations'>
- <title>Building Targets with Multiple Configurations</title>
+ <section id='dev-building'>
+ <title>Building</title>
<para>
- Bitbake also has functionality that allows you to build
- multiple targets at the same time, where each target uses
- a different configuration.
+ This section describes various build procedures.
+ For example, the steps needed for a simple build, a target that
+ uses multiple configurations, building an image for more than
+ one machine, and so forth.
</para>
- <para>
- In order to accomplish this, you setup each of the configurations
- you need to use in parallel by placing the configuration files in
- your current build directory alongside the usual
- <filename>local.conf</filename> file.
- </para>
+ <section id='dev-building-a-simple-image'>
+ <title>Building a Simple Image</title>
+
+ <para>
+ In the development environment, you need to build an image
+ whenever you change hardware support, add or change system
+ libraries, or add or change services that have dependencies.
+ Several methods exist that allow you to build an image within
+ the Yocto Project.
+ This section presents the basic steps you need to build a
+ simple image using BitBake from a build host running Linux.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ For information on how to build an image using
+ <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>,
+ see the
+ <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster User Manual</ulink>.
+ </para></listitem>
+ <listitem><para>
+ For information on how to use
+ <filename>devtool</filename> to build images, see
+ the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#using-devtool-in-your-sdk-workflow'>Using <filename>devtool</filename> in Your SDK Workflow</ulink>"
+ section in the Yocto Project Application
+ Development and the Extensible Software Development
+ Kit (eSDK) manual.
+ </para></listitem>
+ <listitem><para>
+ For a quick example on how to build an image using
+ the OpenEmbedded build system, see the
+ <ulink url='&YOCTO_DOCS_BRIEF_URL;'>Yocto Project Quick Build</ulink>
+ document.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The build process creates an entire Linux distribution from
+ source and places it in your
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ under <filename>tmp/deploy/images</filename>.
+ For detailed information on the build process using BitBake,
+ see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#images-dev-environment'>Images</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para>
+
+ <para>
+ The following figure and list overviews the build process:
+ <imagedata fileref="figures/bitbake-build-flow.png" width="7in" depth="4in" align="center" scalefit="1" />
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Set up Your Host Development System to Support
+ Development Using the Yocto Project</emphasis>:
+ See the
+ "<link linkend='dev-manual-start'>Setting Up to Use the Yocto Project</link>"
+ section for options on how to get a build host ready to
+ use the Yocto Project.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Initialize the Build Environment:</emphasis>
+ Initialize the build environment by sourcing the build
+ environment script (i.e.
+ <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>):
+ <literallayout class='monospaced'>
+ $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>]
+ </literallayout></para>
+
+ <para>When you use the initialization script, the
+ OpenEmbedded build system uses
+ <filename>build</filename> as the default Build
+ Directory in your current work directory.
+ You can use a <replaceable>build_dir</replaceable>
+ argument with the script to specify a different build
+ directory.
+ <note><title>Tip</title>
+ A common practice is to use a different Build
+ Directory for different targets.
+ For example, <filename>~/build/x86</filename> for a
+ <filename>qemux86</filename> target, and
+ <filename>~/build/arm</filename> for a
+ <filename>qemuarm</filename> target.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make Sure Your <filename>local.conf</filename>
+ File is Correct:</emphasis>
+ Ensure the <filename>conf/local.conf</filename>
+ configuration file, which is found in the Build
+ Directory, is set up how you want it.
+ This file defines many aspects of the build environment
+ including the target machine architecture through the
+ <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
+ the packaging format used during the build
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>),
+ and a centralized tarball download directory through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Image:</emphasis>
+ Build the image using the <filename>bitbake</filename>
+ command:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>target</replaceable>
+ </literallayout>
+ <note>
+ For information on BitBake, see the
+ <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>.
+ </note>
+ The <replaceable>target</replaceable> is the name of the
+ recipe you want to build.
+ Common targets are the images in
+ <filename>meta/recipes-core/images</filename>,
+ <filename>meta/recipes-sato/images</filename>, and so
+ forth all found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ Or, the target can be the name of a recipe for a
+ specific piece of software such as BusyBox.
+ For more details about the images the OpenEmbedded build
+ system supports, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+ chapter in the Yocto Project Reference Manual.</para>
+
+ <para>As an example, the following command builds the
+ <filename>core-image-minimal</filename> image:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-minimal
+ </literallayout>
+ Once an image has been built, it often needs to be
+ installed.
+ The images and kernels built by the OpenEmbedded
+ build system are placed in the Build Directory in
+ <filename class="directory">tmp/deploy/images</filename>.
+ For information on how to run pre-built images such as
+ <filename>qemux86</filename> and <filename>qemuarm</filename>,
+ see the
+ <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink>
+ manual.
+ For information about how to install these images,
+ see the documentation for your particular board or
+ machine.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='platdev-building-targets-with-multiple-configurations'>
+ <title>Building Targets with Multiple Configurations</title>
+
+ <para>
+ Bitbake also has functionality that allows you to build
+ multiple targets at the same time, where each target uses
+ a different configuration.
+ </para>
+
+ <para>
+ In order to accomplish this, you setup each of the configurations
+ you need to use in parallel by placing the configuration files in
+ your current build directory alongside the usual
+ <filename>local.conf</filename> file.
+ </para>
+
+ <para>
+ Follow these guidelines to create an environment that supports
+ multiple configurations:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Create Configuration Files</emphasis>:
+ You need to create a single configuration file for each
+ configuration for which you want to add support.
+ These files would contain lines such as the following:
+ <literallayout class='monospaced'>
+ MACHINE = "A"
+ </literallayout>
+ The files would contain any other variables that can
+ be set and built in the same directory.
+ <note>
+ You can change the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ to not conflict.
+ </note></para>
+
+ <para>
+ Furthermore, the configuration file must be located in the
+ current build directory in a directory named
+ <filename>multiconfig</filename> under the build's
+ <filename>conf</filename> directory where
+ <filename>local.conf</filename> resides.
+ The reason for this restriction is because the
+ <filename>BBPATH</filename> variable is not constructed
+ until the layers are parsed.
+ Consequently, using the configuration file as a
+ pre-configuration file is not possible unless it is
+ located in the current working directory.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>:
+ Use the
+ <filename>BBMULTICONFIG</filename>
+ variable in your <filename>conf/local.conf</filename>
+ configuration file to specify each separate configuration.
+ For example, the following line tells BitBake it should load
+ <filename>conf/multiconfig/configA.conf</filename>,
+ <filename>conf/multiconfig/configB.conf</filename>, and
+ <filename>conf/multiconfig/configC.conf</filename>.
+ <literallayout class='monospaced'>
+ BBMULTICONFIG = "configA configB configC"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Launch BitBake</emphasis>:
+ Use the following BitBake command form to launch the
+ build:
+ <literallayout class='monospaced'>
+ $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
+ </literallayout>
+ Following is an example that supports building a minimal
+ image for configuration A alongside a standard
+ <filename>core-image-sato</filename>, which takes its
+ configuration from <filename>local.conf</filename>:
+ <literallayout class='monospaced'>
+ $ bitbake multiconfig:configA:core-image-minimal core-image-sato
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Support for multiple configurations in this current release of
+ the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues:
+ <itemizedlist>
+ <listitem><para>
+ No inter-multi-configuration dependencies exist.
+ </para></listitem>
+ <listitem><para>
+ Shared State (sstate) optimizations do not exist.
+ Consequently, if the build uses the same object twice
+ in, for example, two different
+ <filename>TMPDIR</filename> directories, the build
+ will either load from an existing sstate cache at the
+ start or build the object twice.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='building-an-initramfs-image'>
+ <title>Building an Initial RAM Filesystem (initramfs) Image</title>
+
+ <para>
+ An initial RAM filesystem (initramfs) image provides a temporary
+ root filesystem used for early system initialization (e.g.
+ loading of modules needed to locate and mount the "real" root
+ filesystem).
+ <note>
+ The initramfs image is the successor of initial RAM disk
+ (initrd).
+ It is a "copy in and out" (cpio) archive of the initial
+ filesystem that gets loaded into memory during the Linux
+ startup process.
+ Because Linux uses the contents of the archive during
+ initialization, the initramfs image needs to contain all of the
+ device drivers and tools needed to mount the final root
+ filesystem.
+ </note>
+ </para>
+
+ <para>
+ Follow these steps to create an initramfs image:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Create the initramfs Image Recipe:</emphasis>
+ You can reference the
+ <filename>core-image-minimal-initramfs.bb</filename>
+ recipe found in the <filename>meta/recipes-core</filename>
+ directory of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ as an example from which to work.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Decide if You Need to Bundle the initramfs Image
+ Into the Kernel Image:</emphasis>
+ If you want the initramfs image that is built to be
+ bundled in with the kernel image, set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable to "1" in your <filename>local.conf</filename>
+ configuration file and set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
+ variable in the recipe that builds the kernel image.
+ <note><title>Tip</title>
+ It is recommended that you do bundle the initramfs
+ image with the kernel image to avoid circular
+ dependencies between the kernel recipe and the
+ initramfs recipe should the initramfs image
+ include kernel modules.
+ </note>
+ Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
+ flag causes the initramfs image to be unpacked
+ into the <filename>${B}/usr/</filename> directory.
+ The unpacked initramfs image is then passed to the kernel's
+ <filename>Makefile</filename> using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
+ variable, allowing the initramfs image to be built into
+ the kernel normally.
+ <note>
+ If you choose to not bundle the initramfs image with
+ the kernel image, you are essentially using an
+ <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
+ Creating an initrd is handled primarily through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
+ <filename>INITRD_LIVE</filename>, and
+ <filename>INITRD_IMAGE_LIVE</filename> variables.
+ For more information, see the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
+ file.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Optionally Add Items to the initramfs Image
+ Through the initramfs Image Recipe:</emphasis>
+ If you add items to the initramfs image by way of its
+ recipe, you should use
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
+ rather than
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
+ <filename>PACKAGE_INSTALL</filename> gives more direct
+ control of what is added to the image as compared to
+ the defaults you might not necessarily want that are
+ set by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
+ classes.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the Kernel Image and the initramfs
+ Image:</emphasis>
+ Build your kernel image using BitBake.
+ Because the initramfs image recipe is a dependency of the
+ kernel image, the initramfs image is built as well and
+ bundled with the kernel image if you used the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
+ variable described earlier.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='building-a-tiny-system'>
+ <title>Building a Tiny System</title>
+
+ <para>
+ Very small distributions have some significant advantages such
+ as requiring less on-die or in-package memory (cheaper), better
+ performance through efficient cache usage, lower power requirements
+ due to less memory, faster boot times, and reduced development
+ overhead.
+ Some real-world examples where a very small distribution gives
+ you distinct advantages are digital cameras, medical devices,
+ and small headless systems.
+ </para>
+
+ <para>
+ This section presents information that shows you how you can
+ trim your distribution to even smaller sizes than the
+ <filename>poky-tiny</filename> distribution, which is around
+ 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
+ </para>
+
+ <section id='tiny-system-overview'>
+ <title>Overview</title>
+
+ <para>
+ The following list presents the overall steps you need to
+ consider and perform to create distributions with smaller
+ root filesystems, achieve faster boot times, maintain your critical
+ functionality, and avoid initial RAM disks:
+ <itemizedlist>
+ <listitem><para>
+ <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
+ </para></listitem>
+ <listitem><para>
+ <link linkend='iterate-on-the-process'>Iterate on the process.</link>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='goals-and-guiding-principles'>
+ <title>Goals and Guiding Principles</title>
+
+ <para>
+ Before you can reach your destination, you need to know
+ where you are going.
+ Here is an example list that you can use as a guide when
+ creating very small distributions:
+ <itemizedlist>
+ <listitem><para>Determine how much space you need
+ (e.g. a kernel that is 1 Mbyte or less and
+ a root filesystem that is 3 Mbytes or less).
+ </para></listitem>
+ <listitem><para>Find the areas that are currently
+ taking 90% of the space and concentrate on reducing
+ those areas.
+ </para></listitem>
+ <listitem><para>Do not create any difficult "hacks"
+ to achieve your goals.</para></listitem>
+ <listitem><para>Leverage the device-specific
+ options.</para></listitem>
+ <listitem><para>Work in a separate layer so that you
+ keep changes isolated.
+ For information on how to create layers, see
+ the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='understand-what-gives-your-image-size'>
+ <title>Understand What Contributes to Your Image Size</title>
+
+ <para>
+ It is easiest to have something to start with when creating
+ your own distribution.
+ You can use the Yocto Project out-of-the-box to create the
+ <filename>poky-tiny</filename> distribution.
+ Ultimately, you will want to make changes in your own
+ distribution that are likely modeled after
+ <filename>poky-tiny</filename>.
+ <note>
+ To use <filename>poky-tiny</filename> in your build,
+ set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+ variable in your
+ <filename>local.conf</filename> file to "poky-tiny"
+ as described in the
+ "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
+ section.
+ </note>
+ </para>
+
+ <para>
+ Understanding some memory concepts will help you reduce the
+ system size.
+ Memory consists of static, dynamic, and temporary memory.
+ Static memory is the TEXT (code), DATA (initialized data
+ in the code), and BSS (uninitialized data) sections.
+ Dynamic memory represents memory that is allocated at runtime:
+ stacks, hash tables, and so forth.
+ Temporary memory is recovered after the boot process.
+ This memory consists of memory used for decompressing
+ the kernel and for the <filename>__init__</filename>
+ functions.
+ </para>
+
+ <para>
+ To help you see where you currently are with kernel and root
+ filesystem sizes, you can use two tools found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in
+ the <filename>scripts/tiny/</filename> directory:
+ <itemizedlist>
+ <listitem><para><filename>ksize.py</filename>: Reports
+ component sizes for the kernel build objects.
+ </para></listitem>
+ <listitem><para><filename>dirsize.py</filename>: Reports
+ component sizes for the root filesystem.</para></listitem>
+ </itemizedlist>
+ This next tool and command help you organize configuration
+ fragments and view file dependencies in a human-readable form:
+ <itemizedlist>
+ <listitem><para><filename>merge_config.sh</filename>:
+ Helps you manage configuration files and fragments
+ within the kernel.
+ With this tool, you can merge individual configuration
+ fragments together.
+ The tool allows you to make overrides and warns you
+ of any missing configuration options.
+ The tool is ideal for allowing you to iterate on
+ configurations, create minimal configurations, and
+ create configuration files for different machines
+ without having to duplicate your process.</para>
+ <para>The <filename>merge_config.sh</filename> script is
+ part of the Linux Yocto kernel Git repositories
+ (i.e. <filename>linux-yocto-3.14</filename>,
+ <filename>linux-yocto-3.10</filename>,
+ <filename>linux-yocto-3.8</filename>, and so forth)
+ in the
+ <filename>scripts/kconfig</filename> directory.</para>
+ <para>For more information on configuration fragments,
+ see the
+ "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
+ section in the Yocto Project Linux Kernel Development
+ Manual.
+ </para></listitem>
+ <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>:
+ Using the BitBake command with these options brings up
+ a Dependency Explorer from which you can view file
+ dependencies.
+ Understanding these dependencies allows you to make
+ informed decisions when cutting out various pieces of the
+ kernel and root filesystem.</para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='trim-the-root-filesystem'>
+ <title>Trim the Root Filesystem</title>
+
+ <para>
+ The root filesystem is made up of packages for booting,
+ libraries, and applications.
+ To change things, you can configure how the packaging happens,
+ which changes the way you build them.
+ You can also modify the filesystem itself or select a different
+ filesystem.
+ </para>
+
+ <para>
+ First, find out what is hogging your root filesystem by running the
+ <filename>dirsize.py</filename> script from your root directory:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>root-directory-of-image</replaceable>
+ $ dirsize.py 100000 > dirsize-100k.log
+ $ cat dirsize-100k.log
+ </literallayout>
+ You can apply a filter to the script to ignore files under
+ a certain size.
+ The previous example filters out any files below 100 Kbytes.
+ The sizes reported by the tool are uncompressed, and thus
+ will be smaller by a relatively constant factor in a
+ compressed root filesystem.
+ When you examine your log file, you can focus on areas of the
+ root filesystem that take up large amounts of memory.
+ </para>
+
+ <para>
+ You need to be sure that what you eliminate does not cripple
+ the functionality you need.
+ One way to see how packages relate to each other is by using
+ the Dependency Explorer UI with the BitBake command:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>image-directory</replaceable>
+ $ bitbake -u taskexp -g <replaceable>image</replaceable>
+ </literallayout>
+ Use the interface to select potential packages you wish to
+ eliminate and see their dependency relationships.
+ </para>
+
+ <para>
+ When deciding how to reduce the size, get rid of packages that
+ result in minimal impact on the feature set.
+ For example, you might not need a VGA display.
+ Or, you might be able to get by with <filename>devtmpfs</filename>
+ and <filename>mdev</filename> instead of
+ <filename>udev</filename>.
+ </para>
+
+ <para>
+ Use your <filename>local.conf</filename> file to make changes.
+ For example, to eliminate <filename>udev</filename> and
+ <filename>glib</filename>, set the following in the
+ local configuration file:
+ <literallayout class='monospaced'>
+ VIRTUAL-RUNTIME_dev_manager = ""
+ </literallayout>
+ </para>
+
+ <para>
+ Finally, you should consider exactly the type of root
+ filesystem you need to meet your needs while also reducing
+ its size.
+ For example, consider <filename>cramfs</filename>,
+ <filename>squashfs</filename>, <filename>ubifs</filename>,
+ <filename>ext2</filename>, or an <filename>initramfs</filename>
+ using <filename>initramfs</filename>.
+ Be aware that <filename>ext3</filename> requires a 1 Mbyte
+ journal.
+ If you are okay with running read-only, you do not need this
+ journal.
+ </para>
+
+ <note>
+ After each round of elimination, you need to rebuild your
+ system and then use the tools to see the effects of your
+ reductions.
+ </note>
+ </section>
+
+ <section id='trim-the-kernel'>
+ <title>Trim the Kernel</title>
+
+ <para>
+ The kernel is built by including policies for hardware-independent
+ aspects.
+ What subsystems do you enable?
+ For what architecture are you building?
+ Which drivers do you build by default?
+ <note>You can modify the kernel source if you want to help
+ with boot time.
+ </note>
+ </para>
+
+ <para>
+ Run the <filename>ksize.py</filename> script from the top-level
+ Linux build directory to get an idea of what is making up
+ the kernel:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>top-level-linux-build-directory</replaceable>
+ $ ksize.py > ksize.log
+ $ cat ksize.log
+ </literallayout>
+ When you examine the log, you will see how much space is
+ taken up with the built-in <filename>.o</filename> files for
+ drivers, networking, core kernel files, filesystem, sound,
+ and so forth.
+ The sizes reported by the tool are uncompressed, and thus
+ will be smaller by a relatively constant factor in a compressed
+ kernel image.
+ Look to reduce the areas that are large and taking up around
+ the "90% rule."
+ </para>
+
+ <para>
+ To examine, or drill down, into any particular area, use the
+ <filename>-d</filename> option with the script:
+ <literallayout class='monospaced'>
+ $ ksize.py -d > ksize.log
+ </literallayout>
+ Using this option breaks out the individual file information
+ for each area of the kernel (e.g. drivers, networking, and
+ so forth).
+ </para>
+
+ <para>
+ Use your log file to see what you can eliminate from the kernel
+ based on features you can let go.
+ For example, if you are not going to need sound, you do not
+ need any drivers that support sound.
+ </para>
+
+ <para>
+ After figuring out what to eliminate, you need to reconfigure
+ the kernel to reflect those changes during the next build.
+ You could run <filename>menuconfig</filename> and make all your
+ changes at once.
+ However, that makes it difficult to see the effects of your
+ individual eliminations and also makes it difficult to replicate
+ the changes for perhaps another target device.
+ A better method is to start with no configurations using
+ <filename>allnoconfig</filename>, create configuration
+ fragments for individual changes, and then manage the
+ fragments into a single configuration file using
+ <filename>merge_config.sh</filename>.
+ The tool makes it easy for you to iterate using the
+ configuration change and build cycle.
+ </para>
+
+ <para>
+ Each time you make configuration changes, you need to rebuild
+ the kernel and check to see what impact your changes had on
+ the overall size.
+ </para>
+ </section>
+
+ <section id='remove-package-management-requirements'>
+ <title>Remove Package Management Requirements</title>
+
+ <para>
+ Packaging requirements add size to the image.
+ One way to reduce the size of the image is to remove all the
+ packaging requirements from the image.
+ This reduction includes both removing the package manager
+ and its unique dependencies as well as removing the package
+ management data itself.
+ </para>
+
+ <para>
+ To eliminate all the packaging requirements for an image,
+ be sure that "package-management" is not part of your
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+ statement for the image.
+ When you remove this feature, you are removing the package
+ manager as well as its dependencies from the root filesystem.
+ </para>
+ </section>
+
+ <section id='look-for-other-ways-to-minimize-size'>
+ <title>Look for Other Ways to Minimize Size</title>
+
+ <para>
+ Depending on your particular circumstances, other areas that you
+ can trim likely exist.
+ The key to finding these areas is through tools and methods
+ described here combined with experimentation and iteration.
+ Here are a couple of areas to experiment with:
+ <itemizedlist>
+ <listitem><para><filename>glibc</filename>:
+ In general, follow this process:
+ <orderedlist>
+ <listitem><para>Remove <filename>glibc</filename>
+ features from
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+ that you think you do not need.</para></listitem>
+ <listitem><para>Build your distribution.
+ </para></listitem>
+ <listitem><para>If the build fails due to missing
+ symbols in a package, determine if you can
+ reconfigure the package to not need those
+ features.
+ For example, change the configuration to not
+ support wide character support as is done for
+ <filename>ncurses</filename>.
+ Or, if support for those characters is needed,
+ determine what <filename>glibc</filename>
+ features provide the support and restore the
+ configuration.
+ </para></listitem>
+ <listitem><para>Rebuild and repeat the process.
+ </para></listitem>
+ </orderedlist></para></listitem>
+ <listitem><para><filename>busybox</filename>:
+ For BusyBox, use a process similar as described for
+ <filename>glibc</filename>.
+ A difference is you will need to boot the resulting
+ system to see if you are able to do everything you
+ expect from the running system.
+ You need to be sure to integrate configuration fragments
+ into Busybox because BusyBox handles its own core
+ features and then allows you to add configuration
+ fragments on top.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='iterate-on-the-process'>
+ <title>Iterate on the Process</title>
+
+ <para>
+ If you have not reached your goals on system size, you need
+ to iterate on the process.
+ The process is the same.
+ Use the tools and see just what is taking up 90% of the root
+ filesystem and the kernel.
+ Decide what you can eliminate without limiting your device
+ beyond what you need.
+ </para>
+
+ <para>
+ Depending on your system, a good place to look might be
+ Busybox, which provides a stripped down
+ version of Unix tools in a single, executable file.
+ You might be able to drop virtual terminal services or perhaps
+ ipv6.
+ </para>
+ </section>
+ </section>
+
+ <section id='building-images-for-more-than-one-machine'>
+ <title>Building Images for More than One Machine</title>
+
+ <para>
+ A common scenario developers face is creating images for several
+ different machines that use the same software environment.
+ In this situation, it is tempting to set the
+ tunings and optimization flags for each build specifically for
+ the targeted hardware (i.e. "maxing out" the tunings).
+ Doing so can considerably add to build times and package feed
+ maintenance collectively for the machines.
+ For example, selecting tunes that are extremely specific to a
+ CPU core used in a system might enable some micro optimizations
+ in GCC for that particular system but would otherwise not gain
+ you much of a performance difference across the other systems
+ as compared to using a more general tuning across all the builds
+ (e.g. setting
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>
+ specifically for each machine's build).
+ Rather than "max out" each build's tunings, you can take steps that
+ cause the OpenEmbedded build system to reuse software across the
+ various machines where it makes sense.
+ </para>
+
+ <para>
+ If build speed and package feed maintenance are considerations,
+ you should consider the points in this section that can help you
+ optimize your tunings to best consider build times and package
+ feed maintenance.
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Share the Build Directory:</emphasis>
+ If at all possible, share the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ across builds.
+ The Yocto Project supports switching between different
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+ values in the same <filename>TMPDIR</filename>.
+ This practice is well supported and regularly used by
+ developers when building for multiple machines.
+ When you use the same <filename>TMPDIR</filename> for
+ multiple machine builds, the OpenEmbedded build system can
+ reuse the existing native and often cross-recipes for
+ multiple machines.
+ Thus, build time decreases.
+ <note>
+ If
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+ settings change or fundamental configuration settings
+ such as the filesystem layout, you need to work with
+ a clean <filename>TMPDIR</filename>.
+ Sharing <filename>TMPDIR</filename> under these
+ circumstances might work but since it is not
+ guaranteed, you should use a clean
+ <filename>TMPDIR</filename>.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Enable the Appropriate Package Architecture:</emphasis>
+ By default, the OpenEmbedded build system enables three
+ levels of package architectures: "all", "tune" or "package",
+ and "machine".
+ Any given recipe usually selects one of these package
+ architectures (types) for its output.
+ Depending for what a given recipe creates packages, making
+ sure you enable the appropriate package architecture can
+ directly impact the build time.</para>
+
+ <para>A recipe that just generates scripts can enable
+ "all" architecture because there are no binaries to build.
+ To specifically enable "all" architecture, be sure your
+ recipe inherits the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
+ class.
+ This class is useful for "all" architectures because it
+ configures many variables so packages can be used across
+ multiple architectures.</para>
+
+ <para>If your recipe needs to generate packages that are
+ machine-specific or when one of the build or runtime
+ dependencies is already machine-architecture dependent,
+ which makes your recipe also machine-architecture dependent,
+ make sure your recipe enables the "machine" package
+ architecture through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>
+ variable:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCH = "${MACHINE_ARCH}"
+ </literallayout>
+ When you do not specifically enable a package
+ architecture through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
+ The OpenEmbedded build system defaults to the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink>
+ setting:
+ <literallayout class='monospaced'>
+ PACKAGE_ARCH = "${TUNE_PKGARCH}"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Choose a Generic Tuning File if Possible:</emphasis>
+ Some tunes are more generic and can run on multiple targets
+ (e.g. an <filename>armv5</filename> set of packages could
+ run on <filename>armv6</filename> and
+ <filename>armv7</filename> processors in most cases).
+ Similarly, <filename>i486</filename> binaries could work
+ on <filename>i586</filename> and higher processors.
+ You should realize, however, that advances on newer
+ processor versions would not be used.</para>
+
+ <para>If you select the same tune for several different
+ machines, the OpenEmbedded build system reuses software
+ previously built, thus speeding up the overall build time.
+ Realize that even though a new sysroot for each machine is
+ generated, the software is not recompiled and only one
+ package feed exists.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Manage Granular Level Packaging:</emphasis>
+ Sometimes cases exist where injecting another level of
+ package architecture beyond the three higher levels noted
+ earlier can be useful.
+ For example, consider how NXP (formerly Freescale) allows
+ for the easy reuse of binary packages in their layer
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/'><filename>meta-freescale</filename></ulink>.
+ In this example, the
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/meta-freescale/tree/classes/fsl-dynamic-packagearch.bbclass'><filename>fsl-dynamic-packagearch</filename></ulink>
+ class shares GPU packages for i.MX53 boards because
+ all boards share the AMD GPU.
+ The i.MX6-based boards can do the same because all boards
+ share the Vivante GPU.
+ This class inspects the BitBake datastore to identify if
+ the package provides or depends on one of the
+ sub-architecture values.
+ If so, the class sets the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
+ value based on the <filename>MACHINE_SUBARCH</filename>
+ value.
+ If the package does not provide or depend on one of the
+ sub-architecture values but it matches a value in the
+ machine-specific filter, it sets
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>.
+ This behavior reduces the number of packages built and
+ saves build time by reusing binaries.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Use Tools to Debug Issues:</emphasis>
+ Sometimes you can run into situations where software is
+ being rebuilt when you think it should not be.
+ For example, the OpenEmbedded build system might not be
+ using shared state between machines when you think it
+ should be.
+ These types of situations are usually due to references
+ to machine-specific variables such as
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>,
+ and so forth in code that is supposed to only be
+ tune-specific or when the recipe depends
+ (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>,
+ and so forth) on some other recipe that already has
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
+ defined as "${MACHINE_ARCH}".
+ <note>
+ Patches to fix any issues identified are most welcome
+ as these issues occasionally do occur.
+ </note></para>
+
+ <para>For such cases, you can use some tools to help you
+ sort out the situation:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis>
+ You can find this tool in the
+ <filename>scripts</filename> directory of the
+ Source Repositories.
+ See the comments in the script for information on
+ how to use the tool.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>BitBake's "-S printdiff" Option:</emphasis>
+ Using this option causes BitBake to try to
+ establish the closest signature match it can
+ (e.g. in the shared state cache) and then run
+ <filename>bitbake-diffsigs</filename> over the
+ matches to determine the stamps and delta where
+ these two stamp trees diverge.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="building-software-from-an-external-source">
+ <title>Building Software from an External Source</title>
+
+ <para>
+ By default, the OpenEmbedded build system uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ when building source code.
+ The build process involves fetching the source files, unpacking
+ them, and then patching them if necessary before the build takes
+ place.
+ </para>
+
+ <para>
+ Situations exist where you might want to build software from source
+ files that are external to and thus outside of the
+ OpenEmbedded build system.
+ For example, suppose you have a project that includes a new BSP with
+ a heavily customized kernel.
+ And, you want to minimize exposing the build system to the
+ development team so that they can focus on their project and
+ maintain everyone's workflow as much as possible.
+ In this case, you want a kernel source directory on the development
+ machine where the development occurs.
+ You want the recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ variable to point to the external directory and use it as is, not
+ copy it.
+ </para>
+
+ <para>
+ To build from software that comes from an external source, all you
+ need to do is inherit the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
+ class and then set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
+ variable to point to your external source code.
+ Here are the statements to put in your
+ <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ INHERIT += "externalsrc"
+ EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
+ </literallayout>
+ </para>
+
+ <para>
+ This next example shows how to accomplish the same thing by setting
+ <filename>EXTERNALSRC</filename> in the recipe itself or in the
+ recipe's append file:
+ <literallayout class='monospaced'>
+ EXTERNALSRC = "<replaceable>path</replaceable>"
+ EXTERNALSRC_BUILD = "<replaceable>path</replaceable>"
+ </literallayout>
+ <note>
+ In order for these settings to take effect, you must globally
+ or locally inherit the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
+ class.
+ </note>
+ </para>
+
+ <para>
+ By default, <filename>externalsrc.bbclass</filename> builds
+ the source code in a directory separate from the external source
+ directory as specified by
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
+ If you need to have the source built in the same directory in
+ which it resides, or some other nominated directory, you can set
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
+ to point to that directory:
+ <literallayout class='monospaced'>
+ EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
+ </literallayout>
+ </para>
+ </section>
+ </section>
+
+
+
+ <section id='speeding-up-a-build'>
+ <title>Speeding Up a Build</title>
<para>
- Follow these guidelines to create an environment that supports
- multiple configurations:
+ Build time can be an issue.
+ By default, the build system uses simple controls to try and maximize
+ build efficiency.
+ In general, the default settings for all the following variables
+ result in the most efficient build times when dealing with single
+ socket systems (i.e. a single CPU).
+ If you have multiple CPUs, you might try increasing the default
+ values to gain more speed.
+ See the descriptions in the glossary for each variable for more
+ information:
<itemizedlist>
<listitem><para>
- <emphasis>Create Configuration Files</emphasis>:
- You need to create a single configuration file for each
- configuration for which you want to add support.
- These files would contain lines such as the following:
- <literallayout class='monospaced'>
- MACHINE = "A"
- </literallayout>
- The files would contain any other variables that can
- be set and built in the same directory.
- <note>
- You can change the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
- to not conflict.
- </note></para>
-
- <para>
- Furthermore, the configuration file must be located in the
- current build directory in a directory named
- <filename>multiconfig</filename> under the build's
- <filename>conf</filename> directory where
- <filename>local.conf</filename> resides.
- The reason for this restriction is because the
- <filename>BBPATH</filename> variable is not constructed
- until the layers are parsed.
- Consequently, using the configuration file as a
- pre-configuration file is not possible unless it is
- located in the current working directory.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename>:</ulink>
+ The maximum number of threads BitBake simultaneously executes.
</para></listitem>
<listitem><para>
- <emphasis>Add the BitBake Multi-Config Variable to you Local Configuration File</emphasis>:
- Use the
- <filename>BBMULTICONFIG</filename>
- variable in your <filename>conf/local.conf</filename>
- configuration file to specify each separate configuration.
- For example, the following line tells BitBake it should load
- <filename>conf/multiconfig/configA.conf</filename>,
- <filename>conf/multiconfig/configB.conf</filename>, and
- <filename>conf/multiconfig/configC.conf</filename>.
- <literallayout class='monospaced'>
- BBMULTICONFIG = "configA configB configC"
- </literallayout>
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_NUMBER_PARSE_THREADS'><filename>BB_NUMBER_PARSE_THREADS</filename>:</ulink>
+ The number of threads BitBake uses during parsing.
</para></listitem>
<listitem><para>
- <emphasis>Launch BitBake</emphasis>:
- Use the following BitBake command form to launch the
- build:
- <literallayout class='monospaced'>
- $ bitbake [multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable> [[[multiconfig:<replaceable>multiconfigname</replaceable>:]<replaceable>target</replaceable>] ... ]
- </literallayout>
- Following is an example that supports building a minimal
- image for configuration A alongside a standard
- <filename>core-image-sato</filename>, which takes its
- configuration from <filename>local.conf</filename>:
- <literallayout class='monospaced'>
- $ bitbake multiconfig:configA:core-image-minimal core-image-sato
- </literallayout>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename>:</ulink>
+ Extra options passed to the <filename>make</filename> command
+ during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
+ task in order to specify parallel compilation on the
+ local build host.
+ </para></listitem>
+ <listitem><para>
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename>:</ulink>
+ Extra options passed to the <filename>make</filename> command
+ during the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-install'><filename>do_install</filename></ulink>
+ task in order to specify parallel installation on the
+ local build host.
</para></listitem>
</itemizedlist>
+ As mentioned, these variables all scale to the number of processor
+ cores available on the build system.
+ For single socket systems, this auto-scaling ensures that the build
+ system fundamentally takes advantage of potential parallel operations
+ during the build based on the build machine's capabilities.
</para>
<para>
- Support for multiple configurations in this current release of
- the Yocto Project (&DISTRO_NAME; &DISTRO;) has some known issues:
+ Following are additional factors that can affect build speed:
<itemizedlist>
<listitem><para>
- No inter-multi-configuration dependencies exist.
+ File system type:
+ The file system type that the build is being performed on can
+ also influence performance.
+ Using <filename>ext4</filename> is recommended as compared
+ to <filename>ext2</filename> and <filename>ext3</filename>
+ due to <filename>ext4</filename> improved features
+ such as extents.
</para></listitem>
<listitem><para>
- Shared State (sstate) optimizations do not exist.
- Consequently, if the build uses the same object twice
- in, for example, two different
- <filename>TMPDIR</filename> directories, the build
- will either load from an existing sstate cache at the
- start or build the object twice.
+ Disabling the updating of access time using
+ <filename>noatime</filename>:
+ The <filename>noatime</filename> mount option prevents the
+ build system from updating file and directory access times.
</para></listitem>
+ <listitem><para>
+ Setting a longer commit:
+ Using the "commit=" mount option increases the interval
+ in seconds between disk cache writes.
+ Changing this interval from the five second default to
+ something longer increases the risk of data loss but decreases
+ the need to write to the disk, thus increasing the build
+ performance.
+ </para></listitem>
+ <listitem><para>
+ Choosing the packaging backend:
+ Of the available packaging backends, IPK is the fastest.
+ Additionally, selecting a singular packaging backend also
+ helps.
+ </para></listitem>
+ <listitem><para>
+ Using <filename>tmpfs</filename> for
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ as a temporary file system:
+ While this can help speed up the build, the benefits are
+ limited due to the compiler using
+ <filename>-pipe</filename>.
+ The build system goes to some lengths to avoid
+ <filename>sync()</filename> calls into the
+ file system on the principle that if there was a significant
+ failure, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ contents could easily be rebuilt.
+ </para></listitem>
+ <listitem><para>
+ Inheriting the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+ class:
+ Inheriting this class has shown to speed up builds due to
+ significantly lower amounts of data stored in the data
+ cache as well as on disk.
+ Inheriting this class also makes cleanup of
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ faster, at the expense of being easily able to dive into the
+ source code.
+ File system maintainers have recommended that the fastest way
+ to clean up large numbers of files is to reformat partitions
+ rather than delete files due to the linear nature of
+ partitions.
+ This, of course, assumes you structure the disk partitions and
+ file systems in a way that this is practical.
+ </para></listitem>
+ </itemizedlist>
+ Aside from the previous list, you should keep some trade offs in
+ mind that can help you speed up the build:
+ <itemizedlist>
+ <listitem><para>
+ Remove items from
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+ that you might not need.
+ </para></listitem>
+ <listitem><para>
+ Exclude debug symbols and other debug information:
+ If you do not need these symbols and other debug information,
+ disabling the <filename>*-dbg</filename> package generation
+ can speed up the build.
+ You can disable this generation by setting the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-INHIBIT_PACKAGE_DEBUG_SPLIT'><filename>INHIBIT_PACKAGE_DEBUG_SPLIT</filename></ulink>
+ variable to "1".
+ </para></listitem>
+ <listitem><para>
+ Disable static library generation for recipes derived from
+ <filename>autoconf</filename> or <filename>libtool</filename>:
+ Following is an example showing how to disable static
+ libraries and still provide an override to handle exceptions:
+ <literallayout class='monospaced'>
+ STATICLIBCONF = "--disable-static"
+ STATICLIBCONF_sqlite3-native = ""
+ EXTRA_OECONF += "${STATICLIBCONF}"
+ </literallayout>
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Some recipes need static libraries in order to work
+ correctly (e.g. <filename>pseudo-native</filename>
+ needs <filename>sqlite3-native</filename>).
+ Overrides, as in the previous example, account for
+ these kinds of exceptions.
+ </para></listitem>
+ <listitem><para>
+ Some packages have packaging code that assumes the
+ presence of the static libraries.
+ If so, you might need to exclude them as well.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para></listitem>
</itemizedlist>
</para>
</section>
@@ -4543,6 +6723,84 @@
</section>
</section>
+ <section id='using-x32-psabi'>
+ <title>Using x32 psABI</title>
+
+ <para>
+ x32 processor-specific Application Binary Interface
+ (<ulink url='https://software.intel.com/en-us/node/628948'>x32 psABI</ulink>)
+ is a native 32-bit processor-specific ABI for
+ <trademark class='registered'>Intel</trademark> 64 (x86-64)
+ architectures.
+ An ABI defines the calling conventions between functions in a
+ processing environment.
+ The interface determines what registers are used and what the
+ sizes are for various C data types.
+ </para>
+
+ <para>
+ Some processing environments prefer using 32-bit applications even
+ when running on Intel 64-bit platforms.
+ Consider the i386 psABI, which is a very old 32-bit ABI for Intel
+ 64-bit platforms.
+ The i386 psABI does not provide efficient use and access of the
+ Intel 64-bit processor resources, leaving the system underutilized.
+ Now consider the x86_64 psABI.
+ This ABI is newer and uses 64-bits for data sizes and program
+ pointers.
+ The extra bits increase the footprint size of the programs,
+ libraries, and also increases the memory and file system size
+ requirements.
+ Executing under the x32 psABI enables user programs to utilize CPU
+ and system resources more efficiently while keeping the memory
+ footprint of the applications low.
+ Extra bits are used for registers but not for addressing mechanisms.
+ </para>
+
+ <para>
+ The Yocto Project supports the final specifications of x32 psABI
+ as follows:
+ <itemizedlist>
+ <listitem><para>
+ You can create packages and images in x32 psABI format on
+ x86_64 architecture targets.
+ </para></listitem>
+ <listitem><para>
+ You can successfully build recipes with the x32 toolchain.
+ </para></listitem>
+ <listitem><para>
+ You can create and boot
+ <filename>core-image-minimal</filename> and
+ <filename>core-image-sato</filename> images.
+ </para></listitem>
+ <listitem><para>
+ RPM Package Manager (RPM) support exists for x32 binaries.
+ </para></listitem>
+ <listitem><para>
+ Support for large images exists.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ To use the x32 psABI, you need to edit your
+ <filename>conf/local.conf</filename> configuration file as
+ follows:
+ <literallayout class='monospaced'>
+ MACHINE = "qemux86-64"
+ DEFAULTTUNE = "x86-64-x32"
+ baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
+ or 'INVALID'), True) or 'lib'}"
+ </literallayout>
+ Once you have set up your configuration file, use BitBake to
+ build an image that supports the x32 psABI.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake core-image-sato
+ </literallayout>
+ </para>
+ </section>
+
<section id='enabling-gobject-introspection-support'>
<title>Enabling GObject Introspection Support</title>
@@ -4795,8 +7053,7 @@
variable.
</para></listitem>
<listitem><para>
- Set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNAL_TOOLCHAIN'><filename>EXTERNAL_TOOLCHAIN</filename></ulink>
+ Set the <filename>EXTERNAL_TOOLCHAIN</filename>
variable in your <filename>local.conf</filename> file
to the location in which you installed the toolchain.
</para></listitem>
@@ -4846,7 +7103,7 @@
system.
<note>
For a kickstart file reference, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#openembedded-kickstart-wks-reference'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</ulink>"
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-kickstart'>OpenEmbedded Kickstart (<filename>.wks</filename>) Reference</ulink>"
Chapter in the Yocto Project Reference Manual.
</note>
</para>
@@ -4858,16 +7115,17 @@
customized images, and as such, was designed to be
completely extensible through a plug-in interface.
See the
- "<ulink url='&YOCTO_DOCS_REF_URL;#wic-plug-ins-interface'>Wic Plug-Ins Interface</ulink>"
- section in the Yocto Project Reference Manual for information
- on these plug-ins.
+ "<link linkend='wic-using-the-wic-plug-ins-interface'>Using the Wic Plug-Ins Interface</link>"
+ section for information on these plug-ins.
</para>
<para>
This section provides some background information on Wic,
describes what you need to have in
place to run the tool, provides instruction on how to use
- the Wic utility, and provides several examples.
+ the Wic utility, provides information on using the Wic plug-ins
+ interface, and provides several examples that show how to use
+ Wic.
</para>
<section id='wic-background'>
@@ -4899,7 +7157,7 @@
Wic is a completely independent
standalone utility that initially provides
easier-to-use and more flexible replacements for an
- existing functionality in OE Core's
+ existing functionality in OE-Core's
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image-live'><filename>image-live</filename></ulink>
class and <filename>mkefidisk.sh</filename> script.
The difference between
@@ -4988,6 +7246,7 @@
<literallayout class='monospaced'>
$ wic -h
$ wic --help
+ $ wic help
</literallayout>
</para>
@@ -4997,51 +7256,66 @@
<filename>help</filename>, <filename>list</filename>,
<filename>ls</filename>, <filename>rm</filename>, and
<filename>write</filename>.
- You can get help for these commands as follows with
- <replaceable>command</replaceable> being one of the
- supported commands:
+ You can get help for all these commands except "help" by
+ using the following form:
<literallayout class='monospaced'>
$ wic help <replaceable>command</replaceable>
</literallayout>
- </para>
-
- <para>
- You can also get detailed help on a number of topics
- from the help system.
- The output of <filename>wic --help</filename>
- displays a list of available help
- topics under a "Help topics" heading.
- You can have the help system display the help text for
- a given topic by prefacing the topic with
- <filename>wic help</filename>:
+ For example, the following command returns help for the
+ <filename>write</filename> command:
<literallayout class='monospaced'>
- $ wic help <replaceable>help_topic</replaceable>
+ $ wic help write
</literallayout>
</para>
<para>
- You can find out more about the images Wic creates using
- the existing kickstart files with the following form of
- the command:
+ Wic supports help for three topics:
+ <filename>overview</filename>,
+ <filename>plugins</filename>, and
+ <filename>kickstart</filename>.
+ You can get help for any topic using the following form:
<literallayout class='monospaced'>
- $ wic list <replaceable>image</replaceable> help
+ $ wic help <replaceable>topic</replaceable>
</literallayout>
- For <replaceable>image</replaceable>, you can provide
- any of the following:
+ For example, the following returns overview help for Wic:
<literallayout class='monospaced'>
- beaglebone
- mpc8315e-rdb
- genericx86
- edgerouter
- qemux86-directdisk
- directdisk-gpt
- mkefidisk
- directdisk
- systemd-bootdisk
- mkhybridiso
- sdimage-bootpart
- directdisk-multi-rootfs
- directdisk-bootloader-config
+ $ wic help overview
+ </literallayout>
+ </para>
+
+ <para>
+ One additional level of help exists for Wic.
+ You can get help on individual images through the
+ <filename>list</filename> command.
+ You can use the <filename>list</filename> command to return the
+ available Wic images as follows:
+ <literallayout class='monospaced'>
+ $ wic list images
+ mpc8315e-rdb Create SD card image for MPC8315E-RDB
+ genericx86 Create an EFI disk image for genericx86*
+ beaglebone-yocto Create SD card image for Beaglebone
+ edgerouter Create SD card image for Edgerouter
+ qemux86-directdisk Create a qemu machine 'pcbios' direct disk image
+ directdisk-gpt Create a 'pcbios' direct disk image
+ mkefidisk Create an EFI disk image
+ directdisk Create a 'pcbios' direct disk image
+ systemd-bootdisk Create an EFI disk image with systemd-boot
+ mkhybridiso Create a hybrid ISO image
+ sdimage-bootpart Create SD card image with a boot partition
+ directdisk-multi-rootfs Create multi rootfs image using rootfs plugin
+ directdisk-bootloader-config Create a 'pcbios' direct disk image with custom bootloader config
+ </literallayout>
+ Once you know the list of available Wic images, you can use
+ <filename>help</filename> with the command to get help on a
+ particular image.
+ For example, the following command returns help on the
+ "beaglebone-yocto" image:
+ <literallayout class='monospaced'>
+ $ wic list beaglebone-yocto help
+
+
+ Creates a partitioned SD card image for Beaglebone.
+ Boot files are located in the first vfat partition.
</literallayout>
</para>
</section>
@@ -5058,7 +7332,7 @@
<listitem><para>
<emphasis>Raw Mode:</emphasis>
You explicitly specify build artifacts through
- <filename>wic</filename> command-line arguments.
+ Wic command-line arguments.
</para></listitem>
<listitem><para>
<emphasis>Cooked Mode:</emphasis>
@@ -5153,7 +7427,7 @@
<para>
Running Wic in cooked mode leverages off artifacts in
- Build Directory.
+ the Build Directory.
In other words, you do not have to specify kernel or
root filesystem locations as part of the command.
All you need to provide is a kickstart file and the
@@ -5195,7 +7469,7 @@
can use an existing file provided by the Wic installation.
As shipped, kickstart files can be found in the
Yocto Project
- <ulink url='&YOCTO_DOCS_REF_URL;#source-repositories'>Source Repositories</ulink>
+ <ulink url='&YOCTO_DOCS_OM_URL;#source-repositories'>Source Repositories</ulink>
in the following two locations:
<literallayout class='monospaced'>
poky/meta-yocto-bsp/wic
@@ -5205,9 +7479,9 @@
files:
<literallayout class='monospaced'>
$ wic list images
- beaglebone Create SD card image for Beaglebone
mpc8315e-rdb Create SD card image for MPC8315E-RDB
genericx86 Create an EFI disk image for genericx86*
+ beaglebone-yocto Create SD card image for Beaglebone
edgerouter Create SD card image for Edgerouter
qemux86-directdisk Create a qemu machine 'pcbios' direct disk image
directdisk-gpt Create a 'pcbios' direct disk image
@@ -5245,6 +7519,209 @@
</para>
</section>
+ <section id='wic-using-the-wic-plug-ins-interface'>
+ <title>Using the Wic Plug-Ins Interface</title>
+
+ <para>
+ You can extend and specialize Wic functionality by using
+ Wic plug-ins.
+ This section explains the Wic plug-in interface.
+ <note>
+ Wic plug-ins consist of "source" and "imager" plug-ins.
+ Imager plug-ins are beyond the scope of this section.
+ </note>
+ </para>
+
+ <para>
+ Source plug-ins provide a mechanism to customize partition
+ content during the Wic image generation process.
+ You can use source plug-ins to map values that you specify
+ using <filename>--source</filename> commands in kickstart
+ files (i.e. <filename>*.wks</filename>) to a plug-in
+ implementation used to populate a given partition.
+ <note>
+ If you use plug-ins that have build-time dependencies
+ (e.g. native tools, bootloaders, and so forth)
+ when building a Wic image, you need to specify those
+ dependencies using the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WKS_FILE_DEPENDS'><filename>WKS_FILE_DEPENDS</filename></ulink>
+ variable.
+ </note>
+ </para>
+
+ <para>
+ Source plug-ins are subclasses defined in plug-in files.
+ As shipped, the Yocto Project provides several plug-in
+ files.
+ You can see the source plug-in files that ship with the
+ Yocto Project
+ <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/scripts/lib/wic/plugins/source'>here</ulink>.
+ Each of these plug-in files contains source plug-ins that
+ are designed to populate a specific Wic image partition.
+ </para>
+
+ <para>
+ Source plug-ins are subclasses of the
+ <filename>SourcePlugin</filename> class, which is
+ defined in the
+ <filename>poky/scripts/lib/wic/pluginbase.py</filename>
+ file.
+ For example, the <filename>BootimgEFIPlugin</filename>
+ source plug-in found in the
+ <filename>bootimg-efi.py</filename> file is a subclass of
+ the <filename>SourcePlugin</filename> class, which is found
+ in the <filename>pluginbase.py</filename> file.
+ </para>
+
+ <para>
+ You can also implement source plug-ins in a layer outside
+ of the Source Repositories (external layer).
+ To do so, be sure that your plug-in files are located in
+ a directory whose path is
+ <filename>scripts/lib/wic/plugins/source/</filename>
+ within your external layer.
+ When the plug-in files are located there, the source
+ plug-ins they contain are made available to Wic.
+ </para>
+
+ <para>
+ When the Wic implementation needs to invoke a
+ partition-specific implementation, it looks for the plug-in
+ with the same name as the <filename>--source</filename>
+ parameter used in the kickstart file given to that
+ partition.
+ For example, if the partition is set up using the following
+ command in a kickstart file:
+ <literallayout class='monospaced'>
+ part /boot --source bootimg-pcbios --ondisk sda --label boot --active --align 1024
+ </literallayout>
+ The methods defined as class members of the matching
+ source plug-in (i.e. <filename>bootimg-pcbios</filename>)
+ in the <filename>bootimg-pcbios.py</filename> plug-in file
+ are used.
+ </para>
+
+ <para>
+ To be more concrete, here is the corresponding plug-in
+ definition from the <filename>bootimg-pcbios.py</filename>
+ file for the previous command along with an example
+ method called by the Wic implementation when it needs to
+ prepare a partition using an implementation-specific
+ function:
+ <literallayout class='monospaced'>
+ .
+ .
+ .
+ class BootimgPcbiosPlugin(SourcePlugin):
+ """
+ Create MBR boot partition and install syslinux on it.
+ """
+
+ name = 'bootimg-pcbios'
+ .
+ .
+ .
+ @classmethod
+ def do_prepare_partition(cls, part, source_params, creator, cr_workdir,
+ oe_builddir, bootimg_dir, kernel_dir,
+ rootfs_dir, native_sysroot):
+ """
+ Called to do the actual content population for a partition i.e. it
+ 'prepares' the partition to be incorporated into the image.
+ In this case, prepare content for legacy bios boot partition.
+ """
+ .
+ .
+ .
+ </literallayout>
+ If a subclass (plug-in) itself does not implement a
+ particular function, Wic locates and uses the default
+ version in the superclass.
+ It is for this reason that all source plug-ins are derived
+ from the <filename>SourcePlugin</filename> class.
+ </para>
+
+ <para>
+ The <filename>SourcePlugin</filename> class defined in
+ the <filename>pluginbase.py</filename> file defines
+ a set of methods that source plug-ins can implement or
+ override.
+ Any plug-ins (subclass of
+ <filename>SourcePlugin</filename>) that do not implement
+ a particular method inherit the implementation of the
+ method from the <filename>SourcePlugin</filename> class.
+ For more information, see the
+ <filename>SourcePlugin</filename> class in the
+ <filename>pluginbase.py</filename> file for details:
+ </para>
+
+ <para>
+ The following list describes the methods implemented in the
+ <filename>SourcePlugin</filename> class:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis><filename>do_prepare_partition()</filename>:</emphasis>
+ Called to populate a partition with actual content.
+ In other words, the method prepares the final
+ partition image that is incorporated into the
+ disk image.
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_configure_partition()</filename>:</emphasis>
+ Called before
+ <filename>do_prepare_partition()</filename> to
+ create custom configuration files for a partition
+ (e.g. syslinux or grub configuration files).
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_install_disk()</filename>:</emphasis>
+ Called after all partitions have been prepared and
+ assembled into a disk image.
+ This method provides a hook to allow finalization
+ of a disk image (e.g. writing an MBR).
+ </para></listitem>
+ <listitem><para>
+ <emphasis><filename>do_stage_partition()</filename>:</emphasis>
+ Special content-staging hook called before
+ <filename>do_prepare_partition()</filename>.
+ This method is normally empty.</para>
+
+ <para>Typically, a partition just uses the passed-in
+ parameters (e.g. the unmodified value of
+ <filename>bootimg_dir</filename>).
+ However, in some cases, things might need to be
+ more tailored.
+ As an example, certain files might additionally
+ need to be taken from
+ <filename>bootimg_dir + /boot</filename>.
+ This hook allows those files to be staged in a
+ customized fashion.
+ <note>
+ <filename>get_bitbake_var()</filename>
+ allows you to access non-standard variables
+ that you might want to use for this
+ behavior.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ You can extend the source plug-in mechanism.
+ To add more hooks, create more source plug-in methods
+ within <filename>SourcePlugin</filename> and the
+ corresponding derived subclasses.
+ The code that calls the plug-in methods uses the
+ <filename>plugin.get_source_plugin_methods()</filename>
+ function to find the method or methods needed by the call.
+ Retrieval of those methods is accomplished by filling up
+ a dict with keys that contain the method names of interest.
+ On success, these will be filled in with the actual
+ methods.
+ See the Wic implementation for examples and details.
+ </para>
+ </section>
+
<section id='wic-usage-examples'>
<title>Examples</title>
@@ -5271,16 +7748,16 @@
.
.
INFO: The new image(s) can be found here:
- ./mkefidisk-201710061409-sda.direct
+ ./mkefidisk-201804191017-sda.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.r4hkds0b/rootfs_copy
- BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
- NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/scottrif/poky/scripts/lib/wic/canned-wks/mkefidisk.wks
+ /home/stephano/build/master/openembedded-core/scripts/lib/wic/canned-wks/mkefidisk.wks
</literallayout>
The previous example shows the easiest way to create
an image by running in cooked mode and supplying
@@ -5305,17 +7782,18 @@
<para>
Continuing with the example, you can now write the
- image to a USB stick, or whatever media for which you
- built your image, and boot from the media.
+ image from the Build Directory onto a USB stick, or
+ whatever media for which you built your image, and boot
+ from the media.
You can write the image by using
<filename>bmaptool</filename> or
<filename>dd</filename>:
<literallayout class='monospaced'>
- $ oe-run-native bmaptool copy build/mkefidisk-201710061409-sda.direct /dev/sd<replaceable>X</replaceable>
+ $ oe-run-native bmaptool copy mkefidisk-201804191017-sda.direct /dev/sd<replaceable>X</replaceable>
</literallayout>
or
<literallayout class='monospaced'>
- $ sudo dd if=build/mkefidisk-201710061409-sda.direct of=/dev/sd<replaceable>X</replaceable>
+ $ sudo dd if=mkefidisk-201804191017-sda.direct of=/dev/sd<replaceable>X</replaceable>
</literallayout>
<note>
For more information on how to use the
@@ -5375,8 +7853,8 @@
directory and then by changing the lines that specify
the target disk from which to boot.
<literallayout class='monospaced'>
- $ cp /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
- /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
+ $ cp /home/stephano/poky/scripts/lib/wic/canned-wks/directdisk-gpt.wks \
+ /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
</literallayout>
Next, the example modifies the
<filename>directdisksdb-gpt.wks</filename> file and
@@ -5412,13 +7890,13 @@
./directdisksdb-gpt-201710090938-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/scottrif/poky/build/tmp.wic.hk3wl6zn/rootfs_copy
- BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
- NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/scottrif/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
+ /home/stephano/poky/scripts/lib/wic/canned-wks/directdisksdb-gpt.wks
</literallayout>
Continuing with the example, you can now directly
<filename>dd</filename> the image to a USB stick, or
@@ -5445,25 +7923,25 @@
somewhere other than the default output directory,
which is the current directory:
<literallayout class='monospaced'>
- $ wic create /home/scottrif/my_yocto/test.wks -o /home/scottrif/testwic \
- --rootfs-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
- --bootimg-dir /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
- --kernel-dir /home/scottrif/poky/build/tmp/deploy/images/qemux86 \
- --native-sysroot /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ $ wic create /home/stephano/my_yocto/test.wks -o /home/stephano/testwic \
+ --rootfs-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/rootfs \
+ --bootimg-dir /home/stephano/build/master/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share \
+ --kernel-dir /home/stephano/build/master/build/tmp/deploy/images/qemux86 \
+ --native-sysroot /home/stephano/build/master/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: Creating image(s)...
INFO: The new image(s) can be found here:
- /home/scottrif/testwic/test-201710091445-sdb.direct
+ /home/stephano/testwic/test-201710091445-sdb.direct
The following build artifacts were used to create the image(s):
- ROOTFS_DIR: /home/scottrif/testwic/tmp.wic.x4wipbmb/rootfs_copy
- BOOTIMG_DIR: /home/scottrif/poky/build/tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
- KERNEL_DIR: /home/scottrif/poky/build/tmp/deploy/images/qemux86
- NATIVE_SYSROOT: /home/scottrif/poky/build/tmp/work/i586-poky-linux/wic-tools/1.0-r0/recipe-sysroot-native
+ ROOTFS_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/rootfs
+ BOOTIMG_DIR: /home/stephano/build/master/build/tmp-glibc/work/qemux86-oe-linux/core-image-minimal/1.0-r0/recipe-sysroot/usr/share
+ KERNEL_DIR: /home/stephano/build/master/build/tmp-glibc/deploy/images/qemux86
+ NATIVE_SYSROOT: /home/stephano/build/master/build/tmp-glibc/work/i586-oe-linux/wic-tools/1.0-r0/recipe-sysroot-native
INFO: The image(s) were created using OE kickstart file:
- /home/scottrif/my_yocto/test.wks
+ /home/stephano/my_yocto/test.wks
</literallayout>
For this example,
<ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
@@ -5608,222 +8086,91 @@
</section>
</section>
- <section id='building-an-initramfs-image'>
- <title>Building an Initial RAM Filesystem (initramfs) Image</title>
-
- <para>
- An initial RAM filesystem (initramfs) image provides a temporary
- root filesystem used for early system initialization (e.g.
- loading of modules needed to locate and mount the "real" root
- filesystem).
- <note>
- The initramfs image is the successor of initial RAM disk
- (initrd).
- It is a "copy in and out" (cpio) archive of the initial
- filesystem that gets loaded into memory during the Linux
- startup process.
- Because Linux uses the contents of the archive during
- initialization, the initramfs image needs to contain all of the
- device drivers and tools needed to mount the final root
- filesystem.
- </note>
- </para>
-
- <para>
- Follow these steps to create an initramfs image:
- <orderedlist>
- <listitem><para>
- <emphasis>Create the initramfs Image Recipe:</emphasis>
- You can reference the
- <filename>core-image-minimal-initramfs.bb</filename>
- recipe found in the <filename>meta/recipes-core</filename>
- directory of the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- as an example from which to work.
- </para></listitem>
- <listitem><para>
- <emphasis>Decide if You Need to Bundle the initramfs Image
- Into the Kernel Image:</emphasis>
- If you want the initramfs image that is built to be
- bundled in with the kernel image, set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
- variable to "1" in your <filename>local.conf</filename>
- configuration file and set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE'><filename>INITRAMFS_IMAGE</filename></ulink>
- variable in the recipe that builds the kernel image.
- <note><title>Tip</title>
- It is recommended that you do bundle the initramfs
- image with the kernel image to avoid circular
- dependencies between the kernel recipe and the
- initramfs recipe should the initramfs image
- include kernel modules.
- </note>
- Setting the <filename>INITRAMFS_IMAGE_BUNDLE</filename>
- flag causes the initramfs image to be unpacked
- into the <filename>${B}/usr/</filename> directory.
- The unpacked initramfs image is then passed to the kernel's
- <filename>Makefile</filename> using the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-CONFIG_INITRAMFS_SOURCE'><filename>CONFIG_INITRAMFS_SOURCE</filename></ulink>
- variable, allowing the initramfs image to be built into
- the kernel normally.
- <note>
- If you choose to not bundle the initramfs image with
- the kernel image, you are essentially using an
- <ulink url='https://en.wikipedia.org/wiki/Initrd'>Initial RAM Disk (initrd)</ulink>.
- Creating an initrd is handled primarily through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRD_IMAGE'><filename>INITRD_IMAGE</filename></ulink>,
- <filename>INITRD_LIVE</filename>, and
- <filename>INITRD_IMAGE_LIVE</filename> variables.
- For more information, see the
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/image-live.bbclass'><filename>image-live.bbclass</filename></ulink>
- file.
- </note>
- </para></listitem>
-<!--
-Some notes from Cal:
-
- A non-bundled initramfs is essentially an initrd, which I am discovering
- to be rather confusingly supported in OE at the moment.
-
- Its primarily handled through INITRD_IMAGE(_LIVE/_VM) and INITRD(_LIVE/_VM)
- variables. INITRD_IMAGE* is the primary image target, which gets added to
- INITRD*, which is a list of cpio filesystems. You can add more cpio
- filesystems to the INITRD variable to add more to the initrd. For
- instance, meta-intel adds intel-microcode via the following:
-
- INITRD_LIVE_prepend = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', '${DEPLOY_DIR_IMAGE}/microcode.cpio ', '', d)}"
-
- If 'intel-ucode' is in MACHINE_FEATURES, this resolves to:
-
- INITRD_LIVE_prepend = "${DEPLOY_DIR_IMAGE}/microcode.cpio "
-
- Unfortunately you need the full path, and its up to you to sort out
- dependencies as well. For instance, we have the following:
-
- MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "${@bb.utils.contains('MACHINE_FEATURES', 'intel-ucode', ' intel-microcode', '', d)}"
-
- which resolves to:
-
- MACHINE_ESSENTIAL_EXTRA_RDEPENDS_append = "intel-microcode"
-
- However, the above is only true with the "live" IMAGE_FSTYPE. Wic is
- another beast entirely, with current wic kickstart files not supporting
- initrds, and only partial support in the source plugins. That being said,
- I know the generic bootfs work Ed is working on will help immensely in this
- aspect. He or Saul can provide more details here.
-
- Anyhow, its rather fractured and confusing and could probably use a
- rework honestly. I don't know how feasible it is to document all the
- details and corner cases of this area.
--->
- <listitem><para>
- <emphasis>Optionally Add Items to the initramfs Image
- Through the initramfs Image Recipe:</emphasis>
- If you add items to the initramfs image by way of its
- recipe, you should use
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></ulink>
- rather than
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>.
- <filename>PACKAGE_INSTALL</filename> gives more direct
- control of what is added to the image as compared to
- the defaults you might not necessarily want that are
- set by the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-image'><filename>image</filename></ulink>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-core-image'><filename>core-image</filename></ulink>
- classes.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the Kernel Image and the initramfs
- Image:</emphasis>
- Build your kernel image using BitBake.
- Because the initramfs image recipe is a dependency of the
- kernel image, the initramfs image is built as well and
- bundled with the kernel image if you used the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-INITRAMFS_IMAGE_BUNDLE'><filename>INITRAMFS_IMAGE_BUNDLE</filename></ulink>
- variable described earlier.
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
<section id='flashing-images-using-bmaptool'>
<title>Flashing Images Using <filename>bmaptool</filename></title>
<para>
- An easy way to flash an image to a bootable device is to use
- <filename>bmaptool</filename>, which is integrated into the
- OpenEmbedded build system.
+ A fast and easy way to flash an image to a bootable device
+ is to use Bmaptool, which is integrated into the OpenEmbedded
+ build system.
+ Bmaptool is a generic tool that creates a file's block map (bmap)
+ and then uses that map to copy the file.
+ As compared to traditional tools such as dd or cp, Bmaptool
+ can copy (or flash) large files like raw system image files
+ much faster.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ If you are using Ubuntu or Debian distributions, you
+ can install the <filename>bmap-tools</filename> package
+ using the following command and then use the tool
+ without specifying <filename>PATH</filename> even from
+ the root account:
+ <literallayout class='monospaced'>
+ $ sudo apt-get install bmap-tools
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ If you are unable to install the
+ <filename>bmap-tools</filename> package, you will
+ need to build Bmaptool before using it.
+ Use the following command:
+ <literallayout class='monospaced'>
+ $ bitbake bmap-tools-native
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </note>
</para>
<para>
Following, is an example that shows how to flash a Wic image.
- <note>
- You can use <filename>bmaptool</filename> to flash any
- type of image.
- </note>
- Use these steps to flash an image using
- <filename>bmaptool</filename>:
- <note>
- Unless you are able to install the
- <filename>bmap-tools</filename> package as mentioned in the note
- in the second bullet of step 3 further down, you will need to build
- <filename>bmaptool</filename> before using it.
- Build the tool using the following command:
- <literallayout class='monospaced'>
- $ bitbake bmap-tools-native
- </literallayout>
- </note>
+ Realize that while this example uses a Wic image, you can use
+ Bmaptool to flash any type of image.
+ Use these steps to flash an image using Bmaptool:
<orderedlist>
<listitem><para>
- <emphasis>Update the <filename>local.conf</filename> File:</emphasis>
- Add the following to your <filename>local.conf</filename>
- file:
+ <emphasis>Update your <filename>local.conf</filename> File:</emphasis>
+ You need to have the following set in your
+ <filename>local.conf</filename> file before building
+ your image:
<literallayout class='monospaced'>
IMAGE_FSTYPES += "wic wic.bmap"
</literallayout>
</para></listitem>
<listitem><para>
<emphasis>Get Your Image:</emphasis>
- Either have your image ready (pre-built) or take the step
- build the image:
+ Either have your image ready (pre-built with the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></ulink>
+ setting previously mentioned) or take the step to build
+ the image:
<literallayout class='monospaced'>
$ bitbake <replaceable>image</replaceable>
</literallayout>
</para></listitem>
<listitem><para>
<emphasis>Flash the Device:</emphasis>
- Flash the device with the image by using
- <filename>bmaptool</filename> depending on your particular
- setup:
+ Flash the device with the image by using Bmaptool
+ depending on your particular setup.
+ The following commands assume the image resides in the
+ Build Directory's <filename>deploy/images/</filename>
+ area:
<itemizedlist>
<listitem><para>
- If you have write access to the media,
- use this command form:
+ If you have write access to the media, use this
+ command form:
<literallayout class='monospaced'>
- $ oe-run-native bmap-tools-native bmaptool copy ./tmp/deploy/images/qemux86-64-core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
+ $ oe-run-native bmap-tools-native bmaptool copy <replaceable>build-directory</replaceable>/tmp/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.wic /dev/sd<replaceable>X</replaceable>
</literallayout>
</para></listitem>
<listitem><para>
- If you do not have write access to
- the media, use the following
- commands:
+ If you do not have write access to the media, set
+ your permissions first and then use the same
+ command form:
<literallayout class='monospaced'>
$ sudo chmod 666 /dev/sd<replaceable>X</replaceable>
- $ oe-run-native bmap-tools-native bmaptool copy ./tmp/deploy/images/qemux86-64-core-image-minimal-<replaceable>machine</replaceable>.wic /dev/sd<replaceable>X</replaceable>
+ $ oe-run-native bmap-tools-native bmaptool copy <replaceable>build-directory</replaceable>/tmp/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.wic /dev/sd<replaceable>X</replaceable>
</literallayout>
- <note>
- If you are using Ubuntu or Debian distributions,
- you can install the
- <filename>bmap-tools</filename> package using
- the following command and then use the tool
- without specifying
- <filename>PATH</filename> even from the
- root account:
- <literallayout class='monospaced'>
- $ sudo apt-get install bmap-tools
- </literallayout>
- </note>
</para></listitem>
</itemizedlist>
</para></listitem>
@@ -5852,7 +8199,7 @@
by Bruce Schneier
</para></listitem>
<listitem><para><emphasis>
- "<ulink url='http://internetcensus2012.bitbucket.org/paper.html'>Internet Census 2012</ulink>"</emphasis>
+ "<ulink url='http://census2012.sourceforge.net/paper.html'>Internet Census 2012</ulink>"</emphasis>
by Carna Botnet</para></listitem>
<listitem><para><emphasis>
"<ulink url='http://elinux.org/images/6/6f/Security-issues.pdf'>Security Issues for Embedded Devices</ulink>"</emphasis>
@@ -6060,7 +8407,7 @@
more secure.
You can find these tools in the
<filename>meta-security</filename> layer of the
- <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Yocto Project Source Repositories</ulink>.
+ <ulink url='&YOCTO_GIT_URL;'>Yocto Project Source Repositories</ulink>.
</para>
</section>
</section>
@@ -6308,616 +8655,22 @@
</para>
</section>
- <section id='building-a-tiny-system'>
- <title>Building a Tiny System</title>
+ <section id='dev-saving-memory-during-a-build'>
+ <title>Conserving Disk Space During Builds</title>
<para>
- Very small distributions have some significant advantages such
- as requiring less on-die or in-package memory (cheaper), better
- performance through efficient cache usage, lower power requirements
- due to less memory, faster boot times, and reduced development
- overhead.
- Some real-world examples where a very small distribution gives
- you distinct advantages are digital cameras, medical devices,
- and small headless systems.
- </para>
-
- <para>
- This section presents information that shows you how you can
- trim your distribution to even smaller sizes than the
- <filename>poky-tiny</filename> distribution, which is around
- 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
- </para>
-
- <section id='tiny-system-overview'>
- <title>Overview</title>
-
- <para>
- The following list presents the overall steps you need to
- consider and perform to create distributions with smaller
- root filesystems, achieve faster boot times, maintain your critical
- functionality, and avoid initial RAM disks:
- <itemizedlist>
- <listitem><para>
- <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
- </para></listitem>
- <listitem><para>
- <link linkend='iterate-on-the-process'>Iterate on the process.</link>
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='goals-and-guiding-principles'>
- <title>Goals and Guiding Principles</title>
-
- <para>
- Before you can reach your destination, you need to know
- where you are going.
- Here is an example list that you can use as a guide when
- creating very small distributions:
- <itemizedlist>
- <listitem><para>Determine how much space you need
- (e.g. a kernel that is 1 Mbyte or less and
- a root filesystem that is 3 Mbytes or less).
- </para></listitem>
- <listitem><para>Find the areas that are currently
- taking 90% of the space and concentrate on reducing
- those areas.
- </para></listitem>
- <listitem><para>Do not create any difficult "hacks"
- to achieve your goals.</para></listitem>
- <listitem><para>Leverage the device-specific
- options.</para></listitem>
- <listitem><para>Work in a separate layer so that you
- keep changes isolated.
- For information on how to create layers, see
- the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='understand-what-gives-your-image-size'>
- <title>Understand What Contributes to Your Image Size</title>
-
- <para>
- It is easiest to have something to start with when creating
- your own distribution.
- You can use the Yocto Project out-of-the-box to create the
- <filename>poky-tiny</filename> distribution.
- Ultimately, you will want to make changes in your own
- distribution that are likely modeled after
- <filename>poky-tiny</filename>.
- <note>
- To use <filename>poky-tiny</filename> in your build,
- set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
- variable in your
- <filename>local.conf</filename> file to "poky-tiny"
- as described in the
- "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
- section.
- </note>
- </para>
-
- <para>
- Understanding some memory concepts will help you reduce the
- system size.
- Memory consists of static, dynamic, and temporary memory.
- Static memory is the TEXT (code), DATA (initialized data
- in the code), and BSS (uninitialized data) sections.
- Dynamic memory represents memory that is allocated at runtime:
- stacks, hash tables, and so forth.
- Temporary memory is recovered after the boot process.
- This memory consists of memory used for decompressing
- the kernel and for the <filename>__init__</filename>
- functions.
- </para>
-
- <para>
- To help you see where you currently are with kernel and root
- filesystem sizes, you can use two tools found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in
- the <filename>scripts/tiny/</filename> directory:
- <itemizedlist>
- <listitem><para><filename>ksize.py</filename>: Reports
- component sizes for the kernel build objects.
- </para></listitem>
- <listitem><para><filename>dirsize.py</filename>: Reports
- component sizes for the root filesystem.</para></listitem>
- </itemizedlist>
- This next tool and command help you organize configuration
- fragments and view file dependencies in a human-readable form:
- <itemizedlist>
- <listitem><para><filename>merge_config.sh</filename>:
- Helps you manage configuration files and fragments
- within the kernel.
- With this tool, you can merge individual configuration
- fragments together.
- The tool allows you to make overrides and warns you
- of any missing configuration options.
- The tool is ideal for allowing you to iterate on
- configurations, create minimal configurations, and
- create configuration files for different machines
- without having to duplicate your process.</para>
- <para>The <filename>merge_config.sh</filename> script is
- part of the Linux Yocto kernel Git repositories
- (i.e. <filename>linux-yocto-3.14</filename>,
- <filename>linux-yocto-3.10</filename>,
- <filename>linux-yocto-3.8</filename>, and so forth)
- in the
- <filename>scripts/kconfig</filename> directory.</para>
- <para>For more information on configuration fragments,
- see the
- "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
- section in the Yocto Project Linux Kernel Development
- Manual.
- </para></listitem>
- <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>:
- Using the BitBake command with these options brings up
- a Dependency Explorer from which you can view file
- dependencies.
- Understanding these dependencies allows you to make
- informed decisions when cutting out various pieces of the
- kernel and root filesystem.</para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='trim-the-root-filesystem'>
- <title>Trim the Root Filesystem</title>
-
- <para>
- The root filesystem is made up of packages for booting,
- libraries, and applications.
- To change things, you can configure how the packaging happens,
- which changes the way you build them.
- You can also modify the filesystem itself or select a different
- filesystem.
- </para>
-
- <para>
- First, find out what is hogging your root filesystem by running the
- <filename>dirsize.py</filename> script from your root directory:
- <literallayout class='monospaced'>
- $ cd <replaceable>root-directory-of-image</replaceable>
- $ dirsize.py 100000 > dirsize-100k.log
- $ cat dirsize-100k.log
- </literallayout>
- You can apply a filter to the script to ignore files under
- a certain size.
- The previous example filters out any files below 100 Kbytes.
- The sizes reported by the tool are uncompressed, and thus
- will be smaller by a relatively constant factor in a
- compressed root filesystem.
- When you examine your log file, you can focus on areas of the
- root filesystem that take up large amounts of memory.
- </para>
-
- <para>
- You need to be sure that what you eliminate does not cripple
- the functionality you need.
- One way to see how packages relate to each other is by using
- the Dependency Explorer UI with the BitBake command:
- <literallayout class='monospaced'>
- $ cd <replaceable>image-directory</replaceable>
- $ bitbake -u taskexp -g <replaceable>image</replaceable>
- </literallayout>
- Use the interface to select potential packages you wish to
- eliminate and see their dependency relationships.
- </para>
-
- <para>
- When deciding how to reduce the size, get rid of packages that
- result in minimal impact on the feature set.
- For example, you might not need a VGA display.
- Or, you might be able to get by with <filename>devtmpfs</filename>
- and <filename>mdev</filename> instead of
- <filename>udev</filename>.
- </para>
-
- <para>
- Use your <filename>local.conf</filename> file to make changes.
- For example, to eliminate <filename>udev</filename> and
- <filename>glib</filename>, set the following in the
- local configuration file:
- <literallayout class='monospaced'>
- VIRTUAL-RUNTIME_dev_manager = ""
- </literallayout>
- </para>
-
- <para>
- Finally, you should consider exactly the type of root
- filesystem you need to meet your needs while also reducing
- its size.
- For example, consider <filename>cramfs</filename>,
- <filename>squashfs</filename>, <filename>ubifs</filename>,
- <filename>ext2</filename>, or an <filename>initramfs</filename>
- using <filename>initramfs</filename>.
- Be aware that <filename>ext3</filename> requires a 1 Mbyte
- journal.
- If you are okay with running read-only, you do not need this
- journal.
- </para>
-
- <note>
- After each round of elimination, you need to rebuild your
- system and then use the tools to see the effects of your
- reductions.
- </note>
-
-
- </section>
-
- <section id='trim-the-kernel'>
- <title>Trim the Kernel</title>
-
- <para>
- The kernel is built by including policies for hardware-independent
- aspects.
- What subsystems do you enable?
- For what architecture are you building?
- Which drivers do you build by default?
- <note>You can modify the kernel source if you want to help
- with boot time.
- </note>
- </para>
-
- <para>
- Run the <filename>ksize.py</filename> script from the top-level
- Linux build directory to get an idea of what is making up
- the kernel:
- <literallayout class='monospaced'>
- $ cd <replaceable>top-level-linux-build-directory</replaceable>
- $ ksize.py > ksize.log
- $ cat ksize.log
- </literallayout>
- When you examine the log, you will see how much space is
- taken up with the built-in <filename>.o</filename> files for
- drivers, networking, core kernel files, filesystem, sound,
- and so forth.
- The sizes reported by the tool are uncompressed, and thus
- will be smaller by a relatively constant factor in a compressed
- kernel image.
- Look to reduce the areas that are large and taking up around
- the "90% rule."
- </para>
-
- <para>
- To examine, or drill down, into any particular area, use the
- <filename>-d</filename> option with the script:
- <literallayout class='monospaced'>
- $ ksize.py -d > ksize.log
- </literallayout>
- Using this option breaks out the individual file information
- for each area of the kernel (e.g. drivers, networking, and
- so forth).
- </para>
-
- <para>
- Use your log file to see what you can eliminate from the kernel
- based on features you can let go.
- For example, if you are not going to need sound, you do not
- need any drivers that support sound.
- </para>
-
- <para>
- After figuring out what to eliminate, you need to reconfigure
- the kernel to reflect those changes during the next build.
- You could run <filename>menuconfig</filename> and make all your
- changes at once.
- However, that makes it difficult to see the effects of your
- individual eliminations and also makes it difficult to replicate
- the changes for perhaps another target device.
- A better method is to start with no configurations using
- <filename>allnoconfig</filename>, create configuration
- fragments for individual changes, and then manage the
- fragments into a single configuration file using
- <filename>merge_config.sh</filename>.
- The tool makes it easy for you to iterate using the
- configuration change and build cycle.
- </para>
-
- <para>
- Each time you make configuration changes, you need to rebuild
- the kernel and check to see what impact your changes had on
- the overall size.
- </para>
- </section>
-
- <section id='remove-package-management-requirements'>
- <title>Remove Package Management Requirements</title>
-
- <para>
- Packaging requirements add size to the image.
- One way to reduce the size of the image is to remove all the
- packaging requirements from the image.
- This reduction includes both removing the package manager
- and its unique dependencies as well as removing the package
- management data itself.
- </para>
-
- <para>
- To eliminate all the packaging requirements for an image,
- be sure that "package-management" is not part of your
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
- statement for the image.
- When you remove this feature, you are removing the package
- manager as well as its dependencies from the root filesystem.
- </para>
- </section>
-
- <section id='look-for-other-ways-to-minimize-size'>
- <title>Look for Other Ways to Minimize Size</title>
-
- <para>
- Depending on your particular circumstances, other areas that you
- can trim likely exist.
- The key to finding these areas is through tools and methods
- described here combined with experimentation and iteration.
- Here are a couple of areas to experiment with:
- <itemizedlist>
- <listitem><para><filename>glibc</filename>:
- In general, follow this process:
- <orderedlist>
- <listitem><para>Remove <filename>glibc</filename>
- features from
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
- that you think you do not need.</para></listitem>
- <listitem><para>Build your distribution.
- </para></listitem>
- <listitem><para>If the build fails due to missing
- symbols in a package, determine if you can
- reconfigure the package to not need those
- features.
- For example, change the configuration to not
- support wide character support as is done for
- <filename>ncurses</filename>.
- Or, if support for those characters is needed,
- determine what <filename>glibc</filename>
- features provide the support and restore the
- configuration.
- </para></listitem>
- <listitem><para>Rebuild and repeat the process.
- </para></listitem>
- </orderedlist></para></listitem>
- <listitem><para><filename>busybox</filename>:
- For BusyBox, use a process similar as described for
- <filename>glibc</filename>.
- A difference is you will need to boot the resulting
- system to see if you are able to do everything you
- expect from the running system.
- You need to be sure to integrate configuration fragments
- into Busybox because BusyBox handles its own core
- features and then allows you to add configuration
- fragments on top.
- </para></listitem>
- </itemizedlist>
- </para>
- </section>
-
- <section id='iterate-on-the-process'>
- <title>Iterate on the Process</title>
-
- <para>
- If you have not reached your goals on system size, you need
- to iterate on the process.
- The process is the same.
- Use the tools and see just what is taking up 90% of the root
- filesystem and the kernel.
- Decide what you can eliminate without limiting your device
- beyond what you need.
- </para>
-
- <para>
- Depending on your system, a good place to look might be
- Busybox, which provides a stripped down
- version of Unix tools in a single, executable file.
- You might be able to drop virtual terminal services or perhaps
- ipv6.
- </para>
- </section>
- </section>
-
- <section id='building-images-for-more-than-one-machine'>
- <title>Building Images for More than One Machine</title>
-
- <para>
- A common scenario developers face is creating images for several
- different machines that use the same software environment.
- In this situation, it is tempting to set the
- tunings and optimization flags for each build specifically for
- the targeted hardware (i.e. "maxing out" the tunings).
- Doing so can considerably add to build times and package feed
- maintenance collectively for the machines.
- For example, selecting tunes that are extremely specific to a
- CPU core used in a system might enable some micro optimizations
- in GCC for that particular system but would otherwise not gain
- you much of a performance difference across the other systems
- as compared to using a more general tuning across all the builds
- (e.g. setting
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DEFAULTTUNE'><filename>DEFAULTTUNE</filename></ulink>
- specifically for each machine's build).
- Rather than "max out" each build's tunings, you can take steps that
- cause the OpenEmbedded build system to reuse software across the
- various machines where it makes sense.
- </para>
- <para>
- If build speed and package feed maintenance are considerations,
- you should consider the points in this section that can help you
- optimize your tunings to best consider build times and package
- feed maintenance.
- <itemizedlist>
- <listitem><para><emphasis>Share the Build Directory:</emphasis>
- If at all possible, share the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
- across builds.
- The Yocto Project supports switching between different
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
- values in the same <filename>TMPDIR</filename>.
- This practice is well supported and regularly used by
- developers when building for multiple machines.
- When you use the same <filename>TMPDIR</filename> for
- multiple machine builds, the OpenEmbedded build system can
- reuse the existing native and often cross-recipes for
- multiple machines.
- Thus, build time decreases.
- <note>
- If
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
- settings change or fundamental configuration settings
- such as the filesystem layout, you need to work with
- a clean <filename>TMPDIR</filename>.
- Sharing <filename>TMPDIR</filename> under these
- circumstances might work but since it is not
- guaranteed, you should use a clean
- <filename>TMPDIR</filename>.
- </note>
- </para></listitem>
- <listitem><para><emphasis>Enable the Appropriate Package Architecture:</emphasis>
- By default, the OpenEmbedded build system enables three
- levels of package architectures: "all", "tune" or "package",
- and "machine".
- Any given recipe usually selects one of these package
- architectures (types) for its output.
- Depending for what a given recipe creates packages, making
- sure you enable the appropriate package architecture can
- directly impact the build time.</para>
- <para>A recipe that just generates scripts can enable
- "all" architecture because there are no binaries to build.
- To specifically enable "all" architecture, be sure your
- recipe inherits the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-allarch'><filename>allarch</filename></ulink>
- class.
- This class is useful for "all" architectures because it
- configures many variables so packages can be used across
- multiple architectures.</para>
- <para>If your recipe needs to generate packages that are
- machine-specific or when one of the build or runtime
- dependencies is already machine-architecture dependent,
- which makes your recipe also machine-architecture dependent,
- make sure your recipe enables the "machine" package
- architecture through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ARCH'><filename>MACHINE_ARCH</filename></ulink>
- variable:
- <literallayout class='monospaced'>
- PACKAGE_ARCH = "${MACHINE_ARCH}"
- </literallayout>
- When you do not specifically enable a package
- architecture through the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
- The OpenEmbedded build system defaults to the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></ulink>
- setting:
- <literallayout class='monospaced'>
- PACKAGE_ARCH = "${TUNE_PKGARCH}"
- </literallayout>
- </para></listitem>
- <listitem><para><emphasis>Choose a Generic Tuning File if Possible:</emphasis>
- Some tunes are more generic and can run on multiple targets
- (e.g. an <filename>armv5</filename> set of packages could
- run on <filename>armv6</filename> and
- <filename>armv7</filename> processors in most cases).
- Similarly, <filename>i486</filename> binaries could work
- on <filename>i586</filename> and higher processors.
- You should realize, however, that advances on newer
- processor versions would not be used.</para>
- <para>If you select the same tune for several different
- machines, the OpenEmbedded build system reuses software
- previously built, thus speeding up the overall build time.
- Realize that even though a new sysroot for each machine is
- generated, the software is not recompiled and only one
- package feed exists.
- </para></listitem>
- <listitem><para><emphasis>Manage Granular Level Packaging:</emphasis>
- Sometimes cases exist where injecting another level
- of package architecture beyond the three higher levels
- noted earlier can be useful.
- For example, consider the <filename>emgd</filename>
- graphics stack in the
- <filename>meta-intel</filename> layer.
- In this layer, a subset of software exists that is
- compiled against something different from the rest of the
- generic packages.
- You can examine the key code in the
- <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi'>Source Repositories</ulink>
- "daisy" branch in
- <filename>classes/emgd-gl.bbclass</filename>.
- For a specific set of packages, the code redefines
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>.
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXTRA_ARCHS'><filename>PACKAGE_EXTRA_ARCHS</filename></ulink>
- is then appended with this extra tune name in
- <filename>meta-intel-emgd.inc</filename>.
- The result is that when searching for packages, the
- build system uses a four-level search and the packages
- in this new level are preferred as compared to the standard
- tune.
- The overall result is that the build system reuses most
- software from the common tune except for specific cases
- as needed.
- </para></listitem>
- <listitem><para><emphasis>Use Tools to Debug Issues:</emphasis>
- Sometimes you can run into situations where software is
- being rebuilt when you think it should not be.
- For example, the OpenEmbedded build system might not be
- using shared state between machines when you think it
- should be.
- These types of situations are usually due to references
- to machine-specific variables such as
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'><filename>SERIAL_CONSOLE</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-XSERVER'><filename>XSERVER</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></ulink>,
- and so forth in code that is supposed to only be
- tune-specific or when the recipe depends
- (<ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-RSUGGESTS'><filename>RSUGGESTS</filename></ulink>,
- and so forth) on some other recipe that already has
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>
- defined as "${MACHINE_ARCH}".
- <note>
- Patches to fix any issues identified are most welcome
- as these issues occasionally do occur.
- </note></para>
- <para>For such cases, you can use some tools to help you
- sort out the situation:
- <itemizedlist>
- <listitem><para><emphasis><filename>sstate-diff-machines.sh</filename>:</emphasis>
- You can find this tool in the
- <filename>scripts</filename> directory of the
- Source Repositories.
- See the comments in the script for information on
- how to use the tool.
- </para></listitem>
- <listitem><para><emphasis>BitBake's "-S printdiff" Option:</emphasis>
- Using this option causes BitBake to try to
- establish the closest signature match it can
- (e.g. in the shared state cache) and then run
- <filename>bitbake-diffsigs</filename> over the
- matches to determine the stamps and delta where
- these two stamp trees diverge.
- </para></listitem>
- </itemizedlist>
- </para></listitem>
- </itemizedlist>
+ To help conserve disk space during builds, you can add the
+ following statement to your project's
+ <filename>local.conf</filename> configuration file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
+ INHERIT += "rm_work"
+ </literallayout>
+ Adding this statement deletes the work directory used for building
+ a recipe once the recipe is built.
+ For more information on "rm_work", see the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+ class in the Yocto Project Reference Manual.
</para>
</section>
@@ -7121,7 +8874,7 @@
<para>
Because the OpenEmbedded build system uses
- "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
+ "<ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>signatures</ulink>",
which are unique to a given build, the build system
knows when to rebuild packages.
All the inputs into a given task are represented by a
@@ -7206,8 +8959,8 @@
BUILDHISTORY_COMMIT = "1"
</literallayout>
For information on build history, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
- section in the Yocto Project Reference Manual.
+ "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
+ section.
</para>
<note>
@@ -7225,8 +8978,9 @@
<para>
For more information on shared state, see the
- "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
- section in the Yocto Project Reference Manual.
+ "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>Shared State Cache</ulink>"
+ section in the Yocto Project Overview and Concepts
+ Manual.
</para>
</note>
</section>
@@ -7470,7 +9224,7 @@
<filename>connman.inc</filename> file in the
<filename>meta/recipes-connectivity/connman/</filename>
directory of the <filename>poky</filename>
- <ulink url='&YOCTO_DOCS_REF_URL;#yocto-project-repositories'>source repository</ulink>.
+ <ulink url='&YOCTO_DOCS_OM_URL;#yocto-project-repositories'>source repository</ulink>.
You can also find examples in
<filename>meta/classes/kernel.bbclass</filename>.
</para>
@@ -7599,11 +9353,13 @@
During a build, BitBake always transforms a recipe into one or
more packages.
For example, BitBake takes the <filename>bash</filename> recipe
- and currently produces the <filename>bash-dbg</filename>,
- <filename>bash-staticdev</filename>,
- <filename>bash-dev</filename>, <filename>bash-doc</filename>,
- <filename>bash-locale</filename>, and
- <filename>bash</filename> packages.
+ and produces a number of packages (e.g.
+ <filename>bash</filename>, <filename>bash-bashbug</filename>,
+ <filename>bash-completion</filename>,
+ <filename>bash-completion-dbg</filename>,
+ <filename>bash-completion-dev</filename>,
+ <filename>bash-completion-extra</filename>,
+ <filename>bash-dbg</filename>, and so forth).
Not all generated packages are included in an image.
</para>
@@ -7647,7 +9403,7 @@
<para>
In order to use runtime package management, you
- need a host/server machine that serves up the pre-compiled
+ need a host or server machine that serves up the pre-compiled
packages plus the required metadata.
You also need package manipulation tools on the target.
The build machine is a likely candidate to act as the server.
@@ -7655,6 +9411,10 @@
package server.
The build machine could push its artifacts to another machine
that acts as the server (e.g. Internet-facing).
+ In fact, doing so is advantageous for a production
+ environment as getting the packages away from the
+ development system's build directory prevents accidental
+ overwrites.
</para>
<para>
@@ -7664,11 +9424,11 @@
out into a couple of different package groupings based on
criteria such as the target's CPU architecture, the target
board, or the C library used on the target.
- For example, a build targeting the <filename>qemuarm</filename>
+ For example, a build targeting the <filename>qemux86</filename>
device produces the following three package databases:
- <filename>all</filename>, <filename>armv5te</filename>, and
- <filename>qemuarm</filename>.
- If you wanted your <filename>qemuarm</filename> device to be
+ <filename>noarch</filename>, <filename>i586</filename>, and
+ <filename>qemux86</filename>.
+ If you wanted your <filename>qemux86</filename> device to be
aware of all the packages that were available to it,
you would need to point it to each of these databases
individually.
@@ -7714,10 +9474,10 @@
PACKAGE_CLASSES ?= “package_<replaceable>packageformat</replaceable>”
</literallayout>
where <replaceable>packageformat</replaceable>
- can be "ipk", "rpm", and "deb", which are the
+ can be "ipk", "rpm", "deb", or "tar" which are the
supported package formats.
<note>
- Because the Yocto Project supports three
+ Because the Yocto Project supports four
different package formats, you can set the
variable with more than one argument.
However, the OpenEmbedded build system only
@@ -7736,12 +9496,12 @@
"package-management" in the
<ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
variable.
- Including "package-management" in this
- configuration variable ensures that when the image
- is assembled for your target, the image includes
- the currently-known package databases as well as
- the target-specific tools required for runtime
- package management to be performed on the target.
+ Including "package-management" in this configuration
+ variable ensures that when the image is assembled for your
+ target, the image includes the currently-known package
+ databases as well as the target-specific tools required
+ for runtime package management to be performed on the
+ target.
However, this is not strictly necessary.
You could start your image off without any databases
but only include the required on-target package
@@ -7755,21 +9515,26 @@
<para>
Whenever you perform any sort of build step that can
- potentially generate a package or modify an existing
+ potentially generate a package or modify existing
package, it is always a good idea to re-generate the
- package index with:
+ package index after the build by using the following
+ command:
<literallayout class='monospaced'>
$ bitbake package-index
</literallayout>
- Realize that it is not sufficient to simply do the
- following:
+ It might be tempting to build the package and the
+ package index at the same time with a command such as
+ the following:
<literallayout class='monospaced'>
$ bitbake <replaceable>some-package</replaceable> package-index
</literallayout>
- The reason for this restriction is because BitBake does not
- properly schedule the <filename>package-index</filename>
- target fully after any other target has completed.
- Thus, be sure to run the package update step separately.
+ Do not do this as BitBake does not schedule the package
+ index for after the completion of the package you are
+ building.
+ Consequently, you cannot be sure of the package index
+ including information for the package you just built.
+ Thus, be sure to run the package update step separately
+ after building any packages.
</para>
<para>
@@ -7794,8 +9559,8 @@
For example, if
<filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink><filename>}</filename>
is <filename>tmp</filename> and your selected package type
- is IPK, then your IPK packages are available in
- <filename>tmp/deploy/ipk</filename>.
+ is RPM, then your RPM packages are available in
+ <filename>tmp/deploy/rpm</filename>.
</para>
</section>
@@ -7850,17 +9615,39 @@
<title>Using RPM</title>
<para>
- The <filename>dnf</filename> application performs
- runtime package management of RPM packages.
- You must perform an initial setup for
- <filename>dnf</filename> on the target machine
- if the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>,
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>,
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink>
- variables have not been set or the target image was
- built before the variables were set.
+ The
+ <ulink url='https://en.wikipedia.org/wiki/DNF_(software)'>Dandified Packaging Tool</ulink>
+ (DNF) performs runtime package management of RPM
+ packages.
+ In order to use DNF for runtime package management,
+ you must perform an initial setup on the target
+ machine for cases where the
+ <filename>PACKAGE_FEED_*</filename> variables were not
+ set as part of the image that is running on the
+ target.
+ This means if you built your image and did not not use
+ these variables as part of the build and your image is
+ now running on the target, you need to perform the
+ steps in this section if you want to use runtime
+ package management.
+ <note>
+ For information on the
+ <filename>PACKAGE_FEED_*</filename> variables, see
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_ARCHS'><filename>PACKAGE_FEED_ARCHS</filename></ulink>,
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_BASE_PATHS'><filename>PACKAGE_FEED_BASE_PATHS</filename></ulink>,
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_FEED_URIS'><filename>PACKAGE_FEED_URIS</filename></ulink>
+ in the Yocto Project Reference Manual variables
+ glossary.
+ </note>
+ </para>
+
+ <para>
+ On the target, you must inform DNF that package
+ databases are available.
+ You do this by creating a file named
+ <filename>/etc/yum.repos.d/oe-packages.repo</filename>
+ and defining the <filename>oe-packages</filename>.
</para>
<para>
@@ -7869,21 +9656,65 @@
<filename>all</filename>, <filename>i586</filename>,
and <filename>qemux86</filename> from a server named
<filename>my.server</filename>.
- You must inform <filename>dnf</filename> of the
- availability of these databases by creating a
- <filename>/etc/yum.repos.d/oe-packages.repo</filename>
- file with the following content:
- <literallayout class='monospaced'>
+ The specifics for setting up the web server are up to
+ you.
+ The critical requirement is that the URIs in the
+ target repository configuration point to the
+ correct remote location for the feeds.
+ <note><title>Tip</title>
+ For development purposes, you can point the web
+ server to the build system's
+ <filename>deploy</filename> directory.
+ However, for production use, it is better to copy
+ the package directories to a location outside of
+ the build area and use that location.
+ Doing so avoids situations where the build system
+ overwrites or changes the
+ <filename>deploy</filename> directory.
+ </note>
+ </para>
+
+ <para>
+ When telling DNF where to look for the package
+ databases, you must declare individual locations
+ per architecture or a single location used for all
+ architectures.
+ You cannot do both:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Create an Explicit List of Architectures:</emphasis>
+ Define individual base URLs to identify where
+ each package database is located:
+ <literallayout class='monospaced'>
[oe-packages]
baseurl=http://my.server/rpm/i586 http://my.server/rpm/qemux86 http://my.server/rpm/all
- </literallayout>
- From the target machine, fetch the repository:
+ </literallayout>
+ This example informs DNF about individual
+ package databases for all three architectures.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Create a Single (Full) Package Index:</emphasis>
+ Define a single base URL that identifies where
+ a full package database is located:
+ <literallayout class='monospaced'>
+ [oe-packages]
+ baseurl=http://my.server/rpm
+ </literallayout>
+ This example informs DNF about a single package
+ database that contains all the package index
+ information for all supported architectures.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Once you have informed DNF where to find the package
+ databases, you need to fetch them:
<literallayout class='monospaced'>
# dnf makecache
</literallayout>
- After everything is set up, <filename>dnf</filename>
- is able to find, install, and upgrade packages from
- the specified repository.
+ DNF is now able to find, install, and upgrade packages
+ from the specified repository or repositories.
<note>
See the
<ulink url='http://dnf.readthedocs.io/en/latest/'>DNF documentation</ulink>
@@ -8294,8 +10125,8 @@
</section>
</section>
- <section id='working-with-source-files'>
- <title>Working with Source Files</title>
+ <section id='efficiently-fetching-source-files-during-a-build'>
+ <title>Efficiently Fetching Source Files During a Build</title>
<para>
The OpenEmbedded build system works with source files located
@@ -8309,16 +10140,16 @@
</para>
<para>
- This section presents information for working with source
- files that can lead to more efficient use of resources and
- time.
+ This section shows you how you can use mirrors to speed up
+ fetching source files and how you can pre-fetch files all of which
+ leads to more efficient use of resources and time.
</para>
<section id='setting-up-effective-mirrors'>
<title>Setting up Effective Mirrors</title>
<para>
- As mentioned, a good deal that goes into a Yocto Project
+ A good deal that goes into a Yocto Project
build is simply downloading all of the source tarballs.
Maybe you have been working with another build system
(OpenEmbedded or Angstrom) for which you have built up a
@@ -8381,7 +10212,7 @@
Use the following BitBake command form to fetch all the
necessary sources without starting the build:
<literallayout class='monospaced'>
- $ bitbake -c fetchall <replaceable>target</replaceable>
+ $ bitbake -c <replaceable>target</replaceable> runall="fetch"
</literallayout>
This variation of the BitBake command guarantees that you
have all the sources for that BitBake target should you
@@ -8391,81 +10222,6 @@
</section>
</section>
- <section id="building-software-from-an-external-source">
- <title>Building Software from an External Source</title>
-
- <para>
- By default, the OpenEmbedded build system uses the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
- when building source code.
- The build process involves fetching the source files, unpacking
- them, and then patching them if necessary before the build takes
- place.
- </para>
-
- <para>
- Situations exist where you might want to build software from source
- files that are external to and thus outside of the
- OpenEmbedded build system.
- For example, suppose you have a project that includes a new BSP with
- a heavily customized kernel.
- And, you want to minimize exposing the build system to the
- development team so that they can focus on their project and
- maintain everyone's workflow as much as possible.
- In this case, you want a kernel source directory on the development
- machine where the development occurs.
- You want the recipe's
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- variable to point to the external directory and use it as is, not
- copy it.
- </para>
-
- <para>
- To build from software that comes from an external source, all you
- need to do is inherit the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
- class and then set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
- variable to point to your external source code.
- Here are the statements to put in your
- <filename>local.conf</filename> file:
- <literallayout class='monospaced'>
- INHERIT += "externalsrc"
- EXTERNALSRC_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
- </literallayout>
- </para>
-
- <para>
- This next example shows how to accomplish the same thing by setting
- <filename>EXTERNALSRC</filename> in the recipe itself or in the
- recipe's append file:
- <literallayout class='monospaced'>
- EXTERNALSRC = "<replaceable>path</replaceable>"
- EXTERNALSRC_BUILD = "<replaceable>path</replaceable>"
- </literallayout>
- <note>
- In order for these settings to take effect, you must globally
- or locally inherit the
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc</filename></ulink>
- class.
- </note>
- </para>
-
- <para>
- By default, <filename>externalsrc.bbclass</filename> builds
- the source code in a directory separate from the external source
- directory as specified by
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
- If you need to have the source built in the same directory in
- which it resides, or some other nominated directory, you can set
- <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
- to point to that directory:
- <literallayout class='monospaced'>
- EXTERNALSRC_BUILD_pn-<replaceable>myrecipe</replaceable> = "<replaceable>path-to-your-source-tree</replaceable>"
- </literallayout>
- </para>
- </section>
-
<section id="selecting-an-initialization-manager">
<title>Selecting an Initialization Manager</title>
@@ -8863,6 +10619,566 @@
</section>
</section>
+
+
+
+ <section id='maintaining-build-output-quality'>
+ <title>Maintaining Build Output Quality</title>
+
+ <para>
+ Many factors can influence the quality of a build.
+ For example, if you upgrade a recipe to use a new version of an
+ upstream software package or you experiment with some new
+ configuration options, subtle changes can occur that you might
+ not detect until later.
+ Consider the case where your recipe is using a newer version of
+ an upstream package.
+ In this case, a new version of a piece of software might
+ introduce an optional dependency on another library, which is
+ auto-detected.
+ If that library has already been built when the software is
+ building, the software will link to the built library and that
+ library will be pulled into your image along with the new
+ software even if you did not want the library.
+ </para>
+
+ <para>
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-buildhistory'><filename>buildhistory</filename></ulink>
+ class exists to help you maintain the quality of your build
+ output.
+ You can use the class to highlight unexpected and possibly
+ unwanted changes in the build output.
+ When you enable build history, it records information about the
+ contents of each package and image and then commits that
+ information to a local Git repository where you can examine
+ the information.
+ </para>
+
+ <para>
+ The remainder of this section describes the following:
+ <itemizedlist>
+ <listitem><para>
+ How you can enable and disable build history
+ </para></listitem>
+ <listitem><para>
+ How to understand what the build history contains
+ </para></listitem>
+ <listitem><para>
+ How to limit the information used for build history
+ </para></listitem>
+ <listitem><para>
+ How to examine the build history from both a
+ command-line and web interface
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <section id='enabling-and-disabling-build-history'>
+ <title>Enabling and Disabling Build History</title>
+
+ <para>
+ Build history is disabled by default.
+ To enable it, add the following <filename>INHERIT</filename>
+ statement and set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></ulink>
+ variable to "1" at the end of your
+ <filename>conf/local.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
+ INHERIT += "buildhistory"
+ BUILDHISTORY_COMMIT = "1"
+ </literallayout>
+ Enabling build history as previously described causes the
+ OpenEmbedded build system to collect build output information
+ and commit it as a single commit to a local
+ <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>
+ repository.
+ <note>
+ Enabling build history increases your build times slightly,
+ particularly for images, and increases the amount of disk
+ space used during the build.
+ </note>
+ </para>
+
+ <para>
+ You can disable build history by removing the previous
+ statements from your <filename>conf/local.conf</filename>
+ file.
+ </para>
+ </section>
+
+ <section id='understanding-what-the-build-history-contains'>
+ <title>Understanding What the Build History Contains</title>
+
+ <para>
+ Build history information is kept in
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink><filename>}/buildhistory</filename>
+ in the Build Directory as defined by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_DIR'><filename>BUILDHISTORY_DIR</filename></ulink>
+ variable.
+ The following is an example abbreviated listing:
+ <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
+ </para>
+
+ <para>
+ At the top level, a <filename>metadata-revs</filename>
+ file exists that lists the revisions of the repositories for
+ the enabled layers when the build was produced.
+ The rest of the data splits into separate
+ <filename>packages</filename>, <filename>images</filename>
+ and <filename>sdk</filename> directories, the contents of
+ which are described as follows.
+ </para>
+
+ <section id='build-history-package-information'>
+ <title>Build History Package Information</title>
+
+ <para>
+ The history for each package contains a text file that has
+ name-value pairs with information about the package.
+ For example,
+ <filename>buildhistory/packages/i586-poky-linux/busybox/busybox/latest</filename>
+ contains the following:
+ <literallayout class='monospaced'>
+ PV = 1.22.1
+ PR = r32
+ RPROVIDES =
+ RDEPENDS = glibc (>= 2.20) update-alternatives-opkg
+ RRECOMMENDS = busybox-syslog busybox-udhcpc update-rc.d
+ PKGSIZE = 540168
+ FILES = /usr/bin/* /usr/sbin/* /usr/lib/busybox/* /usr/lib/lib*.so.* \
+ /etc /com /var /bin/* /sbin/* /lib/*.so.* /lib/udev/rules.d \
+ /usr/lib/udev/rules.d /usr/share/busybox /usr/lib/busybox/* \
+ /usr/share/pixmaps /usr/share/applications /usr/share/idl \
+ /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
+ FILELIST = /bin/busybox /bin/busybox.nosuid /bin/busybox.suid /bin/sh \
+ /etc/busybox.links.nosuid /etc/busybox.links.suid
+ </literallayout>
+ Most of these name-value pairs correspond to variables
+ used to produce the package.
+ The exceptions are <filename>FILELIST</filename>, which
+ is the actual list of files in the package, and
+ <filename>PKGSIZE</filename>, which is the total size of
+ files in the package in bytes.
+ </para>
+
+ <para>
+ A file also exists that corresponds to the recipe from
+ which the package came (e.g.
+ <filename>buildhistory/packages/i586-poky-linux/busybox/latest</filename>):
+ <literallayout class='monospaced'>
+ PV = 1.22.1
+ PR = r32
+ DEPENDS = initscripts kern-tools-native update-rc.d-native \
+ virtual/i586-poky-linux-compilerlibs virtual/i586-poky-linux-gcc \
+ virtual/libc virtual/update-alternatives
+ PACKAGES = busybox-ptest busybox-httpd busybox-udhcpd busybox-udhcpc \
+ busybox-syslog busybox-mdev busybox-hwclock busybox-dbg \
+ busybox-staticdev busybox-dev busybox-doc busybox-locale busybox
+ </literallayout>
+ </para>
+
+ <para>
+ Finally, for those recipes fetched from a version control
+ system (e.g., Git), a file exists that lists source
+ revisions that are specified in the recipe and lists
+ the actual revisions used during the build.
+ Listed and actual revisions might differ when
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+ is set to
+ ${<ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>}.
+ Here is an example assuming
+ <filename>buildhistory/packages/qemux86-poky-linux/linux-yocto/latest_srcrev</filename>):
+ <literallayout class='monospaced'>
+ # SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
+ SRCREV_machine = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
+ # SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
+ SRCREV_meta = "a227f20eff056e511d504b2e490f3774ab260d6f"
+ </literallayout>
+ You can use the
+ <filename>buildhistory-collect-srcrevs</filename>
+ command with the <filename>-a</filename> option to
+ collect the stored <filename>SRCREV</filename> values
+ from build history and report them in a format suitable for
+ use in global configuration (e.g.,
+ <filename>local.conf</filename> or a distro include file)
+ to override floating <filename>AUTOREV</filename> values
+ to a fixed set of revisions.
+ Here is some example output from this command:
+ <literallayout class='monospaced'>
+ $ buildhistory-collect-srcrevs -a
+ # i586-poky-linux
+ SRCREV_pn-glibc = "b8079dd0d360648e4e8de48656c5c38972621072"
+ SRCREV_pn-glibc-initial = "b8079dd0d360648e4e8de48656c5c38972621072"
+ SRCREV_pn-opkg-utils = "53274f087565fd45d8452c5367997ba6a682a37a"
+ SRCREV_pn-kmod = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
+ # x86_64-linux
+ SRCREV_pn-gtk-doc-stub-native = "1dea266593edb766d6d898c79451ef193eb17cfa"
+ SRCREV_pn-dtc-native = "65cc4d2748a2c2e6f27f1cf39e07a5dbabd80ebf"
+ SRCREV_pn-update-rc.d-native = "eca680ddf28d024954895f59a241a622dd575c11"
+ SRCREV_glibc_pn-cross-localedef-native = "b8079dd0d360648e4e8de48656c5c38972621072"
+ SRCREV_localedef_pn-cross-localedef-native = "c833367348d39dad7ba018990bfdaffaec8e9ed3"
+ SRCREV_pn-prelink-native = "faa069deec99bf61418d0bab831c83d7c1b797ca"
+ SRCREV_pn-opkg-utils-native = "53274f087565fd45d8452c5367997ba6a682a37a"
+ SRCREV_pn-kern-tools-native = "23345b8846fe4bd167efdf1bd8a1224b2ba9a5ff"
+ SRCREV_pn-kmod-native = "fd56638aed3fe147015bfa10ed4a5f7491303cb4"
+ # qemux86-poky-linux
+ SRCREV_machine_pn-linux-yocto = "38cd560d5022ed2dbd1ab0dca9642e47c98a0aa1"
+ SRCREV_meta_pn-linux-yocto = "a227f20eff056e511d504b2e490f3774ab260d6f"
+ # all-poky-linux
+ SRCREV_pn-update-rc.d = "eca680ddf28d024954895f59a241a622dd575c11"
+ </literallayout>
+ <note>
+ Here are some notes on using the
+ <filename>buildhistory-collect-srcrevs</filename>
+ command:
+ <itemizedlist>
+ <listitem><para>
+ By default, only values where the
+ <filename>SRCREV</filename> was not hardcoded
+ (usually when <filename>AUTOREV</filename>
+ is used) are reported.
+ Use the <filename>-a</filename> option to
+ see all <filename>SRCREV</filename> values.
+ </para></listitem>
+ <listitem><para>
+ The output statements might not have any effect
+ if overrides are applied elsewhere in the
+ build system configuration.
+ Use the <filename>-f</filename> option to add
+ the <filename>forcevariable</filename> override
+ to each output line if you need to work around
+ this restriction.
+ </para></listitem>
+ <listitem><para>
+ The script does apply special handling when
+ building for multiple machines.
+ However, the script does place a comment before
+ each set of values that specifies which
+ triplet to which they belong as previously
+ shown (e.g.,
+ <filename>i586-poky-linux</filename>).
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+ </section>
+
+ <section id='build-history-image-information'>
+ <title>Build History Image Information</title>
+
+ <para>
+ The files produced for each image are as follows:
+ <itemizedlist>
+ <listitem><para>
+ <filename>image-files:</filename>
+ A directory containing selected files from the root
+ filesystem.
+ The files are defined by
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_IMAGE_FILES'><filename>BUILDHISTORY_IMAGE_FILES</filename></ulink>.
+ </para></listitem>
+ <listitem><para>
+ <filename>build-id.txt:</filename>
+ Human-readable information about the build
+ configuration and metadata source revisions.
+ This file contains the full build header as printed
+ by BitBake.
+ </para></listitem>
+ <listitem><para>
+ <filename>*.dot:</filename>
+ Dependency graphs for the image that are
+ compatible with <filename>graphviz</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>files-in-image.txt:</filename>
+ A list of files in the image with permissions,
+ owner, group, size, and symlink information.
+ </para></listitem>
+ <listitem><para>
+ <filename>image-info.txt:</filename>
+ A text file containing name-value pairs with
+ information about the image.
+ See the following listing example for more
+ information.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-names.txt:</filename>
+ A list of installed packages by name only.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-sizes.txt:</filename>
+ A list of installed packages ordered by size.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-packages.txt:</filename>
+ A list of installed packages with full package
+ filenames.
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ Installed package information is able to be gathered
+ and produced even if package management is disabled
+ for the final image.
+ </note>
+ </para>
+
+ <para>
+ Here is an example of <filename>image-info.txt</filename>:
+ <literallayout class='monospaced'>
+ DISTRO = poky
+ DISTRO_VERSION = 1.7
+ USER_CLASSES = buildstats image-mklibs image-prelink
+ IMAGE_CLASSES = image_types
+ IMAGE_FEATURES = debug-tweaks
+ IMAGE_LINGUAS =
+ IMAGE_INSTALL = packagegroup-core-boot run-postinsts
+ BAD_RECOMMENDATIONS =
+ NO_RECOMMENDATIONS =
+ PACKAGE_EXCLUDE =
+ ROOTFS_POSTPROCESS_COMMAND = write_package_manifest; license_create_manifest; \
+ write_image_manifest ; buildhistory_list_installed_image ; \
+ buildhistory_get_image_installed ; ssh_allow_empty_password; \
+ postinst_enable_logging; rootfs_update_timestamp ; ssh_disable_dns_lookup ;
+ IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
+ IMAGESIZE = 6900
+ </literallayout>
+ Other than <filename>IMAGESIZE</filename>, which is the
+ total size of the files in the image in Kbytes, the
+ name-value pairs are variables that may have influenced the
+ content of the image.
+ This information is often useful when you are trying to
+ determine why a change in the package or file
+ listings has occurred.
+ </para>
+ </section>
+
+ <section id='using-build-history-to-gather-image-information-only'>
+ <title>Using Build History to Gather Image Information Only</title>
+
+ <para>
+ As you can see, build history produces image information,
+ including dependency graphs, so you can see why something
+ was pulled into the image.
+ If you are just interested in this information and not
+ interested in collecting specific package or SDK
+ information, you can enable writing only image information
+ without any history by adding the following to your
+ <filename>conf/local.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
+ INHERIT += "buildhistory"
+ BUILDHISTORY_COMMIT = "0"
+ BUILDHISTORY_FEATURES = "image"
+ </literallayout>
+ Here, you set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_FEATURES'><filename>BUILDHISTORY_FEATURES</filename></ulink>
+ variable to use the image feature only.
+ </para>
+ </section>
+
+ <section id='build-history-sdk-information'>
+ <title>Build History SDK Information</title>
+
+ <para>
+ Build history collects similar information on the contents
+ of SDKs
+ (e.g. <filename>bitbake -c populate_sdk imagename</filename>)
+ as compared to information it collects for images.
+ Furthermore, this information differs depending on whether
+ an extensible or standard SDK is being produced.
+ </para>
+
+ <para>
+ The following list shows the files produced for SDKs:
+ <itemizedlist>
+ <listitem><para>
+ <filename>files-in-sdk.txt:</filename>
+ A list of files in the SDK with permissions,
+ owner, group, size, and symlink information.
+ This list includes both the host and target parts
+ of the SDK.
+ </para></listitem>
+ <listitem><para>
+ <filename>sdk-info.txt:</filename>
+ A text file containing name-value pairs with
+ information about the SDK.
+ See the following listing example for more
+ information.
+ </para></listitem>
+ <listitem><para>
+ <filename>sstate-task-sizes.txt:</filename>
+ A text file containing name-value pairs with
+ information about task group sizes
+ (e.g. <filename>do_populate_sysroot</filename>
+ tasks have a total size).
+ The <filename>sstate-task-sizes.txt</filename> file
+ exists only when an extensible SDK is created.
+ </para></listitem>
+ <listitem><para>
+ <filename>sstate-package-sizes.txt:</filename>
+ A text file containing name-value pairs with
+ information for the shared-state packages and
+ sizes in the SDK.
+ The <filename>sstate-package-sizes.txt</filename>
+ file exists only when an extensible SDK is created.
+ </para></listitem>
+ <listitem><para>
+ <filename>sdk-files:</filename>
+ A folder that contains copies of the files
+ mentioned in
+ <filename>BUILDHISTORY_SDK_FILES</filename> if the
+ files are present in the output.
+ Additionally, the default value of
+ <filename>BUILDHISTORY_SDK_FILES</filename> is
+ specific to the extensible SDK although you can
+ set it differently if you would like to pull in
+ specific files from the standard SDK.</para>
+
+ <para>The default files are
+ <filename>conf/local.conf</filename>,
+ <filename>conf/bblayers.conf</filename>,
+ <filename>conf/auto.conf</filename>,
+ <filename>conf/locked-sigs.inc</filename>, and
+ <filename>conf/devtool.conf</filename>.
+ Thus, for an extensible SDK, these files get
+ copied into the <filename>sdk-files</filename>
+ directory.
+ </para></listitem>
+ <listitem><para>
+ The following information appears under
+ each of the <filename>host</filename>
+ and <filename>target</filename> directories
+ for the portions of the SDK that run on the host
+ and on the target, respectively:
+ <note>
+ The following files for the most part are empty
+ when producing an extensible SDK because this
+ type of SDK is not constructed from packages
+ as is the standard SDK.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <filename>depends.dot:</filename>
+ Dependency graph for the SDK that is
+ compatible with
+ <filename>graphviz</filename>.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-names.txt:</filename>
+ A list of installed packages by name only.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-package-sizes.txt:</filename>
+ A list of installed packages ordered by size.
+ </para></listitem>
+ <listitem><para>
+ <filename>installed-packages.txt:</filename>
+ A list of installed packages with full
+ package filenames.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ Here is an example of <filename>sdk-info.txt</filename>:
+ <literallayout class='monospaced'>
+ DISTRO = poky
+ DISTRO_VERSION = 1.3+snapshot-20130327
+ SDK_NAME = poky-glibc-i686-arm
+ SDK_VERSION = 1.3+snapshot
+ SDKMACHINE =
+ SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
+ BAD_RECOMMENDATIONS =
+ SDKSIZE = 352712
+ </literallayout>
+ Other than <filename>SDKSIZE</filename>, which is the
+ total size of the files in the SDK in Kbytes, the
+ name-value pairs are variables that might have influenced
+ the content of the SDK.
+ This information is often useful when you are trying to
+ determine why a change in the package or file listings
+ has occurred.
+ </para>
+ </section>
+
+ <section id='examining-build-history-information'>
+ <title>Examining Build History Information</title>
+
+ <para>
+ You can examine build history output from the command
+ line or from a web interface.
+ </para>
+
+ <para>
+ To see any changes that have occurred (assuming you have
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-BUILDHISTORY_COMMIT'><filename>BUILDHISTORY_COMMIT</filename></ulink><filename> = "1"</filename>),
+ you can simply use any Git command that allows you to
+ view the history of a repository.
+ Here is one method:
+ <literallayout class='monospaced'>
+ $ git log -p
+ </literallayout>
+ You need to realize, however, that this method does show
+ changes that are not significant (e.g. a package's size
+ changing by a few bytes).
+ </para>
+
+ <para>
+ A command-line tool called
+ <filename>buildhistory-diff</filename> does exist, though,
+ that queries the Git repository and prints just the
+ differences that might be significant in human-readable
+ form.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
+ Changes to images/qemux86_64/glibc/core-image-minimal (files-in-image.txt):
+ /etc/anotherpkg.conf was added
+ /sbin/anotherpkg was added
+ * (installed-package-names.txt):
+ * anotherpkg was added
+ Changes to images/qemux86_64/glibc/core-image-minimal (installed-package-names.txt):
+ anotherpkg was added
+ packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
+ * PR changed from "r0" to "r1"
+ * PV changed from "0.1.10" to "0.1.12"
+ packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
+ * PR changed from "r0" to "r1"
+ * PV changed from "0.1.10" to "0.1.12"
+ </literallayout>
+ <note>
+ The <filename>buildhistory-diff</filename> tool
+ requires the <filename>GitPython</filename> package.
+ Be sure to install it using Pip3 as follows:
+ <literallayout class='monospaced'>
+ $ pip3 install GitPython --user
+ </literallayout>
+ Alternatively, you can install
+ <filename>python3-git</filename> using the appropriate
+ distribution package manager (e.g.
+ <filename>apt-get</filename>, <filename>dnf</filename>,
+ or <filename>zipper</filename>).
+ </note>
+ </para>
+
+ <para>
+ To see changes to the build history using a web interface,
+ follow the instruction in the <filename>README</filename>
+ file here.
+ <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
+ </para>
+
+ <para>
+ Here is a sample screenshot of the interface:
+ <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
+ </para>
+ </section>
+ </section>
+ </section>
+
<section id="performing-automated-runtime-testing">
<title>Performing Automated Runtime Testing</title>
@@ -8926,6 +11242,25 @@
which should generate a list of tap devices.
This is the option typically chosen for
Autobuilder-type environments.
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ Be sure to use an absolute path
+ when calling this script
+ with sudo.
+ </para></listitem>
+ <listitem><para>
+ The package recipe
+ <filename>qemu-helper-native</filename>
+ is required to run this script.
+ Build the package using the
+ following command:
+ <literallayout class='monospaced'>
+ $ bitbake qemu-helper-native
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </note>
</para></listitem>
</itemizedlist></para></listitem>
<listitem><para><emphasis>Set the
@@ -9768,368 +12103,1009 @@
</section>
</section>
- <section id="platdev-gdb-remotedebug">
- <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
+ <section id='usingpoky-debugging-tools-and-techniques'>
+ <title>Debugging Tools and Techniques</title>
<para>
- GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
- It also allows you to perform post-mortem style analysis of program crashes.
- GDB is available as a package within the Yocto Project and is
- installed in SDK images by default.
- See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
- in the Yocto Project Reference Manual for a description of these images.
- You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
- </para>
-
- <tip>
- For best results, install debug (<filename>-dbg</filename>) packages
- for the applications you are going to debug.
- Doing so makes extra debug symbols available that give you more
- meaningful output.
- </tip>
-
- <para>
- Sometimes, due to memory or disk space constraints, it is not possible
- to use GDB directly on the remote target to debug applications.
- These constraints arise because GDB needs to load the debugging information and the
- binaries of the process being debugged.
- Additionally, GDB needs to perform many computations to locate information such as function
- names, variable names and values, stack traces and so forth - even before starting the
- debugging process.
- These extra computations place more load on the target system and can alter the
- characteristics of the program being debugged.
+ The exact method for debugging build failures depends on the nature
+ of the problem and on the system's area from which the bug
+ originates.
+ Standard debugging practices such as comparison against the last
+ known working version with examination of the changes and the
+ re-application of steps to identify the one causing the problem are
+ valid for the Yocto Project just as they are for any other system.
+ Even though it is impossible to detail every possible potential
+ failure, this section provides some general tips to aid in
+ debugging given a variety of situations.
+ <note><title>Tip</title>
+ A useful feature for debugging is the error reporting tool.
+ Configuring the Yocto Project to use this tool causes the
+ OpenEmbedded build system to produce error reporting commands as
+ part of the console output.
+ You can enter the commands after the build completes to log
+ error information into a common database, that can help you
+ figure out what might be going wrong.
+ For information on how to enable and use this feature, see the
+ "<link linkend='using-the-error-reporting-tool'>Using the Error Reporting Tool</link>"
+ section.
+ </note>
</para>
<para>
- To help get past the previously mentioned constraints, you can use
- gdbserver, which runs on the remote target and does not load any
- debugging information from the debugged process.
- Instead, a GDB instance processes the debugging information that is run on a
- remote computer - the host GDB.
- The host GDB then sends control commands to gdbserver to make it stop or start the debugged
- program, as well as read or write memory regions of that debugged program.
- All the debugging information loaded and processed as well
- as all the heavy debugging is done by the host GDB.
- Offloading these processes gives the gdbserver running on the target a chance to remain
- small and fast.
- </para>
-
- <para>
- Because the host GDB is responsible for loading the debugging information and
- for doing the necessary processing to make actual debugging happen,
- you have to make sure the host can access the unstripped binaries complete
- with their debugging information and also be sure the target is compiled with no optimizations.
- The host GDB must also have local access to all the libraries used by the
- debugged program.
- Because gdbserver does not need any local debugging information, the binaries on
- the remote target can remain stripped.
- However, the binaries must also be compiled without optimization
- so they match the host's binaries.
- </para>
-
- <para>
- To remain consistent with GDB documentation and terminology, the binary being debugged
- on the remote target machine is referred to as the "inferior" binary.
- For documentation on GDB see the
- <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
- </para>
-
- <para>
- The following steps show you how to debug using the GNU project
- debugger.
- <orderedlist>
- <listitem><para>
- <emphasis>Configure your build system to construct the
- companion debug filesystem:</emphasis></para>
-
- <para>In your <filename>local.conf</filename> file, set
- the following:
- <literallayout class='monospaced'>
- IMAGE_GEN_DEBUGFS = "1"
- IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
- </literallayout>
- These options cause the OpenEmbedded build system
- to generate a special companion filesystem fragment,
- which contains the matching source and debug symbols to
- your deployable filesystem.
- The build system does this by looking at what is in the
- deployed filesystem, and pulling the corresponding
- <filename>-dbg</filename> packages.</para>
-
- <para>The companion debug filesystem is not a complete
- filesystem, but only contains the debug fragments.
- This filesystem must be combined with the full filesystem
- for debugging.
- Subsequent steps in this procedure show how to combine
- the partial filesystem with the full filesystem.
- </para></listitem>
- <listitem><para>
- <emphasis>Configure the system to include gdbserver in
- the target filesystem:</emphasis></para>
-
- <para>Make the following addition in either your
- <filename>local.conf</filename> file or in an image
- recipe:
- <literallayout class='monospaced'>
- IMAGE_INSTALL_append = “ gdbserver"
- </literallayout>
- The change makes sure the <filename>gdbserver</filename>
- package is included.
- </para></listitem>
- <listitem><para>
- <emphasis>Build the environment:</emphasis></para>
-
- <para>Use the following command to construct the image and
- the companion Debug Filesystem:
- <literallayout class='monospaced'>
- $ bitbake <replaceable>image</replaceable>
- </literallayout>
- Build the cross GDB component and make it available
- for debugging.
- Build the SDK that matches the image.
- Building the SDK is best for a production build
- that can be used later for debugging, especially
- during long term maintenance:
- <literallayout class='monospaced'>
- $ bitbake -c populate_sdk <replaceable>image</replaceable>
- </literallayout></para>
-
- <para>Alternatively, you can build the minimal
- toolchain components that match the target.
- Doing so creates a smaller than typical SDK and only
- contains a minimal set of components with which to
- build simple test applications, as well as run the
- debugger:
- <literallayout class='monospaced'>
- $ bitbake meta-toolchain
- </literallayout></para>
-
- <para>A final method is to build Gdb itself within
- the build system:
- <literallayout class='monospaced'>
- $ bitbake gdb-cross-<replaceable>architecture</replaceable>
- </literallayout>
- Doing so produces a temporary copy of
- <filename>cross-gdb</filename> you can use for
- debugging during development.
- While this is the quickest approach, the two previous
- methods in this step are better when considering
- long-term maintenance strategies.
- <note>
- If you run
- <filename>bitbake gdb-cross</filename>, the
- OpenEmbedded build system suggests the actual
- image (e.g. <filename>gdb-cross-i586</filename>).
- The suggestion is usually the actual name you want
- to use.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up the</emphasis> <filename>debugfs</filename></para>
-
- <para>Run the following commands to set up the
- <filename>debugfs</filename>:
- <literallayout class='monospaced'>
- $ mkdir debugfs
- $ cd debugfs
- $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
- $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
- </literallayout>
- </para></listitem>
- <listitem><para>
- <emphasis>Set up GDB</emphasis></para>
-
- <para>Install the SDK (if you built one) and then
- source the correct environment file.
- Sourcing the environment file puts the SDK in your
- <filename>PATH</filename> environment variable.</para>
-
- <para>If you are using the build system, Gdb is
- located in
- <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
- </para></listitem>
- <listitem><para>
- <emphasis>Boot the target:</emphasis></para>
-
- <para>For information on how to run QEMU, see the
- <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
- <note>
- Be sure to verify that your host can access the
- target via TCP.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Debug a program:</emphasis></para>
-
- <para>Debugging a program involves running gdbserver
- on the target and then running Gdb on the host.
- The example in this step debugs
- <filename>gzip</filename>:
- <literallayout class='monospaced'>
- root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
- </literallayout>
- For additional gdbserver options, see the
- <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>.
- </para>
-
- <para>After running gdbserver on the target, you need
- to run Gdb on the host and configure it and connect to
- the target.
- Use these commands:
- <literallayout class='monospaced'>
- $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
- $ <replaceable>arch</replaceable>-gdb
-
- (gdb) set sysroot debugfs
- (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
- (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
- </literallayout>
- At this point, everything should automatically load
- (i.e. matching binaries, symbols and headers).
- <note>
- The Gdb <filename>set</filename> commands in the
- previous example can be placed into the users
- <filename>~/.gdbinit</filename> file.
- Upon starting, Gdb automatically runs whatever
- commands are in that file.
- </note>
- </para></listitem>
- <listitem><para>
- <emphasis>Deploying without a full image
- rebuild:</emphasis></para>
-
- <para>In many cases, during development you want a
- quick method to deploy a new binary to the target and
- debug it, without waiting for a full image build.
- </para>
-
- <para>One approach to solving this situation is to
- just build the component you want to debug.
- Once you have built the component, copy the
- executable directly to both the target and the
- host <filename>debugfs</filename>.</para>
-
- <para>If the binary is processed through the debug
- splitting in OpenEmbedded, you should also
- copy the debug items (i.e. <filename>.debug</filename>
- contents and corresponding
- <filename>/usr/src/debug</filename> files)
- from the work directory.
- Here is an example:
- <literallayout class='monospaced'>
- $ bitbake bash
- $ bitbake -c devshell bash
- $ cd ..
- $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
- $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
- </literallayout>
- </para></listitem>
- </orderedlist>
- </para>
- </section>
-
- <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
- <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
-
- <para>
- The previous section addressed using GDB remotely for debugging
- purposes, which is the most usual case due to the inherent
- hardware limitations on many embedded devices.
- However, debugging in the target hardware itself is also possible
- with more powerful devices.
- This section describes what you need to do in order to support
- using GDB to debug on the target hardware.
- </para>
-
- <para>
- To support this kind of debugging, you need do the following:
+ The following list shows the debugging topics in the remainder of
+ this section:
<itemizedlist>
<listitem><para>
- Ensure that GDB is on the target.
- You can do this by adding "gdb" to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
- <literallayout class='monospaced'>
- IMAGE_INSTALL_append = " gdb"
- </literallayout>
- Alternatively, you can add "tools-debug" to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
- <literallayout class='monospaced'>
- IMAGE_FEATURES_append = " tools-debug"
- </literallayout>
+ "<link linkend='dev-debugging-viewing-logs-from-failed-tasks'>Viewing Logs from Failed Tasks</link>"
+ describes how to find and view logs from tasks that
+ failed during the build process.
</para></listitem>
<listitem><para>
- Ensure that debug symbols are present.
- You can make sure these symbols are present by installing
- <filename>-dbg</filename>:
- <literallayout class='monospaced'>
- IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg"
- </literallayout>
- Alternatively, you can do the following to include all the
- debug symbols:
- <literallayout class='monospaced'>
- IMAGE_FEATURES_append = " dbg-pkgs"
- </literallayout>
+ "<link linkend='dev-debugging-viewing-variable-values'>Viewing Variable Values</link>"
+ describes how to use the BitBake <filename>-e</filename>
+ option to examine variable values after a recipe has been
+ parsed.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='viewing-package-information-with-oe-pkgdata-util'>Viewing Package Information with <filename>oe-pkgdata-util</filename></link>"
+ describes how to use the
+ <filename>oe-pkgdata-util</filename> utility to query
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+ and display package-related information for built
+ packages.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-viewing-dependencies-between-recipes-and-tasks'>Viewing Dependencies Between Recipes and Tasks</link>"
+ describes how to use the BitBake <filename>-g</filename>
+ option to display recipe dependency information used
+ during the build.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
+ describes how to use the
+ <filename>bitbake-dumpsig</filename> command in
+ conjunction with key subdirectories in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>
+ to determine variable dependencies.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-debugging-taskrunning'>Running Specific Tasks</link>"
+ describes how to use several BitBake options (e.g.
+ <filename>-c</filename>, <filename>-C</filename>, and
+ <filename>-f</filename>) to run specific tasks in the
+ build chain.
+ It can be useful to run tasks "out-of-order" when trying
+ isolate build issues.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-debugging-bitbake'>General BitBake Problems</link>"
+ describes how to use BitBake's <filename>-D</filename>
+ debug output option to reveal more about what BitBake is
+ doing during the build.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-debugging-buildfile'>Building with No Dependencies</link>"
+ describes how to use the BitBake <filename>-b</filename>
+ option to build a recipe while ignoring dependencies.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='recipe-logging-mechanisms'>Recipe Logging Mechanisms</link>"
+ describes how to use the many recipe logging functions
+ to produce debugging output and report errors and warnings.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='debugging-parallel-make-races'>Debugging Parallel Make Races</link>"
+ describes how to debug situations where the build consists
+ of several parts that are run simultaneously and when the
+ output or result of one part is not ready for use with a
+ different part of the build that depends on that output.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</link>"
+ describes how to use GDB to allow you to examine running
+ programs, which can help you fix problems.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>Debugging with the GNU Project Debugger (GDB) on the Target</link>"
+ describes how to use GDB directly on target hardware for
+ debugging.
+ </para></listitem>
+ <listitem><para>
+ "<link linkend='dev-other-debugging-others'>Other Debugging Tips</link>"
+ describes miscellaneous debugging tips that can be useful.
</para></listitem>
</itemizedlist>
- <note>
- To improve the debug information accuracy, you can reduce the
- level of optimization used by the compiler.
- For example, when adding the following line to your
- <filename>local.conf</filename> file, you will reduce
- optimization from
- <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
- of "-O2" to
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
- of "-O -fno-omit-frame-pointer":
- <literallayout class='monospaced'>
- DEBUG_BUILD = "1"
- </literallayout>
- Consider that this will reduce the application's performance
- and is recommended only for debugging purposes.
- </note>
</para>
- </section>
-
- <section id='debugging-parallel-make-races'>
- <title>Debugging Parallel Make Races</title>
<para>
- A parallel <filename>make</filename> race occurs when the build
- consists of several parts that are run simultaneously and
- a situation occurs when the output or result of one
- part is not ready for use with a different part of the build that
- depends on that output.
- Parallel make races are annoying and can sometimes be difficult
- to reproduce and fix.
- However, some simple tips and tricks exist that can help
- you debug and fix them.
- This section presents a real-world example of an error encountered
- on the Yocto Project autobuilder and the process used to fix it.
- <note>
- If you cannot properly fix a <filename>make</filename> race
- condition, you can work around it by clearing either the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
- or
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
- variables.
- </note>
+ For debugging information within the popular
+ <trademark class='trade'>Eclipse</trademark> IDE, see the
+ "<ulink url='&YOCTO_DOCS_SDK_URL;#adt-eclipse'>Working within Eclipse</ulink>"
+ section in the Yocto Project Application Development and the
+ Extensible Software Development Kit (eSDK) manual.
</para>
- <section id='the-failure'>
- <title>The Failure</title>
+ <section id='dev-debugging-viewing-logs-from-failed-tasks'>
+ <title>Viewing Logs from Failed Tasks</title>
<para>
- For this example, assume that you are building an image that
- depends on the "neard" package.
- And, during the build, BitBake runs into problems and
- creates the following output.
- <note>
- This example log file has longer lines artificially
- broken to make the listing easier to read.
- </note>
- If you examine the output or the log file, you see the
- failure during <filename>make</filename>:
+ You can find the log for a task in the file
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/temp/log.do_</filename><replaceable>taskname</replaceable>.
+ For example, the log for the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>
+ task of the QEMU minimal image for the x86 machine
+ (<filename>qemux86</filename>) might be in
+ <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile</filename>.
+ To see the commands
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ ran to generate a log, look at the corresponding
+ <filename>run.do_</filename><replaceable>taskname</replaceable>
+ file in the same directory.
+ </para>
+
+ <para>
+ <filename>log.do_</filename><replaceable>taskname</replaceable>
+ and
+ <filename>run.do_</filename><replaceable>taskname</replaceable>
+ are actually symbolic links to
+ <filename>log.do_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>
+ and
+ <filename>log.run_</filename><replaceable>taskname</replaceable><filename>.</filename><replaceable>pid</replaceable>,
+ where <replaceable>pid</replaceable> is the PID the task had
+ when it ran.
+ The symlinks always point to the files corresponding to the most
+ recent run.
+ </para>
+ </section>
+
+ <section id='dev-debugging-viewing-variable-values'>
+ <title>Viewing Variable Values</title>
+
+ <para>
+ BitBake's <filename>-e</filename> option is used to display
+ variable values after parsing.
+ The following command displays the variable values after the
+ configuration files (i.e. <filename>local.conf</filename>,
+ <filename>bblayers.conf</filename>,
+ <filename>bitbake.conf</filename> and so forth) have been
+ parsed:
<literallayout class='monospaced'>
+ $ bitbake -e
+ </literallayout>
+ The following command displays variable values after a specific
+ recipe has been parsed.
+ The variables include those from the configuration as well:
+ <literallayout class='monospaced'>
+ $ bitbake -e recipename
+ </literallayout>
+ <note><para>
+ Each recipe has its own private set of variables
+ (datastore).
+ Internally, after parsing the configuration, a copy of the
+ resulting datastore is made prior to parsing each recipe.
+ This copying implies that variables set in one recipe will
+ not be visible to other recipes.</para>
+
+ <para>Likewise, each task within a recipe gets a private
+ datastore based on the recipe datastore, which means that
+ variables set within one task will not be visible to
+ other tasks.</para>
+ </note>
+ </para>
+
+ <para>
+ In the output of <filename>bitbake -e</filename>, each
+ variable is preceded by a description of how the variable
+ got its value, including temporary values that were later
+ overriden.
+ This description also includes variable flags (varflags) set on
+ the variable.
+ The output can be very helpful during debugging.
+ </para>
+
+ <para>
+ Variables that are exported to the environment are preceded by
+ <filename>export</filename> in the output of
+ <filename>bitbake -e</filename>.
+ See the following example:
+ <literallayout class='monospaced'>
+ export CC="i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/ulf/poky/build/tmp/sysroots/qemux86"
+ </literallayout>
+ </para>
+
+ <para>
+ In addition to variable values, the output of the
+ <filename>bitbake -e</filename> and
+ <filename>bitbake -e</filename> <replaceable>recipe</replaceable>
+ commands includes the following information:
+ <itemizedlist>
+ <listitem><para>
+ The output starts with a tree listing all configuration
+ files and classes included globally, recursively listing
+ the files they include or inherit in turn.
+ Much of the behavior of the OpenEmbedded build system
+ (including the behavior of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>)
+ is implemented in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-base'><filename>base</filename></ulink>
+ class and the classes it inherits, rather than being
+ built into BitBake itself.
+ </para></listitem>
+ <listitem><para>
+ After the variable values, all functions appear in the
+ output.
+ For shell functions, variables referenced within the
+ function body are expanded.
+ If a function has been modified using overrides or
+ using override-style operators like
+ <filename>_append</filename> and
+ <filename>_prepend</filename>, then the final assembled
+ function body appears in the output.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id='viewing-package-information-with-oe-pkgdata-util'>
+ <title>Viewing Package Information with <filename>oe-pkgdata-util</filename></title>
+
+ <para>
+ You can use the <filename>oe-pkgdata-util</filename>
+ command-line utility to query
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></ulink>
+ and display various package-related information.
+ When you use the utility, you must use it to view information
+ on packages that have already been built.
+ </para>
+
+ <para>
+ Following are a few of the available
+ <filename>oe-pkgdata-util</filename> subcommands.
+ <note>
+ You can use the standard * and ? globbing wildcards as part
+ of package names and paths.
+ </note>
+ <itemizedlist>
+ <listitem><para>
+ <filename>oe-pkgdata-util list-pkgs [</filename><replaceable>pattern</replaceable><filename>]</filename>:
+ Lists all packages that have been built, optionally
+ limiting the match to packages that match
+ <replaceable>pattern</replaceable>.
+ </para></listitem>
+ <listitem><para>
+ <filename>oe-pkgdata-util list-pkg-files </filename><replaceable>package</replaceable><filename> ...</filename>:
+ Lists the files and directories contained in the given
+ packages.
+ <note>
+ <para>
+ A different way to view the contents of a package is
+ to look at the
+ <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/packages-split</filename>
+ directory of the recipe that generates the
+ package.
+ This directory is created by the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ task and has one subdirectory for each package the
+ recipe generates, which contains the files stored in
+ that package.</para>
+ <para>
+ If you want to inspect the
+ <filename>${WORKDIR}/packages-split</filename>
+ directory, make sure that
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-rm-work'><filename>rm_work</filename></ulink>
+ is not enabled when you build the recipe.
+ </para>
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <filename>oe-pkgdata-util find-path </filename><replaceable>path</replaceable><filename> ...</filename>:
+ Lists the names of the packages that contain the given
+ paths.
+ For example, the following tells us that
+ <filename>/usr/share/man/man1/make.1</filename>
+ is contained in the <filename>make-doc</filename>
+ package:
+ <literallayout class='monospaced'>
+ $ oe-pkgdata-util find-path /usr/share/man/man1/make.1
+ make-doc: /usr/share/man/man1/make.1
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <filename>oe-pkgdata-util lookup-recipe </filename><replaceable>package</replaceable><filename> ...</filename>:
+ Lists the name of the recipes that
+ produce the given packages.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For more information on the <filename>oe-pkgdata-util</filename>
+ command, use the help facility:
+ <literallayout class='monospaced'>
+ $ oe-pkgdata-util ‐‐help
+ $ oe-pkgdata-util <replaceable>subcommand</replaceable> --help
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='dev-viewing-dependencies-between-recipes-and-tasks'>
+ <title>Viewing Dependencies Between Recipes and Tasks</title>
+
+ <para>
+ Sometimes it can be hard to see why BitBake wants to build other
+ recipes before the one you have specified.
+ Dependency information can help you understand why a recipe is
+ built.
+ </para>
+
+ <para>
+ To generate dependency information for a recipe, run the
+ following command:
+ <literallayout class='monospaced'>
+ $ bitbake -g <replaceable>recipename</replaceable>
+ </literallayout>
+ This command writes the following files in the current
+ directory:
+ <itemizedlist>
+ <listitem><para>
+ <filename>pn-buildlist</filename>: A list of
+ recipes/targets involved in building
+ <replaceable>recipename</replaceable>.
+ "Involved" here means that at least one task from the
+ recipe needs to run when building
+ <replaceable>recipename</replaceable> from scratch.
+ Targets that are in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-ASSUME_PROVIDED'><filename>ASSUME_PROVIDED</filename></ulink>
+ are not listed.
+ </para></listitem>
+ <listitem><para>
+ <filename>task-depends.dot</filename>: A graph showing
+ dependencies between tasks.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The graphs are in
+ <ulink url='https://en.wikipedia.org/wiki/DOT_%28graph_description_language%29'>DOT</ulink>
+ format and can be converted to images (e.g. using the
+ <filename>dot</filename> tool from
+ <ulink url='http://www.graphviz.org/'>Graphviz</ulink>).
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ DOT files use a plain text format.
+ The graphs generated using the
+ <filename>bitbake -g</filename> command are often so
+ large as to be difficult to read without special
+ pruning (e.g. with Bitbake's
+ <filename>-I</filename> option) and processing.
+ Despite the form and size of the graphs, the
+ corresponding <filename>.dot</filename> files can
+ still be possible to read and provide useful
+ information.
+ </para>
+
+ <para>As an example, the
+ <filename>task-depends.dot</filename> file contains
+ lines such as the following:
+ <literallayout class='monospaced'>
+ "libxslt.do_configure" -> "libxml2.do_populate_sysroot"
+ </literallayout>
+ The above example line reveals that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>
+ task in <filename>libxslt</filename> depends on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-populate_sysroot'><filename>do_populate_sysroot</filename></ulink>
+ task in <filename>libxml2</filename>, which is a
+ normal
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+ dependency between the two recipes.
+ </para></listitem>
+ <listitem><para>
+ For an example of how <filename>.dot</filename>
+ files can be processed, see the
+ <filename>scripts/contrib/graph-tool</filename>
+ Python script, which finds and displays paths
+ between graph nodes.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ You can use a different method to view dependency information
+ by using the following command:
+ <literallayout class='monospaced'>
+ $ bitbake -g -u taskexp <replaceable>recipename</replaceable>
+ </literallayout>
+ This command displays a GUI window from which you can view
+ build-time and runtime dependencies for the recipes involved in
+ building <replaceable>recipename</replaceable>.
+ </para>
+ </section>
+
+ <section id='dev-viewing-task-variable-dependencies'>
+ <title>Viewing Task Variable Dependencies</title>
+
+ <para>
+ As mentioned in the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#checksums'>Checksums (Signatures)</ulink>"
+ section of the BitBake User Manual, BitBake tries to
+ automatically determine what variables a task depends on so
+ that it can rerun the task if any values of the variables
+ change.
+ This determination is usually reliable.
+ However, if you do things like construct variable names at
+ runtime, then you might have to manually declare dependencies
+ on those variables using <filename>vardeps</filename> as
+ described in the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'>Variable Flags</ulink>"
+ section of the BitBake User Manual.
+ </para>
+
+ <para>
+ If you are unsure whether a variable dependency is being
+ picked up automatically for a given task, you can list the
+ variable dependencies BitBake has determined by doing the
+ following:
+ <orderedlist>
+ <listitem><para>
+ Build the recipe containing the task:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>recipename</replaceable>
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Inside the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-STAMPS_DIR'><filename>STAMPS_DIR</filename></ulink>
+ directory, find the signature data
+ (<filename>sigdata</filename>) file that corresponds
+ to the task.
+ The <filename>sigdata</filename> files contain a pickled
+ Python database of all the metadata that went into
+ creating the input checksum for the task.
+ As an example, for the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-fetch'><filename>do_fetch</filename></ulink>
+ task of the <filename>db</filename> recipe, the
+ <filename>sigdata</filename> file might be found in the
+ following location:
+ <literallayout class='monospaced'>
+ ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
+ </literallayout>
+ For tasks that are accelerated through the shared state
+ (<ulink url='&YOCTO_DOCS_OM_URL;#shared-state-cache'>sstate</ulink>)
+ cache, an additional <filename>siginfo</filename> file
+ is written into
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+ along with the cached task output.
+ The <filename>siginfo</filename> files contain exactly
+ the same information as <filename>sigdata</filename>
+ files.
+ </para></listitem>
+ <listitem><para>
+ Run <filename>bitbake-dumpsig</filename> on the
+ <filename>sigdata</filename> or
+ <filename>siginfo</filename> file.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake-dumpsig ${BUILDDIR}/tmp/stamps/i586-poky-linux/db/6.0.30-r1.do_fetch.sigdata.7c048c18222b16ff0bcee2000ef648b1
+ </literallayout>
+ In the output of the above command, you will find a
+ line like the following, which lists all the (inferred)
+ variable dependencies for the task.
+ This list also includes indirect dependencies from
+ variables depending on other variables, recursively.
+ <literallayout class='monospaced'>
+ Task dependencies: ['PV', 'SRCREV', 'SRC_URI', 'SRC_URI[md5sum]', 'SRC_URI[sha256sum]', 'base_do_fetch']
+ </literallayout>
+ <note>
+ Functions (e.g. <filename>base_do_fetch</filename>)
+ also count as variable dependencies.
+ These functions in turn depend on the variables they
+ reference.
+ </note>
+ The output of <filename>bitbake-dumpsig</filename> also
+ includes the value each variable had, a list of
+ dependencies for each variable, and
+ <ulink url='&YOCTO_DOCS_BB_URL;#var-BB_HASHBASE_WHITELIST'><filename>BB_HASHBASE_WHITELIST</filename></ulink>
+ information.
+ </para></listitem>
+ </orderedlist>
+ </para>
+
+ <para>
+ There is also a <filename>bitbake-diffsigs</filename> command
+ for comparing two <filename>siginfo</filename> or
+ <filename>sigdata</filename> files.
+ This command can be helpful when trying to figure out what
+ changed between two versions of a task.
+ If you call <filename>bitbake-diffsigs</filename> with just one
+ file, the command behaves like
+ <filename>bitbake-dumpsig</filename>.
+ </para>
+
+ <para>
+ You can also use BitBake to dump out the signature construction
+ information without executing tasks by using either of the
+ following BitBake command-line options:
+ <literallayout class='monospaced'>
+ ‐‐dump-signatures=<replaceable>SIGNATURE_HANDLER</replaceable>
+ -S <replaceable>SIGNATURE_HANDLER</replaceable>
+ </literallayout>
+ <note>
+ Two common values for
+ <replaceable>SIGNATURE_HANDLER</replaceable> are "none" and
+ "printdiff", which dump only the signature or compare the
+ dumped signature with the cached one, respectively.
+ </note>
+ Using BitBake with either of these options causes BitBake to
+ dump out <filename>sigdata</filename> files in the
+ <filename>stamps</filename> directory for every task it would
+ have executed instead of building the specified target package.
+ </para>
+ </section>
+
+ <section id='dev-viewing-metadata-used-to-create-the-input-signature-of-a-shared-state-task'>
+ <title>Viewing Metadata Used to Create the Input Signature of a Shared State Task</title>
+
+ <para>
+ Seeing what metadata went into creating the input signature
+ of a shared state (sstate) task can be a useful debugging
+ aid.
+ This information is available in signature information
+ (<filename>siginfo</filename>) files in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>.
+ For information on how to view and interpret information in
+ <filename>siginfo</filename> files, see the
+ "<link linkend='dev-viewing-task-variable-dependencies'>Viewing Task Variable Dependencies</link>"
+ section.
+ </para>
+
+ <para>
+ For conceptual information on shared state, see the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>Shared State</ulink>"
+ section in the Yocto Project Overview and Concepts Manual.
+ </para>
+ </section>
+
+ <section id='dev-invalidating-shared-state-to-force-a-task-to-run'>
+ <title>Invalidating Shared State to Force a Task to Run</title>
+
+ <para>
+ The OpenEmbedded build system uses
+ <ulink url='&YOCTO_DOCS_OM_URL;#overview-checksums'>checksums</ulink>
+ and
+ <ulink url='&YOCTO_DOCS_OM_URL;#shared-state'>shared state</ulink>
+ cache to avoid unnecessarily rebuilding tasks.
+ Collectively, this scheme is known as "shared state code."
+ </para>
+
+ <para>
+ As with all schemes, this one has some drawbacks.
+ It is possible that you could make implicit changes to your
+ code that the checksum calculations do not take into
+ account.
+ These implicit changes affect a task's output but do not
+ trigger the shared state code into rebuilding a recipe.
+ Consider an example during which a tool changes its output.
+ Assume that the output of <filename>rpmdeps</filename>
+ changes.
+ The result of the change should be that all the
+ <filename>package</filename> and
+ <filename>package_write_rpm</filename> shared state cache
+ items become invalid.
+ However, because the change to the output is
+ external to the code and therefore implicit,
+ the associated shared state cache items do not become
+ invalidated.
+ In this case, the build process uses the cached items
+ rather than running the task again.
+ Obviously, these types of implicit changes can cause
+ problems.
+ </para>
+
+ <para>
+ To avoid these problems during the build, you need to
+ understand the effects of any changes you make.
+ Realize that changes you make directly to a function
+ are automatically factored into the checksum calculation.
+ Thus, these explicit changes invalidate the associated
+ area of shared state cache.
+ However, you need to be aware of any implicit changes that
+ are not obvious changes to the code and could affect
+ the output of a given task.
+ </para>
+
+ <para>
+ When you identify an implicit change, you can easily
+ take steps to invalidate the cache and force the tasks
+ to run.
+ The steps you can take are as simple as changing a
+ function's comments in the source code.
+ For example, to invalidate package shared state files,
+ change the comment statements of
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-package'><filename>do_package</filename></ulink>
+ or the comments of one of the functions it calls.
+ Even though the change is purely cosmetic, it causes the
+ checksum to be recalculated and forces the build system to
+ run the task again.
+ <note>
+ For an example of a commit that makes a cosmetic
+ change to invalidate shared state, see this
+ <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
+ </note>
+ </para>
+ </section>
+
+ <section id='dev-debugging-taskrunning'>
+ <title>Running Specific Tasks</title>
+
+ <para>
+ Any given recipe consists of a set of tasks.
+ The standard BitBake behavior in most cases is:
+ <filename>do_fetch</filename>,
+ <filename>do_unpack</filename>,
+ <filename>do_patch</filename>,
+ <filename>do_configure</filename>,
+ <filename>do_compile</filename>,
+ <filename>do_install</filename>,
+ <filename>do_package</filename>,
+ <filename>do_package_write_*</filename>, and
+ <filename>do_build</filename>.
+ The default task is <filename>do_build</filename> and any tasks
+ on which it depends build first.
+ Some tasks, such as <filename>do_devshell</filename>, are not
+ part of the default build chain.
+ If you wish to run a task that is not part of the default build
+ chain, you can use the <filename>-c</filename> option in
+ BitBake.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -c devshell
+ </literallayout>
+ </para>
+
+ <para>
+ The <filename>-c</filename> option respects task dependencies,
+ which means that all other tasks (including tasks from other
+ recipes) that the specified task depends on will be run before
+ the task.
+ Even when you manually specify a task to run with
+ <filename>-c</filename>, BitBake will only run the task if it
+ considers it "out of date".
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#stamp-files-and-the-rerunning-of-tasks'>Stamp Files and the Rerunning of Tasks</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for
+ how BitBake determines whether a task is "out of date".
+ </para>
+
+ <para>
+ If you want to force an up-to-date task to be rerun (e.g.
+ because you made manual modifications to the recipe's
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
+ that you want to try out), then you can use the
+ <filename>-f</filename> option.
+ <note>
+ The reason <filename>-f</filename> is never required when
+ running the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-devshell'><filename>do_devshell</filename></ulink>
+ task is because the
+ <filename>[</filename><ulink url='&YOCTO_DOCS_BB_URL;#variable-flags'><filename>nostamp</filename></ulink><filename>]</filename>
+ variable flag is already set for the task.
+ </note>
+ The following example shows one way you can use the
+ <filename>-f</filename> option:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop
+ .
+ .
+ make some changes to the source code in the work directory
+ .
+ .
+ $ bitbake matchbox-desktop -c compile -f
+ $ bitbake matchbox-desktop
+ </literallayout>
+ </para>
+
+ <para>
+ This sequence first builds and then recompiles
+ <filename>matchbox-desktop</filename>.
+ The last command reruns all tasks (basically the packaging
+ tasks) after the compile.
+ BitBake recognizes that the <filename>do_compile</filename>
+ task was rerun and therefore understands that the other tasks
+ also need to be run again.
+ </para>
+
+ <para>
+ Another, shorter way to rerun a task and all
+ <ulink url='&YOCTO_DOCS_REF_URL;#normal-recipe-build-tasks'>normal recipe build tasks</ulink>
+ that depend on it is to use the <filename>-C</filename>
+ option.
+ <note>
+ This option is upper-cased and is separate from the
+ <filename>-c</filename> option, which is lower-cased.
+ </note>
+ Using this option invalidates the given task and then runs the
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-build'><filename>do_build</filename></ulink>
+ task, which is the default task if no task is given, and the
+ tasks on which it depends.
+ You could replace the final two commands in the previous example
+ with the following single command:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -C compile
+ </literallayout>
+ Internally, the <filename>-f</filename> and
+ <filename>-C</filename> options work by tainting (modifying) the
+ input checksum of the specified task.
+ This tainting indirectly causes the task and its
+ dependent tasks to be rerun through the normal task dependency
+ mechanisms.
+ <note>
+ BitBake explicitly keeps track of which tasks have been
+ tainted in this fashion, and will print warnings such as the
+ following for builds involving such tasks:
+ <literallayout class='monospaced'>
+ WARNING: /home/ulf/poky/meta/recipes-sato/matchbox-desktop/matchbox-desktop_2.1.bb.do_compile is tainted from a forced run
+ </literallayout>
+ The purpose of the warning is to let you know that the work
+ directory and build output might not be in the clean state
+ they would be in for a "normal" build, depending on what
+ actions you took.
+ To get rid of such warnings, you can remove the work
+ directory and rebuild the recipe, as follows:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -c clean
+ $ bitbake matchbox-desktop
+ </literallayout>
+ </note>
+ </para>
+
+ <para>
+ You can view a list of tasks in a given package by running the
+ <filename>do_listtasks</filename> task as follows:
+ <literallayout class='monospaced'>
+ $ bitbake matchbox-desktop -c listtasks
+ </literallayout>
+ The results appear as output to the console and are also in the
+ file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
+ </para>
+ </section>
+
+ <section id='dev-debugging-bitbake'>
+ <title>General BitBake Problems</title>
+
+ <para>
+ You can see debug output from BitBake by using the
+ <filename>-D</filename> option.
+ The debug output gives more information about what BitBake
+ is doing and the reason behind it.
+ Each <filename>-D</filename> option you use increases the
+ logging level.
+ The most common usage is <filename>-DDD</filename>.
+ </para>
+
+ <para>
+ The output from
+ <filename>bitbake -DDD -v</filename> <replaceable>targetname</replaceable>
+ can reveal why BitBake chose a certain version of a package or
+ why BitBake picked a certain provider.
+ This command could also help you in a situation where you think
+ BitBake did something unexpected.
+ </para>
+ </section>
+
+ <section id='dev-debugging-buildfile'>
+ <title>Building with No Dependencies</title>
+
+ <para>
+ To build a specific recipe (<filename>.bb</filename> file),
+ you can use the following command form:
+ <literallayout class='monospaced'>
+ $ bitbake -b <replaceable>somepath</replaceable>/<replaceable>somerecipe</replaceable>.bb
+ </literallayout>
+ This command form does not check for dependencies.
+ Consequently, you should use it only when you know existing
+ dependencies have been met.
+ <note>
+ You can also specify fragments of the filename.
+ In this case, BitBake checks for a unique match.
+ </note>
+ </para>
+ </section>
+
+ <section id='recipe-logging-mechanisms'>
+ <title>Recipe Logging Mechanisms</title>
+
+ <para>
+ The Yocto Project provides several logging functions for
+ producing debugging output and reporting errors and warnings.
+ For Python functions, the following logging functions exist.
+ All of these functions log to
+ <filename>${T}/log.do_</filename><replaceable>task</replaceable>,
+ and can also log to standard output (stdout) with the right
+ settings:
+ <itemizedlist>
+ <listitem><para>
+ <filename>bb.plain(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes <replaceable>msg</replaceable> as is to the
+ log while also logging to stdout.
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.note(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "NOTE: <replaceable>msg</replaceable>" to the
+ log.
+ Also logs to stdout if BitBake is called with "-v".
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.debug(</filename><replaceable>level</replaceable><filename>, </filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "DEBUG: <replaceable>msg</replaceable>" to the
+ log.
+ Also logs to stdout if the log level is greater than or
+ equal to <replaceable>level</replaceable>.
+ See the
+ "<ulink url='&YOCTO_DOCS_BB_URL;#usage-and-syntax'>-D</ulink>"
+ option in the BitBake User Manual for more information.
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.warn(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "WARNING: <replaceable>msg</replaceable>" to the
+ log while also logging to stdout.
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ Writes "ERROR: <replaceable>msg</replaceable>" to the
+ log while also logging to standard out (stdout).
+ <note>
+ Calling this function does not cause the task to fail.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <filename>bb.fatal(</filename><replaceable>msg</replaceable><filename>)</filename>:
+ This logging function is similar to
+ <filename>bb.error(</filename><replaceable>msg</replaceable><filename>)</filename>
+ but also causes the calling task to fail.
+ <note>
+ <filename>bb.fatal()</filename> raises an exception,
+ which means you do not need to put a "return"
+ statement after the function.
+ </note>
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ The same logging functions are also available in shell
+ functions, under the names
+ <filename>bbplain</filename>, <filename>bbnote</filename>,
+ <filename>bbdebug</filename>, <filename>bbwarn</filename>,
+ <filename>bberror</filename>, and <filename>bbfatal</filename>.
+ The
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-logging'><filename>logging</filename></ulink>
+ class implements these functions.
+ See that class in the
+ <filename>meta/classes</filename> folder of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ for information.
+ </para>
+
+ <section id='logging-with-python'>
+ <title>Logging With Python</title>
+
+ <para>
+ When creating recipes using Python and inserting code that
+ handles build logs, keep in mind the goal is to have
+ informative logs while keeping the console as "silent" as
+ possible.
+ Also, if you want status messages in the log, use the
+ "debug" loglevel.
+ </para>
+
+ <para>
+ Following is an example written in Python.
+ The code handles logging for a function that determines the
+ number of tasks needed to be run.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-listtasks'><filename>do_listtasks</filename></ulink>"
+ section for additional information:
+ <literallayout class='monospaced'>
+ python do_listtasks() {
+ bb.debug(2, "Starting to figure out the task list")
+ if noteworthy_condition:
+ bb.note("There are 47 tasks to run")
+ bb.debug(2, "Got to point xyz")
+ if warning_trigger:
+ bb.warn("Detected warning_trigger, this might be a problem later.")
+ if recoverable_error:
+ bb.error("Hit recoverable_error, you really need to fix this!")
+ if fatal_error:
+ bb.fatal("fatal_error detected, unable to print the task list")
+ bb.plain("The tasks present are abc")
+ bb.debug(2, "Finished figuring out the tasklist")
+ }
+ </literallayout>
+ </para>
+ </section>
+
+ <section id='logging-with-bash'>
+ <title>Logging With Bash</title>
+
+ <para>
+ When creating recipes using Bash and inserting code that
+ handles build logs, you have the same goals - informative
+ with minimal console output.
+ The syntax you use for recipes written in Bash is similar
+ to that of recipes written in Python described in the
+ previous section.
+ </para>
+
+ <para>
+ Following is an example written in Bash.
+ The code logs the progress of the <filename>do_my_function</filename> function.
+ <literallayout class='monospaced'>
+ do_my_function() {
+ bbdebug 2 "Running do_my_function"
+ if [ exceptional_condition ]; then
+ bbnote "Hit exceptional_condition"
+ fi
+ bbdebug 2 "Got to point xyz"
+ if [ warning_trigger ]; then
+ bbwarn "Detected warning_trigger, this might cause a problem later."
+ fi
+ if [ recoverable_error ]; then
+ bberror "Hit recoverable_error, correcting"
+ fi
+ if [ fatal_error ]; then
+ bbfatal "fatal_error detected"
+ fi
+ bbdebug 2 "Completed do_my_function"
+ }
+ </literallayout>
+ </para>
+ </section>
+ </section>
+
+ <section id='debugging-parallel-make-races'>
+ <title>Debugging Parallel Make Races</title>
+
+ <para>
+ A parallel <filename>make</filename> race occurs when the build
+ consists of several parts that are run simultaneously and
+ a situation occurs when the output or result of one
+ part is not ready for use with a different part of the build
+ that depends on that output.
+ Parallel make races are annoying and can sometimes be difficult
+ to reproduce and fix.
+ However, some simple tips and tricks exist that can help
+ you debug and fix them.
+ This section presents a real-world example of an error
+ encountered on the Yocto Project autobuilder and the process
+ used to fix it.
+ <note>
+ If you cannot properly fix a <filename>make</filename> race
+ condition, you can work around it by clearing either the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
+ or
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKEINST'><filename>PARALLEL_MAKEINST</filename></ulink>
+ variables.
+ </note>
+ </para>
+
+ <section id='the-failure'>
+ <title>The Failure</title>
+
+ <para>
+ For this example, assume that you are building an image that
+ depends on the "neard" package.
+ And, during the build, BitBake runs into problems and
+ creates the following output.
+ <note>
+ This example log file has longer lines artificially
+ broken to make the listing easier to read.
+ </note>
+ If you examine the output or the log file, you see the
+ failure during <filename>make</filename>:
+ <literallayout class='monospaced'>
| DEBUG: SITE files ['endian-little', 'bit-32', 'ix86-common', 'common-linux', 'common-glibc', 'i586-linux', 'common']
| DEBUG: Executing shell function do_compile
| NOTE: make -j 16
@@ -10194,61 +13170,62 @@
| make[1]: *** Waiting for unfinished jobs....
| make: *** [all] Error 2
| ERROR: oe_runmake failed
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='reproducing-the-error'>
- <title>Reproducing the Error</title>
+ <section id='reproducing-the-error'>
+ <title>Reproducing the Error</title>
- <para>
- Because race conditions are intermittent, they do not
- manifest themselves every time you do the build.
- In fact, most times the build will complete without problems
- even though the potential race condition exists.
- Thus, once the error surfaces, you need a way to reproduce it.
- </para>
+ <para>
+ Because race conditions are intermittent, they do not
+ manifest themselves every time you do the build.
+ In fact, most times the build will complete without problems
+ even though the potential race condition exists.
+ Thus, once the error surfaces, you need a way to reproduce
+ it.
+ </para>
- <para>
- In this example, compiling the "neard" package is causing the
- problem.
- So the first thing to do is build "neard" locally.
- Before you start the build, set the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
- variable in your <filename>local.conf</filename> file to
- a high number (e.g. "-j 20").
- Using a high value for <filename>PARALLEL_MAKE</filename>
- increases the chances of the race condition showing up:
- <literallayout class='monospaced'>
+ <para>
+ In this example, compiling the "neard" package is causing
+ the problem.
+ So the first thing to do is build "neard" locally.
+ Before you start the build, set the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink>
+ variable in your <filename>local.conf</filename> file to
+ a high number (e.g. "-j 20").
+ Using a high value for <filename>PARALLEL_MAKE</filename>
+ increases the chances of the race condition showing up:
+ <literallayout class='monospaced'>
$ bitbake neard
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- Once the local build for "neard" completes, start a
- <filename>devshell</filename> build:
- <literallayout class='monospaced'>
+ <para>
+ Once the local build for "neard" completes, start a
+ <filename>devshell</filename> build:
+ <literallayout class='monospaced'>
$ bitbake neard -c devshell
- </literallayout>
- For information on how to use a
- <filename>devshell</filename>, see the
- "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
- section.
- </para>
+ </literallayout>
+ For information on how to use a
+ <filename>devshell</filename>, see the
+ "<link linkend='platdev-appdev-devshell'>Using a Development Shell</link>"
+ section.
+ </para>
- <para>
- In the <filename>devshell</filename>, do the following:
- <literallayout class='monospaced'>
+ <para>
+ In the <filename>devshell</filename>, do the following:
+ <literallayout class='monospaced'>
$ make clean
$ make tools/snep-send.o
- </literallayout>
- The <filename>devshell</filename> commands cause the failure
- to clearly be visible.
- In this case, a missing dependency exists for the "neard"
- Makefile target.
- Here is some abbreviated, sample output with the
- missing dependency clearly visible at the end:
- <literallayout class='monospaced'>
+ </literallayout>
+ The <filename>devshell</filename> commands cause the failure
+ to clearly be visible.
+ In this case, a missing dependency exists for the "neard"
+ Makefile target.
+ Here is some abbreviated, sample output with the
+ missing dependency clearly visible at the end:
+ <literallayout class='monospaced'>
i586-poky-linux-gcc -m32 -march=i586 --sysroot=/home/scott-lenovo/......
.
.
@@ -10261,238 +13238,1687 @@
compilation terminated.
make: *** [tools/snep-send.o] Error 1
$
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='creating-a-patch-for-the-fix'>
- <title>Creating a Patch for the Fix</title>
+ <section id='creating-a-patch-for-the-fix'>
+ <title>Creating a Patch for the Fix</title>
- <para>
- Because there is a missing dependency for the Makefile
- target, you need to patch the
- <filename>Makefile.am</filename> file, which is generated
- from <filename>Makefile.in</filename>.
- You can use Quilt to create the patch:
- <literallayout class='monospaced'>
+ <para>
+ Because there is a missing dependency for the Makefile
+ target, you need to patch the
+ <filename>Makefile.am</filename> file, which is generated
+ from <filename>Makefile.in</filename>.
+ You can use Quilt to create the patch:
+ <literallayout class='monospaced'>
$ quilt new parallelmake.patch
Patch patches/parallelmake.patch is now on top
$ quilt add Makefile.am
File Makefile.am added to patch patches/parallelmake.patch
- </literallayout>
- For more information on using Quilt, see the
- "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
- section.
- </para>
+ </literallayout>
+ For more information on using Quilt, see the
+ "<link linkend='using-a-quilt-workflow'>Using Quilt in Your Workflow</link>"
+ section.
+ </para>
- <para>
- At this point you need to make the edits to
- <filename>Makefile.am</filename> to add the missing
- dependency.
- For our example, you have to add the following line
- to the file:
- <literallayout class='monospaced'>
+ <para>
+ At this point you need to make the edits to
+ <filename>Makefile.am</filename> to add the missing
+ dependency.
+ For our example, you have to add the following line
+ to the file:
+ <literallayout class='monospaced'>
tools/snep-send.$(OBJEXT): include/near/dbus.h
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- Once you have edited the file, use the
- <filename>refresh</filename> command to create the patch:
- <literallayout class='monospaced'>
+ <para>
+ Once you have edited the file, use the
+ <filename>refresh</filename> command to create the patch:
+ <literallayout class='monospaced'>
$ quilt refresh
Refreshed patch patches/parallelmake.patch
- </literallayout>
- Once the patch file exists, you need to add it back to the
- originating recipe folder.
- Here is an example assuming a top-level
- <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
- named <filename>poky</filename>:
- <literallayout class='monospaced'>
+ </literallayout>
+ Once the patch file exists, you need to add it back to the
+ originating recipe folder.
+ Here is an example assuming a top-level
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ named <filename>poky</filename>:
+ <literallayout class='monospaced'>
$ cp patches/parallelmake.patch poky/meta/recipes-connectivity/neard/neard
- </literallayout>
- The final thing you need to do to implement the fix in the
- build is to update the "neard" recipe (i.e.
- <filename>neard-0.14.bb</filename>) so that the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
- statement includes the patch file.
- The recipe file is in the folder above the patch.
- Here is what the edited <filename>SRC_URI</filename>
- statement would look like:
- <literallayout class='monospaced'>
+ </literallayout>
+ The final thing you need to do to implement the fix in the
+ build is to update the "neard" recipe (i.e.
+ <filename>neard-0.14.bb</filename>) so that the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+ statement includes the patch file.
+ The recipe file is in the folder above the patch.
+ Here is what the edited <filename>SRC_URI</filename>
+ statement would look like:
+ <literallayout class='monospaced'>
SRC_URI = "${KERNELORG_MIRROR}/linux/network/nfc/${BPN}-${PV}.tar.xz \
file://neard.in \
file://neard.service.in \
file://parallelmake.patch \
"
- </literallayout>
- </para>
+ </literallayout>
+ </para>
- <para>
- With the patch complete and moved to the correct folder and
- the <filename>SRC_URI</filename> statement updated, you can
- exit the <filename>devshell</filename>:
- <literallayout class='monospaced'>
+ <para>
+ With the patch complete and moved to the correct folder and
+ the <filename>SRC_URI</filename> statement updated, you can
+ exit the <filename>devshell</filename>:
+ <literallayout class='monospaced'>
$ exit
- </literallayout>
- </para>
- </section>
+ </literallayout>
+ </para>
+ </section>
- <section id='testing-the-build'>
- <title>Testing the Build</title>
+ <section id='testing-the-build'>
+ <title>Testing the Build</title>
- <para>
- With everything in place, you can get back to trying the
- build again locally:
- <literallayout class='monospaced'>
+ <para>
+ With everything in place, you can get back to trying the
+ build again locally:
+ <literallayout class='monospaced'>
$ bitbake neard
- </literallayout>
- This build should succeed.
- </para>
+ </literallayout>
+ This build should succeed.
+ </para>
- <para>
- Now you can open up a <filename>devshell</filename> again
- and repeat the clean and make operations as follows:
- <literallayout class='monospaced'>
+ <para>
+ Now you can open up a <filename>devshell</filename> again
+ and repeat the clean and make operations as follows:
+ <literallayout class='monospaced'>
$ bitbake neard -c devshell
$ make clean
$ make tools/snep-send.o
- </literallayout>
- The build should work without issue.
+ </literallayout>
+ The build should work without issue.
+ </para>
+
+ <para>
+ As with all solved problems, if they originated upstream,
+ you need to submit the fix for the recipe in OE-Core and
+ upstream so that the problem is taken care of at its
+ source.
+ See the
+ "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
+ section for more information.
+ </para>
+ </section>
+ </section>
+
+ <section id="platdev-gdb-remotedebug">
+ <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
+
+ <para>
+ GDB allows you to examine running programs, which in turn helps
+ you to understand and fix problems.
+ It also allows you to perform post-mortem style analysis of
+ program crashes.
+ GDB is available as a package within the Yocto Project and is
+ installed in SDK images by default.
+ See the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+ chapter in the Yocto Project Reference Manual for a description of
+ these images.
+ You can find information on GDB at
+ <ulink url="http://sourceware.org/gdb/"/>.
+ <note><title>Tip</title>
+ For best results, install debug (<filename>-dbg</filename>)
+ packages for the applications you are going to debug.
+ Doing so makes extra debug symbols available that give you
+ more meaningful output.
+ </note>
</para>
<para>
- As with all solved problems, if they originated upstream, you
- need to submit the fix for the recipe in OE-Core and upstream
- so that the problem is taken care of at its source.
- See the
- "<link linkend='how-to-submit-a-change'>Submitting a Change to the Yocto Project</link>"
- section for more information.
+ Sometimes, due to memory or disk space constraints, it is not
+ possible to use GDB directly on the remote target to debug
+ applications.
+ These constraints arise because GDB needs to load the debugging
+ information and the binaries of the process being debugged.
+ Additionally, GDB needs to perform many computations to locate
+ information such as function names, variable names and values,
+ stack traces and so forth - even before starting the debugging
+ process.
+ These extra computations place more load on the target system
+ and can alter the characteristics of the program being debugged.
+ </para>
+
+ <para>
+ To help get past the previously mentioned constraints, you can
+ use gdbserver, which runs on the remote target and does not
+ load any debugging information from the debugged process.
+ Instead, a GDB instance processes the debugging information that
+ is run on a remote computer - the host GDB.
+ The host GDB then sends control commands to gdbserver to make
+ it stop or start the debugged program, as well as read or write
+ memory regions of that debugged program.
+ All the debugging information loaded and processed as well
+ as all the heavy debugging is done by the host GDB.
+ Offloading these processes gives the gdbserver running on the
+ target a chance to remain small and fast.
+ </para>
+
+ <para>
+ Because the host GDB is responsible for loading the debugging
+ information and for doing the necessary processing to make
+ actual debugging happen, you have to make sure the host can
+ access the unstripped binaries complete with their debugging
+ information and also be sure the target is compiled with no
+ optimizations.
+ The host GDB must also have local access to all the libraries
+ used by the debugged program.
+ Because gdbserver does not need any local debugging information,
+ the binaries on the remote target can remain stripped.
+ However, the binaries must also be compiled without optimization
+ so they match the host's binaries.
+ </para>
+
+ <para>
+ To remain consistent with GDB documentation and terminology,
+ the binary being debugged on the remote target machine is
+ referred to as the "inferior" binary.
+ For documentation on GDB see the
+ <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
+ </para>
+
+ <para>
+ The following steps show you how to debug using the GNU project
+ debugger.
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Configure your build system to construct the
+ companion debug filesystem:</emphasis></para>
+
+ <para>In your <filename>local.conf</filename> file, set
+ the following:
+ <literallayout class='monospaced'>
+ IMAGE_GEN_DEBUGFS = "1"
+ IMAGE_FSTYPES_DEBUGFS = "tar.bz2"
+ </literallayout>
+ These options cause the OpenEmbedded build system
+ to generate a special companion filesystem fragment,
+ which contains the matching source and debug symbols to
+ your deployable filesystem.
+ The build system does this by looking at what is in the
+ deployed filesystem, and pulling the corresponding
+ <filename>-dbg</filename> packages.</para>
+
+ <para>The companion debug filesystem is not a complete
+ filesystem, but only contains the debug fragments.
+ This filesystem must be combined with the full filesystem
+ for debugging.
+ Subsequent steps in this procedure show how to combine
+ the partial filesystem with the full filesystem.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Configure the system to include gdbserver in
+ the target filesystem:</emphasis></para>
+
+ <para>Make the following addition in either your
+ <filename>local.conf</filename> file or in an image
+ recipe:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = “ gdbserver"
+ </literallayout>
+ The change makes sure the <filename>gdbserver</filename>
+ package is included.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Build the environment:</emphasis></para>
+
+ <para>Use the following command to construct the image
+ and the companion Debug Filesystem:
+ <literallayout class='monospaced'>
+ $ bitbake <replaceable>image</replaceable>
+ </literallayout>
+ Build the cross GDB component and make it available
+ for debugging.
+ Build the SDK that matches the image.
+ Building the SDK is best for a production build
+ that can be used later for debugging, especially
+ during long term maintenance:
+ <literallayout class='monospaced'>
+ $ bitbake -c populate_sdk <replaceable>image</replaceable>
+ </literallayout></para>
+
+ <para>Alternatively, you can build the minimal
+ toolchain components that match the target.
+ Doing so creates a smaller than typical SDK and only
+ contains a minimal set of components with which to
+ build simple test applications, as well as run the
+ debugger:
+ <literallayout class='monospaced'>
+ $ bitbake meta-toolchain
+ </literallayout></para>
+
+ <para>A final method is to build Gdb itself within
+ the build system:
+ <literallayout class='monospaced'>
+ $ bitbake gdb-cross-<replaceable>architecture</replaceable>
+ </literallayout>
+ Doing so produces a temporary copy of
+ <filename>cross-gdb</filename> you can use for
+ debugging during development.
+ While this is the quickest approach, the two previous
+ methods in this step are better when considering
+ long-term maintenance strategies.
+ <note>
+ If you run
+ <filename>bitbake gdb-cross</filename>, the
+ OpenEmbedded build system suggests the actual
+ image (e.g. <filename>gdb-cross-i586</filename>).
+ The suggestion is usually the actual name you want
+ to use.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up the</emphasis> <filename>debugfs</filename></para>
+
+ <para>Run the following commands to set up the
+ <filename>debugfs</filename>:
+ <literallayout class='monospaced'>
+ $ mkdir debugfs
+ $ cd debugfs
+ $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>.rootfs.tar.bz2
+ $ tar xvfj <replaceable>build-dir</replaceable>/tmp-glibc/deploy/images/<replaceable>machine</replaceable>/<replaceable>image</replaceable>-dbg.rootfs.tar.bz2
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Set up GDB</emphasis></para>
+
+ <para>Install the SDK (if you built one) and then
+ source the correct environment file.
+ Sourcing the environment file puts the SDK in your
+ <filename>PATH</filename> environment variable.</para>
+
+ <para>If you are using the build system, Gdb is
+ located in
+ <replaceable>build-dir</replaceable>/tmp/sysroots/<replaceable>host</replaceable>/usr/bin/<replaceable>architecture</replaceable>/<replaceable>architecture</replaceable>-gdb
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Boot the target:</emphasis></para>
+
+ <para>For information on how to run QEMU, see the
+ <ulink url='http://wiki.qemu.org/Documentation/GettingStartedDevelopers'>QEMU Documentation</ulink>.
+ <note>
+ Be sure to verify that your host can access the
+ target via TCP.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Debug a program:</emphasis></para>
+
+ <para>Debugging a program involves running gdbserver
+ on the target and then running Gdb on the host.
+ The example in this step debugs
+ <filename>gzip</filename>:
+ <literallayout class='monospaced'>
+ root@qemux86:~# gdbserver localhost:1234 /bin/gzip —help
+ </literallayout>
+ For additional gdbserver options, see the
+ <ulink url='https://www.gnu.org/software/gdb/documentation/'>GDB Server Documentation</ulink>.
+ </para>
+
+ <para>After running gdbserver on the target, you need
+ to run Gdb on the host and configure it and connect to
+ the target.
+ Use these commands:
+ <literallayout class='monospaced'>
+ $ cd <replaceable>directory-holding-the-debugfs-directory</replaceable>
+ $ <replaceable>arch</replaceable>-gdb
+
+ (gdb) set sysroot debugfs
+ (gdb) set substitute-path /usr/src/debug debugfs/usr/src/debug
+ (gdb) target remote <replaceable>IP-of-target</replaceable>:1234
+ </literallayout>
+ At this point, everything should automatically load
+ (i.e. matching binaries, symbols and headers).
+ <note>
+ The Gdb <filename>set</filename> commands in the
+ previous example can be placed into the users
+ <filename>~/.gdbinit</filename> file.
+ Upon starting, Gdb automatically runs whatever
+ commands are in that file.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Deploying without a full image
+ rebuild:</emphasis></para>
+
+ <para>In many cases, during development you want a
+ quick method to deploy a new binary to the target and
+ debug it, without waiting for a full image build.
+ </para>
+
+ <para>One approach to solving this situation is to
+ just build the component you want to debug.
+ Once you have built the component, copy the
+ executable directly to both the target and the
+ host <filename>debugfs</filename>.</para>
+
+ <para>If the binary is processed through the debug
+ splitting in OpenEmbedded, you should also
+ copy the debug items (i.e. <filename>.debug</filename>
+ contents and corresponding
+ <filename>/usr/src/debug</filename> files)
+ from the work directory.
+ Here is an example:
+ <literallayout class='monospaced'>
+ $ bitbake bash
+ $ bitbake -c devshell bash
+ $ cd ..
+ $ scp packages-split/bash/bin/bash <replaceable>target</replaceable>:/bin/bash
+ $ cp -a packages-split/bash-dbg/* <replaceable>path</replaceable>/debugfs
+ </literallayout>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='debugging-with-the-gnu-project-debugger-gdb-on-the-target'>
+ <title>Debugging with the GNU Project Debugger (GDB) on the Target</title>
+
+ <para>
+ The previous section addressed using GDB remotely for debugging
+ purposes, which is the most usual case due to the inherent
+ hardware limitations on many embedded devices.
+ However, debugging in the target hardware itself is also
+ possible with more powerful devices.
+ This section describes what you need to do in order to support
+ using GDB to debug on the target hardware.
+ </para>
+
+ <para>
+ To support this kind of debugging, you need do the following:
+ <itemizedlist>
+ <listitem><para>
+ Ensure that GDB is on the target.
+ You can do this by adding "gdb" to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = " gdb"
+ </literallayout>
+ Alternatively, you can add "tools-debug" to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>:
+ <literallayout class='monospaced'>
+ IMAGE_FEATURES_append = " tools-debug"
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Ensure that debug symbols are present.
+ You can make sure these symbols are present by
+ installing <filename>-dbg</filename>:
+ <literallayout class='monospaced'>
+ IMAGE_INSTALL_append = " <replaceable>packagename</replaceable>-dbg"
+ </literallayout>
+ Alternatively, you can do the following to include all
+ the debug symbols:
+ <literallayout class='monospaced'>
+ IMAGE_FEATURES_append = " dbg-pkgs"
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ <note>
+ To improve the debug information accuracy, you can reduce
+ the level of optimization used by the compiler.
+ For example, when adding the following line to your
+ <filename>local.conf</filename> file, you will reduce
+ optimization from
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-FULL_OPTIMIZATION'><filename>FULL_OPTIMIZATION</filename></ulink>
+ of "-O2" to
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_OPTIMIZATION'><filename>DEBUG_OPTIMIZATION</filename></ulink>
+ of "-O -fno-omit-frame-pointer":
+ <literallayout class='monospaced'>
+ DEBUG_BUILD = "1"
+ </literallayout>
+ Consider that this will reduce the application's performance
+ and is recommended only for debugging purposes.
+ </note>
+ </para>
+ </section>
+
+ <section id='dev-other-debugging-others'>
+ <title>Other Debugging Tips</title>
+
+ <para>
+ Here are some other tips that you might find useful:
+ <itemizedlist>
+ <listitem><para>
+ When adding new packages, it is worth watching for
+ undesirable items making their way into compiler command
+ lines.
+ For example, you do not want references to local system
+ files like
+ <filename>/usr/lib/</filename> or
+ <filename>/usr/include/</filename>.
+ </para></listitem>
+ <listitem><para>
+ If you want to remove the <filename>psplash</filename>
+ boot splashscreen,
+ add <filename>psplash=false</filename> to the kernel
+ command line.
+ Doing so prevents <filename>psplash</filename> from
+ loading and thus allows you to see the console.
+ It is also possible to switch out of the splashscreen by
+ switching the virtual console (e.g. Fn+Left or Fn+Right
+ on a Zaurus).
+ </para></listitem>
+ <listitem><para>
+ Removing
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>
+ (usually <filename>tmp/</filename>, within the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>)
+ can often fix temporary build issues.
+ Removing <filename>TMPDIR</filename> is usually a
+ relatively cheap operation, because task output will be
+ cached in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>
+ (usually <filename>sstate-cache/</filename>, which is
+ also in the Build Directory).
+ <note>
+ Removing <filename>TMPDIR</filename> might be a
+ workaround rather than a fix.
+ Consequently, trying to determine the underlying
+ cause of an issue before removing the directory is
+ a good idea.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ Understanding how a feature is used in practice within
+ existing recipes can be very helpful.
+ It is recommended that you configure some method that
+ allows you to quickly search through files.</para>
+
+ <para>Using GNU Grep, you can use the following shell
+ function to recursively search through common
+ recipe-related files, skipping binary files,
+ <filename>.git</filename> directories, and the
+ Build Directory (assuming its name starts with
+ "build"):
+ <literallayout class='monospaced'>
+ g() {
+ grep -Ir \
+ --exclude-dir=.git \
+ --exclude-dir='build*' \
+ --include='*.bb*' \
+ --include='*.inc*' \
+ --include='*.conf*' \
+ --include='*.py*' \
+ "$@"
+ }
+ </literallayout>
+ Following are some usage examples:
+ <literallayout class='monospaced'>
+ $ g FOO # Search recursively for "FOO"
+ $ g -i foo # Search recursively for "foo", ignoring case
+ $ g -w FOO # Search recursively for "FOO" as a word, ignoring e.g. "FOOBAR"
+ </literallayout>
+ If figuring out how some feature works requires a lot of
+ searching, it might indicate that the documentation
+ should be extended or improved.
+ In such cases, consider filing a documentation bug using
+ the Yocto Project implementation of
+ <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
+ For information on how to submit a bug against
+ the Yocto Project, see the Yocto Project Bugzilla
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>
+ and the
+ "<link linkend='submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</link>"
+ section.
+ <note>
+ The manuals might not be the right place to document
+ variables that are purely internal and have a
+ limited scope (e.g. internal variables used to
+ implement a single <filename>.bbclass</filename>
+ file).
+ </note>
+ </para></listitem>
+ </itemizedlist>
</para>
</section>
</section>
- <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
- <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
+ <section id='making-changes-to-the-yocto-project'>
+ <title>Making Changes to the Yocto Project</title>
<para>
- One of the concerns for a development organization using open source
- software is how to maintain compliance with various open source
- licensing during the lifecycle of the product.
- While this section does not provide legal advice or
- comprehensively cover all scenarios, it does
- present methods that you can use to
- assist you in meeting the compliance requirements during a software
- release.
+ Because the Yocto Project is an open-source, community-based
+ project, you can effect changes to the project.
+ This section presents procedures that show you how to submit
+ a defect against the project and how to submit a change.
</para>
- <para>
- With hundreds of different open source licenses that the Yocto
- Project tracks, it is difficult to know the requirements of each
- and every license.
- However, the requirements of the major FLOSS licenses can begin
- to be covered by
- assuming that three main areas of concern exist:
- <itemizedlist>
- <listitem><para>Source code must be provided.</para></listitem>
- <listitem><para>License text for the software must be
- provided.</para></listitem>
- <listitem><para>Compilation scripts and modifications to the
- source code must be provided.
- </para></listitem>
- </itemizedlist>
- There are other requirements beyond the scope of these
- three and the methods described in this section
- (e.g. the mechanism through which source code is distributed).
- </para>
-
- <para>
- As different organizations have different methods of complying with
- open source licensing, this section is not meant to imply that
- there is only one single way to meet your compliance obligations,
- but rather to describe one method of achieving compliance.
- The remainder of this section describes methods supported to meet the
- previously mentioned three requirements.
- Once you take steps to meet these requirements,
- and prior to releasing images, sources, and the build system,
- you should audit all artifacts to ensure completeness.
- <note>
- The Yocto Project generates a license manifest during
- image creation that is located
- in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename>
- to assist with any audits.
- </note>
- </para>
-
- <section id='providing-the-source-code'>
- <title>Providing the Source Code</title>
+ <section id='submitting-a-defect-against-the-yocto-project'>
+ <title>Submitting a Defect Against the Yocto Project</title>
<para>
- Compliance activities should begin before you generate the
- final image.
- The first thing you should look at is the requirement that
- tops the list for most compliance groups - providing
- the source.
- The Yocto Project has a few ways of meeting this
- requirement.
+ Use the Yocto Project implementation of
+ <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
+ to submit a defect (bug) against the Yocto Project.
+ For additional information on this implementation of Bugzilla see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
+ section in the Yocto Project Reference Manual.
+ For more detail on any of the following steps, see the Yocto Project
+ <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
</para>
<para>
- One of the easiest ways to meet this requirement is
- to provide the entire
- <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
- used by the build.
- This method, however, has a few issues.
- The most obvious is the size of the directory since it includes
- all sources used in the build and not just the source used in
- the released image.
- It will include toolchain source, and other artifacts, which
- you would not generally release.
- However, the more serious issue for most companies is accidental
- release of proprietary software.
- The Yocto Project provides an
- <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
- class to help avoid some of these concerns.
+ Use the following general steps to submit a bug"
+
+ <orderedlist>
+ <listitem><para>
+ Open the Yocto Project implementation of
+ <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
+ </para></listitem>
+ <listitem><para>
+ Click "File a Bug" to enter a new bug.
+ </para></listitem>
+ <listitem><para>
+ Choose the appropriate "Classification", "Product", and
+ "Component" for which the bug was found.
+ Bugs for the Yocto Project fall into one of several
+ classifications, which in turn break down into several
+ products and components.
+ For example, for a bug against the
+ <filename>meta-intel</filename> layer, you would choose
+ "Build System, Metadata & Runtime", "BSPs", and
+ "bsps-meta-intel", respectively.
+ </para></listitem>
+ <listitem><para>
+ Choose the "Version" of the Yocto Project for which you found
+ the bug (e.g. &DISTRO;).
+ </para></listitem>
+ <listitem><para>
+ Determine and select the "Severity" of the bug.
+ The severity indicates how the bug impacted your work.
+ </para></listitem>
+ <listitem><para>
+ Choose the "Hardware" that the bug impacts.
+ </para></listitem>
+ <listitem><para>
+ Choose the "Architecture" that the bug impacts.
+ </para></listitem>
+ <listitem><para>
+ Choose a "Documentation change" item for the bug.
+ Fixing a bug might or might not affect the Yocto Project
+ documentation.
+ If you are unsure of the impact to the documentation, select
+ "Don't Know".
+ </para></listitem>
+ <listitem><para>
+ Provide a brief "Summary" of the bug.
+ Try to limit your summary to just a line or two and be sure
+ to capture the essence of the bug.
+ </para></listitem>
+ <listitem><para>
+ Provide a detailed "Description" of the bug.
+ You should provide as much detail as you can about the context,
+ behavior, output, and so forth that surrounds the bug.
+ You can even attach supporting files for output from logs by
+ using the "Add an attachment" button.
+ </para></listitem>
+ <listitem><para>
+ Click the "Submit Bug" button submit the bug.
+ A new Bugzilla number is assigned to the bug and the defect
+ is logged in the bug tracking system.
+ </para></listitem>
+ </orderedlist>
+ Once you file a bug, the bug is processed by the Yocto Project Bug
+ Triage Team and further details concerning the bug are assigned
+ (e.g. priority and owner).
+ You are the "Submitter" of the bug and any further categorization,
+ progress, or comments on the bug result in Bugzilla sending you an
+ automated email concerning the particular change or progress to the
+ bug.
+ </para>
+ </section>
+
+ <section id='how-to-submit-a-change'>
+ <title>Submitting a Change to the Yocto Project</title>
+
+ <para>
+ Contributions to the Yocto Project and OpenEmbedded are very welcome.
+ Because the system is extremely configurable and flexible, we recognize
+ that developers will want to extend, configure or optimize it for
+ their specific uses.
</para>
<para>
- Before you employ <filename>DL_DIR</filename> or the
- <filename>archiver</filename> class, you need to decide how
- you choose to provide source.
- The source <filename>archiver</filename> class can generate
- tarballs and SRPMs and can create them with various levels of
- compliance in mind.
+ The Yocto Project uses a mailing list and a patch-based workflow
+ that is similar to the Linux kernel but contains important
+ differences.
+ In general, a mailing list exists through which you can submit
+ patches.
+ You should send patches to the appropriate mailing list so that they
+ can be reviewed and merged by the appropriate maintainer.
+ The specific mailing list you need to use depends on the
+ location of the code you are changing.
+ Each component (e.g. layer) should have a
+ <filename>README</filename> file that indicates where to send
+ the changes and which process to follow.
</para>
<para>
- One way of doing this (but certainly not the only way) is to
- release just the source as a tarball.
- You can do this by adding the following to the
- <filename>local.conf</filename> file found in the
- <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ You can send the patch to the mailing list using whichever approach
+ you feel comfortable with to generate the patch.
+ Once sent, the patch is usually reviewed by the community at large.
+ If somebody has concerns with the patch, they will usually voice
+ their concern over the mailing list.
+ If a patch does not receive any negative reviews, the maintainer of
+ the affected layer typically takes the patch, tests it, and then
+ based on successful testing, merges the patch.
+ </para>
+
+ <para id='figuring-out-the-mailing-list-to-use'>
+ The "poky" repository, which is the Yocto Project's reference build
+ environment, is a hybrid repository that contains several
+ individual pieces (e.g. BitBake, Metadata, documentation,
+ and so forth) built using the combo-layer tool.
+ The upstream location used for submitting changes varies by
+ component:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Core Metadata:</emphasis>
+ Send your patch to the
+ <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
+ mailing list. For example, a change to anything under
+ the <filename>meta</filename> or
+ <filename>scripts</filename> directories should be sent
+ to this mailing list.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>BitBake:</emphasis>
+ For changes to BitBake (i.e. anything under the
+ <filename>bitbake</filename> directory), send your patch
+ to the
+ <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
+ mailing list.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>"meta-*" trees:</emphasis>
+ These trees contain Metadata.
+ Use the
+ <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
+ mailing list.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+
+ <para>
+ For changes to other layers hosted in the Yocto Project source
+ repositories (i.e. <filename>yoctoproject.org</filename>), tools,
+ and the Yocto Project documentation, use the
+ <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
+ general mailing list.
+ <note>
+ Sometimes a layer's documentation specifies to use a
+ particular mailing list.
+ If so, use that list.
+ </note>
+ For additional recipes that do not fit into the core Metadata, you
+ should determine which layer the recipe should go into and submit
+ the change in the manner recommended by the documentation (e.g.
+ the <filename>README</filename> file) supplied with the layer.
+ If in doubt, please ask on the Yocto general mailing list or on
+ the openembedded-devel mailing list.
+ </para>
+
+ <para>
+ You can also push a change upstream and request a maintainer to
+ pull the change into the component's upstream repository.
+ You do this by pushing to a contribution repository that is upstream.
+ See the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#gs-git-workflows-and-the-yocto-project'>Git Workflows and the Yocto Project</ulink>"
+ section in the Yocto Project Overview and Concepts Manual for additional
+ concepts on working in the Yocto Project development environment.
+ </para>
+
+ <para>
+ Two commonly used testing repositories exist for
+ OpenEmbedded-Core:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>"ross/mut" branch:</emphasis>
+ The "mut" (master-under-test) tree
+ exists in the <filename>poky-contrib</filename> repository
+ in the
+ <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>"master-next" branch:</emphasis>
+ This branch is part of the main
+ "poky" repository in the Yocto Project source repositories.
+ </para></listitem>
+ </itemizedlist>
+ Maintainers use these branches to test submissions prior to merging
+ patches.
+ Thus, you can get an idea of the status of a patch based on
+ whether the patch has been merged into one of these branches.
+ <note>
+ This system is imperfect and changes can sometimes get lost in the
+ flow.
+ Asking about the status of a patch or change is reasonable if the
+ change has been idle for a while with no feedback.
+ The Yocto Project does have plans to use
+ <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
+ to track the status of patches and also to automatically preview
+ patches.
+ </note>
+ </para>
+
+ <para>
+ The following sections provide procedures for submitting a change.
+ </para>
+
+ <section id='pushing-a-change-upstream'>
+ <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
+
+ <para>
+ Follow this procedure to push a change to an upstream "contrib"
+ Git repository:
+ <note>
+ You can find general Git information on how to push a change
+ upstream in the
+ <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
+ </note>
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Make Your Changes Locally:</emphasis>
+ Make your changes in your local Git repository.
+ You should make small, controlled, isolated changes.
+ Keeping changes small and isolated aids review,
+ makes merging/rebasing easier and keeps the change
+ history clean should anyone need to refer to it in
+ future.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Stage Your Changes:</emphasis>
+ Stage your changes by using the <filename>git add</filename>
+ command on each file you changed.
+ </para></listitem>
+ <listitem><para id='making-sure-you-have-correct-commit-information'>
+ <emphasis>Commit Your Changes:</emphasis>
+ Commit the change by using the
+ <filename>git commit</filename> command.
+ Make sure your commit information follows standards by
+ following these accepted conventions:
+ <itemizedlist>
+ <listitem><para>
+ Be sure to include a "Signed-off-by:" line in the
+ same style as required by the Linux kernel.
+ Adding this line signifies that you, the submitter,
+ have agreed to the Developer's Certificate of
+ Origin 1.1 as follows:
+ <literallayout class='monospaced'>
+ Developer's Certificate of Origin 1.1
+
+ By making a contribution to this project, I certify that:
+
+ (a) The contribution was created in whole or in part by me and I
+ have the right to submit it under the open source license
+ indicated in the file; or
+
+ (b) The contribution is based upon previous work that, to the best
+ of my knowledge, is covered under an appropriate open source
+ license and I have the right under that license to submit that
+ work with modifications, whether created in whole or in part
+ by me, under the same open source license (unless I am
+ permitted to submit under a different license), as indicated
+ in the file; or
+
+ (c) The contribution was provided directly to me by some other
+ person who certified (a), (b) or (c) and I have not modified
+ it.
+
+ (d) I understand and agree that this project and the contribution
+ are public and that a record of the contribution (including all
+ personal information I submit with it, including my sign-off) is
+ maintained indefinitely and may be redistributed consistent with
+ this project or the open source license(s) involved.
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Provide a single-line summary of the change.
+ and,
+ if more explanation is needed, provide more
+ detail in the body of the commit.
+ This summary is typically viewable in the
+ "shortlist" of changes.
+ Thus, providing something short and descriptive
+ that gives the reader a summary of the change is
+ useful when viewing a list of many commits.
+ You should prefix this short description with the
+ recipe name (if changing a recipe), or else with
+ the short form path to the file being changed.
+ </para></listitem>
+ <listitem><para>
+ For the body of the commit message, provide
+ detailed information that describes what you
+ changed, why you made the change, and the approach
+ you used.
+ It might also be helpful if you mention how you
+ tested the change.
+ Provide as much detail as you can in the body of
+ the commit message.
+ <note>
+ You do not need to provide a more detailed
+ explanation of a change if the change is
+ minor to the point of the single line
+ summary providing all the information.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ If the change addresses a specific bug or issue
+ that is associated with a bug-tracking ID,
+ include a reference to that ID in your detailed
+ description.
+ For example, the Yocto Project uses a specific
+ convention for bug references - any commit that
+ addresses a specific bug should use the following
+ form for the detailed description.
+ Be sure to use the actual bug-tracking ID from
+ Bugzilla for
+ <replaceable>bug-id</replaceable>:
+ <literallayout class='monospaced'>
+ Fixes [YOCTO #<replaceable>bug-id</replaceable>]
+
+ <replaceable>detailed description of change</replaceable>
+ </literallayout>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
+ If you have arranged for permissions to push to an
+ upstream contrib repository, push the change to that
+ repository:
+ <literallayout class='monospaced'>
+ $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
+ </literallayout>
+ For example, suppose you have permissions to push into the
+ upstream <filename>meta-intel-contrib</filename>
+ repository and you are working in a local branch named
+ <replaceable>your_name</replaceable><filename>/README</filename>.
+ The following command pushes your local commits to the
+ <filename>meta-intel-contrib</filename> upstream
+ repository and puts the commit in a branch named
+ <replaceable>your_name</replaceable><filename>/README</filename>:
+ <literallayout class='monospaced'>
+ $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
+ </literallayout>
+ </para></listitem>
+ <listitem><para id='push-determine-who-to-notify'>
+ <emphasis>Determine Who to Notify:</emphasis>
+ Determine the maintainer or the mailing list
+ that you need to notify for the change.</para>
+
+ <para>Before submitting any change, you need to be sure
+ who the maintainer is or what mailing list that you need
+ to notify.
+ Use either these methods to find out:
+ <itemizedlist>
+ <listitem><para>
+ <emphasis>Maintenance File:</emphasis>
+ Examine the <filename>maintainers.inc</filename>
+ file, which is located in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ at
+ <filename>meta/conf/distro/include</filename>,
+ to see who is responsible for code.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Search by File:</emphasis>
+ Using <ulink url='&YOCTO_DOCS_OM_URL;#git'>Git</ulink>,
+ you can enter the following command to bring up a
+ short list of all commits against a specific file:
+ <literallayout class='monospaced'>
+ git shortlog -- <replaceable>filename</replaceable>
+ </literallayout>
+ Just provide the name of the file for which you
+ are interested.
+ The information returned is not ordered by history
+ but does include a list of everyone who has
+ committed grouped by name.
+ From the list, you can see who is responsible for
+ the bulk of the changes against the file.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Examine the List of Mailing Lists:</emphasis>
+ For a list of the Yocto Project and related mailing
+ lists, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Make a Pull Request:</emphasis>
+ Notify the maintainer or the mailing list that you have
+ pushed a change by making a pull request.</para>
+
+ <para>The Yocto Project provides two scripts that
+ conveniently let you generate and send pull requests to the
+ Yocto Project.
+ These scripts are <filename>create-pull-request</filename>
+ and <filename>send-pull-request</filename>.
+ You can find these scripts in the
+ <filename>scripts</filename> directory within the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
+ (e.g. <filename>~/poky/scripts</filename>).
+ </para>
+
+ <para>Using these scripts correctly formats the requests
+ without introducing any whitespace or HTML formatting.
+ The maintainer that receives your patches either directly
+ or through the mailing list needs to be able to save and
+ apply them directly from your emails.
+ Using these scripts is the preferred method for sending
+ patches.</para>
+
+ <para>First, create the pull request.
+ For example, the following command runs the script,
+ specifies the upstream repository in the contrib directory
+ into which you pushed the change, and provides a subject
+ line in the created patch files:
+ <literallayout class='monospaced'>
+ $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
+ </literallayout>
+ Running this script forms
+ <filename>*.patch</filename> files in a folder named
+ <filename>pull-</filename><replaceable>PID</replaceable>
+ in the current directory.
+ One of the patch files is a cover letter.</para>
+
+ <para>Before running the
+ <filename>send-pull-request</filename> script, you must
+ edit the cover letter patch to insert information about
+ your change.
+ After editing the cover letter, send the pull request.
+ For example, the following command runs the script and
+ specifies the patch directory and email address.
+ In this example, the email address is a mailing list:
+ <literallayout class='monospaced'>
+ $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
+ </literallayout>
+ You need to follow the prompts as the script is
+ interactive.
+ <note>
+ For help on using these scripts, simply provide the
+ <filename>-h</filename> argument as follows:
+ <literallayout class='monospaced'>
+ $ poky/scripts/create-pull-request -h
+ $ poky/scripts/send-pull-request -h
+ </literallayout>
+ </note>
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+
+ <section id='submitting-a-patch'>
+ <title>Using Email to Submit a Patch</title>
+
+ <para>
+ You can submit patches without using the
+ <filename>create-pull-request</filename> and
+ <filename>send-pull-request</filename> scripts described in the
+ previous section.
+ However, keep in mind, the preferred method is to use the scripts.
+ </para>
+
+ <para>
+ Depending on the components changed, you need to submit the email
+ to a specific mailing list.
+ For some guidance on which mailing list to use, see the
+ <link linkend='figuring-out-the-mailing-list-to-use'>list</link>
+ at the beginning of this section.
+ For a description of all the available mailing lists, see the
+ "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+ section in the Yocto Project Reference Manual.
+ </para>
+
+ <para>
+ Here is the general procedure on how to submit a patch through
+ email without using the scripts:
+ <orderedlist>
+ <listitem><para>
+ <emphasis>Make Your Changes Locally:</emphasis>
+ Make your changes in your local Git repository.
+ You should make small, controlled, isolated changes.
+ Keeping changes small and isolated aids review,
+ makes merging/rebasing easier and keeps the change
+ history clean should anyone need to refer to it in
+ future.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Stage Your Changes:</emphasis>
+ Stage your changes by using the <filename>git add</filename>
+ command on each file you changed.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Commit Your Changes:</emphasis>
+ Commit the change by using the
+ <filename>git commit --signoff</filename> command.
+ Using the <filename>--signoff</filename> option identifies
+ you as the person making the change and also satisfies
+ the Developer's Certificate of Origin (DCO) shown earlier.
+ </para>
+
+ <para>When you form a commit, you must follow certain
+ standards established by the Yocto Project development
+ team.
+ See
+ <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
+ in the previous section for information on how to
+ provide commit information that meets Yocto Project
+ commit message standards.
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Format the Commit:</emphasis>
+ Format the commit into an email message.
+ To format commits, use the
+ <filename>git format-patch</filename> command.
+ When you provide the command, you must include a revision
+ list or a number of patches as part of the command.
+ For example, either of these two commands takes your most
+ recent single commit and formats it as an email message in
+ the current directory:
+ <literallayout class='monospaced'>
+ $ git format-patch -1
+ </literallayout>
+ or
+ <literallayout class='monospaced'>
+ $ git format-patch HEAD~
+ </literallayout></para>
+
+ <para>After the command is run, the current directory
+ contains a numbered <filename>.patch</filename> file for
+ the commit.</para>
+
+ <para>If you provide several commits as part of the
+ command, the <filename>git format-patch</filename> command
+ produces a series of numbered files in the current
+ directory – one for each commit.
+ If you have more than one patch, you should also use the
+ <filename>--cover</filename> option with the command,
+ which generates a cover letter as the first "patch" in
+ the series.
+ You can then edit the cover letter to provide a
+ description for the series of patches.
+ For information on the
+ <filename>git format-patch</filename> command,
+ see <filename>GIT_FORMAT_PATCH(1)</filename> displayed
+ using the <filename>man git-format-patch</filename>
+ command.
+ <note>
+ If you are or will be a frequent contributor to the
+ Yocto Project or to OpenEmbedded, you might consider
+ requesting a contrib area and the necessary associated
+ rights.
+ </note>
+ </para></listitem>
+ <listitem><para>
+ <emphasis>Import the Files Into Your Mail Client:</emphasis>
+ Import the files into your mail client by using the
+ <filename>git send-email</filename> command.
+ <note>
+ In order to use <filename>git send-email</filename>,
+ you must have the proper Git packages installed on
+ your host.
+ For Ubuntu, Debian, and Fedora the package is
+ <filename>git-email</filename>.
+ </note></para>
+
+ <para>The <filename>git send-email</filename> command
+ sends email by using a local or remote Mail Transport Agent
+ (MTA) such as <filename>msmtp</filename>,
+ <filename>sendmail</filename>, or through a direct
+ <filename>smtp</filename> configuration in your Git
+ <filename>~/.gitconfig</filename> file.
+ If you are submitting patches through email only, it is
+ very important that you submit them without any whitespace
+ or HTML formatting that either you or your mailer
+ introduces.
+ The maintainer that receives your patches needs to be able
+ to save and apply them directly from your emails.
+ A good way to verify that what you are sending will be
+ applicable by the maintainer is to do a dry run and send
+ them to yourself and then save and apply them as the
+ maintainer would.</para>
+
+ <para>The <filename>git send-email</filename> command is
+ the preferred method for sending your patches using
+ email since there is no risk of compromising whitespace
+ in the body of the message, which can occur when you use
+ your own mail client.
+ The command also has several options that let you
+ specify recipients and perform further editing of the
+ email message.
+ For information on how to use the
+ <filename>git send-email</filename> command,
+ see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
+ the <filename>man git-send-email</filename> command.
+ </para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
+ </section>
+
+ <section id='working-with-licenses'>
+ <title>Working With Licenses</title>
+
+ <para>
+ As mentioned in the
+ "<ulink url='&YOCTO_DOCS_OM_URL;#licensing'>Licensing</ulink>"
+ section in the Yocto Project Overview and Concepts Manual,
+ open source projects are open to the public and they
+ consequently have different licensing structures in place.
+ This section describes the mechanism by which the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink>
+ tracks changes to licensing text and covers how to maintain open
+ source license compliance during your project's lifecycle.
+ The section also describes how to enable commercially licensed
+ recipes, which by default are disabled.
+ </para>
+
+ <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
+ <title>Tracking License Changes</title>
+
+ <para>
+ The license of an upstream project might change in the future.
+ In order to prevent these changes going unnoticed, the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></ulink>
+ variable tracks changes to the license text. The checksums are
+ validated at the end of the configure step, and if the
+ checksums do not match, the build will fail.
+ </para>
+
+ <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
+ <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
+
+ <para>
+ The <filename>LIC_FILES_CHKSUM</filename>
+ variable contains checksums of the license text in the
+ source code for the recipe.
+ Following is an example of how to specify
+ <filename>LIC_FILES_CHKSUM</filename>:
+ <literallayout class='monospaced'>
+ LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
+ file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
+ file://licfile2.txt;endline=50;md5=zzzz \
+ ..."
+ </literallayout>
+ <note><title>Notes</title>
+ <itemizedlist>
+ <listitem><para>
+ When using "beginline" and "endline", realize
+ that line numbering begins with one and not
+ zero.
+ Also, the included lines are inclusive (i.e.
+ lines five through and including 29 in the
+ previous example for
+ <filename>licfile1.txt</filename>).
+ </para></listitem>
+ <listitem><para>
+ When a license check fails, the selected license
+ text is included as part of the QA message.
+ Using this output, you can determine the exact
+ start and finish for the needed license text.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+
+ <para>
+ The build system uses the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+ variable as the default directory when searching files
+ listed in <filename>LIC_FILES_CHKSUM</filename>.
+ The previous example employs the default directory.
+ </para>
+
+ <para>
+ Consider this next example:
+ <literallayout class='monospaced'>
+ LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
+ md5=bb14ed3c4cda583abc85401304b5cd4e"
+ LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
+ </literallayout>
+ </para>
+
+ <para>
+ The first line locates a file in
+ <filename>${S}/src/ls.c</filename> and isolates lines five
+ through 16 as license text.
+ The second line refers to a file in
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>.
+ </para>
+
+ <para>
+ Note that <filename>LIC_FILES_CHKSUM</filename> variable is
+ mandatory for all recipes, unless the
+ <filename>LICENSE</filename> variable is set to "CLOSED".
+ </para>
+ </section>
+
+ <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
+ <title>Explanation of Syntax</title>
+
+ <para>
+ As mentioned in the previous section, the
+ <filename>LIC_FILES_CHKSUM</filename> variable lists all
+ the important files that contain the license text for the
+ source code.
+ It is possible to specify a checksum for an entire file,
+ or a specific section of a file (specified by beginning and
+ ending line numbers with the "beginline" and "endline"
+ parameters, respectively).
+ The latter is useful for source files with a license
+ notice header, README documents, and so forth.
+ If you do not use the "beginline" parameter, then it is
+ assumed that the text begins on the first line of the file.
+ Similarly, if you do not use the "endline" parameter,
+ it is assumed that the license text ends with the last
+ line of the file.
+ </para>
+
+ <para>
+ The "md5" parameter stores the md5 checksum of the license
+ text.
+ If the license text changes in any way as compared to
+ this parameter then a mismatch occurs.
+ This mismatch triggers a build failure and notifies
+ the developer.
+ Notification allows the developer to review and address
+ the license text changes.
+ Also note that if a mismatch occurs during the build,
+ the correct md5 checksum is placed in the build log and
+ can be easily copied to the recipe.
+ </para>
+
+ <para>
+ There is no limit to how many files you can specify using
+ the <filename>LIC_FILES_CHKSUM</filename> variable.
+ Generally, however, every project requires a few
+ specifications for license tracking.
+ Many projects have a "COPYING" file that stores the
+ license information for all the source code files.
+ This practice allows you to just track the "COPYING"
+ file as long as it is kept up to date.
+ <note><title>Tips</title>
+ <itemizedlist>
+ <listitem><para>
+ If you specify an empty or invalid "md5"
+ parameter,
+ <ulink url='&YOCTO_DOCS_REF_URL;#bitbake-term'>BitBake</ulink>
+ returns an md5 mis-match
+ error and displays the correct "md5" parameter
+ value during the build.
+ The correct parameter is also captured in
+ the build log.
+ </para></listitem>
+ <listitem><para>
+ If the whole file contains only license text,
+ you do not need to use the "beginline" and
+ "endline" parameters.
+ </para></listitem>
+ </itemizedlist>
+ </note>
+ </para>
+ </section>
+ </section>
+
+ <section id="enabling-commercially-licensed-recipes">
+ <title>Enabling Commercially Licensed Recipes</title>
+
+ <para>
+ By default, the OpenEmbedded build system disables
+ components that have commercial or other special licensing
+ requirements.
+ Such requirements are defined on a
+ recipe-by-recipe basis through the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS'><filename>LICENSE_FLAGS</filename></ulink>
+ variable definition in the affected recipe.
+ For instance, the
+ <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ recipe contains the following statement:
<literallayout class='monospaced'>
+ LICENSE_FLAGS = "commercial"
+ </literallayout>
+ Here is a slightly more complicated example that contains both
+ an explicit recipe name and version (after variable expansion):
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS = "license_${PN}_${PV}"
+ </literallayout>
+ In order for a component restricted by a
+ <filename>LICENSE_FLAGS</filename> definition to be enabled and
+ included in an image, it needs to have a matching entry in the
+ global
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_FLAGS_WHITELIST'><filename>LICENSE_FLAGS_WHITELIST</filename></ulink>
+ variable, which is a variable typically defined in your
+ <filename>local.conf</filename> file.
+ For example, to enable the
+ <filename>poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+ package, you could add either the string
+ "commercial_gst-plugins-ugly" or the more general string
+ "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
+ See the
+ "<link linkend='license-flag-matching'>License Flag Matching</link>"
+ section for a full
+ explanation of how <filename>LICENSE_FLAGS</filename> matching
+ works.
+ Here is the example:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
+ </literallayout>
+ Likewise, to additionally enable the package built from the
+ recipe containing
+ <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>,
+ and assuming that the actual recipe name was
+ <filename>emgd_1.10.bb</filename>, the following string would
+ enable that package as well as the original
+ <filename>gst-plugins-ugly</filename> package:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
+ </literallayout>
+ As a convenience, you do not need to specify the complete
+ license string in the whitelist for every package.
+ You can use an abbreviated form, which consists
+ of just the first portion or portions of the license
+ string before the initial underscore character or characters.
+ A partial string will match any license that contains the
+ given string as the first portion of its license.
+ For example, the following whitelist string will also match
+ both of the packages previously mentioned as well as any other
+ packages that have licenses starting with "commercial" or
+ "license".
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial license"
+ </literallayout>
+ </para>
+
+ <section id="license-flag-matching">
+ <title>License Flag Matching</title>
+
+ <para>
+ License flag matching allows you to control what recipes
+ the OpenEmbedded build system includes in the build.
+ Fundamentally, the build system attempts to match
+ <filename>LICENSE_FLAGS</filename> strings found in recipes
+ against <filename>LICENSE_FLAGS_WHITELIST</filename>
+ strings found in the whitelist.
+ A match causes the build system to include a recipe in the
+ build, while failure to find a match causes the build
+ system to exclude a recipe.
+ </para>
+
+ <para>
+ In general, license flag matching is simple.
+ However, understanding some concepts will help you
+ correctly and effectively use matching.
+ </para>
+
+ <para>
+ Before a flag
+ defined by a particular recipe is tested against the
+ contents of the whitelist, the expanded string
+ <filename>_${PN}</filename> is appended to the flag.
+ This expansion makes each
+ <filename>LICENSE_FLAGS</filename> value recipe-specific.
+ After expansion, the string is then matched against the
+ whitelist.
+ Thus, specifying
+ <filename>LICENSE_FLAGS = "commercial"</filename>
+ in recipe "foo", for example, results in the string
+ <filename>"commercial_foo"</filename>.
+ And, to create a match, that string must appear in the
+ whitelist.
+ </para>
+
+ <para>
+ Judicious use of the <filename>LICENSE_FLAGS</filename>
+ strings and the contents of the
+ <filename>LICENSE_FLAGS_WHITELIST</filename> variable
+ allows you a lot of flexibility for including or excluding
+ recipes based on licensing.
+ For example, you can broaden the matching capabilities by
+ using license flags string subsets in the whitelist.
+ <note>
+ When using a string subset, be sure to use the part of
+ the expanded string that precedes the appended
+ underscore character (e.g.
+ <filename>usethispart_1.3</filename>,
+ <filename>usethispart_1.4</filename>, and so forth).
+ </note>
+ For example, simply specifying the string "commercial" in
+ the whitelist matches any expanded
+ <filename>LICENSE_FLAGS</filename> definition that starts
+ with the string "commercial" such as "commercial_foo" and
+ "commercial_bar", which are the strings the build system
+ automatically generates for hypothetical recipes named
+ "foo" and "bar" assuming those recipes simply specify the
+ following:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS = "commercial"
+ </literallayout>
+ Thus, you can choose to exhaustively
+ enumerate each license flag in the whitelist and
+ allow only specific recipes into the image, or
+ you can use a string subset that causes a broader range of
+ matches to allow a range of recipes into the image.
+ </para>
+
+ <para>
+ This scheme works even if the
+ <filename>LICENSE_FLAGS</filename> string already
+ has <filename>_${PN}</filename> appended.
+ For example, the build system turns the license flag
+ "commercial_1.2_foo" into "commercial_1.2_foo_foo" and
+ would match both the general "commercial" and the specific
+ "commercial_1.2_foo" strings found in the whitelist, as
+ expected.
+ </para>
+
+ <para>
+ Here are some other scenarios:
+ <itemizedlist>
+ <listitem><para>
+ You can specify a versioned string in the recipe
+ such as "commercial_foo_1.2" in a "foo" recipe.
+ The build system expands this string to
+ "commercial_foo_1.2_foo".
+ Combine this license flag with a whitelist that has
+ the string "commercial" and you match the flag
+ along with any other flag that starts with the
+ string "commercial".
+ </para></listitem>
+ <listitem><para>
+ Under the same circumstances, you can use
+ "commercial_foo" in the whitelist and the build
+ system not only matches "commercial_foo_1.2" but
+ also matches any license flag with the string
+ "commercial_foo", regardless of the version.
+ </para></listitem>
+ <listitem><para>
+ You can be very specific and use both the
+ package and version parts in the whitelist (e.g.
+ "commercial_foo_1.2") to specifically match a
+ versioned recipe.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
+ <section id="other-variables-related-to-commercial-licenses">
+ <title>Other Variables Related to Commercial Licenses</title>
+
+ <para>
+ Other helpful variables related to commercial
+ license handling exist and are defined in the
+ <filename>poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
+ <literallayout class='monospaced'>
+ COMMERCIAL_AUDIO_PLUGINS ?= ""
+ COMMERCIAL_VIDEO_PLUGINS ?= ""
+ </literallayout>
+ If you want to enable these components, you can do so by
+ making sure you have statements similar to the following
+ in your <filename>local.conf</filename> configuration file:
+ <literallayout class='monospaced'>
+ COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
+ gst-plugins-ugly-mpegaudioparse"
+ COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
+ gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
+ LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
+ </literallayout>
+ Of course, you could also create a matching whitelist
+ for those components using the more general "commercial"
+ in the whitelist, but that would also enable all the
+ other packages with <filename>LICENSE_FLAGS</filename>
+ containing "commercial", which you may or may not want:
+ <literallayout class='monospaced'>
+ LICENSE_FLAGS_WHITELIST = "commercial"
+ </literallayout>
+ </para>
+
+ <para>
+ Specifying audio and video plug-ins as part of the
+ <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
+ <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
+ (along with the enabling
+ <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
+ plug-ins or components into built images, thus adding
+ support for media formats or components.
+ </para>
+ </section>
+ </section>
+
+ <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
+ <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
+
+ <para>
+ One of the concerns for a development organization using open source
+ software is how to maintain compliance with various open source
+ licensing during the lifecycle of the product.
+ While this section does not provide legal advice or
+ comprehensively cover all scenarios, it does
+ present methods that you can use to
+ assist you in meeting the compliance requirements during a software
+ release.
+ </para>
+
+ <para>
+ With hundreds of different open source licenses that the Yocto
+ Project tracks, it is difficult to know the requirements of each
+ and every license.
+ However, the requirements of the major FLOSS licenses can begin
+ to be covered by
+ assuming that three main areas of concern exist:
+ <itemizedlist>
+ <listitem><para>Source code must be provided.</para></listitem>
+ <listitem><para>License text for the software must be
+ provided.</para></listitem>
+ <listitem><para>Compilation scripts and modifications to the
+ source code must be provided.
+ </para></listitem>
+ </itemizedlist>
+ There are other requirements beyond the scope of these
+ three and the methods described in this section
+ (e.g. the mechanism through which source code is distributed).
+ </para>
+
+ <para>
+ As different organizations have different methods of complying with
+ open source licensing, this section is not meant to imply that
+ there is only one single way to meet your compliance obligations,
+ but rather to describe one method of achieving compliance.
+ The remainder of this section describes methods supported to meet the
+ previously mentioned three requirements.
+ Once you take steps to meet these requirements,
+ and prior to releasing images, sources, and the build system,
+ you should audit all artifacts to ensure completeness.
+ <note>
+ The Yocto Project generates a license manifest during
+ image creation that is located
+ in <filename>${DEPLOY_DIR}/licenses/<replaceable>image_name-datestamp</replaceable></filename>
+ to assist with any audits.
+ </note>
+ </para>
+
+ <section id='providing-the-source-code'>
+ <title>Providing the Source Code</title>
+
+ <para>
+ Compliance activities should begin before you generate the
+ final image.
+ The first thing you should look at is the requirement that
+ tops the list for most compliance groups - providing
+ the source.
+ The Yocto Project has a few ways of meeting this
+ requirement.
+ </para>
+
+ <para>
+ One of the easiest ways to meet this requirement is
+ to provide the entire
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+ used by the build.
+ This method, however, has a few issues.
+ The most obvious is the size of the directory since it includes
+ all sources used in the build and not just the source used in
+ the released image.
+ It will include toolchain source, and other artifacts, which
+ you would not generally release.
+ However, the more serious issue for most companies is accidental
+ release of proprietary software.
+ The Yocto Project provides an
+ <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'><filename>archiver</filename></ulink>
+ class to help avoid some of these concerns.
+ </para>
+
+ <para>
+ Before you employ <filename>DL_DIR</filename> or the
+ <filename>archiver</filename> class, you need to decide how
+ you choose to provide source.
+ The source <filename>archiver</filename> class can generate
+ tarballs and SRPMs and can create them with various levels of
+ compliance in mind.
+ </para>
+
+ <para>
+ One way of doing this (but certainly not the only way) is to
+ release just the source as a tarball.
+ You can do this by adding the following to the
+ <filename>local.conf</filename> file found in the
+ <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>:
+ <literallayout class='monospaced'>
INHERIT += "archiver"
ARCHIVER_MODE[src] = "original"
- </literallayout>
- During the creation of your image, the source from all
- recipes that deploy packages to the image is placed within
- subdirectories of
- <filename>DEPLOY_DIR/sources</filename> based on the
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
- for each recipe.
- Releasing the entire directory enables you to comply with
- requirements concerning providing the unmodified source.
- It is important to note that the size of the directory can
- get large.
- </para>
+ </literallayout>
+ During the creation of your image, the source from all
+ recipes that deploy packages to the image is placed within
+ subdirectories of
+ <filename>DEPLOY_DIR/sources</filename> based on the
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
+ for each recipe.
+ Releasing the entire directory enables you to comply with
+ requirements concerning providing the unmodified source.
+ It is important to note that the size of the directory can
+ get large.
+ </para>
- <para>
- A way to help mitigate the size issue is to only release
- tarballs for licenses that require the release of
- source.
- Let us assume you are only concerned with GPL code as
- identified by running the following script:
- <literallayout class='monospaced'>
+ <para>
+ A way to help mitigate the size issue is to only release
+ tarballs for licenses that require the release of
+ source.
+ Let us assume you are only concerned with GPL code as
+ identified by running the following script:
+ <literallayout class='monospaced'>
# Script to archive a subset of packages matching specific license(s)
# Source and license files are copied into sub folders of package folder
# Must be run from build folder
@@ -10515,96 +14941,97 @@
cp tmp/deploy/licenses/$p/* $src_release_dir/$p/license 2> /dev/null
fi
done
- done </literallayout>
- At this point, you could create a tarball from the
- <filename>gpl_source_release</filename> directory and
- provide that to the end user.
- This method would be a step toward achieving compliance
- with section 3a of GPLv2 and with section 6 of GPLv3.
- </para>
- </section>
+ done
+ </literallayout>
+ At this point, you could create a tarball from the
+ <filename>gpl_source_release</filename> directory and
+ provide that to the end user.
+ This method would be a step toward achieving compliance
+ with section 3a of GPLv2 and with section 6 of GPLv3.
+ </para>
+ </section>
- <section id='providing-license-text'>
- <title>Providing License Text</title>
+ <section id='providing-license-text'>
+ <title>Providing License Text</title>
- <para>
- One requirement that is often overlooked is inclusion
- of license text.
- This requirement also needs to be dealt with prior to
- generating the final image.
- Some licenses require the license text to accompany
- the binary.
- You can achieve this by adding the following to your
- <filename>local.conf</filename> file:
- <literallayout class='monospaced'>
+ <para>
+ One requirement that is often overlooked is inclusion
+ of license text.
+ This requirement also needs to be dealt with prior to
+ generating the final image.
+ Some licenses require the license text to accompany
+ the binary.
+ You can achieve this by adding the following to your
+ <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
COPY_LIC_MANIFEST = "1"
COPY_LIC_DIRS = "1"
LICENSE_CREATE_PACKAGE = "1"
- </literallayout>
- Adding these statements to the configuration file ensures
- that the licenses collected during package generation
- are included on your image.
- <note>
- <para>Setting all three variables to "1" results in the
- image having two copies of the same license file.
- One copy resides in
- <filename>/usr/share/common-licenses</filename> and
- the other resides in
- <filename>/usr/share/license</filename>.</para>
+ </literallayout>
+ Adding these statements to the configuration file ensures
+ that the licenses collected during package generation
+ are included on your image.
+ <note>
+ <para>Setting all three variables to "1" results in the
+ image having two copies of the same license file.
+ One copy resides in
+ <filename>/usr/share/common-licenses</filename> and
+ the other resides in
+ <filename>/usr/share/license</filename>.</para>
- <para>The reason for this behavior is because
- <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink>
- and
- <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink>
- add a copy of the license when the image is built but do
- not offer a path for adding licenses for newly installed
- packages to an image.
- <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink>
- adds a separate package and an upgrade path for adding
- licenses to an image.</para>
- </note>
- </para>
+ <para>The reason for this behavior is because
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_DIRS'><filename>COPY_LIC_DIRS</filename></ulink>
+ and
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-COPY_LIC_MANIFEST'><filename>COPY_LIC_MANIFEST</filename></ulink>
+ add a copy of the license when the image is built but do
+ not offer a path for adding licenses for newly installed
+ packages to an image.
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE_CREATE_PACKAGE'><filename>LICENSE_CREATE_PACKAGE</filename></ulink>
+ adds a separate package and an upgrade path for adding
+ licenses to an image.</para>
+ </note>
+ </para>
- <para>
- As the source <filename>archiver</filename> class has already
- archived the original
- unmodified source that contains the license files,
- you would have already met the requirements for inclusion
- of the license information with source as defined by the GPL
- and other open source licenses.
- </para>
- </section>
+ <para>
+ As the source <filename>archiver</filename> class has already
+ archived the original
+ unmodified source that contains the license files,
+ you would have already met the requirements for inclusion
+ of the license information with source as defined by the GPL
+ and other open source licenses.
+ </para>
+ </section>
- <section id='providing-compilation-scripts-and-source-code-modifications'>
- <title>Providing Compilation Scripts and Source Code Modifications</title>
+ <section id='providing-compilation-scripts-and-source-code-modifications'>
+ <title>Providing Compilation Scripts and Source Code Modifications</title>
- <para>
- At this point, we have addressed all we need to
- prior to generating the image.
- The next two requirements are addressed during the final
- packaging of the release.
- </para>
+ <para>
+ At this point, we have addressed all we need to
+ prior to generating the image.
+ The next two requirements are addressed during the final
+ packaging of the release.
+ </para>
- <para>
- By releasing the version of the OpenEmbedded build system
- and the layers used during the build, you will be providing both
- compilation scripts and the source code modifications in one
- step.
- </para>
+ <para>
+ By releasing the version of the OpenEmbedded build system
+ and the layers used during the build, you will be providing both
+ compilation scripts and the source code modifications in one
+ step.
+ </para>
- <para>
- If the deployment team has a
- <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
- and a distro layer, and those those layers are used to patch,
- compile, package, or modify (in any way) any open source
- software included in your released images, you
- might be required to release those layers under section 3 of
- GPLv2 or section 1 of GPLv3.
- One way of doing that is with a clean
- checkout of the version of the Yocto Project and layers used
- during your build.
- Here is an example:
- <literallayout class='monospaced'>
+ <para>
+ If the deployment team has a
+ <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
+ and a distro layer, and those those layers are used to patch,
+ compile, package, or modify (in any way) any open source
+ software included in your released images, you
+ might be required to release those layers under section 3 of
+ GPLv2 or section 1 of GPLv3.
+ One way of doing that is with a clean
+ checkout of the version of the Yocto Project and layers used
+ during your build.
+ Here is an example:
+ <literallayout class='monospaced'>
# We built using the &DISTRO_NAME_NO_CAP; branch of the poky repo
$ git clone -b &DISTRO_NAME_NO_CAP; git://git.yoctoproject.org/poky
$ cd poky
@@ -10613,18 +15040,18 @@
$ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
# clean up the .git repos
$ find . -name ".git" -type d -exec rm -rf {} \;
- </literallayout>
- One thing a development organization might want to consider
- for end-user convenience is to modify
- <filename>meta-poky/conf/bblayers.conf.sample</filename> to
- ensure that when the end user utilizes the released build
- system to build an image, the development organization's
- layers are included in the <filename>bblayers.conf</filename>
- file automatically:
- <literallayout class='monospaced'>
- # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
+ </literallayout>
+ One thing a development organization might want to consider
+ for end-user convenience is to modify
+ <filename>meta-poky/conf/bblayers.conf.sample</filename> to
+ ensure that when the end user utilizes the released build
+ system to build an image, the development organization's
+ layers are included in the <filename>bblayers.conf</filename>
+ file automatically:
+ <literallayout class='monospaced'>
+ # POKY_BBLAYERS_CONF_VERSION is increased each time build/conf/bblayers.conf
# changes incompatibly
- LCONF_VERSION = "6"
+ POKY_BBLAYERS_CONF_VERSION = "2"
BBPATH = "${TOPDIR}"
BBFILES ?= ""
@@ -10635,14 +15062,15 @@
##OEROOT##/meta-yocto-bsp \
##OEROOT##/meta-mylayer \
"
- </literallayout>
- Creating and providing an archive of the
- <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
- layers (recipes, configuration files, and so forth)
- enables you to meet your
- requirements to include the scripts to control compilation
- as well as any modifications to the original source.
- </para>
+ </literallayout>
+ Creating and providing an archive of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#metadata'>Metadata</ulink>
+ layers (recipes, configuration files, and so forth)
+ enables you to meet your
+ requirements to include the scripts to control compilation
+ as well as any modifications to the original source.
+ </para>
+ </section>
</section>
</section>
@@ -10761,6 +15189,136 @@
</para>
</section>
</section>
+
+ <section id="dev-using-wayland-and-weston">
+ <title>Using Wayland and Weston</title>
+
+ <para>
+ <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)'>Wayland</ulink>
+ is a computer display server protocol that
+ provides a method for compositing window managers to communicate
+ directly with applications and video hardware and expects them to
+ communicate with input hardware using other libraries.
+ Using Wayland with supporting targets can result in better control
+ over graphics frame rendering than an application might otherwise
+ achieve.
+ </para>
+
+ <para>
+ The Yocto Project provides the Wayland protocol libraries and the
+ reference
+ <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Weston</ulink>
+ compositor as part of its release.
+ You can find the integrated packages in the
+ <filename>meta</filename> layer of the
+ <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
+ Specifically, you can find the recipes that build both Wayland
+ and Weston at <filename>meta/recipes-graphics/wayland</filename>.
+ </para>
+
+ <para>
+ You can build both the Wayland and Weston packages for use only
+ with targets that accept the
+ <ulink url='https://en.wikipedia.org/wiki/Mesa_(computer_graphics)'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
+ which is also known as Mesa DRI.
+ This implies that you cannot build and use the packages if your
+ target uses, for example, the
+ <trademark class='registered'>Intel</trademark> Embedded Media
+ and Graphics Driver
+ (<trademark class='registered'>Intel</trademark> EMGD) that
+ overrides Mesa DRI.
+ <note>
+ Due to lack of EGL support, Weston 1.0.3 will not run
+ directly on the emulated QEMU hardware.
+ However, this version of Weston will run under X emulation
+ without issues.
+ </note>
+ </para>
+
+ <para>
+ This section describes what you need to do to implement Wayland and
+ use the Weston compositor when building an image for a supporting
+ target.
+ </para>
+
+ <section id="enabling-wayland-in-an-image">
+ <title>Enabling Wayland in an Image</title>
+
+ <para>
+ To enable Wayland, you need to enable it to be built and enable
+ it to be included (installed) in the image.
+ </para>
+
+ <section id="enable-building">
+ <title>Building</title>
+
+ <para>
+ To cause Mesa to build the <filename>wayland-egl</filename>
+ platform and Weston to build Wayland with Kernel Mode
+ Setting
+ (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
+ support, include the "wayland" flag in the
+ <ulink url="&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></ulink>
+ statement in your <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ DISTRO_FEATURES_append = " wayland"
+ </literallayout>
+ <note>
+ If X11 has been enabled elsewhere, Weston will build
+ Wayland with X11 support
+ </note>
+ </para>
+ </section>
+
+ <section id="enable-installation-in-an-image">
+ <title>Installing</title>
+
+ <para>
+ To install the Wayland feature into an image, you must
+ include the following
+ <ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></ulink>
+ statement in your <filename>local.conf</filename> file:
+ <literallayout class='monospaced'>
+ CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
+ </literallayout>
+ </para>
+ </section>
+ </section>
+
+ <section id="running-weston">
+ <title>Running Weston</title>
+
+ <para>
+ To run Weston inside X11, enabling it as described earlier and
+ building a Sato image is sufficient.
+ If you are running your image under Sato, a Weston Launcher
+ appears in the "Utility" category.
+ </para>
+
+ <para>
+ Alternatively, you can run Weston through the command-line
+ interpretor (CLI), which is better suited for development work.
+ To run Weston under the CLI, you need to do the following after
+ your image is built:
+ <orderedlist>
+ <listitem><para>
+ Run these commands to export
+ <filename>XDG_RUNTIME_DIR</filename>:
+ <literallayout class='monospaced'>
+ mkdir -p /tmp/$USER-weston
+ chmod 0700 /tmp/$USER-weston
+ export XDG_RUNTIME_DIR=/tmp/$USER-weston
+ </literallayout>
+ </para></listitem>
+ <listitem><para>
+ Launch Weston in the shell:
+ <literallayout class='monospaced'>
+ weston
+ </literallayout></para></listitem>
+ </orderedlist>
+ </para>
+ </section>
+ </section>
</chapter>
<!--