<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'>
<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 <packagename></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>
<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>
<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>
<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>
</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'>
</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>
<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>
<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>
<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>
<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>
