path: root/usermanual/usermanual.xml

<?xml version='1.0'   encoding='utf-8'?>
<!--
  ex:ts=4:sw=4:sts=4:et
  -*- tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*-
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<book>
    <bookinfo>
        <title>OpenEmbedded User Manual</title>
        <authorgroup>
            <corpauthor>OpenEmbedded Team</corpauthor>
        </authorgroup>
        <copyright>
            <year>2006</year>
            <holder>Holger Hans Peter Freyther</holder>
        </copyright>
        <copyright>
            <year>2006</year>
            <holder>Koen Kooi</holder>
        </copyright>

        <legalnotice>
            <para>This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit <ulink url="http://creativecommons.org/licenses/by/2.0/">http://creativecommons.org/licenses/by/2.0/</ulink> or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.</para>
        </legalnotice>
    </bookinfo>


    <chapter>
        <title>Introduction</title>
        <section>
            <title>Overview</title>
            <para><ulink url="http://www.openembedded.org"><application>OpenEmbedded</application></ulink> is a set of metadata used to crosscompile, package and install software packages. <application>OpenEmbedded</application> is being used to build and maintain a number of embedded Linux distributions, including OpenZaurus, Familiar and SlugOS.</para>
        <para>The primary usecase of <application>OpenEmbedded</application> are:
            <itemizedlist>
                <listitem><para>Handle crosscompilation.</para></listitem>
                <listitem><para>Handle interpackage dependencies</para></listitem>
                <listitem><para>Must be able to emit packages (tar, rpm, ipk)</para></listitem>
                <listitem><para>Must be able to create images and feeds from packages</para></listitem>
                <listitem><para>Must be highly configurable to support many machines, distribution and architectures.</para></listitem>
                <listitem><para>Writing of metadata must be easy and reusable</para></listitem>
            </itemizedlist>
        </para>
        <para>Together with <ulink url="http://bitbake.berlios.de/manual"><application>BitBake</application></ulink>, OpenEmbedded satisfies all these and many more. Flexibility and power have always been the priorities.</para>
        </section>


       <section>
            <title>History</title>
            <para>OpenEmbedded was invented and founded by the creators of the OpenZaurus project. 
At this time the project had pushed <emphasis>buildroot</emphasis> to its limits. It supported the creation of
<emphasis>ipk</emphasis> packages, feeds and images and had support for more than one machine. But it was impossible
to use different patches, files for different architectures, machines or distributions. To overcome this shortcoming
OpenEmbedded was created.</para>
            <para>After a few months other projects started using OpenEmbedded and contributing back. On 7 December 2004 Chris Larson split the project into two parts: BitBake, a generic task executor and OpenEmbedded, the metadata for BitBake.</para>   
       </section>
    </chapter>


    <chapter>
        <title>Metadata</title>
        <section>
            <title>File Layout</title>
            <para>OpenEmbedded has three directories holding <application>BitBake</application> metadata <emphasis>conf</emphasis>,
<emphasis>classes</emphasis> and <emphasis>packaes</emphasis>. FIXME</para>
        </section>
        <section>
            <title>Syntax</title>
            <para>OpenEmbedded has files ending with <emphasis>.conf</emphasis>, <emphasis>.inc</emphasis>,
<emphasis>.bb</emphasis> and<emphasis>.bbclass</emphasis>. The syntax and semantic of these files are best
described in the <ulink url="http://bitbake.berlios.de/manual"><application>BitBake</application> manual</ulink>. </para>
        </section>
        <section>
            <title>Classes</title>
            <para>OpenEmbedded provides special <application>BitBake</application> classes to ease compiling, packaging and other things. FIXME.</para>
        </section>
        <section>
            <title>Writing Meta Data (Adding packages)</title>
            <para>
This page will guide you trough the effort of writing a .bb file or <emphasis>recipe</emphasis> in BitBake speak.

Let's start with the easy stuff, like the package description, license, etc:

<screen>

DESCRIPTION = "My first application, a really cool app containing lots of foo and bar"
LICENSE = "GPLv2"
HOMEPAGE = "http://www.host.com/foo/"
MAINTAINER = "Joe N. User &lt;joe@user.net&gt;"

</screen>

The maintainer field needs to have a real name and a working email-address to be usefull, the description and license fields are mandatory, so better check them twice.

The next step is to specify what the package needs to build and run, the so called <emphasis>dependencies</emphasis>:

<screen>

DEPENDS = "gtk+"
RDEPENDS = "cool-ttf-fonts"

</screen>

The package needs gtk+ to build ('DEPENDS') and requires the 'cool-ttf-fonts' package to run ('RDEPENDS'). OE will add runtime dependencies on libraries on its own via the so called <emphasis>shlibs</emphasis>-code, but you need to specify everything by yourself, which in this case is the 'cool-ttf-fonts' package.

After entering all this OE will know what to build before trying to build your application, but it doesn't know where to get it yet. So let's add the source location:

<screen>

SRC_URI = "http://www.host.com/foo/files/${P}.tar.bz2;md5sum=yoursum"

</screen>

This will tell the fetcher to where to download the sources from and it will check the integrity using md5sum if you provided the appropriate <emphasis>yoursum</emphasis>. You can make one by doing <screen>md5sum foo-3.2.2.tar.gz</screen> and replacing <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8db </screen>Notice the <emphasis>${P}</emphasis> variable, that one holds the package name, <emphasis>${PN}</emphasis> in BitBake speak and the package version, <emphasis>${PV}</emphasis> in BitBake speak. It's a short way of writing <emphasis>${PN}-${PV}</emphasis>. Using this notation means you can copy the recipe when a new version is released without having to alter the contents. You do need to check if everything is still correct, because new versions mean new bugs.


Before we can move to the actual building we need to find out which build system the package is using. If we're lucky, we see a <emphasis>configure</emphasis> file in the build tree this is an indicator that we can <emphasis>inherit autotools</emphasis> if we see a <emphasis>.pro</emphasis> file, it might be qmake, which needs <emphasis>inherit qmake</emphasis>. Virtually all gtk apps use autotools:

<screen>

inherit autotools pkgconfig

</screen>

We are in luck! The package is a well-behaved application using autotools and pkgconfig to configure and build it self.
Lets start the build:

<screen>

<command>bitbake</command> foo

</screen>

Depending on what you have built before and the speed of your computer this can take a few seconds to a few hours, so be prepared.

.... some time goes by .....

Your screen should now have something like this on it:

<screen>

NOTE: package foo-1.9-r0: task do_build: completed
NOTE: package foo-1.9: completed
NOTE: build 200605052219: completed

</screen>

All looks well, but wait, let's scroll up:


<screen>

NOTE: the following files where installed but not shipped:
    /usr/weirdpath/importantfile.foo

</screen>

OE has a standard list of paths which need to be included, but it can't know everything, so we have to tell OE to include that file as well:

<screen>

FILES_${PN} += "/usr/weirdpath/importantfile.foo"

</screen>

It's important to use <emphasis>+=</emphasis> so it will get appended to the standard filelist, not replace the standard one.



</para>
        </section>
    </chapter>


    <chapter>
        <title>Getting OpenEmbedded</title>
        <section>
            <title>Getting <application>BitBake</application></title>
            <para></para>
        </section>

        <section>
            <title>Getting OpenEmbedded</title>
            <para></para>
        </section>

        <section>
            <title>Configuring OpenEmbedded</title>
            <para></para>
        </section>

        <section>
            <title>Building Software</title>
            <para></para>
        </section>
    </chapter>

    <chapter>
        <title>Common Usecases/tasks</title>

        <section>
            <title>Creating a new Distribution</title>
            <para></para>
        </section>

        <section>
            <title>Adding a new Machine</title>
            <para></para>
        </section>

        <section>
            <title>Adding a new Package</title>
            <para></para>
        </section>

        <section>
            <title>Creating your own image</title>
            <para></para>
        </section>

        <section>
            <title>Using a prebuilt toolchain to create your packages</title>
            <para>It might be necessary to integrate a prebuilt toolchain and other libraries but still be use
OpenEmbedded to build packages. One of many approaches is shown and discussed here.</para>

            <section>
                <title>The toolchain</title>
                <para>We assume the toolchain provides a C and C++ compiler, an assembler and other tools to build packages.
The list below shows a gcc 3.4.4 toolchain using glibc. We assume that the toolchain is in your <command>PATH</command>.</para>
<screen>
ls pre-built/cross/bin

arm-linux-g++
arm-linux-ld
arm-linux-ranlib
arm-linux-ar
arm-linux-g77
arm-linux-readelf
arm-linux-as
arm-linux-gcc
arm-linux-c++
arm-linux-size
arm-linux-c++filt
arm-linux-nm
arm-linux-strings
arm-linux-cpp
arm-linux-objcopy
arm-linux-strip
arm-linux-objdump
</screen>
            </section>
            <section>
                <title>The libraries</title>
                <para>The additional libraries</para>
                <screen>
</screen>
            </section>

        </section>

        <section>
            <title>Using a new package format</title>
            <para></para>
        </section>
    </chapter>

    <chapter>
        <title>Comparsion</title>

        <section>
            <title>buildroot</title>
            <para>We are better, they are on crack?</para>
        </section>

        <section>
            <title>crosstool</title>
            <para>We are better, they are on crack?</para>
        </section>

        <section>
            <title>handmade</title>
            <para>Crosscompilation is a tough business. It is not that crosscompiling is hard itself but many people misuse
the buildsystem they use to build their software. This will lead to a variety of issues you can run into. This can be failing
tests on configuration because of executing cross compiled binaries or crashes at runtime due wrong sizes of basic types. 
When utilizing OpenEmbedded you avoid searching for patches at many different places and will be able to get things done more quickly.
<application>OpenEmbedded</application> allows you to chooose from a pool of ready to use software packages, allow creation of images and many more.</para>
        </section>
    </chapter>
</book>