usermanual: Split each of the original chapters out of usermanual.xml into a

seperate file per chapter in the chapters subdirectory. In preparation for
cleaning up some of the overlap between chapters and to make life a bit
easier for editing and merging.

1 files changed, 15 insertions, 775 deletions

diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml
index 06ccf59573..9555a65220 100644
--- a/usermanual/usermanual.xml
+++ b/usermanual/usermanual.xml
@@ -5,6 +5,12 @@
 -->
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!ENTITY chapter-introduction SYSTEM "chapters/introduction.xml">
+<!ENTITY chapter-metadata SYSTEM "chapters/metadata.xml">
+<!ENTITY chapter-gettingoe SYSTEM "chapters/getting_oe.xml">
+<!ENTITY chapter-features SYSTEM "chapters/features.xml">
+<!ENTITY chapter-commonusecases SYSTEM "chapters/common_use_cases.xml">
+<!ENTITY chapter-comparing SYSTEM "chapters/comparing.xml">
 <!ENTITY chapter-usage SYSTEM "chapters/usage.xml">
 <!ENTITY chapter-recipes SYSTEM "chapters/recipes.xml">
 <!ENTITY class-autotools SYSTEM "reference/class_autotools.xml">
@@ -47,7 +53,6 @@
       <holder>Marcin Juszkiewicz</holder>
 
       <holder>Rolf Leggewie</holder>
-
     </copyright>
 
     <legalnotice>
@@ -59,790 +64,25 @@
     </legalnotice>
   </bookinfo>
 
-  <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, Angström, Familiar and SlugOS.</para>
-
-      <para>The primary use-case of <application>OpenEmbedded</application>
-      are: <itemizedlist>
-          <listitem>
-            <para>Handle cross-compilation.</para>
-          </listitem>
-
-          <listitem>
-            <para>Handle inter-package dependencies</para>
-          </listitem>
-
-          <listitem>
-            <para>Must be able to emit packages (tar, rpm, ipk)</para>
-          </listitem>
-
-          <listitem>
-            <para>Must be able to create images and feeds from packages</para>
-          </listitem>
-
-          <listitem>
-            <para>Must be highly configurable to support many machines,
-            distribution and architectures.</para>
-          </listitem>
-
-          <listitem>
-            <para>Writing of metadata must be easy and reusable</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para>Together with <ulink
-      url="http://bitbake.berlios.de/manual"><application>BitBake</application></ulink>,
-      OpenEmbedded satisfies all these and many more. Flexibility and power
-      have always been the priorities.</para>
-    </section>
-
-    <section 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>
+  <!-- Main chapters-->
 
-  <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>
+  &chapter-introduction;
 
-  <chapter id="chapter_getting_oe">
-    <title>Getting OpenEmbedded</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 (30th of June 2007)
-      <application>BitBake</application> 1.8.2 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>This section is a stub, help us by expanding it</para>
-    </section>
-  </chapter>
+  &chapter-metadata;
 
-  <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>
+  &chapter-gettingoe;
 
-  <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</para>
-    </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>
-      </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>
+  &chapter-features;
 
-  <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>
+  &chapter-commonusecases;
 
-  <!-- Bitbake usage chapter -->
+  &chapter-comparing;
 
   &chapter-usage;
 
-  <!-- Bitbake recipies chapter -->
-
   &chapter-recipes;
 
-  <!-- Reference manual. Sorted alphabetically. All entries are pulled in from external files -->
+  <!-- Reference manual. Sorted alphabetically. -->
 
   <chapter id="chapter_reference">
     <title>Reference</title>
@@ -877,4 +117,4 @@ NOTE: Couldn't find shared library provider for libm.so.6
 
     &class-update-rcd;
   </chapter>
-</book>
+</book>
\ No newline at end of file