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

documentation/poky-ref-manual/usingpoky.xml: re-write for Yocto 

General re-write to make the chapter Yocto Project friendly.
Weeded out the references to "Poky."

(From yocto-docs rev: ac4fc6082f458e5ee60962693ee332bbf1e3c1a9)

Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
This commit is contained in:
Scott Rifenbark 2011-08-18 07:52:05 -07:00 committed by Richard Purdie
parent 00d483d65a
commit 295b855fc9
1 changed files with 143 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -4,16 +4,17 @@
<title>Using Poky</title>
<para>
This section gives an overview of the components that make up Poky
followed by information about running poky builds and dealing with any
problems that may arise.
This section gives an overview of the components that make up the Yocto Project
followed by information about Yocto Project builds and dealing with any
problems that might arise.
</para>
<section id='usingpoky-components'>
<title>Poky Overview</title>
<para>
The BitBake task executor together with various types of configuration files form the core of Poky.
The BitBake task executor together with various types of configuration files form the
Yocto Project core.
This section overviews the BitBake task executor and the
configuration files by describing what they are used for and they they interact.
</para>
@ -28,6 +29,11 @@
<listitem><para>Configuration Data: Defines machine-specific settings, policy decisions, etc.
Configuration data acts a the glue to bind everything together.</para></listitem>
</itemizedlist>
For more information on data, see the
<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html#yocto-project-terms'>
Yocto Project Terms</ulink> section in
<ulink url='http://www.yoctoproject.org/docs/1.1/dev-manual/dev-manual.html'>
The Yocto Project Development Manual</ulink>.
</para>
<para>
@ -46,16 +52,19 @@
<title>BitBake</title>
<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 BitBake
supports look at 'bitbake --help'.
BitBake is the tool at the heart of the Yocto Project and is responsible
for parsing the metadata, generating a list of tasks from it,
and then executing those tasks.
To see a list of the options BitBake supports, use the following help command:
<literallayout class='monospaced'>
$ bitbake --help
</literallayout>
</para>
<para>
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).
<filename>packagename</filename> 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:
@ -64,43 +73,46 @@
</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'</link> section.
You can get more details about how BitBake chooses between different
target versions and providers in the
<link linkend='ref-bitbake-providers'>Preferences and Providers</link> section.
</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.
So for example, before building <filename>matchbox-desktop</filename>, BitBake
would build a cross compiler and <filename>glibc</filename> if they had not already
been built.
</para>
<para>
A useful BitBake option to consider is the <filename>-k</filename> or
<filename>--continue</filename> option.
This option instructs BitBake to try and continue processing the job as much
as possible even after encountering an error. When an error occurs the target that
failed and those that depend on it cannot be remade. However, when you use this
option other dependencies can still be processed.
as possible even after encountering an error.
When an error occurs, the target that
failed and those that depend on it cannot be remade.
However, when you use this option other dependencies can still be processed.
</para>
</section>
<section id='usingpoky-components-metadata'>
<title>Metadata (Recipes)</title>
<para>
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.
The <filename>.bb</filename> files are usually referred to as "recipes."
In general, a recipe contains information about a single piece of software.
The information includes the location from which 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>
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.
The term "package" can also be used to describe recipes.
However, since the same word is used for the packaged output from the Yocto
Project (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
this document avoids using the term "package" to refer to recipes.
</para>
</section>
<section id='usingpoky-components-classes'>
@ -109,8 +121,8 @@
<para>
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.
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>
@ -121,13 +133,13 @@
<para>
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,
that govern the Yocto Project build process.
These files fall 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>).
options and user configuration options (<filename>local.conf</filename>, which is found
in the Yocto Project files build directory).
</para>
</section>
</section>
@ -135,47 +147,64 @@
<title>Running a Build</title>
<para>
First the Poky build environment needs to be set up using the following command:
You can find information on how to build an image using the Yocto Project in the
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html#building-image'>
Building an Image</ulink> section of the
<ulink url='http://www.yoctoproject.org/docs/1.1/yocto-project-qs/yocto-project-qs.html'>
Yocto Project Quick Start</ulink>.
This section provides a quick overview.
</para>
<para>
The first thing you need to do is set up the Yocto Project build environment by sourcing
the environment setup script as follows:
<literallayout class='monospaced'>
$ source oe-init-build-env [build_dir]
$ source oe-init-build-env [build_dir];
</literallayout>
</para>
<para>
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">oe-init-build-env</link>
for more detailed information.
</para>
<para>
Once the Poky build environment is set up, a target can be built using:
The <filename>build_dir</filename> is optional and specifies the directory Yocto Project
uses for the build.
If you do not specify a build directory it defaults to <filename>build</filename>
in the Yocto Project files directory structure.
A common practice is to use a different build directory for different targets.
For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
See <link linkend="structure-core-script">oe-init-build-env</link>
for more information on this script.
</para>
<para>
Once the Yocto Project build environment is set up, you can build a target using:
<literallayout class='monospaced'>
$ bitbake &lt;target&gt;
</literallayout>
</para>
<para>
The target is the name of the recipe you want to build.
The <filename>target</filename> 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.
<filename>/meta/recipes-sato/images</filename>, etc. all found in the Yocto Project
files.
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
For more details about the images Yocto Project supports, see the
<link linkend="ref-images">'Reference: Images'</link> appendix.
</para>
<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>
<note>
When building an image using GPL components you need to maintain your original
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.
Public License.
If you rebuild using different versions of GPL, dependency errors might occur
due to some components not being rebuilt.
</note>
</section>
@ -183,17 +212,18 @@
<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 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"/>
for the guide.
Once an image has been built, it often needs to be installed.
The images and kernels built by the Yocto Project are placed in the build directory in
<filename class="directory">tmp/deploy/images</filename>.
For information on how to run pre-built images such as <filename>qemux86</filename>
and <filename>qemuarm</filename>, see the
<ulink url='http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html#using-pre-built'>
Using Pre-Built Binaries and QEMU</ulink> section in the
<ulink url='http://www.yoctoproject.org//docs/yocto-quick-start/yocto-project-qs.html'>
Yocto Project Quick Start</ulink>.
For information about how to install these images, see the documentation for your
particular board/machine.
</para>
</section>
<section id='usingpoky-debugging'>
@ -213,15 +243,17 @@
<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 example, the "compile" task of busybox 1.01 on the ARM spitz machine might be
<para>The log file for shell tasks is available in
<filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
For example, the <filename>compile</filename> 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>
Presently, the output from python tasks is sent directly to the console.
Presently, the output from Python tasks is sent directly to the console.
</para>
</section>
@ -230,28 +262,33 @@
<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:
The standard BitBake behavior in most cases is: <filename>fetch</filename>,
<filename>unpack</filename>,
<filename>patch</filename>, <filename>configure</filename>,
<filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
<filename>package_write</filename>, and <filename>build</filename>.
The default task is <filename>build</filename> and any tasks on which it depends
build first.
Some tasks exist, such as <filename>devshell</filename>, 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
<filename>-c</filename> option in BitBake as follows:
<literallayout class='monospaced'>
$ bitbake matchbox-desktop -c devshell
</literallayout>
</para>
<para>
If you wish to rerun a task use the force option "-f".
If you wish to rerun a task, use the <filename>-f</filename> force option.
For example, the following sequence forces recompilation after changing files in the
working directory.
</para>
<para>
<literallayout class='monospaced'>
$ bitbake matchbox-desktop
[make some changes to the source code in the WORKDIR]
.
.
[make some changes to the source code in the working directory]
.
.
$ bitbake matchbox-desktop -c compile -f
$ bitbake matchbox-desktop
</literallayout>
@ -259,14 +296,14 @@
<para>
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.
The last command reruns all tasks (basically the packaging tasks) after the compile.
BitBake recognizes that the <filename>compile</filename> 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.
For example:
You can view a list of tasks in a given package by running the
<filename>listtasks</filename> task as follows:
<literallayout class='monospaced'>
$ bitbake matchbox-desktop -c
</literallayout>
@ -279,12 +316,13 @@
<para>
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.
package you have 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.
You can use the <filename>bitbake -g -u depexp targetname</filename> command to
display the results in a more human-readable form.
</para>
</section>
@ -292,10 +330,10 @@
<title>General BitBake Problems</title>
<para>
You can see debug output from BitBake by using the "-D" option.
You can see debug output from BitBake by using the <filename>-D</filename> option.
The debug output gives more information about what BitBake
is doing and the reason behind it.
Each "-D" option you use increases the logging level.
Each <filename>-D</filename> option you use increases the logging level.
The most common usage is <filename>-DDD</filename>.
</para>
@ -312,19 +350,20 @@
<title>Building with No Dependencies</title>
<para>
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>.
the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>.
This command form does not check for dependencies so you should use it
only when you know its dependencies already exist.
You can also specify fragments of the filename and BitBake checks for a unique match.
You can also specify fragments of the filename.
In this case, BitBake checks for a unique match.
</para>
</section>
<section id='usingpoky-debugging-variables'>
<title>Variables</title>
<para>
The "-e" option dumps the resulting environment for
The <filename>-e</filename> option dumps the resulting environment for
either the configuration (no package specified) or for a
specific package when specified with the "-b" option.
specific package when specified with the <filename>-b</filename> option.
</para>
</section>
@ -422,23 +461,23 @@
<section id='usingpoky-debugging-others'>
<title>Other Tips</title>
<tip>
<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>.
Here are some other tips that you might find useful:
<itemizedlist>
<listitem><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>.
</para></listitem>
<listitem><para>If you want to remove the psplash boot splashscreen,
add <filename>psplash=false</filename> to the kernel command line.
Doing so prevents psplash from loading and thus allows you to see the console.
It is also possible to switch out of the splashscreen by
switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
</para></listitem>
</itemizedlist>
</para>
</tip>
<tip>
<para>
If you want to remove the psplash boot splashscreen, add "psplash=false"
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).
</para>
</tip>
</section>
</section>