sysmo-bts
/
generic-poky
9
0
Fork 0
Code Pull Requests Releases Activity

General text edits through section 2.4.4 "General Bitbak Problems" 

Extensive language and consistency edits being applied to the manual.
During the 0.9 push I did not have time to make a pass through the
document.

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
This commit is contained in:
Scott Rifenbark 2010-10-28 08:27:28 -07:00 committed by Richard Purdie
parent ceef5c20cf
commit 30e92723e1
1 changed files with 140 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

255
documentation/poky-ref-manual/usingpoky.xml
View File

@ -13,27 +13,33 @@
<title>Poky Overview</title>
<para>
At the core of Poky is the bitbake task executor together with various types of
configuration files. This section gives an overview of bitbake and the
configuration files, in particular what they are used for, and how they
interact.
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
configuration files by describing what they are used for and they they interact.
</para>
<para>
Bitbake handles the parsing and execution of the data
files. The data itself is of various types; recipes which give
details about particular pieces of software, class data which is an
abstraction of common build information (e.g. how to build a Linux kernel)
and configuration data for machines, policy decisions, etc., which acts as
a glue and binds everything together. Bitbake knows how to combine multiple
data sources together, each data source being referred to as a <link
linkend='usingpoky-changes-layers'>'layer'</link>.
Bitbake handles the parsing and execution of the data files.
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>
Bitbake knows how to combine multiple data sources together and refers to each data source
as a <link linkend='usingpoky-changes-layers'>'layer'</link>.
</para>
<para>
The <link linkend='ref-structure'>directory structure walkthrough</link>
section gives details on the meaning of specific directories but some
brief details on the core components follows:
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.
</para>
<section id='usingpoky-components-bitbake'>
@ -42,23 +48,30 @@
<para>
Bitbake is the tool at the heart of Poky and is responsible
for parsing the metadata, generating a list of tasks from it
and then executing them. To see a list of the options it
supports look at <command>bitbake --help</command>.
and then executing them. To see a list of the options bitbake
supports look at 'bitbake --help'.
</para>
<para>
The most common usage is <command>bitbake packagename</command> where
packagename is the name of the package you wish to build
(from now on called the target). This often equates to the first part of a .bb
filename, so to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
might type <command>bitbake matchbox-desktop</command>.
Several different versions of matchbox-desktop might exist and
bitbake will choose the one selected by the distribution configuration
(more details about how bitbake chooses between different versions
and providers is available in the <link linkend='ref-bitbake-providers'>
'Preferences and Providers' section</link>). Bitbake will also try to execute any
dependent tasks first so before building matchbox-desktop it
would build a cross compiler and glibc if not already built.
The most common usage for bitbake is <filename>bitbake &lt;packagename&gt;</filename>, where
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.
Bitbake chooses the one selected by the distribution configuration.
You can get more details about how bitbake chooses between different versions
and providers in the <link linkend='ref-bitbake-providers'>
'Preferences and Providers' section</link>.
</para>
<para>
Bitbake also tries to execute any dependent tasks first.
So for example, before building <filename>matchbox-desktop</filename> bitbake
would build a cross compiler and glibc if they had not already been built.
</para>
</section>
@ -67,17 +80,17 @@
<title>Metadata (Recipes)</title>
<para>
The .bb files are usually referred to as 'recipes'. In general, a
recipe contains information about a single piece of software such
as where to download the source, any patches that are needed,
any special configuration options, how to compile the source files
and how to package the compiled output.
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.
</para>
<para>
'package' can also be used to describe recipes but since the same
word is used for the packaged output from Poky (i.e. .ipk or .deb
files), this document will avoid it.
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.
</para>
</section>
@ -86,11 +99,12 @@
<title>Classes</title>
<para>
Class (.bbclass) files contain information which is useful to share
between metadata files. An example is the autotools class which contains
the common settings that any application using autotools would use. The
<link linkend='ref-classes'>classes reference section</link> gives details
on common classes and how to use them.
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.
</para>
</section>
@ -98,18 +112,17 @@
<title>Configuration</title>
<para>
The configuration (.conf) files define various configuration variables
which govern what Poky does. These are split into several areas, such
as machine configuration options, distribution configuration options,
compiler tuning options, general common configuration and user
configuration (local.conf).
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>).
</para>
</section>
</section>
<section id='usingpoky-build'>
<title>Running a Build</title>
@ -122,14 +135,14 @@ $ source poky-init-build-env [build_dir]
</literallayout>
</para>
<para>
The build_dir is the dir containing all the building object files. The default
build dir is poky-dir/build. Multiple build_dir can be used for different targets.
For example, ~/build/x86 for qemux86 target, and ~/build/arm for qemuarm target.
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.
Please refer to <link linkend="structure-core-script">poky-init-build-env</link>
for detail info
for more detailed information.
</para>
<para>
Once the Poky build environment is set up, a target can now be built using:
Once the Poky build environment is set up, a target can be built using:
</para>
<para>
<literallayout class='monospaced'>
@ -137,11 +150,13 @@ $ bitbake &lt;target&gt;
</literallayout>
</para>
<para>
The target is the name of the recipe you want to build. Common targets are the
images (in <filename class="directory">meta/packages/images/</filename>)
or the name of a recipe for a specific piece of software like
<application>busybox</application>. More details about the standard images
are available in the <link linkend='ref-images'>image reference section</link>.
The target is the name of the recipe you want to build.
Common targets are the images in <filename>meta/recipes-core/images</filename>),
<filename>/meta/recipes-sato/images</filename>, 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.
</para>
</section>
@ -149,11 +164,15 @@ $ bitbake &lt;target&gt;
<title>Installing and Using the Result</title>
<para>
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 covered in the <link
linkend='intro-quickstart-qemu'>Running an Image</link> section. See your
board/machine documentation for information about how to install these images.
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.
See <ulink url="http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html"></ulink>
for the guide.
For information about how to install these images, see the documentation for your
particular board/machine.
</para>
</section>
@ -163,66 +182,73 @@ $ bitbake &lt;target&gt;
<para>
The exact method for debugging Poky depends on the nature of the
bug(s) and which part of the system they might be from. Standard
debugging practises such as comparing to the last
known working version and examining the changes, reapplying the
changes in steps to identify the one causing the problem etc. are
valid for Poky just like any other system. It's impossible to detail
every possible potential failure here but there are some general
tips to aid debugging:
problem and on the system's area from which the bug originates.
Standard debugging practises such as comparison against the last
known working version with examination of the changes and the reapplication of steps
to identify the one causing the problem are
valid for Poky just as they are for any other system.
It's impossible to detail every possible potential failure but here are some general
tips to aid in debugging:
</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>.
For the compile task of busybox 1.01 on the ARM spitz machine, this
might be <filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>
for example. To see what bitbake ran to generate that log, look at the <filename>run.do_taskname.pid </filename>
file in the same directory.
For example, the compile task of busybox 1.01 on the ARM spitz machine might be
<filename>tmp/work/armv5te-poky-linux-gnueabi/busybox-1.01/temp/log.do_compile.1234</filename>.
To see what bitbake runs to generate that log, look at the corresponding
<filename>run.do_taskname.pid </filename> file located in the same directory.
</para>
<para>The output from python tasks is sent directly to the console at present.</para>
<para>Presently, the output from python tasks is sent directly to the console.</para>
</section>
<section id='usingpoky-debugging-taskrunning'>
<title>Running specific tasks</title>
<para> Any given package consists of a set of tasks, 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 this depends on are
built first hence the standard bitbake behaviour. There are
some tasks such as devshell which are not part of the
default build chain. If you wish to run such a task you can
use the "-c" option to bitbake e.g. <command>bitbake
matchbox-desktop -c devshell</command>.
<para> Any given package consists of a set of tasks.
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,
the standard bitbake behaviour.
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
"-c" option in bitbake as follows:
<literallayout class='monospaced'>
$ bitbake matchbox-desktop -c devshell
</literallayout>
</para>
<para>
If you wish to rerun a task you can use the force option
"-f". A typical usage session might look like: </para>
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>
<para>
<literallayout class='monospaced'>
% bitbake matchbox-desktop
[change some source in the WORKDIR for example]
% bitbake matchbox-desktop -c compile -f
% bitbake matchbox-desktop</literallayout>
$ bitbake matchbox-desktop
[make some changes to the source code in the WORKDIR]
$ bitbake matchbox-desktop -c compile -f
$ bitbake matchbox-desktop
</literallayout>
</para>
<para>
which would build matchbox-desktop, then recompile it. The
final command reruns all tasks after the compile (basically
the packaging tasks) since bitbake will notice that the
compile has been rerun and hence the other tasks also need
to run again.
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.
Bitbake recognizes that the compile task was rerun and therefore understands that the other
tasks also need to be run again.
</para>
<para>
You can view a list of tasks in a given package by running
the listtasks task e.g. <command>bitbake matchbox-desktop -c
listtasks</command>, and the result is in file ${WORKDIR}/temp/log.do_listtasks.
You can view a list of tasks in a given package by running the listtasks task.
For example:
<literallayout class='monospaced'>
$ bitbake matchbox-desktop -c
</literallayout>
The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
</para>
</section>
@ -230,16 +256,13 @@ $ bitbake &lt;target&gt;
<title>Dependency Graphs</title>
<para>
Sometimes it can be hard to see why bitbake wants to build
some other packages before a given package you've specified.
<command>bitbake -g targetname</command> will create
<filename>depends.dot</filename> and
<filename>task-depends.dot</filename> files in the current
directory. They show
which packages and tasks depend on which other packages and
tasks and are useful for debugging purposes.
<command>"bitbake -g -u depexp targetname"</command> will show result
in more human-readable GUI style.
Sometimes it can be hard to see why bitbake wants to build some other packages before a given
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.
</para>
</section>
@ -247,17 +270,19 @@ $ bitbake &lt;target&gt;
<title>General Bitbake Problems</title>
<para>
Debug output from bitbake can be seen with the "-D" option.
You can see debug output from bitbake by using the "-D" option.
The debug output gives more information about what bitbake
is doing and/or why. Each -D option increases the logging
level, the most common usage being "-DDD".
is doing and the reason behind it.
Each "-D" option you use increases the logging level.
The most common usage is <filename>-DDD</filename>.
</para>
<para>
The output from <command>bitbake -DDD -v targetname</command> can reveal why
a certain version of a package might be chosen, why bitbake
picked a certain provider or help in other situations where
bitbake does something you're not expecting.
The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
bitbake chose a certain version of a package or why bitbake
picked a certain provider.
This command could also help you in a situation where you think bitbake did something
unexpected.
</para>
</section>