2008-02-26 11:31:34 +00:00
|
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<chapter id='usingpoky'>
|
|
|
|
<title>Using Poky</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
This section gives an overview of the components that make up Poky
|
2011-03-17 22:41:43 +00:00
|
|
|
followed by information about running poky builds and dealing with any
|
2008-02-26 11:31:34 +00:00
|
|
|
problems that may arise.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='usingpoky-components'>
|
|
|
|
<title>Poky Overview</title>
|
|
|
|
|
|
|
|
<para>
|
2011-03-17 22:41:43 +00:00
|
|
|
The BitBake task executor together with various types of configuration files form the core of Poky.
|
|
|
|
This section overviews the BitBake task executor and the
|
2010-10-28 15:27:28 +00:00
|
|
|
configuration files by describing what they are used for and they they interact.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2011-03-17 22:46:38 +00:00
|
|
|
BitBake handles the parsing and execution of the data files.
|
2010-10-28 15:27:28 +00:00
|
|
|
The data itself is of various types:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem><para>Recipes: Provides details about particular pieces of software</para></listitem>
|
|
|
|
<listitem><para>Class Data: An abstraction of common build information (e.g. how to build a
|
|
|
|
Linux kernel).</para></listitem>
|
|
|
|
<listitem><para>Configuration Data: Defines machine-specific settings, policy decisions, etc.
|
|
|
|
Configuration data acts a the glue to bind everything together.</para></listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2011-03-17 22:46:38 +00:00
|
|
|
BitBake knows how to combine multiple data sources together and refers to each data source
|
2010-10-28 15:27:28 +00:00
|
|
|
as a <link linkend='usingpoky-changes-layers'>'layer'</link>.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
Following are some brief details on these core components.
|
|
|
|
For more detailed information on these components see the
|
|
|
|
<link linkend='ref-structure'>'Reference: Directory Structure'</link>
|
|
|
|
appendix.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='usingpoky-components-bitbake'>
|
2011-03-17 22:46:38 +00:00
|
|
|
<title>BitBake</title>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
|
|
|
<para>
|
2011-03-17 22:46:38 +00:00
|
|
|
BitBake is the tool at the heart of Poky and is responsible
|
2008-02-26 11:31:34 +00:00
|
|
|
for parsing the metadata, generating a list of tasks from it
|
2011-03-17 22:41:43 +00:00
|
|
|
and then executing them. To see a list of the options BitBake
|
2010-10-28 15:27:28 +00:00
|
|
|
supports look at 'bitbake --help'.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2011-03-17 22:41:43 +00:00
|
|
|
The most common usage for BitBake is <filename>bitbake <packagename></filename>, where
|
2010-10-28 15:27:28 +00:00
|
|
|
packagename is the name of the package you want to build (referred to as the 'target'
|
|
|
|
in this manual).
|
|
|
|
The target often equates to the first part of a <filename>.bb</filename> filename.
|
|
|
|
So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
|
|
|
|
might type the following:
|
|
|
|
<literallayout class='monospaced'>
|
|
|
|
$ bitbake matchbox-desktop
|
|
|
|
</literallayout>
|
|
|
|
Several different versions of <filename>matchbox-desktop</filename> might exist.
|
2011-03-17 22:46:38 +00:00
|
|
|
BitBake chooses the one selected by the distribution configuration.
|
2011-03-17 22:41:43 +00:00
|
|
|
You can get more details about how BitBake chooses between different versions
|
2010-10-28 15:27:28 +00:00
|
|
|
and providers in the <link linkend='ref-bitbake-providers'>
|
2010-11-09 21:14:00 +00:00
|
|
|
'Preferences and Providers'</link> section.
|
2010-10-28 15:27:28 +00:00
|
|
|
</para>
|
|
|
|
<para>
|
2011-03-17 22:46:38 +00:00
|
|
|
BitBake also tries to execute any dependent tasks first.
|
2011-03-17 22:41:43 +00:00
|
|
|
So for example, before building <filename>matchbox-desktop</filename> BitBake
|
2010-10-28 15:27:28 +00:00
|
|
|
would build a cross compiler and glibc if they had not already been built.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-components-metadata'>
|
|
|
|
<title>Metadata (Recipes)</title>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
The <filename>.bb</filename> files are usually referred to as 'recipes'.
|
|
|
|
In general, a recipe contains information about a single piece of software such
|
|
|
|
as from where to download the source patches (if any are needed), which special
|
|
|
|
configuration options to apply, how to compile the source files, and how to
|
|
|
|
package the compiled output.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
The term 'package' can also be used to describe recipes.
|
|
|
|
However, since the same word is used for the packaged output from Poky (i.e. .ipk or .deb
|
|
|
|
files), this document avoids it.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-components-classes'>
|
|
|
|
<title>Classes</title>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
Class files (<filename>.bbclass</filename>) contain information that is useful to share
|
|
|
|
between metadata files.
|
|
|
|
An example is the autotools class, which contains
|
|
|
|
common settings for any application that autotools uses.
|
|
|
|
The <link linkend='ref-classes'>Reference: Classes</link> appendix provides details
|
|
|
|
about common classes and how to use them.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-components-configuration'>
|
|
|
|
<title>Configuration</title>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
The configuration files (<filename>.conf</filename>) define various configuration variables
|
|
|
|
that govern what Poky does.
|
|
|
|
These files are split into several areas that define machine configuration options,
|
|
|
|
distribution configuration options, compiler tuning options, general common configuration
|
|
|
|
options and user configuration options (<filename>local.conf</filename>).
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
|
|
|
|
<section id='usingpoky-build'>
|
|
|
|
<title>Running a Build</title>
|
|
|
|
|
|
|
|
<para>
|
2008-12-05 12:07:12 +00:00
|
|
|
First the Poky build environment needs to be set up using the following command:
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literallayout class='monospaced'>
|
2010-11-09 21:14:00 +00:00
|
|
|
$ source poky-init-build-env [build_dir]
|
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2010-09-09 02:34:34 +00:00
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
The build_dir is the dir containing all the build's object files. The default
|
|
|
|
build dir is poky-dir/build. A different build_dir can be used for each of the targets.
|
|
|
|
For example, ~/build/x86 for a qemux86 target, and ~/build/arm for a qemuarm target.
|
2010-09-09 02:34:34 +00:00
|
|
|
Please refer to <link linkend="structure-core-script">poky-init-build-env</link>
|
2010-10-28 15:27:28 +00:00
|
|
|
for more detailed information.
|
2010-09-09 02:34:34 +00:00
|
|
|
</para>
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
Once the Poky build environment is set up, a target can be built using:
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
<literallayout class='monospaced'>
|
2010-11-09 21:14:00 +00:00
|
|
|
$ bitbake <target>
|
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
The target is the name of the recipe you want to build.
|
2011-03-17 04:50:06 +00:00
|
|
|
Common targets are the images in <filename>meta/recipes-core/images</filename>,
|
2010-10-28 15:27:28 +00:00
|
|
|
<filename>/meta/recipes-sato/images</filename>, etc.
|
|
|
|
Or, the target can be the name of a recipe for a specific piece of software such as
|
|
|
|
<application>busybox</application>.
|
|
|
|
For more details about the standard images available, see the
|
|
|
|
<link linkend="ref-images">'Reference: Images'</link> appendix.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
2011-03-17 04:50:06 +00:00
|
|
|
<note>
|
|
|
|
Building an image without GNU Public License Version 3 (GPLv3) components is
|
|
|
|
only supported for minimal and base images.
|
|
|
|
See <link linkend='ref-images'>'Reference: Images'</link> for more information.
|
|
|
|
</note>
|
2011-03-30 14:17:33 +00:00
|
|
|
<note>
|
|
|
|
When building an image using GPL components you need to maintain your original
|
|
|
|
settings and not switch back and forth applying different versions of the GNU
|
|
|
|
Public License. If you rebuild using different versions of GPL you can get
|
|
|
|
dependency errors due to some components not being rebuilt.
|
|
|
|
</note>
|
2008-02-26 11:31:34 +00:00
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-install'>
|
|
|
|
<title>Installing and Using the Result</title>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
Once an image has been built it often needs to be installed.
|
|
|
|
The images/kernels built by Poky are placed in the
|
|
|
|
<filename class="directory">tmp/deploy/images</filename> directory.
|
|
|
|
Running qemux86 and qemuarm images is described in the
|
|
|
|
'Using Pre-Built Binaries and QEMU' section of the Yocto Project Quick Start.
|
2010-11-09 21:14:00 +00:00
|
|
|
See <ulink url="http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html"/>
|
2010-10-28 15:27:28 +00:00
|
|
|
for the guide.
|
|
|
|
For information about how to install these images, see the documentation for your
|
|
|
|
particular board/machine.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging'>
|
|
|
|
<title>Debugging Build Failures</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The exact method for debugging Poky depends on the nature of the
|
2010-10-28 15:27:28 +00:00
|
|
|
problem and on the system's area from which the bug originates.
|
2011-03-17 23:59:59 +00:00
|
|
|
Standard debugging practices such as comparison against the last
|
|
|
|
known working version with examination of the changes and the re-application of steps
|
2010-10-28 15:27:28 +00:00
|
|
|
to identify the one causing the problem are
|
|
|
|
valid for Poky just as they are for any other system.
|
2011-03-17 23:59:59 +00:00
|
|
|
Even though it is impossible to detail every possible potential failure,
|
|
|
|
here are some general tips to aid in debugging:
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging-taskfailures'>
|
|
|
|
<title>Task Failures</title>
|
|
|
|
|
|
|
|
<para>The log file for shell tasks is available in <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
|
2010-11-11 21:44:17 +00:00
|
|
|
For example, the "compile" task of busybox 1.01 on the ARM spitz machine might be
|
2010-10-28 15:27:28 +00:00
|
|
|
<filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>.
|
2011-03-17 22:41:43 +00:00
|
|
|
To see what BitBake runs to generate that log, look at the corresponding
|
2010-10-28 15:27:28 +00:00
|
|
|
<filename>run.do_taskname.pid </filename> file located in the same directory.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
2010-11-09 21:14:00 +00:00
|
|
|
<para>
|
|
|
|
Presently, the output from python tasks is sent directly to the console.
|
|
|
|
</para>
|
2008-02-26 11:31:34 +00:00
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging-taskrunning'>
|
2010-10-28 21:29:17 +00:00
|
|
|
<title>Running Specific Tasks</title>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
2010-11-09 21:14:00 +00:00
|
|
|
<para>
|
|
|
|
Any given package consists of a set of tasks.
|
2010-10-28 15:27:28 +00:00
|
|
|
In most cases the series is: fetch, unpack, patch, configure,
|
|
|
|
compile, install, package, package_write and build.
|
|
|
|
The default task is "build" and any tasks on which it depends build first - hence,
|
2011-03-17 22:41:43 +00:00
|
|
|
the standard BitBake behaviour.
|
2010-10-28 15:27:28 +00:00
|
|
|
Some tasks exist, such as devshell, that are not part of the default build chain.
|
|
|
|
If you wish to run a task that is not part of the default build chain you can use the
|
2011-03-17 22:41:43 +00:00
|
|
|
"-c" option in BitBake as follows:
|
2010-10-28 15:27:28 +00:00
|
|
|
<literallayout class='monospaced'>
|
2010-11-09 21:14:00 +00:00
|
|
|
$ bitbake matchbox-desktop -c devshell
|
2010-10-28 15:27:28 +00:00
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
If you wish to rerun a task use the force option "-f".
|
|
|
|
For example, the following sequence forces recompilation after changing files in the
|
|
|
|
working directory.
|
|
|
|
</para>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
|
|
|
<para>
|
|
|
|
<literallayout class='monospaced'>
|
2010-11-09 21:14:00 +00:00
|
|
|
$ bitbake matchbox-desktop
|
|
|
|
[make some changes to the source code in the WORKDIR]
|
|
|
|
$ bitbake matchbox-desktop -c compile -f
|
|
|
|
$ bitbake matchbox-desktop
|
2010-10-28 15:27:28 +00:00
|
|
|
</literallayout>
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
This sequence first builds <filename>matchbox-desktop</filename> and then recompiles it.
|
|
|
|
The last command reruns all tasks, basically the packaging tasks, after the compile.
|
2011-03-17 22:46:38 +00:00
|
|
|
BitBake recognizes that the "compile" task was rerun and therefore understands that the other
|
2010-10-28 15:27:28 +00:00
|
|
|
tasks also need to be run again.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-11-11 21:44:17 +00:00
|
|
|
You can view a list of tasks in a given package by running the "listtasks" task.
|
2010-10-28 15:27:28 +00:00
|
|
|
For example:
|
|
|
|
<literallayout class='monospaced'>
|
2010-11-09 21:14:00 +00:00
|
|
|
$ bitbake matchbox-desktop -c
|
2010-10-28 15:27:28 +00:00
|
|
|
</literallayout>
|
|
|
|
The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging-dependencies'>
|
|
|
|
<title>Dependency Graphs</title>
|
|
|
|
|
|
|
|
<para>
|
2011-03-17 22:41:43 +00:00
|
|
|
Sometimes it can be hard to see why BitBake wants to build some other packages before a given
|
2010-10-28 15:27:28 +00:00
|
|
|
package you've specified.
|
|
|
|
The <filename>bitbake -g targetname</filename> command creates the <filename>depends.dot</filename> and
|
|
|
|
<filename>task-depends.dot</filename> files in the current directory.
|
|
|
|
These files show the package and task dependencies and are useful for debugging problems.
|
|
|
|
You can use the <filename>bitbake -g -u depexp targetname</filename> command to display the results
|
|
|
|
in a more human-readable form.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging-bitbake'>
|
2011-03-17 22:46:38 +00:00
|
|
|
<title>General BitBake Problems</title>
|
2008-02-26 11:31:34 +00:00
|
|
|
|
|
|
|
<para>
|
2011-03-17 22:41:43 +00:00
|
|
|
You can see debug output from BitBake by using the "-D" option.
|
|
|
|
The debug output gives more information about what BitBake
|
2010-10-28 15:27:28 +00:00
|
|
|
is doing and the reason behind it.
|
|
|
|
Each "-D" option you use increases the logging level.
|
|
|
|
The most common usage is <filename>-DDD</filename>.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-10-28 15:27:28 +00:00
|
|
|
The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
|
2011-03-17 22:41:43 +00:00
|
|
|
BitBake chose a certain version of a package or why BitBake
|
2010-10-28 15:27:28 +00:00
|
|
|
picked a certain provider.
|
2011-03-17 22:41:43 +00:00
|
|
|
This command could also help you in a situation where you think BitBake did something
|
2010-10-28 15:27:28 +00:00
|
|
|
unexpected.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging-buildfile'>
|
2010-10-28 21:29:17 +00:00
|
|
|
<title>Building with No Dependencies</title>
|
2008-02-26 11:31:34 +00:00
|
|
|
<para>
|
2010-10-28 21:29:17 +00:00
|
|
|
If you really want to build a specific <filename>.bb</filename> file, you can use
|
|
|
|
the command form <filename>bitbake -b somepath/somefile.bb</filename>.
|
|
|
|
This command form does not check for dependencies so you should use it
|
|
|
|
only when you know its dependencies already exist.
|
2011-03-17 22:41:43 +00:00
|
|
|
You can also specify fragments of the filename and BitBake checks for a unique match.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging-variables'>
|
|
|
|
<title>Variables</title>
|
|
|
|
<para>
|
2010-10-28 21:29:17 +00:00
|
|
|
The "-e" option dumps the resulting environment for
|
2008-02-26 11:31:34 +00:00
|
|
|
either the configuration (no package specified) or for a
|
|
|
|
specific package when specified with the "-b" option.
|
|
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
<section id='usingpoky-debugging-others'>
|
|
|
|
<title>Other Tips</title>
|
|
|
|
<tip>
|
2010-10-28 21:29:17 +00:00
|
|
|
<para>
|
|
|
|
When adding new packages it is worth watching for undesireable items making their way
|
|
|
|
into compiler command lines.
|
|
|
|
For example, you do not want references to local system files like
|
|
|
|
<filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</tip>
|
|
|
|
<tip>
|
|
|
|
<para>
|
|
|
|
If you want to remove the psplash boot splashscreen, add "psplash=false"
|
2010-10-28 21:29:17 +00:00
|
|
|
to the kernel command line.
|
|
|
|
Doing so prevents psplash from loading thus allowing you to see the console.
|
|
|
|
It is also possible to switch out of the splashscreen by
|
|
|
|
switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
|
2008-02-26 11:31:34 +00:00
|
|
|
</para>
|
|
|
|
</tip>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
|
|
</chapter>
|
|
|
|
<!--
|
|
|
|
vim: expandtab tw=80 ts=4
|
|
|
|
-->
|