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" [
<!ENTITY class-autotools           SYSTEM "reference/class_autotools.xml">
<!ENTITY class-binconfig           SYSTEM "reference/class_binconfig.xml">
<!ENTITY dirs-install              SYSTEM "reference/dirs_install.xml">
<!ENTITY class-distutils           SYSTEM "reference/class_distutils.xml">
<!ENTITY fakeroot                  SYSTEM "reference/fakeroot.xml">
<!ENTITY class-image_ipkg          SYSTEM "reference/class_image_ipkg.xml">
<!ENTITY image-types               SYSTEM "reference/image_types.xml">
<!ENTITY class-pkgconfig           SYSTEM "reference/class_pkgconfig.xml">
<!ENTITY class-rootfs_ipkg         SYSTEM "reference/class_rootfs_ipkg.xml">
<!ENTITY var-section               SYSTEM "reference/var_section.xml">
<!ENTITY var-src-uri               SYSTEM "reference/var_src_uri.xml">
<!ENTITY class-update-alternatives SYSTEM "reference/class_update-alternatives.xml">
<!ENTITY class-update-rcd          SYSTEM "reference/class_update-rc.d.xml">
]>
<book>
    <bookinfo>
        <title>OpenEmbedded User Manual</title>
        <authorgroup>
            <corpauthor>OpenEmbedded Team</corpauthor>
        </authorgroup>
        <copyright>
            <year>2006</year>
            <holder>Holger Hans Peter Freyther</holder>
            <holder>Koen Kooi</holder>
            <holder>Detlef Vollmann</holder>
            <holder>Jamie Lenehan</holder>
            <holder>Marcin Juszkiewicz</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> Like any build tool (make, ant, jam), the OpenEmbedded build tool BitBake controls how to build things and the build dependencies. But unlike single project tools like <command>make</command> it is not based on one makefile or a closed set of inter-dependent makefiles, but collects and manages an open set of largely independent build descriptions (package recipes) and builds them in proper order. </para>
            <para>To be more precise: <ulink url="http://www.openembedded.org"><application>OpenEmbedded</application></ulink> is a set of metadata used to cross-compile, package and install software packages. <application>OpenEmbedded</application> is being used to build and maintain a number of embedded Linux distributions, including OpenZaurus, Angström, Familiar and SlugOS.</para>
        <para>The primary use-case of <application>OpenEmbedded</application> are:
            <itemizedlist>
                <listitem><para>Handle cross-compilation.</para></listitem>
                <listitem><para>Handle inter-package 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 six directories three of them hold <application>BitBake</application> metadata.</para>

            <para>The <emphasis>conf</emphasis> directory is holding the bitbake.conf, machine and distribution configuration. bitbake.conf is read when <application>BitBake</application> is started and this will include among others a local.conf the machine and distribution configuration files. These files will be searched in the <command>BBPATH</command> environment variable.</para>

            <para><emphasis>classes</emphasis> is the directory holding <application>BitBake</application> bbclass. These classes can be inherited by the <application>BitBake</application> files. BitBake automatically inherits the base.bbclass on every parsed file. <command>BBPATH</command> is used to  find the class.</para>

            <para>In <emphasis>packages</emphasis> the <application>BitBake</application> files are stored. For each task or application we have a directory. These directories store the real <application>BitBake</application> files. They are the ones ending with <emphasis>.bb</emphasis>. And for each application and version we have one.</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.</para>

            <para>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/"
                </screen>

The description and license fields are mandatory, so better check them twice.
            </para>

            <para>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 run-time dependencies on libraries on its own via the so called <emphasis>shlibs</emphasis>-code, but you need to specify everything other by yourself, which in this case is the 'cool-ttf-fonts' package.
            </para>

            <para>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-1.9.tar.bz2</screen> and replacing <emphasis>yoursum</emphasis> with the md5sum on your screen. A typical md5sum will look like this: <screen>a6434b0fc8a54c3dec3d6875bf3be8mtn </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.
            </para>

            <para>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.
            </para>

            <para>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.
            </para>

            <para>
.... some time goes by .....
            </para>

            <para>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>
            </para>

            <para>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 file-list, not replace the standard one.
            </para>
        </section>
    </chapter>


    <chapter>
        <title>Getting OpenEmbedded</title>
        <section>
            <title>Getting <application>BitBake</application></title>
            <para>The required version of <application>BitBake</application> is changing rapidly. At the time of writing (15th of October 2006) <application>BitBake</application> 1.6.0 was required.</para>
            <para>A safe method is to get <application>BitBake</application> from a stable (even mior number) Subversion branch.
            <screen>
<command>svn</command> co http://svn.berlios.de/svnroot/repos/bitbake/branches/bitbake-1.6
...
A   bitbake-1.6/classes/base.bbclass
U   bitbake-1.6
At revision 570.
            </screen>
            <application>BitBake</application> is checked out now; this completes the first and most critical dependency of OpenEmbedded. Issuing <command>svn</command> <command>up</command> in the <emphasis>bitbake-1.6</emphasis> directory will update <application>BitBake</application> to the latest stable version, but generally it is a good idea to stick with a specific known working version of <application>BitBake</application> until OpenEmbedded asks you to upgrade.
            </para>
        </section>

        <section>
            <title>Getting OpenEmbedded</title>
            <para>
The OpenEmbedded metadata has a high rate of development, so it's a good idea to stay up to date.
You'll need monotone 0.28 to get the metadata and stay up to date. Monotone is available in most distributions and has binaries at <ulink url="http://venge.net/monotone/">Monotone homepage</ulink>.</para>
<para> Next step is getting snapshot of database.

<screen>
wget http://openembedded.org/snapshots/OE.mtn.bz2 http://openembedded.org/snapshots/OE.mtn.bz2.md5
</screen>

Or if you have monotone 0.30 or later:

<screen>
wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2 
wget http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.30.mtn.bz2.md5
</screen>

Then verify integrity of snapshot by checking md5sum.

<screen>
cat OE.mtn.bz2.md5sum
md5sum OE.mtn.bz2
</screen>

Then unpack database.

<screen>
bunzip OE.mtn.bz2
</screen>

Finally checkout the development branch.

<screen>
mtn --db=OE.mtn co -b org.openembedded.dev
</screen>

           </para>
        </section>

        <section>
            <title>Configuring OpenEmbedded</title>
            <para>This section is a stub, help us by expanding it</para>
        </section>

        <section>
            <title>Building Software</title>
            <para>This section is a stub, help us by expanding it</para>
        </section>
    </chapter>

    <chapter>
        <title>Special features</title>
        <section>
            <title>Debian package naming <anchor id="debian" /></title>
            <screen>INHERIT += "debian"</screen>
            <para>Placing the above line into your <emphasis>${DISTRO}.conf</emphasis> or <emphasis>local.conf</emphasis> will trigger renaming of packages if they only ship one library. Imagine a package where the package name (<command>PN</command>) is foo and this packages ships a file named <command>libfoo.so.1.2.3</command>. Now this package will be renamed to <command>libfoo1</command> to follow the Debian package naming policy.</para>
        </section>

        <section>
            <title>Shared Library handling (shlibs) <anchor id="shlibs" /></title>
            <para>Run-time Dependencies (<command>RDEPENDS</command>) will be added when packaging the software. They should only contain the minimal dependencies to run the program. OpenEmbedded will analyze each packaged binary and search for <command>SO_NEEDED</command> libraries. The libraries are absolutely required by the program then OpenEmbedded is searching for packages that installs these libraries. these packages are automatically added to the <command>RDEPENDS</command>. As a packager you don't need to worry about shared libraries anymore they will be added automatically.</para>
            <remark>NOTE: This does not apply to plug-ins used by the program.</remark>
        </section>

        <section>
            <title>BitBake Collections <anchor id="collections" /></title>
            <para>This section is a stub, help us by expanding it</para>
            <para>
<screen>
BBFILES := "${OEDIR}/openembedded/packages/*/*.bb ${LOCALDIR}/packages/*/*.bb"
BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/packages/"
BBFILE_PATTERN_local = "^${LOCALDIR}/packages/"
BBFILE_PRIORITY_upstream = "5"
BBFILE_PRIORITY_local = "10"
</screen>
</para>
        </section>

        <section>
            <title>Task-base <anchor id="task-base" /></title>

<para>Task-base is new way of creating basic root filesystems. Instead of having each machine setting a ton of duplicate variables, this allow a machine to specify its features and <command>task-base</command> builds it a customised package based on what the machine needs along with what the distro supports.</para>

<para> To illustrate, the distro config file can say:

<screen>
DISTRO_FEATURES = "nfs smbfs ipsec wifi ppp alsa bluetooth ext2 irda pcmcia usbgadget usbhost"
</screen>

and the machine config:

<screen>
MACHINE_FEATURES = "kernel26 apm alsa pcmcia bluetooth irda usbgadget"
</screen>

and the resulting <command>task-base</command> would support pcmcia but not usbhost.</para>

<para>Task-base details exactly which options are either machine or distro settings (or need to be in both). Machine options are meant to reflect capabilities of the machine, distro options list things distribution maintainers might want to add or remove from their distros images.</para>
        </section>
        <section>
            <title>Overrides <anchor id="overrides" /></title>
            <para>This section is a stub, help us by expanding it</para>
        </section>
    </chapter>

    <chapter>
        <title>Common Use-cases/tasks</title>

        <section>
            <title>Creating a new Distribution</title>
<para>
Creating a new distribution is not complicated. Config need to be created
in /conf/distro directory. What has to be inside?
<itemizedlist>
    <listitem><para><command>DISTRO_VERSION</command> so users will know which version of distribution they use.</para></listitem>
    <listitem><para><command>DISTRO_TYPE</command> (release/debug) variable is used in some recipes to enable/disable some features - for example kernel output on screen for "debug" builds.</para></listitem>
    <listitem><para>Type of libc used: will it be glibc (<command>TARGET_OS</command> = "linux") or uclibc (<command>TARGET_OS</command> = "linux-uclibc")?</para></listitem>
    <listitem><para>Toolchain versions - for example gcc 3.4.4 based distro will have:
            <screen>
PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc-initial:gcc-cross-initial"
PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}gcc:gcc-cross"
PREFERRED_PROVIDERS += " virtual/${TARGET_PREFIX}g++:gcc-cross"

PREFERRED_VERSION_binutils = "2.16"
PREFERRED_VERSION_binutils-cross = "2.16"

PREFERRED_VERSION_gcc = "3.4.4"
PREFERRED_VERSION_gcc-cross = "3.4.4"
PREFERRED_VERSION_gcc-initial-cross = "3.4.4"
            </screen>
    </para></listitem>
    <listitem><para> <command>DISTRO_FEATURES</command> which describe which features distro has. More about it in <link linkend="task-base">task-base</link> section.</para></listitem>
    <listitem><para>Versions of kernels used for supported devices:
            <screen>
PREFERRED_VERSION_linux-omap1_omap5912osk ?= "2.6.18+git"
PREFERRED_VERSION_linux-openzaurus ?= "2.6.17"
            </screen>
    </para></listitem>
    <listitem><para>To get more stable build it is good to make use of sane-srcdates.inc file which contain working SRCDATE for many of floating recipes.
            <screen>
require conf/distro/include/sane-srcdates.inc
            </screen>
            It also should have global <command>SRCDATE</command> value set (format is ISO date: YYYYMMDD):
            <screen>
SRCDATE = "20061014"
            </screen>
    </para></listitem>
</itemizedlist>
</para>
        </section>

        <section>
            <title>Adding a new Machine</title>
<para>To be able to build for device OpenEmbedded have to know it, so machine config file need to be written. All those configs are stored in /conf/machine/ directory.</para>

<para>As usual some variables are required:
      <itemizedlist>
          <listitem><para><command>TARGET_ARCH</command> which describe which CPU architecture does machine use.</para></listitem>
          <listitem><para><command>MACHINE_FEATURES</command> which describe which features device has. More about it in <link linkend="task-base">task-base</link> section.</para></listitem>
          <listitem><para><command>PREFERRED_PROVIDER_virtual/kernel</command> has to point into proper kernel recipe for this machine.</para></listitem>
      </itemizedlist>
</para>

<para>
Next kernel recipe needs to be added.
</para>
        </section>

        <section>
            <title>Adding a new Package</title>
            <para>This section is a stub, help us by expanding it</para>
        </section>

        <section>
            <title>Creating your own image</title>
<para>
    Creating own image is easy - only few variables needs to be set:
    <itemizedlist>
        <listitem><para><command>IMAGE_BASENAME</command> to give name for own image</para></listitem>
        <listitem><para><command>IPKG_INSTALL</command> to give list of packages to install into image</para></listitem>
        <listitem><para><command>RDEPENDS</command> to give list of packages which are needed to be build to create image</para></listitem>
        <listitem><para><command>IMAGE_LINGUAS</command> is optional list of languages which has to be installed into image</para></listitem>
    </itemizedlist>

    Then adding of <emphasis>image_ipk</emphasis> class use:
    <screen>
inherit image_ipk
</screen>

And image recipe is ready for usage.
</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 for ARM architectures using glibc. We assume that the toolchain is in your <command>PATH</command>.</para>
<screen>
<command>ls</command> 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-gcc-3.4.4
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 prebuilt libraries</title>
                <para>We need the header files and the libraries itself. The following directory layout is assume.
<command>PRE_BUILT</command> has two subdirectories one is called <emphasis>include</emphasis> and holds the header files and the other directory is called <emphasis>lib</emphasis> and holds the shared and static libraries. Additionally a Qt2 directory is present having a <emphasis>include</emphasis> and <emphasis>lib</emphasis> sub-directory.</para>
                <screen>
<command>ls</command> $PRE_BUILT
include
lib
qt2
</screen>
            </section>

            <section>
                <title>Setting up OpenEmbedded</title>
                <para>OpenEmbedded will be setup here. We assume that your machine and distribution is not part
of OpenEmbedded and they will be created ad-hoc in the <emphasis>local.conf</emphasis> file. You will need to have
<application>BitBake</application> and a current OpenEmbedded version available.
                </para>

                <section>
                    <title>Sourcable script</title>
                    <para>To ease the usage of OpenEmbedded we start by creating a source-able script. This is actually a small variation from the already seen script. We will name it <emphasis>build_source</emphasis> and you will need to source it.</para>
                    <screen>
BITBAKE_PATH=/where/is/bitbake/bin
TOOLCHAIN=/where/is/toolchain/bin
HOST_TOOLS=/where/is/hosttools/bin
export PRE_BUILT=/where/is/pre-built

export PATH=$BITBAKE_PATH:$TOOLCHAIN:$HOST_TOOLS:$PATH
export OEDIR=$PWD
export LOCALDIR=$PWD/secret-isv
                    </screen>
                    <para>Use <command>source build_source</command> to source the script, use <command>env</command> to check that the variable where exported.</para>
                </section>

                <section>
                    <title>Creating the local.conf</title>
                    <para>We will configure OpenEmbedded now, it is very similar to what we have done above.</para>

                    <screen>
DL_DIR = "${OEDIR}/sources"
BBFILES := "${OEDIR}/openembedded/packages/*/*.bb ${LOCALDIR}/packages/*/*.bb"
BBFILE_COLLECTIONS = "upstream local"
BBFILE_PATTERN_upstream = "^${OEDIR}/openembedded/packages/"
BBFILE_PATTERN_local = "^${LOCALDIR}/packages/"
BBFILE_PRIORITY_upstream = "5"
BBFILE_PRIORITY_local = "10"
BBMASK = ""
                    </screen>
                    <para>${OEDIR}/openembedded will be a upstream release of OpenEmbedded. Above we have assumed it is in the current working directory. Additionally we have a ${LOCALDIR}, we combine these two directories as a special <link linkend="collections">BitBake Collection</link>.</para>

                <screen>
#
# machine stuff
#
MACHINE = "secret-killer"
PACKAGE_EXTRA_ARCHS = "armv4 armv4t armv5te iwmmxt xscale""
TARGET_CC_ARCH = "-mcpu=xscale -mtune=iwmmxt"
TARGET_ARCH = "arm"
PACKAGE_ARCH="xscale"
                </screen>
                <para>We tell OpenEmbedded that we build for the ARM platform and optimize for xscale and iwmmxt.</para>

                <screen>
INHERIT += " package_ipk debian"
TARGET_OS  = "linux"
TARGET_FPU = "soft"
DISTRO = "secret-disro"
DISTRO_NAME = "secret-distro"
DISTRO_VERSION = "x.y.z"
DISTRO_TYPE = "release"
                </screen>
                <para>Create a distribution ad-hoc as well. We tell OpenEmbedded that we build for linux and glibc using soft float as fpu. If your toolchain is a uclibc toolchain you will need to set <command>TARGET_OS</command> to linux-uclibc.</para>

                <screen>
export CC  = "${CCACHE}arm-linux-gcc-3.4.4 ${HOST_CC_ARCH}"
export CXX = "${CCACHE}arm-linux-g++ ${HOST_CC_ARCH}"
export CPP = "arm-linux-gcc-3.4.4 -E"
export LD = "arm-linux-ld"
export AR  = "arm-linux-ar"
export AS  = "arm-linux-as"
export RANLIB  = "arm-linux-ranlib"
export STRIP  = "arm-linux-strip"
                </screen>
                <para>The above variables replace the ones from <emphasis>bitbake.conf</emphasis>. This will make OpenEmbedded use the prebuilt toolchain.</para>

                <screen>
#
# point OE to the lib and include directory
#
TARGET_CPPFLAGS_append = " -I${PRE_BUILT}/include "
TARGET_LDFLAGS_prepend = " -L${PRE_BUILT}/qt2/lib -L${PRE_BUILT}/lib \
-Wl,-rpath-link,${PRE_BUILT}/lib -Wl,-rpath-link,${PRE_BUILT}/qt2/lib "

# special to Qt/Qtopia
QTDIR  = "${PRE_BUILT}/qt2"
QPEDIR = "${PRE_BUILT}"
palmtopdir = "/opt/Qtopia"
palmqtdir  = "/opt/Qtopia"
                </screen>
                <para>We will add the <command>PRE_BUILT</command> libraries to the include and library paths. And the same is done for the special version of Qt we have in your <command>PRE_BUILT</command> directory.</para>

                <screen>
ASSUME_PROVIDED += " virtual/${TARGET_PREFIX}gcc "
ASSUME_PROVIDED += " virtual/libc "
ASSUME_PROVIDED += " virtual/qte "
ASSUME_PROVIDED += " virtual/libqpe "
ASSUME_PROVIDED += " libqpe-opie "
                </screen>
                <para>Now we have told <application>BitBake</application> that the C library, compiler and Qtopia is already provided.  These lines will avoid building binutils, gcc initial, glibc, gcc.</para>


                <screen>
<command>source</command> build_source
<command>bitbake</command> your-killer-app
                </screen>
                <para>You should be able to create the packages you want to using the prebuilt toolchain now.</para>

                </section>
            </section>

            <section>
                <title>Useful hints</title>
                <para>If you have more prebuilt libraries you need to add additional <command>ASSUME_PROVIDED</command>
lines to your <emphasis>local.conf</emphasis>. Using <command>bitbake -vvv PACKAGE</command> you can easily see the package names you could <command>ASSUME_PROVIDED</command> if you have some prebuilt.</para> 
            </section>

            <section>
                <title>Issues with this approach</title>
<screen>
NOTE: Couldn't find shared library provider for libqtopia.so.1
NOTE: Couldn't find shared library provider for libqtopia2.so.2
NOTE: Couldn't find shared library provider for libqpe.so.1
NOTE: Couldn't find shared library provider for libpthread.so.0
NOTE: Couldn't find shared library provider for libstdc++.so.6
NOTE: Couldn't find shared library provider for libqte.so.2
NOTE: Couldn't find shared library provider for libgcc_s.so.1
NOTE: Couldn't find shared library provider for libc.so.6
NOTE: Couldn't find shared library provider for libm.so.6
</screen>
                <para>OpenEmbedded tries to automatically add run-time dependencies (RDEPENDS) to the package. It uses the <emphasis><link linkend="shlibs">shlibs</link></emphasis> system to do add them, in this case it was not able to find packages providing these libraries as they are prebuilt. This means they will not be added to the RDEPENDS of the just created package. The result can be fatal. If you use OpenEmbedded to create images you will end up with a image without a libc being installed. This will lead to a fatal failure. To workaround this issue you could create a package for the metadata to install every needed library and use ${BOOTSTRAP_EXTRA_RDEPENDS} to make sure this package is installed when creating images.</para>
            </section>

        </section>

        <section>
            <title>Using a new package format</title>
            <para>This section is a stub, help us by expanding it</para>
        </section>
    </chapter>

    <chapter>
        <title>Comparing</title>

        <section>
            <title>buildroot</title>
            <para>Writing of <application>BitBake</application> recipes is more easy and more intuitive than writing Makefiles while providing higher flexibility. This allows you to tweak specific recipes for your very special needs and to add new recipes very fast. You can build toolchains, Software Distribution Kits (SDKs), complete Distributions or just single packages. The flexibility of OpenEmbedded allows you to reuse the once written recipes for many different purposes. OpenEmbedded provides everything buildroot will be able to provide. But in contrast to buildroot OpenEmbedded will allow you to achieve what you really want to achieve. You can add new package formats, new filesystems, new output formats easily. OpenEmbedded will suit your need.</para>
        </section>

        <section>
            <title>crosstool</title>
            <para>Crosstool allows to create toolchains for you. It can only create the initial toolchain for you. It will not compile other needed libraries or applications for you, it will not be able to track dependencies or to package them properly. OpenEmbedded supports all configurations crosstool supports. You can start to create toolchains with OpenEmbedded, then as your needs grow create a more complete SDK from already present base libraries and applications and if you recognize you need to have packages for the target you have them almost built already.</para>
        </section>

        <section>
            <title>handmade</title>
            <para>Cross-compilation is a tough business. It is not that cross-compiling 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 run-time 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 choose from a pool of ready to use software packages.</para>
            <para>OpenEmbedded will create complete flashable images using different output formats and filesystems. This allows you to create complete and specialized distributions easily.</para>
        </section>
    </chapter>

<!-- Reference manual. Sorted alphabetically. All entries are pulled in from external files -->
    <chapter>
        <title>Reference</title>
        &class-autotools;
        &class-binconfig;
        &dirs-install;
        &class-distutils;
        &fakeroot;
        &class-image_ipkg;
        &image-types;
        &class-pkgconfig;
        &class-rootfs_ipkg;
        &var-section;
        &var-src-uri;
        &class-update-alternatives;
        &class-update-rcd;
    </chapter>

</book>