2008-02-26 11:31:34 +00:00
|
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
2012-03-09 19:40:39 +00:00
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
|
|
|
|
[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
|
2008-02-26 11:31:34 +00:00
|
|
|
|
|
|
|
<chapter id='extendpoky'>
|
|
|
|
|
2011-12-08 21:22:23 +00:00
|
|
|
<title>Common Tasks</title>
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
This chapter describes standard tasks such as adding new
|
2012-07-02 16:59:11 +00:00
|
|
|
software packages, extending or customizing images, and porting work to
|
2010-10-28 21:29:17 +00:00
|
|
|
new hardware (adding a new machine).
|
2012-06-12 14:48:52 +00:00
|
|
|
The chapter also describes how to combine multiple
|
|
|
|
versions of library files into a single image, how to handle a package name alias, and
|
|
|
|
gives advice about how to make changes to the Yocto Project to achieve the best results.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
2012-03-02 15:47:21 +00:00
|
|
|
<section id="understanding-and-creating-layers">
|
|
|
|
<title>Understanding and Creating Layers</title>
|
2012-03-02 15:34:18 +00:00
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
The OpenEmbedded build system supports organizing <link linkend='metadata'>metadata</link>
|
2012-03-02 23:21:55 +00:00
|
|
|
into 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 you organize your metadata, the easier it is to cope with future changes.
|
2012-03-02 15:34:18 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-03-02 23:21:55 +00:00
|
|
|
To illustrate how layers are used to keep things modular, consider machine customizations.
|
|
|
|
These types of customizations typically reside in a 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 a 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.
|
2012-03-13 22:05:00 +00:00
|
|
|
You can accomplish this through a recipe that is a BitBake append
|
|
|
|
(<filename>.bbappend</filename>) file, which is described later in this section.
|
2012-03-02 15:34:18 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
2012-03-02 23:21:55 +00:00
|
|
|
<section id='yocto-project-layers'>
|
2012-07-02 16:59:11 +00:00
|
|
|
<title>Layers</title>
|
2012-03-02 23:21:55 +00:00
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
The source directory contains several layers right out of the box.
|
|
|
|
You can easily identify a layer in the source directory by its folder name.
|
2012-03-02 23:21:55 +00:00
|
|
|
Folders that are layers begin with the string <filename>meta</filename>.
|
2012-07-02 16:59:11 +00:00
|
|
|
For example, when you set up the <link linkend='source-directory'>source directory</link>
|
2012-03-02 23:21:55 +00:00
|
|
|
structure, you will see several layers: <filename>meta</filename>, <filename>meta-demoapps</filename>,
|
|
|
|
<filename>meta-skeleton</filename>, and <filename>meta-yocto</filename>.
|
|
|
|
Each of these folders is a layer.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Furthermore, if you set up a local copy of the <filename>meta-intel</filename> Git repository
|
|
|
|
and then explore that folder, you will discover many BSP layers within the
|
|
|
|
<filename>meta-intel</filename> layer.
|
|
|
|
For more information on BSP layers, see the
|
2012-03-09 19:40:39 +00:00
|
|
|
"<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
|
|
|
|
section in the Yocto Project Board Support Package (BSP) Developer's Guide.
|
2012-03-02 23:21:55 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='creating-your-own-layer'>
|
|
|
|
<title>Creating Your Own Layer</title>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
It is very easy to create your own layer to use with the OpenEmbedded build system.
|
2012-03-02 23:21:55 +00:00
|
|
|
Follow these general steps to create your layer:
|
|
|
|
<orderedlist>
|
|
|
|
<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
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&OE_HOME_URL;/wiki/LayerIndex'><filename>LayerIndex</filename></ulink>
|
2012-03-06 16:37:59 +00:00
|
|
|
for a list of layers from the OpenEmbedded community that can be used in the
|
|
|
|
Yocto Project.</para></listitem>
|
2012-03-02 23:21:55 +00:00
|
|
|
<listitem><para><emphasis>Create a Directory:</emphasis> Create the directory
|
|
|
|
for your layer.
|
|
|
|
Traditionally, prepend the name of the folder with the string
|
|
|
|
<filename>meta</filename>.
|
|
|
|
For example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
meta-mylayer
|
|
|
|
meta-GUI_xyz
|
|
|
|
meta-mymachine
|
|
|
|
</literallayout></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/conf/layer.conf</filename> file demonstrates the
|
|
|
|
required syntax:
|
|
|
|
<literallayout class='monospaced'>
|
2012-03-02 15:34:18 +00:00
|
|
|
# We have a conf and classes directory, add to BBPATH
|
2012-03-02 23:21:55 +00:00
|
|
|
BBPATH := "${LAYERDIR}:${BBPATH}"
|
2012-03-02 15:34:18 +00:00
|
|
|
|
2012-08-13 15:17:40 +00:00
|
|
|
# We have recipes-* directories, add to BBFILES
|
2012-03-02 15:34:18 +00:00
|
|
|
BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
|
|
|
|
${LAYERDIR}/recipes-*/*/*.bbappend"
|
|
|
|
|
|
|
|
BBFILE_COLLECTIONS += "yocto"
|
|
|
|
BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
|
|
|
|
BBFILE_PRIORITY_yocto = "5"
|
2012-03-02 23:21:55 +00:00
|
|
|
</literallayout></para>
|
|
|
|
<para>In the previous example, the recipes for the layers are added to
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
|
2012-03-02 23:21:55 +00:00
|
|
|
The
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
|
2012-03-02 23:21:55 +00:00
|
|
|
variable is then appended with the layer name.
|
|
|
|
The
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
|
2012-03-06 16:37:59 +00:00
|
|
|
variable is set to a regular expression and is used to match files
|
|
|
|
from <filename>BBFILES</filename> into a particular layer.
|
|
|
|
In this case, immediate expansion of
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
|
2012-03-12 20:25:58 +00:00
|
|
|
sets <filename>BBFILE_PATTERN</filename> to the layer's path.
|
2012-03-02 23:21:55 +00:00
|
|
|
The
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
|
2012-03-06 16:37:59 +00:00
|
|
|
variable then assigns a priority to the layer.
|
2012-03-02 23:21:55 +00:00
|
|
|
Applying priorities is useful in situations where the same package might appear in multiple
|
|
|
|
layers and allows you to choose what layer should take precedence.</para>
|
|
|
|
<para>Note the use of the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
|
2012-03-02 23:21:55 +00:00
|
|
|
variable with the immediate expansion operator.
|
|
|
|
The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
|
|
|
|
requires the immediate expansion operator so that BitBake does not wait to expand the variable
|
|
|
|
when it's parsing a different directory.</para>
|
2012-03-13 13:57:37 +00:00
|
|
|
<para>Through the use of the <filename>BBPATH</filename> variable,
|
2012-03-12 20:25:58 +00:00
|
|
|
BitBake locates <filename>.bbclass</filename> files, configuration
|
|
|
|
files, and files that are included with <filename>include</filename>
|
|
|
|
and <filename>require</filename> statements.
|
2012-03-02 23:21:55 +00:00
|
|
|
For these cases, BitBake uses the first file with the matching name found in
|
|
|
|
<filename>BBPATH</filename>.
|
|
|
|
This is similar to the way the <filename>PATH</filename> variable is used for binaries.
|
|
|
|
We recommend, therefore, that you use unique <filename>.bbclass</filename>
|
|
|
|
and configuration file names in your custom layer.</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.
|
|
|
|
If the layer adds distro policy, add the distro configuration in a
|
|
|
|
<filename>conf/distro/</filename> file with the layer.
|
|
|
|
If the layer introduces new recipes, put the recipes you need in
|
|
|
|
<filename>recipes-*</filename> subdirectories within the layer.</para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</para>
|
2012-03-02 15:34:18 +00:00
|
|
|
|
2012-03-02 23:21:55 +00:00
|
|
|
<para>
|
|
|
|
To create layers that are easier to maintain, you should consider the following:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Avoid "overlaying" entire recipes from other layers in your
|
|
|
|
configuration.
|
|
|
|
In other words, don't copy an entire recipe into your layer and then modify it.
|
|
|
|
Use <filename>.bbappend</filename> files to override the parts of the
|
|
|
|
recipe you need to modify.</para></listitem>
|
|
|
|
<listitem><para>Avoid duplicating include files.
|
|
|
|
Use <filename>.bbappend</filename> files for each recipe that uses an include
|
|
|
|
file.
|
2012-03-13 22:07:39 +00:00
|
|
|
Or, if you are introducing a new recipe that requires the included file, use the
|
2012-03-13 13:57:37 +00:00
|
|
|
path relative to the original layer directory to refer to the file.
|
2012-03-02 23:21:55 +00:00
|
|
|
For example, use <filename>require recipes-core/somepackage/somefile.inc</filename>
|
|
|
|
instead of <filename>require somefile.inc</filename>.
|
|
|
|
If you're finding you have to overlay the include file, it could indicate a
|
|
|
|
deficiency in the include file in the layer to which it originally belongs.
|
|
|
|
If this is the case, you need to address that deficiency instead of overlaying
|
|
|
|
the include file.
|
|
|
|
For example, consider how Qt 4 database support plugins are configured.
|
2012-07-02 16:59:11 +00:00
|
|
|
The source directory does not have
|
|
|
|
MySQL or PostgreSQL, however OpenEmbedded's
|
2012-03-02 23:21:55 +00:00
|
|
|
layer <filename>meta-oe</filename> does.
|
|
|
|
Consequently, <filename>meta-oe</filename> uses <filename>.bbappend</filename>
|
|
|
|
files to modify the <filename>QT_SQL_DRIVER_FLAGS</filename> variable to enable
|
|
|
|
the appropriate plugins.
|
|
|
|
This variable was added to the <filename>qt4.inc</filename> include file in
|
2012-07-02 16:59:11 +00:00
|
|
|
the source directory specifically to allow the <filename>meta-oe</filename> layer
|
2012-03-02 23:21:55 +00:00
|
|
|
to be able to control which plugins are built.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
2012-03-02 15:34:18 +00:00
|
|
|
|
2012-03-02 23:21:55 +00:00
|
|
|
<para>
|
|
|
|
We also recommend the following:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Store custom layers in a Git repository that uses the
|
2012-03-13 13:57:37 +00:00
|
|
|
<filename>meta-<layer_name></filename> format.</para></listitem>
|
2012-03-02 23:21:55 +00:00
|
|
|
<listitem><para>Clone the repository alongside other <filename>meta</filename>
|
2012-07-02 16:59:11 +00:00
|
|
|
directories in the
|
|
|
|
<link linkend='source-directory'>source directory</link>.</para></listitem>
|
2012-03-02 23:21:55 +00:00
|
|
|
</itemizedlist>
|
2012-07-02 16:59:11 +00:00
|
|
|
Following these recommendations keeps your source directory and
|
2012-03-02 23:21:55 +00:00
|
|
|
its configuration entirely inside the Yocto Project's core base.
|
|
|
|
</para>
|
|
|
|
</section>
|
2012-03-02 15:34:18 +00:00
|
|
|
|
2012-03-02 23:21:55 +00:00
|
|
|
<section id='enabling-your-layer'>
|
|
|
|
<title>Enabling Your Layer</title>
|
2012-03-02 15:34:18 +00:00
|
|
|
|
2012-03-02 23:21:55 +00:00
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
Before the OpenEmbedded build system can use your new layer, you need to enable it.
|
2012-03-02 23:21:55 +00:00
|
|
|
To enable your layer, simply add your layer's path to the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
|
2012-03-02 23:21:55 +00:00
|
|
|
variable in your <filename>conf/bblayers.conf</filename> file, which is found in the
|
2012-07-02 16:59:11 +00:00
|
|
|
<link linkend='build-directory'>build directory</link>.
|
2012-03-02 23:21:55 +00:00
|
|
|
The following example shows how to enable a layer named <filename>meta-mylayer</filename>:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
LCONF_VERSION = "1"
|
|
|
|
|
|
|
|
BBFILES ?= ""
|
|
|
|
BBLAYERS = " \
|
|
|
|
/path/to/poky/meta \
|
|
|
|
/path/to/poky/meta-yocto \
|
|
|
|
/path/to/poky/meta-mylayer \
|
|
|
|
"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
BitBake parses each <filename>conf/layer.conf</filename> file 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
|
2012-07-02 16:59:11 +00:00
|
|
|
recipes, classes and configurations contained within the particular layer to the source
|
|
|
|
directory.
|
2012-03-02 23:21:55 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='using-bbappend-files'>
|
|
|
|
<title>Using .bbappend Files</title>
|
|
|
|
|
|
|
|
<para>
|
2012-03-13 22:26:42 +00:00
|
|
|
Recipes used to append metadata to other recipes are called BitBake append files.
|
|
|
|
BitBake append files use the <filename>.bbappend</filename> file type suffix, while
|
|
|
|
underlying recipes to which metadata is being appended use the
|
|
|
|
<filename>.bb</filename> file type suffix.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A <filename>.bbappend</filename> file allows your layer to make additions or
|
|
|
|
changes to the content of another layer's recipe without having to copy the other
|
|
|
|
recipe into your layer.
|
|
|
|
Your <filename>.bbappend</filename> file resides in your layer, while the underlying
|
|
|
|
<filename>.bb</filename> recipe file to which you are appending metadata
|
|
|
|
resides in a different layer.
|
2012-03-02 23:21:55 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Append files files must have the same name as the underlying recipe.
|
2012-04-23 20:41:10 +00:00
|
|
|
For example, the append file <filename>someapp_&DISTRO;.bbappend</filename> must
|
|
|
|
apply to <filename>someapp_&DISTRO;.bb</filename>.
|
2012-03-02 23:21:55 +00:00
|
|
|
This means the original recipe and append file names are version number specific.
|
|
|
|
If the underlying recipe is renamed to update to a newer version, the
|
|
|
|
corresponding <filename>.bbappend</filename> file must be renamed as well.
|
2012-03-06 16:37:59 +00:00
|
|
|
During the build process, BitBake displays an error on starting if it detects a
|
2012-03-02 23:21:55 +00:00
|
|
|
<filename>.bbappend</filename> file that does not have an underlying recipe
|
2012-03-06 16:37:59 +00:00
|
|
|
with a matching name.
|
2012-03-02 23:21:55 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Being able to append information to an existing recipe not only avoids duplication,
|
|
|
|
but also automatically applies recipe changes in a different layer to your layer.
|
|
|
|
If you were copying recipes, you would have to manually merge changes as they occur.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As an example, consider the main formfactor recipe and a corresponding formfactor
|
2012-03-13 22:33:19 +00:00
|
|
|
append file both from the
|
2012-07-02 16:59:11 +00:00
|
|
|
<link linkend='source-directory'>source directory</link>.
|
2012-03-02 23:21:55 +00:00
|
|
|
Here is the main formfactor recipe, which is named <filename>formfactor_0.0.bb</filename> and
|
2012-04-25 17:47:51 +00:00
|
|
|
located in the meta layer at <filename>meta/recipes-bsp/formfactor</filename>:
|
2012-03-02 23:21:55 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
DESCRIPTION = "Device formfactor information"
|
|
|
|
SECTION = "base"
|
|
|
|
LICENSE = "MIT"
|
|
|
|
LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \
|
2012-04-25 17:47:51 +00:00
|
|
|
file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
|
|
|
|
PR = "r20"
|
2012-03-02 23:21:55 +00:00
|
|
|
|
|
|
|
SRC_URI = "file://config file://machconfig"
|
|
|
|
S = "${WORKDIR}"
|
|
|
|
|
|
|
|
PACKAGE_ARCH = "${MACHINE_ARCH}"
|
|
|
|
INHIBIT_DEFAULT_DEPS = "1"
|
|
|
|
|
|
|
|
do_install() {
|
|
|
|
# Only install file if it has a contents
|
|
|
|
install -d ${D}${sysconfdir}/formfactor/
|
|
|
|
install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
|
|
|
|
if [ -s "${S}/machconfig" ]; then
|
|
|
|
install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
|
2012-04-25 17:47:51 +00:00
|
|
|
fi
|
2012-03-02 23:21:55 +00:00
|
|
|
}
|
|
|
|
</literallayout>
|
|
|
|
Here is the append file, which is named <filename>formfactor_0.0.bbappend</filename> and is from the
|
2012-04-25 17:53:32 +00:00
|
|
|
Crown Bay BSP Layer named <filename>meta-intel/meta-crownbay</filename>.
|
|
|
|
The file is in <filename>recipes-bsp/formfactor</filename>:
|
2012-03-02 23:21:55 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
|
|
|
|
|
|
|
|
PRINC = "1"
|
|
|
|
</literallayout>
|
|
|
|
This example adds or overrides files in
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
2012-03-13 22:33:19 +00:00
|
|
|
within a <filename>.bbappend</filename> by extending the path BitBake uses to search for files.
|
2012-03-02 23:21:55 +00:00
|
|
|
The most reliable way to do this is by prepending the
|
|
|
|
<filename>FILESEXTRAPATHS</filename> variable.
|
|
|
|
For example, if you have your files in a directory that is named the same as your package
|
2012-03-09 19:40:39 +00:00
|
|
|
(<ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>),
|
2012-03-13 22:33:19 +00:00
|
|
|
you can add this directory by adding the following to your <filename>.bbappend</filename> file:
|
2012-03-02 23:21:55 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
|
|
|
|
</literallayout>
|
2012-03-06 16:37:59 +00:00
|
|
|
Using the immediate expansion assignment operator <filename>:=</filename> is important because
|
|
|
|
of the reference to <filename>THISDIR</filename>.
|
|
|
|
The trailing colon character is important as it ensures that items in the list remain
|
|
|
|
colon-separated.
|
2012-03-02 23:21:55 +00:00
|
|
|
<note>BitBake automatically defines the <filename>THISDIR</filename> variable.
|
|
|
|
You should never set this variable yourself.
|
|
|
|
Using <filename>_prepend</filename> ensures your path will be searched prior to other
|
|
|
|
paths in the final list.
|
|
|
|
</note>
|
|
|
|
</para>
|
2012-03-13 23:02:42 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
For another example on how to use a <filename>.bbappend</filename> file, see the
|
|
|
|
"<link linkend='changing-recipes-kernel'>Changing <filename>recipes-kernel</filename></link>"
|
|
|
|
section.
|
|
|
|
</para>
|
2012-03-02 23:21:55 +00:00
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='prioritizing-your-layer'>
|
|
|
|
<title>Prioritizing Your Layer</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Each layer is assigned a priority value.
|
|
|
|
Priority values control which layer takes precedence if there are recipe files with
|
|
|
|
the same name in multiple layers.
|
|
|
|
For these cases, the recipe file from the layer with a higher priority number taking precedence.
|
|
|
|
Priority values also affect the order in which multiple <filename>.bbappend</filename> files
|
|
|
|
for the same recipe are applied.
|
|
|
|
You can either specify the priority manually, or allow the build system to calculate it
|
|
|
|
based on the layer's dependencies.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To specify the layer's priority manually, use the
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
|
2012-03-02 23:21:55 +00:00
|
|
|
variable.
|
|
|
|
For example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
BBFILE_PRIORITY := "1"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<note>
|
|
|
|
<para>It is possible for a recipe with a lower version number
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
|
2012-03-02 23:21:55 +00:00
|
|
|
in a layer that has a higher priority to take precedence.</para>
|
|
|
|
<para>Also, the layer priority does not currently affect the precedence order of
|
|
|
|
<filename>.conf</filename> or <filename>.bbclass</filename> files.
|
|
|
|
Future versions of BitBake might address this.</para>
|
|
|
|
</note>
|
|
|
|
</section>
|
2012-03-05 18:00:46 +00:00
|
|
|
|
|
|
|
<section id='managing-layers'>
|
|
|
|
<title>Managing Layers</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You can use the BitBake layer management tool 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 <filename>.bbappend</filename> files and their applicable recipes
|
|
|
|
can help to reveal potential problems.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Use the following form when running the layer management tool.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ bitbake-layers <command> [arguments]
|
|
|
|
</literallayout>
|
2012-03-06 16:37:59 +00:00
|
|
|
The following list describes the available commands:
|
2012-03-05 18:00:46 +00:00
|
|
|
<itemizedlist>
|
2012-03-12 20:25:58 +00:00
|
|
|
<listitem><para><filename><emphasis>help:</emphasis></filename>
|
|
|
|
Displays general help or help on a specified command.</para></listitem>
|
|
|
|
<listitem><para><filename><emphasis>show-layers:</emphasis></filename>
|
|
|
|
Show 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>
|
|
|
|
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>
|
|
|
|
Lists <filename>.bbappend</filename> files and the recipe files to which
|
|
|
|
they apply.</para></listitem>
|
2012-03-06 16:37:59 +00:00
|
|
|
<listitem><para><filename><emphasis>flatten:</emphasis></filename>
|
|
|
|
Flattens the layer configuration into a separate output directory.
|
|
|
|
Flattening your layer configuration builds a "flattened" directory that contains
|
|
|
|
the contents of all layers, with any overlayed recipes removed and any
|
2012-03-13 22:35:40 +00:00
|
|
|
<filename>.bbappend</filename> files appended to the corresponding recipes.
|
2012-03-06 16:37:59 +00:00
|
|
|
You might have to perform some manual cleanup of the flattened layer as follows:
|
|
|
|
<itemizedlist>
|
|
|
|
<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 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 <filename>.bbappend</filename>
|
|
|
|
files need to be cleaned up.
|
2012-03-12 20:25:58 +00:00
|
|
|
The contents of each <filename>.bbappend</filename> end up in the
|
2012-03-06 16:37:59 +00:00
|
|
|
flattened recipe.
|
|
|
|
However, if there are appended or changed variable values, you need to tidy
|
2012-03-12 20:25:58 +00:00
|
|
|
these up yourself.
|
|
|
|
Consider the following example.
|
|
|
|
Here, the <filename>bitbake-layers</filename> command adds the line
|
|
|
|
<filename>#### bbappended ...</filename> so that you know where the following
|
|
|
|
lines originate:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
...
|
|
|
|
DESCRIPTION = "A useful utility"
|
|
|
|
...
|
|
|
|
EXTRA_OECONF = "--enable-something"
|
|
|
|
...
|
|
|
|
|
|
|
|
#### bbappended from meta-anotherlayer ####
|
|
|
|
|
|
|
|
DESCRIPTION = "Customized utility"
|
|
|
|
EXTRA_OECONF += "--enable-somethingelse"
|
|
|
|
</literallayout>
|
|
|
|
Ideally, you would tidy up these utilities as follows:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
...
|
|
|
|
DESCRIPTION = "Customized utility"
|
|
|
|
...
|
|
|
|
EXTRA_OECONF = "--enable-something --enable-somethingelse"
|
|
|
|
...
|
|
|
|
</literallayout></para></listitem>
|
2012-03-06 16:37:59 +00:00
|
|
|
</itemizedlist></para></listitem>
|
2012-03-05 18:00:46 +00:00
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
</section>
|
2012-03-02 15:34:18 +00:00
|
|
|
</section>
|
|
|
|
|
2012-03-29 19:31:41 +00:00
|
|
|
<section id='usingpoky-extend-customimage'>
|
|
|
|
<title>Customizing Images</title>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
You can customize images to satisfy particular requirements.
|
2012-03-29 19:31:41 +00:00
|
|
|
This section describes several methods and provides guidelines for each.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='usingpoky-extend-customimage-custombb'>
|
|
|
|
<title>Customizing Images Using Custom .bb Files</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
One way to get additional software into an image is to create a custom image.
|
|
|
|
The following example shows the form for the two lines you need:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
IMAGE_INSTALL = "task-core-x11-base package1 package2"
|
|
|
|
|
|
|
|
inherit core-image
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
By creating a custom image, a developer has total control
|
|
|
|
over the contents of the image.
|
|
|
|
It is important to use the correct names of packages in the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
|
|
|
|
variable.
|
|
|
|
You must use the OpenEmbedded notation and not the Debian notation for the names
|
|
|
|
(e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-04-24 11:19:07 +00:00
|
|
|
The other method for creating a custom image is to base it on an existing image.
|
|
|
|
For example, if you want to create an image based on <filename>core-image-sato</filename>
|
|
|
|
but add the additional package <filename>strace</filename> to the image,
|
|
|
|
copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
|
|
|
|
new <filename>.bb</filename> and add the following line to the end of the copy:
|
2012-03-29 19:31:41 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
IMAGE_INSTALL += "strace"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-extend-customimage-customtasks'>
|
|
|
|
<title>Customizing Images Using Custom Tasks</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For complex custom images, the best approach is to create a custom task package
|
|
|
|
that is used to build the image or images.
|
|
|
|
A good example of a tasks package is
|
2012-04-16 13:50:57 +00:00
|
|
|
<filename>meta/recipes-core/tasks/task-core-boot.bb</filename>
|
2012-03-29 19:31:41 +00:00
|
|
|
The
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
|
|
|
|
variable lists the task packages to build along with the complementary
|
|
|
|
<filename>-dbg</filename> and <filename>-dev</filename> packages.
|
|
|
|
For each package added, you can use
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
|
|
|
|
and
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
|
|
|
|
entries to provide a list of packages the parent task package should contain.
|
|
|
|
Following is an example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
DESCRIPTION = "My Custom Tasks"
|
|
|
|
|
|
|
|
PACKAGES = "\
|
|
|
|
task-custom-apps \
|
|
|
|
task-custom-apps-dbg \
|
|
|
|
task-custom-apps-dev \
|
|
|
|
task-custom-tools \
|
|
|
|
task-custom-tools-dbg \
|
|
|
|
task-custom-tools-dev \
|
|
|
|
"
|
|
|
|
|
|
|
|
RDEPENDS_task-custom-apps = "\
|
|
|
|
dropbear \
|
|
|
|
portmap \
|
|
|
|
psplash"
|
|
|
|
|
|
|
|
RDEPENDS_task-custom-tools = "\
|
|
|
|
oprofile \
|
|
|
|
oprofileui-server \
|
|
|
|
lttng-control \
|
|
|
|
lttng-viewer"
|
|
|
|
|
|
|
|
RRECOMMENDS_task-custom-tools = "\
|
|
|
|
kernel-module-oprofile"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In the previous example, two task packages are created with their dependencies and their
|
|
|
|
recommended package dependencies listed: <filename>task-custom-apps</filename>, and
|
|
|
|
<filename>task-custom-tools</filename>.
|
|
|
|
To build an image using these task packages, you need to add
|
|
|
|
<filename>task-custom-apps</filename> and/or
|
|
|
|
<filename>task-custom-tools</filename> to
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
|
|
|
|
For other forms of image dependencies see the other areas of this section.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-extend-customimage-imagefeatures'>
|
|
|
|
<title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
|
|
|
|
<filename>EXTRA_IMAGE_FEATURES</filename></title>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
Ultimately users might want to add extra image features to the set by using the
|
2012-03-29 19:31:41 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename>
|
|
|
|
variable.
|
|
|
|
To create these features, the best reference is
|
2012-07-02 16:59:11 +00:00
|
|
|
<filename>meta/classes/core-image.bbclass</filename>, which shows how to achieve this.
|
2012-03-29 19:31:41 +00:00
|
|
|
In summary, the file looks at the contents of the
|
|
|
|
<filename>IMAGE_FEATURES</filename>
|
|
|
|
variable and then maps that into a set of tasks or packages.
|
|
|
|
Based on this information the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'> IMAGE_INSTALL</ulink></filename>
|
|
|
|
variable is generated automatically.
|
|
|
|
Users can add extra features by extending the class or creating a custom class for use
|
|
|
|
with specialized image <filename>.bb</filename> files.
|
|
|
|
You can also add more features by configuring the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</ulink></filename>
|
2012-07-02 16:59:11 +00:00
|
|
|
variable in the <filename>local.conf</filename> file found in the source directory
|
|
|
|
located in the build directory.
|
2012-03-29 19:31:41 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The Yocto Project ships with two SSH servers you can use in your images:
|
|
|
|
Dropbear and OpenSSH.
|
|
|
|
Dropbear is a minimal SSH server appropriate for resource-constrained environments,
|
|
|
|
while OpenSSH is a well-known standard SSH server implementation.
|
|
|
|
By default, the <filename>core-image-sato</filename> image is configured to use Dropbear.
|
|
|
|
The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename>
|
|
|
|
images both include OpenSSH.
|
2012-08-13 15:15:07 +00:00
|
|
|
The <filename>core-image-minimal</filename> image does not contain an SSH server.
|
2012-03-29 19:31:41 +00:00
|
|
|
To change these defaults, edit the <filename>IMAGE_FEATURES</filename> variable
|
|
|
|
so that it sets the image you are working with to include
|
|
|
|
<filename>ssh-server-dropbear</filename> or <filename>ssh-server-openssh</filename>.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-extend-customimage-localconf'>
|
|
|
|
<title>Customizing Images Using <filename>local.conf</filename></title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It is possible to customize image contents by using variables from your
|
|
|
|
local configuration in your <filename>conf/local.conf</filename> file.
|
|
|
|
Because it is limited to local use, this method generally only allows you to
|
|
|
|
add packages and is not as flexible as creating your own customized image.
|
|
|
|
When you add packages using local variables this way, you need to realize that
|
|
|
|
these variable changes affect all images at the same time and might not be
|
|
|
|
what you require.
|
|
|
|
</para>
|
|
|
|
|
2012-03-29 21:54:55 +00:00
|
|
|
<para>
|
|
|
|
The simplest way to add extra packages to all images is by using the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
|
|
|
|
variable with the <filename>_append</filename> operator:
|
|
|
|
<literallayout class='monospaced'>
|
2012-03-29 19:31:41 +00:00
|
|
|
IMAGE_INSTALL_append = " strace"
|
2012-03-29 21:54:55 +00:00
|
|
|
</literallayout>
|
|
|
|
Use of the syntax is important.
|
|
|
|
Specifically, the space between the quote and the package name, which is
|
|
|
|
<filename>strace</filename> in this example.
|
|
|
|
This space is required since the <filename>_append</filename>
|
|
|
|
operator does not add the space.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename>
|
|
|
|
operator if you want to avoid ordering issues.
|
|
|
|
The reason for this is because doing so unconditionally appends to the variable and
|
|
|
|
avoids ordering problems due to the variable being set in image recipes and
|
|
|
|
<filename>.bbclass</filename> files with operators like <filename>?=</filename>.
|
|
|
|
Using <filename>_append</filename> ensures the operation takes affect.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As shown in its simplest use, <filename>IMAGE_INSTALL_append</filename> affects
|
|
|
|
all images.
|
|
|
|
It is possible to extend the syntax so that the variable applies to a specific image only.
|
|
|
|
Here is an example:
|
|
|
|
<literallayout class='monospaced'>
|
2012-03-29 19:31:41 +00:00
|
|
|
IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
|
2012-03-29 21:54:55 +00:00
|
|
|
</literallayout>
|
|
|
|
This example adds <filename>strace</filename> to <filename>core-image-minimal</filename>
|
|
|
|
only.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You can add packages using a similar approach through the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
|
|
|
|
variable.
|
|
|
|
If you use this variable, only <filename>core-image-*</filename> images are affected.
|
|
|
|
</para>
|
2012-03-29 19:31:41 +00:00
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<section id='usingpoky-extend-addpkg'>
|
|
|
|
<title>Adding a Package</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
To add a package you need to write a recipe for it.
|
2010-10-28 21:29:17 +00:00
|
|
|
Writing a recipe means creating a <filename>.bb</filename> file that sets some
|
|
|
|
variables.
|
|
|
|
For information on variables that are useful for recipes and for information about recipe naming
|
2011-08-18 22:26:48 +00:00
|
|
|
issues, see the
|
2012-03-09 19:40:39 +00:00
|
|
|
"<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
|
|
|
|
section of the Yocto Project Reference Manual.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
Before writing a recipe from scratch, it is often useful to check
|
2010-10-28 21:29:17 +00:00
|
|
|
whether someone else has written one already.
|
|
|
|
OpenEmbedded is a good place to look as it has a wider scope and range of packages.
|
2011-08-18 22:26:48 +00:00
|
|
|
Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
|
2012-07-02 16:59:11 +00:00
|
|
|
you find there should work for you.
|
2009-04-28 07:24:47 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2009-04-28 07:24:47 +00:00
|
|
|
<para>
|
|
|
|
For new packages, the simplest way to add a recipe is to base it on a similar
|
2010-10-28 21:29:17 +00:00
|
|
|
pre-existing recipe.
|
2011-08-18 22:26:48 +00:00
|
|
|
The sections that follow provide some examples that show how to add standard
|
|
|
|
types of packages.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='usingpoky-extend-addpkg-singlec'>
|
|
|
|
<title>Single .c File Package (Hello World!)</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2010-10-28 21:29:17 +00:00
|
|
|
Building an application from a single file that is stored locally (e.g. under
|
|
|
|
<filename>files/</filename>) requires a recipe that has the file listed in
|
2012-02-06 17:39:17 +00:00
|
|
|
the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
|
|
|
|
variable.
|
2011-08-18 22:26:48 +00:00
|
|
|
Additionally, you need to manually write the <filename>do_compile</filename> and
|
|
|
|
<filename>do_install</filename> tasks.
|
2012-03-09 19:40:39 +00:00
|
|
|
The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
|
|
|
|
variable defines the
|
2012-02-06 17:39:17 +00:00
|
|
|
directory containing the source code, which is set to
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'>
|
2012-02-06 17:39:17 +00:00
|
|
|
WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build.
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
DESCRIPTION = "Simple helloworld application"
|
|
|
|
SECTION = "examples"
|
|
|
|
LICENSE = "MIT"
|
2011-08-23 13:08:50 +00:00
|
|
|
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
|
2011-08-18 22:26:48 +00:00
|
|
|
PR = "r0"
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
SRC_URI = "file://helloworld.c"
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
S = "${WORKDIR}"
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
do_compile() {
|
|
|
|
${CC} helloworld.c -o helloworld
|
|
|
|
}
|
|
|
|
|
|
|
|
do_install() {
|
|
|
|
install -d ${D}${bindir}
|
|
|
|
install -m 0755 helloworld ${D}${bindir}
|
|
|
|
}
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>,
|
|
|
|
and <filename>helloworld-dev</filename> packages are built.
|
|
|
|
For information on how to customize the packaging process, see the
|
2011-09-26 17:13:56 +00:00
|
|
|
"<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application
|
|
|
|
into Multiple Packages</link>" section.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-extend-addpkg-autotools'>
|
|
|
|
<title>Autotooled Package</title>
|
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
Applications that use Autotools such as <filename>autoconf</filename> and
|
2010-10-28 21:29:17 +00:00
|
|
|
<filename>automake</filename> require a recipe that has a source archive listed in
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
|
2011-08-18 22:26:48 +00:00
|
|
|
also inherits Autotools, which instructs BitBake to use the
|
2010-11-11 21:40:30 +00:00
|
|
|
<filename>autotools.bbclass</filename> file, which contains the definitions of all the steps
|
2011-08-18 22:26:48 +00:00
|
|
|
needed to build an Autotool-based application.
|
2010-10-28 21:29:17 +00:00
|
|
|
The result of the build is automatically packaged.
|
|
|
|
And, if the application uses NLS for localization, packages with local information are
|
|
|
|
generated (one package per language).
|
2011-05-13 17:27:40 +00:00
|
|
|
Following is one example: (<filename>hello_2.3.bb</filename>)
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
DESCRIPTION = "GNU Helloworld application"
|
|
|
|
SECTION = "examples"
|
|
|
|
LICENSE = "GPLv2+"
|
|
|
|
LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
|
|
|
|
PR = "r0"
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
inherit autotools gettext
|
|
|
|
</literallayout>
|
2010-09-09 09:00:31 +00:00
|
|
|
</para>
|
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
<para>
|
2012-02-06 17:39:17 +00:00
|
|
|
The variable
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
|
2012-02-06 17:39:17 +00:00
|
|
|
is used to track source license changes as described in the
|
2012-04-25 20:25:49 +00:00
|
|
|
"<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Track License Changes</ulink>" section.
|
2011-08-18 22:26:48 +00:00
|
|
|
You can quickly create Autotool-based recipes in a manner similar to the previous example.
|
|
|
|
</para>
|
2008-02-26 11:31:34 +00:00
|
|
|
</section>
|
2010-11-04 21:12:46 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<section id='usingpoky-extend-addpkg-makefile'>
|
|
|
|
<title>Makefile-Based Package</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2010-10-28 21:29:17 +00:00
|
|
|
Applications that use GNU <filename>make</filename> also require a recipe that has
|
2012-03-09 19:40:39 +00:00
|
|
|
the source archive listed in
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
|
2011-08-18 22:26:48 +00:00
|
|
|
You do not need to add a <filename>do_compile</filename> step since by default BitBake
|
2010-10-28 21:29:17 +00:00
|
|
|
starts the <filename>make</filename> command to compile the application.
|
|
|
|
If you need additional <filename>make</filename> options you should store them in the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
|
|
|
|
variable.
|
2011-03-17 14:21:21 +00:00
|
|
|
BitBake passes these options into the <filename>make</filename> GNU invocation.
|
2011-08-18 22:26:48 +00:00
|
|
|
Note that a <filename>do_install</filename> task is still required.
|
|
|
|
Otherwise BitBake runs an empty <filename>do_install</filename> task by default.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2010-10-28 21:29:17 +00:00
|
|
|
Some applications might require extra parameters to be passed to the compiler.
|
2011-08-18 22:26:48 +00:00
|
|
|
For example, the application might need an additional header path.
|
2012-02-06 17:39:17 +00:00
|
|
|
You can accomplish this by adding to the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
|
2010-10-28 21:29:17 +00:00
|
|
|
The following example shows this:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
CFLAGS_prepend = "-I ${S}/include "
|
|
|
|
</literallayout>
|
2010-09-09 09:00:31 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-09-09 09:00:31 +00:00
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
In the following example, <filename>mtd-utils</filename> is a makefile-based package:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
DESCRIPTION = "Tools for managing memory technology devices."
|
|
|
|
SECTION = "base"
|
|
|
|
DEPENDS = "zlib lzo e2fsprogs util-linux"
|
|
|
|
HOMEPAGE = "http://www.linux-mtd.infradead.org/"
|
2012-04-02 22:00:52 +00:00
|
|
|
LICENSE = "GPLv2+"
|
2011-08-23 13:08:50 +00:00
|
|
|
LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
|
2012-04-02 22:00:52 +00:00
|
|
|
file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2012-04-02 22:00:52 +00:00
|
|
|
SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
|
|
|
|
file://add-exclusion-to-mkfs-jffs2-git-2.patch"
|
2011-08-18 22:26:48 +00:00
|
|
|
|
|
|
|
S = "${WORKDIR}/git/"
|
|
|
|
|
2012-04-02 22:00:52 +00:00
|
|
|
PR = "r1"
|
|
|
|
|
|
|
|
EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
|
|
|
|
'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
|
2011-08-18 22:26:48 +00:00
|
|
|
|
|
|
|
do_install () {
|
2012-04-02 22:00:52 +00:00
|
|
|
oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
|
|
|
|
INCLUDEDIR=${includedir}
|
|
|
|
install -d ${D}${includedir}/mtd/
|
|
|
|
for f in ${S}/include/mtd/*.h; do
|
|
|
|
install -m 0644 $f ${D}${includedir}/mtd/
|
|
|
|
done
|
2011-08-18 22:26:48 +00:00
|
|
|
}
|
2012-04-02 22:00:52 +00:00
|
|
|
|
|
|
|
PARALLEL_MAKE = ""
|
|
|
|
|
|
|
|
BBCLASSEXTEND = "native"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If your sources are available as a tarball instead of a Git repository, you
|
|
|
|
will need to provide the URL to the tarball as well as an
|
|
|
|
<filename>md5</filename> or <filename>sha256</filename> sum of
|
|
|
|
the download.
|
|
|
|
Here is an example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
|
|
|
|
SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
|
|
|
|
</literallayout>
|
|
|
|
You can generate the <filename>md5</filename> or <filename>sha256</filename> sums
|
|
|
|
by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands
|
|
|
|
with the target file as the only argument.
|
|
|
|
Here is an example:
|
|
|
|
<literallayout class='monospaced'>
|
2012-04-02 22:23:57 +00:00
|
|
|
$ md5sum mtd-utils-1.4.9.tar.bz2
|
|
|
|
82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
|
2011-08-18 22:26:48 +00:00
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2010-11-04 21:12:46 +00:00
|
|
|
|
2011-09-26 17:13:56 +00:00
|
|
|
<section id='splitting-an-application-into-multiple-packages'>
|
|
|
|
<title>Splitting an Application into Multiple Packages</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2012-02-06 17:39:17 +00:00
|
|
|
You can use the variables
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
|
|
|
|
to split an application into multiple packages.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
Following is an example that uses the <filename>libXpm</filename> recipe.
|
|
|
|
By default, this recipe generates a single package that contains the library along
|
2010-10-28 21:29:17 +00:00
|
|
|
with a few binaries.
|
|
|
|
You can modify the recipe to split the binaries into separate packages:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
require xorg-lib-common.inc
|
|
|
|
|
|
|
|
DESCRIPTION = "X11 Pixmap library"
|
|
|
|
LICENSE = "X-BSD"
|
2011-08-23 13:08:50 +00:00
|
|
|
LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
|
2011-08-18 22:26:48 +00:00
|
|
|
DEPENDS += "libxext libsm libxt"
|
|
|
|
PR = "r3"
|
|
|
|
PE = "1"
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
XORG_PN = "libXpm"
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
PACKAGES =+ "sxpm cxpm"
|
|
|
|
FILES_cxpm = "${bindir}/cxpm"
|
|
|
|
FILES_sxpm = "${bindir}/sxpm"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
In the previous example, we want to ship the <filename>sxpm</filename>
|
|
|
|
and <filename>cxpm</filename> binaries in separate packages.
|
|
|
|
Since <filename>bindir</filename> would be packaged into the main
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
|
2012-02-06 17:39:17 +00:00
|
|
|
package by default, we prepend the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink>
|
2011-08-18 22:26:48 +00:00
|
|
|
</filename> variable so additional package names are added to the start of list.
|
2012-02-06 17:39:17 +00:00
|
|
|
This results in the extra
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink>_*</filename>
|
2010-11-11 21:40:30 +00:00
|
|
|
variables then containing information that define which files and
|
|
|
|
directories go into which packages.
|
2010-10-28 21:29:17 +00:00
|
|
|
Files included by earlier packages are skipped by latter packages.
|
2012-02-06 17:39:17 +00:00
|
|
|
Thus, the main
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename> package
|
2011-08-18 22:26:48 +00:00
|
|
|
does not include the above listed files.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2011-09-26 17:13:56 +00:00
|
|
|
<section id='including-static-library-files'>
|
|
|
|
<title>Including Static Library Files</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If you are building a library and the library offers static linking, you can control
|
|
|
|
which static library files (<filename>*.a</filename> files) get included in the
|
|
|
|
built library.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The <filename>PACKAGES</filename> and <filename>FILES_*</filename> variables in the
|
|
|
|
<filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
|
|
|
|
by the <filename>do_install</filename> task are packaged.
|
|
|
|
By default, the <filename>PACKAGES</filename> variable contains
|
|
|
|
<filename>${PN}-staticdev</filename>, which includes all static library files.
|
|
|
|
<note>
|
|
|
|
Previously released versions of the Yocto Project defined the static library files
|
|
|
|
through <filename>${PN}-dev</filename>.
|
|
|
|
</note>
|
|
|
|
Following, is part of the BitBake configuration file.
|
|
|
|
You can see where the static library files are defined:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
|
|
|
|
PACKAGES_DYNAMIC = "${PN}-locale-*"
|
|
|
|
FILES = ""
|
|
|
|
|
|
|
|
FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
|
|
|
|
${sysconfdir} ${sharedstatedir} ${localstatedir} \
|
|
|
|
${base_bindir}/* ${base_sbindir}/* \
|
|
|
|
${base_libdir}/*${SOLIBS} \
|
|
|
|
${datadir}/${BPN} ${libdir}/${BPN}/* \
|
|
|
|
${datadir}/pixmaps ${datadir}/applications \
|
|
|
|
${datadir}/idl ${datadir}/omf ${datadir}/sounds \
|
|
|
|
${libdir}/bonobo/servers"
|
|
|
|
|
|
|
|
FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
|
|
|
|
${datadir}/gnome/help"
|
|
|
|
SECTION_${PN}-doc = "doc"
|
|
|
|
|
|
|
|
FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
|
|
|
|
${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
|
|
|
|
${datadir}/aclocal ${base_libdir}/*.o"
|
|
|
|
SECTION_${PN}-dev = "devel"
|
|
|
|
ALLOW_EMPTY_${PN}-dev = "1"
|
|
|
|
RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
|
|
|
|
|
|
|
|
FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
|
|
|
|
SECTION_${PN}-staticdev = "devel"
|
|
|
|
RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<section id='usingpoky-extend-addpkg-postinstalls'>
|
|
|
|
<title>Post Install Scripts</title>
|
|
|
|
|
|
|
|
<para>
|
2011-03-18 00:28:20 +00:00
|
|
|
To add a post-installation script to a package, add a <filename>pkg_postinst_PACKAGENAME()
|
|
|
|
</filename> function to the <filename>.bb</filename> file and use
|
2010-10-28 21:29:17 +00:00
|
|
|
<filename>PACKAGENAME</filename> as the name of the package you want to attach to the
|
|
|
|
<filename>postinst</filename> script.
|
2012-02-06 17:39:17 +00:00
|
|
|
Normally
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
|
2012-04-25 20:30:17 +00:00
|
|
|
can be used, which automatically expands to <filename>PACKAGENAME</filename>.
|
2010-10-28 21:29:17 +00:00
|
|
|
A post-installation function has the following structure:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
pkg_postinst_PACKAGENAME () {
|
|
|
|
#!/bin/sh -e
|
|
|
|
# Commands to carry out
|
|
|
|
}
|
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
The script defined in the post-installation function is called when the
|
|
|
|
root filesystem is created.
|
2010-10-28 21:29:17 +00:00
|
|
|
If the script succeeds, the package is marked as installed.
|
|
|
|
If the script fails, the package is marked as unpacked and the script is
|
|
|
|
executed when the image boots again.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2010-10-28 21:29:17 +00:00
|
|
|
Sometimes it is necessary for the execution of a post-installation
|
|
|
|
script to be delayed until the first boot.
|
|
|
|
For example, the script might need to be executed on the device itself.
|
2010-11-11 21:40:30 +00:00
|
|
|
To delay script execution until boot time, use the following structure in the
|
2010-10-28 21:29:17 +00:00
|
|
|
post-installation script:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
pkg_postinst_PACKAGENAME () {
|
|
|
|
#!/bin/sh -e
|
|
|
|
if [ x"$D" = "x" ]; then
|
|
|
|
# Actions to carry out on the device go here
|
|
|
|
else
|
|
|
|
exit 1
|
|
|
|
fi
|
|
|
|
}
|
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2010-10-28 21:29:17 +00:00
|
|
|
The previous example delays execution until the image boots again because the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
|
2012-02-06 17:39:17 +00:00
|
|
|
variable points
|
2011-08-18 22:26:48 +00:00
|
|
|
to the directory containing the image when the root filesystem is created at build time but
|
2008-02-26 11:31:34 +00:00
|
|
|
is unset when executed on the first boot.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<section id="platdev-newmachine">
|
2012-07-02 16:59:11 +00:00
|
|
|
<title>Adding a New Machine</title>
|
2012-02-08 15:47:11 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
Adding a new machine to the Yocto Project is a straightforward process.
|
2010-11-04 21:12:46 +00:00
|
|
|
This section provides information that gives you an idea of the changes you must make.
|
2011-08-18 22:26:48 +00:00
|
|
|
The information covers adding machines similar to those the Yocto Project already supports.
|
|
|
|
Although well within the capabilities of the Yocto Project, adding a totally new architecture
|
|
|
|
might require
|
2011-09-26 18:02:36 +00:00
|
|
|
changes to <filename>gcc/eglibc</filename> and to the site information, which is
|
2010-11-11 21:40:30 +00:00
|
|
|
beyond the scope of this manual.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
2011-08-26 21:27:40 +00:00
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
For a complete example that shows how to add a new machine,
|
2011-08-26 21:27:40 +00:00
|
|
|
see the
|
2012-03-09 19:40:39 +00:00
|
|
|
"<ulink url='&YOCTO_DOCS_DEV_URL;#dev-manual-bsp-appendix'>BSP Development Example</ulink>"
|
2012-02-08 14:41:11 +00:00
|
|
|
in Appendix A.
|
2011-08-26 21:27:40 +00:00
|
|
|
</para>
|
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<section id="platdev-newmachine-conffile">
|
|
|
|
<title>Adding the Machine Configuration File</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
|
|
|
To add a machine configuration you need to add a <filename>.conf</filename> file
|
2010-11-11 21:40:30 +00:00
|
|
|
with details of the device being added to the <filename>conf/machine/</filename> file.
|
2012-07-02 16:59:11 +00:00
|
|
|
The name of the file determines the name the OpenEmbedded build system
|
|
|
|
uses to reference the new machine.
|
2010-11-04 21:12:46 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
The most important variables to set in this file are as follows:
|
|
|
|
<itemizedlist>
|
2012-03-09 19:40:39 +00:00
|
|
|
<listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>
|
2012-02-06 17:39:17 +00:00
|
|
|
TARGET_ARCH</ulink></filename> (e.g. "arm")</para></listitem>
|
2012-03-09 19:40:39 +00:00
|
|
|
<listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>
|
2012-02-06 17:39:17 +00:00
|
|
|
PREFERRED_PROVIDER</ulink></filename>_virtual/kernel (see below)</para></listitem>
|
2012-03-09 19:40:39 +00:00
|
|
|
<listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>
|
2012-04-23 19:22:37 +00:00
|
|
|
MACHINE_FEATURES</ulink></filename> (e.g. "apm screen wifi")</para></listitem>
|
2011-08-18 22:26:48 +00:00
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You might also need these variables:
|
|
|
|
<itemizedlist>
|
2012-03-09 19:40:39 +00:00
|
|
|
<listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLE'>
|
2012-02-06 17:39:17 +00:00
|
|
|
SERIAL_CONSOLE</ulink></filename> (e.g. "115200 ttyS0")</para></listitem>
|
2012-03-09 19:40:39 +00:00
|
|
|
<listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>
|
2012-02-06 17:39:17 +00:00
|
|
|
KERNEL_IMAGETYPE</ulink></filename> (e.g. "zImage")</para></listitem>
|
2012-03-09 19:40:39 +00:00
|
|
|
<listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>
|
2012-02-06 17:39:17 +00:00
|
|
|
IMAGE_FSTYPES</ulink></filename> (e.g. "tar.gz jffs2")</para></listitem>
|
2011-08-18 22:26:48 +00:00
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-11-04 21:12:46 +00:00
|
|
|
You can find full details on these variables in the reference section.
|
|
|
|
You can leverage many existing machine <filename>.conf</filename> files from
|
|
|
|
<filename>meta/conf/machine/</filename>.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-newmachine-kernel">
|
|
|
|
<title>Adding a Kernel for the Machine</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
The OpenEmbedded build system needs to be able to build a kernel for the machine.
|
2010-11-04 21:12:46 +00:00
|
|
|
You need to either create a new kernel recipe for this machine, or extend an
|
|
|
|
existing recipe.
|
2011-08-18 22:26:48 +00:00
|
|
|
You can find several kernel examples in the
|
2012-07-02 16:59:11 +00:00
|
|
|
source directory at <filename>meta/recipes-kernel/linux</filename>
|
|
|
|
that you can use as references.
|
2010-11-04 21:12:46 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
2011-08-18 22:26:48 +00:00
|
|
|
If you are creating a new recipe, normal recipe-writing rules apply for setting
|
2012-02-06 17:39:17 +00:00
|
|
|
up a
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
|
2011-08-18 22:26:48 +00:00
|
|
|
Thus, you need to specify any necessary patches and set
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> to point at the source code.
|
2011-08-18 22:26:48 +00:00
|
|
|
You need to create a <filename>configure</filename> task that configures the
|
|
|
|
unpacked kernel with a defconfig.
|
|
|
|
You can do this by using a <filename>make defconfig</filename> command or,
|
|
|
|
more commonly, by copying in a suitable <filename>defconfig</filename> file and and then running
|
2010-11-04 21:12:46 +00:00
|
|
|
<filename>make oldconfig</filename>.
|
2011-08-18 22:26:48 +00:00
|
|
|
By making use of <filename>inherit kernel</filename> and potentially some of the
|
2010-11-04 21:12:46 +00:00
|
|
|
<filename>linux-*.inc</filename> files, most other functionality is
|
|
|
|
centralized and the the defaults of the class normally work well.
|
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
|
|
|
If you are extending an existing kernel, it is usually a matter of adding a
|
2011-08-18 22:26:48 +00:00
|
|
|
suitable defconfig file.
|
|
|
|
The file needs to be added into a location similar to defconfig files
|
2010-11-04 21:12:46 +00:00
|
|
|
used for other machines in a given kernel.
|
|
|
|
A possible way to do this is by listing the file in the
|
2011-08-18 22:26:48 +00:00
|
|
|
<filename>SRC_URI</filename> and adding the machine to the expression in
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
COMPATIBLE_MACHINE = '(qemux86|qemumips)'
|
|
|
|
</literallayout>
|
2010-11-04 21:12:46 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<section id="platdev-newmachine-formfactor">
|
|
|
|
<title>Adding a Formfactor Configuration File</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
|
|
|
A formfactor configuration file provides information about the
|
2012-07-02 16:59:11 +00:00
|
|
|
target hardware for which the image is being built and information that
|
|
|
|
the build system cannot obtain from other sources such as the kernel.
|
2010-11-04 21:12:46 +00:00
|
|
|
Some examples of information contained in a formfactor configuration file include
|
|
|
|
framebuffer orientation, whether or not the system has a keyboard,
|
|
|
|
the positioning of the keyboard in relation to the screen, and
|
2010-11-11 21:40:30 +00:00
|
|
|
the screen resolution.
|
2010-11-04 21:12:46 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
The build system uses reasonable defaults in most cases, but if customization is
|
2010-11-04 21:12:46 +00:00
|
|
|
necessary you need to create a <filename>machconfig</filename> file
|
2012-07-02 16:59:11 +00:00
|
|
|
in the <filename>meta/recipes-bsp/formfactor/files</filename>
|
2011-08-18 22:26:48 +00:00
|
|
|
directory.
|
|
|
|
This directory contains directories for specific machines such as
|
|
|
|
<filename>qemuarm</filename> and <filename>qemux86</filename>.
|
|
|
|
For information about the settings available and the defaults, see the
|
|
|
|
<filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
|
|
|
|
same area.
|
2010-11-04 21:12:46 +00:00
|
|
|
Following is an example for qemuarm:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
HAVE_TOUCHSCREEN=1
|
|
|
|
HAVE_KEYBOARD=1
|
|
|
|
|
|
|
|
DISPLAY_CAN_ROTATE=0
|
|
|
|
DISPLAY_ORIENTATION=0
|
|
|
|
#DISPLAY_WIDTH_PIXELS=640
|
|
|
|
#DISPLAY_HEIGHT_PIXELS=480
|
|
|
|
#DISPLAY_BPP=16
|
|
|
|
DISPLAY_DPI=150
|
|
|
|
DISPLAY_SUBPIXEL_ORDER=vrgb
|
|
|
|
</literallayout>
|
2010-11-04 21:12:46 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2008-02-26 11:31:34 +00:00
|
|
|
</section>
|
|
|
|
|
2011-12-08 21:22:23 +00:00
|
|
|
<section id="building-multiple-architecture-libraries-into-one-image">
|
2011-12-08 21:24:33 +00:00
|
|
|
<title>Combining Multiple Versions of Library Files into One Image</title>
|
2011-12-08 21:22:23 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
The build system offers the ability to build libraries with different
|
|
|
|
target optimizations or architecture formats and combine these together
|
|
|
|
into one system image.
|
|
|
|
You can link different binaries in the image
|
|
|
|
against the different libraries as needed for specific use cases.
|
|
|
|
This feature is called "Multilib."
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
An example would be where you have most of a system compiled in 32-bit
|
|
|
|
mode using 32-bit libraries, but you have something large, like a database
|
|
|
|
engine, that needs to be a 64-bit application and use 64-bit libraries.
|
|
|
|
Multilib allows you to get the best of both 32-bit and 64-bit libraries.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
While the Multilib feature is most commonly used for 32 and 64-bit differences,
|
|
|
|
the approach the build system uses facilitates different target optimizations.
|
|
|
|
You could compile some binaries to use one set of libraries and other binaries
|
|
|
|
to use other different sets of libraries.
|
|
|
|
The libraries could differ in architecture, compiler options, or other
|
|
|
|
optimizations.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This section overviews the Multilib process only.
|
|
|
|
For more details on how to implement Multilib, see the
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
|
2011-12-08 21:22:23 +00:00
|
|
|
page.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='preparing-to-use-multilib'>
|
|
|
|
<title>Preparing to use Multilib</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
User-specific requirements drive the Multilib feature,
|
|
|
|
Consequently, there is no one "out-of-the-box" configuration that likely
|
|
|
|
exists to meet your needs.
|
2010-11-04 21:12:46 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
In order to enable Multilib, you first need to ensure your recipe is
|
|
|
|
extended to support multiple libraries.
|
|
|
|
Many standard recipes are already extended and support multiple libraries.
|
|
|
|
You can check in the <filename>meta/conf/multilib.conf</filename>
|
2012-07-02 16:59:11 +00:00
|
|
|
configuration file in the source directory to see how this is
|
2011-12-08 21:22:23 +00:00
|
|
|
done using the <filename>BBCLASSEXTEND</filename> variable.
|
|
|
|
Eventually, all recipes will be covered and this list will be unneeded.
|
2010-06-08 16:18:29 +00:00
|
|
|
</para>
|
2011-12-08 21:22:23 +00:00
|
|
|
|
2010-06-08 16:18:29 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
For the most part, the Multilib class extension works automatically to
|
|
|
|
extend the package name from <filename>${PN}</filename> to
|
|
|
|
<filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
|
|
|
|
is the particular multilib (e.g. "lib32-" or "lib64-").
|
|
|
|
Standard variables such as <filename>DEPENDS</filename>,
|
|
|
|
<filename>RDEPENDS</filename>, <filename>RPROVIDES</filename>,
|
|
|
|
<filename>RRECOMMENDS</filename>, <filename>PACKAGES</filename>, and
|
|
|
|
<filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
|
|
|
|
If you are extending any manual code in the recipe, you can use the
|
|
|
|
<filename>${MLPREFIX}</filename> variable to ensure those names are extended
|
|
|
|
correctly.
|
|
|
|
This automatic extension code resides in <filename>multilib.bbclass</filename>.
|
2009-04-28 07:24:47 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-12-08 21:22:23 +00:00
|
|
|
<section id='using-multilib'>
|
|
|
|
<title>Using Multilib</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-04 21:12:46 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
After you have set up the recipes, you need to define the actual
|
|
|
|
combination of multiple libraries you want to build.
|
|
|
|
You accomplish this through your <filename>local.conf</filename>
|
2012-02-22 19:51:35 +00:00
|
|
|
configuration file in the
|
2012-07-02 16:59:11 +00:00
|
|
|
<link linkend='build-directory'>build directory</link>.
|
2011-12-08 21:22:23 +00:00
|
|
|
An example configuration would be as follows:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
2011-12-08 21:22:23 +00:00
|
|
|
MACHINE = "qemux86-64"
|
|
|
|
require conf/multilib.conf
|
|
|
|
MULTILIBS = "multilib:lib32"
|
|
|
|
DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
|
2012-04-02 22:25:15 +00:00
|
|
|
IMAGE_INSTALL = "lib32-connman"
|
2011-08-18 22:26:48 +00:00
|
|
|
</literallayout>
|
2011-12-08 21:22:23 +00:00
|
|
|
This example enables an
|
|
|
|
additional library named <filename>lib32</filename> alongside the
|
|
|
|
normal target packages.
|
|
|
|
When combining these "lib32" alternatives, the example uses "x86" for tuning.
|
|
|
|
For information on this particular tuning, see
|
|
|
|
<filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
|
2011-08-18 22:26:48 +00:00
|
|
|
</para>
|
2010-09-09 09:00:31 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
The example then includes <filename>lib32-connman</filename>
|
|
|
|
in all the images, which illustrates one method of including a
|
|
|
|
multiple library dependency.
|
|
|
|
You can use a normal image build to include this dependency,
|
|
|
|
for example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ bitbake core-image-sato
|
|
|
|
</literallayout>
|
|
|
|
You can also build Multilib packages specifically with a command like this:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ bitbake lib32-connman
|
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2011-12-08 21:22:23 +00:00
|
|
|
<section id='additional-implementation-details'>
|
|
|
|
<title>Additional Implementation Details</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
Different packaging systems have different levels of native Multilib
|
|
|
|
support.
|
|
|
|
For the RPM Package Management System, the following implementation details
|
|
|
|
exist:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>A unique architecture is defined for the Multilib packages,
|
|
|
|
along with creating a unique deploy folder under
|
2012-02-22 19:51:35 +00:00
|
|
|
<filename>tmp/deploy/rpm</filename> in the
|
2012-07-02 16:59:11 +00:00
|
|
|
<link linkend='build-directory'>build directory</link>.
|
2011-12-08 21:22:23 +00:00
|
|
|
For example, consider <filename>lib32</filename> in a
|
|
|
|
<filename>qemux86-64</filename> image.
|
|
|
|
The possible architectures in the system are "all", "qemux86_64",
|
|
|
|
"lib32_qemux86_64", and "lib32_x86".</para></listitem>
|
|
|
|
<listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
|
|
|
|
<filename>${PN}</filename> during RPM packaging.
|
|
|
|
The naming for a normal RPM package and a Multilib RPM package in a
|
|
|
|
<filename>qemux86-64</filename> system resolves to something similar to
|
|
|
|
<filename>bash-4.1-r2.x86_64.rpm</filename> and
|
|
|
|
<filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para>When installing a Multilib image, the RPM backend first
|
|
|
|
installs the base image and then installs the Multilib libraries.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para>The build system relies on RPM to resolve the identical files in the
|
|
|
|
two (or more) Multilib packages.</para></listitem>
|
|
|
|
</itemizedlist>
|
2010-11-04 21:12:46 +00:00
|
|
|
</para>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2010-11-15 16:27:07 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
For the IPK Package Management System, the following implementation details exist:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
|
|
|
|
<filename>${PN}</filename> during IPK packaging.
|
|
|
|
The naming for a normal RPM package and a Multilib IPK package in a
|
|
|
|
<filename>qemux86-64</filename> system resolves to something like
|
|
|
|
<filename>bash_4.1-r2.x86_64.ipk</filename> and
|
|
|
|
<filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para>The IPK deploy folder is not modified with
|
|
|
|
<filename>${MLPREFIX}</filename> because packages with and without
|
|
|
|
the Multilib feature can exist in the same folder due to the
|
|
|
|
<filename>${PN}</filename> differences.</para></listitem>
|
|
|
|
<listitem><para>IPK defines a sanity check for Multilib installation
|
|
|
|
using certain rules for file comparison, overridden, etc.
|
|
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
2011-02-01 21:09:12 +00:00
|
|
|
</para>
|
2011-12-08 21:22:23 +00:00
|
|
|
</section>
|
|
|
|
</section>
|
2011-08-18 22:26:48 +00:00
|
|
|
|
2012-02-14 16:12:32 +00:00
|
|
|
<section id='configuring-the-kernel'>
|
|
|
|
<title>Configuring the Kernel</title>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 17:19:10 +00:00
|
|
|
Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
|
2012-02-14 16:12:32 +00:00
|
|
|
file has all the right information in it for the image you are building.
|
|
|
|
You can use the <filename>menuconfig</filename> tool and configuration fragments to
|
|
|
|
make sure your <filename>.config</filename> file is just how you need it.
|
|
|
|
This section describes how to use <filename>menuconfig</filename>, create and use
|
2012-03-19 18:06:27 +00:00
|
|
|
configuration fragments, and how to interactively tweak your <filename>.config</filename>
|
2012-02-14 16:12:32 +00:00
|
|
|
file to create the leanest kernel configuration file possible.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For concepts on kernel configuration, see the
|
2012-03-09 19:40:39 +00:00
|
|
|
"<ulink url='&YOCTO_DOCS_KERNEL_URL;#kernel-configuration'>Kernel Configuration</ulink>"
|
2012-02-14 16:12:32 +00:00
|
|
|
section in the Yocto Project Kernel Architecture and Use Manual.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='using-menuconfig'>
|
|
|
|
<title>Using <filename>menuconfig</filename></title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The easiest way to define kernel configurations is to set them through the
|
|
|
|
<filename>menuconfig</filename> tool.
|
|
|
|
For general information on <filename>menuconfig</filename>, see
|
|
|
|
<ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To use the <filename>menuconfig</filename> tool in the Yocto Project development
|
|
|
|
environment, you must build the tool using BitBake.
|
|
|
|
The following commands build and invoke <filename>menuconfig</filename> assuming the
|
2012-07-02 16:59:11 +00:00
|
|
|
source directory top-level folder is <filename>~/poky</filename>:
|
2012-02-14 16:12:32 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ cd ~/poky
|
|
|
|
$ source oe-init-build-env
|
|
|
|
$ bitbake linux-yocto -c menuconfig
|
|
|
|
</literallayout>
|
|
|
|
Once <filename>menuconfig</filename> comes up, its standard interface allows you to
|
|
|
|
examine and configure all the kernel configuration parameters.
|
|
|
|
Once you have made your changes, simply exit the tool and save your changes to
|
|
|
|
create an updated version of the <filename>.config</filename> configuration file.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 09:36:15 +00:00
|
|
|
For an example that shows how to change a specific kernel option
|
2012-02-14 16:12:32 +00:00
|
|
|
using <filename>menuconfig</filename>, see the
|
|
|
|
"<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing
|
|
|
|
the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>"
|
|
|
|
section.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='creating-config-fragments'>
|
2012-07-19 17:54:45 +00:00
|
|
|
<title>Creating Configuration Fragments</title>
|
2012-02-14 16:12:32 +00:00
|
|
|
|
|
|
|
<para>
|
2012-07-19 17:54:45 +00:00
|
|
|
Configuration fragments are simply kernel options that appear in a file
|
|
|
|
placed where the OpenEmbedded build system can find and apply them.
|
2012-02-14 16:12:32 +00:00
|
|
|
Syntactically, the configuration statement is identical to what would appear
|
2012-07-19 17:54:45 +00:00
|
|
|
in the <filename>.config</filename> file, which is in the
|
|
|
|
<link linkend='build-directory'>build directory</link> in
|
|
|
|
<filename>tmp/work/<arch>-poky-linux/linux-yocto-<release-specific-string>/linux-<arch>-<build-type></filename>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It is simple to create a configuration fragment.
|
|
|
|
For example, issuing the following from the shell creates a configuration fragment
|
2012-02-14 16:12:32 +00:00
|
|
|
file named <filename>my_smp.cfg</filename> that enables multi-processor support
|
|
|
|
within the kernel:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ echo "CONFIG_SMP=y" >> my_smp.cfg
|
|
|
|
</literallayout>
|
2012-07-19 17:54:45 +00:00
|
|
|
<note>
|
|
|
|
All configuration files must use the <filename>.cfg</filename> extension in order
|
|
|
|
for the OpenEmbedded build system to recognize them as a configuration fragment.
|
|
|
|
</note>
|
2012-02-14 16:12:32 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Where do you put your configuration files?
|
2012-03-13 18:34:30 +00:00
|
|
|
You can place these configuration files in the same area pointed to by
|
|
|
|
<filename>SRC_URI</filename>.
|
2012-07-02 16:59:11 +00:00
|
|
|
The OpenEmbedded build system will pick up the configuration and add it to the
|
2012-02-14 16:12:32 +00:00
|
|
|
kernel's configuration.
|
2012-07-19 17:54:45 +00:00
|
|
|
For example, suppose you had a set of configuration options in a file called
|
|
|
|
<filename>myconfig.cfg</filename>.
|
|
|
|
If you put that file inside a directory named <filename>/linux-yocto</filename>
|
|
|
|
that resides in the same directory as the kernel's append file and then add
|
|
|
|
a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
|
|
|
|
those configuration options will be picked up and applied when the kernel is built.
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRC_URI += "file://myconfig.cfg"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As mentioned earlier, you can group related configurations into multiple files and
|
|
|
|
name them all in the <filename>SRC_URI</filename> statement as well.
|
|
|
|
For example, you could group separate configurations specifically for Ethernet and graphics
|
|
|
|
into their own files and add those by using a <filename>SRC_URI</filename> statement like the
|
|
|
|
following in your append file:
|
2012-02-14 16:12:32 +00:00
|
|
|
<literallayout class='monospaced'>
|
2012-07-19 17:54:45 +00:00
|
|
|
SRC_URI += "file://myconfig.cfg \
|
|
|
|
file://eth.cfg \
|
|
|
|
file://gfx.cfg"
|
2012-02-14 16:12:32 +00:00
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='fine-tuning-the-kernel-configuration-file'>
|
|
|
|
<title>Fine-tuning the Kernel Configuration File</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You can make sure the <filename>.config</filename> is as lean or efficient as
|
|
|
|
possible by reading the output of the kernel configuration fragment audit,
|
|
|
|
noting any issues, making changes to correct the issues, and then repeating.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 17:19:10 +00:00
|
|
|
As part of the kernel build process, the
|
2012-02-14 16:12:32 +00:00
|
|
|
<filename>kernel_configcheck</filename> task runs.
|
|
|
|
This task validates the kernel configuration by checking the final
|
|
|
|
<filename>.config</filename> file against the input files.
|
|
|
|
During the check, the task produces warning messages for the following
|
|
|
|
issues:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Requested options that did not make the final
|
|
|
|
<filename>.config</filename> file.</para></listitem>
|
|
|
|
<listitem><para>Configuration items that appear twice in the same
|
|
|
|
configuration fragment.</para></listitem>
|
|
|
|
<listitem><para>Configuration items tagged as 'required' were overridden.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para>A board overrides a non-board specific option.</para></listitem>
|
|
|
|
<listitem><para>Listed options not valid for the kernel being processed.
|
|
|
|
In other words, the option does not appear anywhere.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
<note>
|
|
|
|
The <filename>kernel_configcheck</filename> task can also optionally report
|
|
|
|
if an option is overridden during processing.
|
|
|
|
</note>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For each output warning, a message points to the file
|
|
|
|
that contains a list of the options and a pointer to the config
|
|
|
|
fragment that defines them.
|
2012-03-19 18:06:27 +00:00
|
|
|
Collectively, the files are the key to streamlining the configuration.
|
2012-02-14 16:12:32 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To streamline the configuration, do the following:
|
|
|
|
<orderedlist>
|
|
|
|
<listitem><para>Start with a full configuration that you know
|
|
|
|
works - it builds and boots successfully.
|
|
|
|
This configuration file will be your baseline.</para></listitem>
|
|
|
|
<listitem><para>Separately run the <filename>configme</filename> and
|
|
|
|
<filename>kernel_configcheck</filename> tasks.</para></listitem>
|
|
|
|
<listitem><para>Take the resulting list of files from the
|
|
|
|
<filename>kernel_configcheck</filename> task warnings and do the following:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Drop values that are redefined in the fragment but do not
|
|
|
|
change the final <filename>.config</filename> file.</para></listitem>
|
|
|
|
<listitem><para>Analyze and potentially drop values from the
|
|
|
|
<filename>.config</filename> file that override required
|
|
|
|
configurations.</para></listitem>
|
|
|
|
<listitem><para>Analyze and potentially remove non-board specific options.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para>Remove repeated and invalid options.</para></listitem>
|
|
|
|
</itemizedlist></para></listitem>
|
|
|
|
<listitem><para>After you have worked through the output of the kernel configuration
|
|
|
|
audit, you can re-run the <filename>configme</filename>
|
|
|
|
and <filename>kernel_configcheck</filename> tasks to see the results of your
|
|
|
|
changes.
|
|
|
|
If you have more issues, you can deal with them as described in the
|
|
|
|
previous step.</para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Iteratively working through steps two through four eventually yields
|
|
|
|
a minimal, streamlined configuration file.
|
|
|
|
Once you have the best <filename>.config</filename>, you can build the Linux
|
|
|
|
Yocto kernel.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
2012-03-05 19:09:31 +00:00
|
|
|
<section id="usingpoky-changes-updatingimages">
|
|
|
|
<title>Updating Existing Images</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Often, rather than re-flashing a new image, you might wish to install updated
|
|
|
|
packages into an existing running system.
|
|
|
|
You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory
|
|
|
|
through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename>
|
|
|
|
to point at the shared server.
|
|
|
|
Following is an example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
|
|
|
|
$ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
|
|
|
|
$ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="usingpoky-changes-prbump">
|
|
|
|
<title>Incrementing a Package Revision Number</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If a committed change results in changing the package output,
|
|
|
|
then the value of the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
|
2012-03-05 19:09:31 +00:00
|
|
|
variable needs to be increased
|
|
|
|
(or "bumped") as part of that commit.
|
|
|
|
This means that for new recipes you must be sure to add the <filename>PR</filename>
|
|
|
|
variable and set its initial value equal to "r0".
|
|
|
|
Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
|
|
|
|
Note that you can only use integer values following the "r" in the
|
|
|
|
<filename>PR</filename> variable.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If you are sharing a common <filename>.inc</filename> file with multiple recipes,
|
|
|
|
you can also use the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
|
2012-03-05 19:09:31 +00:00
|
|
|
variable to ensure that
|
|
|
|
the recipes sharing the <filename>.inc</filename> file are rebuilt when the
|
|
|
|
<filename>.inc</filename> file itself is changed.
|
|
|
|
The <filename>.inc</filename> file must set <filename>INC_PR</filename>
|
|
|
|
(initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
|
|
|
|
to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
|
|
|
|
If the <filename>.inc</filename> file is changed then its
|
|
|
|
<filename>INC_PR</filename> should be incremented.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
When upgrading the version of a package, assuming the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
|
2012-03-05 19:09:31 +00:00
|
|
|
changes, the <filename>PR</filename> variable should be reset to "r0"
|
|
|
|
(or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Usually, version increases occur only to packages.
|
|
|
|
However, if for some reason <filename>PV</filename> changes but does not
|
|
|
|
increase, you can increase the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
|
2012-03-05 19:09:31 +00:00
|
|
|
variable (Package Epoch).
|
|
|
|
The <filename>PE</filename> variable defaults to "0".
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Version numbering strives to follow the
|
|
|
|
<ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
|
|
|
|
Debian Version Field Policy Guidelines</ulink>.
|
|
|
|
These guidelines define how versions are compared and what "increasing" a version means.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There are two reasons for following the previously mentioned guidelines.
|
|
|
|
First, to ensure that when a developer updates and rebuilds, they get all the changes to
|
|
|
|
the repository and do not have to remember to rebuild any sections.
|
|
|
|
Second, to ensure that target users are able to upgrade their
|
|
|
|
devices using package manager commands such as <filename>opkg upgrade</filename>
|
|
|
|
(or similar commands for dpkg/apt or rpm-based systems).
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2011-12-08 21:22:23 +00:00
|
|
|
<section id="usingpoky-configuring-DISTRO_PN_ALIAS">
|
|
|
|
<title>Handling a Package Name Alias</title>
|
2011-08-18 22:26:48 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
Sometimes a package name you are using might exist under an alias or as a similarly named
|
|
|
|
package in a different distribution.
|
2012-07-02 16:59:11 +00:00
|
|
|
The OpenEmbedded build system implements a <filename>distro_check</filename>
|
2011-12-08 21:22:23 +00:00
|
|
|
task that automatically connects to major distributions
|
|
|
|
and checks for these situations.
|
|
|
|
If the package exists under a different name in a different distribution, you get a
|
|
|
|
<filename>distro_check</filename> mismatch.
|
|
|
|
You can resolve this problem by defining a per-distro recipe name alias using the
|
2012-03-09 19:40:39 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
|
2012-02-06 17:39:17 +00:00
|
|
|
variable.
|
2011-08-18 22:26:48 +00:00
|
|
|
</para>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
|
|
|
|
variable:
|
2011-08-18 22:26:48 +00:00
|
|
|
<literallayout class='monospaced'>
|
2011-12-08 21:22:23 +00:00
|
|
|
DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
|
|
|
|
distro2=package_name_alias2 \
|
|
|
|
distro3=package_name_alias3 \
|
|
|
|
..."
|
2011-08-18 22:26:48 +00:00
|
|
|
</literallayout>
|
|
|
|
</para>
|
2011-12-08 21:22:23 +00:00
|
|
|
|
2011-08-18 22:26:48 +00:00
|
|
|
<para>
|
2011-12-08 21:22:23 +00:00
|
|
|
If you have more than one distribution alias, separate them with a space.
|
2012-07-02 16:59:11 +00:00
|
|
|
Note that the build system currently automatically checks the
|
2011-12-08 21:22:23 +00:00
|
|
|
Fedora, OpenSuSE, Debian, Ubuntu,
|
|
|
|
and Mandriva distributions for source package recipes without having to specify them
|
|
|
|
using the <filename>DISTRO_PN_ALIAS</filename> variable.
|
|
|
|
For example, the following command generates a report that lists the Linux distributions
|
2012-07-02 16:59:11 +00:00
|
|
|
that include the sources for each of the recipes.
|
2011-12-08 21:22:23 +00:00
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ bitbake world -f -c distro_check
|
|
|
|
</literallayout>
|
|
|
|
The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
|
2012-07-02 16:59:11 +00:00
|
|
|
file found in the source directory.
|
2011-08-18 22:26:48 +00:00
|
|
|
</para>
|
2010-05-26 14:26:09 +00:00
|
|
|
</section>
|
2010-11-04 21:12:46 +00:00
|
|
|
|
2012-02-28 18:13:06 +00:00
|
|
|
<section id="building-software-from-an-external-source">
|
|
|
|
<title>Building Software from an External Source</title>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
By default, the OpenEmbedded build system does its work from within the
|
|
|
|
<link linkend='build-directory'>build directory</link>.
|
2012-02-28 18:13:06 +00:00
|
|
|
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
|
2012-07-02 16:59:11 +00:00
|
|
|
and thus outside of the <link linkend='source-directory'>source directory</link>.
|
2012-02-28 18:13:06 +00:00
|
|
|
For example, suppose you have a project that includes a new BSP with a heavily customized
|
|
|
|
kernel, a very minimal image, and some new user-space recipes.
|
2012-07-02 16:59:11 +00:00
|
|
|
And, you want to minimize the exposure to the build system to the
|
2012-02-28 18:13:06 +00:00
|
|
|
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
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
|
2012-02-28 18:13:06 +00:00
|
|
|
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
|
|
|
|
change your recipe so that it inherits the
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>
|
2012-02-28 18:13:06 +00:00
|
|
|
class and then sets the
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
|
2012-02-28 18:13:06 +00:00
|
|
|
variable to point to your external source code.
|
|
|
|
Here are the statements to put in your recipe:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
inherit externalsrc
|
|
|
|
S = "/some/path/to/your/package/source"
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It is important to know that the <filename>externalsrc.bbclass</filename> assumes that the
|
|
|
|
source directory <filename>S</filename> and the build directory
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-B'><filename>B</filename></ulink>
|
2012-02-28 18:13:06 +00:00
|
|
|
are different even though by default these directories are the same.
|
|
|
|
This assumption is important because it supports building different variants of the recipe
|
|
|
|
by using the
|
2012-03-09 19:40:39 +00:00
|
|
|
<ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
|
2012-02-28 18:13:06 +00:00
|
|
|
variable.
|
|
|
|
You could allow the build directory to be the same as the source directory but you would
|
|
|
|
not be able to build more than one variant of the recipe.
|
|
|
|
Consequently, if you are building multiple variants of the recipe, you need to establish a
|
|
|
|
build directory that is different than the source directory.
|
|
|
|
</para>
|
|
|
|
</section>
|
2012-03-29 21:54:55 +00:00
|
|
|
|
2012-03-30 14:33:09 +00:00
|
|
|
<section id='excluding-recipes-from-the-build'>
|
|
|
|
<title>Excluding Recipes From the Build</title>
|
2012-03-29 21:54:55 +00:00
|
|
|
|
2012-03-29 22:07:23 +00:00
|
|
|
<para>
|
|
|
|
You might find that there are groups of recipes you want to filter
|
|
|
|
out of the build process.
|
|
|
|
For example, recipes you know you will never use or want should not
|
|
|
|
be part of the build.
|
|
|
|
Removing these recipes from parsing speeds up parts of the build.
|
|
|
|
</para>
|
|
|
|
|
2012-03-29 21:54:55 +00:00
|
|
|
<para>
|
|
|
|
It is possible to filter or mask out <filename>.bb</filename> and
|
2012-03-29 22:07:23 +00:00
|
|
|
<filename>.bbappend</filename> files.
|
2012-03-29 21:54:55 +00:00
|
|
|
You can do this by providing an expression with the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'>BBMASK</ulink></filename>
|
|
|
|
variable.
|
|
|
|
Here is an example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
BBMASK = ".*/meta-mymachine/recipes-maybe/"
|
|
|
|
</literallayout>
|
|
|
|
Here, all <filename>.bb</filename> and <filename>.bbappend</filename> files
|
|
|
|
in the directory that match the expression are ignored during the build
|
2012-03-29 22:07:23 +00:00
|
|
|
process.
|
2012-03-29 21:54:55 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
2012-06-18 16:23:29 +00:00
|
|
|
|
2012-07-13 20:52:36 +00:00
|
|
|
<section id="platdev-appdev-srcrev">
|
|
|
|
<title>Using an External SCM</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If you're working on a recipe that pulls from an external Source Code Manager (SCM), it
|
|
|
|
is possible to have the OpenEmbedded build system notice new changes added to the
|
|
|
|
SCM and then build the package that depends on them using the latest version.
|
|
|
|
This only works for SCMs from which it is possible to get a sensible revision number for changes.
|
|
|
|
Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To enable this behavior, simply add the following to the <filename>local.conf</filename>
|
|
|
|
configuration file found in the
|
|
|
|
<ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>build directory</ulink>:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
SRCREV_pn-<PN> = "${AUTOREV}"
|
|
|
|
</literallayout>
|
|
|
|
where <filename>PN</filename>
|
|
|
|
is the name of the package for which you want to enable automatic source
|
|
|
|
revision updating.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
2012-06-18 16:23:29 +00:00
|
|
|
<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 help 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 by default is
|
|
|
|
installed in sdk images.
|
2012-07-16 21:54:43 +00:00
|
|
|
See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
|
2012-06-18 16:23:29 +00:00
|
|
|
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 <filename>-dbg</filename> packages for the applications
|
|
|
|
you are going to debug.
|
|
|
|
Doing so makes available extra debug symbols 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.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To help get past the previously mentioned constraints, you can use Gdbserver.
|
|
|
|
Gdbserver 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, the
|
|
|
|
user has 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>
|
|
|
|
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdbserver">
|
|
|
|
<title>Launching Gdbserver on the Target</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
First, make sure Gdbserver is installed on the target.
|
|
|
|
If it is not, install the package <filename>gdbserver</filename>, which needs the
|
|
|
|
<filename>libthread-db1</filename> package.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As an example, to launch Gdbserver on the target and make it ready to "debug" a
|
|
|
|
program located at <filename>/path/to/inferior</filename>, connect
|
|
|
|
to the target and launch:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ gdbserver localhost:2345 /path/to/inferior
|
|
|
|
</literallayout>
|
|
|
|
Gdbserver should now be listening on port 2345 for debugging
|
|
|
|
commands coming from a remote GDB process that is running on the host computer.
|
|
|
|
Communication between Gdbserver and the host GDB are done using TCP.
|
|
|
|
To use other communication protocols, please refer to the
|
|
|
|
<ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb">
|
|
|
|
<title>Launching GDB on the Host Computer</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Running GDB on the host computer takes a number of stages.
|
|
|
|
This section describes those stages.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
|
|
|
|
<title>Building the Cross-GDB Package</title>
|
|
|
|
<para>
|
|
|
|
A suitable GDB cross-binary is required that runs on your host computer but
|
|
|
|
also knows about the the ABI of the remote target.
|
2012-07-02 16:59:11 +00:00
|
|
|
You can get this binary from the meta-toolchain.
|
2012-06-18 16:23:29 +00:00
|
|
|
Here is an example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
/usr/local/poky/eabi-glibc/arm/bin/arm-poky-linux-gnueabi-gdb
|
|
|
|
</literallayout>
|
|
|
|
where <filename>arm</filename> is the target architecture and
|
|
|
|
<filename>linux-gnueabi</filename> the target ABI.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
Alternatively, you can use BitBake to build the <filename>gdb-cross</filename> binary.
|
2012-06-18 16:23:29 +00:00
|
|
|
Here is an example:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ bitbake gdb-cross
|
|
|
|
</literallayout>
|
|
|
|
Once the binary is built, you can find it here:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
tmp/sysroots/<host-arch>/usr/bin/<target-abi>-gdb
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb-inferiorbins">
|
|
|
|
<title>Making the Inferior Binaries Available</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The inferior binary (complete with all debugging symbols) as well as any
|
|
|
|
libraries (and their debugging symbols) on which the inferior binary depends
|
|
|
|
need to be available.
|
|
|
|
There are a number of ways you can make these available.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Perhaps the easiest way is to have an 'sdk' image that corresponds to the plain
|
|
|
|
image installed on the device.
|
|
|
|
In the case of <filename>core-image-sato</filename>,
|
|
|
|
<filename>core-image-sato-sdk</filename> would contain suitable symbols.
|
|
|
|
Because the sdk images already have the debugging symbols installed, it is just a
|
|
|
|
question of expanding the archive to some location and then informing GDB.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
Alternatively, the OpenEmbedded build system can build a custom directory of files
|
|
|
|
for a specific
|
2012-06-18 16:23:29 +00:00
|
|
|
debugging purpose by reusing its <filename>tmp/rootfs</filename> directory.
|
|
|
|
This directory contains the contents of the last built image.
|
|
|
|
This process assumes two things:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>The image running on the target was the last image to
|
2012-07-02 16:59:11 +00:00
|
|
|
be built.</para></listitem>
|
2012-06-18 16:23:29 +00:00
|
|
|
<listitem><para>The package (<filename>foo</filename> in the following
|
|
|
|
example) that contains the inferior binary to be debugged has been built
|
|
|
|
without optimization and has debugging information available.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The following steps show how to build the custom directory of files:
|
|
|
|
<orderedlist>
|
|
|
|
<listitem><para>Install the package (<filename>foo</filename> in this case) to
|
|
|
|
<filename>tmp/rootfs</filename>:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
|
|
|
|
tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf -o \
|
|
|
|
tmp/rootfs/ update
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
<listitem><para>Install the debugging information:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
|
|
|
|
tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \
|
|
|
|
-o tmp/rootfs install foo
|
|
|
|
|
|
|
|
$ tmp/sysroots/i686-linux/usr/bin/opkg-cl -f \
|
|
|
|
tmp/work/<target-abi>/core-image-sato-1.0-r0/temp/opkg.conf \
|
|
|
|
-o tmp/rootfs install foo-dbg
|
|
|
|
</literallayout></para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
|
|
|
|
<title>Launch the Host GDB</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To launch the host GDB, you run the <filename>cross-gdb</filename> binary and provide
|
|
|
|
the inferior binary as part of the command line.
|
|
|
|
For example, the following command form continues with the example used in
|
|
|
|
the previous section.
|
|
|
|
This command form loads the <filename>foo</filename> binary
|
|
|
|
as well as the debugging information:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ <target-abi>-gdb rootfs/usr/bin/foo
|
|
|
|
</literallayout>
|
|
|
|
Once the GDB prompt appears, you must instruct GDB to load all the libraries
|
|
|
|
of the inferior binary from <filename>tmp/rootfs</filename> as follows:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ set solib-absolute-prefix /path/to/tmp/rootfs
|
|
|
|
</literallayout>
|
|
|
|
The pathname <filename>/path/to/tmp/rootfs</filename> must either be
|
|
|
|
the absolute path to <filename>tmp/rootfs</filename> or the location at which
|
|
|
|
binaries with debugging information reside.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
At this point you can have GDB connect to the Gdbserver that is running
|
|
|
|
on the remote target by using the following command form:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ target remote remote-target-ip-address:2345
|
|
|
|
</literallayout>
|
|
|
|
The <filename>remote-target-ip-address</filename> is the IP address of the
|
|
|
|
remote target where the Gdbserver is running.
|
|
|
|
Port 2345 is the port on which the GDBSERVER is running.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-gdb-remotedebug-launch-gdb-using">
|
|
|
|
<title>Using the Debugger</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
You can now proceed with debugging as normal - as if you were debugging
|
|
|
|
on the local machine.
|
|
|
|
For example, to instruct GDB to break in the "main" function and then
|
|
|
|
continue with execution of the inferior binary use the following commands
|
|
|
|
from within GDB:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
(gdb) break main
|
|
|
|
(gdb) continue
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For more information about using GDB, see the project's online documentation at
|
|
|
|
<ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-oprofile">
|
|
|
|
<title>Profiling with OProfile</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
|
|
|
|
statistical profiler well suited for finding performance
|
|
|
|
bottlenecks in both userspace software and in the kernel.
|
|
|
|
This profiler provides answers to questions like "Which functions does my application spend
|
|
|
|
the most time in when doing X?"
|
2012-07-02 16:59:11 +00:00
|
|
|
Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
|
|
|
|
applications on target hardware straightforward.
|
2012-06-18 16:23:29 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To use OProfile, you need an image that has OProfile installed.
|
|
|
|
The easiest way to do this is with <filename>tools-profile</filename> in the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
|
|
|
|
You also need debugging symbols to be available on the system where the analysis
|
|
|
|
takes place.
|
|
|
|
You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the
|
|
|
|
<filename>IMAGE_FEATURES</filename> variable or by
|
|
|
|
installing the appropriate <filename>-dbg</filename> packages.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For successful call graph analysis, the binaries must preserve the frame
|
|
|
|
pointer register and should also be compiled with the
|
|
|
|
<filename>-fno-omit-framepointer</filename> flag.
|
2012-07-02 16:59:11 +00:00
|
|
|
You can achieve this by setting the
|
2012-06-18 16:23:29 +00:00
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
|
|
|
|
variable to
|
|
|
|
<filename>-fexpensive-optimizations -fno-omit-framepointer -frename-registers -O2</filename>.
|
|
|
|
You can also achieve it by setting the
|
|
|
|
<filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
|
|
|
|
variable to "1" in the <filename>local.conf</filename> configuration file.
|
|
|
|
If you use the <filename>DEBUG_BUILD</filename> variable you will also add extra debug information
|
|
|
|
that can make the debug packages large.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id="platdev-oprofile-target">
|
|
|
|
<title>Profiling on the Target</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Using OProfile you can perform all the profiling work on the target device.
|
|
|
|
A simple OProfile session might look like the following:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
# opcontrol --reset
|
|
|
|
# opcontrol --start --separate=lib --no-vmlinux -c 5
|
|
|
|
.
|
|
|
|
.
|
|
|
|
[do whatever is being profiled]
|
|
|
|
.
|
|
|
|
.
|
|
|
|
# opcontrol --stop
|
|
|
|
$ opreport -cl
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In this example, the <filename>reset</filename> command clears any previously profiled data.
|
|
|
|
The next command starts OProfile.
|
|
|
|
The options used when starting the profiler separate dynamic library data
|
|
|
|
within applications, disable kernel profiling, and enable callgraphing up to
|
|
|
|
five levels deep.
|
|
|
|
<note>
|
|
|
|
To profile the kernel, you would specify the
|
|
|
|
<filename>--vmlinux=/path/to/vmlinux</filename> option.
|
2012-07-02 16:59:11 +00:00
|
|
|
The <filename>vmlinux</filename> file is usually in the source directory in the
|
2012-06-18 16:23:29 +00:00
|
|
|
<filename>/boot/</filename> directory and must match the running kernel.
|
|
|
|
</note>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
After you perform your profiling tasks, the next command stops the profiler.
|
|
|
|
After that, you can view results with the <filename>opreport</filename> command with options
|
|
|
|
to see the separate library symbols and callgraph information.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Callgraphing logs information about time spent in functions and about a function's
|
|
|
|
calling function (parent) and called functions (children).
|
|
|
|
The higher the callgraphing depth, the more accurate the results.
|
|
|
|
However, higher depths also increase the logging overhead.
|
|
|
|
Consequently, you should take care when setting the callgraphing depth.
|
|
|
|
<note>
|
|
|
|
On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
|
|
|
|
To accomplish this use the <filename>-fno-omit-framepointer</filename> option
|
|
|
|
with <filename>gcc</filename>.
|
|
|
|
</note>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For more information on using OProfile, see the OProfile
|
|
|
|
online documentation at
|
|
|
|
<ulink url="http://oprofile.sourceforge.net/docs/"/>.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-oprofile-oprofileui">
|
|
|
|
<title>Using OProfileUI</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A graphical user interface for OProfile is also available.
|
|
|
|
You can download and build this interface from the Yocto Project at
|
|
|
|
<ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
|
|
|
|
If the "tools-profile" image feature is selected, all necessary binaries
|
|
|
|
are installed onto the target device for OProfileUI interaction.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
Even though the source directory usually includes all needed patches on the target device, you
|
2012-06-18 16:23:29 +00:00
|
|
|
might find you need other OProfile patches for recent OProfileUI features.
|
|
|
|
If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
|
|
|
|
OProfileUI README</ulink> for the most recent information.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id="platdev-oprofile-oprofileui-online">
|
|
|
|
<title>Online Mode</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Using OProfile in online mode assumes a working network connection with the target
|
|
|
|
hardware.
|
|
|
|
With this connection, you just need to run "oprofile-server" on the device.
|
|
|
|
By default, OProfile listens on port 4224.
|
|
|
|
<note>
|
|
|
|
You can change the port using the <filename>--port</filename> command-line
|
|
|
|
option.
|
|
|
|
</note>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
|
|
|
|
straightforward.
|
|
|
|
You access key functionality through the buttons on the toolbar, which
|
|
|
|
are duplicated in the menus.
|
|
|
|
Here are the buttons:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
|
|
|
|
You can also supply the IP address or hostname.</para></listitem>
|
|
|
|
<listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
|
|
|
|
downloads the data to the local host.
|
|
|
|
Stopping the profiler generates the profile and displays it in the viewer.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para><emphasis>Download:</emphasis> Downloads the data from the
|
|
|
|
target and generates the profile, which appears in the viewer.</para></listitem>
|
|
|
|
<listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
|
|
|
|
Resetting the data removes sample information collected from previous
|
|
|
|
sampling runs.
|
|
|
|
Be sure you reset the data if you do not want to include old sample information.
|
|
|
|
</para></listitem>
|
|
|
|
<listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
|
|
|
|
target to another directory for later examination.</para></listitem>
|
|
|
|
<listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
|
|
|
|
</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The client downloads the complete 'profile archive' from
|
|
|
|
the target to the host for processing.
|
|
|
|
This archive is a directory that contains the sample data, the object files,
|
|
|
|
and the debug information for the object files.
|
|
|
|
The archive is then converted using the <filename>oparchconv</filename> script, which is
|
|
|
|
included in this distribution.
|
|
|
|
The script uses <filename>opimport</filename> to convert the archive from
|
|
|
|
the target to something that can be processed on the host.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-07-02 16:59:11 +00:00
|
|
|
Downloaded archives reside in the build directory in
|
2012-06-18 16:23:29 +00:00
|
|
|
<filename>/tmp</filename> and are cleared up when they are no longer in use.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If you wish to perform kernel profiling, you need to be sure
|
|
|
|
a <filename>vmlinux</filename> file that matches the running kernel is available.
|
2012-07-02 16:59:11 +00:00
|
|
|
In the source directory, that file is usually located in
|
2012-06-18 16:23:29 +00:00
|
|
|
<filename>/boot/vmlinux-KERNELVERSION</filename>, where
|
|
|
|
<filename>KERNEL-version</filename> is the version of the kernel.
|
2012-07-02 16:59:11 +00:00
|
|
|
The OpenEmbedded build system generates separate <filename>vmlinux</filename>
|
|
|
|
packages for each kernel it builds.
|
2012-06-18 16:23:29 +00:00
|
|
|
Thus, it should just be a question of making sure a matching package is
|
|
|
|
installed (e.g. <filename>opkg install kernel-vmlinux</filename>.
|
|
|
|
The files are automatically installed into development and profiling images
|
|
|
|
alongside OProfile.
|
|
|
|
A configuration option exists within the OProfileUI settings page that you can use to
|
|
|
|
enter the location of the <filename>vmlinux</filename> file.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Waiting for debug symbols to transfer from the device can be slow, and it
|
|
|
|
is not always necessary to actually have them on the device for OProfile use.
|
|
|
|
All that is needed is a copy of the filesystem with the debug symbols present
|
|
|
|
on the viewer system.
|
|
|
|
The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launching GDB on the Host Computer</link>"
|
|
|
|
section covers how to create such a directory with
|
2012-07-02 16:59:11 +00:00
|
|
|
the source directory and how to use the OProfileUI Settings dialog to specify the location.
|
2012-06-18 16:23:29 +00:00
|
|
|
If you specify the directory, it will be used when the file checksums
|
|
|
|
match those on the system you are profiling.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id="platdev-oprofile-oprofileui-offline">
|
|
|
|
<title>Offline Mode</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If network access to the target is unavailable, you can generate
|
|
|
|
an archive for processing in <filename>oprofile-viewer</filename> as follows:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
# opcontrol --reset
|
|
|
|
# opcontrol --start --separate=lib --no-vmlinux -c 5
|
|
|
|
.
|
|
|
|
.
|
|
|
|
[do whatever is being profiled]
|
|
|
|
.
|
|
|
|
.
|
|
|
|
# opcontrol --stop
|
|
|
|
# oparchive -o my_archive
|
|
|
|
</literallayout>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In the above example, <filename>my_archive</filename> is the name of the
|
|
|
|
archive directory where you would like the profile archive to be kept.
|
|
|
|
After the directory is created, you can copy it to another host and load it
|
|
|
|
using <filename>oprofile-viewer</filename> open functionality.
|
|
|
|
If necessary, the archive is converted.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</section>
|
2008-02-26 11:31:34 +00:00
|
|
|
</chapter>
|
2010-06-01 23:19:22 +00:00
|
|
|
|
2008-02-26 11:31:34 +00:00
|
|
|
<!--
|
|
|
|
vim: expandtab tw=80 ts=4
|
|
|
|
-->
|