usermanual: Clean up the using bitbake/oe chapter to the point where it's

almost useable. Still not included in user manual yet, probably needs a bit
more work before that hppens.

1 files changed, 803 insertions, 100 deletions

diff --git a/usermanual/chapters/usage.xml b/usermanual/chapters/usage.xml
index 2e1f887d38..f2031b3346 100644
--- a/usermanual/chapters/usage.xml
+++ b/usermanual/chapters/usage.xml
@@ -1,138 +1,841 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<chapter>
-  <title>Usage</title>
+<chapter id="chapter_using_bitbake_and_oe">
+  <title>Using bitbake and OE</title>
 
   <section id="usage_introduction" xreflabel="introduction">
     <title>Introduction</title>
 
-    <para>Using bitbake</para>
+    <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. Its all about
+    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 complexities of cross-compiling and the variety of devices to
+    be supported lead to a lot more complexity in on OpenEmbedded based
+    distribution than you'd find in a typical desktop distribution (which
+    doesn't get cross-compiled).</para>
+
+    <para>A major part of OpenEmbedded deals with compiling source code for
+    various projects. For each project OpenEmbedded has to:</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>As mentioned this is made for more complex than normal due
+    to:</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>Due to cross-compiling the executable's that are created cannot
+        normally be run, so any software that tries to run things as part of
+        it's build process need to have changes made to handle this some other
+        way</para>
+      </listitem>
+    </orderedlist>
+
+    <para>Of course there's a lot more to OE then just compiling packages
+    though. Just some of the things that OE can handle:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>Support for glibc and uclibc;</para>
+      </listitem>
+
+      <listitem>
+        <para>Support for building for multiple targets;</para>
+      </listitem>
+
+      <listitem>
+        <para>Dependencies - automatically building anything that is required
+        for the package your really want;</para>
+      </listitem>
+
+      <listitem>
+        <para>Creation of flash and disk images for booting directly on the
+        target device;</para>
+      </listitem>
+
+      <listitem>
+        <para>Support for various packaging formats;</para>
+      </listitem>
+
+      <listitem>
+        <para>Automatically creating 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;</para>
+      </listitem>
+    </itemizedlist>
+
+    <para>This chapter assumes you have master the Getting Start guides to
+    OpenEmbedded (see the OpenEmbedded web site for details), and therefore
+    have an appropriately configured setup and have managed to 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>
   </section>
 
   <section id="usage_workspace" xreflabel="workspace">
     <title>Work space</title>
 
-    <para>The work directory (the working area) is where all of the source is
-    extracted, patched and built: ~/devel/oe/build/titan-glibc-25%&gt; ls
-    tmp/work/strace-4.5.14-r1 image/ install/ strace-4.5.14/ temp/ The
-    subdirectories in the working area are: image When the install is being
-    run for the package it's files are installed into this directory. They are
-    moved out when being placed into individual packages and so only the
-    directores it created should remain. Any other that remain have not been
-    packaged. </para>
-
-    <para>install The install directory contains a subdirectory per package to
-    be created with the appropriate files located under each package (moved
-    from the image directory) and some files related to processing of the
-    packages. </para>
-
-    <para>strace-4.5.14 This is the directory created by the extracted source
-    code. (Refered to by the S variable in the recipes). </para>
-
-    <para>temp Scripts to perform the various stages (configure, compile, etc)
-    and the logs containing the output of those scripts. </para>
-  </section>
+    <para>Let's start out by taking a look at a typically working area OE.
+    Note that this isn't exactly what you'll 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>
 
-  <section id="usage_tempdir" xreflabel="tempdir">
-    <title>Temp dir</title>
+    <para>The various top level directories under tmp include:</para>
 
-    <para>The temp directory contains the scripts to perform various actions
-    and the log files generated by those actions:</para>
-  </section>
+    <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>
 
-  <section id="usage_installdir" xreflabel="installdir">
-    <title>Install dir</title>
+        <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>
 
-    <para>The install directory contains one subdirectory per package to be
-    generated, each containing the files to be included in that package, and
-    some package control files:</para>
+      <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></para>
+
+    <section id="usage_workdir" xreflabel="work directory">
+      <title>work directory</title>
+
+      <para>The working directory is where all files are extracted and
+      everything is configured, compiled and packaged. In other words this is
+      where all the action happens. Each bitbake recipe will produce a
+      corresponding directory in the working area, with the name containing
+      the recipe name, version and the release number (as defined by the PR
+      variable in the recipe).</para>
+
+      <para>In the following example we show some of the directories that are
+      created and in this case they are created directly in 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>Depending on your distribution settings
+      you may have an additional subdirectory present:<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>where are additional directory corresponding to the target
+      architecture and OS has been inserted. This is added by the use of the
+      <emphasis>multimachine</emphasis> feature which is used to allow builds
+      for multiple targets within the one work directory (which in turn
+      enables the sharing of native functionality and a reduction in the time
+      taken to build for multiple machines). We'll assume multimachine is not
+      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 working directory
+      and see what it contain 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 working
+      directory for the recipe is held in the <emphasis
+      role="bold">WORKDIR</emphasis> variable in bitbake. You'll sometimes see
+      recipes refer directly to <emphasis role="bold">WORKDIR</emphasis> and
+      if so this is the directory they are referring to. The <emphasis
+      role="bold">1.08</emphasis> is the version of lzo and the <emphasis
+      role="bold">r14</emphasis> is the release number, as defined by the
+      <emphasis role="bold">PR</emphasis> variable in the recipe.</para>
+
+      <para>Under <emphasis role="bold">WORKDIR</emphasis> there are four
+      directories:</para>
+
+      <variablelist>
+        <varlistentry>
+          <term>temp</term>
+
+          <listitem>
+            <para>The temp directories contains logs and in some cases scripts
+            that actually implement specific tasks.</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 you would need to manually specify
+            the value of <emphasis role="bold">S</emphasis> in your
+            recipe.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>install</term>
+
+          <listitem>
+            <para>The installation 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 into
+            <emphasis role="bold">/usr/bin</emphasis> and <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> in order for the
+            packaging system to work.</para>
+          </listitem>
+        </varlistentry>
+
+        <varlistentry>
+          <term>image</term>
+
+          <listitem>
+            <para>The image directory is used to split the installed files
+            into separate packages. One subdirectory is created per package to
+            be generated and the files and moved from the install directory
+            (<emphasis role="bold">D</emphasis>) over to this directory 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.</para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+
+      <para>The various variables that can be used in a recipe are described
+      in detail in the recipes chapter of this manual.</para>
+
+      <para>What can you do with this information? How about checking out what
+      happened during the configuration of lzo:<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 which files were included in each of
+      the generated packages:<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_deploydir" xreflabel="deploydir">
-    <title>Deploy dir</title>
+  <section id="usage_tasks" xreflabel="tasks">
+    <title>Tasks</title>
+
+    <para>When you build a software package you generally perform a number of
+    steps or tasks. These would include things like "download the source
+    code", "unpack the source code", "run the configure script", "build the
+    software", "install the software" etc. OpenEmbedded builds software in a
+    similar way - by performing a set of tasks. Understanding these tasks is
+    critical to understanding how things get done in OpenEmbedded.</para>
+
+    <para></para>
+
+    <para>The following is a list of the most commonly seen tasks:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>fetch</term>
+
+        <listitem>
+          <para>The fetch task is responsible for fetching any source code
+          that is required. This means things such as downloading files and
+          checking out from svn or git repositories for example.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>unpack</term>
+
+        <listitem>
+          <para>The unpack task is responsible for extracting files from
+          archives, such as .tar.gz, into the working area and copying any
+          additional files into the working area.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>patch</term>
+
+        <listitem>
+          <para>The patch task is responsible for applying any patches to the
+          unpacked source code</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>configure</term>
+
+        <listitem>
+          <para>The configure task takes care of the configuration of the
+          package. Running a configure script ("./configure &lt;options&gt;")
+          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>
 
-    <para>The deploy directory is where the final packaged files (typically
-    .ipk files) and and flash images or nfs images etc end up. For our strace
-    example we end up with just two .ipk files, one for the application and
-    one for the documentation.</para>
+        <listitem>
+          <para>The compile task actually compiles the software. This could be
+          as simple as running "make".</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>populate_staging (stage)</term>
+
+        <listitem>
+          <para>The populate_staging 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>
+
+          <para>NOTE that this is different to the install (and packaging)
+          related tasks in that this is making available things for use during
+          build on the development host while the installed files are being
+          made available for use on the target device.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term></term>
+
+        <listitem>
+          <para></para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>install</term>
+
+        <listitem>
+          <para>The install task is responsible for actually installing the
+          software. Now this needs to install the software into the
+          destination directory (${D}) but once package the destination
+          directory will be removed from all the files. In other words if you
+          install something into ${D}/bin then it will end up in the /bin
+          directory in the package and therefore on the target.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>package</term>
+
+        <listitem>
+          <para>The package task takes the installed files and splits them
+          into separate directories under the ${WORKDIR}/install directory,
+          one per package. It moves the files for the destination directory,
+          ${D}, 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 package_write task is responsible for taking each packages
+          subdirectory and creating any actual installation package, such as
+          .ipk, .deb or .rpm.</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term></term>
+
+        <listitem>
+          <para></para>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para></para>
+
+    <para>Note that these are not the only possible set of tasks. There are
+    various methods available to insert additional tasks in between existing
+    tasks if needed. As an example the insane.bbclass, which performs various
+    QA checks, does these checks by inserting a new task, qa_configure,
+    between the configure and compile tasks to check on the result of
+    configuration and another new tasks, qa_staging, between populate_staging
+    and build to validate the files that have been staged.</para>
+
+    <para></para>
+
+    <para>You can see a list of all the tasks available for a specific recipe
+    by explicitly calling bitbake on the recipe and asking it for a list of
+    tasks:</para>
+
+    <para><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>Note that <emphasis>do_</emphasis> prefixed to the tasks - the
+    <emphasis>do_&lt;task&gt;</emphasis> is the name of the method that
+    implements the required functionality for
+    <emphasis>&lt;task&gt;</emphasis>, so the above is actually listing the
+    methods that implement the available tasks. It's sometimes a but confusing
+    but just remember that the do_ is the method name (with a definition
+    usually found in the of the .bbclass files in the classes
+    directory.)</para>
   </section>
 
-  <section id="usage_singlepkg" xreflabel="singlepkg">
+  <section id="usage_workwithsinglepackage"
+           xreflabel="working with a single package">
     <title>Working with a single package</title>
 
     <para>When working on fixing and/or creating a single recipe you can ask
-    bitbake to deal with a single .bb file only. The -b &lt;bb-file&gt; option
-    asks bitbake to only process the named file. So to clean and rebuild a
-    single package you can do: %&gt; bitbake -b &lt;bb-file&gt; -c clean %&gt;
-    bitbake -D -b &lt;bb-file&gt; The various options that are useful here
-    are: -b &lt;bb-file&gt; Specify which recipe to process -c &lt;action&gt;
-    Specify which action to perform (see below) -D Enable debugging output.
-    This gives you a lot more output during the operation. -f Force on
-    operation. This is useful in getting bitbake to perform some operation it
-    normally wouldn't do. For example, if you try and compile twice ina row
-    then bitbake will not do anything on the second attempt since it has
-    already gone through the compile stage. By adding -f forces it the action
-    to take place. The most common actions (used with -c) are: fetch Will
-    download any files that need to be fetched. unpack Extracts the source
-    code into the working directory, but does not apply any patches. patch
-    Applies patches into the source in the working directory. configure Runs
-    the configuration task for the recipe. compile Actually compile
-    everything. stage Copy required files into the staging area. install
-    Install files that are going to be package. package Package files.
-    Normally this means creating the .ipkg files. clean Clean the package -
-    this deletes the entire working directory for the package, so on the next
-    build the source will be extracted, patches applied etc. Note that each
-    action will run any preceeding actions that have not yet been performed.
-    So starting with compile will also peform the fetch, unpack, patch and
-    configure actions. A typically development session would involve editing
-    files in the working directory and running: %&gt; bitbake -f
-    packages/testapp/testapp_4.3.bb -c compile (Try and compile) look at logs,
-    edit some files in working area %&gt; bitbake -f
-    packages/testapp/testapp_4.3.bb -c compile -f (Force re-compile) and then
-    once appropriate patches have been made and the recipe updated: %&gt;
-    bitbake -f packages/testapp/testapp_4.3.bb -c clean (Remove working files)
-    %&gt; bitbake -f packages/testapp/testapp_4.3.bb (Try everything from
-    scratch) A full list of available tasks for a specific package can be
-    obtained with the listtasks task: %&gt; bitbake -f
-    packages/testapp/testapp_4.3.bb -c listtasks </para>
+    bitbake to deal directly with a single .bb file only. The <emphasis>-b
+    &lt;bb-file&gt;</emphasis> option asks bitbake to only process the named
+    file. Note that this ignores any dependencies that are in the recipe, so
+    these must have already been handled.</para>
+
+    <para>A typically example of this is to clean and then rebuild a package
+    with some debugging information:</para>
+
+    <para><screen>%&gt; bitbake -b &lt;bb-file&gt; -c clean
+%&gt; bitbake -b &lt;bb-file&gt; -D</screen></para>
+
+    <para>The various options to bitbake that are useful here are:</para>
+
+    <variablelist>
+      <varlistentry>
+        <term>-b &lt;bb-file&gt;</term>
+
+        <listitem>
+          <para>Specify which recipe to process;</para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term>-c &lt;action&gt;</term>
+
+        <listitem>
+          <para>Specify which 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 compile twice in a row then bitbake will not do anything on
+          the second attempt since it has already performed the compile 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 recompiling until it all works:<screen>[... test ...]
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D
+
+[... save a copy of main.c and make some changes ...]
+%&gt; vi tmp/work/testapp-4.3-r0/main.c
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c compile -D -f
+
+[... create a patch and add it to the recipe ...]
+%&gt; vi packages/testapp/testapp_4.3.bb
+
+[... test from clean ...]
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb -c clean
+%&gt; bitbake -b packages/testapp/testapp_4.3.bb
+
+[... NOTE: How to create the patch is not covered at this point ...]</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 (${D}) 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_bbinteractive" xreflabel="bbinteractive">
+  <section id="usage_interactive_bitbake" xreflabel="interactive bitbake">
     <title>Interactive bitbake</title>
 
-    <para>To interactively test things use: %&gt; bitbake -i this will open
-    the bitbake shell. From here there are a lot of commands available (try
-    help). First thing you will want to do is parse all of the recipes.
-    BB&gt;&gt; parse You can now build a specific recipe: BB&gt;&gt; build
-    net-snmp If it fails you may want to clean the build before trying again:
-    BB&gt;&gt; clean net-snmp 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: BB&gt;&gt; clean net-snmp BB&gt;&gt;
-    reparse net-snmp BB&gt;&gt; build net-snmp Note that you can use wildcards
-    in the bitbake shell as well: BB&gt;&gt; build t* The interacive mode was
-    most useful with bitbake versions prior to 1.4 where the entire set of
-    recipes had to be reparsed each time bitbake was run. Since bitbake 1.4
-    the parseing is cached between runs and so it is no where near as painful
-    to run individual bitbake commands and therefore the interactive mode is
-    no longer as important as it once was. [edit] </para>
+    <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></para>
+    <para>[To be done]</para>
   </section>
 
-  <section id="usage_workflow" xreflabel="workflow">
-    <title>Workflow</title>
+  <section id="usage_patches" xreflabel="patching">
+    <title>Patching and patch management</title>
 
-    <para>fetch Will download any files that need to be fetched. unpack
-    Extracts the source code into the working directory, but does not apply
-    any patches. patch Applies patches into the source in the working
-    directory. configure Runs the configuration task for the recipe. compile
-    Actually compile everything. stage Copy required files into the staging
-    area. install Install files that are going to be package. package Package
-    files. Normally this means creating the .ipkg files. </para>
+    <para>[To be done]</para>
   </section>
 </chapter>
\ No newline at end of file