docs: import usermanual from org.openembedded.documentation.

org.openembedded.documentation is deprecated now; please do all updates here!

9 files changed, 5712 insertions, 0 deletions

diff --git a/docs/usermanual/chapters/.mtn2git_empty b/docs/usermanual/chapters/.mtn2git_empty
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/docs/usermanual/chapters/.mtn2git_empty
diff --git a/docs/usermanual/chapters/common_use_cases.xml b/docs/usermanual/chapters/common_use_cases.xml
new file mode 100644
index 0000000000..4497683fa9
--- /dev/null
+++ b/docs/usermanual/chapters/common_use_cases.xml
@@ -0,0 +1,409 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_common_use_cases">
+  <title>Common Use-cases/tasks</title>
+
+  <section id="commonuse_new_distro">
+    <title>Creating a new Distribution</title>
+
+    <para>Creating a new distribution is not complicated, however we urge you
+    to try existing distributions first, because it's also very easy to do
+    wrong. The config need to be created in /conf/distro directory. So 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 id="commonuse_new_machine">
+    <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 id="commonuse_new_package">
+    <title>Adding a new Package</title>
+
+    <para>This section is a stub, help us by expanding it.  Learn by example, go through the
+    recipes that are already there and mimic them to do what you want.</para>
+
+    <section>
+        <title>building from unstable source code</title>
+        <para>Building against the latest, bleeding-edge source has some intricacies of its own.
+        For one, it is desirable to pin down a souce code revision that is known to build to 
+        prevent random breakage in OE at the most inopportune time for all OE users.  Here is
+        how to do that properly.
+          <itemizedlist>
+            <listitem><para>for svn: add 'PV = "1.1+svnr${SRCREV}"' to your bb file.</para></listitem>
+            <listitem><para>for cvs: add 'PV = "1.1+cvs${SRCREV}"' to your bb file.</para></listitem>
+          </itemizedlist>
+        Accompany either with an entry to conf/distro/include/sane-srcrevs.inc for a revision that you know
+        builds successfully.
+        </para>
+        <para>
+        If you really absolutely have to follow the latest commits, you can do that by adding
+        'SRCREV_pn-linux-davinci ?= ${AUTOREV}' to your local.conf, for example.  In this case,
+        you'd build against the most recent and unstable source for the pn-linux-davinci package.
+        </para>
+    </section>
+  </section>
+
+  <section id="commonuse_new_image">
+    <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 a name for your own
+          image</para>
+        </listitem>
+
+        <listitem>
+          <para><command>PACKAGE_INSTALL</command> to give a list of packages
+          to install into the image</para>
+        </listitem>
+
+        <listitem>
+          <para><command>RDEPENDS</command> to give a list of recipes which
+          are needed to be built to create this image</para>
+        </listitem>
+
+        <listitem>
+          <para><command>IMAGE_LINGUAS</command> is an optional list of
+          languages which has to be installed into the image</para>
+        </listitem>
+      </itemizedlist> Then adding of the <emphasis>image</emphasis> class use:
+    <screen>
+inherit image
+</screen> And the image recipe is ready for usage.</para>
+  </section>
+
+  <section id="commonuse_prebuilt_toolchain">
+    <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>
+      
+      <para>However, the correct way to resolve this is to provide explicit 
+      mapping using ASSUME_SHLIBS variable. For example, for the libraries 
+      above (partial):
+      <screen>
+ASSUME_SHLIBS = "libqtopia2.so.2:qtopia2_2.4 libc.so.6:libc"
+</screen>
+      The format is shlib_file_name:package[_version]. If a version is specified it will be
+      used as the minimal (>=) version for the dependency.</para>
+    </section>
+  </section>
+
+  <section id="commonuse_new_package_format">
+    <title>Using a new package format</title>
+
+    <para>This section is a stub, help us by expanding it</para>
+  </section>
+</chapter>
diff --git a/docs/usermanual/chapters/comparing.xml b/docs/usermanual/chapters/comparing.xml
new file mode 100644
index 0000000000..1347010977
--- /dev/null
+++ b/docs/usermanual/chapters/comparing.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_comparing">
+  <title>Comparing</title>
+
+  <section id="comparing_buildroot">
+    <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 id="comparing_crosstool">
+    <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 id="comparing_handmade">
+    <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>
\ No newline at end of file
diff --git a/docs/usermanual/chapters/features.xml b/docs/usermanual/chapters/features.xml
new file mode 100644
index 0000000000..8eecaa9ed4
--- /dev/null
+++ b/docs/usermanual/chapters/features.xml
@@ -0,0 +1,78 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_special_features">
+  <title>Special features</title>
+
+  <section id="special_debian_naming">
+    <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 id="special_shlibs">
+    <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 id="special_bitbake_collections">
+    <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 id="special_task_base">
+    <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 id="special_overrides">
+    <title>Overrides <anchor id="overrides" /></title>
+
+    <para>This section is a stub, help us by expanding it</para>
+  </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/usermanual/chapters/getting_oe.xml b/docs/usermanual/chapters/getting_oe.xml
new file mode 100644
index 0000000000..9238e4f29d
--- /dev/null
+++ b/docs/usermanual/chapters/getting_oe.xml
@@ -0,0 +1,70 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_getting_oe">
+  <title>Getting Started</title>
+
+  <section id="gettingoe_getting_bitbake">
+    <title>Getting <application>BitBake</application></title>
+
+    <para>The required version of <application>BitBake</application> is
+    changing rapidly. At the time of writing (end 2007)
+    <application>BitBake</application> 1.8.latest was required.</para>
+
+    <para>A safe method is to get the <application>BitBake</application> from
+    a stable Subversion branch (those with an even minor number). <screen>
+<command>svn</command> co http://svn.berlios.de/svnroot/repos/bitbake/branches/bitbake-1.8
+...
+A   bitbake-1.8/classes/base.bbclass
+U   bitbake-1.8
+At revision 827.
+            </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.8</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 id="gettingoe_getting_oe">
+    <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>
+md5sum -c OE.mtn.bz2.md5sum
+</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 id="gettingoe_configuring_oe">
+    <title>Configuring OpenEmbedded</title>
+
+    <para>This section is a stub, help us by expanding it</para>
+  </section>
+
+  <section id="gettingoe_building_software">
+    <title>Building Software</title>
+
+    <para>Once BitBake and OpenEmbedded are set up and configured, one can build 
+    software and images like this:
+<screen>
+bitbake &lt;recipe_name&gt;
+</screen>
+            </para>
+
+    <para>This section is a stub, help us by expanding it</para>
+  </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/usermanual/chapters/introduction.xml b/docs/usermanual/chapters/introduction.xml
new file mode 100644
index 0000000000..cbe58332e1
--- /dev/null
+++ b/docs/usermanual/chapters/introduction.xml
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_introduction">
+  <title>Introduction</title>
+
+  <section id="intro_overview">
+    <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, &Aring;ngstr&ouml;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 id="intro_history">
+    <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>
diff --git a/docs/usermanual/chapters/metadata.xml b/docs/usermanual/chapters/metadata.xml
new file mode 100644
index 0000000000..f4cf3bc5e6
--- /dev/null
+++ b/docs/usermanual/chapters/metadata.xml
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_metadata">
+  <title>Metadata</title>
+
+  <section id="metadata_file_layout">
+    <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 id="metadata_syntax">
+    <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 id="metadata_classes">
+    <title>Classes</title>
+
+    <para>OpenEmbedded provides special <application>BitBake</application>
+    classes to ease compiling, packaging and other things. FIXME.</para>
+  </section>
+
+  <section id="metadata_writing_data">
+    <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>
\ No newline at end of file
diff --git a/docs/usermanual/chapters/recipes.xml b/docs/usermanual/chapters/recipes.xml
new file mode 100644
index 0000000000..c1ca456fa0
--- /dev/null
+++ b/docs/usermanual/chapters/recipes.xml
@@ -0,0 +1,3710 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_recipes" xreflabel="Recipes chapter">
+  <title>Recipes</title>
+
+  <section id="recipes_introduction" xreflabel="introduction">
+    <title>Introduction</title>
+
+    <para>A bitbake recipe is a set of instructions that describe what needs
+    to be done to retrieve the source code for some application, apply any
+    necessary patches, provide any additional files (such as init scripts),
+    compile it, install it and generated binary packages. The end result is a
+    binary package that you can install on your target device, and maybe some
+    intermediate files, such as libraries and headers, which can be used when
+    building other application.</para>
+
+    <para>In many ways the process is similar to creating .deb or .rpm
+    packages for your standard desktop distributions with one major difference
+    - in OpenEmbedded everything is being cross-compiled. This often makes the
+    task far more difficult (depending on how well suited the application is
+    to cross compiling), then it is for other packaging systems and sometime
+    impossible.</para>
+
+    <para>This chapter assumes that you are familiar with working with
+    bitbake, including the work flow, required directory structures, bitbake
+    configuration and the use of monotone. If you are not familiar with these
+    then first take a look at the chapter on bitbake usage.</para>
+  </section>
+
+  <section id="recipes_syntax" xreflabel="syntax">
+    <title>Syntax of recipes</title>
+
+    <para>The basic items that make up a bitbake recipe file are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>functions</term>
+
+        <listitem>
+          <para>Functions provide a series of actions to be performed.
+          Functions are usually used to override the default implementation of
+          a task function, or to compliment (append or prepend to an existing
+          function) a default function. Standard functions use sh shell
+          syntax, although access to OpenEmbedded variables and internal
+          methods is also available.</para>
+
+          <para>The following is an example function from the sed
+          recipe:</para>
+
+          <para><screen>do_install () {
+    autotools_do_install
+    install -d ${D}${base_bindir}
+    mv ${D}${bindir}/sed ${D}${base_bindir}/sed.${PN}
+}</screen>It is also possible to implement new functions, that are not
+          replacing or complimenting the default functions, which are called
+          between existing tasks. It is also possible to implement functions
+          in python instead of sh. Both of these options are not seen in the
+          majority of recipes.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>variable assignments and manipulations</term>
+
+        <listitem>
+          <para>Variable assignments allow a value to be assigned to a
+          variable. The assignment may be static text or might include the
+          contents of other variables. In addition to assignment, appending
+          and prepending operations are also supported.</para>
+
+          <para>The follow example shows the some of the ways variables can be
+          used in recipes:<screen>S = "${WORKDIR}/postfix-${PV}"
+PR = "r4"
+CFLAGS += "-DNO_ASM"
+SRC_URI_append = "file://fixup.patch;patch=1"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>keywords</term>
+
+        <listitem>
+          <para>Only a few keywords are used in bitbake recipes. They are used
+          for things such as including common functions
+          (<emphasis>inherit</emphasis>), loading parts of a recipe from other
+          files (<emphasis>include</emphasis> and
+          <emphasis>require</emphasis>) and exporting variables to the
+          environment (export).</para>
+
+          <para>The following example shows the use of some of these
+          keywords:<screen>export POSTCONF = "${STAGING_BINDIR}/postconf"
+inherit autoconf
+require otherfile.inc</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>comments</term>
+
+        <listitem>
+          <para>Any lines that begin with a # are treated as comment lines and
+          are ignored.<screen># This is a comment</screen></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>The following is a summary of the most important (and most commonly
+    used) parts of the recipe syntax:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>Line continuation: \</term>
+
+        <listitem>
+          <para>To split a line over multiple lines you should place a \ at
+          the end of the line that is to be continued on the next line.</para>
+
+          <screen>VAR = "A really long \
+       line"</screen>
+
+          <para>Note that there must not be anything (no spaces or tabs) after
+          the \.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Comments: #</term>
+
+        <listitem>
+          <para>Any lines beginning with a # are comments and will be
+          ignored.<screen># This is a comment</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Using variables: ${...}</term>
+
+        <listitem>
+          <para>To access the contents of a variable you need to access it via
+          <emphasis>${&lt;varname&gt;}</emphasis>:<screen>SRC_URI = "${SOURCEFORGE_MIRROR}/libpng/zlib-${PV}.tar.gz"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Quote all assignments</term>
+
+        <listitem>
+          <para>All variable assignments should be quoted with double quotes.
+          (It may work without them at present, but it will not work in the
+          future).<screen>VAR1 = "${OTHERVAR}"
+VAR2 = "The version is ${PV}"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Conditional assignment</term>
+
+        <listitem>
+          <para>Conditional assignement is used to assign a value to a
+          variable, but only when the variable is currently unset. This is
+          commonly used to provide a default value for use when no specific
+          definition is provided by the machine or distro configuration of the
+          users local.conf configuration.</para>
+
+          <para>The following example:<screen>VAR1 ?= "New value"</screen>will
+          set <emphasis role="bold">VAR1</emphasis> to <emphasis>"New
+          value"</emphasis> if its currently empty. However if it was already
+          set it would be unchanged. In the following <emphasis
+          role="bold">VAR1</emphasis> is left with the value
+          <emphasis>"Original value"</emphasis>:<screen>VAR1 = "Original value"
+VAR1 ?= "New value"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Appending: +=</term>
+
+        <listitem>
+          <para>You can append values to existing variables using the
+          <emphasis>+=</emphasis> operator. Note that this operator will add a
+          space between the existing content of the variable and the new
+          content.<screen>SRC_URI += "file://fix-makefile.patch;patch=1"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Prepending: =+</term>
+
+        <listitem>
+          <para>You can prepend values to existing variables using the
+          <emphasis>=+</emphasis> operator. Note that this operator will add a
+          space between the new content and the existing content of the
+          variable.<screen>VAR =+ "Starts"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Appending: _append</term>
+
+        <listitem>
+          <para>You can append values to existing variables using the
+          <emphasis>_append</emphasis> method. Note that this operator does
+          not add any additional space, and it is applied after all the
+          <emphasis>+=</emphasis>, and <emphasis>=+</emphasis> operators have
+          been applied.</para>
+
+          <para>The following example show the space being explicitly added to
+          the start to ensure the appended value is not merged with the
+          existing value:<screen>SRC_URI_append = " file://fix-makefile.patch;patch=1"</screen>The
+          <emphasis>_append</emphasis> method can also be used with overrides,
+          which result in the actions only being performed for the specified
+          target or machine: [TODO: Link to section on overrides]<screen>SRC_URI_append_sh4 = " file://fix-makefile.patch;patch=1"</screen>Note
+          that the appended information is a variable itself, and therefore
+          it's possible to used <emphasis>+=</emphasis> or
+          <emphasis>=+</emphasis> to assign variables to the
+          <emphasis>_append</emphasis> information:<screen>SRC_URI_append = " file://fix-makefile.patch;patch=1"
+SRC_URI_append += "file://fix-install.patch;patch=1"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Prepending: _prepend</term>
+
+        <listitem>
+          <para>You can prepend values to existing variables using the
+          _prepend method. Note that this operator does not add any additional
+          space, and it is applied after all the <emphasis>+=</emphasis>, and
+          <emphasis>=+</emphasis> operators have been applied.</para>
+
+          <para>The following example show the space being explicitly added to
+          the end to ensure the prepended value is not merged with the
+          existing value:<screen>CFLAGS_prepend = "-I${S}/myincludes "</screen>The
+          <emphasis>_prepend</emphasis> method can also be used with
+          overrides, which result in the actions only being performed for the
+          specified target or machine: [TODO: Link to section on
+          overrides]<screen>CFLAGS_prepend_sh4 = " file://fix-makefile.patch;patch=1"</screen>Note
+          that the appended information is a variable itself, and therefore
+          it's possible to used <emphasis>+=</emphasis> or
+          <emphasis>=+</emphasis> to assign variables to the
+          <emphasis>_prepend</emphasis> information:<screen>CFLAGS_prepend = "-I${S}/myincludes "
+CFLAGS_prepend += "-I${S}/myincludes2 "</screen>Note also the lack of a space
+          when using += to append to a prepend value - remember that the +=
+          operator is adding space itself.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Spaces vs tabs</term>
+
+        <listitem>
+          <para>Spaces should be used for indentation, not hard tabs. Both
+          currently work, however it is a policy decision of OE that spaces
+          always be used.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Style: oe-stylize.py</term>
+
+        <listitem>
+          <para>To help with using the correct style in your recipes there is
+          a python script in the contrib directory called
+          <emphasis>oe-stylize.py</emphasis> which can be used to reformat
+          your recipes to the correct style. The output will contain a list of
+          warning (to let you know what you did wrong) which should be edited
+          out before using the new file.<screen>contrib/oe-stylize.py myrecipe.bb &gt; fixed-recipe.bb
+vi fixed-recipe.bb
+mv fixed.recipe.bb myrecipe.bb</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Using python for complex operations: ${@...}</term>
+
+        <listitem>
+          <para>For more advanced processing it is possible to use python code
+          during variable assignments, for doing search and replace on a
+          variable for example.</para>
+
+          <para>Python code is indicated by a proceeding @ sign in the
+          variable assignment.<screen>CXXFLAGS := "${@'${CXXFLAGS}'.replace('-frename-registers', '')}"</screen>More
+          information about using python is available in the <xref
+          linkend="recipes_advanced_python" /> section.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Shell syntax</term>
+
+        <listitem>
+          <para>When describing a list of actions to take shell syntax is used
+          (as if you were writing a shell script). You should ensure that you
+          script would work with a generic sh and not require any bash (or
+          other shell) specific functionality. The same applies to various
+          system utilities (sed, grep, awk etc) that you may wish to use. If
+          in doubt you should check with multiple implementations - including
+          those from busybox.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>For a detailed description of the syntax for the bitbake recipe
+    files you should refer to the bitbake use manual.</para>
+  </section>
+
+  <section id="recipes_versioning" xreflabel="versioning">
+    <title>Recipe naming: Names, versions and releases</title>
+
+    <para>Recipes in OpenEmbedded use a standard naming convention that
+    includes the package name and version number in the filename. In addition
+    to the name and version there is also a release number, which is indicates
+    changes to the way the package is built and/or packaged. The release
+    number is contained within the recipe itself.</para>
+
+    <para>The expected format of recipe name is:<screen>&lt;package-name&gt;_&lt;version&gt;.bb</screen></para>
+
+    <para>where <emphasis>&lt;package-name&gt;</emphasis> is the name of the
+    package (application, library, module, or whatever it is that is being
+    packaged) and <emphasis>version</emphasis> is the version number.</para>
+
+    <para>So a typical recipe name would be:<screen>strace_4.5.14.bb</screen>which
+    would be for version <emphasis>4.5.14</emphasis> of the
+    <emphasis>strace</emphasis> application.</para>
+
+    <para>The release version is defined via the package release variable, PR,
+    contained in the recipe. The expected format is:<screen>r&lt;n&gt;</screen>where
+    <emphasis>&lt;n&gt;</emphasis> is an integer number starting from 0
+    initially and then incremented each time the recipe, or something that
+    effects the recipe, is modified. So a typical definition of the release
+    would be:<screen>PR = "r1"</screen>to specify release number
+    <emphasis>1</emphasis> (the second release, the first would have been
+    <emphasis>0</emphasis>). If there is no definition of PR in the recipe
+    then the default value of "r0" is used.</para>
+
+    <para><note>
+        <para>It is good practice to always define PR in your recipes, even
+        for the <emphasis>"r0"</emphasis> release, so that when editing the
+        recipe it is clear that the PR number needs to be updated.</para>
+
+        <para>You should always increment PR when modifying a recipe.
+        Sometimes this can be avoided if the change will have no effect on the
+        actual packages generated by the recipe, such as updating the SRC_URI
+        to point to a new host. If in any doubt then you should increase the
+        PR regardless of what has been changed.</para>
+
+        <para>The PR value should never be decremented. If you accidentally
+        submit a large PR value for example then it should be left at the
+        value and just increased for new releases, not reset back to a lower
+        version.</para>
+      </note></para>
+
+    <para>When a recipe is being processed some variables are automatically
+    set based on the recipe file name and can be used for other purposes from
+    within the recipe itself. These include:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>PN</term>
+
+        <listitem>
+          <para>The package name. Determined from the recipe filename -
+          everything up until the first underscore is considered to be the
+          package name. For the <command>strace_4.5.14.bb</command> recipe the
+          PN variable would be set to <emphasis>"strace"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PV</term>
+
+        <listitem>
+          <para>The package version. Determined from the recipe filename -
+          everything between the first underscore and the final .bb is
+          considered to be the package version. For the
+          <command>strace_4.5.14.bb</command> recipe the PV variable would be
+          set to <emphasis>"4.5.14"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PR</term>
+
+        <listitem>
+          <para>The package release. This is explicitly set in the recipe, or
+          if not set it defaults to "<emphasis>r0"</emphasis> if not
+          set.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>P</term>
+
+        <listitem>
+          <para>The package name and versions separated by a hyphen.<screen>P = "${PN}-${PV}"</screen></para>
+
+          <para>For the <command>strace_4.5.14.bb</command> recipe the P
+          variable would be set to
+          <emphasis>"strace-4.5.14"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PF</term>
+
+        <listitem>
+          <para>The package name, version and release separated by
+          hyphens.<screen>PF = "${PN}-${PV}-${PR}"</screen></para>
+
+          <para>For the s<command>trace_4.5.14.bb recipe</command>, with PR
+          set to <emphasis>"r1"</emphasis> in the recipe, the PF variable
+          would be set to <emphasis>"strace-4.5.14-r1"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>While some of these variables are not commonly used in recipes (they
+    are used internally though) both PN and PV are used a lot.</para>
+
+    <para>In the following example we are instructing the packaging system to
+    include an additional directory in the package. We use PN to refer to the
+    name of the package rather than spelling out the package name:<screen>FILES_${PN} += "${sysconfdir}/myconf"</screen></para>
+
+    <para>In the next example we are specifying the URL for the package
+    source, by using PV in place of the actual version number it is possible
+    to duplicate, or rename, the recipe for a new version without having to
+    edit the URL:<screen>SRC_URI = "ftp://ftp.vim.org/pub/vim/unix/vim-${PV}.tar.bz2"</screen></para>
+  </section>
+
+  <section id="recipes_variables" xreflabel="variables">
+    <title>Variables</title>
+
+    <para>One of the most confusing part of bitbake recipes for new users is
+    the large amount of variables that appear to be available to change and/or
+    control the behaviour of some aspect of the recipe. Some variables, such
+    as those derived from the file name are reasonably obvious, others are not
+    at all obvious.</para>
+
+    <para>There are several places where these variables are derived from
+    and/or used:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>A large number of variables are defined in the bitbake
+        configuration file conf/bitbake.conf - it's often a good idea to look
+        through that file when trying to determine what a particular variable
+        means.</para>
+      </listitem>
+
+      <listitem>
+        <para>Machine and distribution configuration files in conf/machine and
+        conf/distro will sometimes define some variables specific to the
+        machine and/or distribution. You should look at the appropriate files
+        for your targets to see if anything is being defined that effects the
+        recipes you are building.</para>
+      </listitem>
+
+      <listitem>
+        <para>Bitbake itself will define some variables. The FILE variables
+        that defines the name of the bitbake recipe being processed is set by
+        bitbake itself for example. Refer to the bitbake manual for more
+        information on the variables that bitbake sets.</para>
+      </listitem>
+
+      <listitem>
+        <para>The classes, that are used via the inherit keyword, define
+        and/or use the majority of the remaining variables. A class is a like
+        a library that contain parts of a bitbake recipe that are used by
+        multiple recipes. To make them usable in more situations they often
+        include a large number of variables to control how the class
+        operates.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>Another important aspect is that there are three different types of
+    things that binaries and libraries are used for and they often have
+    different variables for each. These include:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>target</term>
+
+        <listitem>
+          <para>Refers to things built for the target are expected to be run
+          on the target device itself.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>native</term>
+
+        <listitem>
+          <para>Refers to things built to run natively on the build host
+          itself.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>cross</term>
+
+        <listitem>
+          <para>Refers to things built to run natively on the build host
+          itself, but produce output which is suitable for the target device.
+          Cross versions of packages usually only exist for things like
+          compilers and assemblers - i.e. things which are used to produce
+          binary applications themselves.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section id="recipes_header" xreflabel="header">
+    <title>Header</title>
+
+    <para>Practically all recipes start was the header section which describes
+    various aspects of the package that is being built. This information is
+    typically used directly by the package format (such as ipkg or deb) as
+    it's meta data used to describe the package.</para>
+
+    <para>Variables used in the header include:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>DESCRIPTION</term>
+
+        <listitem>
+          <para>Describes what the software does. Hopefully this gives enough
+          information to a use to know if it's the right application for
+          them.</para>
+
+          <para>The default description is: <emphasis>"Version ${PV}-${PR} of
+          package ${PN}"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>HOMEPAGE</term>
+
+        <listitem>
+          <para>The URL of the home page of the application where new releases
+          and more information can be found.</para>
+
+          <para>The default homepage is <emphasis>"unknown"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>SECTION</term>
+
+        <listitem>
+          <para>The section is used to categorise the application into a
+          specific group. Often used by GUI based installers to help users
+          when searching for software.</para>
+
+          <para>See <xref linkend="section_variable" /> for a list of the
+          available sections.</para>
+
+          <para>The default section is <emphasis>"base"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PRIORITY</term>
+
+        <listitem>
+          <para>The default priority is
+          <emphasis>"optional"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>LICENSE</term>
+
+        <listitem>
+          <para>The license for the application. If it is not one of the
+          standard licenses then the license itself must be included
+          (where?).</para>
+
+          <para>As well as being used in the package meta-data the license is
+          also used by the src_distribute class.</para>
+
+          <para>The default license is <emphasis>"unknown"</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section id="recipes_sources" xreflabel="sources">
+    <title>Sources: Downloading, patching and additional files</title>
+
+    <para>A recipes purpose is to describe how to take a software package and
+    build it for your target device. The location of the source file (or
+    files) is specified via the <xref linkend="src_uri_variable" /> in the
+    recipe. This can describe several types of URI's, the most common
+    are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>http and https</term>
+
+        <listitem>
+          <para>Specifies files to be downloaded. A copy is stored locally so
+          that future builds will not download the source again.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>cvs, svn and git</term>
+
+        <listitem>
+          <para>Specifies that the files are to be retrieved using the
+          specified version control system.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>files</term>
+
+        <listitem>
+          <para>Plain files which are included locally. These can be used for
+          adding documentation, init scripts or any other files that need to
+          be added to build the package under openembedded.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>patches</term>
+
+        <listitem>
+          <para>Patches are plain files which are treated as patched and
+          automatically applied.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>If a http, https or file URI refers to a compressed file, an archive
+    file or a compressed archive file, such as .tar.gz or .zip, then the files
+    will be uncompressed and extracted from the archive automatically.</para>
+
+    <para>Archive files will be extracted from with the working directory,
+    <emphasis role="bold">${WORKDIR}</emphasis> and plain files will be copied
+    into the same directory. Patches will be applied from within the unpacked
+    source directory, <emphasis role="bold">${S}</emphasis>. (Details on these
+    directories is provided in the next section.)</para>
+
+    <para>The following example from the havp recipe shows a typical <emphasis
+    role="bold">SRC_URI</emphasis> definition:<screen>SRC_URI = "http://www.server-side.de/download/havp-${PV}.tar.gz \
+           file://sysconfdir-is-etc.patch;patch=1 \
+           file://havp.init \
+           file://doc.configure.txt \
+           file://volatiles.05_havp"</screen></para>
+
+    <para>This describes several files</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>http://www.server-side.de/download/havp-${PV}.tar.gz</term>
+
+        <listitem>
+          <para>This is the URI of the havp source code. Note the use of the
+          <emphasis role="bold">${PV}</emphasis> variable to specify the
+          version. This is done to enable the recipe to be renamed for a new
+          version without the need the edit the recipe itself. Because this is
+          a .tar.gz compressed archive the file will be decompressed and
+          extracted in the working dir <emphasis
+          role="bold">${WORKDIR}</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>file://sysconfdir-is-etc.patch;patch=1</term>
+
+        <listitem>
+          <para>This is a local file that is used to patch the extracted
+          source code. The patch=1 is what specifies that this is a patch. The
+          patch will be applied from the unpacked source directory, <emphasis
+          role="bold">${S}</emphasis>. In this case <emphasis
+          role="bold">${S}</emphasis> will be <emphasis
+          role="bold">${WORKDIR}/havp-0.82</emphasis>, and luckily the
+          <emphasis role="bold">havp-0.82.tar.gz</emphasis> file extracts
+          itself into that directory (so no need to explicitly change
+          <emphasis role="bold">${S}</emphasis>).</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>file://havp.init file://doc.configure.txt
+        file://volatiles.05_havp"</term>
+
+        <listitem>
+          <para>These are plain files which are just copied into the working
+          directory <emphasis role="bold">${WORKDIR}</emphasis>. These are
+          then used during the install task in the recipe to provide init
+          scripts, documentation and volatiles configuration information for
+          the package.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Full details on the <emphasis role="bold">SRC_URI</emphasis>
+    variable and all the support URI's is available in the <xref
+    linkend="src_uri_variable" /> section of the reference chapter.</para>
+  </section>
+
+  <section id="recipes_directories" xreflabel="directories">
+    <title>Directories: What goes where</title>
+
+    <para>A large part of the work or a recipe is involved with specifying
+    where files and found and where they have to go. It's important for
+    example that programs do not try and use files from <emphasis
+    role="bold">/usr/include</emphasis> or <emphasis
+    role="bold">/usr/lib</emphasis> since they are for the host system, not
+    the target. Similarly you don't want programs installed into <emphasis
+    role="bold">/usr/bin</emphasis> since that may overwrite your host system
+    programs with versions that don't work on the host!</para>
+
+    <para>The following are some of the directories commonly referred to in
+    recipes and will be described in more detail in the rest of this
+    section:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>Working directory: WORKDIR</term>
+
+        <listitem>
+          <para>This working directory for a recipe is where archive files
+          will be extracted, plain files will be placed, subdirectories for
+          logs, installed files etc will be created.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Unpacked source code directory: S</term>
+
+        <listitem>
+          <para>This is where patches are applied and where the program is
+          expected to be compiled in.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Destination directory: D</term>
+
+        <listitem>
+          <para>The destination directory. This is where your package should
+          be installed into. The packaging system will then take the files
+          from directories under here and package them up for installation on
+          the target.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Installation directories: bindir, docdir, ...</term>
+
+        <listitem>
+          <para>There are a set of variables available to describe all of the
+          paths on the target that you may want to use. Recipes should use
+          these variables rather than hard coding any specific paths.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Staging directories: STAGING_LIBDIR, STAGING_INCDIR, ...</term>
+
+        <listitem>
+          <para>Staging directories are a special area for headers, libraries
+          and other files that are generated by one recipe that may be needed
+          by another recipe. A library package for example needs to make the
+          library and headers available to other recipes so that they can link
+          against them.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>File path directories: FILE, FILE_DIRNAME, FILESDIR,
+        FILESPATH</term>
+
+        <listitem>
+          <para>These directories are used to control where files are found.
+          Understanding these can help you separate patches for different
+          versions or releases of your recipes and/or use the same patch over
+          multiple versions etc.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <section>
+      <title>WORKDIR: The working directory</title>
+
+      <para>The working directory is where the source code is extracted, to
+      which plain files (not patches) are copied and where the logs and
+      installation files are created. A typical reason for needing to
+      reference the work directory is for the handling of non patch
+      files.</para>
+
+      <para>If we take a look at the recipe for quagga we can see an example
+      non patch files for configuration and init scripts:<screen>SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \
+           file://fix-for-lib-inpath.patch;patch=1 \
+           file://quagga.init \
+           file://quagga.default \
+           file://watchquagga.init \
+           file://watchquagga.default"</screen>The recipe has two init files
+      and two configuration files, which are not patches, but are actually
+      files that it wants to include in the generated packages. Bitbake will
+      copy these files into the work directory. So to access them during the
+      install task we refer to them via the <emphasis
+      role="bold">WORKDIR</emphasis> variable:<screen>do_install () {
+    # Install init script and default settings
+    install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
+    install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga
+    install -m 0644 ${WORKDIR}/watchquagga.default ${D}${sysconfdir}/default/watchquagga
+    install -m 0755 ${WORKDIR}/quagga.init ${D}${sysconfdir}/init.d/quagga
+    install -m 0755 ${WORKDIR}/watchquagga.init ${D}${sysconfdir}/init.d/watchquagga
+    ...</screen></para>
+    </section>
+
+    <section>
+      <title>S: The unpacked source code directory</title>
+
+      <para>Bitbake expects to find the extracted source for a package in a
+      directory called <emphasis
+      role="bold">&lt;packagename&gt;-&lt;version&gt;</emphasis> in the
+      <emphasis role="bold">WORKDIR</emphasis> directory. This is the
+      directory in which it will change into before patching, compiling and
+      installating the package.</para>
+
+      <para>For example, we have a package called <emphasis
+      role="bold">widgets_1.2.bb</emphasis> which we are extracting from the
+      <emphasis role="bold">widgets-1.2.tar.gz</emphasis> file. Bitbake
+      expects the source to end up in a directory called <emphasis
+      role="bold">widgets-1.2</emphasis> within the work directory. If the
+      source does not end up in this directory then bitbake needs to be told
+      this by explicitly setting <emphasis role="bold">S</emphasis>.</para>
+
+      <para>If <emphasis role="bold">widgets-1.2.tar.gz</emphasis> actually
+      extracts into a directory called <emphasis
+      role="bold">widgets</emphasis>, without the version number, instead of
+      <emphasis role="bold">widgets-1.2</emphasis> then the <emphasis
+      role="bold">S</emphasis> variable will be wrong and patching and/or
+      compiling will fail. Therefore we need to override the default value of
+      <emphasis role="bold">S</emphasis> to specify the directory the source
+      was actually extracted into:<screen>SRC_URI = "http://www.example.com/software/widgets-${PN}.tar.gz"
+S = "${WORKDIR}/widgets"</screen></para>
+    </section>
+
+    <section>
+      <title>D: The destination directory</title>
+
+      <para>The destination directory is where the completed application and
+      all of it's files are installed into in preparation for packaging.
+      Typically an installation would places files in directories such as
+      <emphasis role="bold">/etc</emphasis> and <emphasis
+      role="bold">/usr/bin</emphasis> by default. Since those directories are
+      used by the host system we do not want the packages to install into
+      those locations. Instead they need to install into the directories below
+      the destination directory.</para>
+
+      <para>So instead of installing into <emphasis
+      role="bold">/usr/bin</emphasis> the package needs to install into
+      <emphasis role="bold">${D}/usr/bin</emphasis>.</para>
+
+      <para>The following example from arpwatch shows the make install command
+      being passed a <emphasis role="bold">${D}</emphasis> as the <emphasis
+      role="bold">DESTDIR</emphasis> variable to control where the makefile
+      installs everything:<screen>do_install() {
+        ...
+        oe_runmake install DESTDIR=${D}</screen></para>
+
+      <para>The following example from quagga shows the use of the destination
+      directory to install the configuration files and init scripts for the
+      package:<screen>do_install () {
+        # Install init script and default settings
+        install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
+        install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga
+        install -m 0755 ${WORKDIR}/quagga.init ${D}${sysconfdir}/init.d/quagga</screen><note>
+          <para>You should not use directories such as <emphasis
+          role="bold">/etc</emphasis> and <emphasis
+          role="bold">/usr/bin</emphasis> directly in your recipes. You should
+          use the variables that define these locations. The full list of
+          these variables can be found in the <xref
+          linkend="directories_installation" /> section of the reference
+          chapter.</para>
+        </note></para>
+    </section>
+
+    <section>
+      <title>Staging directories</title>
+
+      <para>Staging is used to make libraries, headers and binaries available
+      for the build of one recipe for use by another recipe. Building a
+      library for example requires that packages be created containing the
+      libraries and headers for development on the target as well as making
+      them available on the host for building other packages that need the
+      libraries and headers.</para>
+
+      <para>Making the libraries, headers and binaries available for use by
+      other recipes on the host is called staging and is performed by the
+      <emphasis>stage</emphasis> task in the recipe. Any recipes that contain
+      items that are required to build other packages should have a
+      <emphasis>stage</emphasis> task to make sure the items are all correctly
+      placed into the staging area. The following example from clamav show the
+      clamav library and header being placed into the staging area:<screen>do_stage () {
+        oe_libinstall -a -so libclamav ${STAGING_LIBDIR}
+        install -m 0644 libclamav/clamav.h ${STAGING_INCDIR}
+}</screen></para>
+
+      <para>The following from the p3scan recipe show the path to the clamav
+      library and header being passed to the configure script. Without this
+      the configure script would either fail to find the library, or worse
+      still search the host systems directories for the library. Passing in
+      the location results in it searching the correct location and finding
+      the clamav library and headers:<screen>EXTRA_OECONF = "--with-clamav=${STAGING_LIBDIR}/.. \
+                --with-openssl=${STAGING_LIBDIR}/.. \
+                --disable-ripmime"</screen>While the staging directories are
+      automatically added by OpenEmbedded to the compiler and linking commands
+      it is sometimes necessary, as in the p3scan example above, to explicitly
+      specify the location of the staging directories. Typically this is
+      needed for autoconf scripts that search in multiple places for the
+      libraries and headers.</para>
+
+      <note>
+        <para>Many of the helper classes, such as pkgconfig and autotools add
+        appropriate commands to the stage task for you. Check with the
+        individual class descriptions in the reference section to determine
+        what each class is staging automatically for you.</para>
+      </note>
+
+      <para>A full list of staging directories can be found in the <xref
+      linkend="directories_staging" /> section in the reference
+      chapter.</para>
+    </section>
+
+    <section id="recipes_filespath_dir" xreflabel="FILESPATH/FILESDIR">
+      <title>FILESPATH/FILESDIR: Finding local files</title>
+
+      <para>The file related variables are used by bitbake to determine where
+      to look for patches and local files.</para>
+
+      <para>Typically you will not need to modify these, but it is useful to
+      be aware of the default values. In particular when searching for patches
+      and/or files (file:// URI's), the default search path is:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>${FILE_DIRNAME}/${PF}</term>
+
+          <listitem>
+            <para>This is the package name, version and release, such as
+            "<emphasis role="bold">strace-4.5.14-r1</emphasis>". This is very
+            rarely used since the patches would only be found for the one
+            exact release of the recipe.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>${FILE_DIRNAME}/${P}</term>
+
+          <listitem>
+            <para>This is the package name and version, such as "<emphasis
+            role="bold">strace-4.5.14</emphasis>". This is by far the most
+            common place to place version specified patches.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>${FILE_DIRNAME}/${PN}</term>
+
+          <listitem>
+            <para>This is the package name only, such as "<emphasis
+            role="bold">strace</emphasis>". This is not commonly used.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>${FILE_DIRNAME}/files</term>
+
+          <listitem>
+            <para>This is just the directory called "<emphasis
+            role="bold">files</emphasis>". This is commonly used for patches
+            and files that apply to all version of the package.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>${FILE_DIRNAME}/</term>
+
+          <listitem>
+            <para>This is just the base directory of the recipe. This is very
+            rarely used since it would just clutter the main directory.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>Each of the paths is relative to <emphasis
+      role="bold">${FILE_DIRNAME}</emphasis> which is the directory in which
+      the recipe that is being processed is located.</para>
+
+      <para>The full set of variables that control the file locations and
+      patch are:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>FILE</term>
+
+          <listitem>
+            <para>The path to the .bb file which is currently being
+            processed.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>FILE_DIRNAME</term>
+
+          <listitem>
+            <para>The path to the directory which contains the FILE which is
+            currently being processed.<screen>FILE_DIRNAME = "${@os.path.dirname(bb.data.getVar('FILE', d))}"</screen></para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>FILESPATH</term>
+
+          <listitem>
+            <para>The default set of directories which are available to use
+            for the file:// URI's. Each directory is searched, in the
+            specified order, in an attempt to find the file specified by each
+            file:// URI: <screen>FILESPATH = "${FILE_DIRNAME}/${PF}:${FILE_DIRNAME}/${P}:\
+${FILE_DIRNAME}/${PN}:${FILE_DIRNAME}/files:${FILE_DIRNAME}"</screen></para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>FILESDIR</term>
+
+          <listitem>
+            <para>The default directory to search for file:// URI's. Only used
+            if the file is not found in FILESPATH. This can be used to easily
+            add one additional directory to the search path without having to
+            modify the default FILESPATH setting. By default this is just the
+            first directory from FILESPATH. <screen>FILESDIR = "${@bb.which(bb.data.getVar('FILESPATH', d, 1), '.')}" </screen></para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>Sometimes recipes will modify the <emphasis
+      role="bold">FILESPATH</emphasis> or <emphasis
+      role="bold">FILESDIR</emphasis> variables to change the default search
+      path for patches and files. The most common situation in which this is
+      done is when one recipe includes another one in which the default values
+      will be based on the name of the package doing the including, not the
+      included package. Typically the included package will expect the files
+      to be located in a directories based on it's own name.</para>
+
+      <para>As an example the m4-native recipe includes the m4 recipe. This is
+      fine, except that the m4 recipes expects its files and patches to be
+      located in a directory called <emphasis role="bold">m4</emphasis>
+      directory while the native file name results in them being searched for
+      in <emphasis role="bold">m4-native</emphasis>. So the m4-native recipe
+      sets the <emphasis role="bold">FILESDIR</emphasis> variable to the value
+      that of m4 to add the actual m4 directory (where m4 itself has its files
+      stored) to the list of directories search for:<screen>        include m4_${PV}.bb
+        inherit native
+        FILESDIR = "${@os.path.dirname(bb.data.getVar('FILE',d,1))}/m4"</screen></para>
+    </section>
+  </section>
+
+  <section id="recipes_examples" xreflabel="examples">
+    <title>Basic examples</title>
+
+    <para>By now you should know enough about the bitbake recipes to be able
+    to create a basic recipe. We'll cover a simple single file recipe and then
+    a more advanced example that uses the autotools helper class (to be
+    described later) to build an autoconf based package.</para>
+
+    <section id="recipes_helloworld_example" xreflabel="hello world example">
+      <title>Hello world</title>
+
+      <para>Now it's time for our first recipe. This is going to be one of the
+      simplest possible recipes: all code is included and there's only one
+      file to compile and one readme file. While this isn't all that common
+      it's a useful example because it doesn't depend on any of the helper
+      classes which can sometime hide a lot of what is going on.</para>
+
+      <para>First we'll create the myhelloworld.c file and a readme file.
+      We'll place this in the files subdirectory, which is one of the places
+      that is searched for file:// URI's:<screen>mkdir packages/myhelloworld
+mkdir packages/myhelloworld/files
+cat &gt; packages/myhelloworld/files/myhelloworld.c
+#include &lt;stdio.h&gt;
+
+int main(int argc, char** argv)
+{
+        printf("Hello world!\n");
+        return 0;
+}
+^D
+cat &gt; packages/myhelloworld/files/README.txt
+Readme file for myhelloworld.
+^D</screen></para>
+
+      <para>Now we have a directory for our recipe, packages/myhelloworld, and
+      we've created a files subdirectory in there to store our local files.
+      We've created two local files, the C source code for our helloworld
+      program and a readme file. Now we need to create the bitbake
+      recipe.</para>
+
+      <para>First we need the header section, which will contain a description
+      of the package and the release number. We'll leave the other header
+      variables out for now:<screen>DESCRIPTION = "My hello world program"
+PR = "r0"</screen></para>
+
+      <para>Next we need to tell it which files we want to be included in the
+      recipe, which we do via file:// URI's and the SRC_URI variable:<screen>SRC_URI = "file://myhelloworld.c \
+           file://README.txt"</screen></para>
+
+      <para>Note the use of the \ to continue a file and the file of file://
+      local URI's, rather than other types such as http://.</para>
+
+      <para>Now we need provide a compile task which tells bitbake how to
+      compile this program. We do this by defining a do_compile function in
+      the recipe and providing the appropriate commands:</para>
+
+      <para><screen>do_compile() {
+        ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld
+}</screen></para>
+
+      <para>Note the:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>use of the pre-defined compiler variables, <emphasis
+          role="bold">${CC}</emphasis>, <emphasis
+          role="bold">${CFLAGS}</emphasis> and <emphasis
+          role="bold">${LDFLAGS}</emphasis>. These are setup automatically to
+          contain the settings required to cross-compile the program for the
+          target.</para>
+        </listitem>
+
+        <listitem>
+          <para>use of <emphasis role="bold">${WORKDIR}</emphasis> to find the
+          source file. As mentioned previously all files are copied into the
+          working directory and can be referenced via the <emphasis
+          role="bold">${WORKDIR}</emphasis> variable.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>And finally we want to install the program and readme file into
+      the destination directory so that it'll be packaged up correctly. This
+      is done via the install task, so we need to define a do_install function
+      in the recipe to describe how to install the package:<screen>do_install() {
+        install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld
+        install -m 0644 ${S}/myhelloworld ${D}${bindir}
+        install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld
+}</screen></para>
+
+      <para>Note the:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>use the <emphasis role="bold">install</emphasis> command to
+          create directories and install the files, not cp.</para>
+        </listitem>
+
+        <listitem>
+          <para>way directories are created before we attempt to install any
+          files into them. The install command takes care of any
+          subdirectories that are missing, so we only need to create the full
+          path to the directory - no need to create the subdirectories.</para>
+        </listitem>
+
+        <listitem>
+          <para>way we install everything into the destination directory via
+          the use of the <emphasis role="bold">${D}
+          </emphasis>variable.</para>
+        </listitem>
+
+        <listitem>
+          <para>way we use variables to refer to the target directories, such
+          as <emphasis role="bold">${bindir}</emphasis> and <emphasis
+          role="bold">${docdir}</emphasis>.</para>
+        </listitem>
+
+        <listitem>
+          <para>use of <emphasis role="bold">${WORKDIR}</emphasis> to get
+          access to the <emphasis role="bold">README.txt</emphasis> file,
+          which was provided via file:// URI.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>We'll consider this release 0 and version 0.1 of a program called
+      helloworld. So we'll name the recipe myhelloworld_0.1.bb:<screen>cat &gt; packages/myhelloworld/myhelloworld_0.1.bb
+DESCRIPTION = "Hello world program"
+PR = "r0"
+
+SRC_URI = "file://myhelloworld.c \
+           file://README.txt"
+
+do_compile() {
+        ${CC} ${CFLAGS} ${LDFLAGS} ${WORKDIR}/myhelloworld.c -o myhelloworld
+}
+
+do_install() {
+        install -m 0755 -d ${D}${bindir} ${D}${docdir}/myhelloworld
+        install -m 0644 ${S}/myhelloworld ${D}${bindir}
+        install -m 0644 ${WORKDIR}/README.txt ${D}${docdir}/myhelloworld
+}
+^D</screen>Now we are ready to build our package, hopefully it'll all work
+      since it's such a simple example:<screen>~/oe%&gt; bitbake -b packages/myhelloworld/myhelloworld_0.1.bb
+NOTE: package myhelloworld-0.1: started
+NOTE: package myhelloworld-0.1-r0: task do_fetch: started
+NOTE: package myhelloworld-0.1-r0: task do_fetch: completed
+NOTE: package myhelloworld-0.1-r0: task do_unpack: started
+NOTE: Unpacking /home/lenehan/devel/oe/local-packages/myhelloworld/files/helloworld.c to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/myhelloworld-0.1-r0/
+NOTE: Unpacking /home/lenehan/devel/oe/local-packages/myhelloworld/files/README.txt to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/myhelloworld-0.1-r0/
+NOTE: package myhelloworld-0.1-r0: task do_unpack: completed
+NOTE: package myhelloworld-0.1-r0: task do_patch: started
+NOTE: package myhelloworld-0.1-r0: task do_patch: completed
+NOTE: package myhelloworld-0.1-r0: task do_configure: started
+NOTE: package myhelloworld-0.1-r0: task do_configure: completed
+NOTE: package myhelloworld-0.1-r0: task do_compile: started
+NOTE: package myhelloworld-0.1-r0: task do_compile: completed
+NOTE: package myhelloworld-0.1-r0: task do_install: started
+NOTE: package myhelloworld-0.1-r0: task do_install: completed
+NOTE: package myhelloworld-0.1-r0: task do_package: started
+NOTE: package myhelloworld-0.1-r0: task do_package: completed
+NOTE: package myhelloworld-0.1-r0: task do_package_write: started
+NOTE: Not creating empty archive for myhelloworld-dbg-0.1-r0
+Packaged contents of myhelloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/myhelloworld_0.1-r0_sh4.ipk
+Packaged contents of myhelloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/myhelloworld-doc_0.1-r0_sh4.ipk
+NOTE: Not creating empty archive for myhelloworld-dev-0.1-r0
+NOTE: Not creating empty archive for myhelloworld-locale-0.1-r0
+NOTE: package myhelloworld-0.1-r0: task do_package_write: completed
+NOTE: package myhelloworld-0.1-r0: task do_populate_staging: started
+NOTE: package myhelloworld-0.1-r0: task do_populate_staging: completed
+NOTE: package myhelloworld-0.1-r0: task do_build: started
+NOTE: package myhelloworld-0.1-r0: task do_build: completed
+NOTE: package myhelloworld-0.1: completed
+Build statistics:
+  Attempted builds: 1
+~/oe%&gt;</screen></para>
+
+      <para>The package was successfully built, the output consists of two
+      .ipkg files, which are ready to be installed on the target. One contains
+      the binary and the other contains the readme file:<screen>~/oe%&gt; ls -l tmp/deploy/ipk/*/myhelloworld*
+-rw-r--r--  1 lenehan lenehan 3040 Jan 12 14:46 tmp/deploy/ipk/sh4/myhelloworld_0.1-r0_sh4.ipk
+-rw-r--r--  1 lenehan lenehan  768 Jan 12 14:46 tmp/deploy/ipk/sh4/myhelloworld-doc_0.1-r0_sh4.ipk
+~/oe%&gt;</screen></para>
+
+      <para>It's worthwhile looking at the working directory to see where
+      various files ended up:<screen>~/oe%&gt; find tmp/work/myhelloworld-0.1-r0
+tmp/work/myhelloworld-0.1-r0
+tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1
+tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1/patches
+tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1/myhelloworld
+tmp/work/myhelloworld-0.1-r0/temp
+tmp/work/myhelloworld-0.1-r0/temp/run.do_configure.21840
+tmp/work/myhelloworld-0.1-r0/temp/log.do_stage.21840
+tmp/work/myhelloworld-0.1-r0/temp/log.do_install.21840
+tmp/work/myhelloworld-0.1-r0/temp/log.do_compile.21840
+tmp/work/myhelloworld-0.1-r0/temp/run.do_stage.21840
+tmp/work/myhelloworld-0.1-r0/temp/log.do_configure.21840
+tmp/work/myhelloworld-0.1-r0/temp/run.do_install.21840
+tmp/work/myhelloworld-0.1-r0/temp/run.do_compile.21840
+tmp/work/myhelloworld-0.1-r0/install
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-locale
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-dbg
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-dev
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc/myhelloworld
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld-doc/usr/share/doc/myhelloworld/README.txt
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld
+tmp/work/myhelloworld-0.1-r0/image
+tmp/work/myhelloworld-0.1-r0/image/usr
+tmp/work/myhelloworld-0.1-r0/image/usr/bin
+tmp/work/myhelloworld-0.1-r0/image/usr/share
+tmp/work/myhelloworld-0.1-r0/image/usr/share/doc
+tmp/work/myhelloworld-0.1-r0/image/usr/share/doc/myhelloworld
+tmp/work/myhelloworld-0.1-r0/myhelloworld.c
+tmp/work/myhelloworld-0.1-r0/README.txt
+~/oe%&gt;</screen>Things to note here are:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>The two source files are in <emphasis
+          role="bold">tmp/work/myhelloworld-0.1-r0</emphasis>, which is the
+          working directory as specified via the <emphasis
+          role="bold">${WORKDIR}</emphasis> variable;</para>
+        </listitem>
+
+        <listitem>
+          <para>There's logs of the various tasks in <emphasis
+          role="bold">tmp/work/myhelloworld-0.1-r0/temp</emphasis> which you
+          can look at for more details on what was done in each task;</para>
+        </listitem>
+
+        <listitem>
+          <para>There's an image directory at <emphasis
+          role="bold">tmp/work/myhelloworld-0.1-r0/image</emphasis> which
+          contains just the directories that were to be packaged up. This is
+          actually the destination directory, as specified via the <emphasis
+          role="bold">${D}</emphasis> variable. The two files that we
+          installed were originally in here, but during packaging they were
+          moved into the install area into a subdirectory specific to the
+          package that was being created (remember we have a main package and
+          a -doc package being created.</para>
+        </listitem>
+
+        <listitem>
+          <para>The program was actually compiled in the <emphasis
+          role="bold">tmp/work/myhelloworld-0.1-r0/myhelloworld-0.1</emphasis>
+          directory, this is the source directory as specified via the
+          <emphasis role="bold">${S}</emphasis> variable.</para>
+        </listitem>
+
+        <listitem>
+          <para>There's an install directory at <emphasis
+          role="bold">tmp/work/myhelloworld-0.1-r0/install</emphasis> which
+          contains the packages that were being generated and the files that
+          go in the package. So we can see that the myhelloworld-doc package
+          contains the single file <emphasis
+          role="bold">/usr/share/doc/myhelloworld/README.txt</emphasis>, the
+          myhelloworld package contains the single file <emphasis
+          role="bold">/usr/bin/myhelloworld</emphasis> and the -dev, -dbg and
+          -local packages are all empty.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>At this stage it's good to verify that we really did produce a
+      binary for the target and not for our host system. We can check that
+      with the file command:<screen>~/oe%&gt; file tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld
+tmp/work/myhelloworld-0.1-r0/install/myhelloworld/usr/bin/myhelloworld: ELF 32-bit LSB executable, Hitachi SH, version 1 (SYSV), for GNU/Linux 2.4.0, dynamically linked (uses shared libs), for GNU/Linux 2.4.0, not stripped
+~/oe%&gt; file /bin/ls
+/bin/ls: ELF 64-bit LSB executable, AMD x86-64, version 1 (SYSV), for GNU/Linux 2.4.0, dynamically linked (uses shared libs), for GNU/Linux 2.4.0, stripped
+~/oe%&gt;</screen>This shows us that the helloworld program is for an SH
+      processor (obviously this will change depending on what your target
+      system is), while checking the <emphasis role="bold">/bin/ls</emphasis>
+      program on host shows us that the host system is an AMD X86-64 system.
+      That's exactly what we wanted.</para>
+    </section>
+
+    <section id="recipes_autoconf_example" xreflabel="autoconf example">
+      <title>An autotools package</title>
+
+      <para>Now for an example of a package that uses autotools. These are
+      programs that you need to run a configure script for, passing various
+      parameters, and then make. To make these work when cross-compiling you
+      need to provides a lot of variables to the configure script. But all the
+      hard work as already been done for you. There's an <xref
+      linkend="autotools_class" /> which takes care of most of the complexity
+      of building an autotools based packages.</para>
+
+      <para>Let's take a look at the tuxnes recipe which is an example of a
+      very simple autotools based recipe:<screen>%~oe&gt; cat packages/tuxnes/tuxnes_0.75.bb
+DESCRIPTION = "Tuxnes Nintendo (8bit) Emulator"
+HOMEPAGE = "http://prdownloads.sourceforge.net/tuxnes/tuxnes-0.75.tar.gz"
+LICENSE = "GPLv2"
+SECTION = "x/games"
+PRIORITY = "optional"
+PR = "r1"
+
+SRC_URI = "http://heanet.dl.sourceforge.net/sourceforge/tuxnes/tuxnes-0.75.tar.gz"
+
+inherit autotools</screen></para>
+
+      <para>This is a really simple recipe. There's the standard header that
+      describes the package. Then the SRC_URI, which in this case is a http
+      URL that causes the source code to be downloaded from the specified URI.
+      And finally there's an "<emphasis role="bold">inherit
+      autotools</emphasis>" command which loads the autotools class. The
+      autotools class will take care of generating the require configure,
+      compile and install tasks. So in this case there's nothing else to do -
+      that's all there is to it.</para>
+
+      <para>It would be nice if it was always this simple. Unfortunately
+      there's usually a lot more involved for various reasons including the
+      need to:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Pass parameters to configure to enable and disable
+          features;</para>
+        </listitem>
+
+        <listitem>
+          <para>Pass parameters to configure to specify where to find
+          libraries and headers;</para>
+        </listitem>
+
+        <listitem>
+          <para>Make modifications to prevent searching for headers and
+          libraries in the normal locations (since they below to the host
+          system, not the target);</para>
+        </listitem>
+
+        <listitem>
+          <para>Make modifications to prevent the configure script from tying
+          to compile and run programs - any programs it compiles will be for
+          the target and not the host and so cannot be run.</para>
+        </listitem>
+
+        <listitem>
+          <para>Manually implement staging scripts;</para>
+        </listitem>
+
+        <listitem>
+          <para>Deal with lots of other more complex issues;</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Some of these items are covered in more detail in the advanced
+      autoconf section.</para>
+    </section>
+  </section>
+
+  <section id="recipes_depenencies" xreflabel="dependencies">
+    <title>Dependencies: What's needed to build and/or run the
+    package?</title>
+
+    <para>Dependencies should be familiar to anyone who has used an .rpm and
+    .deb based desktop distribution. A dependency is something that a package
+    requires either to run the package (a run-time dependency) or to build the
+    package (a build-time or compile-time, dependency).</para>
+
+    <para>There are two variables provided to allow the specifications of
+    dependencies:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>DEPENDS</term>
+
+        <listitem>
+          <para>Specifies build-time dependencies, via a list of bitbake
+          recipes to build prior to build the recipe. These are programs
+          (flex-native) or libraries (libpcre) that are required in order to
+          build the package.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>RDEPENDS</term>
+
+        <listitem>
+          <para>Specifies run-time dependencies, via a list of packages to
+          install prior to installing the current package. These are programs
+          or libraries that are required in order to run the program. Note
+          that libraries which are dynamically linked to an application will
+          be automatically detected and added to <emphasis
+          role="bold">RDEPENDS</emphasis> and therefore do not need to be
+          explicitly declared. If a library was dynamically loaded then it
+          would need to be explicitly listed.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>If we take openssh for an example, it requires zlib and openssl in
+    order to both built and run. In the recipe we have:<screen>DEPENDS = "zlib openssl"</screen>This
+    tells bitbake that it will need to build and stage zlib and openssl prior
+    to trying to build openssh, since openssh requires both of them. Note that
+    there is no <emphasis role="bold">RDEPENDS</emphasis> even though openssh
+    requires both of them to run. The run time dependencies on libz1 (the name
+    of the package containing the zlib library) and libssl0 (the name of the
+    package containing the ssl library) are automatically determined and added
+    via the auto shared libs dependency code.</para>
+  </section>
+
+  <section id="recipes_methods" xreflabel="methods">
+    <title>Methods: Inbuilt methods to make your life easier</title>
+
+    <para>There are several helper functions defined by the base class, which
+    is included by default for all recipes. Many of these are used a lot in
+    both recipes and other classes.</para>
+
+    <para>The most commonly seen, and most useful functions, include:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>oe_runmake</term>
+
+        <listitem>
+          <para>This function is used to run make. However unlike calling make
+          yourself this will pass the EXTRA_OEMAKE settings to make, will
+          display a note about the make command and will check for any errors
+          generated via the call to make.</para>
+
+          <para>You should never have any reason to call make directly and
+          should also use oe_runmake when you need to run make.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>oe_runconf (autotools only)</term>
+
+        <listitem>
+          <para>This function is used to run the configure script of a package
+          that is using the autotools class. This takes care of passing all of
+          the correct parameters for cross-compiling and for installing into
+          the appropriate target directory.</para>
+
+          <para>It also passes the value of the <emphasis
+          role="bold">EXTRA_OECONF</emphasis> variable to the configure
+          script. For many situations setting <emphasis
+          role="bold">EXTRA_OECONF</emphasis> is sufficient and you'll have no
+          need to define your own configure task in which you call oe_runconf
+          manually.</para>
+
+          <para>If you need to write your own <emphasis>configure</emphasis>
+          task for an autotools package you can use oe_runconf to manually
+          call the configure process when it is required. The following
+          example from net-snmp shows oe_runconf being called manually so that
+          the parameter for specifying the endianess can be computed and
+          passed in to the configure script:<screen>do_configure() {
+    # Additional flag based on target endiness (see siteinfo.bbclass)
+    ENDIANESS="${@base_conditional('SITEINFO_ENDIANESS', 'le', '--with-endianness=little', '--with-endianness=big', d)}"
+    oenote Determined endianess as: $ENDIANESS
+    oe_runconf $ENDIANESS
+}</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>oe_libinstall</term>
+
+        <listitem>
+          <para>This function is used to install <emphasis
+          role="bold">.so</emphasis>, <emphasis role="bold">.a</emphasis> and
+          associated libtool <emphasis role="bold">.la</emphasis> libraries.
+          It will determine the appropriate libraries to install and take care
+          of any modifications that may be require for <emphasis
+          role="bold">.la</emphasis> files.</para>
+
+          <para>This function supports the following options:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term>-C &lt;dir&gt;</term>
+
+              <listitem>
+                <para>Change into the specified directory before attempting to
+                install a library. Used when the libraries are in
+                subdirectories of the main package.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>-s</term>
+
+              <listitem>
+                <para>Require the presence of a <emphasis
+                role="bold">.so</emphasis> library as one of the libraries
+                that is installed.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>-a</term>
+
+              <listitem>
+                <para>Require the presence of a <emphasis
+                role="bold">.a</emphasis> library as one of the libraries that
+                is installed.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+
+          <para>The following example from gdbm shows the installation of
+          <emphasis role="bold">.so</emphasis>, <emphasis
+          role="bold">.a</emphasis> (and associated <emphasis
+          role="bold">.la</emphasis>) libraries into the staging library
+          area:<screen>do_stage () {
+    oe_libinstall -so -a libgdbm ${STAGING_LIBDIR}
+    install -m 0644 ${S}/gdbm.h ${STAGING_INCDIR}/
+}</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>oenote</term>
+
+        <listitem>
+          <para>Used to display an informational messages to the user.</para>
+
+          <para>The following example from net-snmp uses oenote to tell the
+          user which endianess it determined was appropriate for the target
+          device:<screen>do_configure() {
+    # Additional flag based on target endiness (see siteinfo.bbclass)
+    ENDIANESS="${@base_conditional('SITEINFO_ENDIANESS', 'le', '--with-endianness=little', '--with-endianness=big', d)}"
+    oenote Determined endianess as: $ENDIANESS
+    oe_runconf $ENDIANESS
+}</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>oewarn</term>
+
+        <listitem>
+          <para>Used to display a warning message to the user, warning of
+          something that may be problematic or unexpected.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>oedebug</term>
+
+        <listitem>
+          <para>Used to display debugging related information. These messages
+          will only be visible when bitbake is run with the <emphasis
+          role="bold">-D</emphasis> flag to enable debug output.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>oefatal</term>
+
+        <listitem>
+          <para>Used to display a fatal error message to the user, and then
+          abort the bitbake run.</para>
+
+          <para>The following example from linux-libc-headers shows the use of
+          oefatal to tell the user when it cannot find the kernel source code
+          for the specified target architecture:<screen>do_configure () {
+    case ${TARGET_ARCH} in
+        alpha*)   ARCH=alpha ;;
+        arm*)     ARCH=arm ;;
+        cris*)    ARCH=cris ;;
+        hppa*)    ARCH=parisc ;;
+        i*86*)    ARCH=i386 ;;
+        ia64*)    ARCH=ia64 ;;
+        mips*)    ARCH=mips ;;
+        m68k*)    ARCH=m68k ;;
+        powerpc*) ARCH=ppc ;;
+        s390*)    ARCH=s390 ;;
+        sh*)      ARCH=sh ;;
+        sparc64*) ARCH=sparc64 ;;
+        sparc*)   ARCH=sparc ;;
+        x86_64*)  ARCH=x86_64 ;;
+    esac
+    if test !  -e include/asm-$ARCH; then
+        oefatal unable to create asm symlink in kernel headers
+    fi
+...</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>base_conditional (python)</term>
+
+        <listitem>
+          <para>The base conditional python function is used to set a variable
+          to one of two values based on the definition of a third variable.
+          The general usage is:<screen>${@base_conditional('&lt;variable-name&gt;', '&lt;value&gt;', '&lt;true-result&gt;', &lt;false-result&gt;', d)}"</screen>where:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term>variable-name</term>
+
+              <listitem>
+                <para>This is the name of a variable to check.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>value</term>
+
+              <listitem>
+                <para>This is the value to compare the variable
+                against.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>true-result</term>
+
+              <listitem>
+                <para>If the variable equals the value then this is what is
+                returned by the function.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>false-result</term>
+
+              <listitem>
+                <para>If the variable does not equal the value then this is
+                what is returned by the function.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+
+          <note>
+            <para>The ${@...} syntax is used to call python functions from
+            within a recipe or class. This is described in more detail in the
+            <xref linkend="recipes_advanced_python" /> section.</para>
+          </note>
+
+          <para>The following example from the openssl recipe shows the
+          addition of either <emphasis role="bold">-DL_ENDING</emphasis> or
+          <emphasis role="bold">-DB_ENDIAN</emphasis> depending on the value
+          of <emphasis role="bold">SITEINFO_ENDIANESS</emphasis> which is set
+          to le for little endian targets and to be for big endian
+          targets:<screen>do_compile () {
+    ...
+    # Additional flag based on target endiness (see siteinfo.bbclass)
+    CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"
+    ...</screen></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section id="recipes_packages" xreflabel="packages">
+    <title>Packaging: Defining packages and their contents</title>
+
+    <para>A bitbake recipe is a set of instructions from creating one, or
+    more, packages for installation on the target device. Typically these are
+    .ipkg or .deb packages (although bitbake itself isn't associated with any
+    particular packaging format).</para>
+
+    <para>By default several packages are produced automatically without any
+    special action required on the part of the recipe author. The following
+    example of the packaging output from the helloworld example above shows
+    this packaging in action:<screen>[NOTE: package helloworld-0.1-r0: task do_package_write: started
+NOTE: Not creating empty archive for helloworld-dbg-0.1-r0
+Packaged contents of helloworld into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld_0.1-r0_sh4.ipk
+Packaged contents of helloworld-doc into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/helloworld-doc_0.1-r0_sh4.ipk
+NOTE: Not creating empty archive for helloworld-dev-0.1-r0
+NOTE: Not creating empty archive for helloworld-locale-0.1-r0
+NOTE: package helloworld-0.1-r0: task do_package_write: completed</screen>We
+    can see from above that the packaging did the following:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Created a main package, <emphasis
+        role="bold">helloworld_0.1-r0_sh4.ipk</emphasis>. This package
+        contains the helloworld binary <emphasis
+        role="bold">/usr/bin/helloworld</emphasis>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Created a documentation package, <emphasis
+        role="bold">helloworld-doc_0.1-r0_sh4.ipk</emphasis>. This package
+        contains the readme file <emphasis
+        role="bold">/usr/share/doc/helloworld/README.txt</emphasis>.</para>
+      </listitem>
+
+      <listitem>
+        <para>Considered creating a debug package, <emphasis
+        role="bold">helloworld-dbg-0.1-r0_sh4.ipk</emphasis>, a development
+        package <emphasis role="bold">helloworld-dev-0.1-r0_sh4.ipk</emphasis>
+        and a locale package <emphasis
+        role="bold">helloworld-locale-0.1-r0_sh4.ipk</emphasis>. It didn't
+        create the package due to the fact that it couldn't find any files
+        that would actually go in the package.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>There are several things happening here which are important to
+    understand:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>There is a default set of packages that are considered for
+        creation. This set of packages is controlled via the <emphasis
+        role="bold">PACKAGES</emphasis> variable.</para>
+      </listitem>
+
+      <listitem>
+        <para>For each package there is a default set of files and/or
+        directories that are considered to belong to those packages. The
+        documentation packages for example include anything found <emphasis
+        role="bold">/usr/share/doc</emphasis>. The set of files and
+        directories is controlled via the <emphasis
+        role="bold">FILES_&lt;package-name&gt;</emphasis> variables.</para>
+      </listitem>
+
+      <listitem>
+        <para>By default packages that contain no files are not created and no
+        error is generated. The decision to create empty packages or not is
+        controlled via the <emphasis role="bold">ALLOW_EMPTY</emphasis>
+        variable.</para>
+      </listitem>
+    </orderedlist>
+
+    <section>
+      <title>Philosophy</title>
+
+      <para>Separate packaging, where possible, is of high importance in
+      OpenEmbedded. Many of the target devices have limited storage space and
+      RAM and giving distributions and users the option of not installing a
+      part of the package they don't need allows them to reduce the amount of
+      storage space required.</para>
+
+      <para>As an example almost no distributions will include documentation
+      or development libraries since they are not required for the day to day
+      operation of the device. In particular if your package provides multiple
+      binaries, and it would be common to only use one or the other, then you
+      should consider separating them into separate packages.</para>
+
+      <para>By default several groups of files are automatically separate out,
+      including:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>dev</term>
+
+          <listitem>
+            <para>Any files required for development. This includes header
+            files, static libraries, the shared library symlinks required only
+            for linking etc. These would only ever need to be installed by
+            someone attempt to compile applications on the target device.
+            While this does happen it is very uncommon and so these files are
+            automatically moved into a separate package</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>doc</term>
+
+          <listitem>
+            <para>Any documentation related files, including man pages. These
+            are files which are of informational purposes only. For many
+            embedded devices there is no way for the user to see any of the
+            documentation anyway, and documentation can consume a lot of
+            space. By separating these out they don't take any space by
+            default but distributions and/or users may choose to install them
+            if they need some documentation on a specific package.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>locale</term>
+
+          <listitem>
+            <para>Locale information provides translation information for
+            packages. Many users do not require these translations, and many
+            devices will only want to provide them for user visible
+            components, such as UI related items, and not for system binaries.
+            By separating these out it is left up to the distribution or users
+            to decide if they are required or not.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </section>
+
+    <section>
+      <title>Default packages and files</title>
+
+      <para>The defaults package settings are defined in <emphasis
+      role="bold">conf/bitbake.conf</emphasis> and are suitable for a lot of
+      recipes without any changes. The following list shows the default values
+      for the packaging related variables:</para>
+
+      <para><variablelist>
+          <varlistentry>
+            <term>PACKAGES</term>
+
+            <listitem>
+              <para>This variable lists the names of each of the packages that
+              are to be generated.<screen>PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen>Note
+              that the order of packages is important: the packages are
+              processed in the listed order. So if two packages specify the
+              same file then the first package listed in packages will get the
+              file. This is important when packages use wildcards to specify
+              their contents.</para>
+
+              <para>For example if the main package, <emphasis
+              role="bold">${PN}</emphasis>, contains <emphasis
+              role="bold">/usr/bin/*</emphasis> (i.e. all files in <emphasis
+              role="bold">/usr/bin</emphasis>), but you want <emphasis
+              role="bold">/usr/bin/tprogram</emphasis> in a separate package,
+              <emphasis role="bold">${PN}-tpackage</emphasis>, you would need
+              to either ensure that <emphasis
+              role="bold">${PN}-tpackage</emphasis> is listed prior to
+              <emphasis role="bold">${PN}</emphasis> in <emphasis
+              role="bold">PACKAGES</emphasis> or that <emphasis
+              role="bold">FILES_${PN}</emphasis> was modified to not contain
+              the wildcard that matches <emphasis
+              role="bold">/usr/bin/tprogram</emphasis>.</para>
+
+              <para>Note that the -dbg package contains the debugging
+              information that has been extracted from binaries and libraries
+              prior to them being stripped. This package should always be the
+              first package in the package list to ensure that the debugging
+              information is correctly extracted and moved to the package
+              prior to any other packaging decisions being made.</para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>FILES_${PN}</term>
+
+            <listitem>
+              <para>The base package, this includes everything needed to
+              actually run the application on the target system.<screen>FILES_${PN} = "\
+    ${bindir}/* \
+    ${sbindir}/* \
+    ${libexecdir}/* \
+    ${libdir}/lib*.so.* \
+    ${sysconfdir} \
+    ${sharedstatedir} \
+    ${localstatedir} \
+    /bin/* \
+    /sbin/* \
+    /lib/*.so* \
+    ${datadir}/${PN} \
+    ${libdir}/${PN}/* \
+    ${datadir}/pixmaps \
+    ${datadir}/applications \
+    ${datadir}/idl \
+    ${datadir}/omf \
+    ${datadir}/sounds \
+    ${libdir}/bonobo/servers"</screen></para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>FILES_${PN}-dbg</term>
+
+            <listitem>
+              <para>The debugging information extracted from non-stripped
+              versions of libraries and executable's. OpenEmbedded
+              automatically extracts the debugging information into files in
+              .debug directories and then strips the original files.<screen>FILES_${PN}-dbg = "\
+    ${bindir}/.debug \
+    ${sbindir}/.debug \
+    ${libexecdir}/.debug \
+    ${libdir}/.debug \
+    /bin/.debug \
+    /sbin/.debug \
+    /lib/.debug \
+    ${libdir}/${PN}/.debug"</screen></para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>FILES_${PN}-doc</term>
+
+            <listitem>
+              <para>Documentation related files. All documentation is
+              separated into it's own package so that it does not need to be
+              installed unless explicitly required.<screen>FILES_${PN}-doc = "\
+    ${docdir} \
+    ${mandir} \
+    ${infodir} \
+    ${datadir}/gtk-doc \
+    ${datadir}/gnome/help"</screen></para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>FILES_${PN}-dev</term>
+
+            <listitem>
+              <para>Development related files. Any headers, libraries and
+              support files needed for development work on the target.<screen>FILES_${PN}-dev = "\
+    ${includedir} \
+    ${libdir}/lib*.so \
+    ${libdir}/*.la \
+    ${libdir}/*.a \
+    ${libdir}/*.o \
+    ${libdir}/pkgconfig \
+    /lib/*.a \
+    /lib/*.o \
+    ${datadir}/aclocal"</screen></para>
+            </listitem>
+          </varlistentry>
+
+          <varlistentry>
+            <term>FILES_${PN}-locale</term>
+
+            <listitem>
+              <para>Locale related files.<screen>FILES_${PN}-locale = "${datadir}/locale"</screen></para>
+            </listitem>
+          </varlistentry>
+        </variablelist></para>
+    </section>
+
+    <section>
+      <title>Wildcards</title>
+
+      <para>Wildcards used in the <emphasis role="bold">FILES</emphasis>
+      variables are processed via the python function <emphasis
+      role="bold">fnmatch</emphasis>. The following items are of note about
+      this function:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para><emphasis role="bold">/&lt;dir&gt;/*</emphasis>: This will
+          match all files and directories in the <emphasis
+          role="bold">dir</emphasis> - it will not match other
+          directories.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">/&lt;dir&gt;/a*</emphasis>: This will
+          only match files, and not directories.</para>
+        </listitem>
+
+        <listitem>
+          <para><emphasis role="bold">/dir</emphasis>: will include the
+          directory <emphasis role="bold">dir</emphasis> in the package, which
+          in turn will include all files in the directory and all
+          subdirectories.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Note that the order of packages effects the files that will be
+      matched via wildcards. Consider the case where we have three binaries in
+      the <command>/usr/bin</command> directory and we want the test program
+      in a separate package:<screen>/usr/bin/programa /usr/bin/programb /usr/bin/test</screen>So
+      we define a new package and instruct bitbake to include /usr/bin/test in
+      it.</para>
+
+      <screen>FILES-${PN}-test = "${bindir}/test"
+PACKAGES += "FILES-${PN}-test"</screen>
+
+      <para>When the package is regenerated no <emphasis
+      role="bold">${PN}-test</emphasis> package will be created. The reason
+      for this is that the <emphasis role="bold">PACKAGES</emphasis> line now
+      looks like this:<screen>{PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-locale ${PN}-test</screen>Note
+      how <emphasis role="bold">${PN}</emphasis> is listed prior to <emphasis
+      role="bold">${PN}-test</emphasis>, and if we look at the definition of
+      <emphasis role="bold">FILES-${PN}</emphasis> it contains the <emphasis
+      role="bold">${bindir}/*</emphasis> wildcard. Since <emphasis
+      role="bold">${PN}</emphasis> is first it'll match that wildcard are be
+      moved into the <emphasis role="bold">${PN}</emphasis> package prior to
+      processing of the <emphasis role="bold">${PN}-test</emphasis>
+      package.</para>
+
+      <para>To achieve what we are trying to accomplish we have two
+      options:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Modify the definition of <emphasis
+          role="bold">${PN}</emphasis> so that the wildcard does not match the
+          test program.</para>
+
+          <para>We could do this for example:<screen>FILES-${PN} = "${bindir}/p*"</screen>So
+          now this will only match things in the bindir that start with p, and
+          therefore not match our test program. Note that <emphasis
+          role="bold">FILES-${PN}</emphasis> contains a lot more entries and
+          we'd need to add any of the other that refer to files that are to be
+          included in the package. In this case we have no other files, so
+          it's safe to do this simple declaration.</para>
+        </listitem>
+
+        <listitem>
+          <para>Modify the order of packages so that the <emphasis
+          role="bold">${PN}-test</emphasis> package is listed first.</para>
+
+          <para>The most obvious way to do this would be to prepend our new
+          package name to the packages list instead of appending it:<screen>PACKAGES =+ "FILES-${PN}-test"</screen>In
+          some cases this would work fine, however there is a problem with
+          this for packages that include binaries. The package will now be
+          listed before the -dbg package and often this will result in the
+          .debug directories being included in the package. In this case we
+          are explicitly listing only a single file (and not using wildcards)
+          and therefore it would be ok.</para>
+
+          <para>In general it's more common to have to redefine the entire
+          package list to include your new package plus any of the default
+          packages that you require:<screen>PACKAGES = "${PN}-dbg ${PN}-test ${PN} ${PN}-doc ${PN}-dev ${PN}-locale"</screen></para>
+        </listitem>
+      </orderedlist>
+    </section>
+
+    <section>
+      <title>Checking the packages</title>
+
+      <para>During recipe development it's useful to be able to check on
+      exactly what files went into each package, which files were not packaged
+      and which packages contain no files.</para>
+
+      <para>One of easiest method is to run find on the install directory. In
+      the install directory there is one subdirectory created per package, and
+      the files are moved into the install directory as they are matched to a
+      specific package. The following shows the packages and files for the
+      helloworld example:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/install
+tmp/work/helloworld-0.1-r0/install
+tmp/work/helloworld-0.1-r0/install/helloworld-locale
+tmp/work/helloworld-0.1-r0/install/helloworld-dbg
+tmp/work/helloworld-0.1-r0/install/helloworld-dev
+tmp/work/helloworld-0.1-r0/install/helloworld-doc
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld
+tmp/work/helloworld-0.1-r0/install/helloworld-doc/usr/share/doc/helloworld/README.txt
+tmp/work/helloworld-0.1-r0/install/helloworld
+tmp/work/helloworld-0.1-r0/install/helloworld/usr
+tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin
+tmp/work/helloworld-0.1-r0/install/helloworld/usr/bin/helloworld
+~/oe%&gt;</screen>The above shows that the -local, -dbg and -dev packages are
+      all empty, and the -doc and base package contain a single file each.
+      Uses "<emphasis role="bold">-type f</emphasis>" option to find to show
+      just files will make this clearer as well.</para>
+
+      <para>In addition to the install directory the image directory (which
+      corresponds to the destination directory, <emphasis
+      role="bold">D</emphasis>) will contain any files that were not
+      packaged:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/image
+tmp/work/helloworld-0.1-r0/image
+tmp/work/helloworld-0.1-r0/image/usr
+tmp/work/helloworld-0.1-r0/image/usr/bin
+tmp/work/helloworld-0.1-r0/image/usr/share
+tmp/work/helloworld-0.1-r0/image/usr/share/doc
+tmp/work/helloworld-0.1-r0/image/usr/share/doc/helloworld
+~/oe%&gt;</screen>In this case all files were packaged and so there are no
+      left over files. Using find with "<emphasis role="bold">-type
+      f</emphasis>" makes this much clearer:<screen>~/oe%&gt; find tmp/work/helloworld-0.1-r0/image -type f
+~/oe%&gt;</screen></para>
+
+      <para>Messages reading missing files are also display by bitbake during
+      the package task:<screen>NOTE: package helloworld-0.1-r0: task do_package: started
+NOTE: the following files were installed but not shipped in any package:
+NOTE:   /usualdir/README.txt
+NOTE: package helloworld-0.1-r0: task do_package: completed</screen>Except in
+      very unusual circumstances there should be no unpackaged files left
+      behind by a recipe.</para>
+    </section>
+
+    <section>
+      <title>Excluding files</title>
+
+      <para>There's no actual support for explicitly excluding files from
+      packaging. You could just leave them out of any package, but then you'll
+      get warnings (or errors if requesting full package checking) during
+      packaging which is not desirable. It also doesn't let other people know
+      that you've deliberately avoided packaging the file or files.</para>
+
+      <para>In order to exclude a file totally you should avoid installing it
+      in the first place during the install task.</para>
+
+      <para>In some cases it may be easier to let the package install the file
+      and then explicitly remove the file and the end of the install task. The
+      following example from the samba recipe shows the removal of several
+      files that get installed via the default install task generated by the
+      <xref linkend="autotools_class" />. By using
+      <emphasis>do_install_append</emphasis> these commands and run after the
+      autotools generated install task:</para>
+
+      <screen>do_install_append() {
+    ...
+    rm -f ${D}${bindir}/*.old
+    rm -f ${D}${sbindir}/*.old
+    ...
+}</screen>
+    </section>
+
+    <section>
+      <title>Debian naming</title>
+
+      <para>A special <emphasis>debian library name</emphasis> policy can be
+      applied for packages that contain a single shared library. When enabled
+      packages will be renamed to match the debian policy for such
+      packages.</para>
+
+      <para>Debian naming is enabled by including the debian class via either
+      <command>local.conf</command> or your distributions configuration
+      file:<screen>INHERIT += "debian"</screen></para>
+
+      <para>The policy works by looking at the shared library name and version
+      and will automatically rename the package to
+      <emphasis>&lt;libname&gt;&lt;lib-major-version&gt;</emphasis>. For
+      example if the package name (PN) is <command>foo</command> and the
+      package ships a file named <command>libfoo.so.1.2.3</command> then the
+      package will be renamed to <command>libfoo1</command> to follow the
+      debian policy.</para>
+
+      <para>If we look at the <emphasis>lzo_1.08.bb</emphasis> recipe,
+      currently at release 14, it generates a package containing a single
+      shared library :<screen>~oe/build/titan-glibc-25%&gt; find tmp/work/lzo-1.08-r14/install/
+tmp/work/lzo-1.08-r14/install/lzo
+tmp/work/lzo-1.08-r14/install/lzo/usr
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0</screen>Without
+      debian naming this package would have been called
+      <command>lzo_1.08-r14_sh4.ipk</command> (and the corresponding dev and
+      dbg packages would have been called
+      <command>lzo-dbg_1.08-r14_sh4.ipk</command> and
+      <command>lzo-dev_1.08-r14_sh4.ipk</command>). However with debian naming
+      enabled the package is renamed based on the name of the shared library,
+      which is <command>liblzo.so.1.0.0</command> in this case. So the name
+      <command>lzo</command> is replaced with
+      <command>liblzo1</command>:<screen>~oe/build/titan-glibc-25%&gt; find tmp/deploy/ipk/ -name '*lzo*'  
+tmp/deploy/ipk/sh4/liblzo1_1.08-r14_sh4.ipk
+tmp/deploy/ipk/sh4/liblzo-dev_1.08-r14_sh4.ipk
+tmp/deploy/ipk/sh4/liblzo-dbg_1.08-r14_sh4.ipk</screen></para>
+
+      <para>Some variables are available which effect the operation of the
+      debian renaming class:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>LEAD_SONAME</term>
+
+          <listitem>
+            <para>If the package actually contains multiple shared libraries
+            then one will be selected automatically and a warning will be
+            generated. This variable is a regular expression which is used to
+            select which shared library from those available is to be used for
+            debian renaming.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>DEBIAN_NOAUTONAME_&lt;pkgname&gt;</term>
+
+          <listitem>
+            <para>If this variable is set to 1 for a package then debian
+            renaming will not be applied for the package.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>AUTO_LIBNAME_PKGS</term>
+
+          <listitem>
+            <para>If set this variable specifies the prefix of packages which
+            will be subject to debian renaming. This can be used to prevent
+            all of the packages being renamed via the renaming policy.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </section>
+
+    <section>
+      <title>Empty packages</title>
+
+      <para>By default empty packages are ignored. Occasionally you may wish
+      to actually created empty packages, typically done when you want a
+      virtual package which will install other packages via dependencies
+      without actually installing anything itself. The <emphasis
+      role="bold">ALLOW_EMPTY</emphasis> variable is used to control the
+      creation of empty packages:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>ALLOW_EMPTY</term>
+
+          <listitem>
+            <para>Controls if empty packages will be created or not. By
+            default this is <emphasis role="bold">"0"</emphasis> and empty
+            packages are not created. Setting this to <emphasis
+            role="bold">"1"</emphasis> will permit the creation of empty
+            packages (packages containing no files).</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </section>
+  </section>
+
+  <section id="recipes_tasks" xreflabel="tasks">
+    <title>Tasks: Playing with tasks</title>
+
+    <para>Bitbake steps through a series of tasks when building a recipe.
+    Sometimes you need to explicitly define what a class does, such as
+    providing a <emphasis role="bold">do_install</emphasis> function to
+    implement the <emphasis>install</emphasis> task in a recipe and sometimes
+    they are provided for you by common classes, such as the autotools class
+    providing the default implementations of <emphasis>configure</emphasis>,
+    <emphasis>compile</emphasis> and <emphasis>install</emphasis>
+    tasks.</para>
+
+    <para>There are several methods available to modify the tasks that are
+    being run:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>Overriding the default task implementation</term>
+
+        <listitem>
+          <para>By defining your own implementation of task you'll override
+          any default or class provided implementations.</para>
+
+          <para>For example, you can define you own implementation of the
+          compile task to override any default implementation:<screen>do_compile() {
+      oe_runmake DESTDIR=${D}
+}</screen></para>
+
+          <para>If you with to totally prevent the task from running you need
+          to define your own empty implementation. This is typically done via
+          the definition of the task using a single colon:<screen>do_configure() {
+    :
+}</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Appending or prepending to the task</term>
+
+        <listitem>
+          <para>Sometime you want the default implementation, but you require
+          addition functionality. This can done by appending or pre-pending
+          additional functionality onto the task.</para>
+
+          <para>The following example from units shows an example of
+          installing an addition file which for some reason was not installed
+          via the autotools normal <emphasis>install</emphasis> task:<screen>do_install_append() {
+       install -d ${D}${datadir}
+       install -m 0655 units.dat ${D}${datadir}
+}</screen></para>
+
+          <para>The following example from the cherokee recipe show an example
+          of adding functionality prior to the default
+          <emphasis>install</emphasis> task. In this case it compiles a
+          program that is used during installation natively so that it will
+          work on the host. Without this the autotools default
+          <emphasis>install</emphasis> task would fail since it'd try to run
+          the program on the host which was compiled for the target:<screen>do_install_prepend () {
+        # It only needs this app during the install, so compile it natively
+        $BUILD_CC -DHAVE_SYS_STAT_H -o cherokee_replace cherokee_replace.c
+}</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Defining a new task</term>
+
+        <listitem>
+          <para>Another option is define a totally new task, and then register
+          that with bitbake so that it runs in between two of the existing
+          tasks.</para>
+
+          <para>The following example shows a situation in which a cvs tree
+          needs to be copied over the top of an extracted tar.gz archive, and
+          this needs to be done before any local patches are applied. So a new
+          task is defined to perform this action, and then that task is
+          registered to run between the existing <emphasis>unpack</emphasis>
+          and <emphasis>patch</emphasis> tasks:<screen>do_unpack_extra(){
+    cp -pPR ${WORKDIR}/linux/* ${S}
+}
+addtask unpack_extra after do_unpack before do_patch</screen></para>
+
+          <note>
+            <para>The task to add does not have the do_ prepended to it,
+            however the tasks to insert it after and before do have the _do
+            prepended. No errors will be generated if this is wrong, the
+            additional task simple won't be executed.</para>
+          </note>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>Using overrides</term>
+
+        <listitem>
+          <para>Overrides (described fully elsewhere) allow for various
+          functionality to be performed conditionally based on the target
+          machine, distribution, architecture etc.</para>
+
+          <para>While not commonly used it is possible to use overrides when
+          defining tasks. The following example from udev shows an additional
+          file being installed for the specified machine only by performing an
+          append to the <emphasis>install</emphasis> task for the h2200
+          machine only:<screen>do_install_append_h2200() {
+    install -m 0644 ${WORKDIR}/50-hostap_cs.rules         ${D}${sysconfdir}/udev/rules.d/50-hostap_cs.rules
+}</screen></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section id="recipes_classes" xreflabel="classes">
+    <title>Classes: The separation of common functionality</title>
+
+    <para>Often a certain pattern is followed in more than one recipe, or
+    maybe some complex python based functionality is required to achieve the
+    desired end result. This is achieved through the use of classes, which can
+    be found in the classes subdirectory at the top-level of on OE
+    checkout.</para>
+
+    <para>Being aware of the available classes and understanding their
+    functionality is important because classes:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Save developers time being performing actions that they would
+        otherwise need to perform themselves;</para>
+      </listitem>
+
+      <listitem>
+        <para>Perform a lot of actions in the background making a lot of
+        recipes difficult to understand unless you are aware of classes and
+        how they work;</para>
+      </listitem>
+
+      <listitem>
+        <para>A lot of detail on how things work can be learnt for looking at
+        how classes are implement.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>A class is used via the inherit method. The following is an example
+    for the <emphasis>curl</emphasis> recipe showing that it uses three
+    classes:<screen>inherit autotools pkgconfig binconfig</screen>In this case
+    it is utilising the services of three separate classes:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>autotools</term>
+
+        <listitem>
+          <para>The <xref linkend="autotools_class" /> is used by programs
+          that use the GNU configuration tools and takes care of the
+          configuration and compilation of the software;</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>pkgconfig</term>
+
+        <listitem>
+          <para>The <xref linkend="pkgconfig_class" /> is used to stage the
+          <emphasis>.pc</emphasis> files which are used by the <emphasis
+          role="bold">pkg-config</emphasis> program to provide information
+          about the package to other software that wants to link to this
+          software;</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>binconfig</term>
+
+        <listitem>
+          <para>The <xref linkend="binconfig_class" /> is used to stage the
+          <emphasis>&lt;name&gt;-config</emphasis> files which are used to
+          provide information about the package to other software that wants
+          to link to this software;</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Each class is implemented via the file in the <emphasis
+    role="bold">classes</emphasis> subdirectory named <emphasis
+    role="bold">&lt;classname&gt;.bbclass</emphasis> and these can be examined
+    for further details on a particular class, although sometimes it's not
+    easy to understand everything that's happening. Many of the classes are
+    covered in detail in various sections in this user manual.</para>
+  </section>
+
+  <section id="recipes_staging" xreflabel="staging">
+    <title>Staging: Making includes and libraries available for
+    building</title>
+
+    <para>Staging is the process of making files, such as include files and
+    libraries, available for use by other recipes. This is different to
+    installing because installing is about making things available for
+    packaging and then eventually for use on the target device. Staging on the
+    other hand is about making things available on the host system for use by
+    building later applications.</para>
+
+    <para>Taking bzip2 as an example you can see that it stages a header file
+    and it's library files:<screen>do_stage () {
+    install -m 0644 bzlib.h ${STAGING_INCDIR}/
+    oe_libinstall -a -so libbz2 ${STAGING_LIBDIR}
+}</screen></para>
+
+    <para>The <emphasis>oe_libinstall</emphasis> method used in the bzip2
+    recipe is described in the <xref linkend="recipes_methods" /> section, and
+    it takes care of installing libraries (into the staging area in this
+    case). The staging variables are automatically defined to the correct
+    staging location, in this case the main staging variables are used:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>STAGING_INCDIR</term>
+
+        <listitem>
+          <para>The directory into which staged headers files should be
+          installed. This is the equivalent of the standard <emphasis
+          role="bold">/usr/include</emphasis> directory.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>STAGING_LIBDIR</term>
+
+        <listitem>
+          <para>The directory into which staged library files should be
+          installed. This is the equivalent of the standard <emphasis
+          role="bold">/usr/lib</emphasis> directory.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Additional staging related variables are covered in the <xref
+    linkend="directories_staging" /> section in <xref
+    linkend="chapter_reference" />.</para>
+
+    <para>Looking in the staging area under tmp you can see the result of the
+    bzip2 recipes staging task:<screen>%&gt; find tmp/staging -name '*bzlib*'
+tmp/staging/sh4-linux/include/bzlib.h
+%&gt; find tmp/staging -name '*libbz*'
+tmp/staging/sh4-linux/lib/libbz2.so
+tmp/staging/sh4-linux/lib/libbz2.so.1.0
+tmp/staging/sh4-linux/lib/libbz2.so.1
+tmp/staging/sh4-linux/lib/libbz2.so.1.0.2
+tmp/staging/sh4-linux/lib/libbz2.a</screen></para>
+
+    <para>As well as being used during the stage task the staging related
+    variables are used when building other packages. Looking at the gnupg
+    recipe we see two bzip2 related items:<screen>DEPENDS = "zlib <emphasis
+          role="bold">bzip2</emphasis>"
+...
+EXTRA_OECONF = "--disable-ldap \
+        --with-zlib=${STAGING_LIBDIR}/.. \
+        <emphasis role="bold">--with-bzip2=${STAGING_LIBDIR}/..</emphasis> \
+        --disable-selinux-support"
+</screen></para>
+
+    <para>Bzip2 is referred to in two places in the recipe:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>DEPENDS</term>
+
+        <listitem>
+          <para>Remember that <emphasis role="bold">DEPENDS</emphasis> defines
+          the list of build time dependencies. In this case the staged headers
+          and libraries from bzip2 are required to build gnupg, and therefore
+          we need to make sure the bzip2 recipe has run and staging the
+          headers and libraries. By adding the <emphasis
+          role="bold">DEPENDS</emphasis> on bzip2 this ensures that this
+          happens.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><emphasis role="bold">EXTRA_OECONF</emphasis></term>
+
+        <listitem>
+          <para>This variable is used by the <xref
+          linkend="autotools_class" /> to provide options to the configure
+          script of the package. In the gnupg case it needs to be told where
+          the bzip2 headers and libraries files are, and this is done via the
+          <emphasis>--with-bzip2</emphasis> option. In this case it needs to
+          the directory which include the lib and include subdirectories.
+          Since OE doesn't define a variable for one level above the include
+          and lib directories <emphasis role="bold">..</emphasis> is used to
+          indicate one directory up. Without this gnupg would search the host
+          system headers and libraries instead of those we have provided in
+          the staging area for the target.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Remember that staging is used to make things, such as headers and
+    libraries, available to used by other recipes later on. While header and
+    libraries are the most common item requiring staging other items such as
+    the pkgconfig files need to be staged as well, while for native packages
+    the binaries also need to be staged.</para>
+  </section>
+
+  <section id="recipes_autoconf" xreflabel="about autoconf">
+    <title>Autoconf: All about autotools</title>
+
+    <para>This section is to be completed:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>About building autoconf packages</para>
+      </listitem>
+
+      <listitem>
+        <para>EXTRA_OECONF</para>
+      </listitem>
+
+      <listitem>
+        <para>Problems with /usr/include, /usr/lib</para>
+      </listitem>
+
+      <listitem>
+        <para>Configuring to search in the staging area</para>
+      </listitem>
+
+      <listitem>
+        <para>-L${STAGING_LIBDIR} vs ${TARGET_LDFLAGS}</para>
+      </listitem>
+
+      <listitem>
+        <para>Site files</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="recipes_installation_scripts" xreflabel="installation scripts">
+    <title>Installation scripts: Running scripts during package install and/or
+    removal</title>
+
+    <para>Packaging system such as .ipkg and .deb support pre and post
+    installation and pre and post removal scripts which are run during package
+    install and/or package removal on the target system.</para>
+
+    <para>These scripts can be defined in your recipes to enable actions to be
+    performed at the appropriate time. Common uses include starting new
+    daemons on installation, stopping daemons during uninstall, creating new
+    user and/or group entries during install, registering and unregistering
+    alternative implementations of commands and registering the need for
+    volatiles.</para>
+
+    <para>The following scripts are supported:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>preinst</term>
+
+        <listitem>
+          <para>The preinst script is run prior to installing the contents of
+          the package. During preinst the contents of the package are not
+          available to be used as part of the script. The preinst scripts are
+          not commonly used.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>postinst</term>
+
+        <listitem>
+          <para>The postinst script is run after the installation of the
+          package has completed. During postinst the contents of the package
+          are available to be used. This is often used for the creation of
+          volatile directories, registration of daemons, starting of daemons
+          and fixing up of SUID binaries.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>prerm</term>
+
+        <listitem>
+          <para>The prerm is run prior to the removal of the contents of a
+          package. During prerm the contents of the package are still
+          available for use by the script. The prerm scripts</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>postrm</term>
+
+        <listitem>
+          <para>The postrm script is run after the completion of the removal
+          of the contents of a package. During postrm the contents of the
+          package no longer exist and therefore are not available for use by
+          the script. Postrm is most commonly used for update alternatives (to
+          tell the alternatives system that this alternative is not available
+          and another should be selected).</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Scripts are registered by defining a function for:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>pkg_&lt;scriptname&gt;_&lt;packagename&gt;</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>The following example from ndisc6 shows postinst scripts being
+    registered for three of the packages that ndisc6 creates:<screen># Enable SUID bit for applications that need it
+pkg_postinst_${PN}-rltraceroute6 () {
+    chmod 4555 ${bindir}/rltraceroute6
+}
+pkg_postinst_${PN}-ndisc6 () {
+    chmod 4555 ${bindir}/ndisc6
+}
+pkg_postinst_${PN}-rdisc6 () {
+    chmod 4555 ${bindir}/rdisc6
+}</screen></para>
+
+    <note>
+      <para>These scripts will be run via <emphasis
+      role="bold">/bin/sh</emphasis> on the target device, which is typically
+      the busybox sh but could also be bash or some other sh compatible shell.
+      As always you should not use any bash extensions in your scripts and
+      stick to basic sh syntax.</para>
+    </note>
+
+    <para>Note that several classes will also register scripts, and that any
+    script you declare will have the script for the classes append to by these
+    classes. The following classes all generate additional script
+    contents:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>update-rc.d</term>
+
+        <listitem>
+          <para>This class is used by daemons to register there init scripts
+          with the init code.</para>
+
+          <para>Details are provided in the <xref
+          linkend="recipes_initscripts" /> section.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>module</term>
+
+        <listitem>
+          <para>This class is used by linux kernel modules. It's responsible
+          for calling depmod and update-modules during kernel module
+          installation and removal.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>kernel</term>
+
+        <listitem>
+          <para>This class is used by the linux kernel itself. There is a lot
+          of housekeeping required both when installing and removing a kernel
+          and this class is responsible for generating the required
+          scripts.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>qpf</term>
+
+        <listitem>
+          <para>This class is used when installing and/or removing qpf fonts.
+          It register scripts to update the font paths and font cache
+          information to ensure that the font information is kept up to date
+          as fonts and installed and removed.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>update-alternatives</term>
+
+        <listitem>
+          <para>This class is used by packages that contain binaries which may
+          also be available for other packages. It tells that system that
+          another alternative is available for consideration. The alternatives
+          system will create a symlink to the correct alternative from one or
+          more available on the system.</para>
+
+          <para>Details are provided in the <xref
+          linkend="recipes_alternatives" /> section.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>gtk-icon-cache</term>
+
+        <listitem>
+          <para>This class is used by packages that add new gtk icons. It's
+          responsible for updating the icon cache when packages are installed
+          and removed.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>gconf</term>
+
+        <listitem>
+          <para></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>package</term>
+
+        <listitem>
+          <para>The base class used by packaging classes such as those for
+          .ipkg and .deb. The package class may create scripts used to update
+          the dynamic linkers ld cache.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>The following example from p3scan shows and postinst script which
+    ensure that the required user and group entries exist, and registers the
+    need for volatiles (directories and/or files under <emphasis
+    role="bold">/var</emphasis>). In addition to explicitly declaring a
+    postinst script it uses the update-rc.d class which will result in an
+    additional entry being added to the postinst script to register the init
+    scripts and start the daemon (via call to update-rc.d as describes in the
+    <xref linkend="recipes_alternatives" /> section).<screen>inherit autotools update-rc.d
+
+...
+
+# Add havp's user and groups
+pkg_postinst_${PN} () {
+        grep -q mail: /etc/group || addgroup --system havp
+        grep -q mail: /etc/passwd || \
+            adduser --disabled-password --home=${localstatedir}/mail --system \
+                    --ingroup mail --no-create-home -g "Mail" mail
+        /etc/init.d/populate-volatile.sh update
+}</screen></para>
+
+    <para>Several scripts in existing recipes will be of the following
+    form:<screen>if [ x"$D" = "x" ]; then
+    ...
+fi</screen></para>
+
+    <para>This is testing if the installation directory, <emphasis
+    role="bold">D</emphasis>, is defined and if it is no actions are
+    performed. The installation directory will not be defined under normal
+    circumstances. The primary use of this test is to permit the application
+    to be installed during root filesystem generation. In that situation the
+    scripts cannot be run since the root filesystem is generated on the host
+    system and not on the target. Any required script actions would need to be
+    performed via an alternative method if the package is to be installed in
+    the initial root filesystem (such as including any required users and
+    groups in the default <emphasis role="bold">passwd</emphasis> and
+    <emphasis role="bold">group</emphasis> files for example.)</para>
+  </section>
+
+  <section id="recipes_conffiles" xreflabel="conf files">
+    <title>Configuration files</title>
+
+    <para>Configuration files that are installed as part of a package require
+    special handling. Without special handling as soon as the user upgrades to
+    a new version of the package then changes they have made to the
+    configuration files will be lost.</para>
+
+    <para>In order to prevent this from happening you need to tell the
+    packaging system which files are configuration files. Such files will
+    result in the user being asked how the user wants to handle any
+    configuration file changes (if any), as shown in this example:<screen>Downloading http://nynaeve.twibble.org/ipkg-titan-glibc//./p3scan_2.9.05d-r1_sh4.ipk
+    Configuration file '/etc/p3scan/p3scan.conf'
+    ==&gt; File on system created by you or by a script.
+    ==&gt; File also in package provided by package maintainer.
+       What would you like to do about it ?  Your options are:
+        Y or I  : install the package maintainer's version
+        N or O  : keep your currently-installed version
+          D     : show the differences between the versions (if diff is installed)
+     The default action is to keep your current version.
+    *** p3scan.conf (Y/I/N/O/D) [default=N] ?</screen>To declare a file as a
+    configuration file you need to define the
+    <command>CONFFILES_&lt;pkgname&gt;</command> variable as a whitespace
+    separated list of configuration files. The following example from clamav
+    shows two files being marked as configuration files:<screen>CONFFILES_${PN}-daemon = "${sysconfdir}/clamd.conf \
+                          ${sysconfdir}/default/clamav-daemon"</screen>Note
+    the user of <command>${PN}-daemon</command> as the package name. The
+    <command>${PN}</command> variable will expand to <command>clamav</command>
+    and therefore these conf files are declared as being in the clamav-daemon
+    package.</para>
+  </section>
+
+  <section id="recipes_package_relationships"
+           xreflabel="package relationships files">
+    <title>Package relationships</title>
+
+    <para>Explicit relationships between packages are support by packaging
+    formats such as ipkg and deb. These relationships include describing
+    conflicting packages and recommended packages.</para>
+
+    <para>The following variables control the package relationships in the
+    recipes:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>RRECOMMENDS</term>
+
+        <listitem>
+          <para>Used to specify other packages that are recommended to be
+          installed when this package is installed. Generally this means while
+          the recommended packages are not required they provide some sort of
+          functionality which users would usually want.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>RCONFLICTS</term>
+
+        <listitem>
+          <para>Used to specify other packages that conflict with this
+          package. Two packages that conflict cannot be installed at the same
+          time.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>RREPLACES</term>
+
+        <listitem>
+          <para>Used to specify that the current package replaces an older
+          package with a different name. During package installing the package
+          that is being replaced will be removed since it is no longer needed
+          when this package is installed.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>RSUGGESTS</term>
+
+        <listitem>
+          <para>Used to provide a list of suggested packages to install. These
+          are packages that are related to and useful for the current package
+          but which are not actually required to use the package.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>RPROVIDES</term>
+
+        <listitem>
+          <para>Used to explicitly specify what a package provides at runtime.
+          For example hotplug support is provided by several packages, such as
+          udev and linux-hotplug. Both declare that they runtime provide
+          "hotplug". So any packages that require "hotplug" to work simply
+          declare that it RDEPENDS on "hotplug". It's up to the distribution
+          to specify which actual implementation of "virtual/xserver" is
+          used.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>PROVIDES</term>
+
+        <listitem>
+          <para>Used to explicitly specify what a package provides at build
+          time. This is typically used when two or more packages can provide
+          the same functionality. For example there are several different X
+          servers in OpenEmbedded, and each as declared as providing
+          "virtual/xserver". Therefore a package that depends on an X server
+          to build can simply declare that it DEPENDS on "virtual/xserver".
+          It's up to the distribution to specify which actual implementation
+          of "virtual/xserver" is used.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section id="recipes_fakeroot" xreflabel="fakeroot">
+    <title>Fakeroot: Dealing with the need for "root"</title>
+
+    <para>Sometimes packages requires root permissions in order to perform
+    some action, such as changing user or group owners or creating device
+    nodes. Since OpenEmbedded will not keep the user and group information
+    it's usually preferably to remove that from the makefiles. For device
+    nodes it's usually preferably to create them from the initial device node
+    lists or via udev configuration.</para>
+
+    <para>However if you can't get by without root permissions then you can
+    use <xref linkend="fakeroot" /> to simulate a root environment, without
+    the need to really give root access.</para>
+
+    <para>Using <xref linkend="fakeroot" /> is done by prefixing the
+    task:<screen>fakeroot do_install() {</screen>Since this requires fakeroot
+    you also need to add a dependency on
+    <command>fakeroot-native</command>:<screen>DEPENDS = "fakeroot-native"</screen>See
+    the fuse recipe for an example. Further information on <xref
+    linkend="fakeroot" />, including a description of it works, is provided in
+    the reference section: <xref linkend="fakeroot" />.</para>
+  </section>
+
+  <section id="recipes_native" xreflabel="native">
+    <title>Native: Packages for the build host</title>
+
+    <para>This section is to be completed.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>What native packages are</para>
+      </listitem>
+
+      <listitem>
+        <para>Using require with the non-native package</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="recipes_development" xreflabel="development">
+    <title>Development: Strategies for developing recipes</title>
+
+    <para>This section is to be completed.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>How to go about developing recipes</para>
+      </listitem>
+
+      <listitem>
+        <para>How do handle incrementally creating patches</para>
+      </listitem>
+
+      <listitem>
+        <para>How to deal with site file issues</para>
+      </listitem>
+
+      <listitem>
+        <para>Strategies for autotools issues</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="recipes_advanced_versioning" xreflabel="advanced versioning">
+    <title>Advanced versioning: How to deal with rc and pre versions</title>
+
+    <para>Special care needs to be taken when specify the version number for
+    rc and pre versions of packages.</para>
+
+    <para>Consider the case where we have an existing 1.5 version and there's
+    a new 1.6-rc1 release that you want to add.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>1.5: Existing version;</para>
+      </listitem>
+
+      <listitem>
+        <para>1.6-rc1: New version.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>If the new package is given the version number 1.6-rc1 then
+    everything will work fine initially. However when the final release
+    happens it will be called 1.6. If you now create a 1.6 version of the
+    package you'll find that the packages are sorted into the following
+    order:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>1.5</para>
+      </listitem>
+
+      <listitem>
+        <para>1.6</para>
+      </listitem>
+
+      <listitem>
+        <para>1.6-rc1</para>
+      </listitem>
+    </orderedlist>
+
+    <para>This in turn result in packaging system, such as ipkg, considering
+    the released version to be older then the rc version.</para>
+
+    <para>In OpenEmbedded the correct naming of pre and rc versions is to use
+    the previous version number followed by a + followed by the new version
+    number. So the 1.6-rc1 release would be given the version number:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>1.5+1.6-rc1</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>These would result in the eventually ordering being:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>1.5</para>
+      </listitem>
+
+      <listitem>
+        <para>1.5+1.6-rc1</para>
+      </listitem>
+
+      <listitem>
+        <para>1.6</para>
+      </listitem>
+    </orderedlist>
+
+    <para>This is the correct order and the packaging system will now work as
+    expected.</para>
+  </section>
+
+  <section id="recipes_require" xreflabel="require">
+    <title>Require/include: Reusing recipe contents</title>
+
+    <para>In many packages where you are maintaining multiple versions you'll
+    often end up with several recipes which are either identical, or have only
+    minor differences between them.</para>
+
+    <para>The require and/or include directive can be used to include common
+    content from one file into other. You should always look for a way to
+    factor out common functionality into an include file when adding new
+    versions of a recipe.</para>
+
+    <note>
+      <para>Both require and include perform the same function - including the
+      contents of another file into this recipe. The difference is that
+      require will generate an error if the file is not found while include
+      will not. For this reason include should not be used in new
+      recipes.</para>
+    </note>
+
+    <para>For example the clamav recipe looks like this:<screen>require clamav.inc
+
+PR = "r0"</screen>Note that all of the functionality of the recipe is provided
+    in the clamav.inc file, only the release number is defined in the recipe.
+    Each of the recipes includes the same <emphasis
+    role="bold">clamav.inc</emphasis> file to save having to duplicate any
+    functionality. This also means that as new versions are released it's a
+    simple matter of copying the recipe and resetting the release number back
+    to zero.</para>
+
+    <para>The following example from iproute2 shows the recipe adding
+    additional patches that are not specified by the common included file.
+    These are patches only needed for newer release and by only adding them in
+    this recipe it permits the common code to be used for both old and new
+    recipes:<screen>PR = "r1"
+
+SRC_URI += "file://iproute2-2.6.15_no_strip.diff;patch=1;pnum=0 \
+            file://new-flex-fix.patch;patch=1"
+
+require iproute2.inc
+
+DATE = "060323"</screen></para>
+
+    <para>The following example from cherokee shows a similar method of
+    including additional patches for this version only. However it also show
+    another technique in which the configure task is defined in the recipe for
+    this version, thus replacing the <emphasis>configure</emphasis> task that
+    is provided by the common include:<screen>PR = "r7"
+
+SRC_URI_append = "file://configure.patch;patch=1 \
+                  file://Makefile.in.patch;patch=1 \
+                  file://Makefile.cget.patch;patch=1 \
+                  file://util.patch;patch=1"
+
+require cherokee.inc
+
+do_configure() {
+        gnu-configize
+        oe_runconf
+        sed -i 's:-L\$:-L${STAGING_LIBDIR} -L\$:' ${S}/*libtool
+}</screen></para>
+  </section>
+
+  <section id="recipes_advanced_python" xreflabel="advanced python">
+    <title>Python: Advanced functionality with python</title>
+
+    <para>Recipes permit the use of python code in order to perform complex
+    operations which are not possible with the normal recipe syntax and
+    variables. Python can be used in both variable assignments and in the
+    implementation of tasks.</para>
+
+    <para>For variable assignments python code is indicated via the use of
+    <emphasis>${@...}</emphasis>, as shown in the following example:<screen>TAG = ${@bb.data.getVar('PV',d,1).replace('.', '_')}</screen></para>
+
+    <para>The above example retrieves the PV variable from the bitbake data
+    object, the replaces any dots with underscores. Therefore if the <emphasis
+    role="bold">PV</emphasis> was <emphasis role="bold">0.9.0</emphasis> then
+    <emphasis role="bold">TAG</emphasis> will be set to <emphasis
+    role="bold">0-9-0</emphasis>.</para>
+
+    <para>Some of the more common python code in use in existing recipes is
+    shown in the following table:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>bb.data.getVar(&lt;var&gt;,d,1)</term>
+
+        <listitem>
+          <para>Retrieve the data for the specified variable from the bitbake
+          database for the current recipe.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>&lt;variable&gt;.replace(&lt;key&gt;,
+        &lt;replacement&gt;)</term>
+
+        <listitem>
+          <para>Find each instance of the key and replace it with the
+          replacement value. This can also be used to remove part of a string
+          by specifying <emphasis role="bold">''</emphasis> (two single
+          quotes) as the replacement.</para>
+
+          <para>The following example would remove the <emphasis
+          role="bold">'-frename-registers'</emphasis> option from the
+          <emphasis role="bold">CFLAGS</emphasis> variable:<screen>CFLAGS := "${@'${CFLAGS}'.replace('-frename-registers', '')}"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>os.path.dirname(&lt;filename&gt;)</term>
+
+        <listitem>
+          <para>Return the directory only part of a filename.</para>
+
+          <para>This is most commonly seen in existing recipes when settings
+          the <emphasis role="bold">FILESDIR</emphasis> variable (as described
+          in the <xref linkend="recipes_filespath_dir" /> section). By
+          obtaining name of the recipe file itself, <emphasis
+          role="bold">FILE</emphasis>, and then using os.path.dirname to strip
+          the filename part:<screen>FILESDIR = "${@os.path.dirname(bb.data.getVar('FILE',d,1))}/make-${PV}"</screen>Note
+          however that this is no longer required as <emphasis
+          role="bold">FILE_DIRNAME</emphasis> is automatically set to the
+          dirname of the <emphasis role="bold">FILE</emphasis> variable and
+          therefore this would be written in new recipes as:<screen>FILESDIR = "$FILE_DIRNAME/make-${PV}"</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>&lt;variable&gt;.split(&lt;key&gt;)[&lt;index&gt;]</term>
+
+        <listitem>
+          <para>Splits are variable around the specified key. Use <emphasis
+          role="bold">[&lt;index&gt;]</emphasis> to select one of the matching
+          items from the array generated by the split command.</para>
+
+          <para>The following example from the recipe g<emphasis
+          role="bold">enext2fs_1.3+1.4rc1.bb</emphasis> would take the
+          <emphasis role="bold">PV</emphasis> of <emphasis
+          role="bold">1.3+1.4rc1</emphasis> and split it around the <emphasis
+          role="bold">+</emphasis> sign, resulting in an array containing
+          <emphasis role="bold">1.3</emphasis> and <emphasis
+          role="bold">1.4rc1</emphasis>. It then uses the index of <emphasis
+          role="bold">[1]</emphasis> to select the second item from the list
+          (the first item is at index <emphasis role="bold">0</emphasis>).
+          Therefore <emphasis role="bold">TRIMMEDV</emphasis> would be set to
+          <emphasis role="bold">1.4rc1</emphasis> for this recipe:</para>
+
+          <screen>TRIMMEDV = "${@bb.data.getVar('PV', d, 1).split('+')[1]}"</screen>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>As well as directly calling built-in python functions, those
+    functions defined by the existing classes may also be called. A set of
+    common functions is provided by the base class in <emphasis
+    role="bold">classes/base.bbclass</emphasis>:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>base_conditional</term>
+
+        <listitem>
+          <para>This functions is used to set a variable to one of two values
+          based on the definition of a third variable. The general usage
+          is:<screen>${@base_conditional('&lt;variable-name&gt;', '&lt;value&gt;', '&lt;true-result&gt;', &lt;false-result&gt;', d)}"</screen>where:</para>
+
+          <variablelist>
+            <varlistentry>
+              <term>variable-name</term>
+
+              <listitem>
+                <para>This is the name of a variable to check.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>value</term>
+
+              <listitem>
+                <para>This is the value to compare the variable
+                against.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>true-result</term>
+
+              <listitem>
+                <para>If the variable equals the value then this is what is
+                returned by the function.</para>
+              </listitem>
+            </varlistentry>
+
+            <varlistentry>
+              <term>false-result</term>
+
+              <listitem>
+                <para>If the variable does not equal the value then this is
+                what is returned by the function.</para>
+              </listitem>
+            </varlistentry>
+          </variablelist>
+
+          <para>The following example from the openssl recipe shows the
+          addition of either <emphasis role="bold">-DL_ENDING</emphasis> or
+          <emphasis role="bold">-DB_ENDIAN</emphasis> depending on the value
+          of <emphasis role="bold">SITEINFO_ENDIANESS</emphasis> which is set
+          to le for little endian targets and to be for big endian
+          targets:<screen>do_compile () {
+    ...
+    # Additional flag based on target endiness (see siteinfo.bbclass)
+    CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"
+    ...</screen></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>base_contains</term>
+
+        <listitem>
+          <para>Similar to base_conditional expect that it is checking for the
+          value being an element of an array. The general usage is:<screen>${@base_contains('&lt;array-name&gt;', '&lt;value&gt;', '&lt;true-result&gt;', &lt;false-result&gt;', d)}"</screen></para>
+
+          <para>where:<variablelist>
+              <varlistentry>
+                <term>array-name</term>
+
+                <listitem>
+                  <para>This is the name of the array to search.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>value</term>
+
+                <listitem>
+                  <para>This is the value to check for in the array.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>true-result</term>
+
+                <listitem>
+                  <para>If the value is found in the array then this is what
+                  is returned by the function.</para>
+                </listitem>
+              </varlistentry>
+
+              <varlistentry>
+                <term>false-result</term>
+
+                <listitem>
+                  <para>If the value is not found in the array then this is
+                  what is returned by the function.</para>
+                </listitem>
+              </varlistentry>
+            </variablelist>The following example from the task-angstrom-x11
+          recipe shows base_contains being used to add a recipe to the runtime
+          dependency list but only for machines which have a
+          touchscreen:</para>
+
+          <screen>RDEPENDS_angstrom-gpe-task-base := "\
+    ...
+    ${@base_contains("MACHINE_FEATURES", "touchscreen", "libgtkstylus", "",d)} \
+    ...</screen>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Tasks may be implemented in python by prefixing the task function
+    with "python ". In general this should not be needed and should be avoided
+    where possible. The following example from the devshell recipe shows how
+    the compile task is implemented python:<screen>python do_compile() {
+    import os
+    import os.path
+
+    workdir = bb.data.getVar('WORKDIR', d, 1)
+    shellfile = os.path.join(workdir, bb.data.expand("${TARGET_PREFIX}${DISTRO}-${MACHINE}-devshell", d))
+
+    f = open(shellfile, "w")
+
+    # emit variables and shell functions
+        devshell_emit_env(f, d, False, ["die", "oe", "autotools_do_configure"])
+
+    f.close()
+}</screen></para>
+  </section>
+
+  <section id="recipes_defaultpreference" xreflabel="default preference">
+    <title>Preferences: How to disable packages</title>
+
+    <para>When bitbake is asked to build a package and multiple versions of
+    that package are available then bitbake will normally select the version
+    that has the highest version number (where the version number is defined
+    via the <command>PV</command> variable).</para>
+
+    <para>For example if we were to ask bitbake to build procps and the
+    following packages are available:<screen>~/oe%&gt; ls packages/procps 
+procps-3.1.15/    procps-3.2.1/    procps-3.2.5/    procps-3.2.7/    procps.inc
+procps_3.1.15.bb  procps_3.2.1.bb  procps_3.2.5.bb  procps_3.2.7.bb
+~/oe%&gt;</screen>then we would expect it to select version
+    <command>3.2.7</command> (the highest version number) to build.</para>
+
+    <para>Sometimes this is not actually what you want to happen though.
+    Perhaps you have added a new version of the package that does not yet work
+    or maybe the new version has no support for your target yet. Help is at
+    hand since bitbake is not only looking at the version numbers to decided
+    which version to build but it is also looking at the preference for each
+    of those version. The preference is defined via the
+    <command>DEFAULT_PREFERENCE</command> variable contained within the
+    recipe.</para>
+
+    <para>The default preference (when no
+    <command>DEFAULT_PREFERENCE</command> is specified) is zero. Bitbake will
+    find the highest preference that is available and then for all the
+    packages at the preference level it will select the package with the
+    highest version. In general this means that adding a positive
+    <command>DEFAULT_PREFERENCE</command> will cause the package to be
+    preferred over other versions and a negative
+    <command>DEFAULT_PREFERENCE</command> will cause all other packages to be
+    preferred.</para>
+
+    <para>Imagine that you are adding procps version 4.0.0, but that it does
+    not yet work. You could delete or rename your new recipe so you can build
+    a working image, but what you really to do is just ignore the new 4.0.0
+    version until it works. By adding:<screen>DEFAULT_PREFERENCE = "-1"</screen>to
+    the recipe this is what will happen. Bitbake will now ignore this version
+    (since all of the existing versions have a preference of 0). Note that you
+    can still call bitbake directly on the recipe:<screen>bitbake -b packages/procps/procps_4.0.0.bb</screen>This
+    enables you to test, and fix the package manually without having bitbake
+    automatically select normally.</para>
+
+    <para>By using this feature in conjunction with overrides you can also
+    disable (or select) specific versions based on the override. The following
+    example from glibc shows that this version has been disabled for the sh3
+    architecture because it doesn't support sh3. This will force bitbake to
+    try and select one of the other available versions of glibc
+    instead:<screen>packages/glibc/glibc_2.3.2+cvs20040726.bb:DEFAULT_PREFERENCE_sh3 = "-99"</screen></para>
+  </section>
+
+  <section id="recipes_initscripts" xreflabel="initscripts">
+    <title>Initscripts: How to handle daemons</title>
+
+    <para>This section is to be completed.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>update-rc.d class</para>
+      </listitem>
+
+      <listitem>
+        <para>sh syntax</para>
+      </listitem>
+
+      <listitem>
+        <para>stop/stop/restart params</para>
+      </listitem>
+
+      <listitem>
+        <para>samlpe/standard script?</para>
+      </listitem>
+
+      <listitem>
+        <para>volatiles</para>
+      </listitem>
+    </itemizedlist>
+  </section>
+
+  <section id="recipes_alternatives" xreflabel="alternatives">
+    <title>Alternatives: How to handle the same command in multiple
+    packages</title>
+
+    <para>Alternatives are used when the same command is provided by multiple
+    packages. A classic example is busybox, which provides a whole set of
+    commands such as <emphasis role="bold">/bin/ls</emphasis> and <emphasis
+    role="bold">/bin/find</emphasis>, which are also provided by other
+    packages such as coreutils (<emphasis role="bold">/bin/ls</emphasis>) and
+    findutils (<emphasis role="bold">/bin/find</emphasis>).</para>
+
+    <para>A system for handling alternatives is required to allow the user to
+    choose which version of the command they wish to have installed. It should
+    be possible to install either one, or both, or remove one when both are
+    installed etc, and to have no issues with the packages overwriting files
+    from other packages.</para>
+
+    <para>The most common reason for alternatives is to reduce the size of the
+    binaries. But cutting down on features, built in help and error messages
+    and combining multiple binaries into one large binary it's possible to
+    save considerable space. Often users are not expected to use the commands
+    interactively in embedded appliances and therefore these changes have no
+    visible effect to the user. In some situations users may have interactive
+    access, or they may be more advanced users who want shell access on
+    appliances that normal don't provide it, and in these cases they should be
+    able to install the full functional version if they desire.</para>
+
+    <section>
+      <title>Example of alternative commands</title>
+
+      <para>Most distributions include busybox in place of the full featured
+      version of the commands. The following example shows a typical install
+      in which the find command, which we'll use as an example here, is the
+      busybox version:<screen>root@titan:~$ find --version
+find --version
+BusyBox v1.2.1 (2006.12.17-05:10+0000) multi-call binary
+
+Usage: find [PATH...] [EXPRESSION]
+
+root@titan:~$ which find
+which find
+/usr/bin/find</screen>If we now install the full version of find:<screen>root@titan:~$ ipkg install findutils
+ipkg install findutils
+Installing findutils (4.2.29-r0) to root...
+Downloading http://nynaeve.twibble.org/ipkg-titan-glibc//./findutils_4.2.29-r0_sh4.ipk
+Configuring findutils
+
+update-alternatives: Linking //usr/bin/find to find.findutils
+update-alternatives: Linking //usr/bin/xargs to xargs.findutils</screen></para>
+
+      <para>Then we see that the standard version of find changes to the full
+      featured implement ion:<screen>root@titan:~$ find --version
+find --version
+GNU find version 4.2.29
+Features enabled: D_TYPE O_NOFOLLOW(enabled) LEAF_OPTIMISATION
+root@titan:~$ which find
+which find
+/usr/bin/find</screen></para>
+    </section>
+
+    <section>
+      <title>Using update-alternatives</title>
+
+      <para>Two methods of using the alternatives system are available:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Via the <xref linkend="update-alternatives_class" />. This is
+          the simplest method, but is not usable in all situations.</para>
+        </listitem>
+
+        <listitem>
+          <para>Via directly calling the update-alternatives command.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>The <xref linkend="update-alternatives_class" /> is the provides
+      the simplest method of using alternatives but it only works for a single
+      alternative. For multiple alternatives they need to be manually
+      registered during post install.</para>
+
+      <para>Full details on both methods is provided in the <xref
+      linkend="update-alternatives_class" /> section of the reference
+      manual.</para>
+    </section>
+  </section>
+
+  <section id="recipes_volatiles" xreflabel="volatiles">
+    <title>Volatiles: How to handle the /var directory</title>
+
+    <para>The <emphasis role="bold">/var</emphasis> directory is for storing
+    volatile information, that is information which is constantly changing and
+    which in general may be easily recreated. In embedded applications it is
+    often desirable that such files are not stored on disk or flash for
+    various reasons including:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>The possibility of a reduced lifetime of the flash;</para>
+      </listitem>
+
+      <listitem>
+        <para>The limited amount of storage space available;</para>
+      </listitem>
+
+      <listitem>
+        <para>To ensure filesystem corruption cannot occur due to a sudden
+        power loss.</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>For these reasons many of the OpenEmbedded distributions use a tmpfs
+    based memory filesystem for <emphasis role="bold">/var</emphasis> instead
+    of using a disk or flash based filesystem. The consequence of this is that
+    all contents of the <emphasis role="bold">/var</emphasis> directory is
+    lost when the device is powered off or restarted. Therefore special
+    handling of <emphasis role="bold">/var</emphasis> is required in all
+    packages. Even if your distrubution does not use a tmpfs based <emphasis
+    role="bold">/var</emphasis> you need to assume it does when creating
+    packages to ensure the package can be used on those distributions that do
+    use a tmpfs based <emphasis role="bold">/var</emphasis>. This special
+    handling is provided via the <emphasis
+    role="bold">populate-volatiles.sh</emphasis> script.</para>
+
+    <note>
+      <para>If your package requires any files, directories or symlinks in
+      <emphasis role="bold">/var</emphasis> then it should be using the
+      populate-volatiles facilities.</para>
+    </note>
+
+    <section>
+      <title>Declaring volatiles</title>
+
+      <para>This section is to be completed.</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>how volatiles work</para>
+        </listitem>
+
+        <listitem>
+          <para>default volatiles</para>
+        </listitem>
+
+        <listitem>
+          <para>don't include any /var stuff in packages</para>
+        </listitem>
+
+        <listitem>
+          <para>even if your distro don't use /var in tmpfs, others do</para>
+        </listitem>
+
+        <listitem>
+          <para>updating the volatiles cache during install</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section>
+      <title>Logging and log files</title>
+
+      <para>As a consequence of the non-volatile and/or small capacity of the
+      <emphasis role="bold">/var</emphasis> file system some distributions
+      choose methods of logging other than writing to a file. The most typical
+      is the use of an in-memory circular log buffer which can be read using
+      the <emphasis role="bold">logread</emphasis> command.</para>
+
+      <para>To ensure that each distribution is able to implement logging in a
+      method that is suitable for its goals all packages should be configured
+      by default to log via syslog, and not log directly to a file, if
+      possible. If the distribution and/or end-user requires logging to a file
+      then they can configured syslog and/or your application to implement
+      this.</para>
+    </section>
+
+    <section>
+      <title>Summary</title>
+
+      <para>In summary the following are required when dealing with
+      <command>/var</command>:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Configure all logging to use syslog whenever possible. This
+          leaves the decision on where to log upto the individual
+          distributions.</para>
+        </listitem>
+
+        <listitem>
+          <para>Don't include any <command>/var</command> directories, file or
+          symlinks in packages. They would be lost on a reboot and so should
+          not be included in packages.</para>
+        </listitem>
+
+        <listitem>
+          <para>The only directories that you can assume exist are those
+          listed in the default volatiles file:
+          <command>packages/initscripts/initscripts-1.0/volatiles</command>.</para>
+        </listitem>
+
+        <listitem>
+          <para>For any other directories, files or links that are required in
+          <command>/var</command> you should install your own volatiles list
+          as part of the package.</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+  </section>
+
+  <section id="recipes_misc">
+    <title>Miscellaneous</title>
+
+    <para>This section is to be completed.</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>about optimisation</para>
+      </listitem>
+
+      <listitem>
+        <para>about download directories</para>
+      </listitem>
+
+      <listitem>
+        <para>about parallel builds</para>
+      </listitem>
+
+      <listitem>
+        <para>about determining endianess (aka net-snmp, openssl, hping etc
+        style)</para>
+      </listitem>
+
+      <listitem>
+        <para>about PACKAGES_DYNAMIC</para>
+      </listitem>
+
+      <listitem>
+        <para>about LEAD_SONAME</para>
+      </listitem>
+
+      <listitem>
+        <para>about "python () {" - looks like it is always run when a recipe
+        is parsed? see pam/libpam</para>
+      </listitem>
+
+      <listitem>
+        <para>about SRCDATE with svn/cvs?</para>
+      </listitem>
+
+      <listitem>
+        <para>about INHIBIT_DEFAULT_DEPS?</para>
+      </listitem>
+
+      <listitem>
+        <para>about COMPATIBLE_MACHINE and COMPATIBLE_HOST</para>
+      </listitem>
+
+      <listitem>
+        <para>about SUID binaries, and the need for postinst to fix them
+        up</para>
+      </listitem>
+
+      <listitem>
+        <para>about passwd and group (some comment in install scripts section
+        already).</para>
+      </listitem>
+    </itemizedlist>
+
+    <para></para>
+  </section>
+</chapter>
\ No newline at end of file
diff --git a/docs/usermanual/chapters/usage.xml b/docs/usermanual/chapters/usage.xml
new file mode 100644
index 0000000000..9fe20faf8c
--- /dev/null
+++ b/docs/usermanual/chapters/usage.xml
@@ -0,0 +1,1193 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="chapter_using_bitbake_and_oe">
+  <title>Using bitbake and OpenEmbedded</title>
+
+  <section id="usage_introduction" xreflabel="introduction">
+    <title>Introduction</title>
+
+    <para>If your reading this manual you probably already have some idea of
+    what OpenEmbedded is all about, which is taking a lot of software and
+    creating something that you can run on another device. This involves
+    downloading some source code, compiling it, creating packages (like .deb
+    or .rpm) and/or creating boot images that can written to flash on the
+    device. The difficulties of cross-compiling and the variety of devices
+    which can be supported lead to a lot more complexity in an OpenEmbedded
+    based distribution than you'd find in a typical desktop distribution
+    (which cross-compiling isn't needed).</para>
+
+    <para>A major part of OpenEmbedded deals with compiling source code for
+    various projects. For each project this generally requires the same basic
+    set of tasks:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Download the source code, and any supporting files (such as
+        initscripts);</para>
+      </listitem>
+
+      <listitem>
+        <para>Extract the source code and apply any patches that might be
+        wanted;</para>
+      </listitem>
+
+      <listitem>
+        <para>Configure the software if needed (such as is done by running the
+        configure script);</para>
+      </listitem>
+
+      <listitem>
+        <para>Compile everything;</para>
+      </listitem>
+
+      <listitem>
+        <para>Package up all the files into some package format, like .deb or
+        .rpm or .ipk, ready for installation.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>There's nothing particular unusual about this process when building
+    on the machine the package is to be installed on. What makes this
+    difficult is:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Cross-compiling: cross-compiling is difficult, and lots of
+        software has no support for cross-compiling - all packages included in
+        OE are cross-compiled;</para>
+      </listitem>
+
+      <listitem>
+        <para>Target and host are different: This means you can't compile up a
+        program and then run it - it's compiled to run on the target system,
+        not on the system compiling it. Lots of software tries to build and
+        run little helper and/or test applications and this won't work when
+        cross-compiling.</para>
+      </listitem>
+
+      <listitem>
+        <para>Tool chains (compiler, linker etc) are often difficult to
+        compile. Cross tool chains are even more difficult. Typically you'd go
+        out and download a tool chain made by someone else - but not when your
+        using OE. In OE the entire toolchain is built as part of the process.
+        This may make things take longer initially and may make it more
+        difficult to get started but makes it easier to apply patches and test
+        out changes to the tool chain.</para>
+      </listitem>
+    </orderedlist>
+
+    <para>Of course there's a lot more to OE then just compiling packages
+    though. Some of the features that OE supports includes:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Support for both glibc and uclibc;</para>
+      </listitem>
+
+      <listitem>
+        <para>Support for building for multiple target devices from the one
+        code base;</para>
+      </listitem>
+
+      <listitem>
+        <para>Automatically building anything that is required for the package
+        to compile and/or run (build and run time dependencies);</para>
+      </listitem>
+
+      <listitem>
+        <para>Creation of flash and disk images of any one of a number of
+        types (jffs2, ext2.gz, squashfs etc) for booting directly on the
+        target device;</para>
+      </listitem>
+
+      <listitem>
+        <para>Support for various packaging formats;</para>
+      </listitem>
+
+      <listitem>
+        <para>Automatic building all of the cross-compiling tools you'll
+        need;</para>
+      </listitem>
+
+      <listitem>
+        <para>Support for "native" packages that are built for the host
+        computer and not for the target and used to help during the build
+        process;</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>The rest of this chapter assumes you have mastered the Getting Start
+    guides to OpenEmbedded (see the OpenEmbedded web site for details), and
+    therefore have an appropriately configured setup and that you have managed
+    to actually build the cross-compilers for your target. This section talks
+    you through some of the background on what is happening with the aim of
+    helping you understand how to debug and develop within
+    OpenEmbedded.</para>
+
+    <para>You'll also not a lot of reference to variables that define specific
+    directories or change the behaviour of some part of the build process. You
+    should refer to <xref linkend="chapter_recipes" /> for full details on
+    these variables.</para>
+  </section>
+
+  <section id="usage_configuration" xreflabel="configuration">
+    <title>Configuration</title>
+
+    <para>Configuration covers basic items such as where the various files can
+    be found and where output should be placed to more specific items such as
+    which hardware is being targeted and what features you want to have
+    included in the final image. The main configuration areas in OE
+    are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>conf/machine</term>
+
+        <listitem>
+          <para>This directory contains machine configuration information. For
+          each physical device a configuration file is required in this
+          directory that describes various aspects of the device, such as
+          architecture of the device, hardware features of the device (does it
+          have usb? a keyboard? etc), the type of flash or disk images needed
+          for the device, the serial console settings (if any) etc. If you are
+          adding support for a new device you would need to create a machine
+          configuration in this directory for the device.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>conf/distro</term>
+
+        <listitem>
+          <para>This directory contains distribution related files. A
+          distribution decides how various activities are handled in the final
+          image, such as how networking configured, if usb devices will be
+          supported, what packaging system is used, which libc is used
+          etc.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>conf/bitbake.conf</term>
+
+        <listitem>
+          <para>This is the main bitbake configuration file. This file is not
+          to be edited but it is useful to look at it since it declares a
+          larger number of the predefined variables used by OE and controls a
+          lot of the base functionality provided by OE.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>conf/local.conf</term>
+
+        <listitem>
+          <para>This is the end-user specific configuration. This file needs
+          to be copied and edited and is used to specify the various working
+          directories, the machine to build for and the distribution to
+          use.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+  </section>
+
+  <section id="usage_workspace" xreflabel="workspace">
+    <title>Work space</title>
+
+    <para>Let's start out by taking a look at a typically working area. Note
+    that this may not be exactly what see - there are a lot of options that
+    can effect exactly how things are done, but it gives us a pretty good idea
+    of whats going on. What we are looking at here is the tmp directory (as
+    specified by TMPDIR in your local.conf):<screen>~%&gt; find tmp -maxdepth 2 -type d 
+tmp
+tmp/stamps
+tmp/cross
+tmp/cross/bin
+tmp/cross/libexec
+tmp/cross/lib  
+tmp/cross/share
+tmp/cross/sh4-linux
+tmp/cache
+tmp/cache/titan
+tmp/work
+tmp/work/busybox-1.2.1-r13
+tmp/work/libice-1_1.0.3-r0 
+tmp/work/arpwatch-2.1a15-r2
+...
+tmp/rootfs
+tmp/rootfs/bin
+tmp/rootfs/usr
+tmp/rootfs/media
+tmp/rootfs/dev  
+tmp/rootfs/var  
+tmp/rootfs/lib  
+tmp/rootfs/sbin 
+tmp/rootfs/mnt  
+tmp/rootfs/boot 
+tmp/rootfs/sys  
+tmp/rootfs/proc 
+tmp/rootfs/etc  
+tmp/rootfs/home 
+tmp/rootfs/tmp  
+tmp/staging     
+tmp/staging/man 
+tmp/staging/x86_64-linux
+tmp/staging/pkgdata
+tmp/staging/pkgmaps
+tmp/staging/var
+tmp/staging/sh4-linux
+tmp/staging/local
+tmp/staging/etc  
+tmp/deploy
+tmp/deploy/addons
+tmp/deploy/ipk   
+tmp/deploy/sources
+tmp/deploy/images</screen></para>
+
+    <para>The various top level directories under tmp include:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>stamps</term>
+
+        <listitem>
+          <para>Nothing of interest to users in here. These time stamps are
+          used by bitbake to keep track of what tasks it has completed and
+          what tasks it still has outstanding. This is how it knows that
+          certain actions have been completed and it doesn't need to do them
+          again.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>cross</term>
+
+        <listitem>
+          <para>Contains the cross-compiler toolchain. That is the gcc and
+          binutils that run on the host system but produce output for the
+          target system.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>cache</term>
+
+        <listitem>
+          <para>Nothing of interest to users in here. This contains the
+          bitbake parse cache and is used to avoid the need to parse all of
+          the recipes each time bitbake is run. This makes bitbake a lot
+          faster on the 2nd and subsequent runs.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>work</term>
+
+        <listitem>
+          <para>The work directory. This is the directory in which all
+          packages are built - this is where the source code is extract,
+          patches applied, software configure, compiled, installed and
+          package. This is where you'll spend most of you time looking when
+          working in OE.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>rootfs</term>
+
+        <listitem>
+          <para>The generated root filesystem image for your target device.
+          This is the contents of the root filesystem (NOTE: fakeroot means it
+          doesn't have the correct device special nodes and permissions to use
+          directly).</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>staging</term>
+
+        <listitem>
+          <para>Contains the staging area, which is used to stored natively
+          compiled tools and and libraries and headers for the target that are
+          required for building other software.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>deploy</term>
+
+        <listitem>
+          <para>Contains the final output from OE. This includes the
+          installation packages (typically .ipkg packages) and flash and/or
+          disk images. This is where you go to get the final product.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>When people refer to the <emphasis>"tmp directory"</emphasis> this
+    is the directory them are talking about.</para>
+
+    <para>To perform a complete rebuild from script you would usually rename
+    or delete tmp and then restart your build. I recommend keeping one old
+    version of tmp around to use for comparison if something goes wrong with
+    your new build. For example:<screen>%&gt; rm -fr tmp.OLD
+$&gt; mv tmp tmp.OLD
+%&gt; bitbake bootstrap-image</screen></para>
+
+    <section id="usage_workdir" xreflabel="work directory">
+      <title>work directory (tmp/work)</title>
+
+      <para>The work directory is where all source code is unpacked into,
+      where source is configured, compiled and packaged. In other words this
+      is where all the action happens. Each bitbake recipe will produce a
+      corresponding sub directory in the work directory. The sub directory
+      name will contain the recipe name, version and the release number (as
+      defined by the PR variable within the recipe).</para>
+
+      <para>Here's an example of a few of the subdirectories under the work
+      directory:<screen>~%&gt; find tmp/work -maxdepth 1 -type d | head -4
+tmp/work
+tmp/work/busybox-1.2.1-r13
+tmp/work/libice-1_1.0.3-r0
+tmp/work/arpwatch-2.1a15-r2</screen>You can see that the first three (of
+      several hundred) recipes here and they are for release 13 of busybox
+      1.2.1, release 0 or libice 1.1.0.3 and release 2 of arpwatch 2.1a15.
+      It's also possible that you may just have a sub directory for your
+      targets architecture and operating system in which case these
+      directories will be in that additional subdirectory, as shown
+      here:<screen>~%&gt; find tmp/work -maxdepth 2 -type d | head -4
+tmp/work
+tmp/work/sh4-linux
+tmp/work/sh4-linux/busybox-1.2.1-r13
+tmp/work/sh4-linux/libice-1_1.0.3-r0
+tmp/work/sh4-linux/arpwatch-2.1a15-r2</screen></para>
+
+      <para>The <emphasis role="bold">sh4-linux</emphasis> directory in the
+      above example is a combination of the target architecture (sh4) and
+      operating system (linux). This subdirectory has been added by the use of
+      one of OpenEmbedded's many features. In this case it's the
+      <emphasis>multimachine</emphasis> feature which is used to allow builds
+      for multiple targets within the one work directory and can be enabled on
+      a per distribution basis. This feature enables the sharing of native and
+      architecture neutral packages and building for multiple targets that
+      support the same architecture but require different linux kernels (for
+      example). We'll assume multimachine isn't being used for the rest of
+      this chapter, just remember to add the extra directory if your
+      distribution is using it.</para>
+
+      <para>Using lzo 1.08 as an example we'll examine the contents of the
+      working directory for a typical recipe:<screen>~%&gt; find tmp/work/lzo-1.08-r14 -maxdepth 1
+tmp/work/lzo-1.08-r14
+tmp/work/lzo-1.08-r14/temp
+tmp/work/lzo-1.08-r14/lzo-1.08
+tmp/work/lzo-1.08-r14/install
+tmp/work/lzo-1.08-r14/image</screen></para>
+
+      <para>The directory, <emphasis
+      role="bold">tmp/work/lzo-1.08-r14</emphasis>, is know as the
+      <emphasis>"working directory"</emphasis> for the recipe and is specified
+      via the <emphasis role="bold">WORKDIR</emphasis> variable in bitbake.
+      You'll sometimes see recipes refer directly to <emphasis
+      role="bold">WORKDIR</emphasis> and this is the directory they are
+      referencing. The <emphasis role="bold">1.08</emphasis> is the version of
+      lzo and <emphasis role="bold">r14</emphasis> is the release number, as
+      defined by the <emphasis role="bold">PR</emphasis> variable within the
+      recipe.</para>
+
+      <para>Under the working directory (<emphasis
+      role="bold">WORKDIR</emphasis>) there are four subdirectories:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>temp</term>
+
+          <listitem>
+            <para>The temp directories contains logs and in some cases scripts
+            that actually implement specific tasks (such as a script to
+            configure or compile the source).</para>
+
+            <para>You can look at the logs in this directory to get more
+            information into what happened (or didn't happen). This is usually
+            the first thing to look at when things are going wrong and these
+            usually need to be included when reporting bugs.</para>
+
+            <para>The scripts can be used to see what a particular task, such
+            as configure or compile, is trying to do.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>lzo-1.08</term>
+
+          <listitem>
+            <para>This is the unpacked source code directory, which was
+            created when the lzo source code was extracted in this directory.
+            The name and format of this directory is therefore dependent on
+            the actual source code packaging. Within recipes this directory is
+            referred to as <emphasis role="bold">S</emphasis> and is usually
+            expected to be named like this, that is
+            <emphasis>"&lt;name&gt;-&lt;version&gt;"</emphasis>. If the source
+            code extracts to somewhere else then that would need to be
+            declared in the recipe by explicitly setting the value of the
+            variable <emphasis role="bold">S</emphasis> to the appropriate
+            directory.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>image</term>
+
+          <listitem>
+            <para>The image directory (or destination directory) is where the
+            software needs to be installed into in order to be packaged. This
+            directory is referred to as <emphasis role="bold">D</emphasis> in
+            recipes. So instead of installing binaries into <emphasis
+            role="bold">/usr/bin</emphasis> and libraries into <emphasis
+            role="bold">/usr/lib</emphasis> for example you would need to
+            install into <emphasis role="bold">${D}/usr/bin</emphasis> and
+            <emphasis role="bold">${D}/usr/lib</emphasis> instead. When
+            installed on the target the ${D} will be not be included so
+            they'll end up in the correct place. You definitely don't wont
+            files on your host system being replaced by cross-compiled
+            binaries for your target!</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>install</term>
+
+          <listitem>
+            <para>The install directory is used to split the installed files
+            into separate packages. One subdirectory is created per package to
+            be generated and the files are moved from the image directory
+            (<emphasis role="bold">D</emphasis>) over to this directory, and
+            into the appropriate package subdirectory, as each packaging
+            instruction is processed. Typically there will be separate
+            documentation (<emphasis>-doc</emphasis>), debugging
+            (<emphasis>-dbg</emphasis>) and development
+            (<emphasis>-dev</emphasis>) packages automatically created. There
+            are variables such as <emphasis role="bold">FILES_</emphasis> and
+            <emphasis role="bold">PACKAGES</emphasis> used in recipes which
+            control the separation of various files into individual
+            packages.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>So lets show some examples of the useful information you now have
+      access to.</para>
+
+      <para>How about checking out what happened during the configuration of
+      lzo? Well that requires checking the log file for configure that is
+      generated in the temp directory:<screen>~%&gt; less tmp/work/lzo-1.08-r14/temp/log.do_configure.*
+...
+checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fschedule-insns bug... unknown
+checking whether ccache sh4-linux-gcc -ml -m4 suffers the -fstrength-reduce bug... unknown
+checking whether ccache sh4-linux-gcc -ml -m4 accepts -fstrict-aliasing... yes
+checking the alignment of the assembler... 0
+checking whether to build assembler versions... no
+configure: creating ./config.status
+config.status: creating Makefile
+config.status: creating examples/Makefile
+config.status: creating include/Makefile
+config.status: creating ltest/Makefile
+config.status: creating minilzo/Makefile
+config.status: creating src/Makefile
+config.status: creating tests/Makefile
+config.status: creating config.h
+config.status: executing depfiles commands</screen></para>
+
+      <para>Or perhaps you want to see how the files were distributed into
+      individual packages prior to packaging? The install directory is where
+      the files are split into separate packages and so that shows us which
+      files end up where:<screen>~%&gt; find tmp/work/lzo-1.08-r14/install                
+tmp/work/lzo-1.08-r14/install
+tmp/work/lzo-1.08-r14/install/lzo-doc
+tmp/work/lzo-1.08-r14/install/lzo-dbg
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug
+tmp/work/lzo-1.08-r14/install/lzo-dbg/usr/lib/.debug/liblzo.so.1.0.0
+tmp/work/lzo-1.08-r14/install/lzo-dev
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo2a.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1y.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1b.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1f.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoconf.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1x.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo16bit.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1a.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1z.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzoutil.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/include/lzo1c.h
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.a
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.so
+tmp/work/lzo-1.08-r14/install/lzo-dev/usr/lib/liblzo.la
+tmp/work/lzo-1.08-r14/install/lzo.shlibdeps
+tmp/work/lzo-1.08-r14/install/lzo-locale
+tmp/work/lzo-1.08-r14/install/lzo
+tmp/work/lzo-1.08-r14/install/lzo/usr
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1
+tmp/work/lzo-1.08-r14/install/lzo/usr/lib/liblzo.so.1.0.0</screen></para>
+    </section>
+  </section>
+
+  <section id="usage_tasks" xreflabel="tasks">
+    <title>Tasks</title>
+
+    <para>When you go about building and installing a software package there
+    are a number of tasks that you generally follow with most software
+    packages. You probably need to start out by downloading the source code,
+    then unpacking the source code. Maye you need to apply some patches for
+    some reason. Then you might run the configure script of the package,
+    perhaps passing it some options to configure it to your liking. The you
+    might run "make install" to install the software. If your actually going
+    to make some packages, such as .deb or .rpm, then you'd have additional
+    tasks you'd perform to make them.</para>
+
+    <para>You find that building things in OpenEmbedded works in a similar way
+    - there are a number of tasks that are executed in a predefined order for
+    each recipe. Any many of the tasks correspond to those listed above like
+    <emphasis>"download the source"</emphasis>. In fact you've probably
+    already seen some of the names of these tasks - bitbake displays them as
+    they are processed:<screen>~%&gt; bitbake lzo
+NOTE: Psyco JIT Compiler (http://psyco.sf.net) not available. Install it to increase performance.
+NOTE: Handling BitBake files: \ (4541/4541) [100 %]
+NOTE: Parsing finished. 4325 cached, 0 parsed, 216 skipped, 0 masked.
+NOTE: build 200705041709: started
+
+OE Build Configuration:
+BB_VERSION     = "1.8.2"
+OE_REVISION    = "&lt;unknown&gt;"
+TARGET_ARCH    = "sh4"
+TARGET_OS      = "linux"
+MACHINE        = "titan"
+DISTRO         = "erouter"
+DISTRO_VERSION = "0.1-20070504"
+TARGET_FPU     = ""
+
+NOTE: Resolving missing task queue dependencies
+NOTE: preferred version 2.5 of glibc not available (for item virtual/sh4-linux-libc-for-gcc)
+NOTE: Preparing Runqueue
+NOTE: Executing runqueue
+NOTE: Running task 208 of 226 (ID: 11, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_fetch</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_fetch</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_fetch</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 209 of 226 (ID: 2, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_unpack</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_unpack</emphasis>: started
+NOTE: Unpacking /home/lenehan/devel/oe/sources/lzo-1.08.tar.gz to /home/lenehan/devel/oe/build/titan-glibc-25/tmp/work/lzo-1.08-r14/
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_unpack</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 216 of 226 (ID: 3, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_patch</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_patch</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_patch</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 217 of 226 (ID: 4, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_configure</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_configure</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_configure</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 218 of 226 (ID: 12, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_qa_configure</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_qa_configure</emphasis>: started
+NOTE: Checking sanity of the config.log file
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_qa_configure</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 219 of 226 (ID: 0, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_compile</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_compile</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_compile</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 220 of 226 (ID: 1, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_install</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_install</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_install</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 221 of 226 (ID: 5, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_package</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_package</emphasis>: started
+NOTE: DO PACKAGE QA
+NOTE: Checking Package: lzo-dbg
+NOTE: Checking Package: lzo
+NOTE: Checking Package: lzo-doc
+NOTE: Checking Package: lzo-dev
+NOTE: Checking Package: lzo-locale
+NOTE: DONE with PACKAGE QA
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_package</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 222 of 226 (ID: 8, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, <emphasis
+          role="bold">do_package_write</emphasis>)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_package_write</emphasis>: started
+Packaged contents of lzo-dbg into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/liblzo-dbg_1.08-r14_sh4.ipk
+Packaged contents of lzo into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/liblzo1_1.08-r14_sh4.ipk
+NOTE: Not creating empty archive for lzo-doc-1.08-r14
+Packaged contents of lzo-dev into /home/lenehan/devel/oe/build/titan-glibc-25/tmp/deploy/ipk/sh4/liblzo-dev_1.08-r14_sh4.ipk
+NOTE: Not creating empty archive for lzo-locale-1.08-r14
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_package_write</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 223 of 226 (ID: 6, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, do_populate_staging)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_populate_staging</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_populate_staging</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 224 of 226 (ID: 9, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, do_qa_staging)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_qa_staging</emphasis>: started
+NOTE: QA checking staging
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_qa_staging</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 225 of 226 (ID: 7, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, do_distribute_sources)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_distribute_sources</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_distribute_sources</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Running task 226 of 226 (ID: 10, /home/lenehan/devel/oe/build/titan-glibc-25/packages/lzo/lzo_1.08.bb, do_build)
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_build</emphasis>: started
+NOTE: package lzo-1.08-r14: task <emphasis role="bold">do_build</emphasis>: completed
+NOTE: package lzo-1.08: completed
+NOTE: Tasks Summary: Attempted 226 tasks of which 213 didn't need to be rerun and 0 failed.
+NOTE: build 200705041709: completed</screen><note>
+        <para>The output may look different depending on the version of
+        bitbake being used, and some tasks are only run when specific options
+        are enabled in your distribution. The important point to note is that
+        the various tasks are being run and bitbake shows you each time it
+        starts and completes a task.</para>
+      </note></para>
+
+    <para>So there's a set of tasks here which are being run to generate the
+    final packages. And if you'll notice that every recipe runs through the
+    same set of tasks (ok I'll admit that it is possible that some additional
+    tasks could be run for some recipes, but we'll talk about that later). The
+    tasks that you'll need to be most familiar with are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>fetch</term>
+
+        <listitem>
+          <para>The <emphasis>fetch</emphasis> task is responsible for
+          fetching any source code that is required. This means things such as
+          downloading files and checking out from source control repositories
+          such as git or svn.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>unpack</term>
+
+        <listitem>
+          <para>The <emphasis>unpack</emphasis> task is responsible for
+          extracting files from archives, such as <emphasis
+          role="bold">.tar.gz</emphasis>, into the working area and copying
+          any additional files, such as init scripts, into the working
+          area.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>patch</term>
+
+        <listitem>
+          <para>The <emphasis>patch</emphasis> task is responsible for
+          applying any patches to the unpacked source code</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>configure</term>
+
+        <listitem>
+          <para>The <emphasis>configure</emphasis> task takes care of the
+          configuration of the package. Running a configure script
+          (<emphasis>"./configure &lt;options&gt;"</emphasis>) is probably the
+          form of configuration that is most recognised but it's not the only
+          configuration system that exists.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>compile</term>
+
+        <listitem>
+          <para>The <emphasis>compile</emphasis> task actually compiles the
+          software. This could be as simple as running <emphasis
+          role="bold">make</emphasis>.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>populate_staging (stage)</term>
+
+        <listitem>
+          <para>The <emphasis>populate_staging</emphasis> task (stage is an
+          alternate, easier to type name, that can be used to refer to this
+          task) is responsible for making available libraries and headers (if
+          any) that may be required by other packages to build. For example if
+          you compile zlib then it's headers and the library need to be made
+          available for other applications to include and link against.</para>
+
+          <note>
+            <para>This is different to the <emphasis>install</emphasis> task
+            in that this is responsible for making available libraries and
+            headers for use during build on the development host. Therefore
+            it's libraries which normal have to stage things while
+            applications normally don't need to. The
+            <emphasis>install</emphasis> task on the other hand is making
+            files available for packaging and ultimately installation on the
+            target.</para>
+          </note>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>install</term>
+
+        <listitem>
+          <para>The <emphasis>install</emphasis> task is responsible for
+          actually installing everything. Now this needs to install the
+          software into the destination directory, <emphasis
+          role="bold">D</emphasis>. This directory won't actually be a part of
+          the final package though. In other words if you install something
+          into <emphasis role="bold">${D}/bin</emphasis> then it will end up
+          in the <emphasis role="bold">/bin</emphasis> directory in the
+          package and therefore on the target.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>package</term>
+
+        <listitem>
+          <para>The <emphasis>package</emphasis> task takes the installed
+          files and splits them into separate directories under the <emphasis
+          role="bold">${WORKDIR}/install</emphasis> directory, one per
+          package. It moves the files for the destination directory, <emphasis
+          role="bold">${D}</emphasis>, that they were installed in into the
+          appropriate packages subdirectory. Usually there will be a main
+          package a separate documentation (-doc), development (-dev) and
+          debugging packages (-dbg) for example.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>package_write</term>
+
+        <listitem>
+          <para>The <emphasis>package_write</emphasis> task is responsible for
+          taking each packages subdirectory and creating any actual
+          installation package, such as .ipk, .deb or .rpm. Currently .ipk is
+          the only fully supported packing format although .deb packages are
+          being actively worked on. It should be reasonably easy for an
+          experienced OpenEmbedded developer to add support for any other
+          packaging formats they might required.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <note>
+      <para>You'll notice that the bitbake output had tasks prefixed with
+      <emphasis>do_</emphasis>, as in <emphasis>do_install</emphasis> vs
+      <emphasis>install</emphasis>. This is slightly confusing but any task
+      <emphasis>x</emphasis> is implemented via a function called
+      <emphasis>do_x</emphasis> in the class or recipe where it is defined.
+      See places refer to the tasks via their name only and some with the
+      <emphasis>do</emphasis> prefix.</para>
+    </note>
+
+    <para>You will almost certainly notice tasks beyond these ones - there are
+    various methods available to insert additional tasks into the tasks
+    sequence. As an example the <emphasis
+    role="bold">insane.bbclass</emphasis>, which performs various QA checks,
+    does these checks by inserting a new task called
+    <emphasis>qa_configure</emphasis> between the
+    <emphasis>configure</emphasis> and <emphasis>compile</emphasis> tasks and
+    another new task called <emphasis>qa_staging</emphasis> between
+    <emphasis>populate_staging</emphasis> and <emphasis>build</emphasis>
+    tasks. The former validates the result of the
+    <emphasis>configure</emphasis> task and the late the results of the
+    <emphasis>populate_staging</emphasis> task.</para>
+
+    <para>To determine the full list of tasks available for a specific recipe
+    you can run bitbake on the recipe and asking it for the full list of
+    available tasks:<screen>~%&gt; bitbake -b packages/perl/perl_5.8.8.bb -c listtasks
+NOTE: package perl-5.8.8: started
+NOTE: package perl-5.8.8-r11: task do_listtasks: started
+do_fetchall
+do_listtasks
+do_rebuild
+do_compile
+do_build
+do_populate_staging
+do_mrproper
+do_fetch
+do_configure
+do_clean
+do_package
+do_unpack
+do_install
+do_package_write
+do_distribute_sources
+do_showdata
+do_qa_configure
+do_qa_staging
+do_patch
+NOTE: package perl-5.8.8-r11: task do_listtasks: completed
+NOTE: package perl-5.8.8: completed
+~%&gt; </screen></para>
+
+    <para>If your being observant you'll note that
+    <emphasis>listtasks</emphasis> is in fact a task itself, and that the
+    <emphasis role="bold">-c</emphasis> option to bitbake allows you to
+    explicitly run specific tasks. We'll make use of this in the next section
+    when we discuss working with a recipe.</para>
+  </section>
+
+  <section id="usage_workwithsinglerecipe"
+           xreflabel="working with a single recipe">
+    <title>Working with a single recipe</title>
+
+    <para>During development you're likely to often find yourself working on a
+    single bitbake recipe - maybe trying to fix something or add a new version
+    or perhaps working on a totally new recipe. Now that you know all about
+    tasks you can use that knowledge to help speed up the development and
+    debugging process.</para>
+
+    <para>Bitbake can be instructed to deal directly with a single recipe file
+    by passing it via the <emphasis role="bold">-b</emphasis> parameter. This
+    option takes the recipe as a parameter and instructs bitbake to process
+    the named recipe only. Note that this ignores any dependencies that are in
+    the recipe, so these must have already been built previously.</para>
+
+    <para>Here's a typically example that cleans up the package (using the
+    <emphasis>clean</emphasis> task) and the rebuilds it with debugging output
+    from bitbake enabled:<screen>~%&gt; bitbake -b &lt;bb-file&gt; -c clean
+~%&gt; bitbake -b &lt;bb-file&gt; -D</screen></para>
+
+    <para>The options to bitbake that are most useful here are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>-b &lt;bb-file&gt;</term>
+
+        <listitem>
+          <para>The recipe to process;</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>-c &lt;action&gt;</term>
+
+        <listitem>
+          <para>The action to perform, typically the name of one of the tasks
+          supported by the recipe;</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>-D</term>
+
+        <listitem>
+          <para>Display debugging information, use two <emphasis
+          role="bold">-D</emphasis>'s for additional debugging;</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>-f</term>
+
+        <listitem>
+          <para>Force an operation. This is useful in getting bitbake to
+          perform some operation it normally wouldn't do. For example, if you
+          try and call the <emphasis>compile</emphasis> task twice in a row
+          then bitbake will not do anything on the second attempt since it has
+          already performed the task. By adding <emphasis
+          role="bold">-f</emphasis> it will force it to perform the action
+          regardless of if it thinks it's been done previously.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>The most common actions (used with -c) are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>fetch</term>
+
+        <listitem>
+          <para>Try to download all of the required source files, but don't do
+          anything else with them.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>unpack</term>
+
+        <listitem>
+          <para>Unpack the source file but don't apply the patches yet.
+          Sometimes you may want to look at the extracted, but not patched
+          source code and that's what just unpacking will give you (some
+          time's handy to get diffs generated against the original
+          source).</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>patch</term>
+
+        <listitem>
+          <para>Apply any patches.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>configure</term>
+
+        <listitem>
+          <para>Performs and configuration that is required for the
+          software.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>compile</term>
+
+        <listitem>
+          <para>Perform the actual compilation steps of the software.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>stage</term>
+
+        <listitem>
+          <para>If any files, such as header and libraries, will be required
+          by other packages then they need to be installed into the staging
+          area and that's what this task takes care of.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>install</term>
+
+        <listitem>
+          <para>Install the software in preparation for packaging.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>package</term>
+
+        <listitem>
+          <para>Package the software. Remember that this moves the files from
+          the installation directory, D, into the packing install area. So to
+          re-package you also need to re-install first.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>clean</term>
+
+        <listitem>
+          <para>Delete the entire directory for this version of the software.
+          Usually done to allow a test build with no chance of old files or
+          changes being left behind.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>Note that each of the actions that corresponds to task's will run
+    any preceding tasks that have not yet been performed. So starting with
+    compile will also perform the fetch, unpack, patch and configure
+    actions.</para>
+
+    <para>A typically development session might involve editing files in the
+    working directory and then recompiling until it all works:<screen>[<emphasis>... test ...</emphasis>]
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
+
+[<emphasis>... save a copy of main.c and make some changes ...</emphasis>]
+~%&gt; vi tmp/work/testapp-4.3-r0/main.c
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
+
+[<emphasis>... create a patch and add it to the recipe ...</emphasis>]
+~%&gt; vi packages/testapp/testapp_4.3.bb
+
+[<emphasis>... test from clean ...</emphasis>]
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c clean
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb
+
+[<emphasis>... NOTE: How to create the patch is not covered at this point ...</emphasis>]</screen></para>
+
+    <para>Here's another example showing how you might go about fixing up the
+    packaging in your recipe:<screen>~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c install -f
+~%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c stage -f
+~%&gt; find tmp/work/testapp_4.3/install
+...
+~%&gt; vi packages/testapp/testapp_4.3.bb</screen>At this stage you play with
+    the <emphasis role="bold">PACKAGE_</emphasis> and <emphasis
+    role="bold">FILES_</emphasis> variables and then repeat the above
+    sequence.</para>
+
+    <para>Note how we install and then stage. This is one of those things
+    where understanding the tasks helps a lot! Remember that stage moves the
+    files from where they were installed into the various subdirectories
+    (under <emphasis role="bold">${WORKDIR}/instal</emphasis>l) for each
+    package. So if you try and run a stage task without a prior install there
+    won't be any files there to stage! Note also that the stage tasks clears
+    all the subdirectories in <emphasis
+    role="bold">${WORKDIR}/install</emphasis> so you won't get any left over
+    files. But beware, the install task doesn't clear <emphasis
+    role="bold">${D}</emphasis> directory, so any left over files from a
+    previous packing attempt will be left behind (which is ok if all you care
+    about it staging).</para>
+  </section>
+
+  <section id="usage_interactive_bitbake" xreflabel="interactive bitbake">
+    <title>Interactive bitbake</title>
+
+    <para>To interactively test things use:<screen>~%&gt; bitbake -i</screen>this
+    will open the bitbake shell. From here there are a lot of commands
+    available (try help).</para>
+
+    <para>First thing you will want to do is parse all of the recipes (recent
+    bitbake version do this automatically when needed, so you don't need to
+    manually do this anymore):<screen>BB&gt;&gt; parse</screen>You can now
+    build a specific recipe:<screen>BB&gt;&gt; build net-snmp</screen>If it
+    fails you may want to clean the build before trying again:<screen>BB&gt;&gt; clean net-snmp</screen>If
+    you update the recipe by editing the .bb file (to fix some issues) then
+    you will want to clean the package, reparse the modified recipe, and the
+    build again:<screen>BB&gt;&gt; clean net-snmp
+BB&gt;&gt; reparse net-snmp
+BB&gt;&gt; build net-snmp</screen>Note that you can use wildcards in the
+    bitbake shell as well:<screen>BB&gt;&gt; build t*</screen></para>
+
+    <para></para>
+  </section>
+
+  <section id="usage_devshell" xreflabel="devshell">
+    <title>Devshell</title>
+
+    <para>One of the areas in which OpenEmbedded helps you out is by setting
+    various environment variables, such as <emphasis role="bold">CC</emphasis>
+    and <emphasis role="bold">PATH</emphasis> etc, to values suitable for
+    cross-compiling. If you wish to manually run configure scripts and compile
+    file during development it would be nice to have all those values set for
+    you. This is what devshell does - it provides you with an interactive
+    shell with all the appropriate variables set for cross-compiling.</para>
+
+    <section>
+      <title>devshell via inherit</title>
+
+      <para>This is the newer method of obtaining a devshell and is the
+      recommended way for most users now. The newer method requires that the
+      devshell class be added to you configuration by inheriting it. This is
+      usually done in your <emphasis role="bold">local.conf</emphasis> or your
+      distributions conf file:<screen><emphasis role="bold">INHERIT +=</emphasis> "src_distribute_local insane multimachine <emphasis
+            role="bold">devshell</emphasis>"</screen></para>
+
+      <para>With the inclusion of this class you'll find that devshell is
+      added as a new task that you can use on recipes:<screen>~%&gt; bitbake -b packages/lzo/lzo_1.08.bb -c listtasks
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task do_listtasks: started
+<emphasis role="bold">do_devshell</emphasis>
+do_fetchall
+do_listtasks
+do_rebuild
+do_compile
+do_build
+do_mrproper
+do_fetch
+do_configure
+do_clean
+do_populate_staging
+do_package
+do_unpack
+do_install
+do_package_write
+do_distribute_sources
+do_showdata
+do_qa_staging
+do_qa_configure
+do_patch
+NOTE: package lzo-1.08-r14: task do_listtasks: completed
+NOTE: package lzo-1.08: completed</screen></para>
+
+      <para>To bring up the devshell you call bitbake on a recipe and ask it
+      for the devshell task:<screen>~%&gt; ./bb -b packages/lzo/lzo_1.08.bb -c devshell
+NOTE: package lzo-1.08: started
+NOTE: package lzo-1.08-r14: task do_devshell: started
+[<emphasis>... devshell will appear here ...</emphasis>]
+NOTE: package lzo-1.08-r14: task do_devshell: completed
+NOTE: package lzo-1.08: completed</screen></para>
+
+      <para>How the devshell appears depends on the settings of the <emphasis
+      role="bold">TERMCMD</emphasis> variable - you can see the default
+      settings and other possible values in <emphasis
+      role="bold">conf/bitbake.conf</emphasis>. Feel free to try settings this
+      to something else in your local.conf. Usually you will see a new
+      terminal window open which is the devshell window.</para>
+
+      <para>The devshell task is inserted after the patch task, so if you have
+      not already run bitbake on the recipe it will download the source and
+      apply any patches prior to opening the shell.</para>
+
+      <note>
+        <para>This method of obtaining a devshell works if you using <emphasis
+        role="bold">bash</emphasis> as your shell, it does not work if you are
+        using <emphasis role="bold">zsh</emphasis> as your shell. Other shells
+        may or may not work.</para>
+      </note>
+    </section>
+
+    <section>
+      <title>devshell addon</title>
+
+      <para>The devshell addon was the original method that was used to create
+      a devshell.</para>
+
+      <para>It requires no changes to your configuration, instead you simply
+      build the devshell recipe:<screen>bitabike devshell</screen></para>
+
+      <para>and then manually startup the shell. Once in the shell you'll
+      usually want to change into the working directory for the recipe you are
+      working on:<screen>~%&gt; ./tmp/deploy/addons/sh4-linux-erouter-titan-devshell
+bash: alias: `./configure': invalid alias name
+[OE::sh4-linux-erouter-titan]:~$ cd tmp/work/lzo-1.08-r14/lzo-1.08
+[OE::sh4-linux-erouter-titan]:~tmp/work/lzo-1.08-r14/lzo-1.08$</screen><note>
+          <para>The name of the devshell addon depends on the target
+          architecture, operating system and machine name. So you name will be
+          different - just check for the appropriate name ending in
+          -devshell.</para>
+        </note></para>
+    </section>
+
+    <section>
+      <title>Working in the devshell</title>
+
+      <para>[To be done]</para>
+    </section>
+  </section>
+
+  <section id="usage_patches" xreflabel="patching">
+    <title>Patching and patch management</title>
+
+    <para>[To be done]</para>
+  </section>
+</chapter>
\ No newline at end of file