initial commit of Enea Linux 3.1

Migrated from the internal git server on the dora-enea branch

Signed-off-by: Adrian Dudau <adrian.dudau@enea.com>

228 files changed, 51074 insertions, 0 deletions

diff --git a/documentation/Makefile b/documentation/Makefile
new file mode 100644
index 0000000000..5f2f865f39
--- /dev/null
+++ b/documentation/Makefile
@@ -0,0 +1,395 @@
+# This is a single Makefile to handle all generated Yocto Project documents.
+# The Makefile needs to live in the documents directory and all figures used
+# in any manuals must be .PNG files and live in the individual book's figures
+# directory as well as in the figures directory for the mega-manual.
+# Note that the figures for the Yocto Project Development Manual
+# differ depending on the BRANCH being built.
+#
+# The Makefile has these targets:
+#
+#    pdf:      generates a PDF version of a manual.  Not valid for the Quick Start
+#              or the mega-manual (single, large HTML file comprised of all
+#              Yocto Project manuals).
+#    html:     generates an HTML version of a manual.
+#    eclipse:  generates an HTML version of a manual that can be used as
+#              eclipse help (including necessary metadata files).
+#    tarball:  creates a tarball for the doc files.
+#    validate: validates
+#    publish:  pushes generated files to the Yocto Project website
+#    clean:    removes files
+#
+# The Makefile generates an HTML and PDF version of every document except the
+# Yocto Project Quick Start and the single, HTML mega-manual, which is comprised
+# of all the individual Yocto Project manuals.  These two manuals are in HTML
+# form only.  The variable DOC indicates the folder name for a given manual. The
+# variable VER represents the distro version of the Yocto Release for which the
+# manuals are being generated.  The variable BRANCH is used to indicate the
+# branch (edison or denzil) and is used only when DOC=dev-manual or
+# DOC=mega-manual.  If you do not specify a BRANCH, the default branch used
+# will be for the latest Yocto Project release.  If you build for either
+# edison or denzil, you must use BRANCH. You do not need to use BRANCH for
+# any release beyond denzil.
+#
+# To build a manual, you must invoke Makefile with the DOC argument.  If you
+# are going to publish the manual, then you must invoke Makefile with both the
+# DOC and the VER argument.  Furthermore, if you are building or publishing
+# the edison or denzil versions of the Yocto Poject Development Manual or
+# the mega-manual, you must also use the BRANCH argument.
+#
+# Examples:
+#
+#     make DOC=bsp-guide
+#     make DOC=yocto-project-qs
+#     make pdf DOC=ref-manual
+#     make DOC=dev-manual BRANCH=edison
+#     make DOC=mega-manual BRANCH=denzil
+#
+# The first example generates the HTML and PDF versions of the BSP Guide.
+# The second example generates the HTML version only of the Quick Start.  Note that
+# the Quick Start only has an HTML version available.  The third example generates
+# both the PDF and HTML versions of the Yocto Project Reference Manual. The
+# fourth example generates both the PDF and HTML 'edison' versions of the YP
+# Development Manual.  The last exmample generates the HTML version of the
+# mega-manual and uses the 'denzil' branch when choosing figures for the
+# tarball of figures.  Any example that does not use the BRANCH argument
+# builds the current version of the manual set.
+#
+# Use the publish target to push the generated manuals to the Yocto Project
+# website.  All files needed for the manual's HTML form are pushed as well as the
+# PDF version (if applicable).
+# Examples:
+#
+#    make publish DOC=bsp-guide VER=1.3
+#    make publish DOC=adt-manual VER=1.3
+#    make publish DOC=dev-manual VER=1.1.1 BRANCH=edison
+#    make publish DOC=dev-manual VER=1.2 BRANCH=denzil
+#
+# The first example publishes the 1.3 version of both the PDF and HTML versions of
+# the BSP Guide.  The second example publishes the 1.3 version of both the PDF and
+# HTML versions of the ADT Manual. The third example publishes the PDF and HTML
+# 'edison' versions of the YP Development Manual.  The fourth example publishes
+# the PDF and HTML 'denzil' versions of the YP Development Manual.
+#
+
+ifeq ($(DOC),bsp-guide)
+XSLTOPTS = --xinclude
+ALLPREQ = html pdf eclipse tarball
+TARFILES = bsp-style.css bsp-guide.html bsp-guide.pdf figures/bsp-title.png \
+           eclipse
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+
+endif
+
+ifeq ($(DOC),dev-manual)
+XSLTOPTS = --xinclude
+ALLPREQ = html pdf eclipse tarball
+#
+# Note that the tarfile might produce the "Cannot stat: No such file or directory" error
+# message for .PNG files that are not present when building a particular branch.  The
+# list of files is all-inclusive for all branches.  Note, if you don't provide a BRANCH
+# option, it defaults to the latest stuff.  This would be appropriate for "master" branch.
+#
+
+        ifeq ($(BRANCH),edison)
+TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
+           figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
+           figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
+           figures/kernel-example-repos-edison.png \
+           figures/kernel-overview-1.png figures/kernel-overview-2.png \
+           figures/kernel-overview-3-edison.png \
+           figures/source-repos.png figures/yp-download.png \
+           figures/wip.png
+        else ifeq ($(BRANCH),denzil)
+TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
+           figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
+           figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
+           figures/kernel-example-repos-denzil.png \
+           figures/kernel-overview-1.png figures/kernel-overview-2.png \
+           figures/kernel-overview-3-denzil.png \
+           figures/source-repos.png figures/yp-download.png \
+           figures/wip.png
+        else
+TARFILES = dev-style.css dev-manual.html dev-manual.pdf \
+           figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
+           figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
+           figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
+           figures/source-repos.png figures/yp-download.png \
+           eclipse
+        endif
+
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+
+endif
+
+ifeq ($(DOC),yocto-project-qs)
+XSLTOPTS = --xinclude
+ALLPREQ = html eclipse tarball
+TARFILES = yocto-project-qs.html qs-style.css figures/yocto-environment.png \
+           figures/building-an-image.png figures/using-a-pre-built-image.png \
+           figures/yocto-project-transp.png \
+           eclipse
+MANUALS = $(DOC)/$(DOC).html $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+endif
+
+ifeq ($(DOC),mega-manual)
+XSLTOPTS = --stringparam html.stylesheet mega-style.css \
+           --stringparam  chapter.autolabel 1 \
+           --stringparam  section.autolabel 1 \
+           --stringparam  section.label.includes.component.label 1 \
+           --xinclude
+ALLPREQ = html tarball
+
+        ifeq ($(BRANCH),edison)
+TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png  \
+        figures/using-a-pre-built-image.png \
+        figures/poky-title.png \
+        figures/adt-title.png figures/bsp-title.png \
+        figures/kernel-title.png figures/kernel-architecture-overview.png \
+        figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
+        figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
+        figures/kernel-example-repos-edison.png \
+        figures/kernel-overview-1.png figures/kernel-overview-2.png \
+        figures/kernel-overview-3-edison.png \
+        figures/source-repos.png figures/yp-download.png \
+        figures/wip.png
+        else ifeq ($(BRANCH),denzil)
+TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png  \
+        figures/using-a-pre-built-image.png \
+        figures/poky-title.png \
+        figures/adt-title.png figures/bsp-title.png \
+        figures/kernel-title.png figures/kernel-architecture-overview.png \
+        figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
+        figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
+        figures/kernel-example-repos-denzil.png \
+        figures/kernel-overview-1.png figures/kernel-overview-2.png \
+        figures/kernel-overview-3-denzil.png \
+        figures/source-repos.png figures/yp-download.png \
+        figures/wip.png
+        else
+TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures/building-an-image.png  \
+        figures/using-a-pre-built-image.png \
+        figures/poky-title.png figures/buildhistory.png figures/buildhistory-web.png \
+        figures/adt-title.png figures/bsp-title.png \
+        figures/kernel-dev-title.png figures/kernel-architecture-overview.png \
+        figures/app-dev-flow.png figures/bsp-dev-flow.png figures/dev-title.png \
+        figures/git-workflow.png figures/index-downloads.png figures/kernel-dev-flow.png \
+        figures/kernel-overview-1.png figures/kernel-overview-2-generic.png \
+        figures/source-repos.png figures/yp-download.png \
+        figures/profile-title.png figures/kernelshark-all.png \
+        figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \
+        figures/kernelshark-output-display.png figures/lttngmain0.png \
+        figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \
+        figures/oprofileui-downloading.png figures/oprofileui-processes.png \
+        figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \
+        figures/perf-systemwide.png figures/perf-systemwide-libc.png \
+        figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \
+        figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \
+        figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \
+        figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \
+        figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \
+        figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \
+        figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \
+        figures/sched-wakeup-profile.png figures/sysprof-callers.png \
+        figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \
+        figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \
+        figures/package-feeds.png figures/layer-input.png figures/images.png figures/sdk.png \
+        figures/source-fetching.png figures/patching.png figures/configuration-compile-autoreconf.png \
+        figures/analysis-for-package-splitting.png figures/image-generation.png \
+        figures/sdk-generation.png
+        endif
+
+MANUALS = $(DOC)/$(DOC).html
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+
+endif
+
+ifeq ($(DOC),ref-manual)
+XSLTOPTS = --xinclude
+ALLPREQ = html pdf eclipse tarball
+TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
+        figures/buildhistory.png figures/buildhistory-web.png eclipse \
+        figures/cross-development-toolchains.png figures/layer-input.png \
+        figures/package-feeds.png figures/source-input.png \
+        figures/user-configuration.png figures/yocto-environment-ref.png \
+        figures/images.png figures/sdk.png figures/source-fetching.png \
+        figures/patching.png figures/configuration-compile-autoreconf.png \
+        figures/analysis-for-package-splitting.png figures/image-generation.png \
+        figures/sdk-generation.png
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+endif
+
+
+ifeq ($(DOC),adt-manual)
+XSLTOPTS = --xinclude
+ALLPREQ = html pdf eclipse tarball
+TARFILES = adt-manual.html adt-manual.pdf adt-style.css figures/adt-title.png \
+                        eclipse
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+endif
+
+ifeq ($(DOC),profile-manual)
+XSLTOPTS = --xinclude
+ALLPREQ = html pdf eclipse tarball
+TARFILES = profile-manual.html profile-manual.pdf profile-manual-style.css \
+           figures/profile-title.png figures/kernelshark-all.png \
+           figures/kernelshark-choose-events.png figures/kernelshark-i915-display.png \
+           figures/kernelshark-output-display.png figures/lttngmain0.png \
+           figures/oprofileui-busybox.png figures/oprofileui-copy-to-user.png \
+           figures/oprofileui-downloading.png figures/oprofileui-processes.png \
+           figures/perf-probe-do_fork-profile.png figures/perf-report-cycles-u.png \
+           figures/perf-systemwide.png figures/perf-systemwide-libc.png \
+           figures/perf-wget-busybox-annotate-menu.png figures/perf-wget-busybox-annotate-udhcpc.png \
+           figures/perf-wget-busybox-debuginfo.png figures/perf-wget-busybox-dso-zoom.png \
+           figures/perf-wget-busybox-dso-zoom-menu.png figures/perf-wget-busybox-expanded-stripped.png \
+           figures/perf-wget-flat-stripped.png figures/perf-wget-g-copy-from-user-expanded-stripped.png \
+           figures/perf-wget-g-copy-to-user-expanded-debuginfo.png figures/perf-wget-g-copy-to-user-expanded-stripped.png \
+           figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png figures/pybootchartgui-linux-yocto.png \
+           figures/pychart-linux-yocto-rpm.png figures/pychart-linux-yocto-rpm-nostrip.png \
+           figures/sched-wakeup-profile.png figures/sysprof-callers.png \
+           figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png \
+           eclipse
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+endif
+
+ifeq ($(DOC),kernel-dev)
+XSLTOPTS = --xinclude
+ALLPREQ = html pdf eclipse tarball
+TARFILES = kernel-dev.html kernel-dev.pdf kernel-dev-style.css figures/kernel-dev-title.png \
+           figures/kernel-architecture-overview.png \
+           eclipse
+MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
+FIGURES = figures
+STYLESHEET = $(DOC)/*.css
+endif
+
+
+##
+# These URI should be rewritten by your distribution's xml catalog to
+# match your localy installed XSL stylesheets.
+XSL_BASE_URI  = http://docbook.sourceforge.net/release/xsl/current
+XSL_XHTML_URI = $(XSL_BASE_URI)/xhtml/docbook.xsl
+
+all: $(ALLPREQ)
+
+pdf:
+ifeq ($(DOC),yocto-project-qs)
+        @echo " "
+        @echo "ERROR: You cannot generate a yocto-project-qs PDF file."
+        @echo " "
+
+else ifeq ($(DOC),mega-manual)
+        @echo " "
+        @echo "ERROR: You cannot generate a mega-manual PDF file."
+        @echo " "
+
+else
+
+        cd $(DOC); ../tools/poky-docbook-to-pdf $(DOC).xml ../template; cd ..
+endif
+
+html:
+ifeq ($(DOC),mega-manual)
+#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html
+        @echo " "
+        @echo "******** Building "$(DOC)
+        @echo " "
+        cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
+        @echo " "
+        @echo "******** Using mega-manual.sed to process external links"
+        @echo " "
+        cd $(DOC); sed -f ../tools/mega-manual.sed < mega-manual.html > mega-output.html; cd ..
+        @echo " "
+        @echo "******** Cleaning up transient file mega-output.html"
+        @echo " "
+        cd $(DOC); rm mega-manual.html; mv mega-output.html mega-manual.html; cd ..
+else
+#       See http://www.sagehill.net/docbookxsl/HtmlOutput.html
+        @echo " "
+        @echo "******** Building "$(DOC)
+        @echo " "
+        cd $(DOC); xsltproc $(XSLTOPTS) -o $(DOC).html $(DOC)-customization.xsl $(DOC).xml; cd ..
+endif
+
+
+eclipse: BASE_DIR = html/$(DOC)/
+
+eclipse: eclipse-generate eclipse-resolve-links
+
+.PHONY : eclipse-generate eclipse-resolve-links
+
+eclipse-generate:
+ifeq ($(filter $(DOC), adt-manual bsp-guide dev-manual kernel-dev profile-manual ref-manual yocto-project-qs),)
+        @echo " "
+        @echo "ERROR: You can only create eclipse documentation"
+        @echo "       of the following documentation parts:"
+        @echo "       - adt-manual"
+        @echo "       - bsp-guide"
+        @echo "       - dev-manual"
+        @echo "       - kernel-dev"
+        @echo "       - profile-manual"
+        @echo "       - ref-manual"
+        @echo "       - yocto-project-qs"
+        @echo " "
+else
+        @echo " "
+        @echo "******** Building eclipse help of "$(DOC)
+        @echo " "
+        cd $(DOC) && \
+                xsltproc $(XSLTOPTS) \
+                                --stringparam base.dir '$(BASE_DIR)' \
+                                -o eclipse/$(DOC).html \
+                                $(DOC)-eclipse-customization.xsl $(DOC).xml && \
+                mv eclipse/toc.xml eclipse/$(DOC)-toc.xml && \
+                cp -rf $(FIGURES) eclipse/$(BASE_DIR) && \
+                cd ..;
+
+        $(call modify-eclipse)
+endif
+
+eclipse-resolve-links:
+        @echo " "
+        @echo "******** Using eclipse-help.sed to process external links"
+        @echo " "
+        $(foreach FILE, \
+                $(wildcard $(DOC)/eclipse/html/$(DOC)/*.html), \
+                $(shell sed -i -f tools/eclipse-help.sed $(FILE)))
+
+tarball: html
+        @echo " "
+        @echo "******** Creating Tarball of document files"
+        @echo " "
+        cd $(DOC); tar -cvzf $(DOC).tgz $(TARFILES); cd ..
+
+validate:
+        cd $(DOC); xmllint --postvalid --xinclude --noout $(DOC).xml; cd ..
+
+
+publish:
+        @if test -f $(DOC)/$(DOC).html; \
+          then \
+            echo " "; \
+            echo "******** Publishing "$(DOC)".html"; \
+            echo " "; \
+            scp -r $(MANUALS) $(STYLESHEET) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
+            cd $(DOC); scp -r $(FIGURES) docs.yp:/var/www/www.yoctoproject.org-docs/$(VER)/$(DOC); \
+        else \
+          echo " "; \
+          echo $(DOC)".html missing.  Generate the file first then try again."; \
+          echo " "; \
+        fi
+
+clean:
+        rm -rf $(MANUALS); rm $(DOC)/$(DOC).tgz;
diff --git a/documentation/README b/documentation/README
new file mode 100644
index 0000000000..d01678d4f4
--- /dev/null
+++ b/documentation/README
@@ -0,0 +1,91 @@
+documentation
+=============
+
+This is the directory that contains the Yocto Project documentation.  The Yocto
+Project source repositories at http://git.yoctoproject.org/cgit.cgi have two
+instances of the "documentation" directory.  You should understand each of
+these instances.
+
+  poky/documentation - The directory within the poky Git repository containing
+                       the set of Yocto Project manuals.  When you clone the
+                       poky Git repository, the documentation directory
+                       contains the manuals.  The state of the manuals in this
+                       directory is guaranteed to reflect the latest Yocto
+                       Project release.  The manuals at the tip of this
+                       directory will also likely contain most manual
+                       development changes.
+
+  yocto-docs/documentation - The Git repository for the Yocto Project manuals.
+                             This repository is where manual development
+                             occurs.  If you plan on contributing back to the
+                             Yocto Project documentation, you should set up
+                             a local Git repository based on this upstream
+                             repository as follows:
+
+                               git clone git://git.yoctoproject.org/yocto-docs
+
+                             Changes and patches are first pushed to the
+                             yocto-docs Git repository.  Later, they make it
+                             into the poky Git repository found at
+                             git://git.yoctoproject.org/poky.
+
+Manual Organization
+===================
+
+Folders exist for individual manuals as follows:
+
+* adt-manual       - The Yocto Project Application Developer's Guide.
+* bsp-guide        - The Yocto Project Board Support Package (BSP) Developer's Guide
+* dev-manual       - The Yocto Project Development Manual
+* kernel-dev       - The Yocto Project Linux Kernel Development Manual
+* ref-manual       - The Yocto Project Reference Manual
+* yocto-project-qs - The Yocto Project Quick Start
+* mega-manual      - An aggregated manual comprised of all YP manuals and guides
+* profile-manual   - The Yocto Project Profile and Tracing Manual
+
+Each folder is self-contained regarding content and figures.  Note that there
+is a sed file needed to process the links of the mega-manual.  The sed file
+is located in the tools directory.  Also note that the figures folder in the
+mega-manual directory contains duplicates of all the figures in the YP folders
+directories for all YP manuals and guides.
+
+If you want to find HTML versions of the Yocto Project manuals on the web,
+go to http://www.yoctoproject.org and click on the "Documentation" tab.  From
+there you have access to archived documentation from previous releases, current
+documentation for the latest release, and "Docs in Progress" for the release
+currently being developed.
+
+In general, the Yocto Project site (http://www.yoctoproject.org) is a great
+reference for both information and downloads.
+
+Makefile
+========
+
+The Makefile processes manual directories to create HTML, PDF,
+tarballs, etc.  Details on how the Makefile work are documented
+inside the Makefile.  See that file for more information.
+
+To build a manual, you run the make command and pass it the name
+of the folder containing the manual's contents.
+For example, the following command run from the documentation directory
+creates an HTML and a PDF version of the ADT manual.
+The DOC variable specifies the manual you are making:
+
+     $ make DOC=adt-manual
+
+poky.ent
+========
+
+This file defines variables used for documentation production.  The variables
+are used to define release pathnames, URLs for the published manuals, etc.
+
+template
+========
+Contains various templates, fonts, and some old PNG files.
+
+tools
+=====
+Contains a tool to convert the DocBook files to PDF format.  This folder also
+contains the mega-manual.sed file, which is used by Makefile to process
+cross-references from within the manual that normally go to an external
+manual.
diff --git a/documentation/adt-manual/adt-command.xml b/documentation/adt-manual/adt-command.xml
new file mode 100644
index 0000000000..0ed3396ef5
--- /dev/null
+++ b/documentation/adt-manual/adt-command.xml
@@ -0,0 +1,224 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='using-the-command-line'>
+<title>Using the Command Line</title>
+
+    <para>
+        Recall that earlier the manual discussed how to use an existing toolchain
+        tarball that had been installed into the default installation
+        directory, <filename>/opt/poky/&DISTRO;</filename>, which is outside of the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+        (see the section "<link linkend='using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball)</link>".
+        And, that sourcing your architecture-specific environment setup script
+        initializes a suitable cross-toolchain development environment.
+    </para>
+
+    <para>
+        During this setup, locations for the compiler, QEMU scripts, QEMU binary,
+        a special version of <filename>pkgconfig</filename> and other useful
+        utilities are added to the <filename>PATH</filename> variable.
+        Also, variables to assist
+        <filename>pkgconfig</filename> and <filename>autotools</filename>
+        are also defined so that, for example, <filename>configure.sh</filename>
+        can find pre-generated test results for tests that need target hardware
+        on which to run.
+    </para>
+
+    <para>
+        Collectively, these conditions allow you to easily use the toolchain
+        outside of the OpenEmbedded build environment on both autotools-based
+        projects and Makefile-based projects.
+        This chapter provides information for both these types of projects.
+    </para>
+
+
+<section id='autotools-based-projects'>
+<title>Autotools-Based Projects</title>
+
+    <para>
+        Once you have a suitable cross-toolchain installed, it is very easy to
+        develop a project outside of the OpenEmbedded build system.
+        This section presents a simple "Helloworld" example that shows how
+        to set up, compile, and run the project.
+    </para>
+
+    <section id='creating-and-running-a-project-based-on-gnu-autotools'>
+        <title>Creating and Running a Project Based on GNU Autotools</title>
+
+        <para>
+            Follow these steps to create a simple autotools-based project:
+            <orderedlist>
+                <listitem><para><emphasis>Create your directory:</emphasis>
+                    Create a clean directory for your project and then make
+                    that directory your working location:
+                    <literallayout class='monospaced'>
+     $ mkdir $HOME/helloworld
+     $ cd $HOME/helloworld
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Populate the directory:</emphasis>
+                    Create <filename>hello.c</filename>, <filename>Makefile.am</filename>,
+                    and <filename>configure.in</filename> files as follows:
+                    <itemizedlist>
+                        <listitem><para>For <filename>hello.c</filename>, include
+                            these lines:
+                            <literallayout class='monospaced'>
+     #include &lt;stdio.h&gt;
+
+     main()
+        {
+           printf("Hello World!\n");
+        }
+                            </literallayout></para></listitem>
+                        <listitem><para>For <filename>Makefile.am</filename>,
+                            include these lines:
+                            <literallayout class='monospaced'>
+     bin_PROGRAMS = hello
+     hello_SOURCES = hello.c
+                            </literallayout></para></listitem>
+                        <listitem><para>For <filename>configure.in</filename>,
+                            include these lines:
+                            <literallayout class='monospaced'>
+     AC_INIT(hello.c)
+     AM_INIT_AUTOMAKE(hello,0.1)
+     AC_PROG_CC
+     AC_PROG_INSTALL
+     AC_OUTPUT(Makefile)
+                            </literallayout></para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para><emphasis>Source the cross-toolchain
+                    environment setup file:</emphasis>
+                    Installation of the cross-toolchain creates a cross-toolchain
+                    environment setup script in the directory that the ADT
+                    was installed.
+                    Before you can use the tools to develop your project, you must
+                    source this setup script.
+                    The script begins with the string "environment-setup" and contains
+                    the machine architecture, which is followed by the string
+                    "poky-linux".
+                    Here is an example that sources a script from the
+                    default ADT installation directory that uses the
+                    32-bit Intel x86 Architecture and using the
+                    &DISTRO_NAME; Yocto Project release:
+                    <literallayout class='monospaced'>
+     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate the local aclocal.m4
+                    files and create the configure script:</emphasis>
+                    The following GNU Autotools generate the local
+                    <filename>aclocal.m4</filename> files and create the
+                    configure script:
+                    <literallayout class='monospaced'>
+     $ aclocal
+     $ autoconf
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate files needed by GNU
+                    coding standards:</emphasis>
+                    GNU coding standards require certain files in order for the
+                    project to be compliant.
+                    This command creates those files:
+                    <literallayout class='monospaced'>
+     $ touch NEWS README AUTHORS ChangeLog
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Generate the configure
+                    file:</emphasis>
+                    This command generates the <filename>configure</filename>:
+                    <literallayout class='monospaced'>
+     $ automake -a
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Cross-compile the project:</emphasis>
+                    This command compiles the project using the cross-compiler:
+                    <literallayout class='monospaced'>
+     $ ./configure ${CONFIGURE_FLAGS}
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Make and install the project:</emphasis>
+                    These two commands generate and install the project into the
+                    destination directory:
+                    <literallayout class='monospaced'>
+     $ make
+     $ make install DESTDIR=./tmp
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Verify the installation:</emphasis>
+                    This command is a simple way to verify the installation
+                    of your project.
+                    Running the command prints the architecture on which
+                    the binary file can run.
+                    This architecture should be the same architecture that
+                    the installed cross-toolchain supports.
+                    <literallayout class='monospaced'>
+     $ file ./tmp/usr/local/bin/hello
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Execute your project:</emphasis>
+                    To execute the project in the shell, simply enter the name.
+                    You could also copy the binary to the actual target hardware
+                    and run the project there as well:
+                    <literallayout class='monospaced'>
+     $ ./hello
+                    </literallayout>
+                    As expected, the project displays the "Hello World!" message.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='passing-host-options'>
+        <title>Passing Host Options</title>
+
+        <para>
+            For an Autotools-based project, you can use the cross-toolchain by just
+            passing the appropriate host option to <filename>configure.sh</filename>.
+            The host option you use is derived from the name of the environment setup
+            script found in the directory in which you installed the cross-toolchain.
+            For example, the host option for an ARM-based target that uses the GNU EABI
+            is <filename>armv5te-poky-linux-gnueabi</filename>.
+            You will notice that the name of the script is
+            <filename>environment-setup-armv5te-poky-linux-gnueabi</filename>.
+            Thus, the following command works:
+            <literallayout class='monospaced'>
+     $ ./configure --host=armv5te-poky-linux-gnueabi \
+        --with-libtool-sysroot=&lt;sysroot-dir&gt;
+            </literallayout>
+        </para>
+
+        <para>
+            This single command updates your project and rebuilds it using the appropriate
+            cross-toolchain tools.
+            <note>
+                If <filename>configure</filename> script results in problems recognizing the
+                <filename>--with-libtool-sysroot=&lt;sysroot-dir&gt;</filename> option,
+                regenerate the script to enable the support by doing the following and then
+                run the script again:
+                <literallayout class='monospaced'>
+     $ libtoolize --automake
+     $ aclocal -I ${OECORE_NATIVE_SYSROOT}/usr/share/aclocal \
+        [-I &lt;dir_containing_your_project-specific_m4_macros&gt;]
+     $ autoconf
+     $ autoheader
+     $ automake -a
+                </literallayout>
+            </note>
+        </para>
+    </section>
+</section>
+
+<section id='makefile-based-projects'>
+<title>Makefile-Based Projects</title>
+
+    <para>
+        For a Makefile-based project, you use the cross-toolchain by making sure
+        the tools are used.
+        You can do this as follows:
+        <literallayout class='monospaced'>
+     CC=arm-poky-linux-gnueabi-gcc
+     LD=arm-poky-linux-gnueabi-ld
+     CFLAGS=”${CFLAGS} --sysroot=&lt;sysroot-dir&gt;”
+     CXXFLAGS=”${CXXFLAGS} --sysroot=&lt;sysroot-dir&gt;”
+        </literallayout>
+    </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/adt-manual/adt-intro.xml b/documentation/adt-manual/adt-intro.xml
new file mode 100644
index 0000000000..a92828515d
--- /dev/null
+++ b/documentation/adt-manual/adt-intro.xml
@@ -0,0 +1,195 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='adt-intro'>
+<title>Introduction</title>
+
+<para>
+    Welcome to the Yocto Project Application Developer's Guide.
+    This manual provides information that lets you begin developing applications
+    using the Yocto Project.
+</para>
+
+<para>
+    The Yocto Project provides an application development environment based on
+    an Application Development Toolkit (ADT) and the availability of stand-alone
+    cross-development toolchains and other tools.
+    This manual describes the ADT and how you can configure and install it,
+    how to access and use the cross-development toolchains, how to
+    customize the development packages installation,
+    how to use command line development for both Autotools-based and Makefile-based projects,
+    and an introduction to the <trademark class='trade'>Eclipse</trademark> IDE
+    Yocto Plug-in.
+    <note>
+        The ADT is distribution-neutral and does not require the Yocto
+        Project reference distribution, which is called Poky.
+        This manual, however, uses examples that use the Poky distribution.
+    </note>
+</para>
+
+<section id='adt-intro-section'>
+    <title>The Application Development Toolkit (ADT)</title>
+
+    <para>
+        Part of the Yocto Project development solution is an Application Development
+        Toolkit (ADT).
+        The ADT provides you with a custom-built, cross-development
+        platform suited for developing a user-targeted product application.
+    </para>
+
+    <para>
+        Fundamentally, the ADT consists of the following:
+        <itemizedlist>
+            <listitem><para>An architecture-specific cross-toolchain and matching
+                sysroot both built by the OpenEmbedded build system.
+                The toolchain and sysroot are based on a
+                <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                configuration and extensions,
+                which allows you to cross-develop on the host machine for the target hardware.
+                </para></listitem>
+            <listitem><para>The Eclipse IDE Yocto Plug-in.</para></listitem>
+            <listitem><para>The Quick EMUlator (QEMU), which lets you simulate target hardware.
+                </para></listitem>
+            <listitem><para>Various user-space tools that greatly enhance your application
+                development experience.</para></listitem>
+        </itemizedlist>
+    </para>
+
+    <section id='the-cross-development-toolchain'>
+        <title>The Cross-Development Toolchain</title>
+
+        <para>
+            The
+            <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>Cross-Development Toolchain</ulink>
+            consists of a cross-compiler, cross-linker, and cross-debugger
+            that are used to develop user-space applications for targeted
+            hardware.
+            This toolchain is created either by running the ADT Installer
+            script, a toolchain installer script, or through a
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            that is based on your Metadata configuration or extension for
+            your targeted device.
+            The cross-toolchain works with a matching target sysroot.
+        </para>
+    </section>
+
+    <section id='sysroot'>
+        <title>Sysroot</title>
+
+        <para>
+            The matching target sysroot contains needed headers and libraries for generating
+            binaries that run on the target architecture.
+            The sysroot is based on the target root filesystem image that is built by
+            the OpenEmbedded build system and uses the same Metadata configuration
+            used to build the cross-toolchain.
+        </para>
+    </section>
+
+    <section id='eclipse-overview'>
+        <title>Eclipse Yocto Plug-in</title>
+
+        <para>
+            The Eclipse IDE is a popular development environment and it fully supports
+            development using the Yocto Project.
+            When you install and configure the Eclipse Yocto Project Plug-in into
+            the Eclipse IDE, you maximize your Yocto Project experience.
+            Installing and configuring the Plug-in results in an environment that
+            has extensions specifically designed to let you more easily develop software.
+            These extensions allow for cross-compilation, deployment, and execution of
+            your output into a QEMU emulation session.
+            You can also perform cross-debugging and profiling.
+            The environment also supports a suite of tools that allows you to perform
+            remote profiling, tracing, collection of power data, collection of
+            latency data, and collection of performance data.
+        </para>
+
+        <para>
+            For information about the application development workflow that uses the Eclipse
+            IDE and for a detailed example of how to install and configure the Eclipse
+            Yocto Project Plug-in, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working Within Eclipse</ulink>" section
+            of the Yocto Project Development Manual.
+        </para>
+    </section>
+
+    <section id='the-qemu-emulator'>
+        <title>The QEMU Emulator</title>
+
+        <para>
+            The QEMU emulator allows you to simulate your hardware while running your
+            application or image.
+            QEMU is made available a number of ways:
+            <itemizedlist>
+                <listitem><para>If you use the ADT Installer script to install ADT, you can
+                    specify whether or not to install QEMU.</para></listitem>
+                <listitem><para>If you have downloaded a Yocto Project release and unpacked
+                    it to create a
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> and
+                    you have sourced
+                    the environment setup script, QEMU is installed and automatically
+                    available.</para></listitem>
+                <listitem><para>If you have installed the cross-toolchain
+                    tarball and you have sourced the toolchain's setup environment script, QEMU
+                    is also installed and automatically available.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='user-space-tools'>
+        <title>User-Space Tools</title>
+
+        <para>
+            User-space tools are included as part of the distribution.
+            You will find these tools helpful during development.
+            The tools include LatencyTOP, PowerTOP, OProfile, Perf, SystemTap, and Lttng-ust.
+            These tools are common development tools for the Linux platform.
+            <itemizedlist>
+                <listitem><para><emphasis>LatencyTOP:</emphasis> LatencyTOP focuses on latency
+                    that causes skips in audio,
+                    stutters in your desktop experience, or situations that overload your server
+                    even when you have plenty of CPU power left.
+                    </para></listitem>
+                <listitem><para><emphasis>PowerTOP:</emphasis> Helps you determine what
+                    software is using the most power.
+                    You can find out more about PowerTOP at
+                    <ulink url='https://01.org/powertop/'></ulink>.</para></listitem>
+                <listitem><para><emphasis>OProfile:</emphasis> A system-wide profiler for Linux
+                    systems that is capable of profiling all running code at low overhead.
+                    You can find out more about OProfile at
+                    <ulink url='http://oprofile.sourceforge.net/about/'></ulink>.
+                    For examples on how to setup and use this tool, see the
+                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>OProfile</ulink>"
+                    section in the Yocto Project Profiling and Tracing Manual.
+                    </para></listitem>
+                <listitem><para><emphasis>Perf:</emphasis> Performance counters for Linux used
+                    to keep track of certain types of hardware and software events.
+                    For more information on these types of counters see
+                    <ulink url='https://perf.wiki.kernel.org/'></ulink> and click
+                    on “Perf tools.”
+                    For examples on how to setup and use this tool, see the
+                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
+                    section in the Yocto Project Profiling and Tracing Manual.
+                    </para></listitem>
+                <listitem><para><emphasis>SystemTap:</emphasis> A free software infrastructure
+                    that simplifies information gathering about a running Linux system.
+                    This information helps you diagnose performance or functional problems.
+                    SystemTap is not available as a user-space tool through the Eclipse IDE Yocto Plug-in.
+                    See <ulink url='http://sourceware.org/systemtap'></ulink> for more information
+                    on SystemTap.
+                    For examples on how to setup and use this tool, see the
+                    "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-systemtap'>SystemTap</ulink>"
+                    section in the Yocto Project Profiling and Tracing Manual.</para></listitem>
+                <listitem><para><emphasis>Lttng-ust:</emphasis> A User-space Tracer designed to
+                    provide detailed information on user-space activity.
+                    See <ulink url='http://lttng.org/ust'></ulink> for more information on Lttng-ust.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/adt-manual/adt-manual-customization.xsl b/documentation/adt-manual/adt-manual-customization.xsl
new file mode 100644
index 0000000000..373bdb7140
--- /dev/null
+++ b/documentation/adt-manual/adt-manual-customization.xsl
@@ -0,0 +1,11 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+  
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+  <xsl:param name="html.stylesheet" select="'adt-style.css'" />
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/adt-manual/adt-manual-eclipse-customization.xsl b/documentation/adt-manual/adt-manual-eclipse-customization.xsl
new file mode 100644
index 0000000000..d16ffbb68e
--- /dev/null
+++ b/documentation/adt-manual/adt-manual-eclipse-customization.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+        xmlns="http://www.w3.org/1999/xhtml"
+        xmlns:fo="http://www.w3.org/1999/XSL/Format"
+        version="1.0">
+
+  <xsl:import
+          href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="chunk.quietly" select="1"/>
+  <xsl:param name="chunk.first.sections" select="1"/>
+  <xsl:param name="chunk.section.depth" select="10"/>
+  <xsl:param name="use.id.as.filename" select="1"/>
+  <xsl:param name="ulink.target" select="'_self'" />
+  <xsl:param name="base.dir" select="'html/adt-manual/'"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/adt-manual/adt-manual.xml b/documentation/adt-manual/adt-manual.xml
new file mode 100644
index 0000000000..9ac54d35d0
--- /dev/null
+++ b/documentation/adt-manual/adt-manual.xml
@@ -0,0 +1,113 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='adt-manual' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='figures/adt-title.png'
+                    format='SVG'
+                    align='left' scalefit='1' width='100%'/>
+            </imageobject>
+        </mediaobject>
+
+        <title>
+            Yocto Project Application Developer's Guide
+        </title>
+
+        <authorgroup>
+            <author>
+                <firstname>Jessica</firstname> <surname>Zhang</surname>
+                <affiliation>
+                    <orgname>Intel Corporation</orgname>
+                </affiliation>
+                <email>jessica.zhang@intel.com</email>
+            </author>
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>1.0</revnumber>
+                <date>6 April 2011</date>
+                <revremark>Released with the Yocto Project 1.0 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.0.1</revnumber>
+                <date>23 May 2011</date>
+                <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.1</revnumber>
+                <date>6 October 2011</date>
+                <revremark>Released with the Yocto Project 1.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.2</revnumber>
+                <date>April 2012</date>
+                <revremark>Released with the Yocto Project 1.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.3</revnumber>
+                <date>October 2012</date>
+                <revremark>Released with the Yocto Project 1.3 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>April 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5</revnumber>
+                <date>October 2013</date>
+                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5.1</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
+            </revision>
+       </revhistory>
+
+    <copyright>
+      <year>&COPYRIGHT_YEAR;</year>
+      <holder>Linux Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this document under
+        the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
+      </para>
+      <note>
+          For the latest version of this manual associated with this
+          Yocto Project release, see the
+          <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>
+          from the Yocto Project website.
+      </note>
+
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="adt-intro.xml"/>
+
+    <xi:include href="adt-prepare.xml"/>
+
+    <xi:include href="adt-package.xml"/>
+
+    <xi:include href="adt-command.xml"/>
+
+<!--    <index id='index'>
+      <title>Index</title>
+    </index>
+-->
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/adt-manual/adt-package.xml b/documentation/adt-manual/adt-package.xml
new file mode 100644
index 0000000000..48edf0aef5
--- /dev/null
+++ b/documentation/adt-manual/adt-package.xml
@@ -0,0 +1,101 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='adt-package'>
+<title>Optionally Customizing the Development Packages Installation</title>
+
+    <para>
+        Because the Yocto Project is suited for embedded Linux development, it is
+        likely that you will need to customize your development packages installation.
+        For example, if you are developing a minimal image, then you might not need
+        certain packages (e.g. graphics support packages).
+        Thus, you would like to be able to remove those packages from your target sysroot.
+    </para>
+
+<section id='package-management-systems'>
+    <title>Package Management Systems</title>
+
+    <para>
+        The OpenEmbedded build system supports the generation of sysroot files using
+        three different Package Management Systems (PMS):
+        <itemizedlist>
+            <listitem><para><emphasis>OPKG:</emphasis> A less well known PMS whose use
+                originated in the OpenEmbedded and OpenWrt embedded Linux projects.
+                This PMS works with files packaged in an <filename>.ipk</filename> format.
+                See <ulink url='http://en.wikipedia.org/wiki/Opkg'></ulink> for more
+                information about OPKG.</para></listitem>
+            <listitem><para><emphasis>RPM:</emphasis> A more widely known PMS intended for GNU/Linux
+                distributions.
+                This PMS works with files packaged in an <filename>.rms</filename> format.
+                The build system currently installs through this PMS by default.
+                See <ulink url='http://en.wikipedia.org/wiki/RPM_Package_Manager'></ulink>
+                for more information about RPM.</para></listitem>
+            <listitem><para><emphasis>Debian:</emphasis> The PMS for Debian-based systems
+                is built on many PMS tools.
+                The lower-level PMS tool <filename>dpkg</filename> forms the base of the Debian PMS.
+                For information on dpkg see
+                <ulink url='http://en.wikipedia.org/wiki/Dpkg'></ulink>.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='configuring-the-pms'>
+    <title>Configuring the PMS</title>
+
+    <para>
+        Whichever PMS you are using, you need to be sure that the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
+        variable in the <filename>conf/local.conf</filename>
+        file is set to reflect that system.
+        The first value you choose for the variable specifies the package file format for the root
+        filesystem at sysroot.
+        Additional values specify additional formats for convenience or testing.
+        See the configuration file for details.
+    </para>
+
+    <note>
+        For build performance information related to the PMS, see the
+        "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'>Packaging - <filename>package*.bbclass</filename></ulink>" 
+        section in the Yocto Project Reference Manual.
+    </note>
+
+    <para>
+        As an example, consider a scenario where you are using OPKG and you want to add
+        the <filename>libglade</filename> package to the target sysroot.
+    </para>
+
+    <para>
+        First, you should generate the <filename>ipk</filename> file for the
+        <filename>libglade</filename> package and add it
+        into a working <filename>opkg</filename> repository.
+        Use these commands:
+        <literallayout class='monospaced'>
+     $ bitbake libglade
+     $ bitbake package-index
+        </literallayout>
+    </para>
+
+    <para>
+        Next, source the environment setup script found in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        Follow that by setting up the installation destination to point to your
+        sysroot as <filename>&lt;sysroot_dir&gt;</filename>.
+        Finally, have an OPKG configuration file <filename>&lt;conf_file&gt;</filename>
+        that corresponds to the <filename>opkg</filename> repository you have just created.
+        The following command forms should now work:
+        <literallayout class='monospaced'>
+     $ opkg-cl –f &lt;conf_file&gt; -o &lt;sysroot_dir&gt; update
+     $ opkg-cl –f &lt;cconf_file&gt; -o &lt;sysroot_dir&gt; \
+        --force-overwrite install libglade
+     $ opkg-cl –f &lt;cconf_file&gt; -o &lt;sysroot_dir&gt; \
+        --force-overwrite install libglade-dbg
+     $ opkg-cl –f &lt;conf_file&gt; -o &lt;sysroot_dir&gt; \
+        --force-overwrite install libglade-dev
+        </literallayout>
+    </para>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/adt-manual/adt-prepare.xml b/documentation/adt-manual/adt-prepare.xml
new file mode 100644
index 0000000000..02416b3cda
--- /dev/null
+++ b/documentation/adt-manual/adt-prepare.xml
@@ -0,0 +1,646 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='adt-prepare'>
+
+<title>Preparing for Application Development</title>
+
+<para>
+    In order to develop applications, you need set up your host development system.
+    Several ways exist that allow you to install cross-development tools, QEMU, the
+    Eclipse Yocto Plug-in, and other tools.
+    This chapter describes how to prepare for application development.
+</para>
+
+<section id='installing-the-adt'>
+    <title>Installing the ADT and Toolchains</title>
+
+    <para>
+        The following list describes installation methods that set up varying degrees of tool
+        availability on your system.
+        Regardless of the installation method you choose,
+        you must <filename>source</filename> the cross-toolchain
+        environment setup script before you use a toolchain.
+        See the "<link linkend='setting-up-the-cross-development-environment'>Setting Up the
+        Cross-Development Environment</link>" section for more information.
+    </para>
+
+    <note>
+        <para>Avoid mixing installation methods when installing toolchains for different architectures.
+        For example, avoid using the ADT Installer to install some toolchains and then hand-installing
+        cross-development toolchains by running the toolchain installer for different architectures.
+        Mixing installation methods can result in situations where the ADT Installer becomes
+        unreliable and might not install the toolchain.</para>
+        <para>If you must mix installation methods, you might avoid problems by deleting
+        <filename>/var/lib/opkg</filename>, thus purging the <filename>opkg</filename> package
+        metadata</para>
+    </note>
+
+    <para>
+        <itemizedlist>
+            <listitem><para><emphasis>Use the ADT installer script:</emphasis>
+                This method is the recommended way to install the ADT because it
+                automates much of the process for you.
+                For example, you can configure the installation to install the QEMU emulator
+                and the user-space NFS, specify which root filesystem profiles to download,
+                and define the target sysroot location.</para></listitem>
+            <listitem><para><emphasis>Use an existing toolchain:</emphasis>
+                Using this method, you select and download an architecture-specific
+                toolchain installer and then run the script to hand-install the toolchain.
+                If you use this method, you just get the cross-toolchain and QEMU - you do not
+                get any of the other mentioned benefits had you run the ADT Installer script.</para></listitem>
+            <listitem><para><emphasis>Use the toolchain from within the Build Directory:</emphasis>
+                If you already have a
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+                you can build the cross-toolchain within the directory.
+                However, like the previous method mentioned, you only get the cross-toolchain and QEMU - you
+                do not get any of the other benefits without taking separate steps.</para></listitem>
+        </itemizedlist>
+    </para>
+
+    <section id='using-the-adt-installer'>
+        <title>Using the ADT Installer</title>
+
+        <para>
+            To run the ADT Installer, you need to get the ADT Installer tarball, be sure
+            you have the necessary host development packages that support the ADT Installer,
+            and then run the ADT Installer Script.
+        </para>
+
+        <para>
+            For a list of the host packages needed to support ADT installation and use, see the
+            "ADT Installer Extras" lists in the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>" section
+            of the Yocto Project Reference Manual.
+        </para>
+
+        <section id='getting-the-adt-installer-tarball'>
+            <title>Getting the ADT Installer Tarball</title>
+
+            <para>
+                The ADT Installer is contained in the ADT Installer tarball.
+                You can get the tarball using either of these methods:
+                <itemizedlist>
+                    <listitem><para><emphasis>Download the Tarball:</emphasis>
+                        You can download the tarball from
+                        <ulink url='&YOCTO_ADTINSTALLER_DL_URL;'></ulink> into
+                        any directory.</para></listitem>
+                    <listitem><para><emphasis>Build the Tarball:</emphasis>
+                        You can use BitBake to generate the tarball inside an
+                        existing
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                        </para>
+                        <para>If you use BitBake to generate the ADT Installer
+                        tarball, you must <filename>source</filename> the
+                        environment setup script
+                        (<ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                        or
+                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+                        located in the Source Directory before running the
+                        BitBake command that creates the tarball.</para>
+                        <para>The following example commands establish
+                        the
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
+                        check out the current release branch, set up the
+                        build environment while also creating the default
+                        Build Directory, and run the BitBake command that
+                        results in the tarball
+                        <filename>~/yocto-project/build/tmp/deploy/sdk/adt_installer.tar.bz2</filename>:
+                        <note>
+                            Before using BitBake to build the ADT tarball, be
+                            sure to make sure your
+                            <filename>local.conf</filename> file is properly
+                            configured.
+                        </note>
+                        <literallayout class='monospaced'>
+     $ cd ~
+     $ git clone git://git.yoctoproject.org/poky
+     $ cd poky
+     $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+     $ source &OE_INIT_FILE;
+     $ bitbake adt-installer
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='configuring-and-running-the-adt-installer-script'>
+            <title>Configuring and Running the ADT Installer Script</title>
+
+            <para>
+                Before running the ADT Installer script, you need to unpack the tarball.
+                You can unpack the tarball in any directory you wish.
+                For example, this command copies the ADT Installer tarball from where
+                it was built into the home directory and then unpacks the tarball into
+                a top-level directory named <filename>adt-installer</filename>:
+                <literallayout class='monospaced'>
+     $ cd ~
+     $ cp ~/poky/build/tmp/deploy/sdk/adt_installer.tar.bz2 $HOME
+     $ tar -xjf adt_installer.tar.bz2
+                </literallayout>
+                Unpacking it creates the directory <filename>adt-installer</filename>,
+                which contains the ADT Installer script (<filename>adt_installer</filename>)
+                and its configuration file (<filename>adt_installer.conf</filename>).
+            </para>
+
+            <para>
+                Before you run the script, however, you should examine the ADT Installer configuration
+                file and be sure you are going to get what you want.
+                Your configurations determine which kernel and filesystem image are downloaded.
+            </para>
+
+            <para>
+                The following list describes the configurations you can define for the ADT Installer.
+                For configuration values and restrictions, see the comments in
+                the <filename>adt-installer.conf</filename> file:
+
+                <itemizedlist>
+                    <listitem><para><filename>YOCTOADT_REPO</filename>: This area
+                        includes the IPKG-based packages and the root filesystem upon which
+                        the installation is based.
+                        If you want to set up your own IPKG repository pointed to by
+                        <filename>YOCTOADT_REPO</filename>, you need to be sure that the
+                        directory structure follows the same layout as the reference directory
+                        set up at <ulink url='http://adtrepo.yoctoproject.org'></ulink>.
+                        Also, your repository needs to be accessible through HTTP.</para></listitem>
+                    <listitem><para><filename>YOCTOADT_TARGETS</filename>: The machine
+                        target architectures for which you want to set up cross-development
+                        environments.</para></listitem>
+                    <listitem><para><filename>YOCTOADT_QEMU</filename>: Indicates whether
+                        or not to install the emulator QEMU.</para></listitem>
+                    <listitem><para><filename>YOCTOADT_NFS_UTIL</filename>: Indicates whether
+                        or not to install user-mode NFS.
+                        If you plan to use the Eclipse IDE Yocto plug-in against QEMU,
+                        you should install NFS.
+                        <note>To boot QEMU images using our userspace NFS server, you need
+                            to be running <filename>portmap</filename> or <filename>rpcbind</filename>.
+                            If you are running <filename>rpcbind</filename>, you will also need to add the
+                            <filename>-i</filename> option when <filename>rpcbind</filename> starts up.
+                            Please make sure you understand the security implications of doing this.
+                            You might also have to modify your firewall settings to allow
+                            NFS booting to work.</note></para></listitem>
+                    <listitem><para><filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>: The root
+                        filesystem images you want to download from the
+                        <filename>YOCTOADT_IPKG_REPO</filename> repository.</para></listitem>
+                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_IMAGE_&lt;arch&gt;</filename>: The
+                        particular root filesystem used to extract and create the target sysroot.
+                        The value of this variable must have been specified with
+                        <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>.
+                        For example, if you downloaded both <filename>minimal</filename> and
+                        <filename>sato-sdk</filename> images by setting
+                        <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
+                        to "minimal sato-sdk", then <filename>YOCTOADT_ROOTFS_&lt;arch&gt;</filename>
+                        must be set to either <filename>minimal</filename> or
+                        <filename>sato-sdk</filename>.</para></listitem>
+                    <listitem><para><filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename>: The
+                        location on the development host where the target sysroot is created.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                After you have configured the <filename>adt_installer.conf</filename> file,
+                run the installer using the following command.
+                Be sure that you are not trying to use cross-compilation tools.
+                When you run the installer, the environment must use a
+                host <filename>gcc</filename>:
+                <literallayout class='monospaced'>
+     $ cd ~/adt-installer
+     $ ./adt_installer
+                </literallayout>
+                Once the installer begins to run, you are asked to enter the
+                location for cross-toolchain installation.
+                The default location is
+                <filename>/opt/poky/&lt;release&gt;</filename>.
+                After either accepting the default location or selecting your
+                own location, you are prompted to run the installation script
+                interactively or in silent mode.
+                If you want to closely monitor the installation,
+                choose “I” for interactive mode rather than “S” for silent mode.
+                Follow the prompts from the script to complete the installation.
+            </para>
+
+            <para>
+                Once the installation completes, the ADT, which includes the
+                cross-toolchain, is installed in the selected installation
+                directory.
+                You will notice environment setup files for the cross-toolchain
+                in the installation directory, and image tarballs in the
+                <filename>adt-installer</filename> directory according to your
+                installer configurations, and the target sysroot located
+                according to the
+                <filename>YOCTOADT_TARGET_SYSROOT_LOC_&lt;arch&gt;</filename>
+                variable also in your configuration file.
+            </para>
+         </section>
+    </section>
+
+    <section id='using-an-existing-toolchain-tarball'>
+        <title>Using a Cross-Toolchain Tarball</title>
+
+        <para>
+            If you want to simply install a cross-toolchain by hand, you can
+            do so by running the toolchain installer.
+            The installer includes the pre-built cross-toolchain, the
+            <filename>runqemu</filename> script, and support files.
+            If you use this method to install the cross-toolchain, you
+            might still need to install the target sysroot by installing and
+            extracting it separately.
+            For information on how to install the sysroot, see the
+            "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
+        </para>
+
+        <para>
+            Follow these steps:
+            <orderedlist>
+                <listitem><para>Get your toolchain installer using one of the
+                    following methods:
+                    <itemizedlist>
+                        <listitem><para>Go to
+                            <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>
+                            and find the folder that matches your host
+                            development system (i.e. <filename>i686</filename>
+                            for 32-bit machines or <filename>x86_64</filename>
+                            for 64-bit machines).</para>
+                            <para>Go into that folder and download the toolchain
+                            installer whose name includes the appropriate target
+                            architecture.
+                            The toolchains provided by the Yocto Project
+                            are based off of the
+                            <filename>core-image-sato</filename> image and
+                            contain libraries appropriate for developing
+                            against that image.
+                            For example, if your host development system is a
+                            64-bit x86 system and you are going to use
+                            your cross-toolchain for a 32-bit x86
+                            target, go into the <filename>x86_64</filename>
+                            folder and download the following installer:
+                            <literallayout class='monospaced'>
+     poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+                            </literallayout></para></listitem>
+                        <listitem><para>Build your own toolchain installer.
+                            For cases where you cannot use an installer
+                            from the download area, you can build your own as
+                            described in the
+                            "<link linkend='optionally-building-a-toolchain-installer'>Optionally Building a Toolchain Installer</link>"
+                            section.</para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para>Once you have the installer, run it to install
+                    the toolchain.
+                    <note>
+                        You must change the permissions on the toolchain
+                        installer script so that it is executable.
+                    </note></para>
+                    <para>The following command shows how to run the installer
+                    given a toolchain tarball for a 64-bit x86 development host
+                    system and a 32-bit x86 target architecture.
+                    The example assumes the toolchain installer is located
+                    in <filename>~/Downloads/</filename>.
+                    <literallayout class='monospaced'>
+     $ ~/Downloads/poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+                    </literallayout>
+                    The first thing the installer prompts you for is the
+                    directory into which you want to install the toolchain.
+                    The default directory used is
+                    <filename>opt/poky/&DISTRO;</filename>.
+                    If you do not have write permissions for the directory
+                    into which you are installing the toolchain, the
+                    toolchain installer notifies you and exits.
+                    Be sure you have write permissions in the directory and
+                    run the installer again.</para>
+                    <para>When the script finishes, the cross-toolchain is
+                    installed.
+                    You will notice environment setup files for the
+                    cross-toolchain in the installation directory.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='using-the-toolchain-from-within-the-build-tree'>
+        <title>Using BitBake and the Build Directory</title>
+
+        <para>
+            A final way of making the cross-toolchain available is to use BitBake
+            to generate the toolchain within an existing
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+            This method does not install the toolchain into the default
+            <filename>/opt</filename> directory.
+            As with the previous method, if you need to install the target sysroot, you must
+            do that separately as well.
+        </para>
+
+        <para>
+            Follow these steps to generate the toolchain into the Build Directory:
+            <orderedlist>
+                <listitem><para><emphasis>Set up the Build Environment:</emphasis>
+                    Source the OpenEmbedded build environment setup
+                    script (i.e.
+                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                    or
+                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+                    located in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                    </para></listitem>
+                <listitem><para><emphasis>Check your Local Configuration File:</emphasis>
+                    At this point, you should be sure that the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable
+                    in the <filename>local.conf</filename> file found in the
+                    <filename>conf</filename> directory of the Build Directory
+                    is set for the target architecture.
+                    Comments within the <filename>local.conf</filename> file
+                    list the values you can use for the
+                    <filename>MACHINE</filename> variable.
+                    <note>
+                        You can populate the Build Directory with the
+                        cross-toolchains for more than a single architecture.
+                        You just need to edit the <filename>MACHINE</filename>
+                        variable in the <filename>local.conf</filename> file and
+                        re-run the BitBake command.
+                    </note></para></listitem>
+                <listitem><para><emphasis>Generate the Cross-Toolchain:</emphasis>
+                    Run <filename>bitbake meta-ide-support</filename> to
+                    complete the cross-toolchain generation.
+                    Once the BitBake command finishes, the cross-toolchain is
+                    generated and populated within the Build Directory.
+                    You will notice environment setup files for the
+                    cross-toolchain that contain the string
+                    "<filename>environment-setup</filename>" in the
+                    Build Directory's <filename>tmp</filename> folder.</para>
+                    <para>Be aware that when you use this method to install the
+                    toolchain, you still need to separately extract and install
+                    the sysroot filesystem.
+                    For information on how to do this, see the
+                    "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>" section.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+</section>
+
+<section id='setting-up-the-cross-development-environment'>
+    <title>Setting Up the Cross-Development Environment</title>
+
+    <para>
+        Before you can develop using the cross-toolchain, you need to set up the
+        cross-development environment by sourcing the toolchain's environment setup script.
+        If you used the ADT Installer or hand-installed cross-toolchain,
+        then you can find this script in the directory you chose for installation.
+        The default installation directory is the <filename>&YOCTO_ADTPATH_DIR;</filename>
+        directory.
+        If you installed the toolchain in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+        you can find the environment setup
+        script for the toolchain in the Build Directory's <filename>tmp</filename> directory.
+    </para>
+
+    <para>
+        Be sure to run the environment setup script that matches the
+        architecture for which you are developing.
+        Environment setup scripts begin with the string
+        "<filename>environment-setup</filename>" and include as part of their
+        name the architecture.
+        For example, the toolchain environment setup script for a 64-bit
+        IA-based architecture installed in the default installation directory
+        would be the following:
+        <literallayout class='monospaced'>
+     &YOCTO_ADTPATH_DIR;/environment-setup-x86_64-poky-linux
+        </literallayout>
+    </para>
+</section>
+
+<section id='securing-kernel-and-filesystem-images'>
+    <title>Securing Kernel and Filesystem Images</title>
+
+    <para>
+        You will need to have a kernel and filesystem image to boot using your
+        hardware or the QEMU emulator.
+        Furthermore, if you plan on booting your image using NFS or you want to use the root filesystem
+        as the target sysroot, you need to extract the root filesystem.
+    </para>
+
+    <section id='getting-the-images'>
+        <title>Getting the Images</title>
+
+        <para>
+            To get the kernel and filesystem images, you either have to build them or download
+            pre-built versions.
+            You can find examples for both these situations in the
+            "<ulink url='&YOCTO_DOCS_QS_URL;#test-run'>A Quick Test Run</ulink>" section of
+            the Yocto Project Quick Start.
+        </para>
+
+        <para>
+            The Yocto Project ships basic kernel and filesystem images for several
+            architectures (<filename>x86</filename>, <filename>x86-64</filename>,
+            <filename>mips</filename>, <filename>powerpc</filename>, and <filename>arm</filename>)
+            that you can use unaltered in the QEMU emulator.
+            These kernel images reside in the release
+            area - <ulink url='&YOCTO_MACHINES_DL_URL;'></ulink>
+            and are ideal for experimentation using Yocto Project.
+            For information on the image types you can build using the OpenEmbedded build system,
+            see the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
+            the Yocto Project Reference Manual.
+        </para>
+
+        <para>
+            If you are planning on developing against your image and you are not
+            building or using one of the Yocto Project development images
+            (e.g. <filename>core-image-*-dev</filename>), you must be sure to
+            include the development packages as part of your image recipe.
+        </para>
+
+        <para>
+            Furthermore, if you plan on remotely deploying and debugging your
+            application from within the
+            Eclipse IDE, you must have an image that contains the Yocto Target Communication
+            Framework (TCF) agent (<filename>tcf-agent</filename>).
+            By default, the Yocto Project provides only one type of pre-built
+            image that contains the <filename>tcf-agent</filename>.
+            And, those images are SDK (e.g.<filename>core-image-sato-sdk</filename>).
+        </para>
+
+        <para>
+            If you want to use a different image type that contains the <filename>tcf-agent</filename>,
+            you can do so one of two ways:
+            <itemizedlist>
+                <listitem><para>Modify the <filename>conf/local.conf</filename> configuration in
+                    the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    and then rebuild the image.
+                    With this method, you need to modify the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
+                    variable to have the value of "tools-debug" before rebuilding the image.
+                    Once the image is rebuilt, the <filename>tcf-agent</filename> will be included
+                    in the image and is launched automatically after the boot.</para></listitem>
+                <listitem><para>Manually build the <filename>tcf-agent</filename>.
+                    To build the agent, follow these steps:
+                    <orderedlist>
+                        <listitem><para>Be sure the ADT is installed as described in the
+                            "<link linkend='installing-the-adt'>Installing the ADT and Toolchains</link>" section.
+                            </para></listitem>
+                        <listitem><para>Set up the cross-development environment as described in the
+                            "<link linkend='setting-up-the-cross-development-environment'>Setting
+                            Up the Cross-Development Environment</link>" section.</para></listitem>
+                        <listitem><para>Get the <filename>tcf-agent</filename> source code using
+                            the following commands:
+                            <literallayout class='monospaced'>
+     $ git clone http://git.eclipse.org/gitroot/tcf/org.eclipse.tcf.agent.git
+     $ cd org.eclipse.tcf.agent/agent
+                            </literallayout></para></listitem>
+                        <listitem><para>Locate the
+                            <filename>Makefile.inc</filename> file inside the
+                            <filename>agent</filename> folder and modify it
+                            for the cross-compilation environment by setting the
+                            <filename>OPSYS</filename> and
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                            variables according to your target.
+                            </para></listitem>
+                        <listitem><para>Use the cross-development tools to build the
+                            <filename>tcf-agent</filename>.
+                            Before you "Make" the file, be sure your cross-tools are set up first.
+                            See the "<link linkend='makefile-based-projects'>Makefile-Based Projects</link>"
+                            section for information on how to make sure the cross-tools are set up
+                            correctly.</para>
+                            <para>If the build is successful, the <filename>tcf-agent</filename> output will
+                            be <filename>obj/$(OPSYS)/$(MACHINE)/Debug/agent</filename>.</para></listitem>
+                        <listitem><para>Deploy the agent into the image's root filesystem.</para></listitem>
+                    </orderedlist>
+                </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='extracting-the-root-filesystem'>
+        <title>Extracting the Root Filesystem</title>
+
+        <para>
+            If you install your toolchain by hand or build it using BitBake and
+            you need a root filesystem, you need to extract it separately.
+            If you use the ADT Installer to install the ADT, the root
+            filesystem is automatically extracted and installed.
+        </para>
+
+        <para>
+            Here are some cases where you need to extract the root filesystem:
+            <itemizedlist>
+                <listitem><para>You want to boot the image using NFS.
+                    </para></listitem>
+                <listitem><para>You want to use the root filesystem as the
+                    target sysroot.
+                    For example, the Eclipse IDE environment with the Eclipse
+                    Yocto Plug-in installed allows you to use QEMU to boot
+                    under NFS.</para></listitem>
+                <listitem><para>You want to develop your target application
+                    using the root filesystem as the target sysroot.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            To extract the root filesystem, first <filename>source</filename>
+            the cross-development environment setup script.
+            If you built the toolchain in the Build Directory, you will find
+            the toolchain environment script in the
+            <filename>tmp</filename> directory.
+            If you installed the toolchain by hand, the environment setup
+            script is located in <filename>opt/poky/&DISTRO;</filename>.
+        </para>
+
+        <para>
+            After sourcing the environment script, use the
+            <filename>runqemu-extract-sdk</filename> command and provide the
+            filesystem image.
+        </para>
+
+        <para>
+            Following is an example.
+            The second command sets up the environment.
+            In this case, the setup script is located in the
+            <filename>/opt/poky/&DISTRO;</filename> directory.
+            The third command extracts the root filesystem from a previously
+            built filesystem that is located in the
+            <filename>~/Downloads</filename> directory.
+            Furthermore, this command extracts the root filesystem into the
+            <filename>$HOME/qemux86-sato</filename> directory:
+            <literallayout class='monospaced'>
+     $ cd ~
+     $ source /opt/poky/&DISTRO;/environment-setup-i586-poky-linux
+     $ runqemu-extract-sdk \
+        ~Downloads/core-image-sato-sdk-qemux86-2011091411831.rootfs.tar.bz2 \
+        $HOME/qemux86-sato
+            </literallayout>
+            You could now point to the target sysroot at
+            <filename>$HOME/qemux86-sato</filename>.
+        </para>
+    </section>
+</section>
+
+<section id='optionally-building-a-toolchain-installer'>
+    <title>Optionally Building a Toolchain Installer</title>
+
+    <para>
+        As an alternative to locating and downloading a toolchain installer,
+        you can build the toolchain installer one of two ways if you have a
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+        <itemizedlist>
+            <listitem><para>Use <filename>bitbake meta-toolchain</filename>.
+                This method requires you to still install the target
+                sysroot by installing and extracting it separately.
+                For information on how to install the sysroot, see the
+                "<link linkend='extracting-the-root-filesystem'>Extracting the Root Filesystem</link>"
+                section.</para></listitem>
+            <listitem><para>Use
+                <filename>bitbake image -c populate_sdk</filename>.
+                This method has significant advantages over the previous method
+                because it results in a toolchain installer that contains the
+                sysroot that matches your target root filesystem.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+         Remember, before using any BitBake command, you
+         must source the build environment setup script
+         (i.e.
+         <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+         or
+         <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>)
+         located in the Source Directory and you must make sure your
+         <filename>conf/local.conf</filename> variables are correct.
+         In particular, you need to be sure the
+         <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+         variable matches the architecture for which you are building and that
+         the
+         <ulink url='&YOCTO_DOCS_REF_URL;#var-SDKMACHINE'><filename>SDKMACHINE</filename></ulink>
+         variable is correctly set if you are building a toolchain designed to
+         run on an architecture that differs from your current development host
+         machine (i.e. the build machine).
+    </para>
+
+    <para>
+        When the BitBake command completes, the toolchain installer will be in
+        <filename>tmp/deploy/sdk</filename> in the Build Directory.
+        <note>
+            By default, this toolchain does not build static binaries.
+            If you want to use the toolchain to build these types of libraries,
+            you need to be sure your image has the appropriate static 
+            development libraries.
+            Use the 
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
+            variable inside your <filename>local.conf</filename> file to
+            install the appropriate library packages.
+            Following is an example using <filename>eglibc</filename> static 
+            development libraries:
+            <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = " eglibc-staticdev"
+            </literallayout>
+        </note>
+    </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/adt-manual/adt-style.css b/documentation/adt-manual/adt-style.css
new file mode 100644
index 0000000000..3b098aa493
--- /dev/null
+++ b/documentation/adt-manual/adt-style.css
@@ -0,0 +1,979 @@
+/* 
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+   
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+ 
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("figures/adt-title.png");
+  background-position: left top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 0px;
+  text-align: right;
+  width: 740px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+  
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+} 
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption, 
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;  
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+  
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2; 
+}
+
+.glossary dl dt, 
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title, 
+div.colophon .title, 
+div.chapter .titlepage .title,
+div.article .titlepage .title 
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/yocto-project-bw.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2; 
+   color: #333;   
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;   
+}
+
+.tip a,
+.note a {
+   color: #333;   
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
+
diff --git a/documentation/adt-manual/figures/adt-title.png b/documentation/adt-manual/figures/adt-title.png
new file mode 100644
index 0000000000..6e71e41f1a
--- /dev/null
+++ b/documentation/adt-manual/figures/adt-title.png
diff --git a/documentation/bsp-guide/bsp-guide-customization.xsl b/documentation/bsp-guide/bsp-guide-customization.xsl
new file mode 100644
index 0000000000..5560289ee8
--- /dev/null
+++ b/documentation/bsp-guide/bsp-guide-customization.xsl
@@ -0,0 +1,10 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+  
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+  <xsl:param name="html.stylesheet" select="'bsp-style.css'" />
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl b/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl
new file mode 100644
index 0000000000..1c80bee1cf
--- /dev/null
+++ b/documentation/bsp-guide/bsp-guide-eclipse-customization.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+        xmlns="http://www.w3.org/1999/xhtml"
+        xmlns:fo="http://www.w3.org/1999/XSL/Format"
+        version="1.0">
+
+  <xsl:import
+          href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="chunk.quietly" select="1"/>
+  <xsl:param name="chunk.first.sections" select="1"/>
+  <xsl:param name="chunk.section.depth" select="10"/>
+  <xsl:param name="use.id.as.filename" select="1"/>
+  <xsl:param name="ulink.target" select="'_self'" />
+  <xsl:param name="base.dir" select="'html/bsp-guide/'"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/bsp-guide/bsp-guide.xml b/documentation/bsp-guide/bsp-guide.xml
new file mode 100644
index 0000000000..86b16d1226
--- /dev/null
+++ b/documentation/bsp-guide/bsp-guide.xml
@@ -0,0 +1,118 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='bsp-guide' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='figures/bsp-title.png'
+                    format='SVG'
+                    align='center' scalefit='1' width='100%'/>
+            </imageobject>
+        </mediaobject>
+
+        <title>
+            Yocto Project Board Support Package Developer's Guide
+        </title>
+
+        <authorgroup>
+            <author>
+                <firstname>Tom</firstname> <surname>Zanussi</surname>
+                <affiliation>
+                    <orgname>Intel Corporation</orgname>
+                </affiliation>
+                <email>tom.zanussi@intel.com</email>
+            </author>
+            <author>
+                <firstname>Richard</firstname> <surname>Purdie</surname>
+                <affiliation>
+                    <orgname>Linux Foundation</orgname>
+                </affiliation>
+                <email>richard.purdie@linuxfoundation.org</email>
+            </author>
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>0.9</revnumber>
+                <date>24 November 2010</date>
+                <revremark>The initial document draft released with the Yocto Project 0.9 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.0</revnumber>
+                <date>6 April 2011</date>
+                <revremark>Released with the Yocto Project 1.0 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.0.1</revnumber>
+                <date>23 May 2011</date>
+                <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.1</revnumber>
+                <date>6 October 2011</date>
+                <revremark>Released with the Yocto Project 1.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.2</revnumber>
+                <date>April 2012</date>
+                <revremark>Released with the Yocto Project 1.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.3</revnumber>
+                <date>October 2012</date>
+                <revremark>Released with the Yocto Project 1.3 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>April 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5</revnumber>
+                <date>October 2013</date>
+                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5.1</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
+            </revision>
+        </revhistory>
+
+    <copyright>
+      <year>&COPYRIGHT_YEAR;</year>
+      <holder>Linux Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this document under
+        the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-nc-sa/2.0/uk/">Creative Commons Attribution-Non-Commercial-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
+      </para>
+      <note>
+          For the latest version of this manual associated with this
+          Yocto Project release, see the
+          <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>
+          from the Yocto Project website.
+      </note>
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="bsp.xml"/>
+
+<!--    <index id='index'>
+      <title>Index</title>
+    </index>
+-->
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/bsp-guide/bsp-style.css b/documentation/bsp-guide/bsp-style.css
new file mode 100644
index 0000000000..4a1a45e727
--- /dev/null
+++ b/documentation/bsp-guide/bsp-style.css
@@ -0,0 +1,980 @@
+/* 
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+   
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+ 
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("figures/bsp-title.png");
+  background-position: left top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 0px;
+  text-align: right;
+  width: 740px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+  
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+} 
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption, 
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;  
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+  
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2; 
+}
+
+.glossary dl dt, 
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title, 
+div.colophon .title, 
+div.chapter .titlepage .title {
+  background-image: url("images/title-bg.png");
+  background-position: bottom;
+  background-repeat: repeat-x;
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("poky-ref-manual.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2; 
+   color: #333;   
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;   
+}
+
+.tip a,
+.note a {
+   color: #333;   
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
+
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml
new file mode 100644
index 0000000000..c85e7e0883
--- /dev/null
+++ b/documentation/bsp-guide/bsp.xml
@@ -0,0 +1,1480 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='bsp'>
+
+        <title>Board Support Packages (BSP) - Developer's Guide</title>
+
+        <para>
+            A Board Support Package (BSP) is a collection of information that
+            defines how to support a particular hardware device, set of devices, or
+            hardware platform.
+            The BSP includes information about the hardware features
+            present on the device and kernel configuration information along with any
+            additional hardware drivers required.
+            The BSP also lists any additional software
+            components required in addition to a generic Linux software stack for both
+            essential and optional platform features.
+        </para>
+
+        <para>
+            This guide presents information about BSP Layers, defines a structure for components
+            so that BSPs follow a commonly understood layout, discusses how to customize
+            a recipe for a BSP, addresses BSP licensing, and provides information that
+            shows you how to create and manage a
+            <link linkend='bsp-layers'>BSP Layer</link> using two Yocto Project
+            <link linkend='using-the-yocto-projects-bsp-tools'>BSP Tools</link>.
+        </para>
+
+        <section id='bsp-layers'>
+            <title>BSP Layers</title>
+
+            <para>
+                The BSP consists of a file structure inside a base directory.
+                Collectively, you can think of the base directory and the file structure
+                as a BSP Layer.
+                Although not a strict requirement, layers in the Yocto Project use the
+                following well established naming convention:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;
+                </literallayout>
+                The string "meta-" is prepended to the machine or platform name, which is
+                "bsp_name" in the above form.
+            </para>
+
+            <para>
+                The layer's base directory (<filename>meta-&lt;bsp_name&gt;</filename>) is the root
+                of the BSP Layer.
+                This root is what you add to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
+                variable in the <filename>conf/bblayers.conf</filename> file found in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                Adding the root allows the OpenEmbedded build system to recognize the BSP
+                definition and from it build an image.
+                Here is an example:
+                <literallayout class='monospaced'>
+     BBLAYERS ?= " \
+       /usr/local/src/yocto/meta \
+       /usr/local/src/yocto/meta-yocto \
+       /usr/local/src/yocto/meta-yocto-bsp \
+       /usr/local/src/yocto/meta-mylayer \
+       "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+       /usr/local/src/yocto/meta \
+       /usr/local/src/yocto/meta-yocto \
+       "
+                </literallayout>
+            </para>
+
+            <para>
+                Some BSPs require additional layers on
+                top of the BSP's root layer in order to be functional.
+                For these cases, you also need to add those layers to the
+                <filename>BBLAYERS</filename> variable in order to build the BSP.
+                You must also specify in the "Dependencies" section of the BSP's
+                <filename>README</filename> file any requirements for additional
+                layers and, preferably, any
+                build instructions that might be contained elsewhere
+                in the <filename>README</filename> file.
+            </para>
+
+            <para>
+                Some layers function as a layer to hold other BSP layers.
+                An example of this type of layer is the <filename>meta-intel</filename> layer.
+                The <filename>meta-intel</filename> layer contains over 10 individual BSP layers.
+            </para>
+
+            <para>
+                For more detailed information on layers, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+                section of the Yocto Project Development Manual.
+            </para>
+        </section>
+
+
+        <section id="bsp-filelayout">
+            <title>Example Filesystem Layout</title>
+
+            <para>
+                Providing a common form allows end-users to understand and become familiar
+                with the layout.
+                A common format also encourages standardization of software support of hardware.
+            </para>
+
+            <para>
+                The proposed form does have elements that are specific to the
+                OpenEmbedded build system.
+                It is intended that this information can be
+                used by other build systems besides the OpenEmbedded build system
+                and that it will be simple
+                to extract information and convert it to other formats if required.
+                The OpenEmbedded build system, through its standard layers mechanism, can directly
+                accept the format described as a layer.
+                The BSP captures all
+                the hardware-specific details in one place in a standard format, which is
+                useful for any person wishing to use the hardware platform regardless of
+                the build system they are using.
+            </para>
+
+            <para>
+                The BSP specification does not include a build system or other tools -
+                it is concerned with the hardware-specific components only.
+                At the end-distribution point, you can ship the BSP combined with a build system
+                and other tools.
+                However, it is important to maintain the distinction that these
+                are separate components that happen to be combined in certain end products.
+            </para>
+
+            <para>
+                Before looking at the common form for the file structure inside a BSP Layer,
+                you should be aware that some requirements do exist in order for a BSP to
+                be considered compliant with the Yocto Project.
+                For that list of requirements, see the
+                "<link linkend='released-bsp-requirements'>Released BSP Requirements</link>"
+                section.
+            </para>
+
+            <para>
+                Below is the common form for the file structure inside a BSP Layer.
+                While you can use this basic form for the standard, realize that the actual structures
+                for specific BSPs could differ.
+
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/
+     meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
+     meta-&lt;bsp_name&gt;/README
+     meta-&lt;bsp_name&gt;/README.sources
+     meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
+     meta-&lt;bsp_name&gt;/conf/layer.conf
+     meta-&lt;bsp_name&gt;/conf/machine/*.conf
+     meta-&lt;bsp_name&gt;/recipes-bsp/*
+     meta-&lt;bsp_name&gt;/recipes-core/*
+     meta-&lt;bsp_name&gt;/recipes-graphics/*
+     meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_&lt;kernel_rev&gt;.bbappend
+                </literallayout>
+            </para>
+
+            <para>
+                Below is an example of the Crown Bay BSP:
+
+                <literallayout class='monospaced'>
+     meta-crownbay/COPYING.MIT
+     meta-crownbay/README
+     meta-crownbay/README.sources
+     meta-crownbay/binary/
+     meta-crownbay/conf/
+     meta-crownbay/conf/layer.conf
+     meta-crownbay/conf/machine/
+     meta-crownbay/conf/machine/crownbay.conf
+     meta-crownbay/conf/machine/crownbay-noemgd.conf
+     meta-crownbay/recipes-bsp/
+     meta-crownbay/recipes-bsp/formfactor/
+     meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
+     meta-crownbay/recipes-bsp/formfactor/formfactor/
+     meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/
+     meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
+     meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/
+     meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
+     meta-crownbay/recipes-graphics/
+     meta-crownbay/recipes-graphics/xorg-xserver/
+     meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
+     meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/
+     meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/
+     meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
+     meta-crownbay/recipes-kernel/
+     meta-crownbay/recipes-kernel/linux/
+     meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend
+     meta-crownbay/recipes-kernel/linux/linux-yocto_3.8.bbappend
+     meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend
+     meta-crownbay/recipes-kernel/linux/linux-yocto-dev.bbappend
+     meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.4.bbappend
+     meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.8.bbappend
+     meta-crownbay/recipes-kernel/linux/linux-yocto-rt_3.10.bbappend
+                </literallayout>
+            </para>
+
+            <para>
+                The following sections describe each part of the proposed BSP format.
+            </para>
+
+            <section id="bsp-filelayout-license">
+            <title>License Files</title>
+
+            <para>
+                You can find these files in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/&lt;bsp_license_file&gt;
+                </literallayout>
+            </para>
+
+            <para>
+                These optional files satisfy licensing requirements for the BSP.
+                The type or types of files here can vary depending on the licensing requirements.
+                For example, in the Crown Bay BSP all licensing requirements are handled with the
+                <filename>COPYING.MIT</filename> file.
+            </para>
+
+            <para>
+                Licensing files can be MIT, BSD, GPLv*, and so forth.
+                These files are recommended for the BSP but are optional and totally up to the BSP developer.
+            </para>
+            </section>
+
+            <section id="bsp-filelayout-readme">
+            <title>README File</title>
+            <para>
+                You can find this file in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/README
+                </literallayout>
+            </para>
+
+            <para>
+                This file provides information on how to boot the live images that are optionally
+                included in the <filename>binary/</filename> directory.
+                The <filename>README</filename> file also provides special information needed for
+                building the image.
+            </para>
+
+            <para>
+                At a minimum, the <filename>README</filename> file must
+                contain a list of dependencies, such as the names of
+                any other layers on which the BSP depends and the name of
+                the BSP maintainer with his or her contact information.
+            </para>
+            </section>
+
+            <section id="bsp-filelayout-readme-sources">
+            <title>README.sources File</title>
+            <para>
+                You can find this file in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/README.sources
+                </literallayout>
+            </para>
+
+            <para>
+                This file provides information on where to locate the BSP source files.
+                For example, information provides where to find the sources that comprise
+                the images shipped with the BSP.
+                Information is also included to help you find the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                used to generate the images that ship with the BSP.
+            </para>
+            </section>
+
+            <section id="bsp-filelayout-binary">
+            <title>Pre-built User Binaries</title>
+            <para>
+                You can find these files in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/binary/&lt;bootable_images&gt;
+                </literallayout>
+            </para>
+
+            <para>
+                This optional area contains useful pre-built kernels and user-space filesystem
+                images appropriate to the target system.
+                This directory typically contains graphical (e.g. Sato) and minimal live images
+                when the BSP tarball has been created and made available in the
+                <ulink url='&YOCTO_HOME_URL;'>Yocto Project</ulink> website.
+                You can use these kernels and images to get a system running and quickly get started
+                on development tasks.
+            </para>
+
+            <para>
+                The exact types of binaries present are highly hardware-dependent.
+                However, a README file should be present in the BSP Layer that explains how to use
+                the kernels and images with the target hardware.
+                If pre-built binaries are present, source code to meet licensing requirements must also
+                exist in some form.
+            </para>
+            </section>
+
+            <section id='bsp-filelayout-layer'>
+            <title>Layer Configuration File</title>
+            <para>
+                You can find this file in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/conf/layer.conf
+                </literallayout>
+            </para>
+
+            <para>
+                The <filename>conf/layer.conf</filename> file identifies the file structure as a
+                layer, identifies the
+                contents of the layer, and contains information about how the build
+                system should use it.
+                Generally, a standard boilerplate file such as the following works.
+                In the following example, you would replace "<filename>bsp</filename>" and
+                "<filename>_bsp</filename>" with the actual name
+                of the BSP (i.e. <filename>&lt;bsp_name&gt;</filename> from the example template).
+            </para>
+
+            <para>
+               <literallayout class='monospaced'>
+     # We have a conf and classes directory, add to BBPATH
+     BBPATH .= ":${LAYERDIR}"
+
+     # We have a recipes directory, add to BBFILES
+     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+             ${LAYERDIR}/recipes-*/*/*.bbappend"
+
+     BBFILE_COLLECTIONS += "bsp"
+     BBFILE_PATTERN_bsp = "^${LAYERDIR}/"
+     BBFILE_PRIORITY_bsp = "6"
+                </literallayout>
+            </para>
+
+            <para>
+                To illustrate the string substitutions, here are the corresponding statements
+                from the Crown Bay <filename>conf/layer.conf</filename> file:
+               <literallayout class='monospaced'>
+     BBFILE_COLLECTIONS += "crownbay"
+     BBFILE_PATTERN_crownbay = "^${LAYERDIR}/"
+     BBFILE_PRIORITY_crownbay = "6"
+                </literallayout>
+            </para>
+
+            <para>
+                This file simply makes BitBake aware of the recipes and configuration directories.
+                The file must exist so that the OpenEmbedded build system can recognize the BSP.
+            </para>
+            </section>
+
+            <section id="bsp-filelayout-machine">
+            <title>Hardware Configuration Options</title>
+            <para>
+                You can find these files in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/conf/machine/*.conf
+                </literallayout>
+            </para>
+
+            <para>
+                The machine files bind together all the information contained elsewhere
+                in the BSP into a format that the build system can understand.
+                If the BSP supports multiple machines, multiple machine configuration files
+                can be present.
+                These filenames correspond to the values to which users have set the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink> variable.
+            </para>
+
+            <para>
+                These files define things such as the kernel package to use
+                (<ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink>
+                of virtual/kernel), the hardware drivers to
+                include in different types of images, any special software components
+                that are needed, any bootloader information, and also any special image
+                format requirements.
+            </para>
+
+            <para>
+                Each BSP Layer requires at least one machine file.
+                However, you can supply more than one file.
+            </para>
+
+            <para>
+                This <filename>crownbay.conf</filename> file could also include
+                a hardware "tuning" file that is commonly used to
+                define the package architecture and specify
+                optimization flags, which are carefully chosen to give best
+                performance on a given processor.
+            </para>
+
+            <para>
+                Tuning files are found in the <filename>meta/conf/machine/include</filename>
+                directory within the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                For example, the <filename>ia32-base.inc</filename> file resides in the
+                <filename>meta/conf/machine/include</filename> directory.
+            </para>
+
+            <para>
+                To use an include file, you simply include them in the machine configuration file.
+                For example, the Crown Bay BSP <filename>crownbay.conf</filename> contains the
+                following statements:
+                <literallayout class='monospaced'>
+     require conf/machine/include/tune-atom.inc
+     require conf/machine/include/ia32-base.inc
+     require conf/machine/include/meta-intel.inc
+     require conf/machine/include/meta-intel-emgd.inc
+                </literallayout>
+            </para>
+            </section>
+
+            <section id='bsp-filelayout-misc-recipes'>
+            <title>Miscellaneous BSP-Specific Recipe Files</title>
+            <para>
+                You can find these files in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/recipes-bsp/*
+                </literallayout>
+            </para>
+
+            <para>
+                This optional directory contains miscellaneous recipe files for the BSP.
+                Most notably would be the formfactor files.
+                For example, in the Crown Bay BSP there is the
+                <filename>formfactor_0.0.bbappend</filename> file, which is an
+                append file used to augment the recipe that starts the build.
+                Furthermore, there are machine-specific settings used during the
+                build that are defined by the <filename>machconfig</filename> file.
+                In the Crown Bay example, two <filename>machconfig</filename> files
+                exist: one that supports the Intel® Embedded Media and Graphics
+                Driver (Intel® EMGD) and one that does not:
+                <literallayout class='monospaced'>
+     meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay/machconfig
+     meta-crownbay/recipes-bsp/formfactor/formfactor/crownbay-noemgd/machconfig
+     meta-crownbay/recipes-bsp/formfactor/formfactor_0.0.bbappend
+                </literallayout>
+            </para>
+
+            <note><para>
+                If a BSP does not have a formfactor entry, defaults are established according to
+                the formfactor configuration file that is installed by the main
+                formfactor recipe
+                <filename>meta/recipes-bsp/formfactor/formfactor_0.0.bb</filename>,
+                which is found in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            </para></note>
+            </section>
+
+            <section id='bsp-filelayout-recipes-graphics'>
+            <title>Display Support Files</title>
+            <para>
+                You can find these files in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/recipes-graphics/*
+                </literallayout>
+            </para>
+
+            <para>
+                This optional directory contains recipes for the BSP if it has
+                special requirements for graphics support.
+                All files that are needed for the BSP to support a display are kept here.
+                For example, the Crown Bay BSP's <filename>xorg.conf</filename> file
+                detects the graphics support needed (i.e. the Intel® Embedded Media
+                Graphics Driver (EMGD) or the Video Electronics Standards Association
+                (VESA) graphics):
+                <literallayout class='monospaced'>
+     meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config_0.1.bbappend
+     meta-crownbay/recipes-graphics/xorg-xserver/xserver-xf86-config/crownbay/xorg.conf
+                </literallayout>
+            </para>
+            </section>
+
+            <section id='bsp-filelayout-kernel'>
+            <title>Linux Kernel Configuration</title>
+            <para>
+                You can find these files in the BSP Layer at:
+                <literallayout class='monospaced'>
+     meta-&lt;bsp_name&gt;/recipes-kernel/linux/linux-yocto_*.bbappend
+                </literallayout>
+            </para>
+
+            <para>
+                These files append your specific changes to the main kernel recipe you are using.
+            </para>
+            <para>
+                For your BSP, you typically want to use an existing Yocto Project kernel recipe found in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                at <filename>meta/recipes-kernel/linux</filename>.
+                You can append your specific changes to the kernel recipe by using a
+                similarly named append file, which is located in the BSP Layer (e.g.
+                the <filename>meta-&lt;bsp_name&gt;/recipes-kernel/linux</filename> directory).
+            </para>
+            <para>
+                Suppose you are using the <filename>linux-yocto_3.10.bb</filename> recipe to build
+                the kernel.
+                In other words, you have selected the kernel in your
+                <filename>&lt;bsp_name&gt;.conf</filename> file by adding these types
+                of statements:
+                <literallayout class='monospaced'>
+     PREFERRED_PROVIDER_virtual/kernel ?= "linux-yocto"
+     PREFERRED_VERSION_linux-yocto ?= "3.10%"
+                </literallayout>
+                <note>
+                    When the preferred provider is assumed by default, the
+                    <filename>PREFERRED_PROVIDER</filename> statement does not appear in the
+                    <filename>&lt;bsp_name&gt;.conf</filename> file.
+                </note>
+                You would use the <filename>linux-yocto_3.10.bbappend</filename> file to append
+                specific BSP settings to the kernel, thus configuring the kernel for your particular BSP.
+            </para>
+            <para>
+                As an example, look at the existing Crown Bay BSP.
+                The append file used is:
+                <literallayout class='monospaced'>
+     meta-crownbay/recipes-kernel/linux/linux-yocto_3.10.bbappend
+                </literallayout>
+                The following listing shows the file.
+                Be aware that the actual commit ID strings in this example listing might be different
+                than the actual strings in the file from the <filename>meta-intel</filename>
+                Git source repository.
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+     COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
+     KMACHINE_crownbay-noemgd = "crownbay"
+     KBRANCH_crownbay-noemgd = "standard/crownbay"
+     KERNEL_FEATURES_append_crownbay-noemgd = " cfg/vesafb"
+
+     LINUX_VERSION = "3.10.11"
+
+     SRCREV_meta_crownbay-noemgd = "285f93bf942e8f6fa678ffc6cc53696ed5400718"
+     SRCREV_machine_crownbay-noemgd = "702040ac7c7ec66a29b4d147665ccdd0ff015577"
+                </literallayout>
+                This append file contains statements used to support the Crown Bay BSP.
+                The file defines <filename>crownbay</filename> as the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>
+                and uses the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink> variable to
+                ensure the machine name used by the OpenEmbedded build system maps to the
+                machine name used by the Linux Yocto kernel.
+                The file also uses the optional
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'><filename>KBRANCH</filename></ulink> variable
+                to ensure the build process uses the <filename>standard/crownbay</filename>
+                kernel branch.
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
+                variable enables features specific to the kernel.
+                Finally, the append file points to specific commits in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> Git
+                repository and the <filename>meta</filename> Git repository branches to identify the
+                exact kernel needed to build the Crown Bay BSP.
+            </para>
+
+            <para>
+                One thing missing in this particular BSP, which you will typically need when
+                developing a BSP, is the kernel configuration file (<filename>.config</filename>) for your BSP.
+                When developing a BSP, you probably have a kernel configuration file or a set of kernel
+                configuration files that, when taken together, define the kernel configuration for your BSP.
+                You can accomplish this definition by putting the configurations in a file or a set of files
+                inside a directory located at the same level as your kernel's append file and having the same
+                name as the kernel's main recipe file.
+                With all these conditions met, simply reference those files in a
+                <filename>SRC_URI</filename> statement in the append file.
+            </para>
+
+            <para>
+                For example, suppose you had some configuration options in a file called
+                <filename>network_configs.cfg</filename>.
+                You can place that file inside a directory named <filename>/linux-yocto</filename> and then add
+                a <filename>SRC_URI</filename> statement such as the following to the append file.
+                When the OpenEmbedded build system builds the kernel, the configuration options are
+                picked up and applied.
+                <literallayout class='monospaced'>
+     SRC_URI += "file://network_configs.cfg"
+                </literallayout>
+            </para>
+
+            <para>
+                To group related configurations into multiple files, you perform a similar procedure.
+                Here is an example that groups separate configurations specifically for Ethernet and graphics
+                into their own files and adds the configurations
+                by using a <filename>SRC_URI</filename> statement like the following in your append file:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://myconfig.cfg \
+            file://eth.cfg \
+            file://gfx.cfg"
+                </literallayout>
+            </para>
+
+            <para>
+                The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                variable is in boilerplate form in the
+                previous example in order to make it easy to do that.
+                This variable must be in your layer or BitBake will not find the patches or
+                configurations even if you have them in your <filename>SRC_URI</filename>.
+                The <filename>FILESEXTRAPATHS</filename> variable enables the build process to
+                find those configuration files.
+            </para>
+
+            <note>
+                <para>
+                    Other methods exist to accomplish grouping and defining configuration options.
+                    For example, if you are working with a local clone of the kernel repository,
+                    you could checkout the kernel's <filename>meta</filename> branch, make your changes,
+                    and then push the changes to the local bare clone of the kernel.
+                    The result is that you directly add configuration options to the
+                    <filename>meta</filename> branch for your BSP.
+                    The configuration options will likely end up in that location anyway if the BSP gets
+                    added to the Yocto Project.
+                </para>
+
+                <para>
+                    In general, however, the Yocto Project maintainers take care of moving the
+                    <filename>SRC_URI</filename>-specified
+                    configuration options to the kernel's <filename>meta</filename> branch.
+                    Not only is it easier for BSP developers to not have to worry about putting those
+                   configurations in the branch, but having the maintainers do it allows them to apply
+                    'global' knowledge about the kinds of common configuration options multiple BSPs in
+                    the tree are typically using.
+                    This allows for promotion of common configurations into common features.
+                </para>
+            </note>
+            </section>
+        </section>
+
+        <section id='requirements-and-recommendations-for-released-bsps'>
+            <title>Requirements and Recommendations for Released BSPs</title>
+
+            <para>
+                Certain requirements exist for a released BSP to be considered
+                compliant with the Yocto Project.
+                Additionally, recommendations also exist.
+                This section describes the requirements and recommendations for
+                released BSPs.
+            </para>
+
+            <section id='released-bsp-requirements'>
+                <title>Released BSP Requirements</title>
+
+                <para>
+                    Before looking at BSP requirements, you should consider the following:
+                    <itemizedlist>
+                        <listitem><para>The requirements here assume the BSP layer is a well-formed, "legal"
+                            layer that can be added to the Yocto Project.
+                            For guidelines on creating a layer that meets these base requirements, see the
+                            "<link linkend='bsp-layers'>BSP Layers</link>" and the
+                            "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding
+                            and Creating Layers"</ulink> in the Yocto Project Development Manual.</para></listitem>
+                        <listitem><para>The requirements in this section apply regardless of how you
+                            ultimately package a BSP.
+                            You should consult the packaging and distribution guidelines for your
+                            specific release process.
+                            For an example of packaging and distribution requirements, see the
+                            "<ulink url='https://wiki.yoctoproject.org/wiki/Third_Party_BSP_Release_Process'>Third Party BSP Release Process</ulink>"
+                            wiki page.</para></listitem>
+                        <listitem><para>The requirements for the BSP as it is made available to a developer
+                            are completely independent of the released form of the BSP.
+                            For example, the BSP Metadata can be contained within a Git repository
+                            and could have a directory structure completely different from what appears
+                            in the officially released BSP layer.</para></listitem>
+                        <listitem><para>It is not required that specific packages or package
+                            modifications exist in the BSP layer, beyond the requirements for general
+                            compliance with the Yocto Project.
+                            For example, no requirement exists dictating that a specific kernel or
+                            kernel version be used in a given BSP.</para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    Following are the requirements for a released BSP that conforms to the
+                    Yocto Project:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Layer Name:</emphasis>
+                            The BSP must have a layer name that follows the Yocto
+                            Project standards.
+                            For information on BSP layer names, see the
+                            "<link linkend='bsp-layers'>BSP Layers</link>" section.
+                            </para></listitem>
+                        <listitem><para><emphasis>File System Layout:</emphasis>
+                            When possible, use the same directory names in your
+                            BSP layer as listed in the <filename>recipes.txt</filename> file.
+                            In particular, you should place recipes
+                            (<filename>.bb</filename> files) and recipe
+                            modifications (<filename>.bbappend</filename> files) into
+                            <filename>recipes-*</filename> subdirectories by functional area
+                            as outlined in <filename>recipes.txt</filename>.
+                            If you cannot find a category in <filename>recipes.txt</filename>
+                            to fit a particular recipe, you can make up your own
+                            <filename>recipes-*</filename> subdirectory.
+                            You can find <filename>recipes.txt</filename> in the
+                            <filename>meta</filename> directory of the
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
+                            or in the OpenEmbedded Core Layer
+                            (<filename>openembedded-core</filename>) found at
+                            <ulink url='http://git.openembedded.org/openembedded-core/tree/meta'></ulink>.
+                            </para>
+                            <para>Within any particular <filename>recipes-*</filename> category, the layout
+                            should match what is found in the OpenEmbedded Core
+                            Git repository (<filename>openembedded-core</filename>)
+                            or the Source Directory (<filename>poky</filename>).
+                            In other words, make sure you place related files in appropriately
+                            related <filename>recipes-*</filename> subdirectories specific to the
+                            recipe's function, or within a subdirectory containing a set of closely-related
+                            recipes.
+                            The recipes themselves should follow the general guidelines
+                            for recipes used in the Yocto Project found in the
+                            "<ulink url='https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide'>Yocto Recipe and Patch Style Guide</ulink>".
+                            </para></listitem>
+                        <listitem><para><emphasis>License File:</emphasis>
+                            You must include a license file in the
+                            <filename>meta-&lt;bsp_name&gt;</filename> directory.
+                            This license covers the BSP Metadata as a whole.
+                            You must specify which license to use since there is no
+                            default license if one is not specified.
+                            See the
+                            <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/COPYING.MIT'><filename>COPYING.MIT</filename></ulink>
+                            file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
+                            as an example.</para></listitem>
+                        <listitem><para><emphasis>README File:</emphasis>
+                            You must include a <filename>README</filename> file in the
+                            <filename>meta-&lt;bsp_name&gt;</filename> directory.
+                            See the
+                            <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README'><filename>README</filename></ulink>
+                            file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
+                            as an example.</para>
+                            <para>At a minimum, the <filename>README</filename> file should
+                            contain the following:
+                            <itemizedlist>
+                                <listitem><para>A brief description about the hardware the BSP
+                                    targets.</para></listitem>
+                                <listitem><para>A list of all the dependencies
+                                    on which a BSP layer depends.
+                                    These dependencies are typically a list of required layers needed
+                                    to build the BSP.
+                                    However, the dependencies should also contain information regarding
+                                    any other dependencies the BSP might have.</para></listitem>
+                                <listitem><para>Any required special licensing information.
+                                    For example, this information includes information on
+                                    special variables needed to satisfy a EULA,
+                                    or instructions on information needed to build or distribute
+                                    binaries built from the BSP Metadata.</para></listitem>
+                                <listitem><para>The name and contact information for the
+                                    BSP layer maintainer.
+                                    This is the person to whom patches and questions should
+                                    be sent.
+                                    For information on how to find the right person, see the
+                                    "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
+                                    section in the Yocto Project Development Manual.
+                                    </para></listitem>
+                                <listitem><para>Instructions on how to build the BSP using the BSP
+                                    layer.</para></listitem>
+                                <listitem><para>Instructions on how to boot the BSP build from
+                                    the BSP layer.</para></listitem>
+                                <listitem><para>Instructions on how to boot the binary images
+                                    contained in the <filename>/binary</filename> directory,
+                                    if present.</para></listitem>
+                                <listitem><para>Information on any known bugs or issues that users
+                                    should know about when either building or booting the BSP
+                                    binaries.</para></listitem>
+                            </itemizedlist></para></listitem>
+                        <listitem><para><emphasis>README.sources File:</emphasis>
+                            You must include a <filename>README.sources</filename> in the
+                            <filename>meta-&lt;bsp_name&gt;</filename> directory.
+                            This file specifies exactly where you can find the sources used to
+                            generate the binary images contained in the
+                            <filename>/binary</filename> directory, if present.
+                            See the
+                            <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-intel/tree/meta-fri2/README.sources'><filename>README.sources</filename></ulink>
+                            file for the Fish River Island 2 BSP in the <filename>meta-fri2</filename> BSP layer
+                            as an example.</para></listitem>
+                        <listitem><para><emphasis>Layer Configuration File:</emphasis>
+                            You must include a <filename>conf/layer.conf</filename> in the
+                            <filename>meta-&lt;bsp_name&gt;</filename> directory.
+                            This file identifies the <filename>meta-&lt;bsp_name&gt;</filename>
+                            BSP layer as a layer to the build system.</para></listitem>
+                        <listitem><para><emphasis>Machine Configuration File:</emphasis>
+                            You must include one or more <filename>conf/machine/&lt;bsp_name&gt;.conf</filename>
+                            files in the <filename>meta-&lt;bsp_name&gt;</filename> directory.
+                            These configuration files define machine targets that can be built
+                            using the BSP layer.
+                            Multiple machine configuration files define variations of machine
+                            configurations that are supported by the BSP.
+                            If a BSP supports multiple machine variations, you need to
+                            adequately describe each variation in the BSP
+                            <filename>README</filename> file.
+                            Do not use multiple machine configuration files to describe disparate
+                            hardware.
+                            If you do have very different targets, you should create separate
+                            BSP layers for each target.
+                            <note>It is completely possible for a developer to structure the
+                            working repository as a conglomeration of unrelated BSP
+                            files, and to possibly generate BSPs targeted for release
+                            from that directory using scripts or some other mechanism
+                            (e.g. <filename>meta-yocto-bsp</filename> layer).
+                            Such considerations are outside the scope of this document.</note>
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+
+            <section id='released-bsp-recommendations'>
+                <title>Released BSP Recommendations</title>
+
+                <para>
+                    Following are recommendations for a released BSP that conforms to the
+                    Yocto Project:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Bootable Images:</emphasis>
+                            BSP releases
+                            can contain one or more bootable images.
+                            Including bootable images allows users to easily try out the BSP
+                            on their own hardware.</para>
+                            <para>In some cases, it might not be convenient to include a
+                            bootable image.
+                            In this case, you might want to make two versions of the
+                            BSP available: one that contains binary images, and one
+                            that does not.
+                            The version that does not contain bootable images avoids
+                            unnecessary download times for users not interested in the images.
+                            </para>
+                            <para>If you need to distribute a BSP and include bootable images or build kernel and
+                            filesystems meant to allow users to boot the BSP for evaluation
+                            purposes, you should put the images and artifacts within a
+                            <filename>binary/</filename> subdirectory located in the
+                            <filename>meta-&lt;bsp_name&gt;</filename> directory.
+                            <note>If you do include a bootable image as part of the BSP and the image
+                            was built by software covered by the GPL or other open source licenses,
+                            it is your responsibility to understand
+                            and meet all licensing requirements, which could include distribution
+                            of source files.</note></para></listitem>
+                        <listitem><para><emphasis>Use a Yocto Linux Kernel:</emphasis>
+                            Kernel recipes in the BSP should be based on a Yocto Linux kernel.
+                            Basing your recipes on these kernels reduces the costs for maintaining
+                            the BSP and increases its scalability.
+                            See the <filename>Yocto Linux Kernel</filename> category in the
+                            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>Source Repositories</ulink>
+                            for these kernels.</para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+        </section>
+
+        <section id='customizing-a-recipe-for-a-bsp'>
+            <title>Customizing a Recipe for a BSP</title>
+
+            <para>
+               If you plan on customizing a recipe for a particular BSP, you need to do the
+               following:
+               <itemizedlist>
+                   <listitem><para>Create a <filename>.bbappend</filename>
+                       file for the modified recipe.
+                       For information on using append files, see the
+                       "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
+                       section in the Yocto Project Development Manual.
+                       </para></listitem>
+                   <listitem><para>
+                       Ensure your directory structure in the BSP layer
+                       that supports your machine is such that it can be found
+                       by the build system.
+                       See the example later in this section for more information.
+                       </para></listitem>
+                   <listitem><para>
+                       Put the append file in a directory whose name matches
+                       the machine's name and is located in an appropriate
+                       sub-directory inside the BSP layer (i.e.
+                       <filename>recipes-bsp</filename>, <filename>recipes-graphics</filename>,
+                       <filename>recipes-core</filename>, and so forth).
+                       </para></listitem>
+                   <listitem><para>Place the BSP-specific files in the directory named for
+                       your machine inside the BSP layer.
+                       </para></listitem>
+               </itemizedlist>
+           </para>
+
+           <para>
+               Following is a specific example to help you better understand the process.
+               Consider an example that customizes a recipe by adding
+               a BSP-specific configuration file named <filename>interfaces</filename> to the
+               <filename>init-ifupdown_1.0.bb</filename> recipe for machine "xyz".
+               Do the following:
+               <orderedlist>
+                   <listitem><para>Edit the <filename>init-ifupdown_1.0.bbappend</filename> file so that it
+                       contains the following:
+                       <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
+     PRINC := "${@int(PRINC) + 2}"
+                       </literallayout>
+                       The append file needs to be in the
+                       <filename>meta-xyz/recipes-core/init-ifupdown</filename> directory.
+                       </para></listitem>
+                   <listitem><para>Create and place the new <filename>interfaces</filename>
+                       configuration file in the BSP's layer here:
+                       <literallayout class='monospaced'>
+     meta-xyz/recipes-core/init-ifupdown/files/xyz/interfaces
+                       </literallayout>
+                       The
+                       <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                       variable in the append files extends the search path
+                       the build system uses to find files during the build.
+                       Consequently, for this example you need to have the
+                       <filename>files</filename> directory in the same location
+                       as your append file.</para></listitem>
+               </orderedlist>
+            </para>
+        </section>
+
+        <section id='bsp-licensing-considerations'>
+            <title>BSP Licensing Considerations</title>
+
+            <para>
+                In some cases, a BSP contains separately licensed Intellectual Property (IP)
+                for a component or components.
+                For these cases, you are required to accept the terms of a commercial or other
+                type of license that requires some kind of explicit End User License Agreement (EULA).
+                Once the license is accepted, the OpenEmbedded build system can then build and
+                include the corresponding component in the final BSP image.
+                If the BSP is available as a pre-built image, you can download the image after
+                agreeing to the license or EULA.
+            </para>
+
+            <para>
+                You could find that some separately licensed components that are essential
+                for normal operation of the system might not have an unencumbered (or free)
+                substitute.
+                Without these essential components, the system would be non-functional.
+                Then again, you might find that other licensed components that are simply
+                'good-to-have' or purely elective do have an unencumbered, free replacement
+                component that you can use rather than agreeing to the separately licensed component.
+                Even for components essential to the system, you might find an unencumbered component
+                that is not identical but will work as a less-capable version of the
+                licensed version in the BSP recipe.
+            </para>
+
+            <para>
+                For cases where you can substitute a free component and still
+                maintain the system's functionality, the "Downloads" page from the
+                <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
+                makes available de-featured BSPs
+                that are completely free of any IP encumbrances.
+                For these cases, you can use the substitution directly and
+                without any further licensing requirements.
+                If present, these fully de-featured BSPs are named appropriately
+                different as compared to the names of the respective
+                encumbered BSPs.
+                If available, these substitutions are your
+                simplest and most preferred options.
+                Use of these substitutions of course assumes the resulting functionality meets
+                system requirements.
+            </para>
+
+            <para>
+                If however, a non-encumbered version is unavailable or
+                it provides unsuitable functionality or quality, you can use an encumbered
+                version.
+            </para>
+
+            <para>
+                A couple different methods exist within the OpenEmbedded build system to
+                satisfy the licensing requirements for an encumbered BSP.
+                The following list describes them in order of preference:
+                <orderedlist>
+                    <listitem><para><emphasis>Use the <filename>LICENSE_FLAGS</filename> variable
+                        to define the recipes that have commercial or other types of
+                        specially-licensed packages:</emphasis>
+                        For each of those recipes, you can
+                        specify a matching license string in a
+                        <filename>local.conf</filename> variable named
+                        <filename>LICENSE_FLAGS_WHITELIST</filename>.
+                        Specifying the matching license string signifies that you agree to the license.
+                        Thus, the build system can build the corresponding recipe and include
+                        the component in the image.
+                        See the
+                        "<ulink url='&YOCTO_DOCS_REF_URL;#enabling-commercially-licensed-recipes'>Enabling
+                        Commercially Licensed Recipes</ulink>" section in the Yocto Project Reference
+                        Manual for details on how to use these variables.</para>
+                        <para>If you build as you normally would, without
+                        specifying any recipes in the
+                        <filename>LICENSE_FLAGS_WHITELIST</filename>, the build stops and
+                        provides you with the list of recipes that you have
+                        tried to include in the image that need entries in
+                        the <filename>LICENSE_FLAGS_WHITELIST</filename>.
+                        Once you enter the appropriate license flags into the whitelist,
+                        restart the build to continue where it left off.
+                        During the build, the prompt will not appear again
+                        since you have satisfied the requirement.</para>
+                        <para>Once the appropriate license flags are on the white list
+                        in the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, you
+                        can build the encumbered image with no change at all
+                        to the normal build process.</para></listitem>
+                    <listitem><para><emphasis>Get a pre-built version of the BSP:</emphasis>
+                        You can get this type of BSP by visiting the
+                        "Downloads" page of the
+                        <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
+                        You can download BSP tarballs that contain proprietary components
+                        after agreeing to the licensing
+                        requirements of each of the individually encumbered
+                        packages as part of the download process.
+                        Obtaining the BSP this way allows you to access an encumbered
+                        image immediately after agreeing to the
+                        click-through license agreements presented by the
+                        website.
+                        Note that if you want to build the image
+                        yourself using the recipes contained within the BSP
+                        tarball, you will still need to create an
+                        appropriate <filename>LICENSE_FLAGS_WHITELIST</filename> to match the
+                        encumbered recipes in the BSP.</para></listitem>
+                </orderedlist>
+            </para>
+
+            <note>
+                Pre-compiled images are bundled with
+                a time-limited kernel that runs for a
+                predetermined amount of time (10 days) before it forces
+                the system to reboot.
+                This limitation is meant to discourage direct redistribution
+                of the image.
+                You must eventually rebuild the image if you want to remove this restriction.
+            </note>
+        </section>
+
+        <section id='using-the-yocto-projects-bsp-tools'>
+            <title>Using the Yocto Project's BSP Tools</title>
+
+            <para>
+                The Yocto Project includes a couple of tools that enable
+                you to create a <link linkend='bsp-layers'>BSP layer</link>
+                from scratch and do basic configuration and maintenance
+                of the kernel without ever looking at a Metadata file.
+                These tools are <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename>,
+                respectively.
+            </para>
+
+            <para>
+                The following sections describe the common location and help features as well
+                as provide details for the
+                <filename>yocto-bsp</filename> and <filename>yocto-kernel</filename> tools.
+            </para>
+
+            <section id='common-features'>
+                <title>Common Features</title>
+
+                <para>
+                    Designed to have a  command interface somewhat like
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>, each
+                    tool is structured as a set of sub-commands under a
+                    top-level command.
+                    The top-level command (<filename>yocto-bsp</filename>
+                    or <filename>yocto-kernel</filename>) itself does
+                    nothing but invoke or provide help on the sub-commands
+                    it supports.
+                </para>
+
+                <para>
+                    Both tools reside in the <filename>scripts/</filename> subdirectory
+                    of the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                    Consequently, to use the scripts, you must <filename>source</filename> the
+                    environment just as you would when invoking a build:
+                    <literallayout class='monospaced'>
+     $ source oe-init-build-env [build_dir]
+                    </literallayout>
+                </para>
+
+                <para>
+                    The most immediately useful function is to get help on both tools.
+                    The built-in help system makes it easy to drill down at
+                    any time and view the syntax required for any specific command.
+                    Simply enter the name of the command with the <filename>help</filename>
+                    switch:
+                    <literallayout class='monospaced'>
+     $ yocto-bsp help
+     Usage:
+
+      Create a customized Yocto BSP layer.
+
+      usage: yocto-bsp [--version] [--help] COMMAND [ARGS]
+
+      Current 'yocto-bsp' commands are:
+         create            Create a new Yocto BSP
+         list              List available values for options and BSP properties
+
+      See 'yocto-bsp help COMMAND' for more information on a specific command.
+
+
+     Options:
+       --version    show program's version number and exit
+       -h, --help   show this help message and exit
+       -D, --debug  output debug information
+                    </literallayout>
+                </para>
+
+                <para>
+                    Similarly, entering just the name of a sub-command shows the detailed usage
+                    for that sub-command:
+                    <literallayout class='monospaced'>
+     $ yocto-bsp create
+
+     Usage:
+
+      Create a new Yocto BSP
+
+      usage: yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
+             [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
+
+      This command creates a Yocto BSP based on the specified parameters.
+      The new BSP will be a new Yocto BSP layer contained by default within
+      the top-level directory specified as 'meta-bsp-name'.  The -o option
+      can be used to place the BSP layer in a directory with a different
+      name and location.
+
+      ...
+                    </literallayout>
+                </para>
+
+                <para>
+                    For any sub-command, you can use the word "help" option just before the
+                    sub-command to get more extensive documentation:
+                    <literallayout class='monospaced'>
+     $ yocto-bsp help create
+
+     NAME
+         yocto-bsp create - Create a new Yocto BSP
+
+     SYNOPSIS
+         yocto-bsp create &lt;bsp-name&gt; &lt;karch&gt; [-o &lt;DIRNAME&gt; | --outdir &lt;DIRNAME&gt;]
+             [-i &lt;JSON PROPERTY FILE&gt; | --infile &lt;JSON PROPERTY_FILE&gt;]
+
+     DESCRIPTION
+         This command creates a Yocto BSP based on the specified
+         parameters.  The new BSP will be a new Yocto BSP layer contained
+         by default within the top-level directory specified as
+         'meta-bsp-name'.  The -o option can be used to place the BSP layer
+         in a directory with a different name and location.
+
+         The value of the 'karch' parameter determines the set of files
+         that will be generated for the BSP, along with the specific set of
+         'properties' that will be used to fill out the BSP-specific
+         portions of the BSP.  The possible values for the 'karch' parameter
+         can be listed via 'yocto-bsp list karch'.
+
+         ...
+                    </literallayout>
+                </para>
+
+                <para>
+                    Now that you know where these two commands reside and how to access information
+                    on them, you should find it relatively straightforward to discover the commands
+                    necessary to create a BSP and perform basic kernel maintenance on that BSP using
+                    the tools.
+                    <note>
+                        You can also use the <filename>yocto-layer</filename> tool to create
+                        a "generic" layer.
+                        For information on this tool, see the
+                        "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</ulink>"
+                        section in the Yocto Project Development Guide.
+                    </note>
+                </para>
+
+                <para>
+                    The next sections provide a concrete starting point to expand on a few points that
+                    might not be immediately obvious or that could use further explanation.
+                </para>
+            </section>
+
+
+            <section id='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
+                <title>Creating a new BSP Layer Using the yocto-bsp Script</title>
+
+                <para>
+                    The <filename>yocto-bsp</filename> script creates a new
+                    <link linkend='bsp-layers'>BSP layer</link> for any architecture supported
+                    by the Yocto Project, as well as QEMU versions of the same.
+                    The default mode of the script's operation is to prompt you for information needed
+                    to generate the BSP layer.
+                </para>
+
+                <para>
+                    For the current set of BSPs, the script prompts you for various important
+                    parameters such as:
+                    <itemizedlist>
+                        <listitem><para>The kernel to use</para></listitem>
+                        <listitem><para>The branch of that kernel to use (or re-use)</para></listitem>
+                        <listitem><para>Whether or not to use X, and if so, which drivers to use</para></listitem>
+                        <listitem><para>Whether to turn on SMP</para></listitem>
+                        <listitem><para>Whether the BSP has a keyboard</para></listitem>
+                        <listitem><para>Whether the BSP has a touchscreen</para></listitem>
+                        <listitem><para>Remaining configurable items associated with the BSP</para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    You use the <filename>yocto-bsp create</filename> sub-command to create
+                    a new BSP layer.
+                    This command requires you to specify a particular kernel architecture
+                    (<filename>karch</filename>) on which to base the BSP.
+                    Assuming you have sourced the environment, you can use the
+                    <filename>yocto-bsp list karch</filename> sub-command to list the
+                    architectures available for BSP creation as follows:
+                    <literallayout class='monospaced'>
+     $ yocto-bsp list karch
+     Architectures available:
+         powerpc
+         i386
+         x86_64
+         arm
+         qemu
+         mips
+                    </literallayout>
+                </para>
+
+                <para>
+                    The remainder of this section presents an example that uses
+                    <filename>myarm</filename> as the machine name and <filename>qemu</filename>
+                    as the machine architecture.
+                    Of the available architectures, <filename>qemu</filename> is the only architecture
+                    that causes the script to prompt you further for an actual architecture.
+                    In every other way, this architecture is representative of how creating a BSP for
+                    an actual machine would work.
+                    The reason the example uses this architecture is because it is an emulated architecture
+                    and can easily be followed without requiring actual hardware.
+                </para>
+
+                <para>
+                    As the <filename>yocto-bsp create</filename> command runs, default values for
+                    the prompts appear in brackets.
+                    Pressing enter without supplying anything on the command line or pressing enter
+                    with an invalid response causes the script to accept the default value.
+                    Once the script completes, the new <filename>meta-myarm</filename> BSP layer
+                    is created in the current working directory.
+                    This example assumes you have sourced the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                    and are currently in the top-level folder of the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+
+                <para>
+                    Following is the complete example:
+                    <literallayout class='monospaced'>
+     $ yocto-bsp create myarm qemu
+     Checking basic git connectivity...
+     Done.
+
+     Which qemu architecture would you like to use? [default: i386]
+             1) i386    (32-bit)
+             2) x86_64  (64-bit)
+             3) ARM     (32-bit)
+             4) PowerPC (32-bit)
+             5) MIPS    (32-bit)
+     3
+     Would you like to use the default (3.10) kernel? (y/n) [default: y] y
+     Do you need a new machine branch for this BSP (the alternative is to re-use an existing branch)? [y/n] [default: y]
+     Getting branches from remote repo git://git.yoctoproject.org/linux-yocto-3.10.git...
+     Please choose a machine branch to base your new BSP branch on: [default: standard/base]
+             1) standard/arm-versatile-926ejs
+             2) standard/base
+             3) standard/beagleboard
+             4) standard/ck
+             5) standard/crownbay
+             6) standard/edf
+             7) standard/emenlow
+             8) standard/fri2
+             9) standard/fsl-mpc8315e-rdb
+             10) standard/minnow
+             11) standard/mti-malta32
+             12) standard/mti-malta64
+             13) standard/qemuppc
+             14) standard/routerstationpro
+             15) standard/sys940x
+     1
+     Would you like SMP support? (y/n) [default: y]
+     Does your BSP have a touchscreen? (y/n) [default: n]
+     Does your BSP have a keyboard? (y/n) [default: y]
+
+     New qemu BSP created in meta-myarm
+                    </literallayout>
+                    Let's take a closer look at the example now:
+                    <orderedlist>
+                        <listitem><para>For the QEMU architecture,
+                            the script first prompts you for which emulated architecture to use.
+                            In the example, we use the ARM architecture.
+                            </para></listitem>
+                        <listitem><para>The script then prompts you for the kernel.
+                            The default 3.10 kernel is acceptable.
+                            So, the example accepts the default.
+                            If you enter 'n', the script prompts you to further enter the kernel
+                            you do want to use (e.g. 3.2, 3.2_preempt-rt, and so forth.).</para></listitem>
+                        <listitem><para>Next, the script asks whether you would like to have a new
+                            branch created especially for your BSP in the local
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Linux Yocto Kernel</ulink>
+                            Git repository .
+                            If not, then the script re-uses an existing branch.</para>
+                            <para>In this example, the default (or "yes") is accepted.
+                            Thus, a new branch is created for the BSP rather than using a common, shared
+                            branch.
+                            The new branch is the branch committed to for any patches you might later add.
+                            The reason a new branch is the default is that typically
+                            new BSPs do require BSP-specific patches.
+                            The tool thus assumes that most of time a new branch is required.
+                            </para></listitem>
+                        <listitem><para>Regardless of which choice you make in the previous step,
+                            you are now given the opportunity to select a particular machine branch on
+                            which to base your new BSP-specific machine branch
+                            (or to re-use if you had elected to not create a new branch).
+                            Because this example is generating an ARM-based BSP, the example
+                            uses <filename>#1</filename> at the prompt, which selects the ARM-versatile branch.
+                            </para></listitem>
+                        <listitem><para>The remainder of the prompts are routine.
+                            Defaults are accepted for each.</para></listitem>
+                        <listitem><para>By default, the script creates the new BSP Layer in the
+                            current working directory of the
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
+                            which is <filename>poky</filename> in this case.
+                            </para></listitem>
+                    </orderedlist>
+                </para>
+
+                <para>
+                    Once the BSP Layer is created, you must add it to your
+                    <filename>bblayers.conf</filename> file.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     BBLAYERS = ? " \
+        /usr/local/src/yocto/meta \
+        /usr/local/src/yocto/meta-yocto \
+        /usr/local/src/yocto/meta-yocto-bsp \
+        /usr/local/src/yocto/meta-myarm \
+        "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+        /usr/local/src/yocto/meta \
+        /usr/local/src/yocto/meta-yocto \
+        "
+                    </literallayout>
+                    Adding the layer to this file allows the build system to build the BSP and
+                    the <filename>yocto-kernel</filename> tool to be able to find the layer and
+                    other Metadata it needs on which to operate.
+                </para>
+            </section>
+
+            <section id='managing-kernel-patches-and-config-items-with-yocto-kernel'>
+                <title>Managing Kernel Patches and Config Items with yocto-kernel</title>
+
+                <para>
+                    Assuming you have created a <link linkend='bsp-layers'>BSP Layer</link> using
+                    <link linkend='creating-a-new-bsp-layer-using-the-yocto-bsp-script'>
+                    <filename>yocto-bsp</filename></link> and you added it to your
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
+                    variable in the <filename>bblayers.conf</filename> file, you can now use
+                    the <filename>yocto-kernel</filename> script to add patches and configuration
+                    items to the BSP's kernel.
+                </para>
+
+                <para>
+                    The <filename>yocto-kernel</filename> script allows you to add, remove, and list patches
+                    and kernel config settings to a BSP's kernel
+                    <filename>.bbappend</filename> file.
+                    All you need to do is use the appropriate sub-command.
+                    Recall that the easiest way to see exactly what sub-commands are available
+                    is to use the <filename>yocto-kernel</filename> built-in help as follows:
+                    <literallayout class='monospaced'>
+     $ yocto-kernel
+     Usage:
+
+      Modify and list Yocto BSP kernel config items and patches.
+
+      usage: yocto-kernel [--version] [--help] COMMAND [ARGS]
+
+      Current 'yocto-kernel' commands are:
+        config list       List the modifiable set of bare kernel config options for a BSP
+        config add        Add or modify bare kernel config options for a BSP
+        config rm         Remove bare kernel config options from a BSP
+        patch list        List the patches associated with a BSP
+        patch add         Patch the Yocto kernel for a BSP
+        patch rm          Remove patches from a BSP
+        feature list      List the features used by a BSP
+        feature add       Have a BSP use a feature
+        feature rm        Have a BSP stop using a feature
+        features list     List the features available to BSPs
+        feature describe  Describe a particular feature
+        feature create    Create a new BSP-local feature
+        feature destroy   Remove a BSP-local feature
+
+      See 'yocto-kernel help COMMAND' for more information on a specific command.
+
+
+
+     Options:
+       --version    show program's version number and exit
+       -h, --help   show this help message and exit
+       -D, --debug  output debug information
+                    </literallayout>
+                </para>
+
+                <para>
+                    The <filename>yocto-kernel patch add</filename> sub-command allows you to add a
+                    patch to a BSP.
+                    The following example adds two patches to the <filename>myarm</filename> BSP:
+                    <literallayout class='monospaced'>
+     $ yocto-kernel patch add myarm ~/test.patch
+     Added patches:
+             test.patch
+
+     $ yocto-kernel patch add myarm ~/yocto-testmod.patch
+     Added patches:
+             yocto-testmod.patch
+                    </literallayout>
+                    <note>Although the previous example adds patches one at a time, it is possible
+                    to add multiple patches at the same time.</note>
+                </para>
+
+                <para>
+                    You can verify patches have been added by using the
+                    <filename>yocto-kernel patch list</filename> sub-command.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ yocto-kernel patch list myarm
+     The current set of machine-specific patches for myarm is:
+             1) test.patch
+             2) yocto-testmod.patch
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can also use the <filename>yocto-kernel</filename> script to
+                    remove a patch using the <filename>yocto-kernel patch rm</filename> sub-command.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ yocto-kernel patch rm myarm
+     Specify the patches to remove:
+             1) test.patch
+             2) yocto-testmod.patch
+     1
+     Removed patches:
+             test.patch
+                    </literallayout>
+                </para>
+
+                <para>
+                    Again, using the <filename>yocto-kernel patch list</filename> sub-command,
+                    you can verify that the patch was in fact removed:
+                    <literallayout class='monospaced'>
+     $ yocto-kernel patch list myarm
+     The current set of machine-specific patches for myarm is:
+             1) yocto-testmod.patch
+                    </literallayout>
+                </para>
+
+                <para>
+                    In a completely similar way, you can use the <filename>yocto-kernel config add</filename>
+                    sub-command to add one or more kernel config item settings to a BSP.
+                    The following commands add a couple of config items to the
+                    <filename>myarm</filename> BSP:
+                    <literallayout class='monospaced'>
+     $ yocto-kernel config add myarm CONFIG_MISC_DEVICES=y
+     Added items:
+             CONFIG_MISC_DEVICES=y
+
+     $ yocto-kernel config add myarm CONFIG_YOCTO_TESTMOD=y
+     Added items:
+             CONFIG_YOCTO_TESTMOD=y
+                    </literallayout>
+                    <note>Although the previous example adds config items one at a time, it is possible
+                    to add multiple config items at the same time.</note>
+                </para>
+
+                <para>
+                    You can list the config items now associated with the BSP.
+                    Doing so shows you the config items you added as well as others associated
+                    with the BSP:
+                    <literallayout class='monospaced'>
+     $ yocto-kernel config list myarm
+     The current set of machine-specific kernel config items for myarm is:
+             1) CONFIG_MISC_DEVICES=y
+             2) CONFIG_YOCTO_TESTMOD=y
+                    </literallayout>
+                </para>
+
+                <para>
+                    Finally, you can remove one or more config items using the
+                    <filename>yocto-kernel config rm</filename> sub-command in a manner
+                    completely analogous to <filename>yocto-kernel patch rm</filename>.
+                </para>
+            </section>
+        </section>
+</chapter>
diff --git a/documentation/bsp-guide/figures/bsp-title.png b/documentation/bsp-guide/figures/bsp-title.png
new file mode 100644
index 0000000000..f624dd4f94
--- /dev/null
+++ b/documentation/bsp-guide/figures/bsp-title.png
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
new file mode 100644
index 0000000000..e2e89a032c
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -0,0 +1,5913 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='extendpoky'>
+
+<title>Common Tasks</title>
+    <para>
+        This chapter describes fundamental procedures such as creating layers,
+        adding new software packages, extending or customizing images,
+        porting work to new hardware (adding a new machine), and so forth.
+        You will find the procedures documented here occur often in the
+        develop cycle using the Yocto Project.
+    </para>
+
+    <section id="understanding-and-creating-layers">
+        <title>Understanding and Creating Layers</title>
+
+        <para>
+            The OpenEmbedded build system supports organizing
+            <link linkend='metadata'>Metadata</link> into multiple layers.
+            Layers allow you to isolate different types of customizations from
+            each other.
+            You might find it tempting to keep everything in one layer when
+            working on a single project.
+            However, the more modular you organize your Metadata, the easier
+            it is to cope with future changes.
+        </para>
+
+        <para>
+            To illustrate how layers are used to keep things modular, consider
+            machine customizations.
+            These types of customizations typically reside in a special layer,
+            rather than a general layer, called a Board Specific Package (BSP)
+            Layer.
+            Furthermore, the machine customizations should be isolated from
+            recipes and Metadata that support a new GUI environment,
+            for example.
+            This situation gives you a couple of layers: one for the machine
+            configurations, and one for the GUI environment.
+            It is important to understand, however, that the BSP layer can
+            still make machine-specific additions to recipes within the GUI
+            environment layer without polluting the GUI layer itself
+            with those machine-specific changes.
+            You can accomplish this through a recipe that is a BitBake append
+            (<filename>.bbappend</filename>) file, which is described later
+            in this section.
+        </para>
+
+        <para>
+        </para>
+
+        <section id='yocto-project-layers'>
+            <title>Layers</title>
+
+            <para>
+                The <link linkend='source-directory'>Source Directory</link>
+                contains both general layers and BSP
+                layers right out of the box.
+                You can easily identify layers that ship with a
+                Yocto Project release in the Source Directory by their
+                folder names.
+                Folders that are layers begin with the string
+                <filename>meta</filename>.
+                <note>
+                    It is not a requirement that a layer begins with the
+                    string <filename>meta</filename>.
+                </note>
+                For example, when you set up the Source Directory structure,
+                you will see several layers:
+                <filename>meta</filename>, <filename>meta-hob</filename>,
+                <filename>meta-skeleton</filename>,
+                <filename>meta-yocto</filename>, and
+                <filename>meta-yocto-bsp</filename>.
+                Each of these folders is a layer.
+            </para>
+
+            <para>
+                Furthermore, if you set up a local copy of the
+                <filename>meta-intel</filename> Git repository
+                and then explore the folder of that general layer,
+                you will discover many BSP layers inside.
+                For more information on BSP layers, see the
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+                section in the Yocto Project Board Support Package (BSP)
+                Developer's Guide.
+            </para>
+        </section>
+
+        <section id='creating-your-own-layer'>
+            <title>Creating Your Own Layer</title>
+
+            <para>
+                It is very easy to create your own layers to use with the
+                OpenEmbedded build system.
+                The Yocto Project ships with scripts that speed up creating
+                general layers and BSP layers.
+                This section describes the steps you perform by hand to create
+                a layer so that you can better understand them.
+                For information about the layer-creation scripts, see the
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
+                section in the Yocto Project Board Support Package (BSP)
+                Developer's Guide and the
+                "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
+                section further down in this manual.
+            </para>
+
+            <para>
+                Follow these general steps to create your layer:
+                <orderedlist>
+                    <listitem><para><emphasis>Check Existing Layers:</emphasis>
+                        Before creating a new layer, you should be sure someone
+                        has not already created a layer containing the Metadata
+                        you need.
+                        You can see the
+                        <ulink url='http://layers.openembedded.org/layerindex/layers/'><filename>OpenEmbedded Metadata Index</filename></ulink>
+                        for a list of layers from the OpenEmbedded community
+                        that can be used in the Yocto Project.
+                        </para></listitem>
+                    <listitem><para><emphasis>Create a Directory:</emphasis>
+                        Create the directory for your layer.
+                        While not strictly required, prepend the name of the
+                        folder with the string <filename>meta-</filename>.
+                        For example:
+                        <literallayout class='monospaced'>
+     meta-mylayer
+     meta-GUI_xyz
+     meta-mymachine
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Create a Layer Configuration
+                       File:</emphasis>
+                       Inside your new layer folder, you need to create a
+                       <filename>conf/layer.conf</filename> file.
+                       It is easiest to take an existing layer configuration
+                       file and copy that to your layer's
+                       <filename>conf</filename> directory and then modify the
+                       file as needed.</para>
+                       <para>The
+                       <filename>meta-yocto-bsp/conf/layer.conf</filename> file
+                       demonstrates the required syntax:
+                       <literallayout class='monospaced'>
+     # We have a conf and classes directory, add to BBPATH
+     BBPATH .= ":${LAYERDIR}"
+
+     # We have recipes-* directories, add to BBFILES
+     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+                 ${LAYERDIR}/recipes-*/*/*.bbappend"
+
+     BBFILE_COLLECTIONS += "yoctobsp"
+     BBFILE_PATTERN_yoctobsp = "^${LAYERDIR}/"
+     BBFILE_PRIORITY_yoctobsp = "5"
+     LAYERVERSION_yoctobsp = "2"
+                        </literallayout></para>
+                        <para>Here is an explanation of the example:
+                        <itemizedlist>
+                            <listitem><para>The configuration and
+                                classes directory is appended to
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>.
+                                <note>
+                                    All non-distro layers, which include all BSP
+                                    layers, are expected to append the layer
+                                    directory to the
+                                    <filename>BBPATH</filename>.
+                                    On the other hand, distro layers, such as
+                                    <filename>meta-yocto</filename>, can choose
+                                    to enforce their own precedence over
+                                    <filename>BBPATH</filename>.
+                                    For an example of that syntax, see the
+                                    <filename>layer.conf</filename> file for
+                                    the <filename>meta-yocto</filename> layer.
+                                </note></para></listitem>
+                            <listitem><para>The recipes for the layers are
+                                appended to
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILES'>BBFILES</ulink></filename>.
+                                </para></listitem>
+                            <listitem><para>The
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</ulink></filename>
+                                variable is then appended with the layer name.
+                                </para></listitem>
+                            <listitem><para>The
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PATTERN'>BBFILE_PATTERN</ulink></filename>
+                                variable is set to a regular expression and is
+                                used to match files from
+                                <filename>BBFILES</filename> into a particular
+                                layer.
+                                In this case,
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
+                                is used to make <filename>BBFILE_PATTERN</filename> match within the
+                                layer's path.</para></listitem>
+                            <listitem><para>The
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'>BBFILE_PRIORITY</ulink></filename>
+                                variable then assigns a priority to the layer.
+                                Applying priorities is useful in situations
+                                where the same package might appear in multiple
+                                layers and allows you to choose what layer
+                                should take precedence.</para></listitem>
+                            <listitem><para>The
+                                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERVERSION'>LAYERVERSION</ulink></filename>
+                                variable optionally specifies the version of a
+                                layer as a single number.</para></listitem>
+                        </itemizedlist></para>
+                        <para>Note the use of the
+                        <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LAYERDIR'>LAYERDIR</ulink></filename>
+                        variable, which expands to the directory of the current
+                        layer.</para>
+                        <para>Through the use of the <filename>BBPATH</filename>
+                        variable, BitBake locates <filename>.bbclass</filename>
+                        files, configuration files, and files that are included
+                        with <filename>include</filename> and
+                        <filename>require</filename> statements.
+                        For these cases, BitBake uses the first file that
+                        matches the name found in <filename>BBPATH</filename>.
+                        This is similar to the way the <filename>PATH</filename>
+                        variable is used for binaries.
+                        We recommend, therefore, that you use unique
+                        <filename>.bbclass</filename> and configuration
+                        filenames in your custom layer.</para></listitem>
+                    <listitem><para><emphasis>Add Content:</emphasis> Depending
+                        on the type of layer, add the content.
+                        If the layer adds support for a machine, add the machine
+                        configuration in a <filename>conf/machine/</filename>
+                        file within the layer.
+                        If the layer adds distro policy, add the distro
+                        configuration in a <filename>conf/distro/</filename>
+                        file with the layer.
+                        If the layer introduces new recipes, put the recipes
+                        you need in <filename>recipes-*</filename>
+                        subdirectories within the layer.
+                        <note>In order to be compliant with the Yocto Project,
+                            a layer must contain a
+                            <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-readme'>README file.</ulink>
+                            </note></para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='best-practices-to-follow-when-creating-layers'>
+            <title>Best Practices to Follow When Creating Layers</title>
+
+            <para>
+                To create layers that are easier to maintain and that will
+                not impact builds for other machines, you should consider the
+                information in the following sections.
+            </para>
+
+            <section id='avoid-overlaying-entire-recipes'>
+                <title>Avoid "Overlaying" Entire Recipes</title>
+
+                <para>
+                    Avoid "overlaying" entire recipes from other layers in your
+                    configuration.
+                    In other words, do not copy an entire recipe into your
+                    layer and then modify it.
+                    Use <filename>.bbappend</filename> files to override the
+                    parts of the recipe you need to modify.
+                </para>
+            </section>
+
+            <section id='avoid-duplicating-include-files'>
+                <title>Avoid Duplicating Include Files</title>
+
+                <para>
+                    Avoid duplicating include files.
+                    Use <filename>.bbappend</filename> files for each recipe
+                    that uses an include file.
+                    Or, if you are introducing a new recipe that requires
+                    the included file, use the path relative to the original
+                    layer directory to refer to the file.
+                    For example, use
+                    <filename>require recipes-core/somepackage/somefile.inc</filename>
+                    instead of <filename>require somefile.inc</filename>.
+                    If you're finding you have to overlay the include file,
+                    it could indicate a deficiency in the include file in
+                    the layer to which it originally belongs.
+                    If this is the case, you need to address that deficiency
+                    instead of overlaying the include file.
+                    For example, consider how support plug-ins for the Qt 4
+                    database are configured.
+                    The Source Directory does not have MySQL or PostgreSQL.
+                    However, OpenEmbedded's layer <filename>meta-oe</filename>
+                    does.
+                    Consequently, <filename>meta-oe</filename> uses
+                    <filename>.bbappend</filename> files to modify the
+                    <filename>QT_SQL_DRIVER_FLAGS</filename> variable to
+                    enable the appropriate plug-ins.
+                    This variable was added to the <filename>qt4.inc</filename>
+                    include file in the Source Directory specifically to allow
+                    the <filename>meta-oe</filename> layer to be able to control
+                    which plug-ins are built.
+                </para>
+            </section>
+
+            <section id='structure-your-layers'>
+                <title>Structure Your Layers</title>
+
+                <para>
+                    Proper use of overrides within append files and placement
+                    of machine-specific files within your layer can ensure that
+                    a build is not using the wrong Metadata and negatively
+                    impacting a build for a different machine.
+                    Following are some examples:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Modifying Variables to Support
+                            a Different Machine:</emphasis>
+                            Suppose you have a layer named
+                            <filename>meta-one</filename> that adds support
+                            for building machine "one".
+                            To do so, you use an append file named
+                            <filename>base-files.bbappend</filename> and
+                            create a dependency on "foo" by altering the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+                            variable:
+                            <literallayout class='monospaced'>
+     DEPENDS = "foo"
+                            </literallayout>
+                            The dependency is created during any build that
+                            includes the layer
+                            <filename>meta-one</filename>.
+                            However, you might not want this dependency
+                            for all machines.
+                            For example, suppose you are building for
+                            machine "two" but your
+                            <filename>bblayers.conf</filename> file has the
+                            <filename>meta-one</filename> layer included.
+                            During the build, the
+                            <filename>base-files</filename> for machine
+                            "two" will also have the dependency on
+                            <filename>foo</filename>.</para>
+                            <para>To make sure your changes apply only when
+                            building machine "one", use a machine override
+                            with the <filename>DEPENDS</filename> statement:
+                            <literallayout class='monospaced'>
+     DEPENDS_one = "foo"
+                            </literallayout>
+                            You should follow the same strategy when using
+                            <filename>_append</filename> and
+                            <filename>_prepend</filename> operations:
+                            <literallayout class='monospaced'>
+     DEPENDS_append_one = " foo"
+     DEPENDS_prepend_one = "foo "
+                            </literallayout>
+                            <note>
+                                Avoiding "+=" and "=+" and using
+                                machine-specific
+                                <filename>_append</filename>
+                                and <filename>_prepend</filename> operations
+                                is recommended as well.
+                            </note></para></listitem>
+                        <listitem><para><emphasis>Place Machine-Specific Files
+                            in Machine-Specific Locations:</emphasis>
+                            When you have a base recipe, such as
+                            <filename>base-files.bb</filename>, that
+                            contains a
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                            statement to a file, you can use an append file
+                            to cause the build to use your own version of
+                            the file.
+                            For example, an append file in your layer at
+                            <filename>/meta-one/recipes-core/base-files/base-files.bbappend</filename>
+                            could extend
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                            using
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                            as follows:
+                            <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${BPN}:"
+                            </literallayout>
+                            The build for machine "one" will pick up your
+                            machine-specific file as long as you have the
+                            file in
+                            <filename>/meta-one/recipes-core/base-files/base-files/</filename>.
+                            However, if you are building for a different
+                            machine and the
+                            <filename>bblayers.conf</filename> file includes
+                            the <filename>meta-one</filename> layer and
+                            the location of your machine-specific file is
+                            the first location where that file is found
+                            according to <filename>FILESPATH</filename>,
+                            builds for all machines will also use that
+                            machine-specific file.</para>
+                            <para>You can make sure that a machine-specific
+                            file is used for a particular machine by putting
+                            the file in a subdirectory specific to the
+                            machine.
+                            For example, rather than placing the file in
+                            <filename>/meta-one/recipes-core/base-files/base-files/</filename>
+                            as shown above, put it in
+                            <filename>/meta-one/recipes-core/base-files/base-files/one/</filename>.
+                            Not only does this make sure the file is used
+                            only when building for machine "one" but the
+                            build process locates the file more quickly.</para>
+                            <para>In summary, you need to place all files
+                            referenced from <filename>SRC_URI</filename>
+                            in a machine-specific subdirectory within the
+                            layer in order to restrict those files to
+                            machine-specific builds.</para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+
+            <section id='other-recommendations'>
+                <title>Other Recommendations</title>
+
+                <para>
+                    We also recommend the following:
+                    <itemizedlist>
+                        <listitem><para>Store custom layers in a Git repository
+                            that uses the
+                            <filename>meta-&lt;layer_name&gt;</filename> format.
+                            </para></listitem>
+                        <listitem><para>Clone the repository alongside other
+                            <filename>meta</filename> directories in the
+                            <link linkend='source-directory'>Source Directory</link>.
+                            </para></listitem>
+                     </itemizedlist>
+                     Following these recommendations keeps your Source Directory and
+                     its configuration entirely inside the Yocto Project's core
+                     base.
+                </para>
+            </section>
+        </section>
+
+        <section id='enabling-your-layer'>
+            <title>Enabling Your Layer</title>
+
+            <para>
+                Before the OpenEmbedded build system can use your new layer,
+                you need to enable it.
+                To enable your layer, simply add your layer's path to the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'>BBLAYERS</ulink></filename>
+                variable in your <filename>conf/bblayers.conf</filename> file,
+                which is found in the
+                <link linkend='build-directory'>Build Directory</link>.
+                The following example shows how to enable a layer named
+                <filename>meta-mylayer</filename>:
+                <literallayout class='monospaced'>
+     LCONF_VERSION = "6"
+
+     BBPATH = "${TOPDIR}"
+     BBFILES ?= ""
+
+     BBLAYERS ?= " \
+       $HOME/poky/meta \
+       $HOME/poky/meta-yocto \
+       $HOME/poky/meta-yocto-bsp \
+       $HOME/poky/meta-mylayer \
+       "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+       $HOME/poky/meta \
+       $HOME/poky/meta-yocto \
+       "
+                </literallayout>
+            </para>
+
+            <para>
+                BitBake parses each <filename>conf/layer.conf</filename> file
+                as specified in the <filename>BBLAYERS</filename> variable
+                within the <filename>conf/bblayers.conf</filename> file.
+                During the processing of each
+                <filename>conf/layer.conf</filename> file, BitBake adds the
+                recipes, classes and configurations contained within the
+                particular layer to the source directory.
+            </para>
+        </section>
+
+        <section id='using-bbappend-files'>
+            <title>Using .bbappend Files</title>
+
+            <para>
+                Recipes used to append Metadata to other recipes are called
+                BitBake append files.
+                BitBake append files use the <filename>.bbappend</filename> file
+                type suffix, while the corresponding recipes to which Metadata
+                is being appended use the <filename>.bb</filename> file type
+                suffix.
+            </para>
+
+            <para>
+                A <filename>.bbappend</filename> file allows your layer to make
+                additions or changes to the content of another layer's recipe
+                without having to copy the other recipe into your layer.
+                Your <filename>.bbappend</filename> file resides in your layer,
+                while the main <filename>.bb</filename> recipe file to
+                which you are appending Metadata resides in a different layer.
+            </para>
+
+            <para>
+                Append files must have the same root names as their corresponding
+                recipes.
+                For example, the append file
+                <filename>someapp_&DISTRO;.bbappend</filename> must apply to
+                <filename>someapp_&DISTRO;.bb</filename>.
+                This means the original recipe and append file names are version
+                number-specific.
+                If the corresponding recipe is renamed to update to a newer
+                version, the corresponding <filename>.bbappend</filename> file must
+                be renamed as well.
+                During the build process, BitBake displays an error on starting
+                if it detects a <filename>.bbappend</filename> file that does
+                not have a corresponding recipe with a matching name.
+                See the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_DANGLINGAPPENDS_WARNONLY'><filename>BB_DANGLINGAPPENDS_WARNONLY</filename></ulink>
+                variable for information on how to handle this error.
+            </para>
+
+            <para>
+                Being able to append information to an existing recipe not only
+                avoids duplication, but also automatically applies recipe
+                changes in a different layer to your layer.
+                If you were copying recipes, you would have to manually merge
+                changes as they occur.
+            </para>
+
+            <para>
+                As an example, consider the main formfactor recipe and a
+                corresponding formfactor append file both from the
+                <link linkend='source-directory'>Source Directory</link>.
+                Here is the main formfactor recipe, which is named
+                <filename>formfactor_0.0.bb</filename> and located in the
+                "meta" layer at
+                <filename>meta/recipes-bsp/formfactor</filename>:
+                <literallayout class='monospaced'>
+     DESCRIPTION = "Device formfactor information"
+     SECTION = "base"
+     LICENSE = "MIT"
+     LIC_FILES_CHKSUM = "file://${COREBASE}/LICENSE;md5=3f40d7994397109285ec7b81fdeb3b58 \
+                         file://${COREBASE}/meta/COPYING.MIT;md5=3da9cfbcb788c80a0384361b4de20420"
+     PR = "r41"
+
+     SRC_URI = "file://config file://machconfig"
+     S = "${WORKDIR}"
+
+     PACKAGE_ARCH = "${MACHINE_ARCH}"
+     INHIBIT_DEFAULT_DEPS = "1"
+
+     do_install() {
+        # Only install file if it has a contents
+             install -d ${D}${sysconfdir}/formfactor/
+             install -m 0644 ${S}/config ${D}${sysconfdir}/formfactor/
+        if [ -s "${S}/machconfig" ]; then
+                install -m 0644 ${S}/machconfig ${D}${sysconfdir}/formfactor/
+        fi
+     }
+                </literallayout>
+                In the main recipe, note the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                variable, which tells the OpenEmbedded build system where to
+                find files during the build.
+            </para>
+
+            <para>
+                Following is the append file, which is named
+                <filename>formfactor_0.0.bbappend</filename> and is from the
+                Crown Bay BSP Layer named
+                <filename>meta-intel/meta-crownbay</filename>.
+                The file is in <filename>recipes-bsp/formfactor</filename>:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+                </literallayout>
+            </para>
+
+            <para>
+                By default, the build system uses the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                variable to locate files.
+                This append file extends the locations by setting the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                variable.
+                Setting this variable in the <filename>.bbappend</filename>
+                file is the most reliable and recommended method for adding
+                directories to the search path used by the build system
+                to find files.
+            </para>
+
+            <para>
+                The statement in this example extends the directories to include
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>,
+                which resolves to a directory named
+                <filename>formfactor</filename> in the same directory
+                in which the append file resides (i.e.
+                <filename>meta-intel/meta-crownbay/recipes-bsp/formfactor/formfactor</filename>.
+                This implies that you must have the supporting directory
+                structure set up that will contain any files or patches you
+                will be including from the layer.
+            </para>
+
+            <para>
+                Using the immediate expansion assignment operator
+                <filename>:=</filename> is important because of the reference to
+                <filename>THISDIR</filename>.
+                The trailing colon character is important as it ensures that
+                items in the list remain colon-separated.
+                <note><para>BitBake automatically defines the
+                    <filename>THISDIR</filename> variable.
+                    You should never set this variable yourself.
+                    Using <filename>_prepend</filename> ensures your path will
+                    be searched prior to other paths in the final list.</para>
+                    <para>Also, not all append files add extra files.
+                    Many append files simply exist to add build options
+                    (e.g. <filename>systemd</filename>).
+                    For these cases, it is not necessary to use the
+                    "_prepend" part of the statement.</para>
+                </note>
+            </para>
+        </section>
+
+        <section id='prioritizing-your-layer'>
+            <title>Prioritizing Your Layer</title>
+
+            <para>
+                Each layer is assigned a priority value.
+                Priority values control which layer takes precedence if there
+                are recipe files with the same name in multiple layers.
+                For these cases, the recipe file from the layer with a higher
+                priority number takes precedence.
+                Priority values also affect the order in which multiple
+                <filename>.bbappend</filename> files for the same recipe are
+                applied.
+                You can either specify the priority manually, or allow the
+                build system to calculate it based on the layer's dependencies.
+            </para>
+
+            <para>
+                To specify the layer's priority manually, use the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink>
+                variable.
+                For example:
+                <literallayout class='monospaced'>
+     BBFILE_PRIORITY_mylayer = "1"
+                </literallayout>
+            </para>
+
+            <note>
+                <para>It is possible for a recipe with a lower version number
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+                in a layer that has a higher priority to take precedence.</para>
+                <para>Also, the layer priority does not currently affect the
+                precedence order of <filename>.conf</filename>
+                or <filename>.bbclass</filename> files.
+                Future versions of BitBake might address this.</para>
+            </note>
+        </section>
+
+        <section id='managing-layers'>
+            <title>Managing Layers</title>
+
+            <para>
+                You can use the BitBake layer management tool to provide a view
+                into the structure of recipes across a multi-layer project.
+                Being able to generate output that reports on configured layers
+                with their paths and priorities and on
+                <filename>.bbappend</filename> files and their applicable
+                recipes can help to reveal potential problems.
+            </para>
+
+            <para>
+                Use the following form when running the layer management tool.
+                <literallayout class='monospaced'>
+     $ bitbake-layers &lt;command&gt; [arguments]
+                </literallayout>
+                The following list describes the available commands:
+                <itemizedlist>
+                    <listitem><para><filename><emphasis>help:</emphasis></filename>
+                        Displays general help or help on a specified command.
+                        </para></listitem>
+                    <listitem><para><filename><emphasis>show-layers:</emphasis></filename>
+                        Shows the current configured layers.
+                        </para></listitem>
+                    <listitem><para><filename><emphasis>show-recipes:</emphasis></filename>
+                        Lists available recipes and the layers that provide them.
+                        </para></listitem>
+                    <listitem><para><filename><emphasis>show-overlayed:</emphasis></filename>
+                        Lists overlayed recipes.
+                        A recipe is overlayed when a recipe with the same name
+                        exists in another layer that has a higher layer
+                        priority.
+                        </para></listitem>
+                    <listitem><para><filename><emphasis>show-appends:</emphasis></filename>
+                        Lists <filename>.bbappend</filename> files and the
+                        recipe files to which they apply.
+                        </para></listitem>
+                    <listitem><para><filename><emphasis>show-cross-depends:</emphasis></filename>
+                        Lists dependency relationships between recipes that
+                        cross layer boundaries.
+                        </para></listitem>
+                    <listitem><para><filename><emphasis>flatten:</emphasis></filename>
+                        Flattens the layer configuration into a separate output
+                        directory.
+                        Flattening your layer configuration builds a "flattened"
+                        directory that contains the contents of all layers,
+                        with any overlayed recipes removed and any
+                        <filename>.bbappend</filename> files appended to the
+                        corresponding recipes.
+                        You might have to perform some manual cleanup of the
+                        flattened layer as follows:
+                        <itemizedlist>
+                            <listitem><para>Non-recipe files (such as patches)
+                                are overwritten.
+                                The flatten command shows a warning for these
+                                files.
+                                </para></listitem>
+                            <listitem><para>Anything beyond the normal layer
+                                setup has been added to the
+                                <filename>layer.conf</filename> file.
+                                Only the lowest priority layer's
+                                <filename>layer.conf</filename> is used.
+                                </para></listitem>
+                            <listitem><para>Overridden and appended items from
+                                <filename>.bbappend</filename> files need to be
+                                cleaned up.
+                                The contents of each
+                                <filename>.bbappend</filename> end up in the
+                                flattened recipe.
+                                However, if there are appended or changed
+                                variable values, you need to tidy these up
+                                yourself.
+                                Consider the following example.
+                                Here, the <filename>bitbake-layers</filename>
+                                command adds the line
+                                <filename>#### bbappended ...</filename> so that
+                                you know where the following lines originate:
+                                <literallayout class='monospaced'>
+     ...
+     DESCRIPTION = "A useful utility"
+     ...
+     EXTRA_OECONF = "--enable-something"
+     ...
+
+     #### bbappended from meta-anotherlayer ####
+
+     DESCRIPTION = "Customized utility"
+     EXTRA_OECONF += "--enable-somethingelse"
+                                </literallayout>
+                                Ideally, you would tidy up these utilities as
+                                follows:
+                                <literallayout class='monospaced'>
+     ...
+     DESCRIPTION = "Customized utility"
+     ...
+     EXTRA_OECONF = "--enable-something --enable-somethingelse"
+     ...
+                                </literallayout></para></listitem>
+                        </itemizedlist></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='creating-a-general-layer-using-the-yocto-layer-script'>
+            <title>Creating a General Layer Using the yocto-layer Script</title>
+
+            <para>
+                The <filename>yocto-layer</filename> script simplifies
+                creating a new general layer.
+                <note>
+                    For information on BSP layers, see the
+                    "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+                    section in the Yocto Project Board Specific (BSP)
+                    Developer's Guide.
+                </note>
+                The default mode of the script's operation is to prompt you for
+                information needed to generate the layer:
+                <itemizedlist>
+                    <listitem><para>The layer priority
+                        </para></listitem>
+                    <listitem><para>Whether or not to create a sample recipe.
+                        </para></listitem>
+                    <listitem><para>Whether or not to create a sample
+                        append file.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Use the <filename>yocto-layer create</filename> sub-command
+                to create a new general layer.
+                In its simplest form, you can create a layer as follows:
+                <literallayout class='monospaced'>
+     $ yocto-layer create mylayer
+                </literallayout>
+                The previous example creates a layer named
+                <filename>meta-mylayer</filename> in the current directory.
+            </para>
+
+            <para>
+                As the <filename>yocto-layer create</filename> command runs,
+                default values for the prompts appear in brackets.
+                Pressing enter without supplying anything for the prompts
+                or pressing enter and providing an invalid response causes the
+                script to accept the default value.
+                Once the script completes, the new layer
+                is created in the current working directory.
+                The script names the layer by prepending
+                <filename>meta-</filename> to the name you provide.
+            </para>
+
+            <para>
+                Minimally, the script creates the following within the layer:
+                <itemizedlist>
+                    <listitem><para><emphasis>The <filename>conf</filename>
+                        directory:</emphasis>
+                        This directory contains the layer's configuration file.
+                        The root name for the file is the same as the root name
+                        your provided for the layer (e.g.
+                        <filename>&lt;layer&gt;.conf</filename>).
+                        </para></listitem>
+                    <listitem><para><emphasis>The
+                        <filename>COPYING.MIT</filename>:</emphasis>
+                        The copyright and use notice for the software.
+                        </para></listitem>
+                    <listitem><para><emphasis>The <filename>README</filename>
+                        file:</emphasis>
+                        A file describing the contents of your new layer.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                If you choose to generate a sample recipe file, the script
+                prompts you for the name for the recipe and then creates it
+                in <filename>&lt;layer&gt;/recipes-example/example/</filename>.
+                The script creates a <filename>.bb</filename> file and a
+                directory, which contains a sample
+                <filename>helloworld.c</filename> source file and along with
+                a sample patch file.
+                If you do not provide a recipe name, the script uses
+                "example".
+            </para>
+
+            <para>
+                If you choose to generate a sample append file, the script
+                prompts you for the name for the file and then creates it
+                in <filename>&lt;layer&gt;/recipes-example-bbappend/example-bbappend/</filename>.
+                The script creates a <filename>.bbappend</filename> file and a
+                directory, which contains a sample patch file.
+                If you do not provide a recipe name, the script uses
+                "example".
+                The script also prompts you for the version of the append file.
+                The version should match the recipe to which the append file
+                is associated.
+            </para>
+
+            <para>
+                The easiest way to see how the <filename>yocto-layer</filename>
+                script works is to experiment with the script.
+                You can also read the usage information by entering the
+                following:
+                <literallayout class='monospaced'>
+     $ yocto-layer help
+                </literallayout>
+            </para>
+
+            <para>
+                Once you create your general layer, you must add it to your
+                <filename>bblayers.conf</filename> file.
+                Here is an example where a layer named
+                <filename>meta-mylayer</filename> is added:
+                <literallayout class='monospaced'>
+     BBLAYERS = ?" \
+        /usr/local/src/yocto/meta \
+        /usr/local/src/yocto/meta-yocto \
+        /usr/local/src/yocto/meta-yocto-bsp \
+        /usr/local/src/yocto/meta-mylayer \
+        "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+        /usr/local/src/yocto/meta \
+        /usr/local/src/yocto/meta-yocto \
+        "
+                </literallayout>
+                Adding the layer to this file enables the build system to
+                locate the layer during the build.
+                </para>
+        </section>
+    </section>
+
+    <section id='usingpoky-extend-customimage'>
+        <title>Customizing Images</title>
+
+        <para>
+            You can customize images to satisfy particular requirements.
+            This section describes several methods and provides guidelines for each.
+        </para>
+
+        <section id='usingpoky-extend-customimage-custombb'>
+            <title>Customizing Images Using Custom .bb Files</title>
+
+            <para>
+                One way to get additional software into an image is to create a custom image.
+                The following example shows the form for the two lines you need:
+                <literallayout class='monospaced'>
+     IMAGE_INSTALL = "packagegroup-core-x11-base package1 package2"
+
+     inherit core-image
+                </literallayout>
+            </para>
+
+            <para>
+                By creating a custom image, a developer has total control
+                over the contents of the image.
+                It is important to use the correct names of packages in the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
+                variable.
+                You must use the OpenEmbedded notation and not the Debian notation for the names
+                (e.g. <filename>eglibc-dev</filename> instead of <filename>libc6-dev</filename>).
+            </para>
+
+            <para>
+                The other method for creating a custom image is to base it on an existing image.
+                For example, if you want to create an image based on <filename>core-image-sato</filename>
+                but add the additional package <filename>strace</filename> to the image,
+                copy the <filename>meta/recipes-sato/images/core-image-sato.bb</filename> to a
+                new <filename>.bb</filename> and add the following line to the end of the copy:
+                <literallayout class='monospaced'>
+     IMAGE_INSTALL += "strace"
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='usingpoky-extend-customimage-customtasks'>
+            <title>Customizing Images Using Custom Package Groups</title>
+
+            <para>
+                For complex custom images, the best approach is to create a
+                custom package group recipe that is used to build the image or
+                images.
+                A good example of a package group recipe is
+                <filename>meta/recipes-core/packagegroups/packagegroup-core-boot.bb</filename>.
+                The
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename>
+                variable lists the package group packages you wish to produce.
+                <filename>inherit packagegroup</filename> sets appropriate
+                default values and automatically adds <filename>-dev</filename>,
+                <filename>-dbg</filename>, and <filename>-ptest</filename>
+                complementary packages for every package specified in
+                <filename>PACKAGES</filename>.
+                Note that the inherit line should be towards
+                the top of the recipe, certainly before you set
+                <filename>PACKAGES</filename>.
+                For each package you specify in <filename>PACKAGES</filename>,
+                you can use
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'>RDEPENDS</ulink></filename>
+                and
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'>RRECOMMENDS</ulink></filename>
+                entries to provide a list of packages the parent task package
+                should contain.
+                Following is an example:
+                <literallayout class='monospaced'>
+     DESCRIPTION = "My Custom Package Groups"
+
+     inherit packagegroup
+
+     PACKAGES = "\
+         packagegroup-custom-apps \
+         packagegroup-custom-tools \
+         "
+
+     RDEPENDS_packagegroup-custom-apps = "\
+         dropbear \
+         portmap \
+         psplash"
+
+     RDEPENDS_packagegroup-custom-tools = "\
+         oprofile \
+         oprofileui-server \
+         lttng-control \
+         lttng-viewer"
+
+     RRECOMMENDS_packagegroup-custom-tools = "\
+         kernel-module-oprofile"
+                </literallayout>
+            </para>
+
+            <para>
+                In the previous example, two package group packages are created with their dependencies and their
+                recommended package dependencies listed: <filename>packagegroup-custom-apps</filename>, and
+                <filename>packagegroup-custom-tools</filename>.
+                To build an image using these package group packages, you need to add
+                <filename>packagegroup-custom-apps</filename> and/or
+                <filename>packagegroup-custom-tools</filename> to
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>.
+                For other forms of image dependencies see the other areas of this section.
+            </para>
+        </section>
+
+        <section id='usingpoky-extend-customimage-imagefeatures'>
+            <title>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and
+                <filename>EXTRA_IMAGE_FEATURES</filename></title>
+
+            <para>
+                You might want to customize your image by enabling or
+                disabling high-level image features by using the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+                and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
+                variables.
+                Although the functions for both variables are nearly equivalent,
+                best practices dictate using <filename>IMAGE_FEATURES</filename>
+                from within a recipe and using
+                <filename>EXTRA_IMAGE_FEATURES</filename> from within
+                your <filename>local.conf</filename> file, which is found in the
+                <link linkend='build-directory'>Build Directory</link>.
+            </para>
+
+            <para>
+                To understand how these features work, the best reference is
+                <filename>meta/classes/core-image.bbclass</filename>.
+                In summary, the file looks at the contents of the
+                <filename>IMAGE_FEATURES</filename> variable and then maps
+                those contents into a set of package groups.
+                Based on this information, the build system automatically
+                adds the appropriate packages to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
+                variable.
+                Effectively, you are enabling extra features by extending the
+                class or creating a custom class for use with specialized image
+                <filename>.bb</filename> files.
+            </para>
+
+            <para>
+                Use the <filename>EXTRA_IMAGE_FEATURES</filename> variable
+                from within your local configuration file.
+                Using a separate area from which to enable features with
+                this variable helps you avoid overwriting the features in the
+                image recipe that are enabled with
+                <filename>IMAGE_FEATURES</filename>.
+                The value of <filename>EXTRA_IMAGE_FEATURES</filename> is added
+                to <filename>IMAGE_FEATURES</filename> within
+                <filename>meta/conf/bitbake.conf</filename>.
+            </para>
+
+            <para>
+                To illustrate how you can use these variables to modify your
+                image, consider an example that selects the SSH server.
+                The Yocto Project ships with two SSH servers you can use
+                with your images: Dropbear and OpenSSH.
+                Dropbear is a minimal SSH server appropriate for
+                resource-constrained environments, while OpenSSH is a
+                well-known standard SSH server implementation.
+                By default, the <filename>core-image-sato</filename> image
+                is configured to use Dropbear.
+                The <filename>core-image-basic</filename> and
+                <filename>core-image-lsb</filename> images both
+                include OpenSSH.
+                The <filename>core-image-minimal</filename> image does not
+                contain an SSH server.
+            </para>
+
+            <para>
+                You can customize your image and change these defaults.
+                Edit the <filename>IMAGE_FEATURES</filename> variable
+                in your recipe or use the
+                <filename>EXTRA_IMAGE_FEATURES</filename> in your
+                <filename>local.conf</filename> file so that it configures the
+                image you are working with to include
+                <filename>ssh-server-dropbear</filename> or
+                <filename>ssh-server-openssh</filename>.
+            </para>
+
+            <note>
+                See the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+                section in the Yocto Project Reference Manual for a complete
+                list of image features that ship with the Yocto Project.
+            </note>
+        </section>
+
+        <section id='usingpoky-extend-customimage-localconf'>
+            <title>Customizing Images Using <filename>local.conf</filename></title>
+
+            <para>
+                It is possible to customize image contents by using variables from your
+                local configuration in your <filename>conf/local.conf</filename> file.
+                Because it is limited to local use, this method generally only allows you to
+                add packages and is not as flexible as creating your own customized image.
+                When you add packages using local variables this way, you need to realize that
+                these variable changes affect all images at the same time and might not be
+                what you require.
+            </para>
+
+            <para>
+                The simplest way to add extra packages to all images is by using the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'>IMAGE_INSTALL</ulink></filename>
+                variable with the <filename>_append</filename> operator:
+                <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = " strace"
+                </literallayout>
+                Use of the syntax is important - specifically, the space between
+                the quote and the package name, which is
+                <filename>strace</filename> in this example.
+                This space is required since the <filename>_append</filename>
+                operator does not add the space.
+            </para>
+
+            <para>
+                Furthermore, you must use <filename>_append</filename> instead of the <filename>+=</filename>
+                operator if you want to avoid ordering issues.
+                The reason for this is because doing so unconditionally appends to the variable and
+                avoids ordering problems due to the variable being set in image recipes and
+                <filename>.bbclass</filename> files with operators like <filename>?=</filename>.
+                Using <filename>_append</filename> ensures the operation takes affect.
+            </para>
+
+            <para>
+                As shown in its simplest use, <filename>IMAGE_INSTALL_append</filename> affects
+                all images.
+                It is possible to extend the syntax so that the variable applies to a specific image only.
+                Here is an example:
+                <literallayout class='monospaced'>
+     IMAGE_INSTALL_append_pn-core-image-minimal = " strace"
+                </literallayout>
+                This example adds <filename>strace</filename> to <filename>core-image-minimal</filename>
+                only.
+            </para>
+
+            <para>
+                You can add packages using a similar approach through the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CORE_IMAGE_EXTRA_INSTALL'>CORE_IMAGE_EXTRA_INSTALL</ulink></filename>
+                variable.
+                If you use this variable, only <filename>core-image-*</filename> images are affected.
+            </para>
+        </section>
+    </section>
+
+    <section id='usingpoky-extend-addpkg'>
+        <title>Writing a Recipe to Add a Package to Your Image</title>
+
+        <para>
+            Recipes add packages to your image.
+            Writing a recipe means creating a <filename>.bb</filename> file that sets some
+            variables.
+            For information on variables that are useful for recipes and for information about recipe naming
+            issues, see the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#ref-varlocality-recipe-required'>Required</ulink>"
+            section of the Yocto Project Reference Manual.
+        </para>
+
+        <para>
+            Before writing a recipe from scratch, it is often useful to check
+            whether someone else has written one already.
+            OpenEmbedded is a good place to look as it has a wider scope and range of packages.
+            Because the Yocto Project aims to be compatible with OpenEmbedded, most recipes
+            you find there should work for you.
+        </para>
+
+        <para>
+            For new packages, the simplest way to add a recipe is to base it on a similar
+            pre-existing recipe.
+            The sections that follow provide some examples that show how to add standard
+            types of packages.
+        </para>
+
+        <note>
+            <para>When writing shell functions, you need to be aware of BitBake's
+            curly brace parsing.
+            If a recipe uses a closing curly brace within the function and
+            the character has no leading spaces, BitBake produces a parsing
+            error.
+            If you use a pair of curly brace in a shell function, the
+            closing curly brace must not be located at the start of the line
+            without leading spaces.</para>
+            <para>Here is an example that causes BitBake to produce a parsing
+            error:
+            <literallayout class='monospaced'>
+     fakeroot create_shar() {
+         cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+     usage()
+     {
+       echo "test"
+       ###### The following "}" at the start of the line causes a parsing error ######
+     }
+     EOF
+     }
+            </literallayout>
+            Writing the recipe this way avoids the error:
+            <literallayout class='monospaced'>
+     fakeroot create_shar() {
+         cat &lt;&lt; "EOF" &gt; ${SDK_DEPLOY}/${TOOLCHAIN_OUTPUTNAME}.sh
+     usage()
+     {
+       echo "test"
+       ######The following "}" with a leading space at the start of the line avoids the error ######
+      }
+     EOF
+     }
+            </literallayout></para>
+        </note>
+
+        <section id='usingpoky-extend-addpkg-singlec'>
+            <title>Single .c File Package (Hello World!)</title>
+
+            <para>
+                Building an application from a single file that is stored locally (e.g. under
+                <filename>files/</filename>) requires a recipe that has the file listed in
+                the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
+                variable.
+                Additionally, you need to manually write the <filename>do_compile</filename> and
+                <filename>do_install</filename> tasks.
+                The <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename>
+                variable defines the
+                directory containing the source code, which is set to
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'>
+                WORKDIR</ulink></filename> in this case - the directory BitBake uses for the build.
+                <literallayout class='monospaced'>
+     DESCRIPTION = "Simple helloworld application"
+     SECTION = "examples"
+     LICENSE = "MIT"
+     LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
+     PR = "r0"
+
+     SRC_URI = "file://helloworld.c"
+
+     S = "${WORKDIR}"
+
+     do_compile() {
+        ${CC} helloworld.c -o helloworld
+     }
+
+     do_install() {
+        install -d ${D}${bindir}
+        install -m 0755 helloworld ${D}${bindir}
+     }
+                </literallayout>
+            </para>
+
+            <para>
+                By default, the <filename>helloworld</filename>, <filename>helloworld-dbg</filename>,
+                and <filename>helloworld-dev</filename> packages are built.
+                For information on how to customize the packaging process, see the
+                "<link linkend='splitting-an-application-into-multiple-packages'>Splitting an Application
+                into Multiple Packages</link>" section.
+            </para>
+        </section>
+
+        <section id='usingpoky-extend-addpkg-autotools'>
+            <title>Autotooled Package</title>
+            <para>
+                Applications that use Autotools such as <filename>autoconf</filename> and
+                <filename>automake</filename> require a recipe that has a source archive listed in
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename> and
+                also inherits Autotools, which instructs BitBake to use the
+                <filename>autotools.bbclass</filename> file, which contains the definitions of all the steps
+                needed to build an Autotool-based application.
+                The result of the build is automatically packaged.
+                And, if the application uses NLS for localization, packages with local information are
+                generated (one package per language).
+                Following is one example: (<filename>hello_2.3.bb</filename>)
+                <literallayout class='monospaced'>
+     DESCRIPTION = "GNU Helloworld application"
+     SECTION = "examples"
+     LICENSE = "GPLv2+"
+     LIC_FILES_CHKSUM = "file://COPYING;md5=751419260aa954499f7abaabaa882bbe"
+     PR = "r0"
+
+     SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.gz"
+
+     inherit autotools gettext
+                 </literallayout>
+            </para>
+
+            <para>
+                The variable
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</ulink></filename>
+                is used to track source license changes as described in the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-configuring-LIC_FILES_CHKSUM'>Tracking License Changes</ulink>" section.
+                You can quickly create Autotool-based recipes in a manner similar to the previous example.
+            </para>
+        </section>
+
+        <section id='usingpoky-extend-addpkg-makefile'>
+            <title>Makefile-Based Package</title>
+
+            <para>
+                Applications that use GNU <filename>make</filename> also require a recipe that has
+                the source archive listed in
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
+                You do not need to add a <filename>do_compile</filename> step since by default BitBake
+                starts the <filename>make</filename> command to compile the application.
+                If you need additional <filename>make</filename> options, you should store them in the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_OEMAKE'>EXTRA_OEMAKE</ulink></filename>
+                variable.
+                BitBake passes these options into the <filename>make</filename> GNU invocation.
+                Note that a <filename>do_install</filename> task is still required.
+                Otherwise, BitBake runs an empty <filename>do_install</filename> task by default.
+            </para>
+
+            <para>
+                Some applications might require extra parameters to be passed to the compiler.
+                For example, the application might need an additional header path.
+                You can accomplish this by adding to the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-CFLAGS'>CFLAGS</ulink></filename> variable.
+                The following example shows this:
+                <literallayout class='monospaced'>
+     CFLAGS_prepend = "-I ${S}/include "
+                </literallayout>
+            </para>
+
+            <para>
+            In the following example, <filename>mtd-utils</filename> is a makefile-based package:
+                <literallayout class='monospaced'>
+     DESCRIPTION = "Tools for managing memory technology devices."
+     SECTION = "base"
+     DEPENDS = "zlib lzo e2fsprogs util-linux"
+     HOMEPAGE = "http://www.linux-mtd.infradead.org/"
+     LICENSE = "GPLv2+"
+     LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
+                    file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
+
+     SRC_URI = "git://git.infradead.org/mtd-utils.git;protocol=git;tag=995cfe51b0a3cf32f381c140bf72b21bf91cef1b \
+                file://add-exclusion-to-mkfs-jffs2-git-2.patch"
+
+     S = "${WORKDIR}/git/"
+
+     PR = "r1"
+
+     EXTRA_OEMAKE = "'CC=${CC}' 'RANLIB=${RANLIB}' 'AR=${AR}' \
+        'CFLAGS=${CFLAGS} -I${S}/include -DWITHOUT_XATTR' 'BUILDDIR=${S}'"
+
+     do_install () {
+             oe_runmake install DESTDIR=${D} SBINDIR=${sbindir} MANDIR=${mandir} \
+            INCLUDEDIR=${includedir}
+             install -d ${D}${includedir}/mtd/
+             for f in ${S}/include/mtd/*.h; do
+                install -m 0644 $f ${D}${includedir}/mtd/
+             done
+     }
+
+     PARALLEL_MAKE = ""
+
+     BBCLASSEXTEND = "native"
+                </literallayout>
+            </para>
+
+            <para>
+                If your sources are available as a tarball instead of a Git repository, you
+                will need to provide the URL to the tarball as well as an
+                <filename>md5</filename> or <filename>sha256</filename> sum of
+                the download.
+                Here is an example:
+                <literallayout class='monospaced'>
+     SRC_URI="ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-1.4.9.tar.bz2"
+     SRC_URI[md5sum]="82b8e714b90674896570968f70ca778b"
+                </literallayout>
+                You can generate the <filename>md5</filename> or <filename>sha256</filename> sums
+                by using the <filename>md5sum</filename> or <filename>sha256sum</filename> commands
+                with the target file as the only argument.
+                Here is an example:
+                <literallayout class='monospaced'>
+     $ md5sum mtd-utils-1.4.9.tar.bz2
+     82b8e714b90674896570968f70ca778b mtd-utils-1.4.9.tar.bz2
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='splitting-an-application-into-multiple-packages'>
+            <title>Splitting an Application into Multiple Packages</title>
+
+            <para>
+                You can use the variables
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'>PACKAGES</ulink></filename> and
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'>FILES</ulink></filename>
+                to split an application into multiple packages.
+            </para>
+
+            <para>
+                Following is an example that uses the <filename>libXpm</filename> recipe.
+                By default, this recipe generates a single package that contains the library along
+                with a few binaries.
+                You can modify the recipe to split the binaries into separate packages:
+                <literallayout class='monospaced'>
+     require xorg-lib-common.inc
+
+     DESCRIPTION = "X11 Pixmap library"
+     LICENSE = "X-BSD"
+     LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
+     DEPENDS += "libxext libsm libxt"
+     PR = "r3"
+     PE = "1"
+
+     XORG_PN = "libXpm"
+
+     PACKAGES =+ "sxpm cxpm"
+     FILES_cxpm = "${bindir}/cxpm"
+     FILES_sxpm = "${bindir}/sxpm"
+                </literallayout>
+            </para>
+
+            <para>
+                In the previous example, we want to ship the <filename>sxpm</filename>
+                and <filename>cxpm</filename> binaries in separate packages.
+                Since <filename>bindir</filename> would be packaged into the main
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
+                package by default, we prepend the <filename>PACKAGES</filename>
+                variable so additional package names are added to the start of list.
+                This results in the extra <filename>FILES_*</filename>
+                variables then containing information that define which files and
+                directories go into which packages.
+                Files included by earlier packages are skipped by latter packages.
+                Thus, the main <filename>PN</filename> package
+                does not include the above listed files.
+            </para>
+        </section>
+
+        <section id='usingpoky-extend-addpkg-postinstalls'>
+            <title>Post-Installation Scripts</title>
+
+            <para>
+                To add a post-installation script to a package, add a
+                <filename>pkg_postinst_PACKAGENAME()</filename> function to the
+                <filename>.bb</filename> file and use
+                <filename>PACKAGENAME</filename> as the name of the package you want to attach to the
+                <filename>postinst</filename> script.
+                Normally,
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'>PN</ulink></filename>
+                can be used, which automatically expands to <filename>PACKAGENAME</filename>.
+                A post-installation function has the following structure:
+                <literallayout class='monospaced'>
+     pkg_postinst_PACKAGENAME () {
+     #!/bin/sh -e
+     # Commands to carry out
+     }
+                </literallayout>
+            </para>
+
+            <para>
+                The script defined in the post-installation function is called when the
+                root filesystem is created.
+                If the script succeeds, the package is marked as installed.
+                If the script fails, the package is marked as unpacked and the script is
+                executed when the image boots again.
+            </para>
+
+            <para>
+                Sometimes it is necessary for the execution of a post-installation
+                script to be delayed until the first boot.
+                For example, the script might need to be executed on the device itself.
+                To delay script execution until boot time, use the following structure in the
+                post-installation script:
+                <literallayout class='monospaced'>
+     pkg_postinst_PACKAGENAME () {
+     #!/bin/sh -e
+     if [ x"$D" = "x" ]; then
+          # Actions to carry out on the device go here
+     else
+          exit 1
+     fi
+     }
+                </literallayout>
+            </para>
+
+            <para>
+                The previous example delays execution until the image boots again because the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'>D</ulink></filename>
+                variable points
+                to the directory containing the image when the root filesystem is created at build time but
+                is unset when executed on the first boot.
+            </para>
+        </section>
+    </section>
+
+    <section id="platdev-newmachine">
+        <title>Adding a New Machine</title>
+
+        <para>
+            Adding a new machine to the Yocto Project is a straightforward process.
+            This section provides information that gives you an idea of the changes you must make.
+            The information covers adding machines similar to those the Yocto Project already supports.
+            Although well within the capabilities of the Yocto Project, adding a totally new architecture
+            might require
+            changes to <filename>gcc/eglibc</filename> and to the site information, which is
+            beyond the scope of this manual.
+        </para>
+
+        <para>
+            For a complete example that shows how to add a new machine,
+            see the
+            "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
+            in the Yocto Project Board Support Package (BSP) Developer's Guide.
+        </para>
+
+        <section id="platdev-newmachine-conffile">
+            <title>Adding the Machine Configuration File</title>
+
+            <para>
+                To add a machine configuration, you need to add a <filename>.conf</filename> file
+                with details of the device being added to the <filename>conf/machine/</filename> file.
+                The name of the file determines the name the OpenEmbedded build system
+                uses to reference the new machine.
+            </para>
+
+            <para>
+                The most important variables to set in this file are as follows:
+                <itemizedlist>
+                    <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_ARCH'>TARGET_ARCH</ulink></filename>
+                        (e.g. "arm")</para></listitem>
+                    <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</ulink>_virtual/kernel</filename>
+                        (see below)</para></listitem>
+                    <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_FEATURES'>MACHINE_FEATURES</ulink></filename>
+                        (e.g. "apm screen wifi")</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                You might also need these variables:
+                <itemizedlist>
+                    <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SERIAL_CONSOLES'>SERIAL_CONSOLES</ulink></filename>
+                        (e.g. "115200 ttyS0")</para></listitem>
+                    <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_IMAGETYPE'>KERNEL_IMAGETYPE</ulink></filename>
+                        (e.g. "zImage")</para></listitem>
+                    <listitem><para><filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FSTYPES'>IMAGE_FSTYPES</ulink></filename>
+                        (e.g. "tar.gz jffs2")</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                You can find full details on these variables in the reference section.
+                You can leverage many existing machine <filename>.conf</filename> files from
+                <filename>meta/conf/machine/</filename>.
+            </para>
+        </section>
+
+        <section id="platdev-newmachine-kernel">
+            <title>Adding a Kernel for the Machine</title>
+
+            <para>
+                The OpenEmbedded build system needs to be able to build a kernel for the machine.
+                You need to either create a new kernel recipe for this machine, or extend an
+                existing recipe.
+                You can find several kernel examples in the
+                Source Directory at <filename>meta/recipes-kernel/linux</filename>
+                that you can use as references.
+            </para>
+
+            <para>
+                If you are creating a new recipe, normal recipe-writing rules apply for setting
+                up a
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>.
+                Thus, you need to specify any necessary patches and set
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> to point at the source code.
+                You need to create a <filename>configure</filename> task that configures the
+                unpacked kernel with a defconfig.
+                You can do this by using a <filename>make defconfig</filename> command or,
+                more commonly, by copying in a suitable <filename>defconfig</filename> file and and then running
+                <filename>make oldconfig</filename>.
+                By making use of <filename>inherit kernel</filename> and potentially some of the
+                <filename>linux-*.inc</filename> files, most other functionality is
+                centralized and the the defaults of the class normally work well.
+            </para>
+
+            <para>
+                If you are extending an existing kernel, it is usually a matter of adding a
+                suitable defconfig file.
+                The file needs to be added into a location similar to defconfig files
+                used for other machines in a given kernel.
+                A possible way to do this is by listing the file in the
+                <filename>SRC_URI</filename> and adding the machine to the expression in
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'>COMPATIBLE_MACHINE</ulink></filename>:
+                <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE = '(qemux86|qemumips)'
+                </literallayout>
+            </para>
+        </section>
+
+        <section id="platdev-newmachine-formfactor">
+            <title>Adding a Formfactor Configuration File</title>
+
+            <para>
+                A formfactor configuration file provides information about the
+                target hardware for which the image is being built and information that
+                the build system cannot obtain from other sources such as the kernel.
+                Some examples of information contained in a formfactor configuration file include
+                framebuffer orientation, whether or not the system has a keyboard,
+                the positioning of the keyboard in relation to the screen, and
+                the screen resolution.
+            </para>
+
+            <para>
+                The build system uses reasonable defaults in most cases.
+                However, if customization is
+                necessary, you need to create a <filename>machconfig</filename> file
+                in the <filename>meta/recipes-bsp/formfactor/files</filename>
+                directory.
+                This directory contains directories for specific machines such as
+                <filename>qemuarm</filename> and <filename>qemux86</filename>.
+                For information about the settings available and the defaults, see the
+                <filename>meta/recipes-bsp/formfactor/files/config</filename> file found in the
+                same area.
+            </para>
+
+            <para>
+                Following is an example for qemuarm:
+                <literallayout class='monospaced'>
+     HAVE_TOUCHSCREEN=1
+     HAVE_KEYBOARD=1
+
+     DISPLAY_CAN_ROTATE=0
+     DISPLAY_ORIENTATION=0
+     #DISPLAY_WIDTH_PIXELS=640
+     #DISPLAY_HEIGHT_PIXELS=480
+     #DISPLAY_BPP=16
+     DISPLAY_DPI=150
+     DISPLAY_SUBPIXEL_ORDER=vrgb
+                </literallayout>
+            </para>
+        </section>
+    </section>
+
+    <section id="platdev-working-with-libraries">
+        <title>Working With Libraries</title>
+
+        <para>
+            Libraries are an integral part of your system.
+            This section describes some common practices you might find
+            helpful when working with libraries to build your system:
+            <itemizedlist>
+                <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
+                    </para></listitem>
+                <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link>
+                    </para></listitem>
+                <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <section id='including-static-library-files'>
+            <title>Including Static Library Files</title>
+
+            <para>
+                If you are building a library and the library offers static linking, you can control
+                which static library files (<filename>*.a</filename> files) get included in the
+                built library.
+            </para>
+
+            <para>
+                The <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
+                and <ulink url='&YOCTO_DOCS_REF_URL;#var-FILES'><filename>FILES_*</filename></ulink>
+                variables in the
+                <filename>meta/conf/bitbake.conf</filename> configuration file define how files installed
+                by the <filename>do_install</filename> task are packaged.
+                By default, the <filename>PACKAGES</filename> variable contains
+                <filename>${PN}-staticdev</filename>, which includes all static library files.
+                <note>
+                    Some previously released versions of the Yocto Project
+                    defined the static library files through
+                    <filename>${PN}-dev</filename>.
+                </note>
+                Following, is part of the BitBake configuration file.
+                You can see where the static library files are defined:
+                <literallayout class='monospaced'>
+     PACKAGES = "${PN}-dbg ${PN} ${PN}-doc ${PN}-dev ${PN}-staticdev ${PN}-locale"
+     PACKAGES_DYNAMIC = "${PN}-locale-*"
+     FILES = ""
+
+     FILES_${PN} = "${bindir}/* ${sbindir}/* ${libexecdir}/* ${libdir}/lib*${SOLIBS} \
+                 ${sysconfdir} ${sharedstatedir} ${localstatedir} \
+                 ${base_bindir}/* ${base_sbindir}/* \
+                 ${base_libdir}/*${SOLIBS} \
+                 ${datadir}/${BPN} ${libdir}/${BPN}/* \
+                 ${datadir}/pixmaps ${datadir}/applications \
+                 ${datadir}/idl ${datadir}/omf ${datadir}/sounds \
+                 ${libdir}/bonobo/servers"
+
+     FILES_${PN}-doc = "${docdir} ${mandir} ${infodir} ${datadir}/gtk-doc \
+                 ${datadir}/gnome/help"
+     SECTION_${PN}-doc = "doc"
+
+     FILES_${PN}-dev = "${includedir} ${libdir}/lib*${SOLIBSDEV} ${libdir}/*.la \
+                     ${libdir}/*.o ${libdir}/pkgconfig ${datadir}/pkgconfig \
+                     ${datadir}/aclocal ${base_libdir}/*.o"
+     SECTION_${PN}-dev = "devel"
+     ALLOW_EMPTY_${PN}-dev = "1"
+     RDEPENDS_${PN}-dev = "${PN} (= ${EXTENDPKGV})"
+
+     FILES_${PN}-staticdev = "${libdir}/*.a ${base_libdir}/*.a"
+     SECTION_${PN}-staticdev = "devel"
+     RDEPENDS_${PN}-staticdev = "${PN}-dev (= ${EXTENDPKGV})"
+                </literallayout>
+            </para>
+        </section>
+
+        <section id="combining-multiple-versions-library-files-into-one-image">
+            <title>Combining Multiple Versions of Library Files into One Image</title>
+
+            <para>
+                The build system offers the ability to build libraries with different
+                target optimizations or architecture formats and combine these together
+                into one system image.
+                You can link different binaries in the image
+                against the different libraries as needed for specific use cases.
+                This feature is called "Multilib."
+            </para>
+
+            <para>
+                An example would be where you have most of a system compiled in 32-bit
+                mode using 32-bit libraries, but you have something large, like a database
+                engine, that needs to be a 64-bit application and uses 64-bit libraries.
+                Multilib allows you to get the best of both 32-bit and 64-bit libraries.
+            </para>
+
+            <para>
+                While the Multilib feature is most commonly used for 32 and 64-bit differences,
+                the approach the build system uses facilitates different target optimizations.
+                You could compile some binaries to use one set of libraries and other binaries
+                to use other different sets of libraries.
+                The libraries could differ in architecture, compiler options, or other
+                optimizations.
+            </para>
+
+            <para>
+                This section overviews the Multilib process only.
+                For more details on how to implement Multilib, see the
+                <ulink url='&YOCTO_WIKI_URL;/wiki/Multilib'>Multilib</ulink> wiki
+                page.
+            </para>
+
+            <para>
+                Aside from this wiki page, several examples exist in the
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/tree/meta-skeleton'><filename>meta-skeleton</filename></ulink>
+                layer found in the
+               <link linkend='source-directory'>Source Directory</link>:
+                <itemizedlist>
+                    <listitem><para><filename>conf/multilib-example.conf</filename>
+                        configuration file</para></listitem>
+                    <listitem><para><filename>conf/multilib-example2.conf</filename>
+                        configuration file</para></listitem>
+                    <listitem><para><filename>recipes-multilib/images/core-image-multilib-example.bb</filename>
+                        recipe</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <section id='preparing-to-use-multilib'>
+                <title>Preparing to Use Multilib</title>
+
+                <para>
+                    User-specific requirements drive the Multilib feature.
+                    Consequently, there is no one "out-of-the-box" configuration that likely
+                    exists to meet your needs.
+                </para>
+
+                <para>
+                    In order to enable Multilib, you first need to ensure your recipe is
+                    extended to support multiple libraries.
+                    Many standard recipes are already extended and support multiple libraries.
+                    You can check in the <filename>meta/conf/multilib.conf</filename>
+                    configuration file in the
+                    <link linkend='source-directory'>Source Directory</link> to see how this is
+                    done using the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-BBCLASSEXTEND'><filename>BBCLASSEXTEND</filename></ulink>
+                    variable.
+                    Eventually, all recipes will be covered and this list will be unneeded.
+                </para>
+
+                <para>
+                    For the most part, the Multilib class extension works automatically to
+                    extend the package name from <filename>${PN}</filename> to
+                    <filename>${MLPREFIX}${PN}</filename>, where <filename>MLPREFIX</filename>
+                    is the particular multilib (e.g. "lib32-" or "lib64-").
+                    Standard variables such as
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>,
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-RPROVIDES'><filename>RPROVIDES</filename></ulink>,
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>,
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>,
+                    and <filename>PACKAGES_DYNAMIC</filename> are automatically extended by the system.
+                    If you are extending any manual code in the recipe, you can use the
+                    <filename>${MLPREFIX}</filename> variable to ensure those names are extended
+                    correctly.
+                    This automatic extension code resides in <filename>multilib.bbclass</filename>.
+                </para>
+            </section>
+
+            <section id='using-multilib'>
+                <title>Using Multilib</title>
+
+                <para>
+                    After you have set up the recipes, you need to define the actual
+                    combination of multiple libraries you want to build.
+                    You accomplish this through your <filename>local.conf</filename>
+                    configuration file in the
+                    <link linkend='build-directory'>Build Directory</link>.
+                    An example configuration would be as follows:
+                    <literallayout class='monospaced'>
+     MACHINE = "qemux86-64"
+     require conf/multilib.conf
+     MULTILIBS = "multilib:lib32"
+     DEFAULTTUNE_virtclass-multilib-lib32 = "x86"
+     IMAGE_INSTALL = "lib32-connman"
+                    </literallayout>
+                    This example enables an
+                    additional library named <filename>lib32</filename> alongside the
+                    normal target packages.
+                    When combining these "lib32" alternatives, the example uses "x86" for tuning.
+                    For information on this particular tuning, see
+                    <filename>meta/conf/machine/include/ia32/arch-ia32.inc</filename>.
+                </para>
+
+                <para>
+                    The example then includes <filename>lib32-connman</filename>
+                    in all the images, which illustrates one method of including a
+                    multiple library dependency.
+                    You can use a normal image build to include this dependency,
+                    for example:
+                    <literallayout class='monospaced'>
+     $ bitbake core-image-sato
+                    </literallayout>
+                    You can also build Multilib packages specifically with a command like this:
+                    <literallayout class='monospaced'>
+     $  bitbake lib32-connman
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='additional-implementation-details'>
+                <title>Additional Implementation Details</title>
+
+                <para>
+                    Different packaging systems have different levels of native Multilib
+                    support.
+                    For the RPM Package Management System, the following implementation details
+                    exist:
+                    <itemizedlist>
+                        <listitem><para>A unique architecture is defined for the Multilib packages,
+                            along with creating a unique deploy folder under
+                            <filename>tmp/deploy/rpm</filename> in the
+                            <link linkend='build-directory'>Build Directory</link>.
+                            For example, consider <filename>lib32</filename> in a
+                            <filename>qemux86-64</filename> image.
+                            The possible architectures in the system are "all", "qemux86_64",
+                            "lib32_qemux86_64", and "lib32_x86".</para></listitem>
+                        <listitem><para>The <filename>${MLPREFIX}</filename> variable is stripped from
+                            <filename>${PN}</filename> during RPM packaging.
+                            The naming for a normal RPM package and a Multilib RPM package in a
+                            <filename>qemux86-64</filename> system resolves to something similar to
+                            <filename>bash-4.1-r2.x86_64.rpm</filename> and
+                            <filename>bash-4.1.r2.lib32_x86.rpm</filename>, respectively.
+                            </para></listitem>
+                        <listitem><para>When installing a Multilib image, the RPM backend first
+                            installs the base image and then installs the Multilib libraries.
+                            </para></listitem>
+                        <listitem><para>The build system relies on RPM to resolve the identical files in the
+                            two (or more) Multilib packages.</para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    For the IPK Package Management System, the following implementation details exist:
+                    <itemizedlist>
+                        <listitem><para>The <filename>${MLPREFIX}</filename> is not stripped from
+                            <filename>${PN}</filename> during IPK packaging.
+                            The naming for a normal RPM package and a Multilib IPK package in a
+                            <filename>qemux86-64</filename> system resolves to something like
+                            <filename>bash_4.1-r2.x86_64.ipk</filename> and
+                            <filename>lib32-bash_4.1-rw_x86.ipk</filename>, respectively.
+                            </para></listitem>
+                        <listitem><para>The IPK deploy folder is not modified with
+                            <filename>${MLPREFIX}</filename> because packages with and without
+                            the Multilib feature can exist in the same folder due to the
+                            <filename>${PN}</filename> differences.</para></listitem>
+                        <listitem><para>IPK defines a sanity check for Multilib installation
+                            using certain rules for file comparison, overridden, etc.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+        </section>
+
+        <section id='installing-multiple-versions-of-the-same-library'>
+            <title>Installing Multiple Versions of the Same Library</title>
+
+            <para>
+                Situations can exist where you need to install and use
+                multiple versions of the same library on the same system
+                at the same time.
+                These situations almost always exist when a library API
+                changes and you have multiple pieces of software that
+                depend on the separate versions of the library.
+                To accommodate these situations, you can install multiple
+                versions of the same library in parallel on the same system.
+            </para>
+
+            <para>
+                The process is straight forward as long as the libraries use
+                proper versioning.
+                With properly versioned libraries, all you need to do to
+                individually specify the libraries is create separate,
+                appropriately named recipes where the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
+                name includes a portion that differentiates each library version
+                (e.g.the major part of the version number).
+                Thus, instead of having a single recipe that loads one version
+                of a library (e.g. <filename>clutter</filename>), you provide
+                multiple recipes that result in different versions
+                of the libraries you want.
+                As an example, the following two recipes would allow the
+                two separate versions of the <filename>clutter</filename>
+                library to co-exist on the same system:
+                <literallayout class='monospaced'>
+     clutter-1.6_1.6.20.bb
+     clutter-1.8_1.8.4.bb
+                </literallayout>
+                Additionally, if you have other recipes that depend on a given
+                library, you need to use the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+                variable to create the dependency.
+                Continuing with the same example, if you want to have a recipe
+                depend on the 1.8 version of the <filename>clutter</filename>
+                library, use the following in your recipe:
+                <literallayout class='monospaced'>
+     DEPENDS = "clutter-1.8"
+                </literallayout>
+            </para>
+        </section>
+    </section>
+
+    <section id='configuring-the-kernel'>
+        <title>Configuring the Kernel</title>
+
+        <para>
+            Configuring the Yocto Project kernel consists of making sure the <filename>.config</filename>
+            file has all the right information in it for the image you are building.
+            You can use the <filename>menuconfig</filename> tool and configuration fragments to
+            make sure your <filename>.config</filename> file is just how you need it.
+            This section describes how to use <filename>menuconfig</filename>, create and use
+            configuration fragments, and how to interactively tweak your <filename>.config</filename>
+            file to create the leanest kernel configuration file possible.
+        </para>
+
+        <para>
+            For more information on kernel configuration, see the
+            "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#changing-the-configuration'>Changing the Configuration</ulink>"
+            section in the Yocto Project Linux Kernel Development Manual.
+        </para>
+
+        <section id='using-menuconfig'>
+            <title>Using&nbsp;&nbsp;<filename>menuconfig</filename></title>
+
+            <para>
+                The easiest way to define kernel configurations is to set them through the
+                <filename>menuconfig</filename> tool.
+                This tool provides an interactive method with which
+                to set kernel configurations.
+                For general information on <filename>menuconfig</filename>, see
+                <ulink url='http://en.wikipedia.org/wiki/Menuconfig'></ulink>.
+            </para>
+
+            <para>
+                To use the <filename>menuconfig</filename> tool in the Yocto Project development
+                environment, you must build the tool using BitBake.
+                Thus, the environment must be set up using the
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                or
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
+                script found in the
+                <link linkend='build-directory'>Build Directory</link>.
+                The following commands build and invoke <filename>menuconfig</filename> assuming the
+                <link linkend='source-directory'>Source Directory</link>
+                top-level folder is <filename>~/poky</filename>:
+                <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ source oe-init-build-env
+     $ bitbake linux-yocto -c menuconfig
+                </literallayout>
+                Once <filename>menuconfig</filename> comes up, its standard interface allows you to
+                interactively examine and configure all the kernel configuration parameters.
+                After making your changes, simply exit the tool and save your changes to
+                create an updated version of the <filename>.config</filename> configuration file.
+            </para>
+
+            <para>
+                Consider an example that configures the <filename>linux-yocto-3.4</filename>
+                kernel.
+                The OpenEmbedded build system recognizes this kernel as
+                <filename>linux-yocto</filename>.
+                Thus, the following commands from the shell in which you previously sourced the
+                environment initialization script cleans the shared state cache and the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
+                directory and then builds and launches <filename>menuconfig</filename>:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                </literallayout>
+            </para>
+
+            <para>
+                Once <filename>menuconfig</filename> launches, use the interface
+                to navigate through the selections to find the configuration settings in
+                which you are interested.
+                For example, consider the <filename>CONFIG_SMP</filename> configuration setting.
+                You can find it at <filename>Processor Type and Features</filename> under
+                the configuration selection <filename>Symmetric Multi-processing Support</filename>.
+                After highlighting the selection, use the arrow keys to select or deselect
+                the setting.
+                When you are finished with all your selections, exit out and save them.
+            </para>
+
+            <para>
+                Saving the selections updates the <filename>.config</filename> configuration file.
+                This is the file that the OpenEmbedded build system uses to configure the
+                kernel during the build.
+                You can find and examine this file in the Build Directory in
+                <filename>tmp/work/</filename>.
+                The actual <filename>.config</filename> is located in the area where the
+                specific kernel is built.
+                For example, if you were building a Linux Yocto kernel based on the
+                Linux 3.4 kernel and you were building a QEMU image targeted for
+                <filename>x86</filename> architecture, the
+                <filename>.config</filename> file would be located here:
+                <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-3.4.11+git1+84f...
+        ...656ed30-r1/linux-qemux86-standard-build
+                </literallayout>
+                <note>
+                    The previous example directory is artificially split and many of the characters
+                    in the actual filename are omitted in order to make it more readable.
+                    Also, depending on the kernel you are using, the exact pathname
+                    for <filename>linux-yocto-3.4...</filename> might differ.
+                </note>
+            </para>
+
+            <para>
+                Within the <filename>.config</filename> file, you can see the kernel settings.
+                For example, the following entry shows that symmetric multi-processor support
+                is not set:
+                <literallayout class='monospaced'>
+     # CONFIG_SMP is not set
+                </literallayout>
+            </para>
+
+            <para>
+                A good method to isolate changed configurations is to use a combination of the
+                <filename>menuconfig</filename> tool and simple shell commands.
+                Before changing configurations with <filename>menuconfig</filename>, copy the
+                existing <filename>.config</filename> and rename it to something else,
+                use <filename>menuconfig</filename> to make
+                as many changes an you want and save them, then compare the renamed configuration
+                file against the newly created file.
+                You can use the resulting differences as your base to create configuration fragments
+                to permanently save in your kernel layer.
+                <note>
+                    Be sure to make a copy of the <filename>.config</filename> and don't just
+                    rename it.
+                    The build system needs an existing <filename>.config</filename>
+                    from which to work.
+                </note>
+            </para>
+        </section>
+
+        <section id='creating-config-fragments'>
+            <title>Creating Configuration Fragments</title>
+
+            <para>
+                Configuration fragments are simply kernel options that appear in a file
+                placed where the OpenEmbedded build system can find and apply them.
+                Syntactically, the configuration statement is identical to what would appear
+                in the <filename>.config</filename> file, which is in the
+                <link linkend='build-directory'>Build Directory</link> in
+                <filename>tmp/work/&lt;arch&gt;-poky-linux/linux-yocto-&lt;release-specific-string&gt;/linux-&lt;arch&gt;-&lt;build-type&gt;</filename>.
+            </para>
+
+            <para>
+                It is simple to create a configuration fragment.
+                For example, issuing the following from the shell creates a configuration fragment
+                file named <filename>my_smp.cfg</filename> that enables multi-processor support
+                within the kernel:
+                <literallayout class='monospaced'>
+     $ echo "CONFIG_SMP=y" >> my_smp.cfg
+                </literallayout>
+                <note>
+                    All configuration files must use the <filename>.cfg</filename> extension in order
+                    for the OpenEmbedded build system to recognize them as a configuration fragment.
+                </note>
+            </para>
+
+            <para>
+                Where do you put your configuration files?
+                You can place these configuration files in the same area pointed to by
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
+                The OpenEmbedded build system will pick up the configuration and add it to the
+                kernel's configuration.
+                For example, suppose you had a set of configuration options in a file called
+                <filename>myconfig.cfg</filename>.
+                If you put that file inside a directory named <filename>/linux-yocto</filename>
+                that resides in the same directory as the kernel's append file and then add
+                a <filename>SRC_URI</filename> statement such as the following to the kernel's append file,
+                those configuration options will be picked up and applied when the kernel is built.
+                <literallayout class='monospaced'>
+     SRC_URI += "file://myconfig.cfg"
+                </literallayout>
+            </para>
+
+            <para>
+                As mentioned earlier, you can group related configurations into multiple files and
+                name them all in the <filename>SRC_URI</filename> statement as well.
+                For example, you could group separate configurations specifically for Ethernet and graphics
+                into their own files and add those by using a <filename>SRC_URI</filename> statement like the
+                following in your append file:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://myconfig.cfg \
+            file://eth.cfg \
+            file://gfx.cfg"
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='fine-tuning-the-kernel-configuration-file'>
+            <title>Fine-Tuning the Kernel Configuration File</title>
+
+            <para>
+                You can make sure the <filename>.config</filename> file is as lean or efficient as
+                possible by reading the output of the kernel configuration fragment audit,
+                noting any issues, making changes to correct the issues, and then repeating.
+            </para>
+
+            <para>
+                As part of the kernel build process, the
+                <filename>kernel_configcheck</filename> task runs.
+                This task validates the kernel configuration by checking the final
+                <filename>.config</filename> file against the input files.
+                During the check, the task produces warning messages for the following
+                issues:
+                <itemizedlist>
+                    <listitem><para>Requested options that did not make the final
+                        <filename>.config</filename> file.</para></listitem>
+                    <listitem><para>Configuration items that appear twice in the same
+                        configuration fragment.</para></listitem>
+                    <listitem><para>Configuration items tagged as "required" were overridden.
+                        </para></listitem>
+                    <listitem><para>A board overrides a non-board specific option.</para></listitem>
+                    <listitem><para>Listed options not valid for the kernel being processed.
+                        In other words, the option does not appear anywhere.</para></listitem>
+                </itemizedlist>
+                <note>
+                    The <filename>kernel_configcheck</filename> task can also optionally report
+                    if an option is overridden during processing.
+                </note>
+            </para>
+
+            <para>
+                For each output warning, a message points to the file
+                that contains a list of the options and a pointer to the config
+                fragment that defines them.
+                Collectively, the files are the key to streamlining the configuration.
+            </para>
+
+            <para>
+                To streamline the configuration, do the following:
+                <orderedlist>
+                    <listitem><para>Start with a full configuration that you know
+                        works - it builds and boots successfully.
+                        This configuration file will be your baseline.</para></listitem>
+                    <listitem><para>Separately run the <filename>configme</filename> and
+                        <filename>kernel_configcheck</filename> tasks.</para></listitem>
+                    <listitem><para>Take the resulting list of files from the
+                        <filename>kernel_configcheck</filename> task warnings and do the following:
+                        <itemizedlist>
+                            <listitem><para>Drop values that are redefined in the fragment but do not
+                                change the final <filename>.config</filename> file.</para></listitem>
+                            <listitem><para>Analyze and potentially drop values from the
+                                <filename>.config</filename> file that override required
+                                configurations.</para></listitem>
+                            <listitem><para>Analyze and potentially remove non-board specific options.
+                                </para></listitem>
+                            <listitem><para>Remove repeated and invalid options.</para></listitem>
+                        </itemizedlist></para></listitem>
+                    <listitem><para>After you have worked through the output of the kernel configuration
+                        audit, you can re-run the <filename>configme</filename>
+                        and <filename>kernel_configcheck</filename> tasks to see the results of your
+                        changes.
+                        If you have more issues, you can deal with them as described in the
+                        previous step.</para></listitem>
+                </orderedlist>
+            </para>
+
+            <para>
+                Iteratively working through steps two through four eventually yields
+                a minimal, streamlined configuration file.
+                Once you have the best <filename>.config</filename>, you can build the Linux
+                Yocto kernel.
+            </para>
+        </section>
+    </section>
+
+    <section id="patching-the-kernel">
+        <title>Patching the Kernel</title>
+
+        <para>
+            Patching the kernel involves changing or adding configurations to an existing kernel,
+            changing or adding recipes to the kernel that are needed to support specific hardware features,
+            or even altering the source code itself.
+            <note>
+                You can use the <filename>yocto-kernel</filename> script
+                found in the <link linkend='source-directory'>Source Directory</link>
+                under <filename>scripts</filename> to manage kernel patches and configuration.
+                See the "<ulink url='&YOCTO_DOCS_BSP_URL;#managing-kernel-patches-and-config-items-with-yocto-kernel'>Managing kernel Patches and Config Items with yocto-kernel</ulink>"
+                section in the Yocto Project Board Support Packages (BSP) Developer's Guide for
+                more information.</note>
+        </para>
+
+        <para>
+            This example creates a simple patch by adding some QEMU emulator console
+            output at boot time through <filename>printk</filename> statements in the kernel's
+            <filename>calibrate.c</filename> source code file.
+            Applying the patch and booting the modified image causes the added
+            messages to appear on the emulator's console.
+        </para>
+
+        <para>
+            The example assumes a clean build exists for the <filename>qemux86</filename>
+            machine in a Source Directory named <filename>poky</filename>.
+            Furthermore, the <link linkend='build-directory'>Build Directory</link> is
+            <filename>build</filename> and is located in <filename>poky</filename> and
+            the kernel is based on the Linux 3.4 kernel.
+            For general information on how to configure the most efficient build, see the
+            "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
+            in the Yocto Project Quick Start.
+        </para>
+
+        <para>
+            Also, for more information on patching the kernel, see the
+            "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#applying-patches'>Applying Patches</ulink>"
+            section in the Yocto Project Linux Kernel Development Manual.
+        </para>
+
+        <section id='create-a-layer-for-your-changes'>
+            <title>Create a Layer for your Changes</title>
+
+            <para>
+                The first step is to create a layer so you can isolate your changes:
+                <literallayout class='monospaced'>
+     $cd ~/poky
+     $mkdir meta-mylayer
+                </literallayout>
+                Creating a directory that follows the Yocto Project layer naming
+                conventions sets up the layer for your changes.
+                The layer is where you place your configuration files, append
+                files, and patch files.
+                To learn more about creating a layer and filling it with the
+                files you need, see the "<link linkend='understanding-and-creating-layers'>Understanding
+                and Creating Layers</link>" section.
+            </para>
+        </section>
+
+        <section id='finding-the-kernel-source-code'>
+            <title>Finding the Kernel Source Code</title>
+
+            <para>
+                Each time you build a kernel image, the kernel source code is fetched
+                and unpacked into the following directory:
+                <literallayout class='monospaced'>
+     ${S}/linux
+                </literallayout>
+                See the "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
+                section and the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink> variable
+                for more information about where source is kept during a build.
+            </para>
+
+            <para>
+                For this example, we are going to patch the
+                <filename>init/calibrate.c</filename> file
+                by adding some simple console <filename>printk</filename> statements that we can
+                see when we boot the image using QEMU.
+            </para>
+        </section>
+
+        <section id='creating-the-patch'>
+            <title>Creating the Patch</title>
+
+            <para>
+                Two methods exist by which you can create the patch:
+                <link linkend='using-a-git-workflow'>Git workflow</link> and
+                <link linkend='using-a-quilt-workflow'>Quilt workflow</link>.
+                For kernel patches, the Git workflow is more appropriate.
+                This section assumes the Git workflow and shows the steps specific to
+                this example.
+                <orderedlist>
+                    <listitem><para><emphasis>Change the working directory</emphasis>:
+                        Change to where the kernel source code is before making
+                        your edits to the <filename>calibrate.c</filename> file:
+                        <literallayout class='monospaced'>
+     $ cd ~/poky/build/tmp/work/qemux86-poky-linux/linux-yocto-${PV}-${PR}/linux
+                        </literallayout>
+                        Because you are working in an established Git repository,
+                        you must be in this directory in order to commit your changes
+                        and create the patch file.
+                        <note>The <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink> and
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> variables
+                            represent the version and revision for the
+                            <filename>linux-yocto</filename> recipe.
+                            The <filename>PV</filename> variable includes the Git meta and machine
+                            hashes, which make the directory name longer than you might
+                            expect.
+                        </note></para></listitem>
+                    <listitem><para><emphasis>Edit the source file</emphasis>:
+                        Edit the <filename>init/calibrate.c</filename> file to have the
+                        following changes:
+                        <literallayout class='monospaced'>
+     void __cpuinit calibrate_delay(void)
+     {
+         unsigned long lpj;
+         static bool printed;
+         int this_cpu = smp_processor_id();
+
+         printk("*************************************\n");
+         printk("*                                   *\n");
+         printk("*        HELLO YOCTO KERNEL         *\n");
+         printk("*                                   *\n");
+         printk("*************************************\n");
+
+        if (per_cpu(cpu_loops_per_jiffy, this_cpu)) {
+               .
+               .
+               .
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Stage and commit your changes</emphasis>:
+                        These Git commands display the modified file, stage it, and then
+                        commit the file:
+                        <literallayout class='monospaced'>
+     $ git status
+     $ git add init/calibrate.c
+     $ git commit -m "calibrate: Add printk example"
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Generate the patch file</emphasis>:
+                        This Git command creates the a patch file named
+                        <filename>0001-calibrate-Add-printk-example.patch</filename>
+                        in the current directory.
+                        <literallayout class='monospaced'>
+     $ git format-patch -1
+                        </literallayout>
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='set-up-your-layer-for-the-build'>
+            <title>Set Up Your Layer for the Build</title>
+
+            <para>These steps get your layer set up for the build:
+                <orderedlist>
+                    <listitem><para><emphasis>Create additional structure</emphasis>:
+                        Create the additional layer structure:
+                        <literallayout class='monospaced'>
+     $ cd ~/poky/meta-mylayer
+     $ mkdir conf
+     $ mkdir recipes-kernel
+     $ mkdir recipes-kernel/linux
+     $ mkdir recipes-kernel/linux/linux-yocto
+                         </literallayout>
+                         The <filename>conf</filename> directory holds your configuration files, while the
+                         <filename>recipes-kernel</filename> directory holds your append file and
+                         your patch file.</para></listitem>
+                    <listitem><para><emphasis>Create the layer configuration file</emphasis>:
+                        Move to the <filename>meta-mylayer/conf</filename> directory and create
+                        the <filename>layer.conf</filename> file as follows:
+                        <literallayout class='monospaced'>
+     # We have a conf and classes directory, add to BBPATH
+     BBPATH .= ":${LAYERDIR}"
+
+     # We have recipes-* directories, add to BBFILES
+     BBFILES += "${LAYERDIR}/recipes-*/*/*.bb \
+                 ${LAYERDIR}/recipes-*/*/*.bbappend"
+
+     BBFILE_COLLECTIONS += "mylayer"
+     BBFILE_PATTERN_mylayer = "^${LAYERDIR}/"
+     BBFILE_PRIORITY_mylayer = "5"
+                         </literallayout>
+                         Notice <filename>mylayer</filename> as part of the last three
+                         statements.</para></listitem>
+                    <listitem><para><emphasis>Create the kernel recipe append file</emphasis>:
+                        Move to the <filename>meta-mylayer/recipes-kernel/linux</filename> directory and create
+                        the <filename>linux-yocto_3.4.bbappend</filename> file as follows:
+                        <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+
+     SRC_URI += "file://0001-calibrate-Add-printk-example.patch"
+
+     PRINC := "${@int(PRINC) + 1}"
+                        </literallayout>
+                        The <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                        and <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                        statements enable the OpenEmbedded build system to find the patch file.
+                        For more information on using append files, see the
+                        "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
+                        section.
+                        </para></listitem>
+                    <listitem><para><emphasis>Put the patch file in your layer</emphasis>:
+                        Move the <filename>0001-calibrate-Add-printk-example.patch</filename> file to
+                        the <filename>meta-mylayer/recipes-kernel/linux/linux-yocto</filename>
+                        directory.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='set-up-for-the-build'>
+            <title>Set Up for the Build</title>
+
+            <para>
+                Do the following to make sure the build parameters are set up for the example.
+                Once you set up these build parameters, they do not have to change unless you
+                change the target architecture of the machine you are building:
+                <itemizedlist>
+                    <listitem><para><emphasis>Build for the correct target architecture:</emphasis> Your
+                        selected <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                        definition within the <filename>local.conf</filename> file in the
+                        <link linkend='build-directory'>Build Directory</link>
+                        specifies the target architecture used when building the Linux kernel.
+                        By default, <filename>MACHINE</filename> is set to
+                        <filename>qemux86</filename>, which specifies a 32-bit
+                        <trademark class='registered'>Intel</trademark> Architecture
+                        target machine suitable for the QEMU emulator.</para></listitem>
+                    <listitem><para><emphasis>Identify your <filename>meta-mylayer</filename>
+                        layer:</emphasis> The
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink>
+                        variable in the
+                        <filename>bblayers.conf</filename> file found in the
+                        <filename>poky/build/conf</filename> directory needs to have the path to your local
+                        <filename>meta-mylayer</filename> layer.
+                        By default, the <filename>BBLAYERS</filename> variable contains paths to
+                        <filename>meta</filename>, <filename>meta-yocto</filename>, and
+                        <filename>meta-yocto-bsp</filename> in the
+                        <filename>poky</filename> Git repository.
+                        Add the path to your <filename>meta-mylayer</filename> location:
+                        <literallayout class='monospaced'>
+     BBLAYERS ?= " \
+       $HOME/poky/meta \
+       $HOME/poky/meta-yocto \
+       $HOME/poky/meta-yocto-bsp \
+       $HOME/poky/meta-mylayer \
+       "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+       $HOME/poky/meta \
+       $HOME/poky/meta-yocto \
+       "
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='build-the-modified-qemu-kernel-image'>
+            <title>Build the Modified QEMU Kernel Image</title>
+
+            <para>
+                The following steps build your modified kernel image:
+                <orderedlist>
+                    <listitem><para><emphasis>Be sure your build environment is initialized</emphasis>:
+                        Your environment should be set up since you previously sourced
+                        the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                        script.
+                        If it is not, source the script again from <filename>poky</filename>.
+                        <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ source &OE_INIT_FILE;
+                        </literallayout>
+                        </para></listitem>
+                    <listitem><para><emphasis>Clean up</emphasis>:
+                        Be sure to clean the shared state out by running the
+                        <filename>cleansstate</filename> BitBake task as follows from your Build Directory:
+                        <literallayout class='monospaced'>
+     $ bitbake -c cleansstate linux-yocto
+                        </literallayout></para>
+                        <para><note>Never remove any files by hand from the <filename>tmp/deploy</filename>
+                        directory inside the
+                        <link linkend='build-directory'>Build Directory</link>.
+                        Always use the various BitBake clean tasks to clear out previous
+                        build artifacts.
+                        </note></para></listitem>
+                    <listitem><para><emphasis>Build the image</emphasis>:
+                        Next, build the kernel image using this command:
+                        <literallayout class='monospaced'>
+     $ bitbake -k linux-yocto
+                        </literallayout></para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='boot-the-image-and-verify-your-changes'>
+            <title>Boot the Image and Verify Your Changes</title>
+
+            <para>
+                These steps boot the image and allow you to see the changes
+                <orderedlist>
+                    <listitem><para><emphasis>Boot the image</emphasis>:
+                        Boot the modified image in the QEMU emulator
+                        using this command:
+                        <literallayout class='monospaced'>
+     $ runqemu qemux86
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Verify the changes</emphasis>:
+                        Log into the machine using <filename>root</filename> with no password and then
+                        use the following shell command to scroll through the console's boot output.
+                        <literallayout class='monospaced'>
+     # dmesg | less
+                        </literallayout>
+                        You should see the results of your <filename>printk</filename> statements
+                        as part of the output.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+    </section>
+
+    <section id='creating-your-own-distribution'>
+        <title>Creating Your Own Distribution</title>
+
+        <para>
+            When you build an image using the Yocto Project and
+            do not alter any distribution
+            <link linkend='metadata'>Metadata</link>, you are creating a
+            Poky distribution.
+            If you wish to gain more control over package alternative
+            selections, compile-time options, and other low-level
+            configurations, you can create your own distribution.
+        </para>
+
+        <para>
+            To create your own distribution, the basic steps consist of
+            creating your own distribution layer, creating your own
+            distribution configuration file, and then adding any needed
+            code and Metadata to the layer.
+            The following steps provide some more detail:
+            <itemizedlist>
+                <listitem><para><emphasis>Create a layer for your new distro:</emphasis>
+                    Create your distribution layer so that you can keep your
+                    Metadata and code for the distribution separate.
+                    It is strongly recommended that you create and use your own
+                    layer for configuration and code.
+                    Using your own layer as compared to just placing
+                    configurations in a <filename>local.conf</filename>
+                    configuration file makes it easier to reproduce the same
+                    build configuration when using multiple build machines.
+                    See the
+                    "<link linkend='creating-a-general-layer-using-the-yocto-layer-script'>Creating a General Layer Using the yocto-layer Script</link>"
+                    section for information on how to quickly set up a layer.
+                    </para></listitem>
+                <listitem><para><emphasis>Create the distribution configuration file:</emphasis>
+                    The distribution configuration file needs to be created in
+                    the <filename>conf/distro</filename> directory of your
+                    layer.
+                    You need to name it using your distribution name
+                    (e.g. <filename>mydistro.conf</filename>).</para>
+                    <para>You can split out parts of your configuration file
+                    into include files and then "require" them from within
+                    your distribution configuration file.
+                    Be sure to place the include files in the
+                    <filename>conf/distro/include</filename> directory of
+                    your layer.
+                    A common example usage of include files would be to
+                    separate out the selection of desired version and revisions
+                    for individual recipes.
+</para>
+                    <para>Your configuration file needs to set the following
+                    required variables:
+                    <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_NAME'><filename>DISTRO_NAME</filename></ulink> [required]
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_VERSION'><filename>DISTRO_VERSION</filename></ulink> [required]
+                    </literallayout>
+                    These following variables are optional and you typically
+                    set them from the distribution configuration file:
+                    <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink> [optional]
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RDEPENDS'><filename>DISTRO_EXTRA_RDEPENDS</filename></ulink> [optional]
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_EXTRA_RRECOMMENDS'><filename>DISTRO_EXTRA_RRECOMMENDS</filename></ulink> [optional]
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-TCLIBC'><filename>TCLIBC</filename></ulink> [optional]
+                    </literallayout>
+                    <tip>
+                        If you want to base your distribution configuration file
+                        on the very basic configuration from OE-Core, you
+                        can use
+                        <filename>conf/distro/defaultsetup.conf</filename> as
+                        a reference and just include variables that differ
+                        as compared to <filename>defaultsetup.conf</filename>.
+                        Alternatively, you can create a distribution
+                        configuration file from scratch using the
+                        <filename>defaultsetup.conf</filename> file
+                        or configuration files from other distributions
+                        such as Poky or Angstrom as references.
+                    </tip></para></listitem>
+                <listitem><para><emphasis>Provide miscellaneous variables:</emphasis>
+                    Be sure to define any other variables for which you want to
+                    create a default or enforce as part of the distribution
+                    configuration.
+                    You can include nearly any variable from the
+                    <filename>local.conf</filename> file.
+                    The variables you use are not limited to the list in the
+                    previous bulleted item.</para></listitem>
+                <listitem><para><emphasis>Point to Your distribution configuration file:</emphasis>
+                    In your <filename>local.conf</filename> file in the
+                    <link linkend='build-directory'>Build Directory</link>,
+                    set your
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+                    variable to point to your distribution's configuration file.
+                    For example, if your distribution's configuration file is
+                    named <filename>mydistro.conf</filename>, then you point
+                    to it as follows:
+                    <literallayout class='monospaced'>
+     DISTRO = "mydistro"
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Add more to the layer if necessary:</emphasis>
+                    Use your layer to hold other information needed for the
+                    distribution:
+                    <itemizedlist>
+                        <listitem><para>Add recipes for installing
+                            distro-specific configuration files that are not
+                            already installed by another recipe.
+                            If you have distro-specific configuration files
+                            that are included by an existing recipe, you should
+                            add a <filename>.bbappend</filename> for those.
+                            For general information and recommendations
+                            on how to add recipes to your layer, see the
+                            "<link linkend='creating-your-own-layer'>Creating Your Own Layer</link>"
+                            and
+                            "<link linkend='best-practices-to-follow-when-creating-layers'>Best Practices to Follow When Creating Layers</link>"
+                            sections.</para></listitem>
+                        <listitem><para>Add any image recipes that are specific
+                            to your distribution.</para></listitem>
+                        <listitem><para>Add a <filename>psplash</filename>
+                            append file for a branded splash screen.
+                            For information on append files, see the
+                            "<link linkend='using-bbappend-files'>Using .bbappend Files</link>"
+                            section.</para></listitem>
+                        <listitem><para>Add any other append files to make
+                            custom changes that are specific to individual
+                            recipes.</para></listitem>
+                    </itemizedlist></para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='building-a-tiny-system'>
+        <title>Building a Tiny System</title>
+
+        <para>
+            Very small distributions have some significant advantages such
+            as requiring less on-die or in-package memory (cheaper), better
+            performance through efficient cache usage, lower power requirements
+            due to less memory, faster boot times, and reduced development
+            overhead.
+            Some real-world examples where a very small distribution gives
+            you distinct advantages are digital cameras, medical devices,
+            and small headless systems.
+        </para>
+
+        <para>
+            This section presents information that shows you how you can
+            trim your distribution to even smaller sizes than the
+            <filename>poky-tiny</filename> distribution, which is around
+            5 Mbytes, that can be built out-of-the-box using the Yocto Project.
+        </para>
+
+        <section id='tiny-system-overview'>
+            <title>Overview</title>
+
+            <para>
+                The following list presents the overall steps you need to
+                consider and perform to create distributions with smaller
+                root filesystems, faster boot times, maintain your critical
+                functionality, and avoid initial RAM disks:
+                <itemizedlist>
+                    <listitem><para>Determine your goals and guiding
+                        principles.</para></listitem>
+                    <listitem><para>Understand what gives your image size.
+                        </para></listitem>
+                    <listitem><para>Reduce the size of the root filesystem.
+                        </para></listitem>
+                    <listitem><para>Reduce the size of the kernel.
+                        </para></listitem>
+                    <listitem><para>Eliminate packaging requirements.
+                        </para></listitem>
+                    <listitem><para>Look for other ways to minimize size.
+                        </para></listitem>
+                    <listitem><para>Iterate on the process.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='goals-and-guiding-principles'>
+            <title>Goals and Guiding Principles</title>
+
+            <para>
+                Before you can reach your destination, you need to know
+                where you are going.
+                Here is an example list that you can use as a guide when
+                creating very small distributions:
+                <itemizedlist>
+                    <listitem><para>Determine how much space you need
+                        (e.g. a kernel that is 1 Mbyte or less and
+                        a root filesystem that is 3 Mbytes or less).
+                        </para></listitem>
+                    <listitem><para>Find the areas that are currently
+                        taking 90% of the space and concentrate on reducing
+                        those areas.
+                        </para></listitem>
+                    <listitem><para>Do not create any difficult "hacks"
+                        to achieve your goals.</para></listitem>
+                    <listitem><para>Leverage the device-specific
+                        options.</para></listitem>
+                    <listitem><para>Work in a separate layer so that you
+                        keep changes isolated.
+                        For information on how to create layers, see
+                        the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='understand-what-gives-your-image-size'>
+            <title>Understand What Gives Your Image Size</title>
+
+            <para>
+                It is easiest to have something to start with when creating
+                your own distribution.
+                You can use the Yocto Project out-of-the-box to create the
+                <filename>poky-tiny</filename> distribution.
+                Ultimately, you will want to make changes in your own
+                distribution that are likely modeled after
+                <filename>poky-tiny</filename>.
+                <note>
+                    To use <filename>poky-tiny</filename> in your build,
+                    set the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
+                    variable in your
+                    <filename>local.conf</filename> file to "poky-tiny"
+                    as described in the
+                    "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
+                    section.
+                </note>
+            </para>
+
+            <para>
+                Understanding some memory concepts will help you reduce the
+                system size.
+                Memory consists of static, dynamic, and temporary memory.
+                Static memory is the TEXT (code), DATA (initialized data
+                in the code), and BSS (uninitialized data) sections.
+                Dynamic memory contains memory that is allocated at runtime,
+                stacks, hash tables, and so forth.
+                Temporary memory is recovered after the boot process.
+                This memory consists of memory used for decompressing
+                the kernel and for the <filename>__init__</filename>
+                functions.
+            </para>
+
+            <para>
+                To help you see where you currently are with kernel and root
+                filesystem sizes, you can use two tools found in the
+                <link linkend='source-directory'>Source Directory</link> in
+                the <filename>scripts</filename> directory:
+                <itemizedlist>
+                    <listitem><para><filename>ksize.py</filename>: Reports
+                        component sizes for the kernel build objects.
+                        </para></listitem>
+                    <listitem><para><filename>dirsize.py</filename>: Reports
+                        component sizes for the root filesystem.</para></listitem>
+                </itemizedlist>
+                This next tool and command helps you organize configuration
+                fragments and view file dependencies in a human-readable form:
+                <itemizedlist>
+                    <listitem><para><filename>merge_config.sh</filename>:
+                        Helps you manage configuration files and fragments
+                        within the kernel.
+                        With this tool, you can merge individual configuration
+                        fragments together.
+                        The tool allows you to make overrides and warns you
+                        of any missing configuration options.
+                        The tool is ideal for allowing you to iterate on
+                        configurations, create minimal configurations, and
+                        create configuration files for different machines
+                        without having to duplicate your process.</para>
+                        <para>The <filename>merge_config.sh</filename> script is
+                        part of the Linux Yocto kernel Git repository in the
+                        <filename>scripts/kconfig</filename> directory.</para>
+                        <para>For more information on configuration fragments,
+                        see the
+                        "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#generating-configuration-files'>Generating Configuration Files</ulink>"
+                        section of the Yocto Project Linux Kernel Development
+                        Manual and the "<link linkend='creating-config-fragments'>Creating Configuration Fragments</link>"
+                        section, which is in this manual.</para></listitem>
+                    <listitem><para><filename>bitbake -u depexp -g &lt;bitbake_target&gt;</filename>:
+                        Using the BitBake command with these options brings up
+                        a Dependency Explorer from which you can view file
+                        dependencies.
+                        Understanding these dependencies allows you to make
+                        informed decisions when cutting out various pieces of the
+                        kernel and root filesystem.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='trim-the-root-filesystem'>
+            <title>Trim the Root Filesystem</title>
+
+            <para>
+                The root filesystem is made up of packages for booting,
+                libraries, and applications.
+                To change things, you can configure how the packaging happens,
+                which changes the way you build them.
+                You can also tweak the filesystem itself or select a different
+                filesystem.
+            </para>
+
+            <para>
+                First, find out what is hogging your root filesystem by running the
+                <filename>dirsize.py</filename> script from your root directory:
+                <literallayout class='monospaced'>
+     $ cd &lt;root-directory-of-image&gt;
+     $ dirsize.py 100000 > dirsize-100k.log
+     $ cat dirsize-100k.log
+                </literallayout>
+                You can apply a filter to the script to ignore files under
+                a certain size.
+                This example filters out anything below 100 Kbytes.
+                The sizes reported by the tool are uncompressed and thus,
+                will be smaller by a relatively constant factor in a
+                compressed root filesystem.
+                When you examine your log file, you can focus on areas of the
+                root filesystem that take up large amounts of memory.
+            </para>
+
+            <para>
+                You need to be sure that what you eliminate does not cripple
+                the functionality you need.
+                One way to see how packages relate to each other is by using
+                the Dependency Explorer UI with the BitBake command:
+                <literallayout class='monospaced'>
+     $ cd &lt;image-directory&gt;
+     $ bitbake -u depexp -g &lt;image&gt;
+                </literallayout>
+                Use the interface to select potential packages you wish to
+                eliminate and see their dependency relationships.
+            </para>
+
+            <para>
+                When deciding how to reduce the size, get rid of packages that
+                result in minimal impact on the feature set.
+                For example, you might not need a VGA display.
+                Or, you might be able to get by with <filename>devtmpfs</filename>
+                and <filename>mdev</filename> instead of
+                <filename>udev</filename>.
+            </para>
+
+            <para>
+                Use the <filename>local.conf</filename> file to make changes.
+                For example, to eliminate <filename>udev</filename> and
+                <filename>glib</filename>, set the following in the
+                local configuration file:
+                <literallayout class='monospaced'>
+     VIRTUAL-RUNTIME_dev_manager = ""
+                </literallayout>
+            </para>
+
+            <para>
+                Finally, you should consider exactly the type of root
+                filesystem you need to meet your needs while also reducing
+                its size.
+                For example, consider <filename>cramfs</filename>,
+                <filename>squashfs</filename>, <filename>ubifs</filename>,
+                <filename>ext2</filename>, or an <filename>initramfs</filename>
+                using <filename>initramfs</filename>.
+                Be aware that <filename>ext3</filename> requires a 1 Mbyte
+                journal.
+                If you are okay with running read-only you do not need this
+                journal.
+            </para>
+
+            <note>
+                After each round of elimination, you need to rebuild your
+                system and then use the tools to see the effects of your
+                reductions.
+            </note>
+
+
+        </section>
+
+        <section id='trim-the-kernel'>
+            <title>Trim the Kernel</title>
+
+            <para>
+                The kernel is built by including policies for hardware-independent
+                aspects.
+                What subsystems do you enable?
+                For what architecture are you building?
+                Which drivers do you build by default.
+                <note>You can modify the kernel source if you want to help
+                    with boot time.
+                </note>
+            </para>
+
+            <para>
+                Run the <filename>ksize.py</filename> script from the top-level
+                Linux build directory to get an idea of what is making up
+                the kernel:
+                <literallayout class='monospaced'>
+     $ cd &lt;top-level-linux-build-directory&gt;
+     $ ksize.py > ksize.log
+     $ cat ksize.log
+                </literallayout>
+                When you examine the log, you will see how much space is
+                taken up with the built-in <filename>.o</filename> files for
+                drivers, networking, core kernel files, filesystem, sound,
+                and so forth.
+                The sizes reported by the tool are uncompressed and thus,
+                will be smaller by a relatively constant factor in a compressed
+                kernel image.
+                Look to reduce the areas that are large and taking up around
+                the "90% rule."
+            </para>
+
+            <para>
+                To examine, or drill down, into any particular area, use the
+                <filename>-d</filename> option with the script:
+                <literallayout class='monospaced'>
+     $ ksize.py -d > ksize.log
+                </literallayout>
+                Using this option breaks out the individual file information
+                for each area of the kernel (e.g. drivers, networking, and
+                so forth).
+            </para>
+
+            <para>
+                Use your log file to see what you can eliminate from the kernel
+                based on features you can let go.
+                For example, if you are not going to need sound, you do not
+                need any drivers that support sound.
+            </para>
+
+            <para>
+                After figuring out what to eliminate, you need to reconfigure
+                the kernel to reflect those changes during the next build.
+                You could run <filename>menuconfig</filename> and make all your
+                changes at once.
+                However, that makes it difficult to see the effects of your
+                individual eliminations and also makes it difficult to replicate
+                the changes for perhaps another target device.
+                A better method is to start with no configurations using
+                <filename>allnoconfig</filename>, create configuration
+                fragments for individual changes, and then manage the
+                fragments into a single configuration file using
+                <filename>merge_config.sh</filename>.
+                The tool makes it easy for you to iterate using the
+                configuration change and build cycle.
+            </para>
+
+            <para>
+                Each time you make configuration changes, you need to rebuild
+                the kernel and check to see what impact your changes had on
+                the overall size.
+            </para>
+        </section>
+
+        <section id='remove-package-management-requirements'>
+            <title>Remove Package Management Requirements</title>
+
+            <para>
+                Packaging requirements add size to the image.
+                One way to reduce the size of the image is to remove all the
+                packaging requirements from the image.
+                This reduction includes both removing the package manager
+                and its unique dependencies as well as removing the package
+                management data itself.
+            </para>
+
+            <para>
+                To eliminate all the packaging requirements for an image,
+                follow these steps:
+                <orderedlist>
+                    <listitem><para>Put the following line in your main
+                        recipe for the image to remove package management
+                        data files:
+                        <literallayout class='monospaced'>
+     ROOTFS_POSTPROCESS_COMMAND += "remove_packaging_data_files ;
+                        </literallayout>
+                        For example, the recipe for the
+                        <filename>core-image-minimal</filename> image contains
+                        this line.
+                        You can also add the line to the
+                        <filename>local.conf</filename> configuration file.
+                        </para></listitem>
+                    <listitem><para>Be sure that "package-management" is not
+                        part of your
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+                        statement for the image.
+                        When you remove this feature, you are removing the
+                        package manager as well as its dependencies
+                        from the root filesystem.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='look-for-other-ways-to-minimize-size'>
+            <title>Look for Other Ways to Minimize Size</title>
+
+            <para>
+                Depending on your particular circumstances, other areas that you
+                can trim likely exist.
+                The key to finding these areas is through tools and methods
+                described here combined with experimentation and iteration.
+                Here are a couple of areas to experiment with:
+                <itemizedlist>
+                    <listitem><para><filename>eglibc</filename>:
+                        In general, follow this process:
+                        <orderedlist>
+                            <listitem><para>Remove <filename>eglibc</filename>
+                                features from
+                                <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+                                that you think you do not need.</para></listitem>
+                            <listitem><para>Build your distribution.
+                                </para></listitem>
+                            <listitem><para>If the build fails due to missing
+                                symbols in a package, determine if you can
+                                reconfigure the package to not need those
+                                features.
+                                For example, change the configuration to not
+                                support wide character support as is done for
+                                <filename>ncurses</filename>.
+                                Or, if support for those characters is needed,
+                                determine what <filename>eglibc</filename>
+                                features provide the support and restore the
+                                configuration.
+                                </para></listitem>
+                            <listitem><para>Rebuild and repeat the process.
+                                </para></listitem>
+                        </orderedlist></para></listitem>
+                    <listitem><para><filename>busybox</filename>:
+                        For BusyBox, use a process similar as described for
+                        <filename>eglibc</filename>.
+                        A difference is you will need to boot the resulting
+                        system to see if you are able to do everything you
+                        expect from the running system.
+                        You need to be sure to integrate configuration fragments
+                        into Busybox because BusyBox handles its own core
+                        features and then allows you to add configuration
+                        fragments on top.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='iterate-on-the-process'>
+            <title>Iterate on the Process</title>
+
+            <para>
+                If you have not reached your goals on system size, you need
+                to iterate on the process.
+                The process is the same.
+                Use the tools and see just what is taking up 90% of the root
+                filesystem and the kernel.
+                Decide what you can eliminate without limiting your device
+                beyond what you need.
+            </para>
+
+            <para>
+                Depending on your system, a good place to look might be
+                Busybox, which provides a stripped down
+                version of Unix tools in a single, executable file.
+                You might be able to drop virtual terminal services or perhaps
+                ipv6.
+            </para>
+        </section>
+    </section>
+
+    <section id='working-with-packages'>
+        <title>Working with Packages</title>
+
+        <para>
+            This section describes a few tasks that involve packages:
+            <itemizedlist>
+                <listitem><para>Excluding packages from an image
+                    </para></listitem>
+                <listitem><para>Incrementing a package revision number
+                    </para></listitem>
+                <listitem><para>Handling a package name alias
+                    </para></listitem>
+                <listitem><para>Handling optional module packaging
+                    </para></listitem>
+                <listitem><para>Using Runtime Package Management
+                    </para></listitem>
+                <listitem><para>Setting up and running package test
+                    (ptest)
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <section id='excluding-packages-from-an-image'>
+            <title>Excluding Packages from an Image</title>
+
+            <para>
+                You might find it necessary to prevent specific packages
+                from being installed into an image.
+                If so, you can use several variables to direct the build
+                system to essentially ignore installing recommended packages
+                or to not install a package at all.
+            </para>
+
+            <para>
+                The following list introduces variables you can use to
+                prevent packages from being installed into your image.
+                Each of these variables only works with IPK and RPM
+                package types.
+                Support for Debian packages does not exist.
+                Also, you can use these variables from your
+                <filename>local.conf</filename> file or attach them to a
+                specific image recipe by using a recipe name override.
+                For more detail on the variables, see the descriptions in the
+                Yocto Project Reference Manual's glossary chapter.
+                <itemizedlist>
+                    <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></ulink>:
+                        Use this variable to specify "recommended-only"
+                        packages that you do not want installed.
+                        </para></listitem>
+                    <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></ulink>:
+                        Use this variable to prevent all "recommended-only"
+                        packages from being installed.
+                        </para></listitem>
+                    <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></ulink>:
+                        Use this variable to prevent specific packages from
+                        being installed regardless of whether they are
+                        "recommended-only" or not.
+                        You need to realize that the build process could
+                        fail with an error when you
+                        prevent the installation of a package whose presence
+                        is required by an installed package.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='incrementing-a-package-revision-number'>
+            <title>Incrementing a Package Revision Number</title>
+
+            <para>
+                If a committed change results in changing the package output,
+                then the value of the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+                variable needs to be increased (or "bumped").
+                Increasing <filename>PR</filename> occurs one of two ways:
+                <itemizedlist>
+                    <listitem><para>Automatically using a Package Revision
+                        Service (PR Service).</para></listitem>
+                    <listitem><para>Manually incrementing the
+                        <filename>PR</filename> variable.</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Given that one of the challenges any build system and its
+                users face is how to maintain a package feed that is compatible
+                with existing package manager applications such as
+                RPM, APT, and OPKG, using an automated system is much
+                preferred over a manual system.
+                In either system, the main requirement is that version
+                numbering increases in a linear fashion and that a number of
+                version components exist that support that linear progression.
+            </para>
+
+            <para>
+                The following two sections provide information on the PR Service
+                and on manual <filename>PR</filename> bumping.
+            </para>
+
+            <section id='working-with-a-pr-service'>
+                <title>Working With a PR Service</title>
+
+                <para>
+                    As mentioned, attempting to maintain revision numbers in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                    is error prone, inaccurate and causes problems for people
+                    submitting recipes.
+                    Conversely, the PR Service automatically generates
+                    increasing numbers, particularly the revision field,
+                    which removes the human element.
+                    <note>
+                        For additional information on using a PR Service, you
+                        can see the
+                        <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
+                        wiki page.
+                    </note>
+                </para>
+
+                <para>
+                    The Yocto Project uses variables in order of
+                    decreasing priority to facilitate revision numbering (i.e.
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+                    for epoch, version and revision, respectively).
+                    The values are highly dependent on the policies and
+                    procedures of a given distribution and package feed.
+                </para>
+
+                <para>
+                    Because the OpenEmbedded build system uses
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#checksums'>signatures</ulink>",
+                    which are unique to a given build, the build system
+                    knows when to rebuild packages.
+                    All the inputs into a given task are represented by a
+                    signature, which can trigger a rebuild when different.
+                    Thus, the build system itself does not rely on the
+                    <filename>PR</filename> numbers to trigger a rebuild.
+                    The signatures, however, can be used to generate
+                    <filename>PR</filename> values.
+                </para>
+
+                <para>
+                    The PR Service works with both
+                    <filename>OEBasic</filename> and
+                    <filename>OEBasicHash</filename> generators.
+                    The value of <filename>PR</filename> bumps when the
+                    checksum changes and the different generator mechanisms
+                    change signatures under different circumstances.
+                </para>
+
+                <para>
+                    As implemented, the build system includes values from
+                    the PR Service into the <filename>PR</filename> field as
+                    an addition using the form "<filename>.x</filename>" so
+                    <filename>r0</filename> becomes <filename>r0.1</filename>,
+                    <filename>r0.2</filename> and so forth.
+                    This scheme allows existing <filename>PR</filename> values
+                    to be used for whatever reasons, which include manual
+                    <filename>PR</filename> bumps should it be necessary.
+                </para>
+
+                <para>
+                    By default, the PR Service is not enabled or running.
+                    Thus, the packages generated are just "self consistent".
+                    The build system adds and removes packages and
+                    there are no guarantees about upgrade paths but images
+                    will be consistent and correct with the latest changes.
+                </para>
+
+                <para>
+                    The simplest form for a PR Service is for it to exist
+                    for a single host development system that builds the
+                    package feed (building system).
+                    For this scenario, you can enable the PR Service by adding
+                    the following to your <filename>local.conf</filename>
+                    file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                    <literallayout class='monospaced'>
+     PRSERV_HOST = "localhost:0"
+                    </literallayout>
+                    Once the service is started, packages will automatically
+                    get increasing <filename>PR</filename> values and
+                    BitBake will take care of starting and stopping the server.
+                </para>
+
+                <para>
+                    If you have a more complex setup where multiple host
+                    development systems work against a common, shared package
+                    feed, you have a single PR Service running and it is
+                    connected to each building system.
+                    For this scenario, you need to start the PR Service using
+                    the <filename>bitbake-prserv</filename> command:
+                    <literallayout class='monospaced'>
+     bitbake-prserv &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
+                    </literallayout>
+                    In addition to hand-starting the service, you need to
+                    update the <filename>local.conf</filename> file of each
+                    building system as described earlier so each system
+                    points to the server and port.
+                </para>
+
+                <para>
+                    It is also recommended you use Build History, which adds
+                    some sanity checks to package versions, in conjunction with
+                    the server that is running the PR Service.
+                    To enable build history, add the following to each building
+                    system's <filename>local.conf</filename> file:
+                    <literallayout class='monospaced'>
+     # It is recommended to activate "buildhistory" for testing the PR service
+     INHERIT += "buildhistory"
+     BUILDHISTORY_COMMIT = "1"
+                    </literallayout>
+                    For information on Build History, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
+                    section in the Yocto Project Reference Manual.
+                </para>
+
+                <note>
+                    <para>The OpenEmbedded build system does not maintain
+                    <filename>PR</filename> information as part of the
+                    shared state (sstate) packages.
+                    If you maintain an sstate feed, its expected that either
+                    all your building systems that contribute to the sstate
+                    feed use a shared PR Service, or you do not run a PR
+                    Service on any of your building systems.
+                    Having some systems use a PR Service while others do
+                    not leads to obvious problems.</para>
+                    <para>For more information on shared state, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
+                    section in the Yocto Project Reference Manual.</para>
+                </note>
+            </section>
+
+            <section id='manually-bumping-pr'>
+                <title>Manually Bumping PR</title>
+
+                <para>
+                    The alternative to setting up a PR Service is to manually
+                    bump the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+                    variable.
+                </para>
+
+                <para>
+                    If a committed change results in changing the package output,
+                    then the value of the PR variable needs to be increased
+                    (or "bumped") as part of that commit.
+                    For new recipes you should add the <filename>PR</filename>
+                    variable and set its initial value equal to "r0", which is the default.
+                    Even though the default value is "r0", the practice of adding it to a new recipe makes
+                    it harder to forget to bump the variable when you make changes
+                    to the recipe in future.
+                </para>
+
+                <para>
+                    If you are sharing a common <filename>.inc</filename> file with multiple recipes,
+                    you can also use the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
+                    variable to ensure that
+                    the recipes sharing the <filename>.inc</filename> file are rebuilt when the
+                    <filename>.inc</filename> file itself is changed.
+                    The <filename>.inc</filename> file must set <filename>INC_PR</filename>
+                    (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
+                    to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
+                    If the <filename>.inc</filename> file is changed then its
+                    <filename>INC_PR</filename> should be incremented.
+                </para>
+
+                <para>
+                    When upgrading the version of a package, assuming the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
+                    changes, the <filename>PR</filename> variable should be
+                    reset to "r0" (or "$(INC_PR).0" if you are using
+                    <filename>INC_PR</filename>).
+                </para>
+
+                <para>
+                    Usually, version increases occur only to packages.
+                    However, if for some reason <filename>PV</filename> changes but does not
+                    increase, you can increase the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
+                    variable (Package Epoch).
+                    The <filename>PE</filename> variable defaults to "0".
+                </para>
+
+                <para>
+                    Version numbering strives to follow the
+                    <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
+                    Debian Version Field Policy Guidelines</ulink>.
+                    These guidelines define how versions are compared and what "increasing" a version means.
+                </para>
+            </section>
+        </section>
+
+        <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
+            <title>Handling a Package Name Alias</title>
+            <para>
+                Sometimes a package name you are using might exist under an alias or as a similarly named
+                package in a different distribution.
+                The OpenEmbedded build system implements a <filename>distro_check</filename>
+                task that automatically connects to major distributions
+                and checks for these situations.
+                If the package exists under a different name in a different distribution, you get a
+                <filename>distro_check</filename> mismatch.
+                You can resolve this problem by defining a per-distro recipe name alias using the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_PN_ALIAS'>DISTRO_PN_ALIAS</ulink></filename>
+                variable.
+            </para>
+
+            <para>
+                Following is an example that shows how you specify the <filename>DISTRO_PN_ALIAS</filename>
+                variable:
+                <literallayout class='monospaced'>
+     DISTRO_PN_ALIAS_pn-PACKAGENAME = "distro1=package_name_alias1 \
+                                       distro2=package_name_alias2 \
+                                       distro3=package_name_alias3 \
+                                       ..."
+                </literallayout>
+            </para>
+
+            <para>
+                If you have more than one distribution alias, separate them with a space.
+                Note that the build system currently automatically checks the
+                Fedora, OpenSUSE, Debian, Ubuntu,
+                and Mandriva distributions for source package recipes without having to specify them
+                using the <filename>DISTRO_PN_ALIAS</filename> variable.
+                For example, the following command generates a report that lists the Linux distributions
+                that include the sources for each of the recipes.
+                <literallayout class='monospaced'>
+     $ bitbake world -f -c distro_check
+                </literallayout>
+                The results are stored in the <filename>build/tmp/log/distro_check-${DATETIME}.results</filename>
+                file found in the
+                <link linkend='source-directory'>Source Directory</link>.
+            </para>
+        </section>
+
+        <section id='handling-optional-module-packaging'>
+            <title>Handling Optional Module Packaging</title>
+
+            <para>
+                Many pieces of software split functionality into optional
+                modules (or plug-ins) and the plug-ins that are built
+                might depend on configuration options.
+                To avoid having to duplicate the logic that determines what
+                modules are available in your recipe or to avoid having
+                to package each module by hand, the OpenEmbedded build system
+                provides functionality to handle module packaging dynamically.
+            </para>
+
+            <para>
+                To handle optional module packaging, you need to do two things:
+                <itemizedlist>
+                    <listitem><para>Ensure the module packaging is actually
+                        done</para></listitem>
+                    <listitem><para>Ensure that any dependencies on optional
+                        modules from other recipes are satisfied by your recipe
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <section id='making-sure-the-packaging-is-done'>
+                <title>Making Sure the Packaging is Done</title>
+
+                <para>
+                    To ensure the module packaging actually gets done, you use
+                    the <filename>do_split_packages</filename> function within
+                    the <filename>populate_packages</filename> Python function
+                    in your recipe.
+                    The <filename>do_split_packages</filename> function
+                    searches for a pattern of files or directories under a
+                    specified path and creates a package for each one it finds
+                    by appending to the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES'><filename>PACKAGES</filename></ulink>
+                    variable and setting the appropriate values for
+                    <filename>FILES_packagename</filename>,
+                    <filename>RDEPENDS_packagename</filename>,
+                    <filename>DESCRIPTION_packagename</filename>, and so forth.
+                    Here is an example from the <filename>lighttpd</filename>
+                    recipe:
+                    <literallayout class='monospaced'>
+     python populate_packages_prepend () {
+         lighttpd_libdir = d.expand('${libdir}')
+         do_split_packages(d, lighttpd_libdir, '^mod_(.*)\.so$',
+                          'lighttpd-module-%s', 'Lighttpd module for %s',
+                           extra_depends='')
+     }
+                    </literallayout>
+                    The previous example specifies a number of things in the
+                    call to <filename>do_split_packages</filename>.
+                    <itemizedlist>
+                        <listitem><para>A directory within the files installed
+                            by your recipe through <filename>do_install</filename>
+                            in which to search.</para></listitem>
+                        <listitem><para>A regular expression to match module
+                            files in that directory.
+                            In the example, note the parentheses () that mark
+                            the part of the expression from which the module
+                            name should be derived.</para></listitem>
+                        <listitem><para>A pattern to use for the package names.
+                            </para></listitem>
+                        <listitem><para>A description for each package.
+                            </para></listitem>
+                        <listitem><para>An empty string for
+                            <filename>extra_depends</filename>, which disables
+                            the default dependency on the main
+                            <filename>lighttpd</filename> package.
+                            Thus, if a file in <filename>${libdir}</filename>
+                            called <filename>mod_alias.so</filename> is found,
+                            a package called <filename>lighttpd-module-alias</filename>
+                            is created for it and the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
+                            is set to "Lighttpd module for alias".</para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    Often, packaging modules is as simple as the previous
+                    example.
+                    However, more advanced options exist that you can use
+                    within <filename>do_split_packages</filename> to modify its
+                    behavior.
+                    And, if you need to, you can add more logic by specifying
+                    a hook function that is called for each package.
+                    It is also perfectly acceptable to call
+                    <filename>do_split_packages</filename> multiple times if
+                    you have more than one set of modules to package.
+                </para>
+
+                <para>
+                    For more examples that show how to use
+                    <filename>do_split_packages</filename>, see the
+                    <filename>connman.inc</filename> file in the
+                    <filename>meta/recipes-connectivity/connman/</filename>
+                    directory of the <filename>poky</filename>
+                    <link linkend='yocto-project-repositories'>source repository</link>.
+                    You can also find examples in
+                    <filename>meta/classes/kernel.bbclass</filename>.
+                 </para>
+
+                 <para>
+                     Following is a reference that shows
+                     <filename>do_split_packages</filename> mandatory and
+                     optional arguments:
+                     <literallayout class='monospaced'>
+     Mandatory arguments
+
+     root
+        The path in which to search
+     file_regex
+        Regular expression to match searched files.
+        Use parentheses () to mark the part of this
+        expression that should be used to derive the
+        module name (to be substituted where %s is
+        used in other function arguments as noted below)
+     output_pattern
+        Pattern to use for the package names. Must
+        include %s.
+     description
+        Description to set for each package. Must
+        include %s.
+
+     Optional arguments
+
+     postinst
+        Postinstall script to use for all packages
+        (as a string)
+     recursive
+        True to perform a recursive search - default
+        False
+     hook
+        A hook function to be called for every match.
+        The function will be called with the following
+        arguments (in the order listed):
+
+        f
+           Full path to the file/directory match
+        pkg
+           The package name
+        file_regex
+           As above
+        output_pattern
+           As above
+        modulename
+           The module name derived using file_regex
+
+     extra_depends
+        Extra runtime dependencies (RDEPENDS) to be
+        set for all packages. The default value of None
+        causes a dependency on the main package
+        (${PN}) - if you do not want this, pass empty
+        string '' for this parameter.
+     aux_files_pattern
+        Extra item(s) to be added to FILES for each
+        package. Can be a single string item or a list
+        of strings for multiple items. Must include %s.
+     postrm
+        postrm script to use for all packages (as a
+        string)
+     allow_dirs
+        True to allow directories to be matched -
+        default False
+     prepend
+        If True, prepend created packages to PACKAGES
+        instead of the default False which appends them
+     match_path
+        match file_regex on the whole relative path to
+        the root rather than just the file name
+     aux_files_pattern_verbatim
+        Extra item(s) to be added to FILES for each
+        package, using the actual derived module name
+        rather than converting it to something legal
+        for a package name. Can be a single string item
+        or a list of strings for multiple items. Must
+        include %s.
+     allow_links
+        True to allow symlinks to be matched - default
+        False
+                     </literallayout>
+                 </para>
+            </section>
+
+            <section id='satisfying-dependencies'>
+                <title>Satisfying Dependencies</title>
+
+                <para>
+                    The second part for handling optional module packaging
+                    is to ensure that any dependencies on optional modules
+                    from other recipes are satisfied by your recipe.
+                    You can be sure these dependencies are satisfied by
+                    using the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGES_DYNAMIC'><filename>PACKAGES_DYNAMIC</filename></ulink> variable.
+                    Here is an example that continues with the
+                    <filename>lighttpd</filename> recipe shown earlier:
+                    <literallayout class='monospaced'>
+     PACKAGES_DYNAMIC = "lighttpd-module-.*"
+                    </literallayout>
+                    The name specified in the regular expression can of
+                    course be anything.
+                    In this example, it is <filename>lighttpd-module-</filename>
+                    and is specified as the prefix to ensure that any
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
+                    and <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
+                    on a package name starting with the prefix are satisfied
+                    during build time.
+                    If you are using <filename>do_split_packages</filename>
+                    as described in the previous section, the value you put in
+                    <filename>PACKAGES_DYNAMIC</filename> should correspond to
+                    the name pattern specified in the call to
+                    <filename>do_split_packages</filename>.
+                </para>
+            </section>
+        </section>
+
+        <section id='using-runtime-package-management'>
+            <title>Using Runtime Package Management</title>
+
+            <para>
+                During a build, BitBake always transforms a recipe into one or
+                more packages.
+                For example, BitBake takes the <filename>bash</filename> recipe
+                and currently produces the <filename>bash-dbg</filename>,
+                <filename>bash-staticdev</filename>,
+                <filename>bash-dev</filename>, <filename>bash-doc</filename>,
+                <filename>bash-locale</filename>, and
+                <filename>bash</filename> packages.
+                Not all generated packages are included in an image.
+            </para>
+
+            <para>
+                In several situations, you might need to update, add, remove,
+                or query the packages on a target device at runtime
+                (i.e. without having to generate a new image).
+                Examples of such situations include:
+                <itemizedlist>
+                    <listitem><para>
+                        You want to provide in-the-field updates to deployed
+                        devices (e.g. security updates).
+                        </para></listitem>
+                    <listitem><para>
+                        You want to have a fast turn-around development cycle
+                        for one or more applications that run on your device.
+                        </para></listitem>
+                    <listitem><para>
+                        You want to temporarily install the "debug" packages
+                        of various applications on your device so that
+                        debugging can be greatly improved by allowing
+                        access to symbols and source debugging.
+                        </para></listitem>
+                    <listitem><para>
+                        You want to deploy a more minimal package selection of
+                        your device but allow in-the-field updates to add a
+                        larger selection for customization.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                In all these situations, you have something similar to a more
+                traditional Linux distribution in that in-field devices
+                are able to receive pre-compiled packages from a server for
+                installation or update.
+                Being able to install these packages on a running,
+                in-field device is what is termed "runtime package
+                management".
+            </para>
+
+            <para>
+                In order to use runtime package management, you
+                need a host/server machine that serves up the pre-compiled
+                packages plus the required metadata.
+                You also need package manipulation tools on the target.
+                The build machine is a likely candidate to act as the server.
+                However, that machine does not necessarily have to be the
+                package server.
+                The build machine could push its artifacts to another machine
+                that acts as the server (e.g. Internet-facing).
+            </para>
+
+            <para>
+                A simple build that targets just one device produces
+                more than one package database.
+                In other words, the packages produced by a build are separated
+                out into a couple of different package groupings based on
+                criteria such as the target's CPU architecture, the target
+                board, or the C library used on the target.
+                For example, a build targeting the <filename>qemuarm</filename>
+                device produces the following three package databases:
+                <filename>all</filename>, <filename>armv5te</filename>, and
+                <filename>qemuarm</filename>.
+                If you wanted your <filename>qemuarm</filename> device to be
+                aware of all the packages that were available to it,
+                you would need to point it to each of these databases
+                individually.
+                In a similar way, a traditional Linux distribution usually is
+                configured to be aware of a number of software repositories
+                from which it retrieves packages.
+            </para>
+
+            <para>
+                Using runtime package management is completely optional and
+                not required for a successful build or deployment in any
+                way.
+                But if you want to make use of runtime package management,
+                you need to do a couple things above and beyond the basics.
+                The remainder of this section describes what you need to do.
+            </para>
+
+            <section id='runtime-package-management-build'>
+                <title>Build Considerations</title>
+
+                <para>
+                    This section describes build considerations that you need
+                    to be aware of in order to provide support for runtime
+                    package management.
+                </para>
+
+                <para>
+                    When BitBake generates packages it needs to know
+                    what format(s) to use.
+                    In your configuration, you use the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>
+                    variable to specify the format.
+                    <note>
+                        You can choose to have more than one format but you must
+                        provide at least one.
+                    </note>
+                </para>
+
+                <para>
+                    If you would like your image to start off with a basic
+                    package database of the packages in your current build
+                    as well as have the relevant tools available on the
+                    target for runtime package management, you can include
+                    "package-management" in the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+                    variable.
+                    Including "package-management" in this
+                    configuration variable ensures that when the image
+                    is assembled for your target, the image includes
+                    the currently-known package databases as well as
+                    the target-specific tools required for runtime
+                    package management to be performed on the target.
+                    However, this is not strictly necessary.
+                    You could start your image off without any databases
+                    but only include the required on-target package
+                    tool(s).
+                    As an example, you could include "opkg" in your
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></ulink>
+                    variable if you are using the IPK package format.
+                    You can then initialize your target's package database(s)
+                    later once your image is up and running.
+                </para>
+
+                <para>
+                    Whenever you perform any sort of build step that can
+                    potentially generate a package or modify an existing
+                    package, it is always a good idea to re-generate the
+                    package index with:
+                    <literallayout class='monospaced'>
+    $ bitbake package-index
+                    </literallayout>
+                    Realize that it is not sufficient to simply do the
+                    following:
+                    <literallayout class='monospaced'>
+    $ bitbake &lt;some-package&gt; package-index
+                    </literallayout>
+                    This is because BitBake does not properly schedule the
+                    <filename>package-index</filename> target fully after any
+                    other target has completed.
+                    Thus, be sure to run the package update step separately.
+                </para>
+
+                <para>
+                    As described below in the
+                    "<link linkend='runtime-package-management-target-ipk'>Using IPK</link>"
+                    section, if you are using IPK as your package format, you
+                    can make use of the
+                    <filename>distro-feed-configs</filename> recipe provided
+                    by <filename>meta-oe</filename> in order to configure your
+                    target to use your IPK databases.
+                </para>
+
+                <para>
+                    When your build is complete, your packages reside in the
+                    <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
+                    directory.
+                    For example, if <filename>${TMPDIR}</filename>
+                    is <filename>tmp</filename> and your selected package type
+                    is IPK, then your IPK packages are available in
+                    <filename>tmp/deploy/ipk</filename>.
+                </para>
+            </section>
+
+            <section id='runtime-package-management-server'>
+                <title>Host or Server Machine Setup</title>
+
+                <para>
+                    Typically, packages are served from a server using
+                    HTTP.
+                    However, other protocols are possible.
+                    If you want to use HTTP, then setup and configure a
+                    web server, such as Apache 2 or lighttpd, on the machine
+                    serving the packages.
+                </para>
+
+                <para>
+                    As previously mentioned, the build machine can act as the
+                    package server.
+                    In the following sections that describe server machine
+                    setups, the build machine is assumed to also be the server.
+                </para>
+
+                <section id='package-server-apache'>
+                    <title>Serving Packages via Apache 2</title>
+
+                    <para>
+                        This example assumes you are using the Apache 2
+                        server:
+                        <orderedlist>
+                            <listitem><para>
+                                Add the directory to your Apache
+                                configuration, which you can find at
+                                <filename>/etc/httpd/conf/httpd.conf</filename>.
+                                Use commands similar to these on the
+                                development system.
+                                These example commands assume a top-level
+                                <link linkend='source-directory'>Source Directory</link>
+                                named <filename>poky</filename> in your home
+                                directory.
+                                The example also assumes an RPM package type.
+                                If you are using a different package type, such
+                                as IPK, use "ipk" in the pathnames:
+                                <literallayout class='monospaced'>
+     &lt;VirtualHost *:80&gt;
+       ....
+         Alias /rpm ~/poky/build/tmp/deploy/rpm
+         &lt;Directory "~/poky/build/tmp/deploy/rpm"&gt;
+           Options +Indexes
+         &lt;/Directory&gt;
+     &lt;/VirtualHost&gt;
+                                </literallayout></para></listitem>
+                            <listitem><para>
+                                Reload the Apache configuration as described
+                                in this step.
+                                For all commands, be sure you have root
+                                privileges.
+                                </para>
+
+                                <para>
+                                If your development system is using Fedora or
+                                CentOS, use the following:
+                                <literallayout class='monospaced'>
+     # service httpd reload
+                                </literallayout>
+                                For Ubuntu and Debian, use the following:
+                                <literallayout class='monospaced'>
+     # /etc/init.d/apache2 reload
+                                </literallayout>
+                                For OpenSUSE, use the following:
+                                <literallayout class='monospaced'>
+     # /etc/init.d/apache2 reload
+                                </literallayout></para></listitem>
+                            <listitem><para>
+                                If you are using Security-Enhanced Linux
+                                (SELinux), you need to label the files as
+                                being accessible through Apache.
+                                Use the following command from the development
+                                host.
+                                This example assumes RPM package types:
+                                <literallayout class='monospaced'>
+     # chcon -R -h -t httpd_sys_content_t tmp/deploy/rpm
+                                </literallayout></para></listitem>
+                        </orderedlist>
+                    </para>
+                </section>
+
+                <section id='package-server-lighttpd'>
+                    <title>Serving Packages via lighttpd</title>
+
+                    <para>
+                        If you are using lighttpd, all you need
+                        to do is to provide a link from your
+                        <filename>${TMPDIR}/deploy/&lt;package-format&gt;</filename>
+                        directory to lighttpd's document-root.
+                        You can determine the specifics of your lighttpd
+                        installation by looking through its configuration file,
+                        which is usually found at:
+                        <filename>/etc/lighttpd/lighttpd.conf</filename>.
+                    </para>
+
+                    <para>
+                        For example, if you are using IPK, lighttpd's
+                        document-root is set to
+                        <filename>/var/www/lighttpd</filename>, and you had
+                        packages for a target named "BOARD",
+                        then you might create a link from your build location
+                        to lighttpd's document-root as follows:
+                        <literallayout class='monospaced'>
+    # ln -s $(PWD)/tmp/deploy/ipk /var/www/lighttpd/BOARD-dir
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        At this point, you need to start the lighttpd server.
+                        The method used to start the server varies by
+                        distribution.
+                        However, one basic method that starts it by hand is:
+                        <literallayout class='monospaced'>
+    # lighttpd -f /etc/lighttpd/lighttpd.conf
+                        </literallayout>
+                    </para>
+                </section>
+            </section>
+
+            <section id='runtime-package-management-target'>
+                <title>Target Setup</title>
+
+                <para>
+                    Setting up the target differs depending on the
+                    package management system.
+                    This section provides information for RPM and IPK.
+                </para>
+
+                <section id='runtime-package-management-target-rpm'>
+                    <title>Using RPM</title>
+
+                    <para>
+                        The application for performing runtime package
+                        management of RPM packages on the target is called
+                        <filename>smart</filename>.
+                    </para>
+
+                    <para>
+                        On the target machine, you need to inform
+                        <filename>smart</filename> of every package database
+                        you want to use.
+                        As an example, suppose your target device can use the
+                        following three package databases from a server named
+                        <filename>server.name</filename>:
+                        <filename>all</filename>, <filename>i586</filename>,
+                        and <filename>qemux86</filename>.
+                        Given this example, issue the following commands on the
+                        target:
+                        <literallayout class='monospaced'>
+     # smart channel --add all type=rpm-md baseurl=http://server.name/rpm/all
+     # smart channel --add i585 type=rpm-md baseurl=http://server.name/rpm/i586
+     # smart channel --add qemux86 type=rpm-md baseurl=http://server.name/rpm/qemux86
+                        </literallayout>
+                        Also from the target machine, fetch the repository
+                        information using this command:
+                        <literallayout class='monospaced'>
+     # smart update
+                        </literallayout>
+                        You can now use the <filename>smart query</filename>
+                        and <filename>smart install</filename> commands to
+                        find and install packages from the repositories.
+                    </para>
+                </section>
+
+                <section id='runtime-package-management-target-ipk'>
+                    <title>Using IPK</title>
+
+                    <para>
+                        The application for performing runtime package
+                        management of IPK packages on the target is called
+                        <filename>opkg</filename>.
+                    </para>
+
+                    <para>
+                        In order to inform <filename>opkg</filename> of the
+                        package databases you want to use, simply create one
+                        or more <filename>*.conf</filename> files in the
+                        <filename>/etc/opkg</filename> directory on the target.
+                        The <filename>opkg</filename> application uses them
+                        to find its available package databases.
+                        As an example, suppose you configured your HTTP server
+                        on your machine named
+                        <filename>www.mysite.com</filename> to serve files
+                        from a <filename>BOARD-dir</filename> directory under
+                        its document-root.
+                        In this case, you might create a configuration
+                        file on the target called
+                        <filename>/etc/opkg/base-feeds.conf</filename> that
+                        contains:
+                        <literallayout class='monospaced'>
+     src/gz all http://www.mysite.com/BOARD-dir/all
+     src/gz armv7a http://www.mysite.com/BOARD-dir/armv7a
+     src/gz beagleboard http://www.mysite.com/BOARD-dir/beagleboard
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        As a way of making it easier to generate and make
+                        these IPK configuration files available on your
+                        target, the <filename>meta-oe</filename> layer
+                        provides a recipe called
+                        <filename>distro-feed-configs</filename>, which
+                        provides a package by the same name.
+                        When you include this package into your image, it will
+                        automatically generate and include a set of
+                        <filename>*.conf</filename> files in the image's
+                        <filename>/etc/opkg</filename> directory that will
+                        provide your target's <filename>opkg</filename>
+                        tool with any and all package databases your build will
+                        generate.
+                        The only catch is that this recipe cannot possibly
+                        imagine your server's DNS name/IP address.
+                        Consequently, somewhere in your configuration you need
+                        to set a variable called
+                        <filename>DISTRO_FEED_URI</filename> to point
+                        to your server and the location within the
+                        document-root that contains the databases.
+                        For example: if you are serving your packages over HTTP,
+                        your server's IP address is 192.168.7.1, and your
+                        databases are located in a directory called
+                        <filename>BOARD-dir</filename> underneath your HTTP
+                        server's document-root, you need to set
+                        <filename>DISTRO_FEED_URI</filename> to
+                        <filename>http://192.168.7.1/BOARD-dir</filename>.
+                    </para>
+
+                    <para>
+                        On the target machine, fetch (or refresh) the
+                        repository information using this command:
+                        <literallayout class='monospaced'>
+     # opkg update
+                        </literallayout>
+                        You can now use the <filename>opkg list</filename> and
+                        <filename>opkg install</filename> commands to find and
+                        install packages from the repositories.
+                    </para>
+                </section>
+            </section>
+        </section>
+
+        <section id='testing-packages-with-ptest'>
+            <title>Testing Packages With ptest</title>
+
+            <para>
+                A Package Test (ptest) runs tests against packages built
+                by the OpenEmbedded build system on the target machine.
+                A ptest contains at least two items: the actual test, and
+                a shell script (<filename>run-ptest</filename>) that starts
+                the test.
+                The shell script that starts the test must not contain
+                the actual test, the script only starts it.
+                On the other hand, the test can be anything from a simple
+                shell script that runs a binary and checks the output to
+                an elaborate system of test binaries and data files.
+            </para>
+
+            <para>
+                The test generates output in the format used by
+                Automake:
+                <literallayout class='monospaced'>
+     &lt;result&gt;: &lt;testname&gt;
+                </literallayout>
+                where the result can be <filename>PASS</filename>,
+                <filename>FAIL</filename>, or <filename>SKIP</filename>,
+                and the testname can be any identifying string.
+            </para>
+
+            <note>
+                With this release of the Yocto Project, three recipes exist
+                that are "ptest-enabled": <filename>bash</filename>,
+                <filename>glib-2.0</filename>, and
+                <filename>dbus</filename>.
+                These three recipes are Autotool-enabled.
+            </note>
+
+            <section id='adding-ptest-to-your-build'>
+                <title>Adding ptest to Your Build</title>
+
+                <para>
+                    To add package testing to your build, add the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
+                    and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>
+                    variables to your <filename>local.conf</filename> file,
+                    which is found in the
+                    <link linkend='build-directory'>Build Directory</link>:
+                    <literallayout class='monospaced'>
+     DISTRO_FEATURES_append = " ptest"
+     EXTRA_IMAGE_FEATURES += "ptest-pkgs"
+                    </literallayout>
+                    Once your build is complete, the ptest files are installed
+                    into the <filename>/usr/lib/&lt;package&gt;/ptest</filename>
+                    directory within the image, where
+                    <filename>&lt;package&gt;</filename> is the name of the
+                    package.
+                </para>
+            </section>
+
+            <section id='running-ptest'>
+                <title>Running ptest</title>
+
+                <para>
+                    The <filename>ptest-runner</filename> package installs a
+                    shell script that loops through all installed ptest test
+                    suites and runs them in sequence.
+                    Consequently, you might want to add this package to
+                    your image.
+                </para>
+            </section>
+
+            <section id='getting-your-package-ready'>
+                <title>Getting Your Package Ready</title>
+
+                <para>
+                    In order to enable a recipe to run installed ptests
+                    on target hardware,
+                    you need to prepare the recipes that build the packages
+                    you want to test.
+                    Here is what you have to do for each recipe:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Be sure the recipe
+                            inherits ptest:</emphasis>
+                            Include the following line in each recipe:
+                            <literallayout class='monospaced'>
+     inherit ptest
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para><emphasis>Create <filename>run-ptest</filename>:</emphasis>
+                            This script starts your test.
+                            Locate the script where you will refer to it
+                            using
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
+                            Here is an example that starts a test for
+                            <filename>dbus</filename>:
+                            <literallayout class='monospaced'>
+     #!/bin/sh
+     cd test
+     make -k runtest-TESTS
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para><emphasis>Ensure dependencies are
+                            met:</emphasis>
+                            If the test adds build or runtime dependencies
+                            that normally do not exist for the package
+                            (such as requiring "make" to run the test suite),
+                            use the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
+                            and
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
+                            variables in your recipe in order for the package
+                            to meet the dependencies.
+                            Here is an example where the package has a runtime
+                            dependency on "make":
+                            <literallayout class='monospaced'>
+     RDEPENDS_${PN}-ptest += "make"
+                            </literallayout>
+                            </para></listitem>
+                        <listitem><para><emphasis>Add a function to build the
+                            test suite:</emphasis>
+                            Not many packages support cross-compilation of
+                            their test suites.
+                            Consequently, you usually need to add a
+                            cross-compilation function to the package.
+                            </para>
+                            <para>Many packages based on Automake compile and
+                            run the test suite by using a single command
+                            such as <filename>make check</filename>.
+                            However, the native <filename>make check</filename>
+                            builds and runs on the same computer, while
+                            cross-compiling requires that the package is built
+                            on the host but executed on the target.
+                            The built version of Automake that ships with the
+                            Yocto Project includes a patch that separates
+                            building and execution.
+                            Consequently, packages that use the unaltered,
+                            patched version of <filename>make check</filename>
+                            automatically cross-compiles.</para>
+                            <para>However, you still must add a
+                            <filename>do_compile_ptest</filename> function to
+                            build the test suite.
+                            Add a function similar to the following to your
+                            recipe:
+                            <literallayout class='monospaced'>
+     do_compile_ptest() {
+        oe_runmake buildtest-TESTS
+     }
+                            </literallayout>
+                            </para></listitem>
+                       <listitem><para><emphasis>Ensure special configurations
+                            are set:</emphasis>
+                            If the package requires special configurations
+                            prior to compiling the test code, you must
+                            insert a <filename>do_configure_ptest</filename>
+                            function into the recipe.
+                            </para></listitem>
+                       <listitem><para><emphasis>Install the test
+                            suite:</emphasis>
+                            The <filename>ptest.bbclass</filename> class
+                            automatically copies the file
+                            <filename>run-ptest</filename> to the target and
+                            then runs make <filename>install-ptest</filename>
+                            to run the tests.
+                            If this is not enough, you need to create a
+                            <filename>do_install_ptest</filename> function and
+                            make sure it gets called after the
+                            "make install-ptest" completes.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+        </section>
+    </section>
+
+    <section id="building-software-from-an-external-source">
+        <title>Building Software from an External Source</title>
+
+        <para>
+            By default, the OpenEmbedded build system uses the
+            <link linkend='build-directory'>Build Directory</link> to
+            build source code.
+            The build process involves fetching the source files, unpacking
+            them, and then patching them if necessary before the build takes
+            place.
+        </para>
+
+        <para>
+            Situations exist where you might want to build software from source
+            files that are external to and thus outside of the
+            OpenEmbedded build system.
+            For example, suppose you have a project that includes a new BSP with
+            a heavily customized kernel.
+            And, you want to minimize exposing the build system to the
+            development team so that they can focus on their project and
+            maintain everyone's workflow as much as possible.
+            In this case, you want a kernel source directory on the development
+            machine where the development occurs.
+            You want the recipe's
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+            variable to point to the external directory and use it as is, not
+            copy it.
+        </para>
+
+        <para>
+            To build from software that comes from an external source, all you
+            need to do is inherit
+            <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></ulink>
+            and then set the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>
+            variable to point to your external source code.
+            Here are the statements to put in your
+            <filename>local.conf</filename> file:
+            <literallayout class='monospaced'>
+     INHERIT += "externalsrc"
+     EXTERNALSRC_pn-myrecipe = "/some/path/to/your/source/tree"
+            </literallayout>
+        </para>
+
+        <para>
+            By default, <filename>externalsrc.bbclass</filename> builds
+            the source code in a directory separate from the external source
+            directory as specified by
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC'><filename>EXTERNALSRC</filename></ulink>.
+            If you need to have the source built in the same directory in
+            which it resides, or some other nominated directory, you can set
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></ulink>
+            to point to that directory:
+            <literallayout class='monospaced'>
+     EXTERNALSRC_BUILD_pn-myrecipe = "/path/to/my/source/tree"
+            </literallayout>
+        </para>
+    </section>
+
+    <section id="selecting-an-initialization-manager">
+        <title>Selecting an Initialization Manager</title>
+
+        <para>
+            By default, the Yocto Project uses
+            <filename>SysVinit</filename> as the initialization manager.
+            However, support also exists for <filename>systemd</filename>,
+            which is a full replacement for <filename>init</filename> with
+            parallel starting of services, reduced shell overhead and other
+            features that are used by many distributions.
+        </para>
+
+        <para>
+            If you want to use <filename>sysvinit</filename>, you do
+            not have to do anything.
+            But, if you want to use <filename>systemd</filename>, you must
+            take some steps as described in the following sections.
+        </para>
+
+<!--
+        <note>
+            It is recommended that you create your own distribution configuration
+            file to hold these settings instead of using your
+            <filename>local.conf</filename> file.
+            For information on creating your own distribution, see the
+            "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
+            section.
+        </note>
+-->
+
+        <section id='using-systemd-exclusively'>
+            <title>Using systemd Exclusively</title>
+
+            <para>
+                Set the following variables in your distribution configuration
+                file as follows:
+                <literallayout class='monospaced'>
+     DISTRO_FEATURES_append = " systemd"
+     VIRTUAL-RUNTIME_init_manager = "systemd"
+                </literallayout>
+                You can also prevent the <filename>sysvinit</filename>
+                distribution feature from
+                being automatically enabled as follows:
+                <literallayout class='monospaced'>
+     DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
+                </literallayout>
+                Doing so removes any redundant <filename>sysvinit</filename>
+                scripts.
+            </para>
+
+            <para>
+                For information on the backfill variable, see
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></ulink>
+                in the Yocto Project Reference Manual.
+            </para>
+        </section>
+
+        <section id='using-systemd-for-the-main-image-and-using-sysvinit-for-the-rescue-image'>
+            <title>Using systemd for the Main Image and Using SysVinit for the Rescue Image</title>
+
+            <para>
+                Set the following variables in your distribution configuration
+                file as follows:
+                <literallayout class='monospaced'>
+     DISTRO_FEATURES_append = " systemd"
+     VIRTUAL-RUNTIME_init_manager = "systemd"
+                </literallayout>
+                Doing so causes your main image to use the
+                <filename>packagegroup-core-boot.bb</filename> recipe and
+                <filename>systemd</filename>.
+                The rescue/minimal image cannot use this package group.
+                However, it can install <filename>sysvinit</filename>
+                and the appropriate packages will have support for both
+                <filename>systemd</filename> and <filename>sysvinit</filename>.
+            </para>
+        </section>
+    </section>
+
+    <section id='excluding-recipes-from-the-build'>
+        <title>Excluding Recipes From the Build</title>
+
+        <para>
+            You might find that there are groups of recipes or append files
+            that you want to filter out of the build process.
+            Usually, this is not necessary.
+            However, on rare occasions where you might want to use a
+            layer but exclude parts that are causing problems, such
+            as introducing a different version of a recipe, you can
+            use
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-BBMASK'><filename>BBMASK</filename></ulink>
+            to exclude the recipe.
+        </para>
+
+        <para>
+            It is possible to filter or mask out <filename>.bb</filename> and
+            <filename>.bbappend</filename> files.
+            You can do this by providing an expression with the
+            <filename>BBMASK</filename> variable.
+            Here is an example:
+            <literallayout class='monospaced'>
+     BBMASK = "/meta-mymachine/recipes-maybe/"
+            </literallayout>
+            Here, all <filename>.bb</filename> and
+            <filename>.bbappend</filename> files in the directory that match
+            the expression are ignored during the build process.
+        </para>
+
+        <note>
+            The value you provide is passed to Python's regular expression
+            compiler.
+            The expression is compared against the full paths to the files.
+            For complete syntax information, see Python's documentation at
+            <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
+        </note>
+    </section>
+
+    <section id="platdev-appdev-srcrev">
+        <title>Using an External SCM</title>
+
+        <para>
+            If you're working on a recipe that pulls from an external Source Code Manager (SCM), it
+            is possible to have the OpenEmbedded build system notice new recipe changes added to the
+            SCM and then build the resulting package that depends on the new recipes by using the latest
+            versions.
+            This only works for SCMs from which it is possible to get a sensible revision number for changes.
+            Currently, you can do this with Apache Subversion (SVN), Git, and Bazaar (BZR) repositories.
+        </para>
+
+        <para>
+            To enable this behavior, simply add the following to the <filename>local.conf</filename>
+            configuration file found in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+            <literallayout class='monospaced'>
+     SRCREV_pn-&lt;PN&gt; = "${AUTOREV}"
+            </literallayout>
+            where <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>
+            is the name of the recipe for which you want to enable automatic source
+            revision updating.
+        </para>
+    </section>
+
+    <section id='creating-a-read-only-root-filesystem'>
+        <title>Creating a Read-Only Root Filesystem</title>
+
+        <para>
+            Suppose, for security reasons, you need to disable
+            your target device's root filesystem's write permissions
+            (i.e. you need a read-only root filesystem).
+            Or, perhaps you are running the device's operating system
+            from a read-only storage device.
+            For either case, you can customize your image for
+            that behavior.
+        </para>
+
+        <note>
+            Supporting a read-only root filesystem requires that the system and
+            applications do not try to write to the root filesystem.
+            You must configure all parts of the target system to write
+            elsewhere, or to gracefully fail in the event of failing to
+            write to the root filesystem.
+        </note>
+
+        <section id='creating-the-root-filesystem'>
+            <title>Creating the Root Filesystem</title>
+
+            <para>
+                To create the read-only root filesystem, simply add the
+                <filename>read-only-rootfs</filename> feature to your image.
+                Using either of the following statements in your
+                image recipe or from within the
+                <filename>local.conf</filename> file found in the
+                <link linkend='build-directory'>Build Directory</link>
+                causes the build system to create a read-only root filesystem:
+                <literallayout class='monospaced'>
+     IMAGE_FEATURES = "read-only-rootfs"
+                </literallayout>
+                or
+                <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES = "read-only-rootfs"
+                </literallayout>
+            </para>
+
+            <para>
+                For more information on how to use these variables, see the
+                "<link linkend='usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></link>"
+                section.
+                For information on the variables, see
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+                and <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTRA_IMAGE_FEATURES'><filename>EXTRA_IMAGE_FEATURES</filename></ulink>.
+            </para>
+        </section>
+
+        <section id='post-installation-scripts'>
+            <title>Post-Installation Scripts</title>
+
+            <para>
+                It is very important that you make sure all
+                post-Installation (<filename>pkg_postinst</filename>) scripts
+                for packages that are installed into the image can be run
+                at the time when the root filesystem is created during the
+                build on the host system.
+                These scripts cannot attempt to run during first-boot on the
+                target device.
+                With the <filename>read-only-rootfs</filename> feature enabled,
+                the build system checks during root filesystem creation to make
+                sure all post-installation scripts succeed.
+                If any of these scripts still need to be run after the root
+                filesystem is created, the build immediately fails.
+                These checks during build time ensure that the build fails
+                rather than the target device fails later during its
+                initial boot operation.
+            </para>
+
+            <para>
+                Most of the common post-installation scripts generated by the
+                build system for the out-of-the-box Yocto Project are engineered
+                so that they can run during root filesystem creation
+                (e.g. post-installation scripts for caching fonts).
+                However, if you create and add custom scripts, you need
+                to be sure they can be run during file system creation.
+            </para>
+
+            <para>
+                Here are some common problems that prevent
+                post-installation scripts from running during root filesystem
+                creation:
+                <itemizedlist>
+                    <listitem><para><emphasis>Not using $D in front of absolute paths:</emphasis>
+                        The build system defines
+                        <filename>$</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-D'><filename>D</filename></ulink>
+                        at root filesystem creation time, and
+                        it is blank when run on the target device.
+                        This implies two purposes for <filename>$D</filename>:
+                        ensuring paths are valid in both the host and target
+                        environments, and checking to determine which
+                        environment is being used as a method for taking
+                        appropriate actions.
+                        </para></listitem>
+                    <listitem><para><emphasis>Attempting to run processes that are
+                        specific to or dependent on the target
+                        architecture:</emphasis>
+                        You can work around these attempts by using native
+                        tools to accomplish the same tasks, or
+                        by alternatively running the processes under QEMU,
+                        which has the <filename>qemu_run_binary</filename>
+                        function.
+                        For more information, see the
+                        <filename>meta/classes/qemu.bbclass</filename>
+                        class in the
+                        <link linkend='source-directory'>Source Directory</link>.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='areas-with-write-access'>
+            <title>Areas With Write Access</title>
+
+            <para>
+                With the <filename>read-only-rootfs</filename> feature enabled,
+                any attempt by the target to write to the root filesystem at
+                runtime fails.
+                Consequently, you must make sure that you configure processes
+                and applications that attempt these types of writes do so
+                to directories with write access (e.g.
+                <filename>/tmp</filename> or <filename>/var/run</filename>).
+            </para>
+        </section>
+    </section>
+
+    <section id="performing-automated-runtime-testing">
+        <title>Performing Automated Runtime Testing</title>
+
+        <para>
+            The OpenEmbedded build system makes available a series of automated
+            tests for images to verify runtime functionality.
+            <note>
+                Currently, there is only support for running these tests
+                under QEMU.
+            </note>
+            These tests are written in Python making use of the
+            <filename>unittest</filename> module, and the majority of them
+            run commands on the target system over
+            <filename>ssh</filename>.
+            This section describes how you set up the environment to use these
+            tests, run available tests, and write and add your own tests.
+        </para>
+
+        <section id="qemu-image-enabling-tests">
+            <title>Enabling Tests</title>
+
+            <para>
+                In order to run tests, you need to do the following:
+                <itemizedlist>
+                    <listitem><para><emphasis>Set up to avoid interaction
+                        with <filename>sudo</filename> for networking:</emphasis>
+                        To accomplish this, you must do one of the
+                        following:
+                        <itemizedlist>
+                            <listitem><para>Add
+                                <filename>NOPASSWD</filename> for your user
+                                in <filename>/etc/sudoers</filename> either for
+                                ALL commands or just for
+                                <filename>runqemu-ifup</filename>.
+                                You must provide the full path as that can
+                                change if you are using multiple clones of the
+                                source repository.
+                                <note>
+                                    On some distributions, you also need to
+                                    comment out "Defaults requiretty" in
+                                    <filename>/etc/sudoers</filename>.
+                                </note></para></listitem>
+                            <listitem><para>Manually configure a tap interface
+                                for your system.</para></listitem>
+                            <listitem><para>Run as root the script in
+                                <filename>scripts/runqemu-gen-tapdevs</filename>,
+                                which should generate a list of tap devices.
+                                This is the option typically chosen for
+                                Autobuilder-type environments.
+                                </para></listitem>
+                        </itemizedlist></para></listitem>
+                    <listitem><para><emphasis>Set the
+                        <filename>DISPLAY</filename> variable:</emphasis>
+                        You need to set this variable so that you have an X
+                        server available (e.g. start
+                        <filename>vncserver</filename> for a headless machine).
+                        </para></listitem>
+                    <listitem><para><emphasis>Be sure your host's firewall
+                        accepts incoming connections from
+                        192.168.7.0/24:</emphasis>
+                        Some of the tests (in particular smart tests) start a
+                        HTTP server on a random high number port, which is
+                        used to serve files to the target.
+                        The smart module serves
+                        <filename>${DEPLOY_DIR}/rpm</filename> so it can run
+                        smart channel commands. That means your host's firewall
+                        must accept incoming connections from 192.168.7.0/24,
+                        which is the default IP range used for tap devices
+                        by <filename>runqemu</filename>.</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <note>
+                Regardless of how you initiate the tests, if you built your
+                image using <filename>rm_work</filename>,
+                most of the tests will fail with errors because they rely on
+                <filename>${WORKDIR}/installed_pkgs.txt</filename>.
+            </note>
+        </section>
+
+        <section id="qemu-image-running-tests">
+            <title>Running Tests</title>
+
+            <para>
+                You can start the tests automatically or manually:
+                <itemizedlist>
+                    <listitem><para><emphasis>Automatically Running Tests:</emphasis>
+                        To run the tests automatically after the
+                        OpenEmbedded build system successfully creates an image,
+                        first set the
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_IMAGE'><filename>TEST_IMAGE</filename></ulink>
+                        variable to "1" in your <filename>local.conf</filename>
+                        file in the
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                        <literallayout class='monospaced'>
+     TEST_IMAGE = "1"
+                        </literallayout>
+                        Next, simply build your image.
+                        If the image successfully builds, the tests will be
+                        run:
+                        <literallayout class='monospaced'>
+     bitbake core-image-sato
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Manually Running Tests:</emphasis>
+                        To manually run the tests, first globally inherit
+                        <ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-testimage'><filename>testimage.class</filename></ulink>
+                        by editing your <filename>local.conf</filename> file:
+                        <literallayout class='monospaced'>
+    INHERIT += "testimage"
+                        </literallayout>
+                        Next, use BitBake to run the tests:
+                        <literallayout class='monospaced'>
+     bitbake -c testimage &lt;image&gt;
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Regardless of how you run the tests, once they start, the
+                following happens:
+                <itemizedlist>
+                    <listitem><para>A copy of the root filesystem is written
+                        to <filename>${WORKDIR}/testimage</filename>.
+                        </para></listitem>
+                    <listitem><para>The image is booted under QEMU using the
+                        standard <filename>runqemu</filename> script.
+                        </para></listitem>
+                    <listitem><para>A default timeout of 500 seconds occurs
+                        to allow for the boot process to reach the login prompt.
+                        You can change the timeout period by setting
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_QEMUBOOT_TIMEOUT'><filename>TEST_QEMUBOOT_TIMEOUT</filename></ulink>
+                        in the <filename>local.conf</filename> file.
+                        </para></listitem>
+                    <listitem><para>Once the boot process is reached and the
+                        login prompt appears, the tests run.
+                        The full boot log is written to
+                        <filename>${WORKDIR}/testimage/qemu_boot_log</filename>.
+                        </para></listitem>
+                    <listitem><para>Each test module loads in the order found
+                        in <filename>TEST_SUITES</filename>.
+                        You can find the full output of the commands run over
+                        <filename>ssh</filename> in
+                        <filename>${WORKDIR}/testimgage/ssh_target_log</filename>.
+                        </para></listitem>
+                    <listitem><para>If no failures occur, the task running the
+                        tests ends successfully.
+                        You can find the output from the
+                        <filename>unittest</filename> in the task log at
+                        <filename>${WORKDIR}/temp/log.do_testimage</filename>.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                All test files reside in
+                <filename>meta/lib/oeqa/runtime</filename> in the
+                <link linkend='source-directory'>Source Directory</link>.
+                A test name maps directly to a Python module.
+                Each test module may contain a number of individual tests.
+                Tests are usually grouped together by the area
+                tested (e.g tests for <filename>systemd</filename> reside in
+                <filename>meta/lib/oeqa/runtime/systemd.py</filename>).
+            </para>
+
+            <para>
+                You can add tests to any layer provided you place them in the
+                proper area and you extend
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
+                in the <filename>local.conf</filename> file as normal.
+                Be sure that tests reside in
+                <filename>&lt;layer&gt;/lib/oeqa/runtime</filename>.
+                <note>
+                    Be sure that module names do not collide with module names
+                    used in the default set of test modules in
+                    <filename>meta/lib/oeqa/runtime</filename>.
+                </note>
+            </para>
+
+            <para>
+                You can change the set of tests run by appending or overriding
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-TEST_SUITES'><filename>TEST_SUITES</filename></ulink>
+                variable in <filename>local.conf</filename>.
+                Each name in <filename>TEST_SUITES</filename> represents a
+                required test for the image.
+                Test modules named within <filename>TEST_SUITES</filename>
+                cannot be skipped even if a test is not suitable for an image
+                (e.g. running the rpm tests on an image without
+                <filename>rpm</filename>).
+                Appending "auto" to <filename>TEST_SUITES</filename> causes the
+                build system to try to run all tests that are suitable for the
+                image (i.e. each test module may elect to skip itself).
+            </para>
+
+            <para>
+                The order you list tests in <filename>TEST_SUITES</filename>
+                is important.
+                The order influences test dependencies.
+                Consequently, tests that depend on other tests should be added
+                after the test on which they depend.
+                For example, since <filename>ssh</filename> depends on the
+                <filename>ping</filename> test, <filename>ssh</filename>
+                needs to come after <filename>ping</filename> in the list.
+                The test class provides no re-ordering or dependency handling.
+                <note>
+                    Each module can have multiple classes with multiple test
+                    methods.
+                    And, Python <filename>unittest</filename> rules apply.
+                </note>
+            </para>
+
+            <para>
+                Here are some things to keep in mind when running tests:
+                <itemizedlist>
+                    <listitem><para>The default tests for the image are defined
+                        as:
+                        <literallayout class='monospaced'>
+     DEFAULT_TEST_SUITES_pn-&lt;image&gt; = "ping ssh df connman syslog xorg scp vnc date rpm smart dmesg"
+                        </literallayout></para></listitem>
+                    <listitem><para>Add your own test to the list of the
+                        by using the following:
+                        <literallayout class='monospaced'>
+     TEST_SUITES_append = " mytest"
+                        </literallayout></para></listitem>
+                    <listitem><para>Run a specific list of tests as follows:
+                        <literallayout class='monospaced'>
+     TEST_SUITES = "test1 test2 test3"
+                        </literallayout>
+                        Remember, order is important.
+                        Be sure to place a test that is dependent on another test
+                        later in the order.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id="qemu-image-writing-new-tests">
+            <title>Writing New Tests</title>
+
+            <para>
+                As mentioned previously, all new test files need to be in the
+                proper place for the build system to find them.
+                New tests for additional functionality outside of the core
+                should be added to the layer that adds the functionality, in
+                <filename>&lt;layer&gt;/lib/oeqa/runtime</filename> (as
+                long as
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BBPATH'><filename>BBPATH</filename></ulink>
+                is extended in the layer's
+                <filename>layer.conf</filename> file as normal).
+                Just remember that filenames need to map directly to test
+                (module) names and that you do not use module names that
+                collide with existing core tests.
+            </para>
+
+            <para>
+                To create a new test, start by copying an existing module
+                (e.g. <filename>syslog.py</filename> or
+                <filename>gcc.py</filename> are good ones to use).
+                Test modules can use code from
+                <filename>meta/lib/oeqa/utils</filename>, which are helper
+                classes.
+            </para>
+
+            <note>
+                Structure shell commands such that you rely on them and they
+                return a single code for success.
+                Be aware that sometimes you will need to parse the output.
+                See the <filename>df.py</filename> and
+                <filename>date.py</filename> modules for examples.
+            </note>
+
+            <para>
+                You will notice that all test classes inherit
+                <filename>oeRuntimeTest</filename>, which is found in
+                <filename>meta/lib/oetest.py</filename>.
+                This base class offers some helper attributes, which are
+                described in the following sections:
+            </para>
+
+            <section id='qemu-image-writing-tests-class-methods'>
+                <title>Class Methods</title>
+
+                <para>
+                    Class methods are as follows:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>hasPackage(pkg)</filename>:</emphasis>
+                            Returns "True" if <filename>pkg</filename> is in the
+                            installed package list of the image, which is based
+                            on
+                            <filename>${WORKDIR}/installed_pkgs.txt</filename>
+                            that is generated during the
+                            <filename>do.rootfs</filename> task.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>hasFeature(feature)</filename>:</emphasis>
+                            Returns "True" if the feature is in
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
+                            or
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>restartTarget(params)</filename>:</emphasis>
+                            Restarts the QEMU image optionally passing
+                            <filename>params</filename> to the
+                            <filename>runqemu</filename> script's
+                            <filename>qemuparams</filename> list (e.g "-m 1024" for
+                            more memory).</para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+
+            <section id='qemu-image-writing-tests-class-attributes'>
+                <title>Class Attributes</title>
+
+                <para>
+                    Class attributes are as follows:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>pscmd</filename>:</emphasis>
+                            Equals "ps -ef" if <filename>procps</filename> is
+                            installed in the image.
+                            Otherwise, <filename>pscmd</filename> equals
+                            "ps" (busybox).
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>tc</filename>:</emphasis>
+                            The called text context, which gives access to the
+                            following attributes:
+                            <itemizedlist>
+                                <listitem><para><emphasis><filename>d</filename>:</emphasis>
+                                    The BitBake data store, which allows you to
+                                    use stuff such as
+                                    <filename>oeRuntimeTest.tc.d.getVar("VIRTUAL-RUNTIME_init_manager")</filename>.
+                                    </para></listitem>
+                                <listitem><para><emphasis><filename>testslist</filename> and <filename>testsrequired</filename>:</emphasis>
+                                    Used internally.
+                                    The tests do not need these.
+                                    </para></listitem>
+                                <listitem><para><emphasis><filename>filesdir</filename>:</emphasis>
+                                    The absolute path to
+                                    <filename>meta/lib/oeqa/runtime/files</filename>,
+                                    which contains helper files for tests meant
+                                    for copying on the target such as small
+                                    files written in C for compilation.
+                                    </para></listitem>
+                                <listitem><para><emphasis><filename>qemu</filename>:</emphasis>
+                                    Provides access to the
+                                    <filename>QemuRunner</filename> object,
+                                    which is the class that boots the image.
+                                    The <filename>qemu</filename> attribute
+                                    provides the following useful attributes:
+                                    <itemizedlist>
+                                        <listitem><para><emphasis><filename>ip</filename>:</emphasis>
+                                            The machine's IP address.
+                                            </para></listitem>
+                                        <listitem><para><emphasis><filename>host_ip</filename>:</emphasis>
+                                            The host IP address, which is only
+                                            used by smart tests.
+                                            </para></listitem>
+                                    </itemizedlist></para></listitem>
+                                <listitem><para><emphasis><filename>target</filename>:</emphasis>
+                                    The <filename>SSHControl</filename> object,
+                                    which is used for running the following
+                                    commands on the image:
+                                    <itemizedlist>
+                                        <listitem><para><emphasis><filename>host</filename>:</emphasis>
+                                            Used internally.
+                                            The tests do not use this command.
+                                            </para></listitem>
+                                        <listitem><para><emphasis><filename>timeout</filename>:</emphasis>
+                                            A global timeout for commands run on
+                                            the target for the instance of a
+                                            test.
+                                            The default is 300 seconds.
+                                            </para></listitem>
+                                        <listitem><para><emphasis><filename>run(cmd, timeout=None)</filename>:</emphasis>
+                                            The single, most used method.
+                                            This command is a wrapper for:
+                                            <filename>ssh root@host "cmd"</filename>.
+                                            The command returns a tuple:
+                                            (status, output), which are what
+                                            their names imply - the return code
+                                            of 'cmd' and whatever output
+                                            it produces.
+                                            The optional timeout argument
+                                            represents the number of seconds the
+                                            test should wait for 'cmd' to
+                                            return.
+                                            If the argument is "None", the
+                                            test uses the default instance's
+                                            timeout period, which is 300
+                                            seconds.
+                                            If the argument is "0", the test
+                                            runs until the command returns.
+                                            </para></listitem>
+                                        <listitem><para><emphasis><filename>copy_to(localpath, remotepath)</filename>:</emphasis>
+                                            <filename>scp localpath root@ip:remotepath</filename>.
+                                            </para></listitem>
+                                        <listitem><para><emphasis><filename>copy_from(remotepath, localpath)</filename>:</emphasis>
+                                            <filename>scp root@host:remotepath localpath</filename>.
+                                            </para></listitem>
+                                    </itemizedlist></para></listitem>
+                            </itemizedlist></para></listitem>
+                    </itemizedlist>
+                </para>
+            </section>
+
+            <section id='qemu-image-writing-tests-instance-attributes'>
+                <title>Instance Attributes</title>
+
+                <para>
+                    A single instance attribute exists, which is
+                    <filename>target</filename>.
+                    The <filename>target</filename> instance attribute is
+                    identical to the class attribute of the same name, which
+                    is described in the previous section.
+                    This attribute exists as both an instance and class
+                    attribute so tests can use
+                    <filename>self.target.run(cmd)</filename> in instance
+                    methods instead of
+                    <filename>oeRuntimeTest.tc.target.run(cmd)</filename>.
+                </para>
+            </section>
+        </section>
+    </section>
+
+    <section id="platdev-gdb-remotedebug">
+        <title>Debugging With the GNU Project Debugger (GDB) Remotely</title>
+
+        <para>
+            GDB allows you to examine running programs, which in turn helps you to understand and fix problems.
+            It also allows you to perform post-mortem style analysis of program crashes.
+            GDB is available as a package within the Yocto Project and is
+            installed in SDK images by default.
+            See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
+            in the Yocto Project Reference Manual for a description of these images.
+            You can find information on GDB at <ulink url="http://sourceware.org/gdb/"/>.
+        </para>
+
+        <tip>
+            For best results, install <filename>-dbg</filename> packages for
+            the applications you are going to debug.
+            Doing so makes extra debug symbols available that give you more
+            meaningful output.
+        </tip>
+
+        <para>
+            Sometimes, due to memory or disk space constraints, it is not possible
+            to use GDB directly on the remote target to debug applications.
+            These constraints arise because GDB needs to load the debugging information and the
+            binaries of the process being debugged.
+            Additionally, GDB needs to perform many computations to locate information such as function
+            names, variable names and values, stack traces and so forth - even before starting the
+            debugging process.
+            These extra computations place more load on the target system and can alter the
+            characteristics of the program being debugged.
+        </para>
+
+        <para>
+            To help get past the previously mentioned constraints, you can use Gdbserver.
+            Gdbserver runs on the remote target and does not load any debugging information
+            from the debugged process.
+            Instead, a GDB instance processes the debugging information that is run on a
+            remote computer - the host GDB.
+            The host GDB then sends control commands to Gdbserver to make it stop or start the debugged
+            program, as well as read or write memory regions of that debugged program.
+            All the debugging information loaded and processed as well
+            as all the heavy debugging is done by the host GDB.
+            Offloading these processes gives the Gdbserver running on the target a chance to remain
+            small and fast.
+        </para>
+
+        <para>
+            Because the host GDB is responsible for loading the debugging information and
+            for doing the necessary processing to make actual debugging happen, the
+            user has to make sure the host can access the unstripped binaries complete
+            with their debugging information and also be sure the target is compiled with no optimizations.
+            The host GDB must also have local access to all the libraries used by the
+            debugged program.
+            Because Gdbserver does not need any local debugging information, the binaries on
+            the remote target can remain stripped.
+            However, the binaries must also be compiled without optimization
+            so they match the host's binaries.
+        </para>
+
+        <para>
+            To remain consistent with GDB documentation and terminology, the binary being debugged
+            on the remote target machine is referred to as the "inferior" binary.
+            For documentation on GDB see the
+            <ulink url="http://sourceware.org/gdb/documentation/">GDB site</ulink>.
+        </para>
+
+        <para>
+            The remainder of this section describes the steps you need to take
+            to debug using the GNU project debugger.
+        </para>
+
+        <section id='platdev-gdb-remotedebug-setup'>
+            <title>Set Up the Cross-Development Debugging Environment</title>
+
+            <para>
+                Before you can initiate a remote debugging session, you need
+                to be sure you have set up the cross-development environment,
+                toolchain, and sysroot.
+                The "<ulink url='&YOCTO_DOCS_ADT_URL;#adt-prepare'>Preparing for Application Development</ulink>"
+                chapter of the Yocto Project Application Developer's Guide
+                describes this process.
+                Be sure you have read that chapter and have set up
+                your environment.
+            </para>
+        </section>
+
+        <section id="platdev-gdb-remotedebug-launch-gdbserver">
+            <title>Launch Gdbserver on the Target</title>
+
+            <para>
+                Make sure Gdbserver is installed on the target.
+                If it is not, install the package
+                <filename>gdbserver</filename>, which needs the
+                <filename>libthread-db1</filename> package.
+            </para>
+
+            <para>
+                Here is an example that when entered from the host
+                connects to the target and launches Gdbserver in order to
+                "debug" a binary named <filename>helloworld</filename>:
+                <literallayout class='monospaced'>
+     $ gdbserver localhost:2345 /usr/bin/helloworld
+                </literallayout>
+                Gdbserver should now be listening on port 2345 for debugging
+                commands coming from a remote GDB process that is running on
+                the host computer.
+                Communication between Gdbserver and the host GDB are done
+                using TCP.
+                To use other communication protocols, please refer to the
+                <ulink url='http://www.gnu.org/software/gdb/'>Gdbserver documentation</ulink>.
+            </para>
+        </section>
+
+        <section id="platdev-gdb-remotedebug-launch-gdb">
+            <title>Launch GDB on the Host Computer</title>
+
+            <para>
+                Running GDB on the host computer takes a number of stages, which
+                this section describes.
+            </para>
+
+            <section id="platdev-gdb-remotedebug-launch-gdb-buildcross">
+                <title>Build the Cross-GDB Package</title>
+                <para>
+                    A suitable GDB cross-binary is required that runs on your
+                    host computer but also knows about the the ABI of the
+                    remote target.
+                    You can get this binary from the
+                    <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
+                    Here is an example where the toolchain has been installed
+                    in the default directory
+                    <filename>/opt/poky/&DISTRO;</filename>:
+                    <literallayout class='monospaced'>
+     /opt/poky/1.4/sysroots/i686-pokysdk-linux/usr/bin/armv7a-vfp-neon-poky-linux-gnueabi/arm-poky-linux-gnueabi-gdb
+                    </literallayout>
+                    where <filename>arm</filename> is the target architecture
+                    and <filename>linux-gnueabi</filename> is the target ABI.
+                </para>
+
+                <para>
+                    Alternatively, you can use BitBake to build the
+                    <filename>gdb-cross</filename> binary.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ bitbake gdb-cross
+                    </literallayout>
+                    Once the binary is built, you can find it here:
+                    <literallayout class='monospaced'>
+     tmp/sysroots/&lt;host-arch&gt;/usr/bin/&lt;target-platform&gt;/&lt;target-abi&gt;-gdb
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='create-the-gdb-initialization-file'>
+                <title>Create the GDB Initialization File and Point to Your Root Filesystem</title>
+
+                <para>
+                    Aside from the GDB cross-binary, you also need a GDB
+                    initialization file in the same top directory in which
+                    your binary resides.
+                    When you start GDB on your host development system, GDB
+                    finds this initialization file and executes all the
+                    commands within.
+                    For information on the <filename>.gdbinit</filename>, see
+                    "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>",
+                    which is maintained by
+                    <ulink url='http://www.sourceware.org'>sourceware.org</ulink>.
+                </para>
+
+                <para>
+                    You need to add a statement in the
+                    <filename>.gdbinit</filename> file that points to your
+                    root filesystem.
+                    Here is an example that points to the root filesystem for
+                    an ARM-based target device:
+                    <literallayout class='monospaced'>
+     set sysroot /home/jzhang/sysroot_arm
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id="platdev-gdb-remotedebug-launch-gdb-launchhost">
+                <title>Launch the Host GDB</title>
+
+                <para>
+                    Before launching the host GDB, you need to be sure
+                    you have sourced the cross-debugging environment script,
+                    which if you installed the root filesystem in the default
+                    location is at <filename>/opt/poky/&DISTRO;</filename>
+                    and begins with the string "environment-setup".
+                    For more information, see the
+                    "<ulink url='&YOCTO_DOCS_ADT_URL;#setting-up-the-cross-development-environment'>Setting Up the Cross-Development Environment</ulink>"
+                    section in the Yocto Project Application Developer's
+                    Guide.
+                </para>
+
+                <para>
+                    Finally, switch to the directory where the binary resides
+                    and run the <filename>cross-gdb</filename> binary.
+                    Provide the binary file you are going to debug.
+                    For example, the following command continues with the
+                    example used in the previous section by loading
+                    the <filename>helloworld</filename> binary as well as the
+                    debugging information:
+                    <literallayout class='monospaced'>
+     $ arm-poky-linux-gnuabi-gdb helloworld
+                    </literallayout>
+                    The commands in your <filename>.gdbinit</filename> execute
+                    and the GDB prompt appears.
+                </para>
+            </section>
+        </section>
+
+        <section id='platdev-gdb-connect-to-the-remote-gdb-server'>
+            <title>Connect to the Remote GDB Server</title>
+
+            <para>
+                From the target, you need to connect to the remote GDB
+                server that is running on the host.
+                You need to specify the remote host and port.
+                Here is the command continuing with the example:
+                <literallayout class='monospaced'>
+     target remote 192.168.7.2:2345
+                </literallayout>
+            </para>
+        </section>
+
+        <section id="platdev-gdb-remotedebug-launch-gdb-using">
+            <title>Use the Debugger</title>
+
+            <para>
+                You can now proceed with debugging as normal - as if you were debugging
+                on the local machine.
+                For example, to instruct GDB to break in the "main" function and then
+                continue with execution of the inferior binary use the following commands
+                from within GDB:
+                <literallayout class='monospaced'>
+     (gdb) break main
+     (gdb) continue
+                </literallayout>
+            </para>
+
+            <para>
+                For more information about using GDB, see the project's online documentation at
+                <ulink url="http://sourceware.org/gdb/download/onlinedocs/"/>.
+            </para>
+        </section>
+    </section>
+
+    <section id="examining-builds-using-toaster">
+        <title>Examining Builds Using the Toaster API</title>
+
+        <para>
+            Toaster is an Application Programming Interface (API) and
+            web-based interface to the OpenEmbedded build system, which uses
+            BitBake.
+            Both interfaces are based on a Representational State Transfer
+            (REST) API that queries for and returns build information using
+            <filename>GET</filename> and <filename>JSON</filename>.
+            These types of search operations retrieve sets of objects from
+            a data store used to collect build information.
+            The results contain all the data for the objects being returned.
+            You can order the results of the search by key and the search
+            parameters are consistent for all object types.
+        </para>
+
+        <para>
+            Using the interfaces you can do the following:
+            <itemizedlist>
+                <listitem><para>See information about the tasks executed
+                    and reused during the build.</para></listitem>
+                <listitem><para>See what is built (recipes and
+                    packages) and what packages were installed into the final
+                    image.</para></listitem>
+                <listitem><para>See performance-related information such
+                    as build time, CPU usage, and disk I/O.</para></listitem>
+                <listitem><para>Examine error, warning and trace messages
+                    to aid in debugging.</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <note>
+            <para>This release of Toaster provides you with information
+            about a BitBake run.
+            The tool does not allow you to configure and launch a build.
+            However, future development includes plans to integrate the
+            configuration and build launching capabilities of
+            <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
+            </para>
+            <para>For more information on using Hob to build an image,
+            see the
+            "<link linkend='image-development-using-hob'>Image Development Using Hob</link>"
+            section.</para>
+        </note>
+
+        <para>
+            The remainder of this section describes what you need to have in
+            place to use Toaster, how to start it, use it, and stop it.
+            For additional information on installing and running Toaster, see the
+            "<ulink url='https://wiki.yoctoproject.org/wiki/Toaster#Installation_and_Running'>Installation and Running</ulink>"
+            section of the "Toaster" wiki page.
+            For complete information on the API and its search operation
+            URI, parameters, and responses, see the
+            <ulink url='https://wiki.yoctoproject.org/wiki/REST_API_Contracts'>REST API Contracts</ulink>
+            Wiki page.
+        </para>
+
+        <section id='starting-toaster'>
+            <title>Starting Toaster</title>
+
+            <para>
+                Getting set up to use and start Toaster is simple.
+                First, be sure you have met the following requirements:
+                <itemizedlist>
+                    <listitem><para>You have set up your
+                        <link linkend='source-directory'>Source Directory</link>
+                        by cloning the upstream <filename>poky</filename>
+                        repository.
+                        See the
+                        <link linkend='local-yp-release'>Yocto Project Release</link>
+                        item for information on how to set up the Source
+                        Directory.</para></listitem>
+                    <listitem><para>You have checked out the
+                        <filename>dora-toaster</filename> branch:
+                        <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ git checkout -b dora-toaster origin/dora-toaster
+                        </literallayout></para></listitem>
+                    <listitem><para>Be sure your build machine has
+                        <ulink url='http://en.wikipedia.org/wiki/Django_%28web_framework%29'>Django</ulink>
+                        version 1.4.5 installed.</para></listitem>
+                    <listitem><para>Make sure that port 8000 and 8200 are
+                        free (i.e. they have no servers on them).
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Once you have met the requirements, follow these steps to
+                start Toaster running in the background of your shell:
+                <orderedlist>
+                    <listitem><para><emphasis>Set up your build environment:</emphasis>
+                        Source a build environment script (i.e.
+                        <filename>oe-init-build-env</filename> or
+                        <filename>oe-init-build-env-memres</filename>).
+                        </para></listitem>
+                    <listitem><para><emphasis>Prepare your local configuration file:</emphasis>
+                        Toaster needs the Toaster class enabled
+                        in Bitbake in order to record target image package
+                        information.
+                        You can enable it by adding the following line to your
+                        <filename>conf/local.conf</filename> file:
+                        <literallayout class='monospaced'>
+     INHERIT += "toaster"
+                        </literallayout>
+                        Toaster also needs Build History enabled in Bitbake in
+                        order to record target image package information.
+                        You can enable this by adding the following two lines
+                        to your <filename>conf/local.conf</filename> file:
+                        <literallayout class='monospaced'>
+     INHERIT += "buildhistory"
+     BUILDHISTORY_COMMIT = "1"
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Start Toaster:</emphasis>
+                        Start the Toaster service using this
+                        command from within your build directory:
+                        <literallayout class='monospaced'>
+     $ source toaster start
+                        </literallayout></para></listitem>
+                        <note>
+                            The Toaster must be started and running in order
+                            for it to collect data.
+                        </note>
+                </orderedlist>
+            </para>
+
+            <para>
+                When Toaster starts, it creates some additional files in your
+                Build Directory.
+                Deleting these files will cause you to lose data or interrupt
+                Toaster:
+                <itemizedlist>
+                    <listitem><para><emphasis><filename>toaster.sqlite</filename>:</emphasis>
+                        Toaster's database file.</para></listitem>
+                    <listitem><para><emphasis><filename>toaster_web.log</filename>:</emphasis>
+                        The log file of the web server.</para></listitem>
+                    <listitem><para><emphasis><filename>toaster_ui.log</filename>:</emphasis>
+                        The log file of the user interface component.
+                        </para></listitem>
+                    <listitem><para><emphasis><filename>toastermain.pid</filename>:</emphasis>
+                        The PID of the web server.</para></listitem>
+                    <listitem><para><emphasis><filename>toasterui.pid</filename>:</emphasis>
+                        The PID of the DSI data bridge.</para></listitem>
+                    <listitem><para><emphasis><filename>bitbake-cookerdaemon.log</filename>:</emphasis>
+                        The BitBake server's log file.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='using-toaster'>
+            <title>Using Toaster</title>
+
+            <para>
+                Once Toaster is running, it logs information for any BitBake
+                run from your Build Directory.
+                This logging is automatic.
+                All you need to do is access and use the information.
+            </para>
+
+            <para>
+                You access the information one of two ways:
+                <itemizedlist>
+                    <listitem><para>Open a Browser and type enter in the
+                        <filename>http://localhost:8000</filename> URL.
+                        </para></listitem>
+                    <listitem><para>Use the <filename>xdg-open</filename>
+                        tool from the shell and pass it the same URL.
+                        </para></listitem>
+                </itemizedlist>
+                Either method opens the home page for the Toaster interface,
+                which is temporary for this release.
+            </para>
+        </section>
+
+        <section id='examining-toaster-data'>
+            <title>Examining Toaster Data</title>
+
+            <para>
+                The Toaster database is persistent regardless of whether you
+                start or stop the service.
+            </para>
+
+            <para>
+                Toaster's interface shows you a list of builds
+                (successful and unsuccessful) for which it has data.
+                You can click on any build to see related information.
+                This information includes configuration details, information
+                about tasks, all recipes and packages built and their
+                dependencies, packages installed in your final image,
+                execution time, CPU usage and disk I/O per task.
+            </para>
+        </section>
+
+        <section id='stopping-toaster'>
+            <title>Stopping Toaster</title>
+
+            <para>
+                Stop the Toaster service with the following command:
+                <literallayout class='monospaced'>
+     $ source toaster stop
+                </literallayout>
+                The service stops but the Toaster database remains persistent.
+            </para>
+        </section>
+    </section>
+
+    <section id="platdev-oprofile">
+        <title>Profiling with OProfile</title>
+
+        <para>
+            <ulink url="http://oprofile.sourceforge.net/">OProfile</ulink> is a
+            statistical profiler well suited for finding performance
+            bottlenecks in both user-space software and in the kernel.
+            This profiler provides answers to questions like "Which functions does my application spend
+            the most time in when doing X?"
+            Because the OpenEmbedded build system is well integrated with OProfile, it makes profiling
+            applications on target hardware straightforward.
+            <note>
+                For more information on how to set up and run OProfile, see the
+                "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>OProfile</ulink>"
+                section in the Yocto Project Profiling and Tracing Manual.
+            </note>
+        </para>
+
+        <para>
+            To use OProfile, you need an image that has OProfile installed.
+            The easiest way to do this is with <filename>tools-profile</filename> in the
+            <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'>IMAGE_FEATURES</ulink></filename> variable.
+            You also need debugging symbols to be available on the system where the analysis
+            takes place.
+            You can gain access to the symbols by using <filename>dbg-pkgs</filename> in the
+            <filename>IMAGE_FEATURES</filename> variable or by
+            installing the appropriate <filename>-dbg</filename> packages.
+        </para>
+
+        <para>
+            For successful call graph analysis, the binaries must preserve the frame
+            pointer register and should also be compiled with the
+            <filename>-fno-omit-framepointer</filename> flag.
+            You can achieve this by setting the
+            <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</ulink></filename>
+            variable with the following options:
+            <literallayout class='monospaced'>
+     -fexpensive-optimizations
+     -fno-omit-framepointer
+     -frename-registers
+     -O2
+            </literallayout>
+            You can also achieve it by setting the
+            <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DEBUG_BUILD'>DEBUG_BUILD</ulink></filename>
+            variable to "1" in the <filename>local.conf</filename> configuration file.
+            If you use the <filename>DEBUG_BUILD</filename> variable,
+            you also add extra debugging information that can make the debug
+            packages large.
+        </para>
+
+        <section id="platdev-oprofile-target">
+            <title>Profiling on the Target</title>
+
+            <para>
+                Using OProfile you can perform all the profiling work on the target device.
+                A simple OProfile session might look like the following:
+            </para>
+
+            <para>
+                <literallayout class='monospaced'>
+     # opcontrol --reset
+     # opcontrol --start --separate=lib --no-vmlinux -c 5
+              .
+              .
+        [do whatever is being profiled]
+              .
+              .
+     # opcontrol --stop
+     $ opreport -cl
+                </literallayout>
+            </para>
+
+            <para>
+                In this example, the <filename>reset</filename> command clears any previously profiled data.
+                The next command starts OProfile.
+                The options used when starting the profiler separate dynamic library data
+                within applications, disable kernel profiling, and enable callgraphing up to
+                five levels deep.
+                <note>
+                    To profile the kernel, you would specify the
+                    <filename>--vmlinux=/path/to/vmlinux</filename> option.
+                    The <filename>vmlinux</filename> file is usually in the source directory in the
+                    <filename>/boot/</filename> directory and must match the running kernel.
+                </note>
+            </para>
+
+            <para>
+                After you perform your profiling tasks, the next command stops the profiler.
+                After that, you can view results with the <filename>opreport</filename> command with options
+                to see the separate library symbols and callgraph information.
+            </para>
+
+            <para>
+                Callgraphing logs information about time spent in functions and about a function's
+                calling function (parent) and called functions (children).
+                The higher the callgraphing depth, the more accurate the results.
+                However, higher depths also increase the logging overhead.
+                Consequently, you should take care when setting the callgraphing depth.
+                <note>
+                    On ARM, binaries need to have the frame pointer enabled for callgraphing to work.
+                    To accomplish this use the <filename>-fno-omit-framepointer</filename> option
+                    with <filename>gcc</filename>.
+                </note>
+            </para>
+
+            <para>
+                For more information on using OProfile, see the OProfile
+                online documentation at
+                <ulink url="http://oprofile.sourceforge.net/docs/"/>.
+            </para>
+        </section>
+
+        <section id="platdev-oprofile-oprofileui">
+            <title>Using OProfileUI</title>
+
+            <para>
+                A graphical user interface for OProfile is also available.
+                You can download and build this interface from the Yocto Project at
+                <ulink url="&YOCTO_GIT_URL;/cgit.cgi/oprofileui/"></ulink>.
+                If the "tools-profile" image feature is selected, all necessary binaries
+                are installed onto the target device for OProfileUI interaction.
+                For a list of image features that ship with the Yocto Project,
+                see the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-features-image'>Images</ulink>"
+                section in the Yocto Project Reference Manual.
+            </para>
+
+            <para>
+                Even though the source directory usually includes all needed patches on the target device, you
+                might find you need other OProfile patches for recent OProfileUI features.
+                If so, see the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/oprofileui/tree/README'>
+                OProfileUI README</ulink> for the most recent information.
+            </para>
+
+            <section id="platdev-oprofile-oprofileui-online">
+                <title>Online Mode</title>
+
+                <para>
+                    Using OProfile in online mode assumes a working network connection with the target
+                    hardware.
+                    With this connection, you just need to run "oprofile-server" on the device.
+                    By default, OProfile listens on port 4224.
+                    <note>
+                        You can change the port using the <filename>--port</filename> command-line
+                        option.
+                    </note>
+                </para>
+
+                <para>
+                    The client program is called <filename>oprofile-viewer</filename> and its UI is relatively
+                    straightforward.
+                    You access key functionality through the buttons on the toolbar, which
+                    are duplicated in the menus.
+                    Here are the buttons:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Connect:</emphasis> Connects to the remote host.
+                            You can also supply the IP address or hostname.</para></listitem>
+                        <listitem><para><emphasis>Disconnect:</emphasis> Disconnects from the target.
+                            </para></listitem>
+                        <listitem><para><emphasis>Start:</emphasis> Starts profiling on the device.
+                            </para></listitem>
+                        <listitem><para><emphasis>Stop:</emphasis> Stops profiling on the device and
+                            downloads the data to the local host.
+                            Stopping the profiler generates the profile and displays it in the viewer.
+                            </para></listitem>
+                        <listitem><para><emphasis>Download:</emphasis> Downloads the data from the
+                            target and generates the profile, which appears in the viewer.</para></listitem>
+                        <listitem><para><emphasis>Reset:</emphasis> Resets the sample data on the device.
+                            Resetting the data removes sample information collected from previous
+                            sampling runs.
+                            Be sure you reset the data if you do not want to include old sample information.
+                            </para></listitem>
+                        <listitem><para><emphasis>Save:</emphasis> Saves the data downloaded from the
+                            target to another directory for later examination.</para></listitem>
+                        <listitem><para><emphasis>Open:</emphasis> Loads previously saved data.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    The client downloads the complete 'profile archive' from
+                    the target to the host for processing.
+                    This archive is a directory that contains the sample data, the object files,
+                    and the debug information for the object files.
+                    The archive is then converted using the <filename>oparchconv</filename> script, which is
+                    included in this distribution.
+                    The script uses <filename>opimport</filename> to convert the archive from
+                    the target to something that can be processed on the host.
+                </para>
+
+                <para>
+                    Downloaded archives reside in the
+                    <link linkend='build-directory'>Build Directory</link> in
+                    <filename>/tmp</filename> and are cleared up when they are no longer in use.
+                </para>
+
+                <para>
+                    If you wish to perform kernel profiling, you need to be sure
+                    a <filename>vmlinux</filename> file that matches the running kernel is available.
+                    In the source directory, that file is usually located in
+                    <filename>/boot/vmlinux-KERNELVERSION</filename>, where
+                    <filename>KERNEL-version</filename> is the version of the kernel.
+                    The OpenEmbedded build system generates separate <filename>vmlinux</filename>
+                    packages for each kernel it builds.
+                    Thus, it should just be a question of making sure a matching package is
+                    installed (e.g. <filename>opkg install kernel-vmlinux</filename>).
+                    The files are automatically installed into development and profiling images
+                    alongside OProfile.
+                    A configuration option exists within the OProfileUI settings page that you can use to
+                    enter the location of the <filename>vmlinux</filename> file.
+                </para>
+
+                <para>
+                    Waiting for debug symbols to transfer from the device can be slow, and it
+                    is not always necessary to actually have them on the device for OProfile use.
+                    All that is needed is a copy of the filesystem with the debug symbols present
+                    on the viewer system.
+                    The "<link linkend='platdev-gdb-remotedebug-launch-gdb'>Launch GDB on the Host Computer</link>"
+                    section covers how to create such a directory with
+                    the <link linkend='source-directory'>Source Directory</link>
+                    and how to use the OProfileUI Settings Dialog to specify the location.
+                    If you specify the directory, it will be used when the file checksums
+                    match those on the system you are profiling.
+                </para>
+            </section>
+
+            <section id="platdev-oprofile-oprofileui-offline">
+                <title>Offline Mode</title>
+
+                <para>
+                    If network access to the target is unavailable, you can generate
+                    an archive for processing in <filename>oprofile-viewer</filename> as follows:
+                    <literallayout class='monospaced'>
+     # opcontrol --reset
+     # opcontrol --start --separate=lib --no-vmlinux -c 5
+            .
+            .
+     [do whatever is being profiled]
+            .
+            .
+     # opcontrol --stop
+     # oparchive -o my_archive
+                    </literallayout>
+                </para>
+
+                <para>
+                    In the above example, <filename>my_archive</filename> is the name of the
+                    archive directory where you would like the profile archive to be kept.
+                    After the directory is created, you can copy it to another host and load it
+                    using <filename>oprofile-viewer</filename> open functionality.
+                    If necessary, the archive is converted.
+                </para>
+            </section>
+        </section>
+    </section>
+
+    <section id='maintaining-open-source-license-compliance-during-your-products-lifecycle'>
+        <title>Maintaining Open Source License Compliance During Your Product's Lifecycle</title>
+
+        <para>
+            One of the concerns for a development organization using open source
+            software is how to maintain compliance with various open source
+            licensing during the lifecycle of the product.
+            While this section does not provide legal advice or
+            comprehensively cover all scenarios, it does
+            present methods that you can use to
+            assist you in meeting the compliance requirements during a software
+            release.
+        </para>
+
+        <para>
+            With hundreds of different open source licenses that the Yocto
+            Project tracks, it is difficult to know the requirements of each
+            and every license.
+            However, we can begin to cover the requirements of the major FLOSS licenses, by
+            assuming that there are three main areas of concern:
+            <itemizedlist>
+                <listitem><para>Source code must be provided.</para></listitem>
+                <listitem><para>License text for the software must be
+                    provided.</para></listitem>
+                <listitem><para>Compilation scripts and modifications to the
+                    source code must be provided.
+                    </para></listitem>
+            </itemizedlist>
+            There are other requirements beyond the scope of these
+            three and the methods described in this section
+            (e.g. the mechanism through which source code is distributed).
+        </para>
+
+        <para>
+            As different organizations have different methods of complying with
+            open source licensing, this section is not meant to imply that
+            there is only one single way to meet your compliance obligations,
+            but rather to describe one method of achieving compliance.
+            The remainder of this section describes methods supported to meet the
+            previously mentioned three requirements.
+            Once you take steps to meet these requirements,
+            and prior to releasing images, sources, and the build system,
+            you should audit all artifacts to ensure completeness.
+            <note>
+                The Yocto Project generates a license manifest during
+                image creation that is located
+                in <filename>${DEPLOY_DIR}/licenses/&lt;image_name-datestamp&gt;</filename>
+                to assist with any audits.
+            </note>
+        </para>
+
+        <section id='providing-the-source-code'>
+            <title>Providing the Source Code</title>
+
+            <para>
+                Compliance activities should begin before you generate the
+                final image.
+                The first thing you should look at is the requirement that
+                tops the list for most compliance groups - providing
+                the source.
+                The Yocto Project has a few ways of meeting this
+                requirement.
+            </para>
+
+            <para>
+                One of the easiest ways to meet this requirement is
+                to provide the entire
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+                used by the build.
+                This method, however, has a few issues.
+                The most obvious is the size of the directory since it includes
+                all sources used in the build and not just the source used in
+                the released image.
+                It will include toolchain source, and other artifacts, which
+                you would not generally release.
+                However, the more serious issue for most companies is accidental
+                release of proprietary software.
+                The Yocto Project provides an archiver class to help avoid
+                some of these concerns.
+                See the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-archiver'>Archiving Sources - <filename>archive*.bbclass</filename></ulink>"
+                section in the Yocto Project Reference Manual for information
+                on this class.
+            </para>
+
+            <para>
+                Before you employ <filename>DL_DIR</filename> or the
+                archiver class, you need to decide how you choose to
+                provide source.
+                The source archiver class can generate tarballs and SRPMs
+                and can create them with various levels of compliance in mind.
+                One way of doing this (but certainly not the only way) is to
+                release just the original source as a tarball.
+                You can do this by adding the following to the
+                <filename>local.conf</filename> file found in the
+                <link linkend='build-directory'>Build Directory</link>:
+                <literallayout class='monospaced'>
+     ARCHIVER_MODE ?= "original"
+     ARCHIVER_CLASS = "${@'archive-${ARCHIVER_MODE}-source' if
+     ARCHIVER_MODE != 'none' else ''}"
+     INHERIT += "${ARCHIVER_CLASS}"
+     SOURCE_ARCHIVE_PACKAGE_TYPE = "tar"
+                </literallayout>
+                During the creation of your image, the source from all
+                recipes that deploy packages to the image is placed within
+                subdirectories of
+                <filename>DEPLOY_DIR/sources</filename> based on the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE</filename></ulink>
+                for each recipe.
+                Releasing the entire directory enables you to comply with
+                requirements concerning providing the unmodified source.
+                It is important to note that the size of the directory can
+                get large.
+            </para>
+
+            <para>
+                A way to help mitigate the size issue is to only release
+                tarballs for licenses that require the release of
+                source.
+                Let's assume you are only concerned with GPL code as
+                identified with the following:
+                <literallayout class='monospaced'>
+     $ cd poky/build/tmp/deploy/sources
+     $ mkdir ~/gpl_source_release
+     $ for dir in */*GPL*; do cp -r $dir ~/gpl_source_release; done
+                </literallayout>
+                At this point, you could create a tarball from the
+                <filename>gpl_source_release</filename> directory and
+                provide that to the end user.
+                This method would be a step toward achieving compliance
+                with section 3a of GPLv2 and with section 6 of GPLv3.
+            </para>
+        </section>
+
+        <section id='providing-license-text'>
+            <title>Providing License Text</title>
+
+            <para>
+                One requirement that is often overlooked is inclusion
+                of license text.
+                This requirement also needs to be dealt with prior to
+                generating the final image.
+                Some licenses require the license text to accompany
+                the binary.
+                You can achieve this by adding the following to your
+                <filename>local.conf</filename> file:
+                <literallayout class='monospaced'>
+     COPY_LIC_MANIFEST = "1"
+     COPY_LIC_DIRS = "1"
+                </literallayout>
+                Adding these statements to the configuration file ensures
+                that the licenses collected during package generation
+                are included on your image.
+                As the source archiver has already archived the original
+                unmodified source that contains the license files,
+                you would have already met the requirements for inclusion
+                of the license information with source as defined by the GPL
+                and other open source licenses.
+            </para>
+        </section>
+
+        <section id='providing-compilation-scripts-and-source-code-modifications'>
+            <title>Providing Compilation Scripts and Source Code Modifications</title>
+
+            <para>
+                At this point, we have addressed all we need to address
+                prior to generating the image.
+                The next two requirements are addressed during the final
+                packaging of the release.
+            </para>
+
+            <para>
+                By releasing the version of the OpenEmbedded build system
+                and the layers used during the build, you will be providing both
+                compilation scripts and the source code modifications in one
+                step.
+            </para>
+
+            <para>
+                If the deployment team has a
+                <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP layer</ulink>
+                and a distro layer, and those those layers are used to patch,
+                compile, package, or modify (in any way) any open source
+                software included in your released images, you
+                may be required to to release those layers under section 3 of
+                GPLv2 or section 1 of GPLv3.
+                One way of doing that is with a clean
+                checkout of the version of the Yocto Project and layers used
+                during your build.
+                Here is an example:
+                <literallayout class='monospaced'>
+     # We built using the &DISTRO_NAME; branch of the poky repo
+     $ git clone -b &DISTRO_NAME; git://git.yoctoproject.org/poky
+     $ cd poky
+     # We built using the release_branch for our layers
+     $ git clone -b release_branch git://git.mycompany.com/meta-my-bsp-layer
+     $ git clone -b release_branch git://git.mycompany.com/meta-my-software-layer
+     # clean up the .git repos
+     $ find . -name ".git" -type d -exec rm -rf {} \;
+                </literallayout>
+                One thing a development organization might want to consider
+                for end-user convenience is to modify
+                <filename>meta-yocto/conf/bblayers.conf.sample</filename> to
+                ensure that when the end user utilizes the released build
+                system to build an image, the development organization's
+                layers are included in the <filename>bblayers.conf</filename>
+                file automatically:
+                <literallayout class='monospaced'>
+     # LAYER_CONF_VERSION is increased each time build/conf/bblayers.conf
+     # changes incompatibly
+     LCONF_VERSION = "6"
+
+     BBPATH = "${TOPDIR}"
+     BBFILES ?= ""
+
+     BBLAYERS ?= " \
+       ##OEROOT##/meta \
+       ##OEROOT##/meta-yocto \
+       ##OEROOT##/meta-yocto-bsp \
+       ##OEROOT##/meta-mylayer \
+       "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+       ##OEROOT##/meta \
+       ##OEROOT##/meta-yocto \
+       "
+                </literallayout>
+                Creating and providing an archive of the
+                <link linkend='metadata'>Metadata</link> layers
+                (recipes, configuration files, and so forth)
+                enables you to meet your
+                requirements to include the scripts to control compilation
+                as well as any modifications to the original source.
+            </para>
+        </section>
+    </section>
+</chapter>
+
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/dev-manual/dev-manual-customization.xsl b/documentation/dev-manual/dev-manual-customization.xsl
new file mode 100644
index 0000000000..8969605989
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-customization.xsl
@@ -0,0 +1,10 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+  
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+  <xsl:param name="html.stylesheet" select="'dev-style.css'" />
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/dev-manual/dev-manual-eclipse-customization.xsl b/documentation/dev-manual/dev-manual-eclipse-customization.xsl
new file mode 100644
index 0000000000..8ac4c18f25
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-eclipse-customization.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+        xmlns="http://www.w3.org/1999/xhtml"
+        xmlns:fo="http://www.w3.org/1999/XSL/Format"
+        version="1.0">
+
+  <xsl:import
+          href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="chunk.quietly" select="1"/>
+  <xsl:param name="chunk.first.sections" select="1"/>
+  <xsl:param name="chunk.section.depth" select="10"/>
+  <xsl:param name="use.id.as.filename" select="1"/>
+  <xsl:param name="ulink.target" select="'_self'" />
+  <xsl:param name="base.dir" select="'html/dev-manual/'"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel" select="1" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/dev-manual/dev-manual-intro.xml b/documentation/dev-manual/dev-manual-intro.xml
new file mode 100644
index 0000000000..8923a1d2fb
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-intro.xml
@@ -0,0 +1,210 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='dev-manual-intro'>
+
+<title>The Yocto Project Development Manual</title>
+    <section id='intro'>
+        <title>Introduction</title>
+
+        <para>
+            Welcome to the Yocto Project Development Manual!
+            This manual provides information on how to use the Yocto Project to
+            develop embedded Linux images and user-space applications that
+            run on targeted devices.
+            The manual provides an overview of image, kernel, and
+            user-space application development using the Yocto Project.
+            Because much of the information in this manual is general, it
+            contains many references to other sources where you can find more
+            detail.
+            For example, you can find detailed information on Git, repositories,
+            and open source in general in many places on the Internet.
+            Another example specific to the Yocto Project is how to quickly
+            set up your host development system and build an image, which you
+            find in the
+            <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+        </para>
+
+        <para>
+            The Yocto Project Development Manual does, however, provide
+            guidance and examples on how to change the kernel source code,
+            reconfigure the kernel, and develop an application using the
+            popular <trademark class='trade'>Eclipse</trademark> IDE.
+        </para>
+
+        <note>
+            By default, using the Yocto Project creates a Poky distribution.
+            However, you can create your own distribution by providing key
+            <link linkend='metadata'>Metadata</link>.
+            A good example is Angstrom, which has had a distribution
+            based on the Yocto Project since its inception.
+            Other examples include  commercial distributions like
+            Wind River Linux, Mentor Embedded Linux, and ENEA Linux.
+            See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
+            section for more information.
+        </note>
+    </section>
+
+    <section id='what-this-manual-provides'>
+        <title>What This Manual Provides</title>
+
+        <para>
+            The following list describes what you can get from this manual:
+            <itemizedlist>
+                <listitem><para>Information that lets you get set
+                    up to develop using the Yocto Project.</para></listitem>
+                <listitem><para>Information to help developers who are new to
+                    the open source environment and to the distributed revision
+                    control system Git, which the Yocto Project uses.
+                    </para></listitem>
+                <listitem><para>An understanding of common end-to-end
+                    development models and tasks.</para></listitem>
+                <listitem><para>Information about common development tasks
+                    generally used during image development for
+                    embedded devices.
+                    </para></listitem>
+                <listitem><para>Many references to other sources of related
+                    information.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='what-this-manual-does-not-provide'>
+        <title>What this Manual Does Not Provide</title>
+
+        <para>
+            This manual will not give you the following:
+            <itemizedlist>
+                <listitem><para><emphasis>Step-by-step instructions when those instructions exist in other Yocto
+                    Project documentation:</emphasis>
+                    For example, the Yocto Project Application Developer's Guide contains detailed
+                    instructions on how to run the
+                    <ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>ADT Installer</ulink>,
+                    which is used to set up a cross-development environment.</para></listitem>
+                <listitem><para><emphasis>Reference material:</emphasis>
+                    This type of material resides in an appropriate reference manual.
+                    For example, system variables are documented in the
+                    <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>.</para></listitem>
+                <listitem><para><emphasis>Detailed public information that is not specific to the Yocto Project:</emphasis>
+                    For example, exhaustive information on how to use Git is covered better through the
+                    Internet than in this manual.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='other-information'>
+        <title>Other Information</title>
+
+        <para>
+            Because this manual presents overview information for many different
+            topics, supplemental information is recommended for full
+            comprehension.
+            The following list presents other sources of information you might find helpful:
+            <itemizedlist>
+                <listitem><para><emphasis><ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:
+                    </emphasis> The home page for the Yocto Project provides lots of information on the project
+                    as well as links to software and documentation.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>:</emphasis> This short document lets you get started
+                    with the Yocto Project and quickly begin building an image.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>:</emphasis> This manual is a reference
+                    guide to the OpenEmbedded build system, which is based on BitBake.
+                    The build system is sometimes referred to as "Poky".
+                    </para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>:</emphasis>
+                    This guide provides information that lets you get going with the Application
+                    Development Toolkit (ADT) and stand-alone cross-development toolchains to
+                    develop projects using the Yocto Project.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>:</emphasis>
+                    This guide defines the structure for BSP components.
+                    Having a commonly understood structure encourages standardization.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>:</emphasis>
+                    This manual describes how to work with Linux Yocto kernels as well as provides a bit
+                    of conceptual information on the construction of the Yocto Linux kernel tree.
+                    </para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>:</emphasis>
+                    This manual presents a set of common and generally useful tracing and
+                    profiling schemes along with their applications (as appropriate) to each tool.
+                    </para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='http://www.youtube.com/watch?v=3ZlOu-gLsh0'>
+                    Eclipse IDE Yocto Plug-in</ulink>:</emphasis> A step-by-step instructional video that
+                    demonstrates how an application developer uses Yocto Plug-in features within
+                    the Eclipse IDE.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>FAQ</ulink>:</emphasis>
+                    A list of commonly asked questions and their answers.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>:</emphasis>
+                    Features, updates and known issues for the current
+                    release of the Yocto Project.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>
+                    Hob</ulink>:</emphasis> A graphical user interface for BitBake.
+                    Hob's primary goal is to enable a user to perform common tasks more easily.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_HOME_URL;/download/build-appliance-0'>
+                    Build Appliance</ulink>:</emphasis> A virtual machine that
+                    enables you to build and boot a custom embedded Linux image
+                    with the Yocto Project using a non-Linux development system.
+                    For more information, see the
+                    <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance-manual'>Build Appliance</ulink>
+                    page.
+                    </para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>:</emphasis>
+                    The bug tracking application the Yocto Project uses.
+                    If you find problems with the Yocto Project, you should report them using this
+                    application.</para></listitem>
+                <listitem><para><emphasis>
+                    Yocto Project Mailing Lists:</emphasis> To subscribe to the Yocto Project mailing
+                    lists, click on the following URLs and follow the instructions:
+                    <itemizedlist>
+                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> for a
+                            Yocto Project Discussions mailing list.</para></listitem>
+                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> for a
+                            Yocto Project Discussions mailing list about the
+                            OpenEmbedded build system (Poky).
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink>
+                            for a mailing list to receive official Yocto Project announcements
+                            as well as Yocto Project milestones.</para></listitem>
+                        <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo'></ulink> for a
+                            listing of all public mailing lists on <filename>lists.yoctoproject.org</filename>.
+                            </para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para><emphasis>Internet Relay Chat (IRC):</emphasis>
+                    Two IRC channels on freenode are available
+                    for Yocto Project and Poky discussions: <filename>#yocto</filename> and
+                    <filename>#poky</filename>, respectively.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
+                    The build system used by the Yocto Project.
+                    This project is the upstream, generic, embedded distribution that the Yocto
+                    Project derives its build system (Poky) from and to which it contributes.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='http://developer.berlios.de/projects/bitbake/'>
+                    BitBake</ulink>:</emphasis> The tool used by the OpenEmbedded build system
+                    to process project metadata.</para></listitem>
+                <listitem><para><emphasis>
+                    BitBake User Manual:</emphasis>
+                    A comprehensive guide to the BitBake tool.
+                    If you want information on BitBake, see the user manual included in the
+                    <filename>bitbake/doc/manual</filename> directory of the
+                    <link linkend='source-directory'>Source Directory</link>.</para></listitem>
+                <listitem><para><emphasis>
+                    <ulink url='http://wiki.qemu.org/Index.html'>Quick EMUlator (QEMU)</ulink>:
+                    </emphasis> An open-source machine emulator and virtualizer.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/dev-manual/dev-manual-model.xml b/documentation/dev-manual/dev-manual-model.xml
new file mode 100644
index 0000000000..cb09627d6e
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-model.xml
@@ -0,0 +1,2058 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='dev-manual-model'>
+
+<title>Common Development Models</title>
+
+<para>
+    Many development models exist for which you can use the Yocto Project.
+    This chapter overviews simple methods that use tools provided by the
+    Yocto Project:
+    <itemizedlist>
+        <listitem><para><emphasis>System Development:</emphasis>
+             System Development covers Board Support Package (BSP) development and kernel
+             modification or configuration.
+             For an example on how to create a BSP, see the
+             "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
+             section in the Yocto Project Board Support Package (BSP) Developer's Guide.
+             For more complete information on how to work with the kernel, see the
+             <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel
+             Development Manual</ulink>.
+             </para></listitem>
+         <listitem><para><emphasis>User Application Development:</emphasis>
+             User Application Development covers development of applications that you intend
+             to run on target hardware.
+             For information on how to set up your host development system for user-space
+             application development, see the
+             <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
+             For a simple example of user-space application development using the
+             <trademark class='trade'>Eclipse</trademark> IDE, see the
+             "<link linkend='application-development-workflow'>Application
+             Development Workflow</link>" section.
+             </para></listitem>
+         <listitem><para><emphasis>Temporary Source Code Modification:</emphasis>
+             Direct modification of temporary source code is a convenient development model
+             to quickly iterate and develop towards a solution.
+             Once you implement the solution, you should of course take steps to
+             get the changes upstream and applied in the affected recipes.</para></listitem>
+         <listitem><para><emphasis>Image Development using Hob:</emphasis>
+             You can use the <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build
+             custom operating system images within the build environment.
+             Hob provides an efficient interface to the OpenEmbedded build system.</para></listitem>
+         <listitem><para><emphasis>Using a Development Shell:</emphasis>
+             You can use a <filename>devshell</filename> to efficiently debug commands or simply
+             edit packages.
+             Working inside a development shell is a quick way to set up the OpenEmbedded build
+             environment to work on parts of a project.</para></listitem>
+     </itemizedlist>
+</para>
+
+<section id='system-development-model'>
+    <title>System Development Workflow</title>
+
+    <para>
+        System development involves modification or creation of an image that you want to run on
+        a specific hardware target.
+        Usually, when you want to create an image that runs on embedded hardware, the image does
+        not require the same number of features that a full-fledged Linux distribution provides.
+        Thus, you can create a much smaller image that is designed to use only the
+        features for your particular hardware.
+    </para>
+
+    <para>
+        To help you understand how system development works in the Yocto Project, this section
+        covers two types of image development:  BSP creation and kernel modification or
+        configuration.
+    </para>
+
+    <section id='developing-a-board-support-package-bsp'>
+        <title>Developing a Board Support Package (BSP)</title>
+
+        <para>
+            A BSP is a package of recipes that, when applied during a build, results in
+            an image that you can run on a particular board.
+            Thus, the package when compiled into the new image, supports the operation of the board.
+        </para>
+
+        <note>
+            For a brief list of terms used when describing the development process in the Yocto Project,
+            see the "<link linkend='yocto-project-terms'>Yocto Project Terms</link>" section.
+        </note>
+
+        <para>
+            The remainder of this section presents the basic
+            steps used to create a BSP using the Yocto Project's
+            <ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>BSP Tools</ulink>.
+            Although not required for BSP creation, the
+            <filename>meta-intel</filename> repository, which contains
+            many BSPs supported by the Yocto Project, is part of the example.
+        </para>
+
+        <para>
+            For an example that shows how to create a new layer using the tools, see the
+            "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
+             section in the Yocto Project Board Support Package (BSP) Developer's Guide.
+        </para>
+
+        <para>
+            The following illustration and list summarize the BSP creation general workflow.
+        </para>
+
+        <para>
+            <imagedata fileref="figures/bsp-dev-flow.png" width="6in" depth="7in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            <orderedlist>
+                <listitem><para><emphasis>Set up your host development system to support
+                    development using the Yocto Project</emphasis>:  See the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>"
+                    and the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
+                    in the Yocto Project Quick Start for requirements.</para></listitem>
+                <listitem><para><emphasis>Establish a local copy of the project files on your
+                    system</emphasis>:  You need this <link linkend='source-directory'>Source
+                    Directory</link> available on your host system.
+                    Having these files on your system gives you access to the build
+                    process and to the tools you need.
+                    For information on how to set up the Source Directory,
+                    see the
+                    "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
+                <listitem><para><emphasis>Establish the <filename>meta-intel</filename>
+                    repository on your system</emphasis>:  Having local copies
+                    of these supported BSP layers on your system gives you
+                    access to layers you might be able to build on or modify
+                    to create your BSP.
+                    For information on how to get these files, see the
+                    "<link linkend='getting-setup'>Getting Set Up</link>" section.</para></listitem>
+                <listitem><para><emphasis>Create your own BSP layer using the
+                    <ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'><filename>yocto-bsp</filename></ulink> script</emphasis>:
+                    Layers are ideal for
+                    isolating and storing work for a given piece of hardware.
+                    A layer is really just a location or area in which you place
+                    the recipes and configurations for your BSP.
+                    In fact, a BSP is, in itself, a special type of layer.
+                    The simplest way to create a new BSP layer that is compliant with the
+                    Yocto Project is to use the <filename>yocto-bsp</filename> script.
+                    For information about that script, see the
+                    "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>"
+                    section in the Yocto Project Board Support (BSP) Developer's Guide.
+                    </para>
+                    <para>
+                    Another example that illustrates a layer is an application.
+                    Suppose you are creating an application that has library or other dependencies in
+                    order for it to compile and run.
+                    The layer, in this case, would be where all the recipes that define those dependencies
+                    are kept.
+                    The key point for a layer is that it is an isolated area that contains
+                    all the relevant information for the project that the OpenEmbedded build
+                    system knows about.
+                    For more information on layers, see the
+                    "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>"
+                    section.
+                    For more information on BSP layers, see the
+                    "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>" section in the
+                    Yocto Project Board Support Package (BSP) Developer's Guide.</para>
+                    <note>Four BSPs exist that are part of the
+                    Yocto Project release: <filename>genericx86</filename>, <filename>beagleboard</filename>,
+                    <filename>mpc8315e</filename>, and <filename>routerstationpro</filename>.
+                    The recipes and configurations for these four BSPs are located and dispersed
+                    within the <link linkend='source-directory'>Source Directory</link>.
+                    On the other hand, BSP layers for Chief River, Crown Bay,
+                    Crystal Forest, Emenlow, Fish River Island 2, Jasper Forest, N450, NUC DC3217IYE,
+                    Romley, sys940x, Sugar Bay, and tlk exist in their own separate layers
+                    within the larger <filename>meta-intel</filename> layer.</note>
+                    <para>When you set up a layer for a new BSP, you should follow a standard layout.
+                    This layout is described in the
+                    "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout'>Example Filesystem Layout</ulink>"
+                    section of the Board Support Package (BSP) Development Guide.
+                    In the standard layout, you will notice a suggested structure for recipes and
+                    configuration information.
+                    You can see the standard layout for a BSP by examining
+                    any supported BSP found in the <filename>meta-intel</filename> layer inside
+                    the Source Directory.</para></listitem>
+                <listitem><para><emphasis>Make configuration changes to your new BSP
+                    layer</emphasis>:  The standard BSP layer structure organizes the files you need
+                    to edit in <filename>conf</filename> and several <filename>recipes-*</filename>
+                    directories within the BSP layer.
+                    Configuration changes identify where your new layer is on the local system
+                    and identify which kernel you are going to use.
+                    When you run the <filename>yocto-bsp</filename> script, you are able to interactively
+                    configure many things for the BSP (e.g. keyboard, touchscreen, and so forth).
+                    </para></listitem>
+                <listitem><para><emphasis>Make recipe changes to your new BSP layer</emphasis>:  Recipe
+                    changes include altering recipes (<filename>.bb</filename> files), removing
+                    recipes you don't use, and adding new recipes or append files
+                    (<filename>.bbappend</filename>) that you need to support your hardware.
+                    </para></listitem>
+                <listitem><para><emphasis>Prepare for the build</emphasis>:  Once you have made all the
+                    changes to your BSP layer, there remains a few things
+                    you need to do for the OpenEmbedded build system in order for it to create your image.
+                    You need to get the build environment ready by sourcing an environment setup script
+                    and you need to be sure two key configuration files are configured appropriately:
+                    the <filename>conf/local.conf</filename> and the
+                    <filename>conf/bblayers.conf</filename> file.
+                    You must make the OpenEmbedded build system aware of your new layer.
+                    See the
+                    "<link linkend='enabling-your-layer'>Enabling Your Layer</link>" section
+                    for information on how to let the build system know about your new layer.</para>
+                    <para>The entire process for building an image is overviewed in the section
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>" section
+                    of the Yocto Project Quick Start.
+                    You might want to reference this information.</para></listitem>
+                <listitem><para><emphasis>Build the image</emphasis>:  The OpenEmbedded build system
+                    uses the BitBake tool to build images based on the type of image you want to create.
+                    You can find more information about BitBake in the user manual, which is found in the
+                    <filename>bitbake/doc/manual</filename> directory of the
+                    <link linkend='source-directory'>Source Directory</link>.</para>
+                    <para>The build process supports several types of images to satisfy different needs.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter
+                    in the Yocto Project Reference Manual for information on
+                    supported images.</para></listitem>
+            </orderedlist>
+        </para>
+
+        <para>
+            You can view a video presentation on "Building Custom Embedded Images with Yocto"
+            at <ulink url='http://free-electrons.com/blog/elc-2011-videos'>Free Electrons</ulink>.
+            You can also find supplemental information in
+            <ulink url='&YOCTO_DOCS_BSP_URL;'>
+            The Board Support Package (BSP) Development Guide</ulink>.
+            Finally, there is wiki page write up of the example also located
+            <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>
+            here</ulink> that you might find helpful.
+       </para>
+    </section>
+
+    <section id='modifying-the-kernel'>
+        <title><anchor id='kernel-spot' />Modifying the Kernel</title>
+
+        <para>
+            Kernel modification involves changing the Yocto Project kernel, which could involve changing
+            configuration options as well as adding new kernel recipes.
+            Configuration changes can be added in the form of configuration fragments, while recipe
+            modification comes through the kernel's <filename>recipes-kernel</filename> area
+            in a kernel layer you create.
+        </para>
+
+        <para>
+            The remainder of this section presents a high-level overview of the Yocto Project
+            kernel architecture and the steps to modify the kernel.
+            You can reference the
+            "<link linkend='patching-the-kernel'>Patching the Kernel</link>" section
+            for an example that changes the source code of the kernel.
+            For information on how to configure the kernel, see the
+            "<link linkend='configuring-the-kernel'>Configuring the Kernel</link>" section.
+            For more information on the kernel and on modifying the kernel, see the
+            <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
+        </para>
+
+        <section id='kernel-overview'>
+            <title>Kernel Overview</title>
+
+            <para>
+                Traditionally, when one thinks of a patched kernel, they think of a base kernel
+                source tree and a fixed structure that contains kernel patches.
+                The Yocto Project, however, employs mechanisms that, in a sense, result in a kernel source
+                generator.
+                By the end of this section, this analogy will become clearer.
+            </para>
+
+            <para>
+                You can find a web interface to the Yocto Project kernel source repositories at
+                <ulink url='&YOCTO_GIT_URL;'></ulink>.
+                If you look at the interface, you will see to the left a grouping of
+                Git repositories titled "Yocto Linux Kernel."
+                Within this group, you will find several kernels supported by
+                the Yocto Project:
+                <itemizedlist>
+                    <listitem><para><emphasis><filename>linux-yocto-3.4</filename></emphasis> - The
+                    stable Yocto Project kernel to use with the Yocto Project Release 1.3. This kernel
+                    is based on the Linux 3.4 released kernel.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-yocto-3.8</filename></emphasis> - The
+                    stable Yocto Project kernel to use with the Yocto Project Release 1.4. This kernel
+                    is based on the Linux 3.8 released kernel.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-yocto-3.10</filename></emphasis> - The
+                    stable Yocto Project kernel to use with the Yocto Project Release 1.5. This kernel
+                    is based on the Linux 3.10 released kernel.</para></listitem>
+                    <listitem><para><emphasis><filename>linux-yocto-dev</filename></emphasis> - A development
+                    kernel based on the latest upstream release candidate available.</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                The kernels are maintained using the Git revision control system
+                that structures them using the familiar "tree", "branch", and "leaf" scheme.
+                Branches represent diversions from general code to more specific code, while leaves
+                represent the end-points for a complete and unique kernel whose source files,
+                when gathered from the root of the tree to the leaf, accumulate to create the files
+                necessary for a specific piece of hardware and its features.
+                The following figure displays this concept:
+            <para>
+                <imagedata fileref="figures/kernel-overview-1.png"
+                    width="6in" depth="6in" align="center" scale="100" />
+            </para>
+
+            <para>
+                Within the figure, the "Kernel.org Branch Point" represents the point in the tree
+                where a supported base kernel is modified from the Linux kernel.
+                For example, this could be the branch point for the <filename>linux-yocto-3.4</filename>
+                kernel.
+                Thus, everything further to the right in the structure is based on the
+                <filename>linux-yocto-3.4</filename> kernel.
+                Branch points to right in the figure represent where the
+                <filename>linux-yocto-3.4</filename> kernel is modified for specific hardware
+                or types of kernels, such as real-time kernels.
+                Each leaf thus represents the end-point for a kernel designed to run on a specific
+                targeted device.
+            </para>
+
+            <para>
+                The overall result is a Git-maintained repository from which all the supported
+                kernel types can be derived for all the supported devices.
+                A big advantage to this scheme is the sharing of common features by keeping them in
+                "larger" branches within the tree.
+                This practice eliminates redundant storage of similar features shared among kernels.
+            </para>
+
+            <note>
+                Keep in mind the figure does not take into account all the supported Yocto
+                Project kernel types, but rather shows a single generic kernel just for conceptual purposes.
+                Also keep in mind that this structure represents the Yocto Project source repositories
+                that are either pulled from during the build or established on the host development system
+                prior to the build by either cloning a particular kernel's Git repository or by
+                downloading and unpacking a tarball.
+            </note>
+
+            <para>
+                Upstream storage of all the available kernel source code is one thing, while
+                representing and using the code on your host development system is another.
+                Conceptually, you can think of the kernel source repositories as all the
+                source files necessary for all the supported kernels.
+                As a developer, you are just interested in the source files for the kernel on
+                which you are working.
+                And, furthermore, you need them available on your host system.
+            </para>
+
+            <para>
+                Kernel source code is available on your host system a couple of different
+                ways.
+                If you are working in the kernel all the time, you probably would want
+                to set up your own local Git repository of the kernel tree.
+                If you just need to make some patches to the kernel, you can access
+                temporary kernel source files that were extracted and used
+                during a build.
+                We will just talk about working with the temporary source code.
+                For more information on how to get kernel source code onto your
+                host system, see the
+                "<link linkend='local-kernel-files'>Yocto Project Kernel</link>"
+                bulleted item earlier in the manual.
+            </para>
+
+            <para>
+                What happens during the build?
+                When you build the kernel on your development system, all files needed for the build
+                are taken from the source repositories pointed to by the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> variable
+                and gathered in a temporary work area
+                where they are subsequently used to create the unique kernel.
+                Thus, in a sense, the process constructs a local source tree specific to your
+                kernel to generate the new kernel image - a source generator if you will.
+            </para>
+                The following figure shows the temporary file structure
+                created on your host system when the build occurs.
+                This
+                <link linkend='build-directory'>Build Directory</link> contains all the
+                source files used during the build.
+            </para>
+
+            <para>
+                <imagedata fileref="figures/kernel-overview-2-generic.png"
+                    width="6in" depth="5in" align="center" scale="100" />
+            </para>
+
+            <para>
+                Again, for additional information the Yocto Project kernel's
+                architecture and its branching strategy, see the
+                <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
+                You can also reference the
+                "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
+                section for a detailed example that modifies the kernel.
+            </para>
+        </section>
+
+        <section id='kernel-modification-workflow'>
+            <title>Kernel Modification Workflow</title>
+
+            <para>
+                This illustration and the following list summarizes the kernel modification general workflow.
+            </para>
+
+            <para>
+                <imagedata fileref="figures/kernel-dev-flow.png"
+                    width="6in" depth="5in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                <orderedlist>
+                    <listitem><para><emphasis>Set up your host development system to support
+                        development using the Yocto Project</emphasis>:  See
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
+                        in the Yocto Project Quick Start for requirements.</para></listitem>
+                    <listitem><para><emphasis>Establish a local copy of project files on your
+                        system</emphasis>:  Having the <link linkend='source-directory'>Source
+                        Directory</link> on your system gives you access to the build process and tools
+                        you need.
+                        For information on how to get these files, see the bulleted item
+                        "<link linkend='local-yp-release'>Yocto Project Release</link>" earlier in this manual.
+                        </para></listitem>
+                    <listitem><para><emphasis>Establish the temporary kernel source files</emphasis>:
+                        Temporary kernel source files are kept in the
+                        <link linkend='build-directory'>Build Directory</link>
+                        created by the
+                        OpenEmbedded build system when you run BitBake.
+                        If you have never built the kernel you are interested in, you need to run
+                        an initial build to establish local kernel source files.</para>
+                        <para>If you are building an image for the first time, you need to get the build
+                        environment ready by sourcing
+                        the environment setup script.
+                        You also need to be sure two key configuration files
+                        (<filename>local.conf</filename> and <filename>bblayers.conf</filename>)
+                        are configured appropriately.</para>
+                        <para>The entire process for building an image is overviewed in the
+                        "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+                        section of the Yocto Project Quick Start.
+                        You might want to reference this information.
+                        You can find more information on BitBake in the user manual, which is found in the
+                        <filename>bitbake/doc/manual</filename> directory of the
+                        Source Directory.</para>
+                        <para>The build process supports several types of images to satisfy different needs.
+                        See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in
+                        the Yocto Project Reference Manual for information on supported images.
+                        </para></listitem>
+                    <listitem><para><emphasis>Make changes to the kernel source code if
+                        applicable</emphasis>:  Modifying the kernel does not always mean directly
+                        changing source files.
+                        However, if you have to do this, you make the changes to the files in the
+                        Build directory.</para></listitem>
+                    <listitem><para><emphasis>Make kernel configuration changes
+                        if applicable</emphasis>:
+                        If your situation calls for changing the kernel's configuration, you can
+                        use the <filename>yocto-kernel</filename> script or <filename>menuconfig</filename>
+                        to enable and disable kernel configurations.
+                        Using the script lets you interactively set up kernel configurations.
+                        Using <filename>menuconfig</filename> allows you to interactively develop and test the
+                        configuration changes you are making to the kernel.
+                        When saved, changes using <filename>menuconfig</filename> update the kernel's
+                        <filename>.config</filename> file.
+                        Try to resist the temptation of directly editing the <filename>.config</filename>
+                        file found in the Build Directory at
+                        <filename>tmp/sysroots/&lt;machine-name&gt;/kernel</filename>.
+                        Doing so, can produce unexpected results when the OpenEmbedded build system
+                        regenerates the configuration file.</para>
+                        <para>Once you are satisfied with the configuration changes made using
+                        <filename>menuconfig</filename>, you can directly compare the
+                        <filename>.config</filename> file against a saved original and gather those
+                        changes into a config fragment to be referenced from within the kernel's
+                        <filename>.bbappend</filename> file.</para></listitem>
+                    <listitem><para><emphasis>Rebuild the kernel image with your changes</emphasis>:
+                        Rebuilding the kernel image applies your changes.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+    </section>
+</section>
+
+<section id='application-development-workflow'>
+    <title>Application Development Workflow</title>
+
+    <para>
+        Application development involves creating an application that you want
+        to run on your target hardware, which is running a kernel image created using the
+        OpenEmbedded build system.
+        The Yocto Project provides an
+        <ulink url='&YOCTO_DOCS_ADT_URL;#adt-intro-section'>Application Development Toolkit (ADT)</ulink>
+        and stand-alone
+        <ulink url='&YOCTO_DOCS_ADT_URL;#the-cross-development-toolchain'>cross-development toolchains</ulink>
+        that facilitate quick development and integration of your application into its runtime environment.
+        Using the ADT and toolchains, you can compile and link your application.
+        You can then deploy your application to the actual hardware or to the QEMU emulator for testing.
+        If you are familiar with the popular <trademark class='trade'>Eclipse</trademark> IDE,
+        you can use an Eclipse Yocto Plug-in to
+        allow you to develop, deploy, and test your application all from within Eclipse.
+    </para>
+
+    <para>
+        While we strongly suggest using the ADT to develop your application, this option might not
+        be best for you.
+        If this is the case, you can still use pieces of the Yocto Project for your development process.
+        However, because the process can vary greatly, this manual does not provide detail on the process.
+    </para>
+
+    <section id='workflow-using-the-adt-and-eclipse'>
+        <title>Workflow Using the ADT and <trademark class='trade'>Eclipse</trademark></title>
+
+        <para>
+            To help you understand how application development works using the ADT, this section
+            provides an overview of the general development process and a detailed example of the process
+            as it is used from within the Eclipse IDE.
+        </para>
+
+        <para>
+            The following illustration and list summarize the application development general workflow.
+        </para>
+
+        <para>
+            <imagedata fileref="figures/app-dev-flow.png"
+                width="7in" depth="8in" align="center" scale="100" />
+        </para>
+
+        <para>
+            <orderedlist>
+                <listitem><para><emphasis>Prepare the host system for the Yocto Project</emphasis>:
+                    See
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#the-linux-distro'>The Linux Distribution</ulink>" and
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" sections both
+                    in the Yocto Project Quick Start for requirements.</para></listitem>
+                <listitem><para><emphasis>Secure the Yocto Project kernel target image</emphasis>:
+                    You must have a target kernel image that has been built using the OpenEmbedded
+                    build system.</para>
+                    <para>Depending on whether the Yocto Project has a pre-built image that matches your target
+                    architecture and where you are going to run the image while you develop your application
+                    (QEMU or real hardware), the area from which you get the image differs.
+                        <itemizedlist>
+                            <listitem><para>Download the image from
+                                <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
+                                if your target architecture is supported and you are going to develop
+                                and test your application on actual hardware.</para></listitem>
+                            <listitem><para>Download the image from
+                                <ulink url='&YOCTO_QEMU_DL_URL;'>
+                                <filename>machines/qemu</filename></ulink> if your target architecture is supported
+                                and you are going to develop and test your application using the QEMU
+                                emulator.</para></listitem>
+                            <listitem><para>Build your image if you cannot find a pre-built image that matches
+                                your target architecture.
+                                If your target architecture is similar to a supported architecture, you can
+                                modify the kernel image before you build it.
+                                See the
+                                "<link linkend='patching-the-kernel'>Patching the Kernel</link>"
+                                section for an example.</para></listitem>
+                        </itemizedlist></para>
+                    <para>For information on pre-built kernel image naming schemes for images
+                    that can run on the QEMU emulator, see the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#downloading-the-pre-built-linux-kernel'>Downloading the Pre-Built Linux Kernel</ulink>"
+                    section in the Yocto Project Quick Start.</para></listitem>
+                <listitem><para><emphasis>Install the ADT</emphasis>:
+                    The ADT provides a target-specific cross-development toolchain, the root filesystem,
+                    the QEMU emulator, and other tools that can help you develop your application.
+                    While it is possible to get these pieces separately, the ADT Installer provides an
+                    easy, inclusive method.
+                    You can get these pieces by running an ADT installer script, which is configurable.
+                    For information on how to install the ADT, see the
+                    "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Using the ADT Installer</ulink>"
+                    section
+                    in the Yocto Project Application Developer's Guide.</para></listitem>
+                <listitem><para><emphasis>If applicable, secure the target root filesystem
+                    and the Cross-development toolchain</emphasis>:
+                    If you choose not to install the ADT using the ADT Installer,
+                    you need to find and download the appropriate root filesystem and
+                    the cross-development toolchain.</para>
+                    <para>You can find the tarballs for the root filesystem in the same area used
+                    for the kernel image.
+                    Depending on the type of image you are running, the root filesystem you need differs.
+                    For example, if you are developing an application that runs on an image that
+                    supports Sato, you need to get a root filesystem that supports Sato.</para>
+                    <para>You can find the cross-development toolchains at
+                    <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'><filename>toolchains</filename></ulink>.
+                    Be sure to get the correct toolchain for your development host and your
+                    target architecture.
+                    See the "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
+                    section in the Yocto Project Application Developer's Guide for information
+                    and the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#installing-the-toolchain'>Installing the Toolchain</ulink>"
+                    in the Yocto Project Quick Start for information on finding and installing
+                    the correct toolchain based on your host development system and your target
+                    architecture.
+                    </para></listitem>
+                <listitem><para><emphasis>Create and build your application</emphasis>:
+                    At this point, you need to have source files for your application.
+                    Once you have the files, you can use the Eclipse IDE to import them and build the
+                    project.
+                    If you are not using Eclipse, you need to use the cross-development tools you have
+                    installed to create the image.</para></listitem>
+                <listitem><para><emphasis>Deploy the image with the application</emphasis>:
+                    If you are using the Eclipse IDE, you can deploy your image to the hardware or to
+                    QEMU through the project's preferences.
+                    If you are not using the Eclipse IDE, then you need to deploy the application
+                    to the hardware using other methods.
+                    Or, if you are using QEMU, you need to use that tool and load your image in for testing.
+                    </para></listitem>
+                <listitem><para><emphasis>Test and debug the application</emphasis>:
+                    Once your application is deployed, you need to test it.
+                    Within the Eclipse IDE, you can use the debugging environment along with the
+                    set of user-space tools installed along with the ADT to debug your application.
+                    Of course, the same user-space tools are available separately if you choose
+                    not to use the Eclipse IDE.</para></listitem>
+           </orderedlist>
+        </para>
+    </section>
+
+    <section id='adt-eclipse'>
+        <title>Working Within Eclipse</title>
+
+        <para>
+            The Eclipse IDE is a popular development environment and it fully
+            supports development using the Yocto Project.
+            <note>
+                This release of the Yocto Project supports both the Kepler
+                and Juno versions of the Eclipse IDE.
+                Thus, the following information provides setup information for
+                both versions.
+            </note>
+        </para>
+
+        <para>
+            When you install and configure the Eclipse Yocto Project Plug-in
+            into the Eclipse IDE, you maximize your Yocto Project experience.
+            Installing and configuring the Plug-in results in an environment
+            that has extensions specifically designed to let you more easily
+            develop software.
+            These extensions allow for cross-compilation, deployment, and
+            execution of your output into a QEMU emulation session as well as
+            actual target hardware.
+            You can also perform cross-debugging and profiling.
+            The environment also supports a suite of tools that allows you
+            to perform remote profiling, tracing, collection of power data,
+            collection of latency data, and collection of performance data.
+        </para>
+
+        <para>
+            This section describes how to install and configure the Eclipse IDE
+            Yocto Plug-in and how to use it to develop your application.
+        </para>
+
+        <section id='setting-up-the-eclipse-ide'>
+            <title>Setting Up the Eclipse IDE</title>
+
+            <para>
+                To develop within the Eclipse IDE, you need to do the following:
+                <orderedlist>
+                    <listitem><para>Install the optimal version of the Eclipse
+                       IDE.</para></listitem>
+                    <listitem><para>Configure the Eclipse IDE.
+                       </para></listitem>
+                    <listitem><para>Install the Eclipse Yocto Plug-in.
+                       </para></listitem>
+                    <listitem><para>Configure the Eclipse Yocto Plug-in.
+                       </para></listitem>
+                </orderedlist>
+                <note>
+                    Do not install Eclipse from your distribution's package
+                    repository.
+                    Be sure to install Eclipse from the official Eclipse
+                    download site as directed in the next section.
+                </note>
+            </para>
+
+            <section id='installing-eclipse-ide'>
+                <title>Installing the Eclipse IDE</title>
+
+                <para>
+                    It is recommended that you have the Kepler 4.3 version of
+                    the Eclipse IDE installed on your development system.
+                    However, if you currently have the Juno 4.2 version
+                    installed and you do not want to upgrade the IDE, you can
+                    configure Juno to work with the Yocto Project.
+                </para>
+
+                <para>
+                    If you do not have the Kepler 4.3 Eclipse IDE installed, you
+                    can find the tarball at
+                    <ulink url='&ECLIPSE_MAIN_URL;'></ulink>.
+                    From that site, choose the Eclipse Standard 4.3 version
+                    particular to your development host.
+                    This version contains the Eclipse Platform, the Java
+                    Development Tools (JDT), and the Plug-in Development
+                    Environment.
+                </para>
+
+                <para>
+                    Once you have downloaded the tarball, extract it into a
+                    clean directory.
+                    For example, the following commands unpack and install the
+                    downloaded Eclipse IDE tarball into a clean directory
+                    using the default name <filename>eclipse</filename>:
+                    <literallayout class='monospaced'>
+     $ cd ~
+     $ tar -xzvf ~/Downloads/eclipse-standard-kepler-R-linux-gtk-x86_64.tar.gz
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='configuring-the-eclipse-ide'>
+                <title>Configuring the Eclipse IDE</title>
+
+                <para>
+                    This section presents the steps needed to configure the
+                    Eclipse IDE.
+                </para>
+
+                <para>
+                    Before installing and configuring the Eclipse Yocto Plug-in,
+                    you need to configure the Eclipse IDE.
+                    Follow these general steps:
+                    <orderedlist>
+                        <listitem><para>Start the Eclipse IDE.</para></listitem>
+                        <listitem><para>Make sure you are in your Workbench and
+                            select "Install New Software" from the "Help"
+                            pull-down menu.</para></listitem>
+                        <listitem><para>Select
+                            <filename>Kepler - &ECLIPSE_KEPLER_URL;</filename>
+                            from the "Work with:" pull-down menu.
+                            <note>
+                                For Juno, select
+                                <filename>Juno - &ECLIPSE_JUNO_URL;</filename>
+                            </note>
+                            </para></listitem>
+                        <listitem><para>Expand the box next to "Linux Tools"
+                            and select the
+                            <filename>LTTng - Linux Tracing Toolkit</filename>
+                            boxes.</para></listitem>
+                        <listitem><para>Expand the box next to "Mobile and
+                            Device Development" and select the following boxes:
+                            <itemizedlist>
+                                <listitem><para><filename>C/C++ Remote Launch</filename></para></listitem>
+                                <listitem><para><filename>Remote System Explorer End-user Runtime</filename></para></listitem>
+                                <listitem><para><filename>Remote System Explorer User Actions</filename></para></listitem>
+                                <listitem><para><filename>Target Management Terminal</filename></para></listitem>
+                                <listitem><para><filename>TCF Remote System Explorer add-in</filename></para></listitem>
+                                <listitem><para><filename>TCF Target Explorer</filename></para></listitem>
+                            </itemizedlist></para></listitem>
+                        <listitem><para>Expand the box next to "Programming
+                            Languages" and select the
+                            <filename>Autotools Support for CDT</filename>
+                            and <filename>C/C++ Development Tools</filename>
+                            boxes.</para></listitem>
+                        <listitem><para>Complete the installation and restart
+                            the Eclipse IDE.</para></listitem>
+                    </orderedlist>
+                </para>
+            </section>
+
+            <section id='installing-the-eclipse-yocto-plug-in'>
+                <title>Installing or Accessing the Eclipse Yocto Plug-in</title>
+
+                <para>
+                    You can install the Eclipse Yocto Plug-in into the Eclipse
+                    IDE one of two ways:  use the Yocto Project's Eclipse
+                    Update site to install the pre-built plug-in or build and
+                    install the plug-in from the latest source code.
+                </para>
+
+                <section id='new-software'>
+                    <title>Installing the Pre-built Plug-in from the Yocto Project Eclipse Update Site</title>
+
+                    <para>
+                        To install the Eclipse Yocto Plug-in from the update
+                        site, follow these steps:
+                        <orderedlist>
+                            <listitem><para>Start up the Eclipse IDE.
+                                </para></listitem>
+                            <listitem><para>In Eclipse, select "Install New
+                                Software" from the "Help" menu.
+                                </para></listitem>
+                            <listitem><para>Click "Add..." in the "Work with:"
+                                area.</para></listitem>
+                           <listitem><para>Enter
+                                <filename>&ECLIPSE_DL_PLUGIN_URL;/kepler</filename>
+                                in the URL field and provide a meaningful name
+                                in the "Name" field.
+                                <note>
+                                    If you are using Juno, use
+                                    <filename>&ECLIPSE_DL_PLUGIN_URL;/juno</filename>
+                                    in the URL field.
+                                </note></para></listitem>
+                            <listitem><para>Click "OK" to have the entry added
+                                to the "Work with:" drop-down list.
+                                </para></listitem>
+                            <listitem><para>Select the entry for the plug-in
+                                from the "Work with:" drop-down list.
+                                </para></listitem>
+                            <listitem><para>Check the boxes next to
+                                <filename>Yocto Project ADT Plug-in</filename>,
+                                <filename>Yocto Project Bitbake Commander Plug-in</filename>,
+                                and
+                                <filename>Yocto Project Documentation plug-in</filename>.
+                                </para></listitem>
+                            <listitem><para>Complete the remaining software
+                                installation steps and then restart the Eclipse
+                                IDE to finish the installation of the plug-in.
+                                </para></listitem>
+                        </orderedlist>
+                    </para>
+                </section>
+
+               <section id='zip-file-method'>
+                   <title>Installing the Plug-in Using the Latest Source Code</title>
+
+                   <para>
+                        To install the Eclipse Yocto Plug-in from the latest
+                        source code, follow these steps:
+                        <orderedlist>
+                            <listitem><para>Be sure your development system
+                                is not using OpenJDK to build the plug-in
+                                by doing the following:
+                                <orderedlist>
+                                    <listitem><para>Use the Oracle JDK.
+                                        If you don't have that, go to
+                                        <ulink url='http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html'></ulink>
+                                        and download the appropriate tarball
+                                        for your development system and
+                                        extract it into your home directory.
+                                        </para></listitem>
+                                    <listitem><para>In the shell you are going
+                                        to do your work, export the location of
+                                        the Oracle Java as follows:
+                                        <literallayout class='monospaced'>
+     export PATH=~/jdk1.7.0_40/bin:$PATH
+                                        </literallayout></para></listitem>
+                                </orderedlist></para></listitem>
+                            <listitem><para>In the same shell, create a Git
+                                repository with:
+                                <literallayout class='monospaced'>
+     $ cd ~
+     $ git clone git://git.yoctoproject.org/eclipse-poky-kepler
+                                </literallayout>
+                                <note>
+                                    If you are using Juno, the repository is
+                                    located at
+                                    <filename>git://git.yoctoproject.org/eclipse-poky-juno</filename>.
+                                </note>
+                                For this example, the repository is named
+                                <filename>~/eclipse-poky-kepler</filename>.
+                                </para></listitem>
+                            <listitem><para>Change to the directory where you
+                                set up the Git repository:
+                                <literallayout class='monospaced'>
+     $ cd ~/eclipse-poky-kepler
+                                </literallayout></para></listitem>
+                            <listitem><para>Be sure you are in the right branch
+                                for your Git repository.
+                                For this release set the branch to
+                                <filename>&DISTRO_NAME;</filename>:
+                                <literallayout class='monospaced'>
+     $ git checkout &DISTRO_NAME;
+                                </literallayout></para></listitem>
+                            <listitem><para>Change to the
+                                <filename>scripts</filename>
+                                directory within the Git repository:
+                                <literallayout class='monospaced'>
+     $ cd scripts
+                                </literallayout></para></listitem>
+                            <listitem><para>Set up the local build environment
+                                by running the setup script:
+                                <literallayout class='monospaced'>
+     $ ./setup.sh
+                                </literallayout></para></listitem>
+                            <listitem><para>When the script finishes execution,
+                                it prompts you with instructions on how to run
+                                the <filename>build.sh</filename> script, which
+                                is also in the <filename>scripts</filename> of
+                                the Git repository created earlier.
+                                </para></listitem>
+                            <listitem><para>Run the <filename>build.sh</filename> script
+                                as directed.
+                                Be sure to provide the name of the Git branch
+                                along with the Yocto Project release you are
+                                using.
+                                Here is an example that uses the
+                                <filename>&DISTRO_NAME;</filename> branch:
+                                <literallayout class='monospaced'>
+     $ ECLIPSE_HOME=/home/scottrif/eclipse-poky-kepler/scripts/eclipse ./build.sh &DISTRO_NAME; &DISTRO_NAME;
+                                </literallayout>
+                                After running the script, the file
+                                <filename>org.yocto.sdk-&lt;release&gt;-&lt;date&gt;-archive.zip</filename>
+                                is in the current directory.</para></listitem>
+                            <listitem><para>If necessary, start the Eclipse IDE
+                                and be sure you are in the Workbench.
+                                </para></listitem>
+                            <listitem><para>Select "Install New Software" from the "Help" pull-down menu.
+                                </para></listitem>
+                            <listitem><para>Click "Add".</para></listitem>
+                            <listitem><para>Provide anything you want in the
+                                "Name" field.</para></listitem>
+                            <listitem><para>Click "Archive" and browse to the
+                                ZIP file you built in step seven.
+                                This ZIP file should not be "unzipped", and must
+                                be the <filename>*archive.zip</filename> file
+                                created by running the
+                                <filename>build.sh</filename> script.
+                                </para></listitem>
+                            <listitem><para>Click through the "Okay" buttons.
+                                </para></listitem>
+                            <listitem><para>Check the boxes
+                                in the installation window and complete
+                                the installation.</para></listitem>
+                            <listitem><para>Restart the Eclipse IDE if
+                                necessary.</para></listitem>
+                        </orderedlist>
+                    </para>
+
+                    <para>
+                        At this point you should be able to configure the
+                        Eclipse Yocto Plug-in as described in the
+                        "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>"
+                        section.</para>
+                </section>
+            </section>
+
+            <section id='configuring-the-eclipse-yocto-plug-in'>
+                <title>Configuring the Eclipse Yocto Plug-in</title>
+
+                <para>
+                    Configuring the Eclipse Yocto Plug-in involves setting the
+                    Cross Compiler options and the Target options.
+                    The configurations you choose become the default settings
+                    for all projects.
+                    You do have opportunities to change them later when
+                    you configure the project (see the following section).
+                </para>
+
+                <para>
+                    To start, you need to do the following from within the
+                    Eclipse IDE:
+                    <itemizedlist>
+                        <listitem><para>Choose "Preferences" from the
+                            "Windows" menu to display the Preferences Dialog.
+                            </para></listitem>
+                        <listitem><para>Click "Yocto Project ADT".
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <section id='configuring-the-cross-compiler-options'>
+                    <title>Configuring the Cross-Compiler Options</title>
+
+                    <para>
+                        To configure the Cross Compiler Options, you must select
+                        the type of toolchain, point to the toolchain, specify
+                        the sysroot location, and select the target
+                        architecture.
+                        <itemizedlist>
+                            <listitem><para><emphasis>Selecting the Toolchain Type:</emphasis>
+                                Choose between
+                                <filename>Standalone pre-built toolchain</filename>
+                                and
+                                <filename>Build system derived toolchain</filename>
+                                for Cross Compiler Options.
+                                    <itemizedlist>
+                                        <listitem><para><emphasis>
+                                            <filename>Standalone Pre-built Toolchain:</filename></emphasis>
+                                            Select this mode when you are using
+                                            a stand-alone cross-toolchain.
+                                            For example, suppose you are an
+                                            application developer and do not
+                                            need to build a target image.
+                                            Instead, you just want to use an
+                                            architecture-specific toolchain on
+                                            an existing kernel and target root
+                                            filesystem.</para></listitem>
+                                       <listitem><para><emphasis>
+                                            <filename>Build System Derived Toolchain:</filename></emphasis>
+                                            Select this mode if the
+                                            cross-toolchain has been installed
+                                            and built as part of the
+                                            <link linkend='build-directory'>Build Directory</link>.
+                                            When you select
+                                            <filename>Build system derived toolchain</filename>,
+                                            you are using the toolchain bundled
+                                            inside the Build Directory.
+                                            </para></listitem>
+                                    </itemizedlist>
+                                </para></listitem>
+                            <listitem><para><emphasis>Point to the Toolchain:</emphasis>
+                                If you are using a stand-alone pre-built
+                                toolchain, you should be pointing to where it is
+                                installed.
+                                If you used the ADT Installer script and
+                                accepted the default installation directory, the
+                                toolchain will be installed in the
+                                <filename>&YOCTO_ADTPATH_DIR;</filename>
+                                directory.
+                                Sections "<ulink url='&YOCTO_DOCS_ADT_URL;#configuring-and-running-the-adt-installer-script'>Configuring and Running the ADT Installer Script</ulink>"
+                                and
+                                "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
+                                in the Yocto Project Application Developer's
+                                Guide describe how to install a stand-alone
+                                cross-toolchain.</para>
+                                <para>If you are using a system-derived
+                                toolchain, the path you provide for the
+                                <filename>Toolchain Root Location</filename>
+                                field is the
+                                <link linkend='build-directory'>Build Directory</link>.
+                                See the
+                                "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>"
+                                section in the Yocto Project Application
+                                Developer's Guide for information on how to
+                                install the toolchain into the Build
+                                Directory.</para></listitem>
+                            <listitem><para><emphasis>Specify the Sysroot Location:</emphasis>
+                                This location is where the root filesystem for
+                                the target hardware resides.
+                                If you used the ADT Installer script and
+                                accepted the default installation directory,
+                                then the location is
+                                <filename>/opt/poky/&lt;release&gt;</filename>.
+                                Additionally, when you use the ADT Installer
+                                script, the same location is used for the QEMU
+                                user-space tools and the NFS boot process.
+                                </para>
+                                <para>If you used either of the other two
+                                methods to install the toolchain or did not
+                                accept the ADT Installer script's default
+                                installation directory, then the location of
+                                the sysroot filesystem depends on where you
+                                separately extracted and installed the
+                                filesystem.</para>
+                                <para>For information on how to install the
+                                toolchain and on how to extract and install the
+                                sysroot filesystem, see the
+                                "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>" section.
+                                </para></listitem>
+                            <listitem><para><emphasis>Select the Target Architecture:</emphasis>
+                                The target architecture is the type of hardware
+                                you are going to use or emulate.
+                                Use the pull-down
+                                <filename>Target Architecture</filename> menu
+                                to make your selection.
+                                The pull-down menu should have the supported
+                                architectures.
+                                If the architecture you need is not listed in
+                                the menu, you will need to build the image.
+                                See the
+                                "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+                                section of the Yocto Project Quick Start for
+                                more information.</para></listitem>
+                        </itemizedlist>
+                    </para>
+                </section>
+
+                <section id='configuring-the-target-options'>
+                    <title>Configuring the Target Options</title>
+
+                    <para>
+                        You can choose to emulate hardware using the QEMU
+                        emulator, or you can choose to run your image on actual
+                        hardware.
+                        <itemizedlist>
+                            <listitem><para><emphasis><filename>QEMU:</filename></emphasis>
+                                Select this option if you will be using the
+                                QEMU emulator.
+                                If you are using the emulator, you also need to
+                                locate the kernel and specify any custom
+                                options.</para>
+                                <para>If you selected
+                                <filename>Build system derived toolchain</filename>,
+                                the target kernel you built will be located in
+                                the Build Directory in
+                                <filename>tmp/deploy/images/&lt;machine&gt;</filename>
+                                directory.
+                                If you selected
+                                <filename>Standalone pre-built toolchain</filename>,
+                                the pre-built image you downloaded is located
+                                in the directory you specified when you
+                                downloaded the image.</para>
+                                <para>Most custom options are for advanced QEMU
+                                users to further customize their QEMU instance.
+                                These options are specified between paired
+                                angled brackets.
+                                Some options must be specified outside the
+                                brackets.
+                                In particular, the options
+                                <filename>serial</filename>,
+                                <filename>nographic</filename>, and
+                                <filename>kvm</filename> must all be outside the
+                                brackets.
+                                Use the <filename>man qemu</filename> command
+                                to get help on all the options and their use.
+                                The following is an example:
+                               <literallayout class='monospaced'>
+    serial ‘&lt;-m 256 -full-screen&gt;’
+                                </literallayout></para>
+                                <para>
+                                Regardless of the mode, Sysroot is already
+                                defined as part of the Cross-Compiler Options
+                                configuration in the
+                                <filename>Sysroot Location:</filename> field.
+                                </para></listitem>
+                            <listitem><para><emphasis><filename>External HW:</filename></emphasis>
+                                Select this option if you will be using actual
+                                hardware.</para></listitem>
+                        </itemizedlist>
+                    </para>
+
+                    <para>
+                        Click the "OK" to save your plug-in configurations.
+                    </para>
+                </section>
+            </section>
+        </section>
+
+        <section id='creating-the-project'>
+            <title>Creating the Project</title>
+
+            <para>
+                You can create two types of projects:  Autotools-based, or
+                Makefile-based.
+                This section describes how to create Autotools-based projects
+                from within the Eclipse IDE.
+                For information on creating Makefile-based projects in a
+                terminal window, see the section
+                "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-command-line'>Using the Command Line</ulink>"
+                in the Yocto Project Application Developer's Guide.
+            </para>
+
+            <para>
+                To create a project based on a Yocto template and then display
+                the source code, follow these steps:
+                <orderedlist>
+                    <listitem><para>Select "Project" from the "File -> New" menu.
+                        </para></listitem>
+                    <listitem><para>Double click <filename>CC++</filename>.
+                        </para></listitem>
+                    <listitem><para>Double click <filename>C Project</filename>
+                        to create the project.</para></listitem>
+                    <listitem><para>Expand <filename>Yocto Project ADT Project</filename>.
+                        </para></listitem>
+                    <listitem><para>Select <filename>Hello World ANSI C Autotools Project</filename>.
+                        This is an Autotools-based project based on a Yocto
+                        template.</para></listitem>
+                    <listitem><para>Put a name in the <filename>Project name:</filename>
+                        field.
+                        Do not use hyphens as part of the name.
+                        </para></listitem>
+                    <listitem><para>Click "Next".</para></listitem>
+                    <listitem><para>Add information in the
+                        <filename>Author</filename> and
+                        <filename>Copyright notice</filename> fields.
+                        </para></listitem>
+                    <listitem><para>Be sure the <filename>License</filename>
+                        field is correct.</para></listitem>
+                    <listitem><para>Click "Finish".</para></listitem>
+                    <listitem><para>If the "open perspective" prompt appears,
+                        click "Yes" so that you in the C/C++ perspective.
+                        </para></listitem>
+                    <listitem><para>The left-hand navigation pane shows your
+                        project.
+                        You can display your source by double clicking the
+                        project's source file.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='configuring-the-cross-toolchains'>
+            <title>Configuring the Cross-Toolchains</title>
+
+            <para>
+                The earlier section,
+                "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>",
+                sets up the default project configurations.
+                You can override these settings for a given project by following
+                these steps:
+                <orderedlist>
+                    <listitem><para>Select "Change Yocto Project Settings" from
+                        the "Project" menu.
+                        This selection brings up the Yocto Project Settings
+                        Dialog and allows you to make changes specific to an
+                        individual project.</para>
+                        <para>By default, the Cross Compiler Options and Target
+                        Options for a project are inherited from settings you
+                        provide using the Preferences Dialog as described
+                        earlier in the
+                        "<link linkend='configuring-the-eclipse-yocto-plug-in'>Configuring the Eclipse Yocto Plug-in</link>" section.
+                        The Yocto Project Settings Dialog allows you to override
+                        those default settings for a given project.
+                        </para></listitem>
+                    <listitem><para>Make your configurations for the project
+                        and click "OK".
+                        If you are running the Juno version of Eclipse, you can
+                        skip down to the next section where you build the
+                        project.
+                        If you are not working with Juno, you need to reconfigure the
+                        project as described in the next step.
+                        </para></listitem>
+                    <listitem><para>Select "Reconfigure Project" from the
+                        "Project" menu.
+                        This selection reconfigures the project by running
+                        <filename>autogen.sh</filename> in the workspace for
+                        your project.
+                        The script also runs <filename>libtoolize</filename>,
+                        <filename>aclocal</filename>,
+                        <filename>autoconf</filename>,
+                        <filename>autoheader</filename>,
+                        <filename>automake --a</filename>, and
+                        <filename>./configure</filename>.
+                        Click on the "Console" tab beneath your source code to
+                        see the results of reconfiguring your project.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='building-the-project'>
+            <title>Building the Project</title>
+
+            <para>
+                To build the project in Juno, right click on the project in
+                the navigator pane and select "Build Project".
+                If you are not running Juno, select "Build Project" from the
+                "Project" menu.
+                The console should update and you can note the cross-compiler
+                you are using.
+            </para>
+        </section>
+
+        <section id='starting-qemu-in-user-space-nfs-mode'>
+            <title>Starting QEMU in User-Space NFS Mode</title>
+
+            <para>
+                To start the QEMU emulator from within Eclipse, follow these
+                steps:
+                <orderedlist>
+                    <listitem><para>Expose and select "External Tools" from
+                        the "Run" menu.
+                        Your image should appear as a selectable menu item.
+                        </para></listitem>
+                    <listitem><para>Select your image from the menu to launch
+                        the emulator in a new window.</para></listitem>
+                    <listitem><para>If needed, enter your host root password in
+                        the shell window at the prompt.
+                        This sets up a <filename>Tap 0</filename> connection
+                        needed for running in user-space NFS mode.
+                        </para></listitem>
+                    <listitem><para>Wait for QEMU to launch.</para></listitem>
+                    <listitem><para>Once QEMU launches, you can begin operating
+                        within that environment.
+                        For example, you could determine the IP Address
+                       for the user-space NFS by using the
+                       <filename>ifconfig</filename> command.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='deploying-and-debugging-the-application'>
+            <title>Deploying and Debugging the Application</title>
+
+            <para>
+                Once the QEMU emulator is running the image, you can deploy
+                your application using the Eclipse IDE and use then use
+                the emulator to perform debugging.
+                Follow these steps to deploy the application.
+                <orderedlist>
+                    <listitem><para>Select "Debug Configurations..." from the
+                        "Run" menu.</para></listitem>
+                    <listitem><para>In the left area, expand
+                        <filename>C/C++Remote Application</filename>.
+                        </para></listitem>
+                    <listitem><para>Locate your project and select it to bring
+                        up a new tabbed view in the Debug Configurations Dialog.
+                        </para></listitem>
+                    <listitem><para>Enter the absolute path into which you want
+                        to deploy the application.
+                        Use the "Remote Absolute File Path for
+                        C/C++Application:" field.
+                        For example, enter
+                        <filename>/usr/bin/&lt;programname&gt;</filename>.
+                        </para></listitem>
+                    <listitem><para>Click on the "Debugger" tab to see the
+                        cross-tool debugger you are using.</para></listitem>
+                    <listitem><para>Click on the "Main" tab.</para></listitem>
+                    <listitem><para>Create a new connection to the QEMU instance
+                        by clicking on "new".</para></listitem>
+                    <listitem><para>Select <filename>TCF</filename>, which means
+                        Target Communication Framework.</para></listitem>
+                    <listitem><para>Click "Next".</para></listitem>
+                    <listitem><para>Clear out the "host name" field and enter
+                        the IP Address determined earlier.</para></listitem>
+                    <listitem><para>Click "Finish" to close the
+                        New Connections Dialog.</para></listitem>
+                    <listitem><para>Use the drop-down menu now in the
+                        "Connection" field and pick the IP Address you entered.
+                         </para></listitem>
+                    <listitem><para>Click "Run" to bring up a login screen
+                        and login.</para></listitem>
+                    <listitem><para>Accept the debug perspective.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='running-user-space-tools'>
+            <title>Running User-Space Tools</title>
+
+            <para>
+                As mentioned earlier in the manual, several tools exist that
+                enhance your development experience.
+                These tools are aids in developing and debugging applications
+                and images.
+                You can run these user-space tools from within the Eclipse
+                IDE through the "YoctoTools" menu.
+            </para>
+
+            <para>
+                Once you pick a tool, you need to configure it for the remote
+                target.
+                Every tool needs to have the connection configured.
+                You must select an existing TCF-based RSE connection to the
+                remote target.
+                If one does not exist, click "New" to create one.
+            </para>
+
+            <para>
+                Here are some specifics about the remote tools:
+                <itemizedlist>
+                    <listitem><para><emphasis><filename>OProfile</filename>:</emphasis>
+                        Selecting this tool causes the
+                        <filename>oprofile-server</filename> on the remote
+                        target to launch on the local host machine.
+                        The <filename>oprofile-viewer</filename> must be
+                        installed on the local host machine and the
+                        <filename>oprofile-server</filename> must be installed
+                        on the remote target, respectively, in order to use.
+                        You must compile and install the
+                        <filename>oprofile-viewer</filename> from the source
+                        code on your local host machine.
+                        Furthermore, in order to convert the target's sample
+                        format data into a form that the host can use, you must
+                        have OProfile version 0.9.4 or greater installed on the
+                        host.</para>
+                        <para>You can locate both the viewer and server from
+                        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/oprofileui/'></ulink>.
+                        You can also find more information on setting up and
+                        using this tool in the
+                        "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-oprofile'>OProfile</ulink>"
+                        section of the Yocto Project Profiling and Tracing
+                        Manual.
+                        <note>The <filename>oprofile-server</filename> is
+                        installed by default on the
+                        <filename>core-image-sato-sdk</filename> image.</note>
+                        </para></listitem>
+                    <listitem><para><emphasis><filename>Lttng2.0 ust trace import</filename>:</emphasis>
+                        Selecting this tool transfers the remote target's
+                        <filename>Lttng</filename> tracing data back to the
+                        local host machine and uses the Lttng Eclipse plug-in
+                        to graphically display the output.
+                        For information on how to use Lttng to trace an
+                        application,
+                        see <ulink url='http://lttng.org/documentation'></ulink>
+                        and the
+                        "<ulink url='&YOCTO_DOCS_PROF_URL;#lttng-linux-trace-toolkit-next-generation'>LTTng (Linux Trace Toolkit, next generation)</ulink>"
+                        section, which is in the Yocto Project Profiling and
+                        Tracing Manual.
+                        <note>Do not use
+                            <filename>Lttng-user space (legacy)</filename> tool.
+                            This tool no longer has any upstream support.</note>
+                        </para>
+                        <para>Before you use the
+                        <filename>Lttng2.0 ust trace import</filename> tool,
+                        you need to setup the Lttng Eclipse plug-in and create a
+                        Tracing project.
+                        Do the following:
+                        <orderedlist>
+                            <listitem><para>Select "Open Perspective" from the
+                                "Window" menu and then select "Tracing".
+                                </para></listitem>
+                            <listitem><para>Click "OK" to change the Eclipse
+                                perspective into the Tracing perspective.
+                                </para></listitem>
+                            <listitem><para>Create a new Tracing project by
+                                selecting "Project" from the "File -> New" menu.
+                                </para></listitem>
+                            <listitem><para>Choose "Tracing Project" from the
+                                "Tracing" menu.
+                                </para></listitem>
+                            <listitem><para>Generate your tracing data on the
+                                remote target.</para></listitem>
+                            <listitem><para>Select "Lttng2.0 ust trace import"
+                                from the "Yocto Project Tools" menu to
+                                start the data import process.</para></listitem>
+                            <listitem><para>Specify your remote connection name.
+                                </para></listitem>
+                            <listitem><para>For the Ust directory path, specify
+                                the location of your remote tracing data.
+                                Make sure the location ends with
+                                <filename>ust</filename> (e.g.
+                                <filename>/usr/mysession/ust</filename>).
+                                </para></listitem>
+                            <listitem><para>Click "OK" to complete the import
+                                process.
+                                The data is now in the local tracing project
+                                you created.</para></listitem>
+                            <listitem><para>Right click on the data and then use
+                                the menu to Select "Generic CTF Trace" from the
+                                "Trace Type... -> Common Trace Format" menu to
+                                map the tracing type.</para></listitem>
+                            <listitem><para>Right click the mouse and select
+                                "Open" to bring up the Eclipse Lttng Trace
+                                Viewer so you view the tracing data.
+                                </para></listitem>
+                        </orderedlist></para></listitem>
+                    <listitem><para><emphasis><filename>PowerTOP</filename>:</emphasis>
+                        Selecting this tool runs PowerTOP on the remote target
+                        machine and displays the results in a new view called
+                        PowerTOP.</para>
+                        <para>The "Time to gather data(sec):" field is the time
+                        passed in seconds before data is gathered from the
+                        remote target for analysis.</para>
+                        <para>The "show pids in wakeups list:" field corresponds
+                        to the <filename>-p</filename> argument passed to
+                        <filename>PowerTOP</filename>.</para></listitem>
+                    <listitem><para><emphasis><filename>LatencyTOP and Perf</filename>:</emphasis>
+                        LatencyTOP identifies system latency, while
+                        Perf monitors the system's performance counter
+                        registers.
+                        Selecting either of these tools causes an RSE terminal
+                        view to appear from which you can run the tools.
+                        Both tools refresh the entire screen to display results
+                        while they run.
+                        For more information on setting up and using
+                        <filename>perf</filename>, see the
+                        "<ulink url='&YOCTO_DOCS_PROF_URL;#profile-manual-perf'>perf</ulink>"
+                        section in the Yocto Project Profiling and Tracing
+                        Manual.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='customizing-an-image-using-a-bitbake-commander-project-and-hob'>
+            <title>Customizing an Image Using a BitBake Commander Project and Hob</title>
+
+            <para>
+                Within the Eclipse IDE, you can create a Yocto BitBake Commander
+                project, edit the <link linkend='metadata'>Metadata</link>, and
+                then use
+                <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> to build a customized image all within one IDE.
+            </para>
+
+            <section id='creating-the-yocto-bitbake-commander-project'>
+                <title>Creating the Yocto BitBake Commander Project</title>
+
+                <para>
+                    To create a Yocto BitBake Commander project, follow these
+                    steps:
+                    <orderedlist>
+                        <listitem><para>Select "Other" from the
+                            "Window -> Open Perspective" menu
+                            and then choose "Bitbake Commander".
+                            </para></listitem>
+                        <listitem><para>Click "OK" to change the perspective to
+                            Bitbake Commander.</para></listitem>
+                        <listitem><para>Select "Project" from the "File -> New"
+                            menu to create a new Yocto
+                            Bitbake Commander project.</para></listitem>
+                        <listitem><para>Choose "New Yocto Project" from the
+                            "Yocto Project Bitbake Commander" menu and click
+                            "Next".</para></listitem>
+                        <listitem><para>Enter the Project Name and choose the
+                            Project Location.
+                            The Yocto project's Metadata files will be put under
+                            the directory
+                            <filename>&lt;project_location&gt;/&lt;project_name&gt;</filename>.
+                            If that directory does not exist, you need to check
+                            the "Clone from Yocto Git Repository" box, which
+                            would execute a <filename>git clone</filename>
+                            command to get the project's Metadata files.
+                            <note>
+                                Do not specify your BitBake Commander project
+                                location as your Eclipse workspace.
+                                Doing so causes an error indicating that the
+                                current project overlaps the location of
+                                another project.
+                                This error occurs even if no such project exits.
+                            </note></para></listitem>
+                        <listitem><para>Select <filename>Finish</filename> to
+                            create the project.</para></listitem>
+                    </orderedlist>
+                </para>
+            </section>
+
+            <section id='editing-the-metadata'>
+                <title>Editing the Metadata</title>
+
+                <para>
+                    After you create the Yocto Bitbake Commander project, you
+                    can modify the <link linkend='metadata'>Metadata</link>
+                    files by opening them in the project.
+                    When editing recipe files (<filename>.bb</filename> files),
+                    you can view BitBake variable values and information by
+                    hovering the mouse pointer over the variable name and
+                    waiting a few seconds.
+                </para>
+
+                <para>
+                    To edit the Metadata, follow these steps:
+                    <orderedlist>
+                        <listitem><para>Select your Yocto Bitbake Commander
+                            project.</para></listitem>
+                        <listitem><para>Select "BitBake Recipe" from the
+                        "File -> New -> Yocto BitBake Commander" menu
+                            to open a new recipe wizard.</para></listitem>
+                        <listitem><para>Point to your source by filling in the
+                            "SRC_URL" field.
+                            For example, you can add a recipe to your
+                            <link linkend='source-directory'>Source Directory</link>
+                            by defining "SRC_URL" as follows:
+                            <literallayout class='monospaced'>
+     ftp://ftp.gnu.org/gnu/m4/m4-1.4.9.tar.gz
+                            </literallayout></para></listitem>
+                        <listitem><para>Click "Populate" to calculate the
+                            archive md5, sha256, license checksum values and to
+                            auto-generate the recipe filename.</para></listitem>
+                        <listitem><para>Fill in the "Description" field.
+                            </para></listitem>
+                        <listitem><para>Be sure values for all required
+                            fields exist.</para></listitem>
+                        <listitem><para>Click "Finish".</para></listitem>
+                    </orderedlist>
+                </para>
+            </section>
+
+            <section id='biding-and-customizing-the-image-using-hob'>
+                <title>Building and Customizing the Image Using Hob</title>
+
+                <para>
+                    To build and customize the image using Hob from within the
+                    Eclipse IDE, follow these steps:
+                    <orderedlist>
+                        <listitem><para>Select your Yocto Bitbake Commander
+                            project.</para></listitem>
+                        <listitem><para>Select "Launch Hob" from the "Project"
+                            menu.</para></listitem>
+                        <listitem><para>Enter the
+                            <link linkend='build-directory'>Build Directory</link>
+                            where you want to put your final images.
+                            </para></listitem>
+                        <listitem><para>Click "OK" to launch Hob.
+                            </para></listitem>
+                        <listitem><para>Use Hob to customize and build your own
+                            images.
+                            For information on Hob, see the
+                            <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project Page</ulink>
+                            on the Yocto Project website.</para></listitem>
+                    </orderedlist>
+                </para>
+            </section>
+        </section>
+    </section>
+
+    <section id='workflow-using-stand-alone-cross-development-toolchains'>
+        <title>Workflow Using Stand-Alone Cross-Development Toolchains</title>
+
+        <para>
+            If you want to develop an application without prior installation
+            of the ADT, you still can employ the
+            <link linkend='cross-development-toolchain'>Cross Development Toolchain</link>,
+            the QEMU emulator, and a number of supported  target image files.
+            You just need to follow these general steps:
+            <orderedlist>
+                <listitem><para><emphasis>Install the cross-development
+                    toolchain for your target hardware:</emphasis>
+                    For information on how to install the toolchain, see the
+                    "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>"
+                    section in the Yocto Project Application Developer's
+                    Guide.</para></listitem>
+                <listitem><para><emphasis>Download the Target Image:</emphasis>
+                    The Yocto Project supports several target architectures
+                    and has many pre-built kernel images and root filesystem
+                    images.</para>
+                    <para>If you are going to develop your application on
+                    hardware, go to the
+                    <ulink url='&YOCTO_MACHINES_DL_URL;'><filename>machines</filename></ulink>
+                    download area and choose a target machine area
+                    from which to download the kernel image and root filesystem.
+                    This download area could have several files in it that
+                    support development using actual hardware.
+                    For example, the area might contain
+                    <filename>.hddimg</filename> files that combine the
+                    kernel image with the filesystem, boot loaders, and
+                    so forth.
+                    Be sure to get the files you need for your particular
+                    development process.</para>
+                    <para>If you are going to develop your application and
+                    then run and test it using the QEMU emulator, go to the
+                    <ulink url='&YOCTO_QEMU_DL_URL;'><filename>machines/qemu</filename></ulink>
+                    download area.
+                    From this area, go down into the directory for your
+                    target architecture (e.g. <filename>qemux86_64</filename>
+                    for an <trademark class='registered'>Intel</trademark>-based
+                    64-bit architecture).
+                    Download kernel, root filesystem, and any other files you
+                    need for your process.
+                    <note>In order to use the root filesystem in QEMU, you
+                    need to extract it.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_ADT_URL;#extracting-the-root-filesystem'>Extracting the Root Filesystem</ulink>"
+                    section for information on how to extract the root
+                    filesystem.</note></para></listitem>
+                <listitem><para><emphasis>Develop and Test your
+                    Application:</emphasis>  At this point, you have the tools
+                    to develop your application.
+                    If you need to separately install and use the QEMU
+                    emulator, you can go to
+                    <ulink url='http://wiki.qemu.org/Main_Page'>QEMU Home Page</ulink>
+                    to download and learn about the emulator.</para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+</section>
+
+<section id="modifying-temporary-source-code">
+    <title>Modifying Temporary Source Code</title>
+
+    <para>
+        You might
+        find it helpful during development to modify the temporary source code used by recipes
+        to build packages.
+        For example, suppose you are developing a patch and you need to experiment a bit
+        to figure out your solution.
+        After you have initially built the package, you can iteratively tweak the
+        source code, which is located in the
+        <link linkend='build-directory'>Build Directory</link>, and then
+        you can force a re-compile and quickly test your altered code.
+        Once you settle on a solution, you can then preserve your changes in the form of
+        patches.
+        You can accomplish these steps all within either a
+        <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink> or
+        <link linkend='git'>Git</link> workflow.
+    </para>
+
+    <section id='finding-the-temporary-source-code'>
+        <title>Finding the Temporary Source Code</title>
+
+        <para>
+            During a build, the unpacked temporary source code used by recipes
+            to build packages is available in the Build Directory as
+            defined by the
+            <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-S'>S</ulink></filename> variable.
+            Below is the default value for the <filename>S</filename> variable as defined in the
+            <filename>meta/conf/bitbake.conf</filename> configuration file in the
+            <link linkend='source-directory'>Source Directory</link>:
+            <literallayout class='monospaced'>
+     S = ${WORKDIR}/${BP}
+            </literallayout>
+            You should be aware that many recipes override the <filename>S</filename> variable.
+            For example, recipes that fetch their source from Git usually set
+            <filename>S</filename> to <filename>${WORKDIR}/git</filename>.
+            <note>
+                The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-BP'><filename>BP</filename></ulink>
+                represents the base recipe name, which consists of the name and version:
+                <literallayout class='monospaced'>
+     BP = ${BPN}-${PV}
+                </literallayout>
+            </note>
+        </para>
+
+        <para>
+            The path to the work directory for the recipe
+            (<ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>) depends
+            on the recipe name and the architecture of the target device.
+            For example, here is the work directory for recipes and resulting packages that are
+            not device-dependent:
+            <literallayout class='monospaced'>
+     ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${EXTENDPE}${PV}-${PR}
+            </literallayout>
+            Let's look at an example without variables.
+            Assuming a top-level <link linkend='source-directory'>Source Directory</link>
+            named <filename>poky</filename>
+            and a default Build Directory of <filename>poky/build</filename>,
+            the following is the work directory for the <filename>acl</filename> recipe that
+            creates the <filename>acl</filename> package:
+            <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/i586-poky-linux/acl/2.2.51-r3/
+            </literallayout>
+        </para>
+
+        <para>
+            If your resulting package is dependent on the target device,
+            the work directory varies slightly:
+            <literallayout class='monospaced'>
+     ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${EXTENDPE}${PV}-${PR}
+            </literallayout>
+            Again, assuming top-level Source Directory named <filename>poky</filename>
+            and a default Build Directory of <filename>poky/build</filename>, the
+            following are the work and temporary source directories, respectively,
+            for the <filename>acl</filename> package that is being
+            built for a MIPS-based device:
+            <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
+     ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2/acl-2.2.51
+            </literallayout>
+        </para>
+
+        <note>
+            To better understand how the OpenEmbedded build system resolves directories during the
+            build process, see the glossary entries for the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-TMPDIR'><filename>TMPDIR</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-TARGET_OS'><filename>TARGET_OS</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-EXTENDPE'><filename>EXTENDPE</filename></ulink>,
+            and
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+            variables in the Yocto Project Reference Manual.
+        </note>
+
+        <para>
+            Now that you know where to locate the directory that has the temporary source code,
+            you can use a Quilt or Git workflow to make your edits, test the changes,
+            and preserve the changes in the form of patches.
+        </para>
+    </section>
+
+    <section id="using-a-quilt-workflow">
+        <title>Using a Quilt Workflow</title>
+
+        <para>
+            <ulink url='http://savannah.nongnu.org/projects/quilt'>Quilt</ulink>
+            is a powerful tool that allows you to capture source code changes without having
+            a clean source tree.
+            This section outlines the typical workflow you can use to modify temporary source code,
+            test changes, and then preserve the changes in the form of a patch all using Quilt.
+        </para>
+
+        <para>
+            Follow these general steps:
+            <orderedlist>
+                <listitem><para><emphasis>Find the Source Code:</emphasis>
+                    The temporary source code used by the OpenEmbedded build system is kept in the
+                    Build Directory.
+                    See the
+                    "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
+                    section to learn how to locate the directory that has the temporary source code for a
+                    particular package.</para></listitem>
+                <listitem><para><emphasis>Change Your Working Directory:</emphasis>
+                    You need to be in the directory that has the temporary source code.
+                    That directory is defined by the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+                    variable.</para></listitem>
+                <listitem><para><emphasis>Create a New Patch:</emphasis>
+                    Before modifying source code, you need to create a new patch.
+                    To create a new patch file, use <filename>quilt new</filename> as below:
+                    <literallayout class='monospaced'>
+     $ quilt new my_changes.patch
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Notify Quilt and Add Files:</emphasis>
+                    After creating the patch, you need to notify Quilt about the files
+                    you plan to edit.
+                    You notify Quilt by adding the files to the patch you just created:
+                    <literallayout class='monospaced'>
+     $ quilt add file1.c file2.c file3.c
+                    </literallayout>
+                    </para></listitem>
+                <listitem><para><emphasis>Edit the Files:</emphasis>
+                    Make your changes in the temporary source code to the files you added
+                    to the patch.</para></listitem>
+                <listitem><para><emphasis>Test Your Changes:</emphasis>
+                    Once you have modified the source code, the easiest way to test your changes
+                    is by calling the <filename>compile</filename> task as shown in the following example:
+                    <literallayout class='monospaced'>
+     $ bitbake -c compile -f &lt;name_of_package&gt;
+                    </literallayout>
+                    The <filename>-f</filename> or <filename>--force</filename>
+                    option forces the specified task to execute.
+                    If you find problems with your code, you can just keep editing and
+                    re-testing iteratively until things work as expected.
+                    <note>All the modifications you make to the temporary source code
+                    disappear once you <filename>-c clean</filename> or
+                    <filename>-c cleanall</filename> with BitBake for the package.
+                    Modifications will also disappear if you use the <filename>rm_work</filename>
+                    feature as described in the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+                    section of the Yocto Project Quick Start.
+                    </note></para></listitem>
+                <listitem><para><emphasis>Generate the Patch:</emphasis>
+                    Once your changes work as expected, you need to use Quilt to generate the final patch that
+                    contains all your modifications.
+                    <literallayout class='monospaced'>
+     $ quilt refresh
+                    </literallayout>
+                    At this point, the <filename>my_changes.patch</filename> file has all your edits made
+                    to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
+                    <filename>file3.c</filename> files.</para>
+                    <para>You can find the resulting patch file in the <filename>patches/</filename>
+                    subdirectory of the source (<filename>S</filename>) directory.</para></listitem>
+                <listitem><para><emphasis>Copy the Patch File:</emphasis>
+                    For simplicity, copy the patch file into a directory named <filename>files</filename>,
+                    which you can create in the same directory that holds the recipe
+                    (<filename>.bb</filename>) file or the
+                    append (<filename>.bbappend</filename>) file.
+                    Placing the patch here guarantees that the OpenEmbedded build system will find
+                    the patch.
+                    Next, add the patch into the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
+                    of the recipe.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     SRC_URI += "file://my_changes.patch"
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
+                    Finally, don't forget to 'bump' the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
+                    value in the recipe since the resulting packages have changed.</para></listitem>
+            </orderedlist>
+        </para>     </section>
+
+    <section id='using-a-git-workflow'>
+        <title>Using a Git Workflow</title>
+        <para>
+            Git is an even more powerful tool that allows you to capture source code changes without having
+            a clean source tree.
+            This section outlines the typical workflow you can use to modify temporary source code,
+            test changes, and then preserve the changes in the form of a patch all using Git.
+            For general information on Git as it is used in the Yocto Project, see the
+            "<link linkend='git'>Git</link>" section.
+        </para>
+
+        <note>
+            This workflow uses Git only for its ability to manage local changes to the source code
+            and produce patches independent of any version control system used with the Yocto Project.
+        </note>
+
+        <para>
+            Follow these general steps:
+            <orderedlist>
+                <listitem><para><emphasis>Find the Source Code:</emphasis>
+                    The temporary source code used by the OpenEmbedded build system is kept in the
+                    Build Directory.
+                    See the
+                    "<link linkend='finding-the-temporary-source-code'>Finding the Temporary Source Code</link>"
+                    section to learn how to locate the directory that has the temporary source code for a
+                    particular package.</para></listitem>
+                <listitem><para><emphasis>Change Your Working Directory:</emphasis>
+                    You need to be in the directory that has the temporary source code.
+                    That directory is defined by the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>
+                    variable.</para></listitem>
+                <listitem><para><emphasis>If needed, initialize a Git Repository:</emphasis>
+                    If the recipe you are working with does not use a Git fetcher,
+                    you need to set up a Git repository as follows:
+                    <literallayout class='monospaced'>
+     $ git init
+     $ git add *
+     $ git commit -m "initial revision"
+                    </literallayout>
+                    The above Git commands initialize a Git repository that is based on the
+                    files in your current working directory, stage all the files, and commit
+                    the files.
+                    At this point, your Git repository is aware of all the source code files.
+                    Any edits you now make to files can be committed later and will be tracked by
+                    Git.</para></listitem>
+                <listitem><para><emphasis>Edit the Files:</emphasis>
+                    Make your changes to the temporary source code.</para></listitem>
+                <listitem><para><emphasis>Test Your Changes:</emphasis>
+                    Once you have modified the source code, the easiest way to test your changes
+                    is by calling the <filename>compile</filename> task as shown in the following example:
+                    <literallayout class='monospaced'>
+     $ bitbake -c compile -f &lt;name_of_package&gt;
+                    </literallayout>
+                    The <filename>-f</filename> or <filename>--force</filename>
+                    option forces the specified task to execute.
+                    If you find problems with your code, you can just keep editing and
+                    re-testing iteratively until things work as expected.
+                    <note>All the modifications you make to the temporary source code
+                    disappear once you <filename>-c clean</filename>, <filename>-c cleansstate</filename>,
+                    or <filename>-c cleanall</filename> with BitBake for the package.
+                    Modifications will also disappear if you use the <filename>rm_work</filename>
+                    feature as described in the
+                    "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+                    section of the Yocto Project Quick Start.
+                    </note></para></listitem>
+                <listitem><para><emphasis>See the List of Files You Changed:</emphasis>
+                    Use the <filename>git status</filename> command to see what files you have actually edited.
+                    The ability to have Git track the files you have changed is an advantage that this
+                    workflow has over the Quilt workflow.
+                    Here is the Git command to list your changed files:
+                    <literallayout class='monospaced'>
+     $ git status
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Stage the Modified Files:</emphasis>
+                    Use the <filename>git add</filename> command to stage the changed files so they
+                    can be committed as follows:
+                    <literallayout class='monospaced'>
+     $ git add file1.c file2.c file3.c
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Commit the Staged Files and View Your Changes:</emphasis>
+                    Use the <filename>git commit</filename> command to commit the changes to the
+                    local repository.
+                    Once you have committed the files, you can use the <filename>git log</filename>
+                    command to see your changes:
+                    <literallayout class='monospaced'>
+     $ git commit -m "&lt;commit-summary-message&gt;"
+     $ git log
+                    </literallayout>
+                    <note>The name of the patch file created in the next step is based on your
+                        <filename>commit-summary-message</filename>.</note></para></listitem>
+                <listitem><para><emphasis>Generate the Patch:</emphasis>
+                    Once the changes are committed, use the <filename>git format-patch</filename>
+                    command to generate a patch file:
+                    <literallayout class='monospaced'>
+     $ git format-patch -1
+                    </literallayout>
+                    Specifying "-1" causes Git to generate the
+                    patch file for the most recent commit.</para>
+                    <para>At this point, the patch file has all your edits made
+                    to the <filename>file1.c</filename>, <filename>file2.c</filename>, and
+                    <filename>file3.c</filename> files.
+                    You can find the resulting patch file in the current directory and it
+                    is named according to the <filename>git commit</filename> summary line.
+                    The patch file ends with <filename>.patch</filename>.</para></listitem>
+                <listitem><para><emphasis>Copy the Patch File:</emphasis>
+                    For simplicity, copy the patch file into a directory named <filename>files</filename>,
+                    which you can create in the same directory that holds the recipe
+                    (<filename>.bb</filename>) file or the
+                    append (<filename>.bbappend</filename>) file.
+                    Placing the patch here guarantees that the OpenEmbedded build system will find
+                    the patch.
+                    Next, add the patch into the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'>SRC_URI</ulink></filename>
+                    of the recipe.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     SRC_URI += "file://0001-&lt;commit-summary-message&gt;.patch"
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Increment the Recipe Revision Number:</emphasis>
+                    Finally, don't forget to 'bump' the
+                    <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename>
+                    value in the recipe since the resulting packages have changed.</para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+</section>
+
+<section id='image-development-using-hob'>
+    <title>Image Development Using Hob</title>
+
+    <para>
+        The <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink> is a graphical user interface for the
+        OpenEmbedded build system, which is based on BitBake.
+        You can use the Hob to build custom operating system images within the Yocto Project build environment.
+        Hob simply provides a friendly interface over the build system used during development.
+        In other words, building images with the Hob lets you take care of common build tasks more easily.
+    </para>
+
+    <para>
+        For a better understanding of Hob, see the project page at
+        <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'></ulink>
+        on the Yocto Project website.
+        If you follow the "Documentation" link from the Hob page, you will
+        find a short introductory training video on Hob.
+        The following lists some features of Hob:
+        <itemizedlist>
+            <listitem><para>You can setup and run Hob using these commands:
+            <literallayout class='monospaced'>
+     $ source oe-init-build-env
+     $ hob
+            </literallayout></para></listitem>
+            <listitem><para>You can set the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+                for which you are building the image.</para></listitem>
+            <listitem><para>You can modify various policy settings such as the
+                package format with which to build,
+                the parallelism BitBake uses, whether or not to build an
+                external toolchain, and which host to build against.
+                </para></listitem>
+            <listitem><para>You can manage
+                <link linkend='understanding-and-creating-layers'>layers</link>.</para></listitem>
+            <listitem><para>You can select a base image and then add extra packages for your custom build.
+                </para></listitem>
+            <listitem><para>You can launch and monitor the build from within Hob.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id="platdev-appdev-devshell">
+    <title>Using a Development Shell</title>
+
+    <para>
+        When debugging certain commands or even when just editing packages,
+        <filename>devshell</filename> can be a useful tool.
+        When you invoke <filename>devshell</filename>, source files are
+        extracted into your working directory and patches are applied.
+        Then, a new terminal is opened and you are placed in the working directory.
+        In the new terminal, all the OpenEmbedded build-related environment variables are
+        still defined so you can use commands such as <filename>configure</filename> and
+        <filename>make</filename>.
+        The commands execute just as if the OpenEmbedded build system were executing them.
+        Consequently, working this way can be helpful when debugging a build or preparing
+        software to be used with the OpenEmbedded build system.
+    </para>
+
+    <para>
+        Following is an example that uses <filename>devshell</filename> on a target named
+        <filename>matchbox-desktop</filename>:
+        <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c devshell
+        </literallayout>
+    </para>
+
+    <para>
+        This command spawns a terminal with a shell prompt within the OpenEmbedded build environment.
+        The <ulink url='&YOCTO_DOCS_REF_URL;#var-OE_TERMINAL'><filename>OE_TERMINAL</filename></ulink>
+        variable controls what type of shell is opened.
+    </para>
+
+    <para>
+        For spawned terminals, the following occurs:
+        <itemizedlist>
+            <listitem><para>The <filename>PATH</filename> variable includes the
+                cross-toolchain.</para></listitem>
+            <listitem><para>The <filename>pkgconfig</filename> variables find the correct
+                <filename>.pc</filename> files.</para></listitem>
+                <listitem><para>The <filename>configure</filename> command finds the
+                Yocto Project site files as well as any other necessary files.</para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        Within this environment, you can run configure or compile
+        commands as if they were being run by
+        the OpenEmbedded build system itself.
+        As noted earlier, the working directory also automatically changes to the
+        Source Directory (<ulink url='&YOCTO_DOCS_REF_URL;#var-S'><filename>S</filename></ulink>).
+    </para>
+
+    <para>
+        When you are finished, you just exit the shell or close the terminal window.
+    </para>
+
+    <note>
+        <para>
+            It is worth remembering that when using <filename>devshell</filename>
+            you need to use the full compiler name such as <filename>arm-poky-linux-gnueabi-gcc</filename>
+            instead of just using <filename>gcc</filename>.
+            The same applies to other applications such as <filename>binutils</filename>,
+            <filename>libtool</filename> and so forth.
+            BitBake sets up environment variables such as <filename>CC</filename>
+            to assist applications, such as <filename>make</filename> to find the correct tools.
+        </para>
+
+        <para>
+            It is also worth noting that <filename>devshell</filename> still works over
+            X11 forwarding and similar situations.
+        </para>
+    </note>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
new file mode 100644
index 0000000000..34326d10b6
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -0,0 +1,1575 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='dev-manual-newbie'>
+
+<title>The Yocto Project Open Source Development Environment</title>
+
+<para>
+    This chapter helps you understand the Yocto Project as an open source development project.
+    In general, working in an open source environment is very different from working in a
+    closed, proprietary environment.
+    Additionally, the Yocto Project uses specific tools and constructs as part of its development
+    environment.
+    This chapter specifically addresses open source philosophy, using the
+    Yocto Project in a team environment, source repositories, Yocto Project
+    terms, licensing, the open source distributed version control system Git,
+    workflows, bug tracking, and how to submit changes.
+</para>
+
+<section id='open-source-philosophy'>
+    <title>Open Source Philosophy</title>
+
+    <para>
+        Open source philosophy is characterized by software development directed by peer production
+        and collaboration through an active community of developers.
+        Contrast this to the more standard centralized development models used by commercial software
+        companies where a finite set of developers produces a product for sale using a defined set
+        of procedures that ultimately result in an end product whose architecture and source material
+        are closed to the public.
+    </para>
+
+    <para>
+        Open source projects conceptually have differing concurrent agendas, approaches, and production.
+        These facets of the development process can come from anyone in the public (community) that has a
+        stake in the software project.
+        The open source environment contains new copyright, licensing, domain, and consumer issues
+        that differ from the more traditional development environment.
+        In an open source environment, the end product, source material, and documentation are
+        all available to the public at no cost.
+    </para>
+
+    <para>
+        A benchmark example of an open source project is the Linux Kernel, which was initially conceived
+        and created by Finnish computer science student Linus Torvalds in 1991.
+        Conversely, a good example of a non-open source project is the
+        <trademark class='registered'>Windows</trademark> family of operating
+        systems developed by <trademark class='registered'>Microsoft</trademark> Corporation.
+    </para>
+
+    <para>
+        Wikipedia has a good historical description of the Open Source Philosophy
+        <ulink url='http://en.wikipedia.org/wiki/Open_source'>here</ulink>.
+        You can also find helpful information on how to participate in the Linux Community
+        <ulink url='http://ldn.linuxfoundation.org/book/how-participate-linux-community'>here</ulink>.
+    </para>
+</section>
+
+<section id="usingpoky-changes-collaborate">
+    <title>Using the Yocto Project in a Team Environment</title>
+
+    <para>
+        It might not be immediately clear how you can use the Yocto
+        Project in a team environment, or scale it for a large team of
+        developers.
+        One of the strengths of the Yocto Project is that it is extremely
+        flexible.
+        Thus, you can adapt it to many different use cases and scenarios.
+        However, these characteristics can cause a struggle if you are trying
+        to create a working setup that scales across a large team.
+    </para>
+
+    <para>
+        To help with these types of situations, this section presents
+        some of the project's most successful experiences,
+        practices, solutions, and available technologies that work well.
+        Keep in mind, the information here is a starting point.
+        You can build off it and customize it to fit any
+        particular working environment and set of practices.
+    </para>
+
+    <section id='best-practices-system-configurations'>
+        <title>System Configurations</title>
+
+        <para>
+            Systems across a large team should meet the needs of
+            two types of developers: those working on the contents of the
+            operating system image itself and those developing applications.
+            Regardless of the type of developer, their workstations must
+            be both reasonably powerful and run Linux.
+        </para>
+
+        <section id='best-practices-application-development'>
+            <title>Application Development</title>
+
+            <para>
+                For developers who mainly do application level work
+                on top of an existing software stack,
+                here are some practices that work best:
+                <itemizedlist>
+                    <listitem><para>Use a pre-built toolchain that
+                        contains the software stack itself.
+                        Then, develop the application code on top of the
+                        stack.
+                        This method works well for small numbers of relatively
+                        isolated applications.</para></listitem>
+                    <listitem><para>When possible, use the Yocto Project
+                        plug-in for the <trademark class='trade'>Eclipse</trademark> IDE
+                        and other pieces of Application Development
+                        Technology (ADT).
+                        For more information, see the
+                        "<link linkend='application-development-workflow'>Application
+                        Development Workflow</link>" section as well as the
+                        <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project Application Developer's Guide</ulink>.
+                        </para></listitem>
+                    <listitem><para>Keep your cross-development toolchains
+                        updated.
+                        You can do this through provisioning either as new
+                        toolchain downloads or as updates through a package
+                        update mechanism using <filename>opkg</filename>
+                        to provide updates to an existing toolchain.
+                        The exact mechanics of how and when to do this are a
+                        question for local policy.</para></listitem>
+                    <listitem><para>Use multiple toolchains installed locally
+                        into different locations to allow development across
+                        versions.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='best-practices-core-system-development'>
+            <title>Core System Development</title>
+
+            <para>
+                For core system development, it is often best to have the
+                build system itself available on the developer workstations
+                so developers can run their own builds and directly
+                rebuild the software stack.
+                You should keep the core system unchanged as much as
+                possible and do your work in layers on top of the core system.
+                Doing so gives you a greater level of portability when
+                upgrading to new versions of the core system or Board
+                Support Packages (BSPs).
+                You can share layers amongst the developers of a particular
+                project and contain the policy configuration that defines
+                the project.
+            </para>
+
+            <para>
+                Aside from the previous best practices, there exists a number
+                of tips and tricks that can help speed up core development
+                projects:
+                <itemizedlist>
+                    <listitem><para>Use a
+                        <ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>
+                        (sstate) among groups of developers who are on a
+                        fast network.
+                        The best way to share sstate is through a
+                        Network File System (NFS) share.
+                        The first user to build a given component for the
+                        first time contributes that object to the sstate,
+                        while subsequent builds from other developers then
+                        reuse the object rather than rebuild it themselves.
+                        </para>
+                        <para>Although it is possible to use other protocols for the
+                        sstate such as HTTP and FTP, you should avoid these.
+                        Using HTTP limits the sstate to read-only and
+                        FTP provides poor performance.
+                        </para></listitem>
+                    <listitem><para>Have autobuilders contribute to the sstate
+                        pool similarly to how the developer workstations
+                        contribute.
+                        For information, see the
+                        <link linkend='best-practices-autobuilders'>Autobuilders</link>
+                        section.</para></listitem>
+                    <listitem><para>Build stand-alone tarballs that contain
+                        "missing" system requirements if for some reason
+                        developer workstations do not meet minimum system
+                        requirements such as latest Python versions,
+                        <filename>chrpath</filename>, or other tools.
+                        You can install and relocate the tarball exactly as you
+                        would the usual cross-development toolchain so that
+                        all developers can meet minimum version requirements
+                        on most distributions.</para></listitem>
+                    <listitem><para>Use a small number of shared,
+                        high performance systems for testing purposes
+                        (e.g. dual six core Xeons with 24GB RAM and plenty of
+                        disk space).
+                        Developers can use these systems for wider, more
+                        extensive testing while they continue to develop
+                        locally using their primary development system.
+                        </para></listitem>
+                    <listitem><para>Enable the PR Service when package feeds
+                        need to be incremental with continually increasing
+                        <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink>
+                        values.
+                        Typically, this situation occurs when you use or
+                        publish package feeds and use a shared state.
+                        You should enable the PR Service for all users who
+                        use the shared state pool.
+                        For more information on the PR Service, see the
+                        "<link linkend='working-with-a-pr-service'>Working With a PR Service</link>".
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+    </section>
+
+    <section id='best-practices-source-control-management'>
+        <title>Source Control Management (SCM)</title>
+
+        <para>
+            Keeping your
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+            and any software you are developing under the
+            control of an SCM system that is compatible
+            with the OpenEmbedded build system is advisable.
+            Of the SCMs BitBake supports, the
+            Yocto Project team strongly recommends using
+            <link linkend='git'>Git</link>.
+            Git is a distributed system that is easy to backup,
+            allows you to work remotely, and then connects back to the
+            infrastructure.
+            <note>
+                For information about BitBake and SCMs, see the
+                BitBake manual located in the
+                <filename>bitbake/doc/manual</filename> directory of the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            </note>
+        </para>
+
+        <para>
+            It is relatively easy to set up Git services and create
+            infrastructure like
+            <ulink url='&YOCTO_GIT_URL;'>http://git.yoctoproject.org</ulink>,
+            which is based on server software called
+            <filename>gitolite</filename> with <filename>cgit</filename>
+            being used to generate the web interface that lets you view the
+            repositories.
+            The <filename>gitolite</filename> software identifies users
+            using <filename>ssh</filename> keys and allows branch-based
+            access controls to repositories that you can control as little
+            or as much as necessary.
+        </para>
+
+        <note>
+            The setup of these services is beyond the scope of this manual.
+            However, sites such as these exist that describe how to perform
+            setup:
+            <itemizedlist>
+                <listitem><para><ulink url='http://git-scm.com/book/ch4-8.html'>Git documentation</ulink>:
+                    Describes how to install <filename>gitolite</filename>
+                    on the server.</para></listitem>
+                <listitem><para><ulink url='http://sitaramc.github.com/gitolite/master-toc.html'>The <filename>gitolite</filename> master index</ulink>:
+                    All topics for <filename>gitolite</filename>.
+                    </para></listitem>
+                <listitem><para><ulink url='https://git.wiki.kernel.org/index.php/Interfaces,_frontends,_and_tools'>Interfaces, frontends, and tools</ulink>:
+                    Documentation on how to create interfaces and frontends
+                    for Git.</para></listitem>
+            </itemizedlist>
+        </note>
+    </section>
+
+    <section id='best-practices-autobuilders'>
+        <title>Autobuilders</title>
+
+        <para>
+            Autobuilders are often the core of a development project.
+            It is here that changes from individual developers are brought
+            together and centrally tested and subsequent decisions about
+            releases can be made.
+            Autobuilders also allow for "continuous integration" style
+            testing of software components and regression identification
+            and tracking.
+        </para>
+
+        <para>
+            See "<ulink url='http://autobuilder.yoctoproject.org'>Yocto Project Autobuilder</ulink>"
+            for more information and links to buildbot.
+            The Yocto Project team has found this implementation
+            works well in this role.
+            A public example of this is the Yocto Project
+            Autobuilders, which we use to test the overall health of the
+            project.
+        </para>
+
+        <para>
+            The features of this system are:
+            <itemizedlist>
+                <listitem><para>Highlights when commits break the build.
+                    </para></listitem>
+                <listitem><para>Populates an sstate cache from which
+                    developers can pull rather than requiring local
+                    builds.</para></listitem>
+                <listitem><para>Allows commit hook triggers,
+                    which trigger builds when commits are made.
+                    </para></listitem>
+                <listitem><para>Allows triggering of automated image booting
+                    and testing under the QuickEMUlator (QEMU).
+                    </para></listitem>
+                <listitem><para>Supports incremental build testing and from
+                    scratch builds.</para></listitem>
+                <listitem><para>Shares output that allows developer
+                    testing and historical regression investigation.
+                    </para></listitem>
+                <listitem><para>Creates output that can be used for releases.
+                    </para></listitem>
+                <listitem><para>Allows scheduling of builds so that resources
+                    can be used efficiently.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='best-practices-policies-and-change-flow'>
+        <title>Policies and Change Flow</title>
+
+        <para>
+            The Yocto Project itself uses a hierarchical structure and a
+            pull model.
+            Scripts exist to create and send pull requests
+            (i.e. <filename>create-pull-request</filename> and
+            <filename>send-pull-request</filename>).
+            This model is in line with other open source projects where
+            maintainers are responsible for specific areas of the project
+            and a single maintainer handles the final "top-of-tree" merges.
+        </para>
+
+        <note>
+            You can also use a more collective push model.
+            The <filename>gitolite</filename> software supports both the
+            push and pull models quite easily.
+        </note>
+
+        <para>
+            As with any development environment, it is important
+            to document the policy used as well as any main project
+            guidelines so they are understood by everyone.
+            It is also a good idea to have well structured
+            commit messages, which are usually a part of a project's
+            guidelines.
+            Good commit messages are essential when looking back in time and
+            trying to understand why changes were made.
+        </para>
+
+        <para>
+            If you discover that changes are needed to the core layer of the
+            project, it is worth sharing those with the community as soon
+            as possible.
+            Chances are if you have discovered the need for changes, someone
+            else in the community needs them also.
+        </para>
+    </section>
+
+    <section id='best-practices-summary'>
+        <title>Summary</title>
+
+        <para>
+            This section summarizes the key recommendations described in the
+            previous sections:
+            <itemizedlist>
+                <listitem><para>Use <link linkend='git'>Git</link>
+                    as the source control system.</para></listitem>
+                <listitem><para>Maintain your Metadata in layers that make sense
+                    for your situation.
+                    See the "<link linkend='understanding-and-creating-layers'>Understanding
+                    and Creating Layers</link>" section for more information on
+                    layers.</para></listitem>
+                <listitem><para>Separate the project's Metadata and code by using
+                    separate Git repositories.
+                    See the "<link linkend='yocto-project-repositories'>Yocto Project
+                    Source Repositories</link>" section for information on these
+                    repositories.
+                    See the "<link linkend='getting-setup'>Getting Set Up</link>" section
+                    for information on how to set up various Yocto Project related
+                    Git repositories.</para></listitem>
+                <listitem><para>Set up the directory for the shared state cache
+                    (<ulink url='&YOCTO_DOCS_REF_URL;#var-SSTATE_DIR'><filename>SSTATE_DIR</filename></ulink>)
+                    where it makes sense.
+                    For example, set up the sstate cache on a system used
+                    by developers in the same organization and share the
+                    same source directories on their machines.
+                    </para></listitem>
+                <listitem><para>Set up an Autobuilder and have it populate the
+                    sstate cache and source directories.</para></listitem>
+                <listitem><para>The Yocto Project community encourages you
+                    to send patches to the project to fix bugs or add features.
+                    If you do submit patches, follow the project commit
+                    guidelines for writing good commit messages.
+                    See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
+                    section.</para></listitem>
+                <listitem><para>Send changes to the core sooner than later
+                    as others likely run into the same issues.
+                    For some guidance on mailing lists to use, see the list in the
+                    "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
+                    section.
+                    For a description of the available mailing lists, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+                    section in the Yocto Project Reference Manual.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+
+<section id='yocto-project-repositories'>
+    <title>Yocto Project Source Repositories</title>
+
+    <para>
+        The Yocto Project team maintains complete source repositories for all Yocto Project files
+        at <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'></ulink>.
+        This web-based source code browser is organized into categories by function such as
+        IDE Plugins, Matchbox, Poky, Yocto Linux Kernel, and so forth.
+        From the interface, you can click on any particular item in the "Name" column and
+        see the URL at the bottom of the page that you need to clone a Git repository for
+        that particular item.
+        Having a local Git repository of the Source Directory (poky) allows you to
+        make changes, contribute to the history, and ultimately enhance the Yocto Project's
+        tools, Board Support Packages, and so forth.
+    </para>
+
+    <para>
+        Conversely, if you are a developer that is not interested in contributing back to the
+        Yocto Project, you have the ability to simply download and extract release tarballs
+        and use them within the Yocto Project environment.
+        All that is required is a particular release of the Yocto Project and
+        your application source code.
+    </para>
+
+    <para>
+        For any supported release of Yocto Project, you can go to the
+        <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink> and
+        select the "Downloads" tab and get a tarball of the release.
+        You can also go to this site to download any supported BSP tarballs.
+        Unpacking the tarball gives you a hierarchical Source Directory that lets you develop
+        using the Yocto Project.
+    </para>
+
+    <para>
+        Once you are set up through either tarball extraction or a checkout of Git repositories,
+        you are ready to develop.
+    </para>
+
+    <para>
+        In summary, here is where you can get the project files needed for development:
+        <itemizedlist>
+            <listitem><para id='source-repositories'><emphasis><ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi'>Source Repositories:</ulink></emphasis>
+                This area contains IDE Plugins, Matchbox, Poky, Poky Support, Tools, Yocto Linux Kernel, and Yocto
+                Metadata Layers.
+                You can create local copies of Git repositories for each of these areas.</para>
+                <para>
+                <imagedata fileref="figures/source-repos.png" align="center" width="6in" depth="4in" />
+                </para></listitem>
+            <listitem><para><anchor id='index-downloads' /><emphasis><ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink></emphasis>
+                This area contains index releases such as
+                the <trademark class='trade'>Eclipse</trademark>
+                Yocto Plug-in, miscellaneous support, poky, pseudo, installers for cross-development toolchains,
+                and all released versions of Yocto Project in the form of images or tarballs.
+                Downloading and extracting these files does not produce a local copy of the
+                Git repository but rather a snapshot of a particular release or image.</para>
+                <para>
+                <imagedata fileref="figures/index-downloads.png" align="center" width="6in" depth="3.5in" />
+                </para></listitem>
+            <listitem><para><emphasis>"Downloads" page for the
+                <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>:</emphasis>
+                Access this page by going to the website and then selecting
+                the "Downloads" tab.
+                This page allows you to download any Yocto Project
+                release or Board Support Package (BSP) in tarball form.
+                The tarballs are similar to those found in the
+                <ulink url='&YOCTO_DL_URL;/releases/'>Index of /releases:</ulink> area.</para>
+                <para>
+                <imagedata fileref="figures/yp-download.png" align="center" width="6in" depth="4in" />
+            </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='yocto-project-terms'>
+    <title>Yocto Project Terms</title>
+
+    <para>
+        Following is a list of terms and definitions users new to the Yocto Project development
+        environment might find helpful.
+        While some of these terms are universal, the list includes them just in case:
+        <itemizedlist>
+            <listitem><para><emphasis>Append Files:</emphasis> Files that append build information to
+                a recipe file.
+                Append files are known as BitBake append files and <filename>.bbappend</filename> files.
+                The OpenEmbedded build system expects every append file to have a corresponding
+                recipe (<filename>.bb</filename>) file.
+                Furthermore, the append file and corresponding recipe file
+                must use the same root filename.
+                The filenames can differ only in the file type suffix used (e.g.
+                <filename>formfactor_0.0.bb</filename> and <filename>formfactor_0.0.bbappend</filename>).
+                </para>
+                <para>Information in append files overrides the information in the similarly-named recipe file.
+                For an example of an append file in use, see the
+                "<link linkend='using-bbappend-files'>Using .bbappend Files</link>" section.
+                </para></listitem>
+            <listitem><para id='bitbake-term'><emphasis>BitBake:</emphasis>
+                The task executor and scheduler used by
+                the OpenEmbedded build system to build images.
+                For more information on BitBake, see the BitBake documentation
+                in the <filename>bitbake/doc/manual</filename> directory of the
+                <link linkend='source-directory'>Source Directory</link>.</para></listitem>
+            <listitem>
+                <para id='build-directory'><emphasis>Build Directory:</emphasis>
+                This term refers to the area used by the OpenEmbedded build system for builds.
+                The area is created when you <filename>source</filename> the setup
+                environment script that is found in the Source Directory
+                (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                or
+                <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>).
+                The <ulink url='&YOCTO_DOCS_REF_URL;#var-TOPDIR'><filename>TOPDIR</filename></ulink>
+                variable points to the Build Directory.</para>
+
+                <para>You have a lot of flexibility when creating the Build Directory.
+                Following are some examples that show how to create the directory:
+                   <itemizedlist>
+                        <listitem><para>Create the Build Directory in your current working directory
+                            and name it <filename>build</filename>.
+                            This is the default behavior.
+                            <literallayout class='monospaced'>
+     $ source &OE_INIT_PATH;
+                            </literallayout></para></listitem>
+                        <listitem><para>Provide a directory path and specifically name the build
+                            directory.
+                            This next example creates a Build Directory named <filename>YP-&POKYVERSION;</filename>
+                            in your home directory within the directory <filename>mybuilds</filename>.
+                            If <filename>mybuilds</filename> does not exist, the directory is created for you:
+                            <literallayout class='monospaced'>
+     $ source &OE_INIT_PATH; $HOME/mybuilds/YP-&POKYVERSION;
+                            </literallayout></para></listitem>
+                        <listitem><para>Provide an existing directory to use as the Build Directory
+                            and use the default <filename>build</filename> name.
+                            <literallayout class='monospaced'>
+     $ source &OE_INIT_PATH; $HOME/mybuilds/
+                            </literallayout></para></listitem>
+                    </itemizedlist>
+                </para></listitem>
+            <listitem><para><emphasis>Build System:</emphasis> In the context of the Yocto Project,
+                this term refers to the OpenEmbedded build system used by the project.
+                This build system is based on the project known as "Poky."
+                For some historical information about Poky, see the
+                <link linkend='poky'>Poky</link> term.
+                </para></listitem>
+            <listitem><para><emphasis>Classes:</emphasis> Files that provide for logic encapsulation
+                and inheritance so that commonly used patterns can be defined once and then easily used
+                in multiple recipes.
+                Class files end with the <filename>.bbclass</filename> filename extension.
+                </para></listitem>
+            <listitem><para><emphasis>Configuration File:</emphasis>  Configuration information in various
+                <filename>.conf</filename> files provides global definitions of variables.
+                The <filename>conf/local.conf</filename> configuration file in the
+                <link linkend='build-directory'>Build Directory</link>
+                contains user-defined variables that affect each build.
+                The <filename>meta-yocto/conf/distro/poky.conf</filename> configuration file
+                defines Yocto "distro" configuration
+                variables used only when building with this policy.
+                Machine configuration files, which
+                are located throughout the
+                <link linkend='source-directory'>Source Directory</link>, define
+                variables for specific hardware and are only used when building for that target
+                (e.g. the <filename>machine/beagleboard.conf</filename> configuration file defines
+                variables for the Texas Instruments ARM Cortex-A8 development board).
+                Configuration files end with a <filename>.conf</filename> filename extension.
+                </para></listitem>
+            <listitem><para id='cross-development-toolchain'>
+                <emphasis>Cross-Development Toolchain:</emphasis>
+                    In general, a cross-development toolchain is a collection of
+                    software development tools and utilities that run on one
+                    architecture and allow you to develop software for a
+                    different, or targeted, architecture.
+                    These toolchains contain cross-compilers, linkers, and
+                    debuggers that are specific to the target architecture.
+                </para>
+
+                <para>The Yocto Project supports two different cross-development
+                    toolchains:
+                    <itemizedlist>
+                        <listitem><para>A toolchain only used by and within
+                            BitBake when building an image for a target
+                            architecture.</para></listitem>
+                        <listitem><para>A relocatable toolchain used outside of
+                            BitBake by developers when developing applications
+                            that will run on a targeted device.
+                            Sometimes this relocatable cross-development
+                            toolchain is referred to as the meta-toolchain.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    Creation of these toolchains is simple and automated.
+                    For information on toolchain concepts as they apply to the
+                    Yocto Project, see the
+                    "<ulink url='&YOCTO_DOCS_REF_URL;#cross-development-toolchain-generation'>Cross-Development Toolchain Generation</ulink>"
+                    section in the Yocto Project Reference Manual.
+                    You can also find more information on using the
+                    relocatable toolchain in the
+                    <ulink url='&YOCTO_DOCS_ADT_URL;'>Yocto Project
+                    Application Developer's Guide</ulink>.
+                </para></listitem>
+            <listitem><para><emphasis>Image:</emphasis> An image is the result produced when
+                BitBake processes a given collection of recipes and related Metadata.
+                Images are the binary output that run on specific hardware or QEMU
+                and for specific use cases.
+                For a list of the supported image types that the Yocto Project provides, see the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+                chapter in the Yocto Project Reference Manual.</para></listitem>
+            <listitem><para id='layer'><emphasis>Layer:</emphasis> A collection of recipes representing the core,
+                a BSP, or an application stack.
+                For a discussion on BSP Layers, see the
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+                section in the Yocto Project Board Support Packages (BSP)
+                Developer's Guide.</para></listitem>
+            <listitem><para id='meta-toolchain'><emphasis>Meta-Toolchain:</emphasis>
+                A term sometimes used for
+                <link linkend='cross-development-toolchain'>Cross-Development Toolchain</link>.
+                </para></listitem>
+            <listitem><para id='metadata'><emphasis>Metadata:</emphasis>
+                The files that BitBake parses when building an image.
+                In general, Metadata includes recipes, classes, and
+                configuration files.
+                In the context of the kernel ("kernel Metadata"),
+                it refers to Metadata in the <filename>meta</filename>
+                branches of the kernel source Git repositories.
+                </para></listitem>
+            <listitem><para id='oe-core'><emphasis>OE-Core:</emphasis> A core set of Metadata originating
+                with OpenEmbedded (OE) that is shared between OE and the Yocto Project.
+                This Metadata is found in the <filename>meta</filename> directory of the
+                <link linkend='source-directory'>Source Directory</link>.</para></listitem>
+            <listitem><para><emphasis>Package:</emphasis> In the context of the Yocto Project,
+                this term refers to the packaged output from a baked recipe.
+                A package is generally the compiled binaries produced from the recipe's sources.
+                You "bake" something by running it through BitBake.</para>
+                <para>It is worth noting that the term "package" can, in general, have subtle
+                meanings.  For example, the packages referred to in the
+                "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>" section are
+                compiled binaries that when installed add functionality to your Linux
+                distribution.</para>
+                <para>Another point worth noting is that historically within the Yocto Project,
+                recipes were referred to as packages - thus, the existence of several BitBake
+                variables that are seemingly mis-named,
+                (e.g. <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PRINC'><filename>PRINC</filename></ulink>,
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>).
+                </para></listitem>
+            <listitem><para id='poky'><emphasis>Poky:</emphasis> The term "poky" can mean several things.
+                In its most general sense, it is an open-source project that was initially developed
+                by OpenedHand.  With OpenedHand, poky was developed off of the existing OpenEmbedded
+                build system becoming a build system for embedded images.
+                After Intel Corporation acquired OpenedHand, the project poky became the basis for
+                the Yocto Project's build system.
+                Within the Yocto Project source repositories, <filename>poky</filename>
+                exists as a separate Git repository
+                that can be cloned to yield a local copy on the host system.
+                Thus, "poky" can refer to the local copy of the Source Directory used to develop within
+                the Yocto Project.</para></listitem>
+            <listitem><para><emphasis>Recipe:</emphasis> A set of instructions for building packages.
+                A recipe describes where you get source code and which patches to apply.
+                Recipes describe dependencies for libraries or for other recipes, and they
+                also contain configuration and compilation options.
+                Recipes contain the logical unit of execution, the software/images to build, and
+                use the <filename>.bb</filename> file extension.</para></listitem>
+            <listitem>
+                <para id='source-directory'><emphasis>Source Directory:</emphasis>
+                This term refers to the directory structure created as a result of either downloading
+                and unpacking a Yocto Project release tarball or creating a local copy of
+                the <filename>poky</filename> Git repository
+                <filename>git://git.yoctoproject.org/poky</filename>.
+                Sometimes you might hear the term "poky directory" used to refer to this
+                directory structure.
+                <note>
+                    The OpenEmbedded build system does not support file or directory names that
+                    contain spaces.
+                    Be sure that the Source Directory you use does not contain these types
+                    of names.
+                </note></para>
+                <para>The Source Directory contains BitBake, Documentation, Metadata and
+                other files that all support the Yocto Project.
+                Consequently, you must have the Source Directory in place on your development
+                system in order to do any development using the Yocto Project.</para>
+
+                <para>For tarball expansion, the name of the top-level directory of the Source Directory
+                is derived from the Yocto Project release tarball.
+                For example, downloading and unpacking <filename>&YOCTO_POKY_TARBALL;</filename>
+                results in a Source Directory whose top-level folder is named
+                <filename>&YOCTO_POKY;</filename>.
+                If you create a local copy of the Git repository, you can name the repository
+                anything you like.
+                Throughout much of the documentation, <filename>poky</filename> is used as the name of
+                the top-level folder of the local copy of the poky Git repository.
+                So, for example, cloning the <filename>poky</filename> Git repository results in a
+                local Git repository whose top-level folder is also named <filename>poky</filename>.</para>
+
+                <para>It is important to understand the differences between the Source Directory created
+                by unpacking a released tarball as compared to cloning
+                <filename>git://git.yoctoproject.org/poky</filename>.
+                When you unpack a tarball, you have an exact copy of the files based on the time of
+                release - a fixed release point.
+                Any changes you make to your local files in the Source Directory are on top of the release.
+                On the other hand, when you clone the <filename>poky</filename> Git repository, you have an
+                active development repository.
+                In this case, any local changes you make to the Source Directory can be later applied
+                to active development branches of the upstream <filename>poky</filename> Git
+                repository.</para>
+
+                <para>Finally, if you want to track a set of local changes while starting from the same point
+                as a release tarball, you can create a local Git branch that
+                reflects the exact copy of the files at the time of their release.
+                You do this by using Git tags that are part of the repository.</para>
+
+                <para>For more information on concepts related to Git repositories, branches, and tags,
+                see the
+                "<link linkend='repositories-tags-and-branches'>Repositories, Tags, and Branches</link>"
+                section.</para></listitem>
+            <listitem><para><emphasis>Tasks:</emphasis> Arbitrary groups of software Recipes.
+                You use tasks to hold recipes that, when built, usually accomplish a single task.
+                For example, a task could contain the recipes for a company’s proprietary or value-add software.
+                Or, the task could contain the recipes that enable graphics.
+                A task is really just another recipe.
+                Because task files are recipes, they end with the <filename>.bb</filename> filename
+                extension.</para></listitem>
+            <listitem><para><emphasis>Upstream:</emphasis> A reference to source code or repositories
+                that are not local to the development system but located in a master area that is controlled
+                by the maintainer of the source code.
+                For example, in order for a developer to work on a particular piece of code, they need to
+                first get a copy of it from an "upstream" source.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='licensing'>
+    <title>Licensing</title>
+
+    <para>
+        Because open source projects are open to the public, they have different licensing structures in place.
+        License evolution for both Open Source and Free Software has an interesting history.
+        If you are interested in this history, you can find basic information here:
+    <itemizedlist>
+        <listitem><para><ulink url='http://en.wikipedia.org/wiki/Open-source_license'>Open source license history</ulink>
+            </para></listitem>
+        <listitem><para><ulink url='http://en.wikipedia.org/wiki/Free_software_license'>Free software license
+            history</ulink></para></listitem>
+    </itemizedlist>
+    </para>
+
+    <para>
+        In general, the Yocto Project is broadly licensed under the Massachusetts Institute of Technology
+        (MIT) License.
+        MIT licensing permits the reuse of software within proprietary software as long as the
+        license is distributed with that software.
+        MIT is also compatible with the GNU General Public License (GPL).
+        Patches to the Yocto Project follow the upstream licensing scheme.
+        You can find information on the MIT license at
+        <ulink url='http://www.opensource.org/licenses/mit-license.php'>here</ulink>.
+        You can find information on the GNU GPL <ulink url='http://www.opensource.org/licenses/LGPL-3.0'>
+        here</ulink>.
+    </para>
+
+    <para>
+        When you build an image using the Yocto Project, the build process uses a
+        known list of licenses to ensure compliance.
+        You can find this list in the
+        <link linkend='source-directory'>Source Directory</link> at
+        <filename>meta/files/common-licenses</filename>.
+        Once the build completes, the list of all licenses found and used during that build are
+        kept in the
+        <link linkend='build-directory'>Build Directory</link> at
+        <filename>tmp/deploy/licenses</filename>.
+    </para>
+
+    <para>
+        If a module requires a license that is not in the base list, the build process
+        generates a warning during the build.
+        These tools make it easier for a developer to be certain of the licenses with which
+        their shipped products must comply.
+        However, even with these tools it is still up to the developer to resolve potential licensing issues.
+    </para>
+
+    <para>
+        The base list of licenses used by the build process is a combination of the Software Package
+        Data Exchange (SPDX) list and the Open Source Initiative (OSI) projects.
+        <ulink url='http://spdx.org'>SPDX Group</ulink> is a working group of the Linux Foundation
+        that maintains a specification
+        for a standard format for communicating the components, licenses, and copyrights
+        associated with a software package.
+        <ulink url='http://opensource.org'>OSI</ulink> is a corporation dedicated to the Open Source
+        Definition and the effort for reviewing and approving licenses that are OSD-conformant.
+    </para>
+
+    <para>
+        You can find a list of the combined SPDX and OSI licenses that the Yocto Project uses
+        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/files/common-licenses'>here</ulink>.
+    </para>
+
+    <para>
+        For information that can help you to maintain compliance with various open source licensing
+        during the lifecycle of a product created using the Yocto Project, see the
+        "<link linkend='maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</link>" section.
+    </para>
+</section>
+
+<section id='git'>
+    <title>Git</title>
+
+    <para>
+        The Yocto Project uses Git, which is a free, open source distributed version control system.
+        Git supports distributed development, non-linear development, and can handle large projects.
+        It is best that you have some fundamental understanding of how Git tracks projects and
+        how to work with Git if you are going to use the Yocto Project for development.
+        This section provides a quick overview of how Git works and provides you with a summary
+        of some essential Git commands.
+    </para>
+
+    <para>
+        For more information on Git, see
+        <ulink url='http://git-scm.com/documentation'></ulink>.
+        If you need to download Git, go to <ulink url='http://git-scm.com/download'></ulink>.
+    </para>
+
+    <section id='repositories-tags-and-branches'>
+        <title>Repositories, Tags, and Branches</title>
+
+        <para>
+            As mentioned earlier in the section
+            "<link linkend='yocto-project-repositories'>Yocto Project Source Repositories</link>",
+            the Yocto Project maintains source repositories at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
+            If you look at this web-interface of the repositories, each item is a separate
+            Git repository.
+        </para>
+
+        <para>
+            Git repositories use branching techniques that track content change (not files)
+            within a project (e.g. a new feature or updated documentation).
+            Creating a tree-like structure based on project divergence allows for excellent historical
+            information over the life of a project.
+            This methodology also allows for an environment from which you can do lots of
+            local experimentation on projects as you develop changes or new features.
+        </para>
+
+        <para>
+            A Git repository represents all development efforts for a given project.
+            For example, the Git repository <filename>poky</filename> contains all changes
+            and developments for Poky over the course of its entire life.
+            That means that all changes that make up all releases are captured.
+            The repository maintains a complete history of changes.
+        </para>
+
+        <para>
+            You can create a local copy of any repository by "cloning" it with the Git
+            <filename>clone</filename> command.
+            When you clone a Git repository, you end up with an identical copy of the
+            repository on your development system.
+            Once you have a local copy of a repository, you can take steps to develop locally.
+            For examples on how to clone Git repositories, see the
+            "<link linkend='getting-setup'>Getting Set Up</link>" section.
+        </para>
+
+        <para>
+            It is important to understand that Git tracks content change and not files.
+            Git uses "branches" to organize different development efforts.
+            For example, the <filename>poky</filename> repository has
+            <filename>denzil</filename>, <filename>danny</filename>,
+            <filename>dylan</filename>, <filename>dora</filename>,
+            and <filename>master</filename> branches among others.
+            You can see all the branches by going to
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
+            clicking on the
+            <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/heads'>[...]</ulink></filename>
+            link beneath the "Branch" heading.
+        </para>
+
+        <para>
+            Each of these branches represents a specific area of development.
+            The <filename>master</filename> branch represents the current or most recent
+            development.
+            All other branches represent off-shoots of the <filename>master</filename>
+            branch.
+        </para>
+
+        <para>
+            When you create a local copy of a Git repository, the copy has the same set
+            of branches as the original.
+            This means you can use Git to create a local working area (also called a branch)
+            that tracks a specific development branch from the source Git repository.
+            in other words, you can define your local Git environment to work on any development
+            branch in the repository.
+            To help illustrate, here is a set of commands that creates a local copy of the
+            <filename>poky</filename> Git repository and then creates and checks out a local
+            Git branch that tracks the Yocto Project &DISTRO; Release (&DISTRO_NAME;) development:
+            <literallayout class='monospaced'>
+     $ cd ~
+     $ git clone git://git.yoctoproject.org/poky
+     $ cd poky
+     $ git checkout -b &DISTRO_NAME; origin/&DISTRO_NAME;
+            </literallayout>
+            In this example, the name of the top-level directory of your local
+            <link linkend='source-directory'>Source Directory</link>
+            is <filename>poky</filename>,
+            and the name of that local working area (local branch) you just
+            created and checked out is <filename>&DISTRO_NAME;</filename>.
+            The files in your local repository now reflect the same files that
+            are in the <filename>&DISTRO_NAME;</filename> development
+            branch of the Yocto Project's <filename>poky</filename>
+            upstream repository.
+            It is important to understand that when you create and checkout a
+            local working branch based on a branch name,
+            your local environment matches the "tip" of that development branch
+            at the time you created your local branch, which could be
+            different than the files at the time of a similarly named release.
+            In other words, creating and checking out a local branch based on the
+            <filename>&DISTRO_NAME;</filename> branch name is not the same as
+            cloning and checking out the <filename>master</filename> branch.
+            Keep reading to see how you create a local snapshot of a Yocto Project Release.
+        </para>
+
+        <para>
+            Git uses "tags" to mark specific changes in a repository.
+            Typically, a tag is used to mark a special point such as the final change
+            before a project is released.
+            You can see the tags used with the <filename>poky</filename> Git repository
+            by going to <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/'></ulink> and
+            clicking on the
+            <filename><ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/refs/tags'>[...]</ulink></filename>
+            link beneath the "Tag" heading.
+        </para>
+
+        <para>
+            Some key tags are <filename>bernard-5.0</filename>, <filename>denzil-7.0</filename>,
+            and <filename>&DISTRO_NAME;-&POKYVERSION;</filename>.
+            These tags represent Yocto Project releases.
+        </para>
+
+        <para>
+            When you create a local copy of the Git repository, you also have access to all the
+            tags.
+            Similar to branches, you can create and checkout a local working Git branch based
+            on a tag name.
+            When you do this, you get a snapshot of the Git repository that reflects
+            the state of the files when the change was made associated with that tag.
+            The most common use is to checkout a working branch that matches a specific
+            Yocto Project release.
+            Here is an example:
+            <literallayout class='monospaced'>
+     $ cd ~
+     $ git clone git://git.yoctoproject.org/poky
+     $ cd poky
+     $ git checkout -b my-&DISTRO_NAME;-&POKYVERSION; &DISTRO_NAME;-&POKYVERSION;
+            </literallayout>
+            In this example, the name of the top-level directory of your local Yocto Project
+            Files Git repository is <filename>poky</filename>.
+            And, the name of the local branch you have created and checked out is
+            <filename>my-&DISTRO_NAME;-&POKYVERSION;</filename>.
+            The files in your repository now exactly match the Yocto Project &DISTRO;
+            Release tag (<filename>&DISTRO_NAME;-&POKYVERSION;</filename>).
+            It is important to understand that when you create and checkout a local
+            working branch based on a tag, your environment matches a specific point
+            in time and not the entire development branch.
+        </para>
+    </section>
+
+    <section id='basic-commands'>
+        <title>Basic Commands</title>
+
+        <para>
+            Git has an extensive set of commands that lets you manage changes and perform
+            collaboration over the life of a project.
+            Conveniently though, you can manage with a small set of basic operations and workflows
+            once you understand the basic philosophy behind Git.
+            You do not have to be an expert in Git to be functional.
+            A good place to look for instruction on a minimal set of Git commands is
+            <ulink url='http://git-scm.com/documentation'>here</ulink>.
+            If you need to download Git, you can do so
+            <ulink url='http://git-scm.com/download'>here</ulink>.
+        </para>
+
+        <para>
+            If you don’t know much about Git, you should educate
+            yourself by visiting the links previously mentioned.
+        </para>
+
+        <para>
+            The following list briefly describes some basic Git operations as a way to get started.
+            As with any set of commands, this list (in most cases) simply shows the base command and
+            omits the many arguments they support.
+            See the Git documentation for complete descriptions and strategies on how to use these commands:
+            <itemizedlist>
+                <listitem><para><emphasis><filename>git init</filename>:</emphasis> Initializes an empty Git repository.
+                    You cannot use Git commands unless you have a <filename>.git</filename> repository.</para></listitem>
+                <listitem><para><emphasis><filename>git clone</filename>:</emphasis> Creates a clone of a repository.
+                    During collaboration, this command allows you to create a local repository that is on
+                    equal footing with a fellow developer’s repository.</para></listitem>
+                <listitem><para><emphasis><filename>git add</filename>:</emphasis> Stages updated file contents
+                    to the index that
+                    Git uses to track changes.
+                    You must stage all files that have changed before you can commit them.</para></listitem>
+                <listitem><para><emphasis><filename>git commit</filename>:</emphasis> Creates a "commit" that documents
+                    the changes you made.
+                    Commits are used for historical purposes, for determining if a maintainer of a project
+                    will allow the change, and for ultimately pushing the change from your local Git repository
+                    into the project’s upstream (or master) repository.</para></listitem>
+                <listitem><para><emphasis><filename>git status</filename>:</emphasis> Reports any modified files that
+                    possibly need staged and committed.</para></listitem>
+                <listitem><para><emphasis><filename>git checkout &lt;branch-name&gt;</filename>:</emphasis> Changes
+                    your working branch.
+                    This command is analogous to "cd".</para></listitem>
+                <listitem><para><emphasis><filename>git checkout –b &lt;working-branch&gt;</filename>:</emphasis> Creates
+                    a working branch on your local machine where you can isolate work.
+                    It is a good idea to use local branches when adding specific features or changes.
+                    This way if you do not like what you have done you can easily get rid of the work.</para></listitem>
+                <listitem><para><emphasis><filename>git branch</filename>:</emphasis> Reports
+                    existing local branches and
+                    tells you the branch in which you are currently working.</para></listitem>
+                <listitem><para><emphasis><filename>git branch -D &lt;branch-name&gt;</filename>:</emphasis>
+                    Deletes an existing local branch.
+                    You need to be in a local branch other than the one you are deleting
+                    in order to delete <filename>&lt;branch-name&gt;</filename>.</para></listitem>
+                <listitem><para><emphasis><filename>git pull</filename>:</emphasis> Retrieves information
+                    from an upstream Git
+                    repository and places it in your local Git repository.
+                    You use this command to make sure you are synchronized with the repository
+                    from which you are basing changes (.e.g. the master branch).</para></listitem>
+                <listitem><para><emphasis><filename>git push</filename>:</emphasis>
+                    Sends all your committed local changes to an upstream Git
+                    repository (e.g. a contribution repository).
+                    The maintainer of the project draws from these repositories
+                    when adding changes to the project’s master repository or
+                    other development branch.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>git merge</filename>:</emphasis> Combines or adds changes from one
+                    local branch of your repository with another branch.
+                    When you create a local Git repository, the default branch is named "master".
+                    A typical workflow is to create a temporary branch for isolated work, make and commit your
+                    changes, switch to your local master branch, merge the changes from the temporary branch into the
+                    local master branch, and then delete the temporary branch.</para></listitem>
+                <listitem><para><emphasis><filename>git cherry-pick</filename>:</emphasis> Choose and apply specific
+                    commits from one branch into another branch.
+                    There are times when you might not be able to merge all the changes in one branch with
+                    another but need to pick out certain ones.</para></listitem>
+                <listitem><para><emphasis><filename>gitk</filename>:</emphasis> Provides a GUI view of the branches
+                    and changes in your local Git repository.
+                    This command is a good way to graphically see where things have diverged in your
+                    local repository.</para></listitem>
+                <listitem><para><emphasis><filename>git log</filename>:</emphasis> Reports a history of your changes to the
+                    repository.</para></listitem>
+                <listitem><para><emphasis><filename>git diff</filename>:</emphasis> Displays line-by-line differences
+                    between your local working files and the same files in the upstream Git repository that your
+                    branch currently tracks.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+
+<section id='workflows'>
+    <title>Workflows</title>
+
+    <para>
+        This section provides some overview on workflows using Git.
+        In particular, the information covers basic practices that describe roles and actions in a
+        collaborative development environment.
+        Again, if you are familiar with this type of development environment, you might want to just
+        skip this section.
+    </para>
+
+    <para>
+        The Yocto Project files are maintained using Git in a "master" branch whose Git history
+        tracks every change and whose structure provides branches for all diverging functionality.
+        Although there is no need to use Git, many open source projects do so.
+        For the Yocto Project, a key individual called the "maintainer" is responsible for the "master"
+        branch of a given Git repository.
+        The "master" branch is the “upstream” repository where the final builds of the project occur.
+        The maintainer is responsible for allowing changes in from other developers and for
+        organizing the underlying branch structure to reflect release strategies and so forth.
+        <note>For information on finding out who is responsible (maintains)
+            for a particular area of code, see the
+            "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
+            section.
+        </note>
+    </para>
+
+    <para>
+        The project also has contribution repositories known as "contrib" areas.
+        These areas temporarily hold changes to the project that have been submitted or committed
+        by the Yocto Project development team and by community members that contribute to the project.
+        The maintainer determines if the changes are qualified to be moved from the "contrib" areas
+        into the "master" branch of the Git repository.
+    </para>
+
+    <para>
+        Developers (including contributing community members) create and maintain cloned repositories
+        of the upstream "master" branch.
+        These repositories are local to their development platforms and are used to develop changes.
+        When a developer is satisfied with a particular feature or change, they "push" the changes
+        to the appropriate "contrib" repository.
+    </para>
+
+    <para>
+        Developers are responsible for keeping their local repository up-to-date with "master".
+        They are also responsible for straightening out any conflicts that might arise within files
+        that are being worked on simultaneously by more than one person.
+        All this work is done locally on the developer’s machines before anything is pushed to a
+        "contrib" area and examined at the maintainer’s level.
+    </para>
+
+    <para>
+        A somewhat formal method exists by which developers commit changes and push them into the
+        "contrib" area and subsequently request that the maintainer include them into "master"
+        This process is called “submitting a patch” or "submitting a change."
+        For information on submitting patches and changes, see the
+        "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" section.
+    </para>
+
+    <para>
+        To summarize the environment:  we have a single point of entry for changes into the project’s
+        "master" branch of the Git repository, which is controlled by the project’s maintainer.
+        And, we have a set of developers who independently develop, test, and submit changes
+        to "contrib" areas for the maintainer to examine.
+        The maintainer then chooses which changes are going to become a permanent part of the project.
+    </para>
+
+    <para>
+        <imagedata fileref="figures/git-workflow.png" width="6in" depth="3in" align="left" scalefit="1" />
+    </para>
+
+    <para>
+        While each development environment is unique, there are some best practices or methods
+        that help development run smoothly.
+        The following list describes some of these practices.
+        For more information about Git workflows, see the workflow topics in the
+        <ulink url='http://book.git-scm.com'>Git Community Book</ulink>.
+        <itemizedlist>
+            <listitem><para><emphasis>Make Small Changes:</emphasis> It is best to keep the changes you commit
+                small as compared to bundling many disparate changes into a single commit.
+                This practice not only keeps things manageable but also allows the maintainer
+                to more easily include or refuse changes.</para>
+                <para>It is also good practice to leave the repository in a state that allows you to
+                still successfully build your project.  In other words, do not commit half of a feature,
+                then add the other half as a separate, later commit.
+                Each commit should take you from one buildable project state to another
+                buildable state.</para></listitem>
+            <listitem><para><emphasis>Use Branches Liberally:</emphasis> It is very easy to create, use, and
+                delete local branches in your working Git repository.
+                You can name these branches anything you like.
+                It is helpful to give them names associated with the particular feature or change
+                on which you are working.
+                Once you are done with a feature or change and have merged it
+                into your local master branch, simply discard the temporary
+                branch.</para></listitem>
+            <listitem><para><emphasis>Merge Changes:</emphasis> The <filename>git merge</filename>
+                command allows you to take the
+                changes from one branch and fold them into another branch.
+                This process is especially helpful when more than a single developer might be working
+                on different parts of the same feature.
+                Merging changes also automatically identifies any collisions or "conflicts"
+                that might happen as a result of the same lines of code being altered by two different
+                developers.</para></listitem>
+            <listitem><para><emphasis>Manage Branches:</emphasis> Because branches are easy to use, you should
+                use a system where branches indicate varying levels of code readiness.
+                For example, you can have a "work" branch to develop in, a "test" branch where the code or
+                change is tested, a "stage" branch where changes are ready to be committed, and so forth.
+                As your project develops, you can merge code across the branches to reflect ever-increasing
+                stable states of the development.</para></listitem>
+            <listitem><para><emphasis>Use Push and Pull:</emphasis> The push-pull workflow is based on the
+                concept of developers "pushing" local commits to a remote repository, which is
+                usually a contribution repository.
+                This workflow is also based on developers "pulling" known states of the project down into their
+                local development repositories.
+                The workflow easily allows you to pull changes submitted by other developers from the
+                upstream repository into your work area ensuring that you have the most recent software
+                on which to develop.
+                The Yocto Project has two scripts named <filename>create-pull-request</filename> and
+                <filename>send-pull-request</filename> that ship with the release to facilitate this
+                workflow.
+                You can find these scripts in the <filename>scripts</filename>
+                folder of the
+                <link linkend='source-directory'>Source Directory</link>.
+                For information on how to use these scripts, see the
+                "<link linkend='pushing-a-change-upstream'>Using Scripts to Push a Change Upstream and Request a Pull</link>" section.
+                </para></listitem>
+            <listitem><para><emphasis>Patch Workflow:</emphasis> This workflow allows you to notify the
+                maintainer through an email that you have a change (or patch) you would like considered
+                for the "master" branch of the Git repository.
+                To send this type of change, you format the patch and then send the email using the Git commands
+                <filename>git format-patch</filename> and <filename>git send-email</filename>.
+                For information on how to use these scripts, see the
+                "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
+                section.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='tracking-bugs'>
+    <title>Tracking Bugs</title>
+
+    <para>
+        The Yocto Project uses its own implementation of
+        <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs.
+        Implementations of Bugzilla work well for group development because they track bugs and code
+        changes, can be used to communicate changes and problems with developers, can be used to
+        submit and review patches, and can be used to manage quality assurance.
+        The home page for the Yocto Project implementation of Bugzilla is
+        <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.
+    </para>
+
+    <para>
+        Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
+        such as when discovering an issue with some component of the build system that acts contrary
+        to the documentation or your expectations.
+        Following is the general procedure for submitting a new bug using the Yocto Project
+        Bugzilla.
+        You can find more information on defect management, bug tracking, and feature request
+        processes all accomplished through the Yocto Project Bugzilla on the wiki page
+        <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>here</ulink>.
+        <orderedlist>
+            <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit
+                a bug.</para></listitem>
+            <listitem><para>When submitting a new bug, be sure to choose the appropriate
+                Classification, Product, and Component for which the issue was found.
+                Defects for the Yocto Project fall into one of six classifications:  Yocto Project
+                Components, Infrastructure, Build System &amp; Metadata, Documentation,
+                QA/Testing, and Runtime.
+                Each of these Classifications break down into multiple Products and, in some
+                cases, multiple Components.</para></listitem>
+            <listitem><para>Use the bug form to choose the correct Hardware and Architecture
+                for which the bug applies.</para></listitem>
+            <listitem><para>Indicate the Yocto Project version you were using when the issue
+                occurred.</para></listitem>
+            <listitem><para>Be sure to indicate the Severity of the bug.
+                Severity communicates how the bug impacted your work.</para></listitem>
+            <listitem><para>Select the appropriate "Documentation change" item
+                for the bug.
+                Fixing a bug may or may not affect the Yocto Project
+                documentation.</para></listitem>
+            <listitem><para>Provide a brief summary of the issue.
+                Try to limit your summary to just a line or two and be sure to capture the
+                essence of the issue.</para></listitem>
+            <listitem><para>Provide a detailed description of the issue.
+                You should provide as much detail as you can about the context, behavior, output,
+                and so forth that surrounds the issue.
+                You can even attach supporting files for output from logs by
+                using the "Add an attachment" button.</para></listitem>
+            <listitem><para>Be sure to copy the appropriate people in the
+                "CC List" for the bug.
+                See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
+                section for information about finding out who is responsible
+                for code.</para></listitem>
+            <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
+<section id='how-to-submit-a-change'>
+    <title>How to Submit a Change</title>
+
+    <para>
+        Contributions to the Yocto Project and OpenEmbedded are very welcome.
+        Because the system is extremely configurable and flexible, we recognize that developers
+        will want to extend, configure or optimize it for their specific uses.
+        You should send patches to the appropriate mailing list so that they
+        can be reviewed and merged by the appropriate maintainer.
+    </para>
+
+    <para>
+        Before submitting any change, be sure to find out who you should be
+        notifying.
+        Several methods exist through which you find out who you should be copying
+        or notifying:
+        <itemizedlist>
+            <listitem><para><emphasis>Maintenance File:</emphasis>
+                Examine the <filename>maintainers.inc</filename> file, which is
+                located in the
+                <link linkend='source-directory'>Source Directory</link>
+                at <filename>meta-yocto/conf/distro/include</filename>, to
+                see who is responsible for code.
+                </para></listitem>
+            <listitem><para><emphasis>Board Support Package (BSP) README Files:</emphasis>
+                For BSP maintainers of supported BSPs, you can examine
+                individual BSP <filename>README</filename> files.
+                Alternatively, you can examine the
+                <filename>MAINTAINERS</filename> file, which is found in the
+                <filename>meta-intel</filename>, for a list of all supported
+                BSP maintainers.
+                </para></listitem>
+            <listitem><para><emphasis>Search by File:</emphasis>
+                Using <link linkend='git'>Git</link>, you can enter the
+                following command to bring up a short list of all commits
+                against a specific file:
+                <literallayout class='monospaced'>
+     git shortlog -- &lt;filename&gt;
+                </literallayout>
+                Just provide the name of the file for which you are interested.
+                The information returned is not ordered by history but does
+                include a list of all committers grouped by name.
+                From the list, you can see who is responsible for the bulk of
+                the changes against the file.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        For a list of the Yocto Project and related mailing lists, see the
+        "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
+        the Yocto Project Reference Manual.
+    </para>
+
+    <para>
+        Here is some guidance on which mailing list to use for what type of change:
+        <itemizedlist>
+            <listitem><para>For changes to the core
+                <link linkend='metadata'>Metadata</link>, send your patch to the
+                <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
+                For example, a change to anything under the <filename>meta</filename> or
+                <filename>scripts</filename> directories
+                should be sent to this mailing list.</para></listitem>
+            <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
+                directory), send your patch to the
+                <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
+            <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
+                <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
+            <listitem><para>For changes to other layers hosted on
+                <filename>yoctoproject.org</filename> (unless the
+                layer's documentation specifies otherwise), tools, and Yocto Project
+                documentation, use the
+                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
+            <listitem><para>For additional recipes that do not fit into the core Metadata,
+                you should determine which layer the recipe should go into and submit the
+                change in the manner recommended by the documentation (e.g. README) supplied
+                with the layer. If in doubt, please ask on the
+                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
+                <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
+                mailing lists.</para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        When you send a patch, be sure to include a "Signed-off-by:"
+        line in the same style as required by the Linux kernel.
+        Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
+        as follows:
+        <literallayout class='monospaced'>
+     Developer's Certificate of Origin 1.1
+
+     By making a contribution to this project, I certify that:
+
+     (a) The contribution was created in whole or in part by me and I
+         have the right to submit it under the open source license
+         indicated in the file; or
+
+     (b) The contribution is based upon previous work that, to the best
+         of my knowledge, is covered under an appropriate open source
+         license and I have the right under that license to submit that
+         work with modifications, whether created in whole or in part
+         by me, under the same open source license (unless I am
+         permitted to submit under a different license), as indicated
+         in the file; or
+
+     (c) The contribution was provided directly to me by some other
+         person who certified (a), (b) or (c) and I have not modified
+         it.
+
+     (d) I understand and agree that this project and the contribution
+         are public and that a record of the contribution (including all
+         personal information I submit with it, including my sign-off) is
+         maintained indefinitely and may be redistributed consistent with
+         this project or the open source license(s) involved.
+        </literallayout>
+    </para>
+
+    <para>
+        In a collaborative environment, it is necessary to have some sort of standard
+        or method through which you submit changes.
+        Otherwise, things could get quite chaotic.
+        One general practice to follow is to make small, controlled changes.
+        Keeping changes small and isolated aids review, makes merging/rebasing easier
+        and keeps the change history clean when anyone needs to refer to it in future.
+    </para>
+
+    <para>
+        When you make a commit, you must follow certain standards established by the
+        OpenEmbedded and Yocto Project development teams.
+        For each commit, you must provide a single-line summary of the change and you
+        should almost always provide a more detailed description of what you did (i.e.
+        the body of the commit message).
+        The only exceptions for not providing a detailed description would be if your
+        change is a simple, self-explanatory change that needs no further description
+        beyond the summary.
+        Here are the guidelines for composing a commit message:
+        <itemizedlist>
+            <listitem><para>Provide a single-line, short summary of the change.
+                This summary is typically viewable in the "shortlist" of changes.
+                Thus, providing something short and descriptive that gives the reader
+                a summary of the change is useful when viewing a list of many commits.
+                This short description should be prefixed by the recipe name (if changing a recipe), or
+                else the short form path to the file being changed.
+                </para></listitem>
+            <listitem><para>For the body of the commit message, provide detailed information
+                that describes what you changed, why you made the change, and the approach
+                you used. It may also be helpful if you mention how you tested the change.
+                Provide as much detail as you can in the body of the commit message.
+                </para></listitem>
+            <listitem><para>If the change addresses a specific bug or issue that is
+                associated with a bug-tracking ID, include a reference to that ID in
+                your detailed description.
+                For example, the Yocto Project uses a specific convention for bug
+                references - any commit that addresses a specific bug should include the
+                bug ID in the description (typically at the beginning) as follows:
+                <literallayout class='monospaced'>
+     [YOCTO #&lt;bug-id&gt;]
+
+     &lt;detailed description of change&gt;
+                </literallayout></para></listitem>
+                Where &lt;bug-id&gt; is replaced with the specific bug ID from the
+                Yocto Project Bugzilla instance.
+        </itemizedlist>
+    </para>
+
+    <para>
+        You can find more guidance on creating well-formed commit messages at this OpenEmbedded
+        wiki page:
+        <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
+    </para>
+
+    <para>
+        The next two sections describe general instructions for both pushing
+        changes upstream and for submitting changes as patches.
+    </para>
+
+    <section id='pushing-a-change-upstream'>
+        <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
+
+        <para>
+            The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
+            <itemizedlist>
+                <listitem><para>Make your changes in your local Git repository.</para></listitem>
+                <listitem><para>Stage your changes by using the <filename>git add</filename>
+                    command on each file you changed.</para></listitem>
+                <listitem><para>Commit the change by using the <filename>git commit</filename>
+                    command and push it to the "contrib" repository.
+                    Be sure to provide a commit message that follows the project’s commit message standards
+                    as described earlier.</para></listitem>
+                <listitem><para>Notify the maintainer that you have pushed a change by making a pull
+                    request.
+                    The Yocto Project provides two scripts that conveniently let you generate and send
+                    pull requests to the Yocto Project.
+                    These scripts are <filename>create-pull-request</filename> and
+                    <filename>send-pull-request</filename>.
+                    You can find these scripts in the <filename>scripts</filename> directory
+                    within the <link linkend='source-directory'>Source Directory</link>.</para>
+                    <para>Using these scripts correctly formats the requests without introducing any
+                    whitespace or HTML formatting.
+                    The maintainer that receives your patches needs to be able to save and apply them
+                    directly from your emails.
+                    Using these scripts is the preferred method for sending patches.</para>
+                    <para>For help on using these scripts, simply provide the
+                    <filename>-h</filename> argument as follows:
+                    <literallayout class='monospaced'>
+     $ ~/poky/scripts/create-pull-request -h
+     $ ~/poky/scripts/send-pull-request -h
+                    </literallayout></para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            You can find general Git information on how to push a change upstream in the
+            <ulink url='http://book.git-scm.com/3_distributed_workflows.html'>Git Community Book</ulink>.
+        </para>
+    </section>
+
+    <section id='submitting-a-patch'>
+        <title>Using Email to Submit a Patch</title>
+
+        <para>
+            You can submit patches without using the <filename>create-pull-request</filename> and
+            <filename>send-pull-request</filename> scripts described in the previous section.
+            However, keep in mind, the preferred method is to use the scripts.
+        </para>
+
+        <para>
+            Depending on the components changed, you need to submit the email to a specific
+            mailing list.
+            For some guidance on which mailing list to use, see the list in the
+            "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
+            section.
+            For a description of the available mailing lists, see the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
+            section in the Yocto Project Reference Manual.
+        </para>
+
+        <para>
+            Here is the general procedure on how to submit a patch through email without using the
+            scripts:
+            <itemizedlist>
+                <listitem><para>Make your changes in your local Git repository.</para></listitem>
+                <listitem><para>Stage your changes by using the <filename>git add</filename>
+                    command on each file you changed.</para></listitem>
+                <listitem><para>Commit the change by using the
+                    <filename>git commit --signoff</filename> command.
+                    Using the <filename>--signoff</filename> option identifies you as the person
+                    making the change and also satisfies the Developer's Certificate of
+                    Origin (DCO) shown earlier.</para>
+                    <para>When you form a commit, you must follow certain standards established by the
+                    Yocto Project development team.
+                    See the earlier section
+                    "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
+                    for Yocto Project commit message standards.</para></listitem>
+                <listitem><para>Format the commit into an email message.
+                    To format commits, use the <filename>git format-patch</filename> command.
+                    When you provide the command, you must include a revision list or a number of patches
+                    as part of the command.
+                    For example, either of these two commands takes your most
+                    recent single commit and formats it as an email message in
+                    the current directory:
+                    <literallayout class='monospaced'>
+     $ git format-patch -1
+                    </literallayout>
+                    or
+                    <literallayout class='monospaced'>
+     $ git format-patch HEAD~
+                    </literallayout></para>
+                    <para>After the command is run, the current directory contains a
+                    numbered <filename>.patch</filename> file for the commit.</para>
+                    <para>If you provide several commits as part of the command,
+                    the <filename>git format-patch</filename> command produces a
+                    series of numbered files in the current directory – one for each commit.
+                    If you have more than one patch, you should also use the
+                    <filename>--cover</filename> option with the command, which generates a
+                    cover letter as the first "patch" in the series.
+                    You can then edit the cover letter to provide a description for
+                    the series of patches.
+                    For information on the <filename>git format-patch</filename> command,
+                    see <filename>GIT_FORMAT_PATCH(1)</filename> displayed using the
+                    <filename>man git-format-patch</filename> command.</para>
+                    <note>If you are or will be a frequent contributor to the Yocto Project
+                    or to OpenEmbedded, you might consider requesting a contrib area and the
+                    necessary associated rights.</note></listitem>
+                <listitem><para>Import the files into your mail client by using the
+                    <filename>git send-email</filename> command.
+                    <note>In order to use <filename>git send-email</filename>, you must have the
+                    the proper Git packages installed.
+                    For Ubuntu, Debian, and Fedora the package is <filename>git-email</filename>.</note></para>
+                    <para>The <filename>git send-email</filename> command sends email by using a local
+                    or remote Mail Transport Agent (MTA) such as
+                    <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
+                    <filename>smtp</filename> configuration in your Git <filename>config</filename>
+                    file.
+                    If you are submitting patches through email only, it is very important
+                    that you submit them without any whitespace or HTML formatting that
+                    either you or your mailer introduces.
+                    The maintainer that receives your patches needs to be able to save and
+                    apply them directly from your emails.
+                    A good way to verify that what you are sending will be applicable by the
+                    maintainer is to do a dry run and send them to yourself and then
+                    save and apply them as the maintainer would.</para>
+                    <para>The <filename>git send-email</filename> command is the preferred method
+                    for sending your patches since there is no risk of compromising whitespace
+                    in the body of the message, which can occur when you use your own mail client.
+                    The command also has several options that let you
+                    specify recipients and perform further editing of the email message.
+                    For information on how to use the <filename>git send-email</filename> command,
+                    see <filename>GIT-SEND-EMAIL(1)</filename> displayed using
+                    the <filename>man git-send-email</filename> command.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml
new file mode 100644
index 0000000000..0729baa0da
--- /dev/null
+++ b/documentation/dev-manual/dev-manual-start.xml
@@ -0,0 +1,407 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='dev-manual-start'>
+
+<title>Getting Started with the Yocto Project</title>
+
+<para>
+    This chapter introduces the Yocto Project and gives you an idea of what you need to get started.
+    You can find enough information to set up your development host and build or use images for
+    hardware supported by the Yocto Project by reading the
+    <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+</para>
+
+<para>
+    The remainder of this chapter summarizes what is in the Yocto Project Quick Start and provides
+    some higher-level concepts you might want to consider.
+</para>
+
+<section id='introducing-the-yocto-project'>
+    <title>Introducing the Yocto Project</title>
+
+    <para>
+        The Yocto Project is an open-source collaboration project focused on embedded Linux development.
+        The project currently provides a build system that is
+        referred to as the OpenEmbedded build system in the Yocto Project documentation.
+        The Yocto Project provides various ancillary tools for the embedded developer
+        and also features the Sato reference User Interface, which is optimized for
+        stylus driven, low-resolution screens.
+    </para>
+
+    <para>
+        You can use the OpenEmbedded build system, which uses
+        BitBake, to develop complete Linux
+        images and associated user-space applications for architectures based
+        on ARM, MIPS, PowerPC, x86 and x86-64.
+        <note>
+            By default, using the Yocto Project creates a Poky distribution.
+            However, you can create your own distribution by providing key
+            <link linkend='metadata'>Metadata</link>.
+            See the "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
+            section for more information.
+        </note>
+        While the Yocto Project does not provide a strict testing framework,
+        it does provide or generate for you artifacts that let you perform target-level and
+        emulated testing and debugging.
+        Additionally, if you are an <trademark class='trade'>Eclipse</trademark>
+        IDE user, you can install an Eclipse Yocto Plug-in to allow you to
+        develop within that familiar environment.
+    </para>
+</section>
+
+<section id='getting-setup'>
+    <title>Getting Set Up</title>
+
+    <para>
+        Here is what you need to get set up to use the Yocto Project:
+        <itemizedlist>
+            <listitem><para><emphasis>Host System:</emphasis>  You should have a reasonably current
+                Linux-based host system.
+                You will have the best results with a recent release of Fedora,
+                OpenSUSE, Debian, Ubuntu, or CentOS as these releases are frequently tested against the Yocto Project
+                and officially supported.
+                For a list of the distributions under validation and their status, see the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
+                in the Yocto Project Reference Manual and the wiki page at
+                <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>.</para>
+                <para>
+                You should also have about 100 gigabytes of free disk space for building images.
+                </para></listitem>
+            <listitem><para><emphasis>Packages:</emphasis>  The OpenEmbedded build system
+                requires certain packages exist on your development system (e.g. Python 2.6 or 2.7).
+                See "<ulink url='&YOCTO_DOCS_QS_URL;#packages'>The Packages</ulink>"
+                section in the Yocto Project Quick Start and the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
+                section in the Yocto Project Reference Manual for the exact
+                package requirements and the installation commands to install
+                them for the supported distributions.
+                </para></listitem>
+            <listitem id='local-yp-release'><para><emphasis>Yocto Project Release:</emphasis>
+                You need a release of the Yocto Project.
+                You set that up with a local <link linkend='source-directory'>Source Directory</link>
+                one of two ways depending on whether you
+                are going to contribute back into the Yocto Project or not.
+                <note>
+                    Regardless of the method you use, this manual refers to the resulting local
+                    hierarchical set of files as the "Source Directory."
+                </note>
+                <itemizedlist>
+                    <listitem><para><emphasis>Tarball Extraction:</emphasis>
+                        If you are not going to contribute back into the Yocto
+                        Project, you can simply go to the
+                        <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>,
+                        select the "Downloads" tab, and choose what you want.
+                        Once you have the tarball, just extract it into a
+                        directory of your choice.</para>
+                        <para>For example, the following command extracts the
+                        Yocto Project &DISTRO; release tarball
+                        into the current working directory and sets up the local Source Directory
+                        with a top-level folder named <filename>&YOCTO_POKY;</filename>:
+                        <literallayout class='monospaced'>
+     $ tar xfj &YOCTO_POKY_TARBALL;
+                        </literallayout></para>
+                        <para>This method does not produce a local Git repository.
+                        Instead, you simply end up with a snapshot of the release.</para></listitem>
+                    <listitem><para><emphasis>Git Repository Method:</emphasis>  If you are going to be contributing
+                        back into the Yocto Project or you simply want to keep up
+                        with the latest developments, you should use Git commands to set up a local
+                        Git repository of the upstream <filename>poky</filename> source repository.
+                        Doing so creates a repository with a complete history of changes and allows
+                        you to easily submit your changes upstream to the project.
+                        Because you clone the repository, you have access to all the Yocto Project development
+                        branches and tag names used in the upstream repository.</para>
+                        <note>You can view the Yocto Project Source Repositories at
+                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink></note>
+                        <para>The following transcript shows how to clone the <filename>poky</filename>
+                        Git repository into the current working directory.
+                        The command creates the local repository in a directory named <filename>poky</filename>.
+                        For information on Git used within the Yocto Project, see the
+                        "<link linkend='git'>Git</link>" section.
+                        <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky
+     Cloning into 'poky'...
+     remote: Counting objects: 203728, done.
+     remote: Compressing objects: 100% (52371/52371), done.
+     remote: Total 203728 (delta 147444), reused 202891 (delta 146614)
+     Receiving objects: 100% (203728/203728), 95.54 MiB | 308 KiB/s, done.
+     Resolving deltas: 100% (147444/147444), done.
+                        </literallayout></para>
+                        <para>For another example of how to set up your own local Git repositories, see this
+                        <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>
+                        wiki page</ulink>, which describes how to create both <filename>poky</filename>
+                        and <filename>meta-intel</filename> Git repositories.</para></listitem>
+                </itemizedlist></para></listitem>
+            <listitem id='local-kernel-files'><para><emphasis>Yocto Project Kernel:</emphasis>
+                If you are going to be making modifications to a supported Yocto Project kernel, you
+                need to establish local copies of the source.
+                You can find Git repositories of supported Yocto Project Kernels organized under
+                "Yocto Linux Kernel" in the Yocto Project Source Repositories at
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
+                <para>This setup can involve creating a bare clone of the Yocto Project kernel and then
+                copying that cloned repository.
+                You can create the bare clone and the copy of the bare clone anywhere you like.
+                For simplicity, it is recommended that you create these structures outside of the
+                Source Directory (usually <filename>poky</filename>).</para>
+                <para>As an example, the following transcript shows how to create the bare clone
+                of the <filename>linux-yocto-3.10</filename> kernel and then create a copy of
+                that clone.
+                <note>When you have a local Yocto Project kernel Git repository, you can
+                reference that repository rather than the upstream Git repository as
+                part of the <filename>clone</filename> command.
+                Doing so can speed up the process.</note></para>
+                <para>In the following example, the bare clone is named
+                <filename>linux-yocto-3.10.git</filename>, while the
+                copy is named <filename>my-linux-yocto-3.10-work</filename>:
+                <literallayout class='monospaced'>
+     $ git clone --bare git://git.yoctoproject.org/linux-yocto-3.10 linux-yocto-3.10.git
+     Cloning into bare repository 'linux-yocto-3.10.git'...
+     remote: Counting objects: 3364487, done.
+     remote: Compressing objects: 100% (507178/507178), done.
+     remote: Total 3364487 (delta 2827715), reused 3364481 (delta 2827709)
+     Receiving objects: 100% (3364487/3364487), 722.95 MiB | 423 KiB/s, done.
+     Resolving deltas: 100% (2827715/2827715), done.
+                </literallayout></para>
+                <para>Now create a clone of the bare clone just created:
+                <literallayout class='monospaced'>
+     $ git clone linux-yocto-3.10.git my-linux-yocto-3.10-work
+     Cloning into 'my-linux-yocto-3.10-work'...
+     done.
+                </literallayout></para></listitem>
+            <listitem id='meta-yocto-kernel-extras-repo'><para><emphasis>
+                The <filename>meta-yocto-kernel-extras</filename> Git Repository</emphasis>:
+                The <filename>meta-yocto-kernel-extras</filename> Git repository contains Metadata needed
+                only if you are modifying and building the kernel image.
+                In particular, it contains the kernel BitBake append (<filename>.bbappend</filename>)
+                files that you
+                edit to point to your locally modified kernel source files and to build the kernel
+                image.
+                Pointing to these local files is much more efficient than requiring a download of the
+                kernel's source files from upstream each time you make changes to the kernel.</para>
+                <para>You can find the <filename>meta-yocto-kernel-extras</filename> Git Repository in the
+                "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.
+                It is good practice to create this Git repository inside the Source Directory.</para>
+                <para>Following is an example that creates the <filename>meta-yocto-kernel-extras</filename> Git
+                repository inside the Source Directory, which is named <filename>poky</filename>
+                in this case:
+                <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ git clone git://git.yoctoproject.org/meta-yocto-kernel-extras meta-yocto-kernel-extras
+     Cloning into 'meta-yocto-kernel-extras'...
+     remote: Counting objects: 727, done.
+     remote: Compressing objects: 100% (452/452), done.
+     remote: Total 727 (delta 260), reused 719 (delta 252)
+     Receiving objects: 100% (727/727), 536.36 KiB | 102 KiB/s, done.
+     Resolving deltas: 100% (260/260), done.
+               </literallayout></para></listitem>
+           <listitem><para id='supported-board-support-packages-(bsps)'><emphasis>Supported Board
+                Support Packages (BSPs):</emphasis>
+                The Yocto Project provides a layer called <filename>meta-intel</filename> and
+                it is maintained in its own separate Git repository.
+                The <filename>meta-intel</filename> layer contains many supported
+                <ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>.</para>
+                <para>Similar considerations exist for setting up the <filename>meta-intel</filename>
+                layer.
+                You can get set up for BSP development one of two ways: tarball extraction or
+                with a local Git repository.
+                It is a good idea to use the same method that you used to set up the Source Directory.
+                Regardless of the method you use, the Yocto Project uses the following BSP layer
+                naming scheme:
+                <literallayout class='monospaced'>
+     meta-&lt;BSP_name&gt;
+                </literallayout>
+                where <filename>&lt;BSP_name&gt;</filename> is the recognized BSP name.
+                Here are some examples:
+                <literallayout class='monospaced'>
+     meta-crownbay
+     meta-emenlow
+     meta-n450
+                </literallayout>
+                See the
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-layers'>BSP Layers</ulink>"
+                section in the Yocto Project Board Support Package (BSP) Developer's Guide for more
+                information on BSP Layers.
+                <itemizedlist>
+                    <listitem><para><emphasis>Tarball Extraction:</emphasis>  You can download any released
+                        BSP tarball from the same "Downloads" page of the
+                        <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+                        to get the Yocto Project release.
+                        Once on the "Download" page, look to the right of the
+                        page and scroll down to find the BSP tarballs.</para>
+                        <para>Once you have the tarball, just extract it into a directory of your choice.
+                        Again, this method just produces a snapshot of the BSP layer in the form
+                        of a hierarchical directory structure.</para></listitem>
+                    <listitem><para><emphasis>Git Repository Method:</emphasis>  If you are working
+                        with a local Git repository for your Source Directory, you should also use this method
+                        to set up the <filename>meta-intel</filename> Git repository.
+                        You can locate the <filename>meta-intel</filename> Git repository in the
+                        "Yocto Metadata Layers" area of the Yocto Project Source Repositories at
+                        <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink>.</para>
+                        <para>Typically, you set up the <filename>meta-intel</filename> Git repository inside
+                        the Source Directory.
+                        For example, the following transcript shows the steps to clone the
+                        <filename>meta-intel</filename>
+                        Git repository inside the local <filename>poky</filename> Git repository.
+                        <literallayout class='monospaced'>
+     $ cd ~/poky
+     $ git clone git://git.yoctoproject.org/meta-intel.git
+     Cloning into 'meta-intel'...
+     remote: Counting objects: 7366, done.
+     remote: Compressing objects: 100% (2491/2491), done.
+     remote: Total 7366 (delta 3997), reused 7299 (delta 3930)
+     Receiving objects: 100% (7366/7366), 2.31 MiB | 95 KiB/s, done.
+     Resolving deltas: 100% (3997/3997), done.
+                        </literallayout></para>
+                        <para>The same
+                        <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_from_git_checkout_to_meta-intel_BSP'>wiki page</ulink>
+                        referenced earlier covers how to
+                        set up the <filename>meta-intel</filename> Git repository.
+                        </para></listitem>
+                </itemizedlist></para></listitem>
+            <listitem><para><emphasis>Eclipse Yocto Plug-in:</emphasis>  If you are developing
+                applications using the Eclipse Integrated Development Environment (IDE),
+                you will need this plug-in.
+                See the
+                "<link linkend='setting-up-the-eclipse-ide'>Setting up the Eclipse IDE</link>"
+                section for more information.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='building-images'>
+    <title>Building Images</title>
+
+    <para>
+        The build process creates an entire Linux distribution, including the toolchain, from source.
+        For more information on this topic, see the
+        "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+        section in the Yocto Project Quick Start.
+    </para>
+
+    <para>
+        The build process is as follows:
+        <orderedlist>
+            <listitem><para>Make sure you have set up the Source Directory described in the
+                previous section.</para></listitem>
+            <listitem><para>Initialize the build environment by sourcing a build environment
+                script.</para></listitem>
+            <listitem><para>Optionally ensure the <filename>conf/local.conf</filename> configuration file,
+                which is found in the
+                <link linkend='build-directory'>Build Directory</link>,
+                is set up how you want it.
+                This file defines many aspects of the build environment including
+                the target machine architecture through the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'>MACHINE</ulink></filename> variable,
+                the development machine's processor use through the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</ulink></filename> and
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'>PARALLEL_MAKE</ulink></filename> variables, and
+                a centralized tarball download directory through the
+                <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable.</para></listitem>
+            <listitem><para>Build the image using the <filename>bitbake</filename> command.
+                If you want information on BitBake, see the user manual included in the
+                <filename>bitbake/doc/manual</filename> directory of the
+                <link linkend='source-directory'>Source Directory</link>.</para></listitem>
+            <listitem><para>Run the image either on the actual hardware or using the QEMU
+                emulator.</para></listitem>
+        </orderedlist>
+    </para>
+</section>
+
+<section id='using-pre-built-binaries-and-qemu'>
+    <title>Using Pre-Built Binaries and QEMU</title>
+
+    <para>
+        Another option you have to get started is to use pre-built binaries.
+        The Yocto Project provides many types of binaries with each release.
+        See the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>"
+        chapter in the Yocto Project Reference Manual
+        for descriptions of the types of binaries that ship with a Yocto Project
+        release.
+    </para>
+
+    <para>
+        Using a pre-built binary is ideal for developing software applications to run on your
+        target hardware.
+        To do this, you need to be able to access the appropriate cross-toolchain tarball for
+        the architecture on which you are developing.
+        If you are using an SDK type image, the image ships with the complete toolchain native to
+        the architecture.
+        If you are not using an SDK type image, you need to separately download and
+        install the stand-alone Yocto Project cross-toolchain tarball.
+    </para>
+
+    <para>
+        Regardless of the type of image you are using, you need to download the pre-built kernel
+        that you will boot in the QEMU emulator and then download and extract the target root
+        filesystem for your target machine’s architecture.
+        You can get architecture-specific binaries and file systems from
+        <ulink url='&YOCTO_MACHINES_DL_URL;'>machines</ulink>.
+        You can get installation scripts for stand-alone toolchains from
+        <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'>toolchains</ulink>.
+        Once you have all your files, you set up the environment to emulate the hardware
+        by sourcing an environment setup script.
+        Finally, you start the QEMU emulator.
+        You can find details on all these steps in the
+        "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
+        section of the Yocto Project Quick Start.
+    </para>
+
+    <para>
+        Using QEMU to emulate your hardware can result in speed issues
+        depending on the target and host architecture mix.
+        For example, using the <filename>qemux86</filename> image in the emulator
+        on an Intel-based 32-bit (x86) host machine is fast because the target and
+        host architectures match.
+        On the other hand, using the <filename>qemuarm</filename> image on the same Intel-based
+        host can be slower.
+        But, you still achieve faithful emulation of ARM-specific issues.
+    </para>
+
+    <para>
+        To speed things up, the QEMU images support using <filename>distcc</filename>
+        to call a cross-compiler outside the emulated system.
+        If you used <filename>runqemu</filename> to start QEMU, and the
+        <filename>distccd</filename> application is present on the host system, any
+        BitBake cross-compiling toolchain available from the build system is automatically
+        used from within QEMU simply by calling <filename>distcc</filename>.
+        You can accomplish this by defining the cross-compiler variable
+        (e.g. <filename>export CC="distcc"</filename>).
+        Alternatively, if you are using a suitable SDK image or the appropriate
+        stand-alone toolchain is present,
+        the toolchain is also automatically used.
+    </para>
+
+    <note>
+        Several mechanisms exist that let you connect to the system running on the
+        QEMU emulator:
+        <itemizedlist>
+            <listitem><para>QEMU provides a framebuffer interface that makes standard
+                consoles available.</para></listitem>
+            <listitem><para>Generally, headless embedded devices have a serial port.
+                If so, you can configure the operating system of the running image
+                to use that port to run a console.
+                The connection uses standard IP networking.</para></listitem>
+            <listitem><para>SSH servers exist in some QEMU images.
+                The <filename>core-image-sato</filename> QEMU image has a Dropbear secure
+                shell (SSH) server that runs with the root password disabled.
+                The <filename>core-image-basic</filename> and <filename>core-image-lsb</filename> QEMU images
+                have OpenSSH instead of Dropbear.
+                Including these SSH servers allow you to use standard <filename>ssh</filename> and
+                <filename>scp</filename> commands.
+                The <filename>core-image-minimal</filename> QEMU image, however, contains no SSH
+                server.</para></listitem>
+            <listitem><para>You can use a provided, user-space NFS server to boot the QEMU session
+                using a local copy of the root filesystem on the host.
+                In order to make this connection, you must extract a root filesystem tarball by using the
+                <filename>runqemu-extract-sdk</filename> command.
+                After running the command, you must then point the <filename>runqemu</filename>
+                script to the extracted directory instead of a root filesystem image file.</para></listitem>
+        </itemizedlist>
+    </note>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/dev-manual/dev-manual.xml b/documentation/dev-manual/dev-manual.xml
new file mode 100644
index 0000000000..ca400fbd18
--- /dev/null
+++ b/documentation/dev-manual/dev-manual.xml
@@ -0,0 +1,102 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='dev-manual' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='figures/dev-title.png'
+                    format='SVG'
+                    align='left' scalefit='1' width='100%'/>
+            </imageobject>
+        </mediaobject>
+
+        <title>
+            Yocto Project Development Manual
+        </title>
+
+        <authorgroup>
+            <author>
+                <firstname>Scott</firstname> <surname>Rifenbark</surname>
+                <affiliation>
+                    <orgname>Intel Corporation</orgname>
+                </affiliation>
+                <email>scott.m.rifenbark@intel.com</email>
+            </author>
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>1.1</revnumber>
+                <date>6 October 2011</date>
+                <revremark>The initial document released with the Yocto Project 1.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.2</revnumber>
+                <date>April 2012</date>
+                <revremark>Released with the Yocto Project 1.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.3</revnumber>
+                <date>October 2012</date>
+                <revremark>Released with the Yocto Project 1.3 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>April 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5</revnumber>
+                <date>October 2013</date>
+                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5.1</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
+            </revision>
+        </revhistory>
+
+    <copyright>
+     <year>&COPYRIGHT_YEAR;</year>
+      <holder>Linux Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+          Permission is granted to copy, distribute and/or modify this document under
+          the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
+          Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
+          Creative Commons.
+      </para>
+
+      <note>
+          For the latest version of this manual associated with this
+          Yocto Project release, see the
+          <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
+          from the Yocto Project website.
+      </note>
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="dev-manual-intro.xml"/>
+
+    <xi:include href="dev-manual-start.xml"/>
+
+    <xi:include href="dev-manual-newbie.xml"/>
+
+    <xi:include href="dev-manual-model.xml"/>
+
+    <xi:include href="dev-manual-common-tasks.xml"/>
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/dev-manual/dev-style.css b/documentation/dev-manual/dev-style.css
new file mode 100644
index 0000000000..23c8e74c1e
--- /dev/null
+++ b/documentation/dev-manual/dev-style.css
@@ -0,0 +1,979 @@
+/* 
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+   
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+ 
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("figures/dev-title.png");
+  background-position: left top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 0px;
+  text-align: right;
+  width: 740px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+  
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+} 
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption, 
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;  
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+  
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2; 
+}
+
+.glossary dl dt, 
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title, 
+div.colophon .title, 
+div.chapter .titlepage .title,
+div.article .titlepage .title 
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/yocto-project-bw.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2; 
+   color: #333;   
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;   
+}
+
+.tip a,
+.note a {
+   color: #333;   
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
+
diff --git a/documentation/dev-manual/figures/app-dev-flow.png b/documentation/dev-manual/figures/app-dev-flow.png
new file mode 100644
index 0000000000..ec93374ee7
--- /dev/null
+++ b/documentation/dev-manual/figures/app-dev-flow.png
diff --git a/documentation/dev-manual/figures/bsp-dev-flow.png b/documentation/dev-manual/figures/bsp-dev-flow.png
new file mode 100644
index 0000000000..1ccd9c3e3b
--- /dev/null
+++ b/documentation/dev-manual/figures/bsp-dev-flow.png
diff --git a/documentation/dev-manual/figures/dev-title.png b/documentation/dev-manual/figures/dev-title.png
new file mode 100644
index 0000000000..d3cac4a7e5
--- /dev/null
+++ b/documentation/dev-manual/figures/dev-title.png
diff --git a/documentation/dev-manual/figures/git-workflow.png b/documentation/dev-manual/figures/git-workflow.png
new file mode 100644
index 0000000000..4fdf42f89c
--- /dev/null
+++ b/documentation/dev-manual/figures/git-workflow.png
diff --git a/documentation/dev-manual/figures/index-downloads.png b/documentation/dev-manual/figures/index-downloads.png
new file mode 100644
index 0000000000..41251d5d18
--- /dev/null
+++ b/documentation/dev-manual/figures/index-downloads.png
diff --git a/documentation/dev-manual/figures/kernel-dev-flow.png b/documentation/dev-manual/figures/kernel-dev-flow.png
new file mode 100644
index 0000000000..edd9e82af7
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-dev-flow.png
diff --git a/documentation/dev-manual/figures/kernel-overview-1.png b/documentation/dev-manual/figures/kernel-overview-1.png
new file mode 100644
index 0000000000..116c0b9bd4
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-overview-1.png
diff --git a/documentation/dev-manual/figures/kernel-overview-2-generic.png b/documentation/dev-manual/figures/kernel-overview-2-generic.png
new file mode 100644
index 0000000000..889ff1bf0d
--- /dev/null
+++ b/documentation/dev-manual/figures/kernel-overview-2-generic.png
diff --git a/documentation/dev-manual/figures/source-repos.png b/documentation/dev-manual/figures/source-repos.png
new file mode 100644
index 0000000000..65c5f29a43
--- /dev/null
+++ b/documentation/dev-manual/figures/source-repos.png
diff --git a/documentation/dev-manual/figures/yp-download.png b/documentation/dev-manual/figures/yp-download.png
new file mode 100644
index 0000000000..7f1e5ca118
--- /dev/null
+++ b/documentation/dev-manual/figures/yp-download.png
diff --git a/documentation/kernel-dev/figures/kernel-architecture-overview.png b/documentation/kernel-dev/figures/kernel-architecture-overview.png
new file mode 100755
index 0000000000..2aad172db3
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-architecture-overview.png
diff --git a/documentation/kernel-dev/figures/kernel-dev-title.png b/documentation/kernel-dev/figures/kernel-dev-title.png
new file mode 100644
index 0000000000..7a8dd54372
--- /dev/null
+++ b/documentation/kernel-dev/figures/kernel-dev-title.png
diff --git a/documentation/kernel-dev/kernel-dev-advanced.xml b/documentation/kernel-dev/kernel-dev-advanced.xml
new file mode 100644
index 0000000000..4589e4b9fc
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-advanced.xml
@@ -0,0 +1,1071 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-advanced'>
+<title>Working with Advanced Metadata</title>
+
+<section id='kernel-dev-advanced-overview'>
+    <title>Overview</title>
+
+    <para>
+        In addition to supporting configuration fragments and patches, the
+        Yocto Project kernel tools also support rich
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> that you can
+        use to define complex policies and Board Support Package (BSP) support.
+        The purpose of the Metadata and the tools that manage it, known as
+        the kern-tools (<filename>kern-tools-native_git.bb</filename>), is
+        to help you manage the complexity of the configuration and sources
+        used to support multiple BSPs and Linux kernel types.
+    </para>
+</section>
+
+<section id='using-kernel-metadata-in-a-recipe'>
+    <title>Using Kernel Metadata in a Recipe</title>
+
+    <para>
+        The kernel sources in the Yocto Project contain kernel Metadata, which is
+        located in the <filename>meta</filename> branches of the kernel source
+        Git repositories.
+        This Metadata defines Board Support Packages (BSPs) that
+        correspond to definitions in linux-yocto recipes for the same BSPs.
+        A BSP consists of an aggregation of kernel policy and hardware-specific
+        feature enablements.
+        The BSP can be influenced from within the linux-yocto recipe.
+        <note>
+            Linux kernel source that contains kernel Metadata is said to be
+            "linux-yocto style" kernel source.
+            A Linux kernel recipe that inherits from the
+            <filename>linux-yocto.inc</filename> include file is said to be a
+            "linux-yocto style" recipe.
+        </note>
+    </para>
+
+    <para>
+        Every linux-yocto style recipe must define the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>
+        variable.
+        This variable is typically set to the same value as the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+        variable, which is used by BitBake (e.g. "routerstationpro" or "fri2").
+        Multiple BSPs can reuse the same <filename>KMACHINE</filename>
+        name if they are built using the same BSP description.
+        The "fri2" and "fri2-noemgd" BSP combination
+        in the <filename>meta-intel</filename>
+        layer is a good example of two BSPs using the same
+        <filename>KMACHINE</filename> value (i.e. "fri2").
+        See the <link linkend='bsp-descriptions'>BSP Descriptions</link> section
+        for more information.
+    </para>
+
+    <para>
+        The linux-yocto style recipes can optionally define the following
+        variables:
+        <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH'>KBRANCH</ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'>KERNEL_FEATURES</ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-KBRANCH_DEFAULT'>KBRANCH_DEFAULT</ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</ulink>
+        </literallayout>
+        <filename>KBRANCH_DEFAULT</filename> defines the Linux kernel source
+        repository's default branch to use to build the Linux kernel.
+        The value is used as the default for <filename>KBRANCH</filename>, which
+        can define an alternate branch typically with a machine override as
+        follows:
+        <literallayout class='monospaced'>
+     KBRANCH_fri2 = "standard/fri2"
+        </literallayout>
+        Unless you specify otherwise, <filename>KBRANCH_DEFAULT</filename>
+        initializes to "master".
+    </para>
+
+    <para>
+        <filename>LINUX_KERNEL_TYPE</filename> defines the kernel type to be
+        used in assembling the configuration.
+        If you do not specify a <filename>LINUX_KERNEL_TYPE</filename>,
+        it defaults to "standard".
+        Together with
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
+        <filename>LINUX_KERNEL_TYPE</filename> defines the search
+        arguments used by the kernel tools to find the
+        appropriate description within the kernel Metadata with which to
+        build out the sources and configuration.
+        The linux-yocto recipes define "standard", "tiny", and "preempt-rt"
+        kernel types.
+        See the <link linkend='kernel-types'>Kernel Types</link> section
+        for more information on kernel types.
+    </para>
+
+    <para>
+        During the build, the kern-tools search for the BSP description
+        file that most closely matches the <filename>KMACHINE</filename>
+        and <filename>LINUX_KERNEL_TYPE</filename> variables passed in from the
+        recipe.
+        The tools use the first BSP description it finds that match
+        both variables.
+        If the tools cannot find a match, they issue a warning such as
+        the following:
+        <literallayout class='monospaced'>
+     WARNING: Can't find any BSP hardware or required configuration fragments.
+     WARNING: Looked at meta/cfg/broken/fri2-broken/hdw_frags.txt and
+              meta/cfg/broken/fri2-broken/required_frags.txt in directory:
+              meta/cfg/broken/fri2-broken
+        </literallayout>
+        In this example, <filename>KMACHINE</filename> was set to "fri2-broken"
+        and <filename>LINUX_KERNEL_TYPE</filename> was set to "broken".
+    </para>
+
+    <para>
+        The tools first search for the <filename>KMACHINE</filename> and
+        then for the <filename>LINUX_KERNEL_TYPE</filename>.
+        If the tools cannot find a partial match, they will use the
+        sources from the <filename>KBRANCH</filename> and any configuration
+        specified in the
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
+    </para>
+
+    <para>
+        You can use the <filename>KERNEL_FEATURES</filename> variable
+        to include features (configuration fragments, patches, or both) that
+        are not already included by the <filename>KMACHINE</filename> and
+        <filename>LINUX_KERNEL_TYPE</filename> variable combination.
+        For example, to include a feature specified as "features/netfilter.scc",
+        specify:
+        <literallayout class='monospaced'>
+     KERNEL_FEATURES += "features/netfilter.scc"
+        </literallayout>
+        To include a feature called "cfg/sound.scc" just for the
+        <filename>qemux86</filename> machine, specify:
+        <literallayout class='monospaced'>
+     KERNEL_FEATURES_append_qemux86 = "cfg/sound.scc"
+        </literallayout>
+        The value of the entries in <filename>KERNEL_FEATURES</filename>
+        are dependent on their location within the kernel Metadata itself.
+        The examples here are taken from the
+        <filename>linux-yocto-3.4</filename> repository where "features"
+        and "cfg" are subdirectories within the
+        <filename>meta/cfg/kernel-cache</filename> directory.
+        For more information, see the
+        "<link linkend='kernel-metadata-syntax'>Kernel Metadata Syntax</link>" section.
+        <note>
+            The processing of the these variables has evolved some between the
+                0.9 and 1.3 releases of the Yocto Project and associated
+                kern-tools sources.
+            The descriptions in this section are accurate for 1.3 and later
+                releases of the Yocto Project.
+        </note>
+    </para>
+</section>
+
+<section id='kernel-metadata-location'>
+    <title>Kernel Metadata Location</title>
+
+    <para>
+        Kernel Metadata can be defined in either the kernel recipe
+        (recipe-space) or in the kernel tree (in-tree).
+        Where you choose to define the Metadata depends on what you want
+        to do and how you intend to work.
+        Regardless of where you define the kernel Metadata, the syntax used
+        applies equally.
+    </para>
+
+    <para>
+        If you are unfamiliar with the Linux kernel and only wish
+        to apply a configuration and possibly a couple of patches provided to
+        you by others, the recipe-space method is recommended.
+        This method is also a good approach if you are working with Linux kernel
+        sources you do not control or if you just do not want to maintain a
+        Linux kernel Git repository on your own.
+        For partial information on how you can define kernel Metadata in
+        the recipe-space, see the
+        "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
+        section.
+    </para>
+
+    <para>
+        Conversely, if you are actively developing a kernel and are already
+        maintaining a Linux kernel Git repository of your own, you might find
+        it more convenient to work with the kernel Metadata in the same
+        repository as the Linux kernel sources.
+        This method can make iterative development of the Linux kernel
+        more efficient outside of the BitBake environment.
+    </para>
+
+    <section id='recipe-space-metadata'>
+        <title>Recipe-Space Metadata</title>
+
+        <para>
+            When stored in recipe-space, the kernel Metadata files reside in a
+            directory hierarchy below
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>.
+            For a linux-yocto recipe or for a Linux kernel recipe derived
+            by copying and modifying
+            <filename>oe-core/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb</filename>
+            to a recipe in your layer, <filename>FILESEXTRAPATHS</filename>
+            is typically set to
+            <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>.
+            See the "<link linkend='modifying-an-existing-recipe'>Modifying an Existing Recipe</link>"
+            section for more information.
+        </para>
+
+        <para>
+            Here is an example that shows a trivial tree of kernel Metadata
+            stored in recipe-space within a BSP layer:
+            <literallayout class='monospaced'>
+     meta-my_bsp_layer/
+     `-- recipes-kernel
+         `-- linux
+             `-- linux-yocto
+                 |-- bsp-standard.scc
+                 |-- bsp.cfg
+                 `-- standard.cfg
+            </literallayout>
+        </para>
+
+        <para>
+            When the Metadata is stored in recipe-space, you must take
+            steps to ensure BitBake has the necessary information to decide
+            what files to fetch and when they need to be fetched again.
+            It is only necessary to specify the <filename>.scc</filename>
+            files on the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
+            BitBake parses them and fetches any files referenced in the
+            <filename>.scc</filename> files by the <filename>include</filename>,
+            <filename>patch</filename>, or <filename>kconf</filename> commands.
+            Because of this, it is necessary to bump the recipe
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
+            value when changing the content of files not explicitly listed
+            in the <filename>SRC_URI</filename>.
+        </para>
+    </section>
+
+    <section id='in-tree-metadata'>
+        <title>In-Tree Metadata</title>
+
+        <para>
+            When stored in-tree, the kernel Metadata files reside in the
+            <filename>meta</filename> directory of the Linux kernel sources.
+            The <filename>meta</filename> directory can be present in the
+            same repository branch as the sources,
+            such as "master", or <filename>meta</filename> can be its own
+            orphan branch.
+            <note>
+                An orphan branch in Git is a branch with unique history and
+                content to the other branches in the repository.
+                Orphan branches are useful to track Metadata changes
+                independently from the sources of the Linux kernel, while
+                still keeping them together in the same repository.
+            </note>
+            For the purposes of this document, we will discuss all
+            in-tree Metadata as residing below the
+            <filename>meta/cfg/kernel-cache</filename> directory.
+        </para>
+
+        <para>
+            Following is an example that shows how a trivial tree of Metadata
+            is stored in a custom Linux kernel Git repository:
+            <literallayout class='monospaced'>
+     meta/
+     `-- cfg
+         `-- kernel-cache
+             |-- bsp-standard.scc
+             |-- bsp.cfg
+             `-- standard.cfg
+            </literallayout>
+        </para>
+
+        <para>
+            To use a branch different from where the sources reside,
+            specify the branch in the <filename>KMETA</filename> variable
+            in your Linux kernel recipe.
+            Here is an example:
+            <literallayout class='monospaced'>
+     KMETA = "meta"
+            </literallayout>
+            To use the same branch as the sources, set
+            <filename>KMETA</filename> to an empty string:
+            <literallayout class='monospaced'>
+     KMETA = ""
+            </literallayout>
+            If you are working with your own sources and want to create an
+            orphan <filename>meta</filename> branch, use these commands
+            from within your Linux kernel Git repository:
+            <literallayout class='monospaced'>
+     $ git checkout --orphan meta
+     $ git rm -rf .
+     $ git commit --allow-empty -m "Create orphan meta branch"
+            </literallayout>
+        </para>
+
+        <para>
+            If you modify the Metadata in the linux-yocto 
+            <filename>meta</filename> branch, you must not forget to update 
+            the 
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
+            statements in the kernel's recipe.
+            In particular, you need to update the 
+            <filename>SRCREV_meta</filename> variable to match the commit in 
+            the <filename>KMETA</filename> branch you wish to use.
+            Changing the data in these branches and not updating the 
+            <filename>SRCREV</filename> statements to match will cause the 
+            build to fetch an older commit.
+        </para>
+    </section>
+</section>
+
+<section id='kernel-metadata-syntax'>
+    <title>Kernel Metadata Syntax</title>
+
+    <para>
+        The kernel Metadata consists of three primary types of files:
+        <filename>scc</filename>
+        <footnote>
+            <para>
+                <filename>scc</filename> stands for Series Configuration
+                Control, but the naming has less significance in the
+                current implementation of the tooling than it had in the
+                past.
+                Consider <filename>scc</filename> files to be description files.
+            </para>
+        </footnote>
+        description files, configuration fragments, and patches.
+        The <filename>scc</filename> files define variables and include or
+        otherwise reference any of the three file types.
+        The description files are used to aggregate all types of kernel
+        Metadata into
+        what ultimately describes the sources and the configuration required
+        to build a Linux kernel tailored to a specific machine.
+    </para>
+
+    <para>
+        The <filename>scc</filename> description files are used to define two
+        fundamental types of kernel Metadata:
+        <itemizedlist>
+            <listitem><para>Features</para></listitem>
+            <listitem><para>Board Support Packages (BSPs)</para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        Features aggregate sources in the form of patches and configuration
+        fragments into a modular reusable unit.
+        You can use features to implement conceptually separate kernel
+        Metadata descriptions such as pure configuration fragments,
+        simple patches, complex features, and kernel types.
+        <link linkend='kernel-types'>Kernel types</link> define general
+        kernel features and policy to be reused in the BSPs.
+    </para>
+
+    <para>
+        BSPs define hardware-specific features and aggregate them with kernel
+        types to form the final description of what will be assembled and built.
+    </para>
+
+    <para>
+        While the kernel Metadata syntax does not enforce any logical
+        separation of configuration fragments, patches, features or kernel
+        types, best practices dictate a logical separation of these types
+        of Metadata.
+        The following Metadata file hierarchy is recommended:
+        <literallayout class='monospaced'>
+     &lt;base&gt;/
+        bsp/
+        cfg/
+        features/
+        ktypes/
+        patches/
+        </literallayout>
+    </para>
+
+    <para>
+        The <filename>bsp</filename> directory contains the
+        <link linkend='bsp-descriptions'>BSP descriptions</link>.
+        The remaining directories all contain "features".
+        Separating <filename>bsp</filename> from the rest of the structure
+        aids conceptualizing intended usage.
+    </para>
+
+    <para>
+        Use these guidelines to help place your <filename>scc</filename>
+        description files within the structure:
+        <itemizedlist>
+            <listitem><para>If your file contains
+                only configuration fragments, place the file in the
+                <filename>cfg</filename> directory.</para></listitem>
+            <listitem><para>If your file contains
+                only source-code fixes, place the file in the
+                <filename>patches</filename> directory.</para></listitem>
+            <listitem><para>If your file encapsulates
+                a major feature, often combining sources and configurations,
+                place the file in <filename>features</filename> directory.
+                </para></listitem>
+            <listitem><para>If your file aggregates
+                non-hardware configuration and patches in order to define a
+                base kernel policy or major kernel type to be reused across
+                multiple BSPs, place the file in <filename>ktypes</filename>
+                directory.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        These distinctions can easily become blurred - especially as
+        out-of-tree features slowly merge upstream over time.
+        Also, remember that how the description files are placed is
+        a purely logical organization and has no impact on the functionality
+        of the kernel Metadata.
+        There is no impact because all of <filename>cfg</filename>,
+        <filename>features</filename>, <filename>patches</filename>, and
+        <filename>ktypes</filename>, contain "features" as far as the kernel
+        tools are concerned.
+    </para>
+
+    <para>
+        Paths used in kernel Metadata files are relative to
+        <filename>&lt;base&gt;</filename>, which is either
+        <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+        if you are creating Metadata in
+        <link linkend='recipe-space-metadata'>recipe-space</link>,
+        or <filename>meta/cfg/kernel-cache/</filename> if you are creating
+        Metadata <link linkend='in-tree-metadata'>in-tree</link>.
+    </para>
+
+    <section id='configuration'>
+        <title>Configuration</title>
+
+        <para>
+            The simplest unit of kernel Metadata is the configuration-only
+            feature.
+            This feature consists of one or more Linux kernel configuration
+            parameters in a configuration fragment file
+            (<filename>.cfg</filename>) and an <filename>.scc</filename> file
+            that describes the fragment.
+        </para>
+
+        <para>
+            The Symmetric Multi-Processing (SMP) fragment included in the
+            <filename>linux-yocto-3.4</filename> Git repository
+            consists of the following two files:
+            <literallayout class='monospaced'>
+     cfg/smp.scc:
+        define KFEATURE_DESCRIPTION "Enable SMP"
+        kconf hardware smp.cfg
+
+     cfg/smp.cfg:
+        CONFIG_SMP=y
+        CONFIG_SCHED_SMT=y
+            </literallayout>
+            You can find information on configuration fragment files in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
+            section of the Yocto Project Development Manual and in
+            the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+            section earlier in this manual.
+        </para>
+
+        <para>
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KFEATURE_DESCRIPTION'><filename>KFEATURE_DESCRIPTION</filename></ulink>
+            provides a short description of the fragment.
+            Higher level kernel tools use this description.
+        </para>
+
+        <para>
+            The <filename>kconf</filename> command is used to include the
+            actual configuration fragment in an <filename>.scc</filename>
+            file, and the "hardware" keyword identifies the fragment as
+            being hardware enabling, as opposed to general policy,
+            which would use the "non-hardware" keyword.
+            The distinction is made for the benefit of the configuration
+            validation tools, which warn you if a hardware fragment
+            overrides a policy set by a non-hardware fragment.
+            <note>
+                The description file can include multiple
+                <filename>kconf</filename> statements, one per fragment.
+            </note>
+        </para>
+
+        <para>
+            As described in the
+            "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+            section, you can use the following BitBake command to audit your
+            configuration:
+            <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configcheck -f
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='patches'>
+        <title>Patches</title>
+
+        <para>
+            Patch descriptions are very similar to configuration fragment
+            descriptions, which are described in the previous section.
+            However, instead of a <filename>.cfg</filename> file, these
+            descriptions work with source patches.
+        </para>
+
+        <para>
+            A typical patch includes a description file and the patch itself:
+            <literallayout class='monospaced'>
+     patches/mypatch.scc:
+        patch mypatch.patch
+
+     patches/mypatch.patch:
+        &lt;typical-patch&gt;
+            </literallayout>
+            You can create the typical <filename>.patch</filename>
+            file using <filename>diff -Nurp</filename> or
+            <filename>git format-patch</filename>.
+        </para>
+
+        <para>
+            The description file can include multiple patch statements,
+            one per patch.
+        </para>
+    </section>
+
+    <section id='features'>
+        <title>Features</title>
+
+        <para>
+            Features are complex kernel Metadata types that consist
+            of configuration fragments (<filename>kconf</filename>), patches
+            (<filename>patch</filename>), and possibly other feature
+            description files (<filename>include</filename>).
+        </para>
+
+        <para>
+            Here is an example that shows a feature description file:
+            <literallayout class='monospaced'>
+     features/myfeature.scc
+        define KFEATURE_DESCRIPTION "Enable myfeature"
+
+        patch 0001-myfeature-core.patch
+        patch 0002-myfeature-interface.patch
+
+        include cfg/myfeature_dependency.scc
+        kconf non-hardware myfeature.cfg
+            </literallayout>
+            This example shows how the <filename>patch</filename> and
+            <filename>kconf</filename> commands are used as well as
+            how an additional feature description file is included.
+        </para>
+
+        <para>
+            Typically, features are less granular than configuration
+            fragments and are more likely than configuration fragments
+            and patches to be the types of things you want to specify
+            in the <filename>KERNEL_FEATURES</filename> variable of the
+            Linux kernel recipe.
+            See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
+            section earlier in the manual.
+        </para>
+    </section>
+
+    <section id='kernel-types'>
+        <title>Kernel Types</title>
+
+        <para>
+            A kernel type defines a high-level kernel policy by
+            aggregating non-hardware configuration fragments with
+            patches you want to use when building a Linux kernels of a
+            specific type.
+            Syntactically, kernel types are no different than features
+            as described in the "<link linkend='features'>Features</link>"
+            section.
+            The <filename>LINUX_KERNEL_TYPE</filename> variable in the kernel
+            recipe selects the kernel type.
+            See the "<link linkend='using-kernel-metadata-in-a-recipe'>Using Kernel Metadata in a Recipe</link>"
+            section for more information.
+        </para>
+
+        <para>
+            As an example, the <filename>linux-yocto-3.4</filename>
+            tree defines three kernel types: "standard",
+            "tiny", and "preempt-rt":
+            <itemizedlist>
+                <listitem><para>"standard":
+                    Includes the generic Linux kernel policy of the Yocto
+                    Project linux-yocto kernel recipes.
+                    This policy includes, among other things, which file
+                    systems, networking options, core kernel features, and
+                    debugging and tracing options are supported.
+                    </para></listitem>
+                <listitem><para>"preempt-rt":
+                    Applies the <filename>PREEMPT_RT</filename>
+                    patches and the configuration options required to
+                    build a real-time Linux kernel.
+                    This kernel type inherits from the "standard" kernel type.
+                    </para></listitem>
+                <listitem><para>"tiny":
+                    Defines a bare minimum configuration meant to serve as a
+                    base for very small Linux kernels.
+                    The "tiny" kernel type is independent from the "standard"
+                    configuration.
+                    Although the "tiny" kernel type does not currently include
+                    any source changes, it might in the future.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            The "standard" kernel type is defined by
+            <filename>standard.scc</filename>:
+            <literallayout class='monospaced'>
+     # Include this kernel type fragment to get the standard features and
+     # configuration values.
+
+     # Include all standard features
+     include standard-nocfg.scc
+
+     kconf non-hardware standard.cfg
+
+     # individual cfg block section
+     include cfg/fs/devtmpfs.scc
+     include cfg/fs/debugfs.scc
+     include cfg/fs/btrfs.scc
+     include cfg/fs/ext2.scc
+     include cfg/fs/ext3.scc
+     include cfg/fs/ext4.scc
+
+     include cfg/net/ipv6.scc
+     include cfg/net/ip_nf.scc
+     include cfg/net/ip6_nf.scc
+     include cfg/net/bridge.scc
+            </literallayout>
+        </para>
+
+        <para>
+            As with any <filename>.scc</filename> file, a
+            kernel type definition can aggregate other
+            <filename>.scc</filename> files with
+            <filename>include</filename> commands.
+            These definitions can also directly pull in
+            configuration fragments and patches with the
+            <filename>kconf</filename> and <filename>patch</filename>
+            commands, respectively.
+        </para>
+
+        <note>
+            It is not strictly necessary to create a kernel type
+            <filename>.scc</filename> file.
+            The Board Support Package (BSP) file can implicitly define
+            the kernel type using a <filename>define
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'>KTYPE</ulink> myktype</filename>
+            line.
+            See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
+            section for more information.
+        </note>
+    </section>
+
+    <section id='bsp-descriptions'>
+        <title>BSP Descriptions</title>
+
+        <para>
+            BSP descriptions combine kernel types with hardware-specific
+            features.
+            The hardware-specific portion is typically defined
+            independently, and then aggregated with each supported kernel
+            type.
+            Consider this simple BSP description that supports the "mybsp"
+            machine:
+            <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
+
+        kconf mybsp.cfg
+            </literallayout>
+            Every BSP description should define the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KMACHINE'><filename>KMACHINE</filename></ulink>,
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>,
+            and <ulink url='&YOCTO_DOCS_REF_URL;#var-KARCH'><filename>KARCH</filename></ulink>
+            variables.
+            These variables allow the OpenEmbedded build system to identify
+            the description as meeting the criteria set by the recipe being
+            built.
+            This simple example supports the "mybsp" machine for the "standard"
+            kernel and the "i386" architecture.
+        </para>
+
+        <para>
+            Be aware that a hard link between the
+            <filename>KTYPE</filename> variable and a kernel type
+            description file does not exist.
+            Thus, if you do not have kernel types defined in your kernel
+            Metadata, you only need to ensure that the kernel recipe's
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></ulink>
+            variable and the <filename>KTYPE</filename> variable in the
+            BSP description file match.
+            <note>
+                Future versions of the tooling make the specification of
+                <filename>KTYPE</filename> in the BSP optional.
+            </note>
+        </para>
+
+        <para>
+            If you did want to separate your kernel policy from your
+            hardware configuration, you could do so by specifying a kernel
+            type, such as "standard" and including that description file
+            in the BSP description file.
+            See the "<link linkend='kernel-types'>Kernel Types</link>" section
+            for more information.
+        </para>
+
+        <para>
+            You might also have multiple hardware configurations that you
+            aggregate into a single hardware description file that you
+            could include in the BSP description file, rather than referencing
+            a single <filename>.cfg</filename> file.
+            Consider the following:
+            <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
+
+        include standard.scc
+        include mybsp-hw.scc
+            </literallayout>
+        </para>
+
+        <para>
+            In the above example, <filename>standard.scc</filename>
+            aggregates all the configuration fragments, patches, and
+            features that make up your standard kernel policy whereas
+            <filename>mybsp-hw.scc</filename> aggregates all those necessary
+            to support the hardware available on the "mybsp" machine.
+            For information on how to break a complete
+            <filename>.config</filename> file into the various
+            configuration fragments, see the
+            "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+            section.
+        </para>
+
+        <para>
+            Many real-world examples are more complex.
+            Like any other <filename>.scc</filename> file, BSP
+            descriptions can aggregate features.
+            Consider the Fish River Island 2 (fri2)
+            BSP definition from the <filename>linux-yocto-3.4</filename>
+            Git repository:
+            <literallayout class='monospaced'>
+     fri2.scc:
+        kconf hardware fri2.cfg
+
+        include cfg/x86.scc
+        include features/eg20t/eg20t.scc
+        include cfg/dmaengine.scc
+        include features/ericsson-3g/f5521gw.scc
+        include features/power/intel.scc
+        include cfg/efi.scc
+        include features/usb/ehci-hcd.scc
+        include features/usb/ohci-hcd.scc
+        include features/iwlwifi/iwlwifi.scc
+            </literallayout>
+        </para>
+
+        <para>
+            The <filename>fri2.scc</filename> description file includes
+            a hardware configuration fragment
+            (<filename>fri2.cfg</filename>) specific to the Fish River
+            Island 2 BSP as well as several more general configuration
+            fragments and features enabling hardware found on the
+            machine.
+            This description file is then included in each of the three
+            "fri2" description files for the supported kernel types
+            (i.e. "standard", "preempt-rt", and "tiny").
+            Consider the "fri2" description for the "standard" kernel
+            type:
+            <literallayout class='monospaced'>
+     fri2-standard.scc:
+        define KMACHINE fri2
+        define KTYPE standard
+        define KARCH i386
+
+        include ktypes/standard/standard.scc
+        branch fri2
+
+        git merge emgd-1.14
+
+        include fri2.scc
+
+        # Extra fri2 configs above the minimal defined in fri2.scc
+        include cfg/efi-ext.scc
+        include features/drm-emgd/drm-emgd.scc
+        include cfg/vesafb.scc
+
+        # default policy for standard kernels
+        include cfg/usb-mass-storage.scc
+            </literallayout>
+            The <filename>include</filename> command midway through the file
+            includes the <filename>fri2.scc</filename> description that
+            defines all hardware enablements for the BSP that is common to all
+            kernel types.
+            Using this command significantly reduces duplication.
+        </para>
+
+        <para>
+            This "fri2" standard description introduces a few more variables
+            and commands that are worth further discussion.
+            Notice the <filename>branch fri2</filename> command, which creates
+            a machine-specific branch into which source changes are applied.
+            With this branch set up, the <filename>git merge</filename> command
+            uses Git to merge in a feature branch named "emgd-1.14".
+            You could also handle this with the <filename>patch</filename>
+            command.
+            However, for commonly used features such as this, feature branches
+            are a convenient mechanism.
+            See the "<link linkend='feature-branches'>Feature Branches</link>"
+            section for more information.
+        </para>
+
+        <para>
+            Now consider the "fri2" description for the "tiny" kernel type:
+            <literallayout class='monospaced'>
+     fri2-tiny.scc:
+        define KMACHINE fri2
+        define KTYPE tiny
+        define KARCH i386
+
+        include ktypes/tiny/tiny.scc
+        branch fri2
+
+        include fri2.scc
+            </literallayout>
+            As you might expect, the "tiny" description includes quite a
+            bit less.
+            In fact, it includes only the minimal policy defined by the
+            "tiny" kernel type and the hardware-specific configuration required
+            for booting the machine along with the most basic functionality of
+            the system as defined in the base "fri2" description file.
+        </para>
+
+        <para>
+            Notice again the three critical variables:
+            <filename>KMACHINE</filename>, <filename>KTYPE</filename>,
+            and <filename>KARCH</filename>.
+            Of these variables, only the <filename>KTYPE</filename> has changed.
+            It is now set to "tiny".
+        </para>
+    </section>
+</section>
+
+<section id='organizing-your-source'>
+    <title>Organizing Your Source</title>
+
+    <para>
+        Many recipes based on the <filename>linux-yocto-custom.bb</filename>
+        recipe use Linux kernel sources that have only a single
+        branch - "master".
+        This type of repository structure is fine for linear development
+        supporting a single machine and architecture.
+        However, if you work with multiple boards and architectures,
+        a kernel source repository with multiple branches is more
+        efficient.
+        For example, suppose you need a series of patches for one board to boot.
+        Sometimes, these patches are works-in-progress or fundamentally wrong,
+        yet they are still necessary for specific boards.
+        In these situations, you most likely do not want to include these
+        patches in every kernel you build (i.e. have the patches as part of
+        the lone "master" branch).
+        It is situations like these that give rise to multiple branches used
+        within a Linux kernel sources Git repository.
+    </para>
+
+    <para>
+        Repository organization strategies exist that maximize source reuse,
+        remove redundancy, and logically order your changes.
+        This section presents strategies for the following cases:
+        <itemizedlist>
+            <listitem><para>Encapsulating patches in a feature description
+                and only including the patches in the BSP descriptions of
+                the applicable boards.</para></listitem>
+            <listitem><para>Creating a machine branch in your
+                kernel source repository and applying the patches on that
+                branch only.</para></listitem>
+            <listitem><para>Creating a feature branch in your
+                kernel source repository and merging that branch into your
+                BSP when needed.</para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        The approach you take is entirely up to you
+        and depends on what works best for your development model.
+    </para>
+
+    <section id='encapsulating-patches'>
+        <title>Encapsulating Patches</title>
+
+        <para>
+            if you are reusing patches from an external tree and are not
+            working on the patches, you might find the encapsulated feature
+            to be appropriate.
+            Given this scenario, you do not need to create any branches in the
+            source repository.
+            Rather, you just take the static patches you need and encapsulate
+            them within a feature description.
+            Once you have the feature description, you simply include that into
+            the BSP description as described in the
+            "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
+            section.
+        </para>
+
+        <para>
+            You can find information on how to create patches and BSP
+            descriptions in the "<link linkend='patches'>Patches</link>" and
+            "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
+            sections.
+        </para>
+    </section>
+
+    <section id='machine-branches'>
+        <title>Machine Branches</title>
+
+        <para>
+            When you have multiple machines and architectures to support,
+            or you are actively working on board support, it is more
+            efficient to create branches in the repository based on
+            individual machines.
+            Having machine branches allows common source to remain in the
+            "master" branch with any features specific to a machine stored
+            in the appropriate machine branch.
+            This organization method frees you from continually reintegrating
+            your patches into a feature.
+        </para>
+
+        <para>
+            Once you have a new branch, you can set up your kernel Metadata
+            to use the branch a couple different ways.
+            In the recipe, you can specify the new branch as the
+            <filename>KBRANCH</filename> to use for the board as
+            follows:
+            <literallayout class='monospaced'>
+     KBRANCH = "mynewbranch"
+            </literallayout>
+            Another method is to use the <filename>branch</filename> command
+            in the BSP description:
+            <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
+        include standard.scc
+
+        branch mynewbranch
+
+        include mybsp-hw.scc
+            </literallayout>
+        </para>
+
+        <para>
+            If you find
+            yourself with numerous branches, you might consider using a
+            hierarchical branching system similar to what the linux-yocto Linux
+            kernel repositories use:
+            <literallayout class='monospaced'>
+     &lt;common&gt;/&lt;kernel_type&gt;/&lt;machine&gt;
+            </literallayout>
+        </para>
+
+        <para>
+            If you had two kernel types, "standard" and "small" for
+            instance, and three machines, the branches in your
+            Git repository might look like this:
+            <literallayout class='monospaced'>
+     common/base
+     common/standard/base
+     common/standard/machine_a
+     common/standard/machine_b
+     common/standard/machine_c
+     common/small/base
+     common/small/machine_a
+            </literallayout>
+        </para>
+
+        <para>
+            This organization can help clarify the branch relationships.
+            In this case, <filename>common/standard/machine_a</filename>
+            includes everything in <filename>common/base</filename> and
+            <filename>common/standard/base</filename>.
+            The "standard" and "small" branches add sources specific to those
+            kernel types that for whatever reason are not appropriate for the
+            other branches.
+            <note>The "base" branches are an artifact of the way Git manages
+                its data internally on the filesystem: Git will not allow you
+                to use <filename>common/standard</filename> and
+                <filename>common/standard/machine_a</filename> because it
+                would have to create a file and a directory named "standard".
+            </note>
+        </para>
+    </section>
+
+    <section id='feature-branches'>
+        <title>Feature Branches</title>
+
+        <para>
+            When you are actively developing new features, it can be more
+            efficient to work with that feature as a branch, rather than
+            as a set of patches that have to be regularly updated.
+            The Yocto Project Linux kernel tools provide for this with
+            the <filename>git merge</filename> command.
+        </para>
+
+        <para>
+            To merge a feature branch into a BSP, insert the
+            <filename>git merge</filename> command after any
+            <filename>branch</filename> commands:
+            <literallayout class='monospaced'>
+     mybsp.scc:
+        define KMACHINE mybsp
+        define KTYPE standard
+        define KARCH i386
+        include standard.scc
+
+        branch mynewbranch
+        git merge myfeature
+
+        include mybsp-hw.scc
+            </literallayout>
+        </para>
+    </section>
+</section>
+
+<section id='scc-reference'>
+    <title>SCC Description File Reference</title>
+
+    <para>
+        This section provides a brief reference for the commands you can use
+        within an SCC description file (<filename>.scc</filename>):
+        <itemizedlist>
+            <listitem><para><filename>branch [ref]</filename>:
+                Creates a new branch relative to the current branch
+                (typically <filename>${KTYPE}</filename>) using
+                the currently checked-out branch, or "ref" if specified.
+                </para></listitem>
+            <listitem><para><filename>define</filename>:
+                Defines variables, such as <filename>KMACHINE</filename>,
+                <filename>KTYPE</filename>, <filename>KARCH</filename>,
+                and <filename>KFEATURE_DESCRIPTION</filename>.</para></listitem>
+            <listitem><para><filename>include SCC_FILE</filename>:
+                Includes an SCC file in the current file.
+                The file is parsed as if you had inserted it inline.
+                </para></listitem>
+            <listitem><para><filename>kconf [hardware|non-hardware] CFG_FILE</filename>:
+                Queues a configuration fragment for merging into the final
+                Linux <filename>.config</filename> file.</para></listitem>
+            <listitem><para><filename>git merge GIT_BRANCH</filename>:
+                Merges the feature branch into the current branch.
+                </para></listitem>
+            <listitem><para><filename>patch PATCH_FILE</filename>:
+                Applies the patch to the current Git branch.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-common.xml b/documentation/kernel-dev/kernel-dev-common.xml
new file mode 100644
index 0000000000..a152f9fbbe
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-common.xml
@@ -0,0 +1,863 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-common'>
+
+<title>Common Tasks</title>
+
+<para>
+    This chapter presents several common tasks you perform when you
+    work with the Yocto Project Linux kernel.
+    These tasks include preparing a layer, modifying an existing recipe,
+    iterative development, working with your own sources, and incorporating
+    out-of-tree modules.
+    <note>
+        The examples presented in this chapter work with the Yocto Project
+        1.2.2 Release and forward.
+    </note>
+</para>
+
+    <section id='creating-and-preparing-a-layer'>
+        <title>Creating and Preparing a Layer</title>
+
+        <para>
+            If you are going to be modifying kernel recipes, it is recommended
+            that you create and prepare your own layer in which to do your
+            work.
+            Your layer contains its own BitBake append files
+            (<filename>.bbappend</filename>) and provides a convenient
+            mechanism to create your own recipe files
+            (<filename>.bb</filename>).
+            For details on how to create and work with layers, see the following
+            sections in the Yocto Project Development Manual:
+            <itemizedlist>
+                <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" for
+                    general information on layers and how to create layers.</para></listitem>
+                <listitem><para>"<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" for
+                    specific instructions on setting up a layer for kernel
+                    development.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='modifying-an-existing-recipe'>
+        <title>Modifying an Existing Recipe</title>
+
+        <para>
+            In many cases, you can customize an existing linux-yocto recipe to
+            meet the needs of your project.
+            Each release of the Yocto Project provides a few Linux
+            kernel recipes from which you can choose.
+            These are located in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            in <filename>meta/recipes-kernel/linux</filename>.
+        </para>
+
+        <para>
+            Modifying an existing recipe can consist of the following:
+            <itemizedlist>
+                <listitem><para>Creating the append file</para></listitem>
+                <listitem><para>Applying patches</para></listitem>
+                <listitem><para>Changing the configuration</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Before modifying an existing recipe, be sure that you have created
+            a minimal, custom layer from which you can work.
+            See the "<link linkend='creating-and-preparing-a-layer'>Creating and Preparing a Layer</link>"
+            section for some general resources.
+            You can also see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#set-up-your-layer-for-the-build'>Set Up Your Layer for the Build</ulink>" section
+            of the Yocto Project Development Manual for a detailed
+            example.
+        </para>
+
+        <section id='creating-the-append-file'>
+            <title>Creating the Append File</title>
+
+            <para>
+                You create this file in your custom layer.
+                You also name it accordingly based on the linux-yocto recipe
+                you are using.
+                For example, if you are modifying the
+                <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename>
+                recipe, the append file will typical be located as follows
+                within your custom layer:
+                <literallayout class='monospaced'>
+     &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto_3.4.bbappend
+                </literallayout>
+                The append file should initially extend the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                search path by prepending the directory that contains your
+                files to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                variable as follows:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+                </literallayout>
+                The path <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-THISDIR'><filename>THISDIR</filename></ulink><filename>}/${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
+                expands to "linux-yocto" in the current directory for this
+                example.
+                If you add any new files that modify the kernel recipe and you
+                have extended <filename>FILESPATH</filename> as
+                described above, you must place the files in your layer in the
+                following area:
+                <literallayout class='monospaced'>
+     &lt;your-layer&gt;/recipes-kernel/linux/linux-yocto/
+                </literallayout>
+                <note>If you are working on a new machine Board Support Package
+                    (BSP), be sure to refer to the
+                    <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+                </note>
+            </para>
+        </section>
+
+        <section id='applying-patches'>
+            <title>Applying Patches</title>
+
+            <para>
+                If you have a single patch or a small series of patches
+                that you want to apply to the Linux kernel source, you
+                can do so just as you would with any other recipe.
+                You first copy the patches to the path added to
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                in your <filename>.bbappend</filename> file as described in
+                the previous section, and then reference them in
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                statements.
+            </para>
+
+            <para>
+                For example, you can apply a three-patch series by adding the
+                following lines to your linux-yocto <filename>.bbappend</filename>
+                file in your layer:
+                <literallayout class='monospaced'>
+     SRC_URI += "file://0001-first-change.patch"
+     SRC_URI += "file://0002-first-change.patch"
+     SRC_URI += "file://0003-first-change.patch"
+                </literallayout>
+                The next time you run BitBake to build the Linux kernel, BitBake
+                detects the change in the recipe and fetches and applies the patches
+                before building the kernel.
+            </para>
+
+            <para>
+                For a detailed example showing how to patch the kernel, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#patching-the-kernel'>Patching the Kernel</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+
+        <section id='changing-the-configuration'>
+            <title>Changing the Configuration</title>
+
+            <para>
+                You can make wholesale or incremental changes to the Linux
+                kernel <filename>.config</filename> file by including a
+                <filename>defconfig</filename> and by specifying
+                configuration fragments in the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>.
+            </para>
+
+            <para>
+                If you have a final Linux kernel <filename>.config</filename>
+                file you want to use, copy it to a directory named
+                <filename>files</filename>, which must be in
+                your layer's <filename>recipes-kernel/linux</filename>
+                directory, and name the file "defconfig".
+                Then, add the following lines to your linux-yocto
+                <filename>.bbappend</filename> file in your layer:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
+     SRC_URI += "file://defconfig"
+                </literallayout>
+                The <filename>SRC_URI</filename> tells the build system how to
+                search for the file, while the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></ulink>
+                extends the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-FILESPATH'><filename>FILESPATH</filename></ulink>
+                variable (search directories) to include the
+                <filename>files</filename> directory you created for the
+                configuration changes.
+            </para>
+
+            <note>
+                The build system applies the configurations from the
+                <filename>.config</filename> file before applying any
+                subsequent configuration fragments.
+                The final kernel configuration is a combination of the
+                configurations in the <filename>.config</filename> file and
+                any configuration fragments you provide.
+                You need to realize that if you have any configuration
+                fragments, the build system applies these on top of and
+                after applying the existing <filename>.config</filename>
+                file configurations.
+            </note>
+
+            <para>
+                Generally speaking, the preferred approach is to determine the
+                incremental change you want to make and add that as a
+                configuration fragment.
+                For example, if you want to add support for a basic serial
+                console, create a file named <filename>8250.cfg</filename> in
+                the <filename>files</filename> directory with the following
+                content (without indentation):
+                <literallayout class='monospaced'>
+     CONFIG_SERIAL_8250=y
+     CONFIG_SERIAL_8250_CONSOLE=y
+     CONFIG_SERIAL_8250_PCI=y
+     CONFIG_SERIAL_8250_NR_UARTS=4
+     CONFIG_SERIAL_8250_RUNTIME_UARTS=4
+     CONFIG_SERIAL_CORE=y
+     CONFIG_SERIAL_CORE_CONSOLE=y
+                </literallayout>
+                Next, include this configuration fragment and extend the
+                <filename>FILESPATH</filename> variable in your
+                <filename>.bbappend</filename> file:
+                <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
+     SRC_URI += "file://8250.cfg"
+                </literallayout>
+                The next time you run BitBake to build the Linux kernel, BitBake
+                detects the change in the recipe and fetches and applies the
+                new configuration before building the kernel.
+            </para>
+
+            <para>
+                For a detailed example showing how to configure the kernel,
+                see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#configuring-the-kernel'>Configuring the Kernel</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+    </section>
+
+    <section id='using-an-iterative-development-process'>
+        <title>Using an Iterative Development Process</title>
+
+        <para>
+            If you do not have existing patches or configuration files,
+            you can iteratively generate them from within the BitBake build
+            environment as described within this section.
+            During an iterative workflow, running a previously completed BitBake
+            task causes BitBake to invalidate the tasks that follow the
+            completed task in the build sequence.
+            Invalidated tasks rebuild the next time you run the build using
+            BitBake.
+        </para>
+
+        <para>
+            As you read this section, be sure to substitute the name
+            of your Linux kernel recipe for the term
+            "linux-yocto".
+        </para>
+
+        <section id='tip-dirty-string'>
+            <title>"-dirty" String</title>
+
+<!--
+            <para>
+                <emphasis>AR - Darrren Hart:</emphasis>  This section
+                originated from the old Yocto Project Kernel Architecture
+                and Use Manual.
+                It was decided we need to put it in this section here.
+                Darren needs to figure out where we want it and what part
+                of it we want (all, revision???)
+            </para>
+-->
+
+            <para>
+                If kernel images are being built with "-dirty" on the
+                end of the version string, this simply means that
+                modifications in the source directory have not been committed.
+                <literallayout class='monospaced'>
+     $ git status
+                </literallayout>
+            </para>
+
+            <para>
+                You can use the above Git command to report modified,
+                removed, or added files.
+                You should commit those changes to the tree regardless of
+                whether they will be saved, exported, or used.
+                Once you commit the changes, you need to rebuild the kernel.
+            </para>
+
+            <para>
+                To force a pickup and commit of all such pending changes,
+                enter the following:
+                <literallayout class='monospaced'>
+     $ git add .
+     $ git commit -s -a -m "getting rid of -dirty"
+                </literallayout>
+            </para>
+
+            <para>
+                Next, rebuild the kernel.
+            </para>
+        </section>
+
+        <section id='generating-configuration-files'>
+            <title>Generating Configuration Files</title>
+
+            <para>
+                You can manipulate the <filename>.config</filename> file
+                used to build a linux-yocto recipe with the
+                <filename>menuconfig</filename> command as follows:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                </literallayout>
+                This command starts the Linux kernel configuration tool,
+                which allows you to prepare a new
+                <filename>.config</filename> file for the build.
+                When you exit the tool, be sure to save your changes
+                at the prompt.
+            </para>
+
+            <para>
+                The resulting <filename>.config</filename> file is
+                located in
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}</filename> under the
+                <filename>linux-${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink><filename>}-${<ulink url='&YOCTO_DOCS_REF_URL;#var-KTYPE'><filename>KTYPE</filename></ulink>}-build</filename> directory.
+                You can use the entire <filename>.config</filename> file as the
+                <filename>defconfig</filename> file as described in the
+                "<link linkend='changing-the-configuration'>Changing the Configuration</link>" section.
+            </para>
+
+            <para>
+                A better method is to create a configuration fragment using the
+                differences between two configuration files: one previously
+                created and saved, and one freshly created using the
+                <filename>menuconfig</filename> tool.
+            </para>
+
+            <para>
+                To create a configuration fragment using this method, follow
+                these steps:
+                <orderedlist>
+                    <listitem><para>Complete a build at least through the kernel
+                        configuration task as follows:
+                        <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configme -f
+                        </literallayout></para></listitem>
+                    <listitem><para>Copy and rename the resulting
+                        <filename>.config</filename> file (e.g.
+                        <filename>config.orig</filename>).
+                        </para></listitem>
+                    <listitem><para>Run the <filename>menuconfig</filename>
+                        command:
+                        <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c menuconfig
+                        </literallayout></para></listitem>
+                    <listitem><para>Prepare a configuration fragment based on
+                        the differences between the two files.
+                        </para></listitem>
+                </orderedlist>
+            </para>
+
+            <para>
+                Ultimately, the configuration fragment file needs to be a
+                list of Linux kernel <filename>CONFIG_</filename> assignments.
+                It cannot be in <filename>diff</filename> format.
+                Here is an example of a command that creates your
+                configuration fragment file.
+                Regardless of the exact command you use, plan on reviewing
+                the output as you can usually remove some of the defaults:
+                <literallayout class='monospaced'>
+     $ diff -Nurp config.orig .config | sed -n "s/^\+//p" > frag.cfg
+                </literallayout>
+                See the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
+                section for information on how to use the output as a
+                configuration fragment.
+                <note>
+                    You can also use this method to create configuration
+                    fragments for a BSP.
+                    See the "<link linkend='bsp-descriptions'>BSP Descriptions</link>"
+                    section for more information.
+                </note>
+            </para>
+
+            <para>
+                The kernel tools also provide configuration validation.
+                You can use these tools to produce warnings for when a
+                requested configuration does not appear in the final
+                <filename>.config</filename> file or when you override a
+                policy configuration in a hardware configuration fragment.
+                Here is an example with some sample output of the command
+                that runs these tools:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configcheck -f
+
+     ...
+
+     NOTE: validating kernel configuration
+     This BSP sets 3 invalid/obsolete kernel options.
+     These config options are not offered anywhere within this kernel.
+     The full list can be found in your kernel src dir at:
+     meta/cfg/standard/mybsp/invalid.cfg
+
+     This BSP sets 21 kernel options that are possibly non-hardware related.
+     The full list can be found in your kernel src dir at:
+     meta/cfg/standard/mybsp/specified_non_hdw.cfg
+
+     WARNING: There were 2 hardware options requested that do not
+              have a corresponding value present in the final ".config" file.
+              This probably means you are not't getting the config you wanted.
+              The full list can be found in your kernel src dir at:
+              meta/cfg/standard/mybsp/mismatch.cfg
+                </literallayout>
+            </para>
+
+            <para>
+                The output describes the various problems that you can
+                encounter along with where to find the offending configuration
+                items.
+                You can use the information in the logs to adjust your
+                configuration files and then repeat the
+                <filename>kernel_configme</filename> and
+                <filename>kernel_configcheck</filename> commands until
+                they produce no warnings.
+            </para>
+
+            <para>
+                For more information on how to use the
+                <filename>menuconfig</filename> tool, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#using-menuconfig'>Using <filename>menuconfig</filename></ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+
+        <section id='modifying-source-code'>
+            <title>Modifying Source Code</title>
+
+            <para>
+                You can experiment with source code changes and create a
+                simple patch without leaving the BitBake environment.
+                To get started, be sure to complete a build at
+                least through the kernel configuration task:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c kernel_configme -f
+                </literallayout>
+                Taking this step ensures you have the sources prepared
+                and the configuration completed.
+                You can find the sources in the
+                <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink><filename>}/linux</filename> directory.
+            </para>
+
+            <para>
+                You can edit the sources as you would any other Linux source
+                tree.
+                However, keep in mind that you will lose changes if you
+                trigger the <filename>fetch</filename> task for the recipe.
+                You can avoid triggering this task by not issuing BitBake's
+                <filename>cleanall</filename>, <filename>cleansstate</filename>,
+                or forced <filename>fetch</filename> commands.
+                Also, do not modify the recipe itself while working
+                with temporary changes or BitBake might run the
+                <filename>fetch</filename> command depending on the
+                changes to the recipe.
+            </para>
+
+            <para>
+                To test your temporary changes, instruct BitBake to run the
+                <filename>compile</filename> again.
+                The <filename>-f</filename> option forces the command to run
+                even though BitBake might think it has already done so:
+                <literallayout class='monospaced'>
+     $ bitbake linux-yocto -c compile -f
+                </literallayout>
+                If the compile fails, you can update the sources and repeat
+                the <filename>compile</filename>.
+                Once compilation is successful, you can inspect and test
+                the resulting build (i.e. kernel, modules, and so forth) from
+                the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                <literallayout class='monospaced'>
+     ${WORKDIR}/linux-${MACHINE}-${KTYPE}-build
+                </literallayout>
+                Alternatively, you can run the <filename>deploy</filename>
+                command to place the kernel image in the
+                <filename>tmp/deploy/images</filename> directory:
+                <literallayout class='monospaced'>
+        $ bitbake linux-yocto -c deploy
+                </literallayout>
+                And, of course, you can perform the remaining installation and
+                packaging steps by issuing:
+                <literallayout class='monospaced'>
+        $ bitbake linux-yocto
+                </literallayout>
+            </para>
+
+            <para>
+                For rapid iterative development, the edit-compile-repeat loop
+                described in this section is preferable to rebuilding the
+                entire recipe because the installation and packaging tasks
+                are very time consuming.
+            </para>
+
+            <para>
+                Once you are satisfied with your source code modifications,
+                you can make them permanent by generating patches and
+                applying them to the
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                statement as described in section
+                "<link linkend='applying-patches'>Applying Patches</link>" section.
+                If you are not familiar with generating patches, refer to the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-the-patch'>Creating the Patch</ulink>"
+                section in the Yocto Project Development Manual.
+            </para>
+        </section>
+    </section>
+
+    <section id='working-with-your-own-sources'>
+        <title>Working With Your Own Sources</title>
+
+        <para>
+            If you cannot work with one of the Linux kernel
+            versions supported by existing linux-yocto recipes, you can
+            still make use of the Yocto Project Linux kernel tooling by
+            working with your own sources.
+            When you use your own sources, you will not be able to
+            leverage the existing kernel
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> and
+            stabilization work of the linux-yocto sources.
+            However, you will be able to manage your own Metadata in the same
+            format as the linux-yocto sources.
+            Maintaining format compatibility facilitates converging with
+            linux-yocto on a future, mutually-supported kernel version.
+        </para>
+
+        <para>
+            To help you use your own sources, the Yocto Project provides a
+            linux-yocto custom recipe
+            (<filename>linux-yocto-custom.bb</filename>) that uses
+            <filename>kernel.org</filename> sources
+            and the Yocto Project Linux kernel tools for managing
+            kernel Metadata.
+            You can find this recipe in the
+            <filename>poky</filename> Git repository of the
+            Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
+            at:
+            <literallayout class="monospaced">
+     poky/meta-skeleton/recipes-kernel/linux/linux-yocto-custom.bb
+            </literallayout>
+        </para>
+
+        <para>
+            Here are some basic steps you can use to work with your own sources:
+            <orderedlist>
+                <listitem><para>Copy the <filename>linux-yocto-custom.bb</filename>
+                    recipe to your layer and give it a meaningful name.
+                    The name should include the version of the Linux kernel you
+                    are using (e.g. <filename>linux-yocto-myproject_3.5.bb</filename>,
+                    where "3.5" is the base version of the Linux kernel
+                    with which you would be working).</para></listitem>
+                <listitem><para>In the same directory inside your layer,
+                    create a matching directory
+                    to store your patches and configuration files (e.g.
+                    <filename>linux-yocto-myproject</filename>).
+                    </para></listitem>
+                <listitem><para>Edit the following variables in your recipe
+                    as appropriate for your project:
+                    <itemizedlist>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>:
+                            The <filename>SRC_URI</filename> should be a Git
+                            repository that uses one of the supported Git fetcher
+                            protocols (i.e. <filename>file</filename>,
+                            <filename>git</filename>, <filename>http</filename>,
+                            and so forth).
+                            The skeleton recipe provides an example
+                            <filename>SRC_URI</filename> as a syntax reference.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION'><filename>LINUX_VERSION</filename></ulink>:
+                            The Linux kernel version you are using (e.g.
+                            "3.4").</para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LINUX_VERSION_EXTENSION'><filename>LINUX_VERSION_EXTENSION</filename></ulink>:
+                            The Linux kernel <filename>CONFIG_LOCALVERSION</filename>
+                            that is compiled into the resulting kernel and visible
+                            through the <filename>uname</filename> command.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>:
+                            The commit ID from which you want to build.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>:
+                            Treat this variable the same as you would in any other
+                            recipe.
+                            Increment the variable to indicate to the OpenEmbedded
+                            build system that the recipe has changed.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>:
+                            The default <filename>PV</filename> assignment is
+                            typically adequate.
+                            It combines the <filename>LINUX_VERSION</filename>
+                            with the Source Control Manager (SCM) revision
+                            as derived from the
+                            <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>
+                            variable.
+                            The combined results are a string with
+                            the following form:
+                            <literallayout class='monospaced'>
+     3.4.11+git1+68a635bf8dfb64b02263c1ac80c948647cc76d5f_1+218bd8d2022b9852c60d32f0d770931e3cf343e2
+                            </literallayout>
+                            While lengthy, the extra verbosity in <filename>PV</filename>
+                            helps ensure you are using the exact
+                            sources from which you intend to build.
+                            </para></listitem>
+                        <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-COMPATIBLE_MACHINE'><filename>COMPATIBLE_MACHINE</filename></ulink>:
+                            A list of the machines supported by your new recipe.
+                            This variable in the example recipe is set
+                            by default to a regular expression that matches
+                            only the empty string, "(^$)".
+                            This default setting triggers an explicit build
+                            failure.
+                            You must change it to match a list of the machines
+                            that your new recipe supports.
+                            For example, to support the <filename>qemux86</filename>
+                            and <filename>qemux86-64</filename> machines, use
+                            the following form:
+                            <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE = "qemux86|qemux86-64"
+                            </literallayout></para></listitem>
+                    </itemizedlist></para></listitem>
+                <listitem><para>Provide further customizations to your recipe
+                    as needed just as you would customize an existing
+                    linux-yocto recipe.
+                    See the "<link linkend='modifying-an-existing-recipe'>Modifying
+                    an Existing Recipe</link>" section for information.
+                    </para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+
+    <section id='incorporating-out-of-tree-modules'>
+        <title>Incorporating Out-of-Tree Modules</title>
+
+        <para>
+            While it is always preferable to work with sources integrated
+            into the Linux kernel sources, if you need an external kernel
+            module, the <filename>hello-mod.bb</filename> recipe is available
+            as a template from which you can create your own out-of-tree
+            Linux kernel module recipe.
+        </para>
+
+        <para>
+            This template recipe is located in the
+            <filename>poky</filename> Git repository of the
+            Yocto Project <ulink url='&YOCTO_GIT_URL;'>Source Repository</ulink>
+            at:
+            <literallayout class="monospaced">
+     poky/meta-skeleton/recipes-kernel/hello-mod/hello-mod_0.1.bb
+            </literallayout>
+        </para>
+
+        <para>
+            To get started, copy this recipe to your layer and give it a
+            meaningful name (e.g. <filename>mymodule_1.0.bb</filename>).
+            In the same directory, create a directory named
+            <filename>files</filename> where you can store any source files,
+            patches, or other files necessary for building
+            the module that do not come with the sources.
+            Finally, update the recipe as appropriate for the module.
+            Typically you will need to set the following variables:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-DESCRIPTION'><filename>DESCRIPTION</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-LICENSE'><filename>LICENSE*</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Depending on the build system used by the module sources, you might
+            need to make some adjustments.
+            For example, a typical module <filename>Makefile</filename> looks
+            much like the one provided with the <filename>hello-mod</filename>
+            template:
+            <literallayout class='monospaced'>
+     obj-m := hello.o
+
+     SRC := $(shell pwd)
+
+     all:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC)
+
+     modules_install:
+         $(MAKE) -C $(KERNEL_SRC) M=$(SRC) modules_install
+     ...
+            </literallayout>
+        </para>
+
+        <para>
+            The important point to note here is the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_SRC'><filename>KERNEL_SRC</filename></ulink>
+            variable.
+            The class <filename>module.bbclass</filename> sets this variable,
+            as well as the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_PATH'><filename>KERNEL_PATH</filename></ulink>
+            variable to
+            <filename>${<ulink url='&YOCTO_DOCS_REF_URL;#var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></ulink>}</filename>
+            with the necessary Linux kernel build information to build modules.
+            If your module <filename>Makefile</filename> uses a different
+            variable, you might want to override the
+            <filename>do_compile()</filename> step, or create a patch to
+            the <filename>Makefile</filename> to work with the more typical
+            <filename>KERNEL_SRC</filename> or <filename>KERNEL_PATH</filename>
+            variables.
+        </para>
+
+        <para>
+            After you have prepared your recipe, you will likely want to
+            include the module in your images.
+            To do this, see the documentation for the following variables in
+            the Yocto Project Reference Manual and set one of them as
+            appropriate in your machine configuration file:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            modules are often not required for boot and can be excluded from
+            certain build configurations.
+            The following allows for the most flexibility:
+            <literallayout class='monospaced'>
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-mymodule"
+            </literallayout>
+            Where the value is derived by appending the module filename without
+            the <filename>.ko</filename> extension to the string
+            "kernel-module-".
+        </para>
+
+        <para>
+            Because the variable is
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
+            and not a
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>
+            variable, the build will not fail if this module is not available
+            to include in the image.
+        </para>
+    </section>
+
+    <section id='inspecting-changes-and-commits'>
+        <title>Inspecting Changes and Commits</title>
+
+        <para>
+            A common question when working with a kernel is:
+            "What changes have been applied to this tree?"
+            Rather than using "grep" across directories to see what has
+            changed, you can use Git to inspect or search the kernel tree.
+            Using Git is an efficient way to see what has changed in the tree.
+        </para>
+
+        <section id='what-changed-in-a-kernel'>
+            <title>What Changed in a Kernel?</title>
+
+            <para>
+                Following are a few examples that show how to use Git
+                commands to examine changes.
+                These examples are by no means the only way to see changes.
+                <note>
+                    In the following examples, unless you provide a commit
+                    range, <filename>kernel.org</filename> history is blended
+                    with Yocto Project kernel changes.
+                    You can form ranges by using branch names from the
+                    kernel tree as the upper and lower commit markers with
+                    the Git commands.
+                    You can see the branch names through the web interface
+                    to the Yocto Project source repositories at
+                    <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
+                </note>
+                To see a full range of the changes, use the
+                <filename>git whatchanged</filename> command and specify a
+                commit range for the branch
+                (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
+            </para>
+
+            <para>
+                Here is an example that looks at what has changed in the
+                <filename>emenlow</filename> branch of the
+                <filename>linux-yocto-3.4</filename> kernel.
+                The lower commit range is the commit associated with the
+                <filename>standard/base</filename> branch, while
+                the upper commit range is the commit associated with the
+                <filename>standard/emenlow</filename> branch.
+                <literallayout class='monospaced'>
+     $ git whatchanged origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                To see short, one line summaries of changes use the
+                <filename>git log</filename> command:
+                <literallayout class='monospaced'>
+     $ git log --oneline origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                Use this command to see code differences for the changes:
+                <literallayout class='monospaced'>
+     $ git diff origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                Use this command to see the commit log messages and the
+                text differences:
+                <literallayout class='monospaced'>
+     $ git show origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+
+            <para>
+                Use this command to create individual patches for
+                each change.
+                Here is an example that that creates patch files for each
+                commit and places them in your <filename>Documents</filename>
+                directory:
+                <literallayout class='monospaced'>
+     $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='showing-a-particular-feature-or-branch-change'>
+            <title>Showing a Particular Feature or Branch Change</title>
+
+            <para>
+                Tags in the Yocto Project kernel tree divide changes for
+                significant features or branches.
+                The <filename>git show &lt;tag&gt;</filename> command shows
+                changes based on a tag.
+                Here is an example that shows <filename>systemtap</filename>
+                changes:
+                <literallayout class='monospaced'>
+     $ git show systemtap
+                </literallayout>
+                You can use the
+                <filename>git branch --contains &lt;tag&gt;</filename> command
+                to show the branches that contain a particular feature.
+                This command shows the branches that contain the
+                <filename>systemtap</filename> feature:
+                <literallayout class='monospaced'>
+     $ git branch --contains systemtap
+                </literallayout>
+            </para>
+        </section>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-concepts-appx.xml b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
new file mode 100644
index 0000000000..ac91749cd6
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-concepts-appx.xml
@@ -0,0 +1,253 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<appendix id='kernel-dev-concepts-appx'>
+<title>Advanced Kernel Concepts</title>
+
+    <section id='kernel-big-picture'>
+        <title>Yocto Project Kernel Development and Maintenance</title>
+        <para>
+            Kernels available through the Yocto Project, like other kernels, are based off the Linux
+            kernel releases from <ulink url='http://www.kernel.org'></ulink>.
+            At the beginning of a major development cycle, the Yocto Project team
+            chooses its kernel based on factors such as release timing, the anticipated release
+            timing of final upstream <filename>kernel.org</filename> versions, and Yocto Project
+            feature requirements.
+            Typically, the kernel chosen is in the
+            final stages of development by the community.
+            In other words, the kernel is in the release
+            candidate or "rc" phase and not yet a final release.
+            But, by being in the final stages of external development, the team knows that the
+            <filename>kernel.org</filename> final release will clearly be within the early stages of
+            the Yocto Project development window.
+        </para>
+        <para>
+            This balance allows the team to deliver the most up-to-date kernel
+            possible, while still ensuring that the team has a stable official release for
+            the baseline Linux kernel version.
+        </para>
+        <para>
+            The ultimate source for kernels available through the Yocto Project are released kernels
+            from <filename>kernel.org</filename>.
+            In addition to a foundational kernel from <filename>kernel.org</filename>, the
+            kernels available contain a mix of important new mainline
+            developments, non-mainline developments (when there is no alternative),
+            Board Support Package (BSP) developments,
+            and custom features.
+            These additions result in a commercially released Yocto Project Linux kernel that caters
+            to specific embedded designer needs for targeted hardware.
+        </para>
+        <para>
+            Once a kernel is officially released, the Yocto Project team goes into
+            their next development cycle, or upward revision (uprev) cycle, while still
+            continuing maintenance on the released kernel.
+            It is important to note that the most sustainable and stable way
+            to include feature development upstream is through a kernel uprev process.
+            Back-porting hundreds of individual fixes and minor features from various
+            kernel versions is not sustainable and can easily compromise quality.
+        </para>
+        <para>
+            During the uprev cycle, the Yocto Project team uses an ongoing analysis of
+            kernel development, BSP support, and release timing to select the best
+            possible <filename>kernel.org</filename> version.
+            The team continually monitors community kernel
+            development to look for significant features of interest.
+            The team does consider back-porting large features if they have a significant advantage.
+            User or community demand can also trigger a back-port or creation of new
+            functionality in the Yocto Project baseline kernel during the uprev cycle.
+        </para>
+        <para>
+            Generally speaking, every new kernel both adds features and introduces new bugs.
+            These consequences are the basic properties of upstream kernel development and are
+            managed by the Yocto Project team's kernel strategy.
+            It is the Yocto Project team's policy to not back-port minor features to the released kernel.
+            They only consider back-porting significant technological jumps - and, that is done
+            after a complete gap analysis.
+            The reason for this policy is that back-porting any small to medium sized change
+            from an evolving kernel can easily create mismatches, incompatibilities and very
+            subtle errors.
+        </para>
+        <para>
+            These policies result in both a stable and a cutting
+            edge kernel that mixes forward ports of existing features and significant and critical
+            new functionality.
+            Forward porting functionality in the kernels available through the Yocto Project kernel
+            can be thought of as a "micro uprev."
+            The many “micro uprevs” produce a kernel version with a mix of
+            important new mainline, non-mainline, BSP developments and feature integrations.
+            This kernel gives insight into new features and allows focused
+            amounts of testing to be done on the kernel, which prevents
+            surprises when selecting the next major uprev.
+            The quality of these cutting edge kernels is evolving and the kernels are used in leading edge
+            feature and BSP development.
+        </para>
+    </section>
+
+    <section id='kernel-architecture'>
+        <title>Kernel Architecture</title>
+        <para>
+            This section describes the architecture of the kernels available through the
+            Yocto Project and provides information
+            on the mechanisms used to achieve that architecture.
+        </para>
+
+        <section id='architecture-overview'>
+            <title>Overview</title>
+            <para>
+                As mentioned earlier, a key goal of the Yocto Project is to present the
+                developer with
+                a kernel that has a clear and continuous history that is visible to the user.
+                The architecture and mechanisms used achieve that goal in a manner similar to the
+                upstream <filename>kernel.org</filename>.
+            </para>
+            <para>
+                You can think of a Yocto Project kernel as consisting of a baseline Linux kernel with
+                added features logically structured on top of the baseline.
+                The features are tagged and organized by way of a branching strategy implemented by the
+                source code manager (SCM) Git.
+                For information on Git as applied to the Yocto Project, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>" section in the
+                Yocto Project Development Manual.
+            </para>
+            <para>
+                The result is that the user has the ability to see the added features and
+                the commits that make up those features.
+                In addition to being able to see added features, the user can also view the history of what
+                made up the baseline kernel.
+            </para>
+            <para>
+                The following illustration shows the conceptual Yocto Project kernel.
+            </para>
+            <para>
+                <imagedata fileref="figures/kernel-architecture-overview.png" width="6in" depth="7in" align="center" scale="100" />
+            </para>
+            <para>
+                In the illustration, the "Kernel.org Branch Point"
+                marks the specific spot (or release) from
+                which the Yocto Project kernel is created.
+                From this point "up" in the tree, features and differences are organized and tagged.
+            </para>
+            <para>
+                The "Yocto Project Baseline Kernel" contains functionality that is common to every kernel
+                type and BSP that is organized further up the tree.
+                Placing these common features in the
+                tree this way means features do not have to be duplicated along individual branches of the
+                structure.
+            </para>
+            <para>
+                From the Yocto Project Baseline Kernel, branch points represent specific functionality
+                for individual BSPs as well as real-time kernels.
+                The illustration represents this through three BSP-specific branches and a real-time
+                kernel branch.
+                Each branch represents some unique functionality for the BSP or a real-time kernel.
+            </para>
+            <para>
+                In this example structure, the real-time kernel branch has common features for all
+                real-time kernels and contains
+                more branches for individual BSP-specific real-time kernels.
+                The illustration shows three branches as an example.
+                Each branch points the way to specific, unique features for a respective real-time
+                kernel as they apply to a given BSP.
+            </para>
+            <para>
+                The resulting tree structure presents a clear path of markers (or branches) to the
+                developer that, for all practical purposes, is the kernel needed for any given set
+                of requirements.
+            </para>
+        </section>
+
+        <section id='branching-and-workflow'>
+            <title>Branching Strategy and Workflow</title>
+            <para>
+                The Yocto Project team creates kernel branches at points where functionality is
+                no longer shared and thus, needs to be isolated.
+                For example, board-specific incompatibilities would require different functionality
+                and would require a branch to separate the features.
+                Likewise, for specific kernel features, the same branching strategy is used.
+            </para>
+            <para>
+                This branching strategy results in a tree that has features organized to be specific
+                for particular functionality, single kernel types, or a subset of kernel types.
+                This strategy also results in not having to store the same feature twice
+                internally in the tree.
+                Rather, the kernel team stores the unique differences required to apply the
+                feature onto the kernel type in question.
+                <note>
+                    The Yocto Project team strives to place features in the tree such that they can be
+                    shared by all boards and kernel types where possible.
+                    However, during development cycles or when large features are merged,
+                    the team cannot always follow this practice.
+                    In those cases, the team uses isolated branches to merge features.
+                </note>
+            </para>
+            <para>
+                BSP-specific code additions are handled in a similar manner to kernel-specific additions.
+                Some BSPs only make sense given certain kernel types.
+                So, for these types, the team creates branches off the end of that kernel type for all
+                of the BSPs that are supported on that kernel type.
+                From the perspective of the tools that create the BSP branch, the BSP is really no
+                different than a feature.
+                Consequently, the same branching strategy applies to BSPs as it does to features.
+                So again, rather than store the BSP twice, the team only stores the unique
+                differences for the BSP across the supported multiple kernels.
+            </para>
+            <para>
+                While this strategy can result in a tree with a significant number of branches, it is
+                important to realize that from the developer's point of view, there is a linear
+                path that travels from the baseline <filename>kernel.org</filename>, through a select
+                group of features and ends with their BSP-specific commits.
+                In other words, the divisions of the kernel are transparent and are not relevant
+                to the developer on a day-to-day basis.
+                From the developer's perspective, this path is the "master" branch.
+                The developer does not need to be aware of the existence of any other branches at all.
+                Of course, there is value in the existence of these branches
+                in the tree, should a person decide to explore them.
+                For example, a comparison between two BSPs at either the commit level or at the line-by-line
+                code <filename>diff</filename> level is now a trivial operation.
+            </para>
+            <para>
+                Working with the kernel as a structured tree follows recognized community best practices.
+                In particular, the kernel as shipped with the product, should be
+                considered an "upstream source" and viewed as a series of
+                historical and documented modifications (commits).
+                These modifications represent the development and stabilization done
+                by the Yocto Project kernel development team.
+            </para>
+            <para>
+                Because commits only change at significant release points in the product life cycle,
+                developers can work on a branch created
+                from the last relevant commit in the shipped Yocto Project kernel.
+                As mentioned previously, the structure is transparent to the developer
+                because the kernel tree is left in this state after cloning and building the kernel.
+            </para>
+        </section>
+
+        <section id='source-code-manager-git'>
+            <title>Source Code Manager - Git</title>
+            <para>
+                The Source Code Manager (SCM) is Git.
+                This SCM is the obvious mechanism for meeting the previously mentioned goals.
+                Not only is it the SCM for <filename>kernel.org</filename> but,
+                Git continues to grow in popularity and supports many different work flows,
+                front-ends and management techniques.
+            </para>
+            <para>
+                You can find documentation on Git at <ulink url='http://git-scm.com/documentation'></ulink>.
+                You can also get an introduction to Git as it applies to the Yocto Project in the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
+                section in the Yocto Project Development Manual.
+                These referenced sections overview Git and describe a minimal set of
+                commands that allows you to be functional using Git.
+                <note>
+                    You can use as much, or as little, of what Git has to offer to accomplish what
+                    you need for your project.
+                    You do not have to be a "Git Master" in order to use it with the Yocto Project.
+                </note>
+            </para>
+        </section>
+    </section>
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-customization.xsl b/documentation/kernel-dev/kernel-dev-customization.xsl
new file mode 100644
index 0000000000..43e9dadf21
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-customization.xsl
@@ -0,0 +1,11 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+  <xsl:param name="html.stylesheet" select="'kernel-dev-style.css'" />
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel">A</xsl:param>
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl
new file mode 100644
index 0000000000..7d1bb8dc08
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-eclipse-customization.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+        xmlns="http://www.w3.org/1999/xhtml"
+        xmlns:fo="http://www.w3.org/1999/XSL/Format"
+        version="1.0">
+
+  <xsl:import
+          href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="chunk.quietly" select="1"/>
+  <xsl:param name="chunk.first.sections" select="1"/>
+  <xsl:param name="chunk.section.depth" select="10"/>
+  <xsl:param name="use.id.as.filename" select="1"/>
+  <xsl:param name="ulink.target" select="'_self'" />
+  <xsl:param name="base.dir" select="'html/kernel-dev/'"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel">A</xsl:param>
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/kernel-dev/kernel-dev-examples.xml b/documentation/kernel-dev/kernel-dev-examples.xml
new file mode 100644
index 0000000000..9d9aef6d06
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-examples.xml
@@ -0,0 +1,918 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-how-to'>
+
+<title>Working with the Yocto Project Kernel</title>
+
+
+<section id='actions-org'>
+    <title>Introduction</title>
+    <para>
+        This chapter describes how to accomplish tasks involving a kernel's tree structure.
+        The information is designed to help the developer that wants to modify the Yocto
+        Project kernel and contribute changes upstream to the Yocto Project.
+        The information covers the following:
+        <itemizedlist>
+            <listitem><para>Tree construction</para></listitem>
+            <listitem><para>Build strategies</para></listitem>
+            <listitem><para>Workflow examples</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+    <section id='tree-construction'>
+        <title>Tree Construction</title>
+        <para>
+            This section describes construction of the Yocto Project kernel source repositories
+            as accomplished by the Yocto Project team to create kernel repositories.
+            These kernel repositories are found under the heading "Yocto Linux Kernel" at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
+            and can be shipped as part of a Yocto Project release.
+            The team creates these repositories by
+            compiling and executing the set of feature descriptions for every BSP/feature
+            in the product.
+            Those feature descriptions list all necessary patches,
+            configuration, branching, tagging and feature divisions found in a kernel.
+            Thus, the Yocto Project kernel repository (or tree) is built.
+        </para>
+        <para>
+            The existence of this tree allows you to access and clone a particular
+            Yocto Project kernel repository and use it to build images based on their configurations
+            and features.
+        </para>
+        <para>
+            You can find the files used to describe all the valid features and BSPs
+            in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
+            Git tree.
+            For example, the following command clones the Yocto Project baseline kernel that
+            branched off of <filename>linux.org</filename> version 3.4:
+            <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/linux-yocto-3.4
+            </literallayout>
+            For another example of how to set up a local Git repository of the Yocto Project
+            kernel files, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
+            item in the Yocto Project Development Manual.
+        </para>
+        <para>
+            Once you have cloned the kernel Git repository on your local machine, you can
+            switch to the <filename>meta</filename> branch within the repository.
+            Here is an example that assumes the local Git repository for the kernel is in
+            a top-level directory named <filename>linux-yocto-3.4</filename>:
+            <literallayout class='monospaced'>
+     $ cd ~/linux-yocto-3.4
+     $ git checkout -b meta origin/meta
+            </literallayout>
+            Once you have checked out and switched to the <filename>meta</filename> branch,
+            you can see a snapshot of all the kernel configuration and feature descriptions that are
+            used to build that particular kernel repository.
+            These descriptions are in the form of <filename>.scc</filename> files.
+        </para>
+        <para>
+            You should realize, however, that browsing your local kernel repository
+            for feature descriptions and patches is not an effective way to determine what is in a
+            particular kernel branch.
+            Instead, you should use Git directly to discover the changes in a branch.
+            Using Git is an efficient and flexible way to inspect changes to the kernel.
+            For examples showing how to use Git to inspect kernel commits, see the following sections
+            in this chapter.
+            <note>
+                Ground up reconstruction of the complete kernel tree is an action only taken by the
+                Yocto Project team during an active development cycle.
+                When you create a clone of the kernel Git repository, you are simply making it
+                efficiently available for building and development.
+            </note>
+        </para>
+        <para>
+            The following steps describe what happens when the Yocto Project Team constructs
+            the Yocto Project kernel source Git repository (or tree) found at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
+            introduction of a new top-level kernel feature or BSP.
+            These are the actions that effectively create the tree
+            that includes the new feature, patch or BSP:
+            <orderedlist>
+                <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
+                    Normally, this feature is a BSP for a particular kernel type.</para></listitem>
+                <listitem><para>The file that describes the top-level feature is located by searching
+                    these system directories:
+                    <itemizedlist>
+                        <listitem><para>The in-tree kernel-cache directories, which are located
+                            in <filename>meta/cfg/kernel-cache</filename></para></listitem>
+                        <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
+                            found in recipes</para></listitem>
+                    </itemizedlist>
+                    For a typical build, the target of the search is a
+                    feature description in an <filename>.scc</filename> file
+                    whose name follows this format:
+                    <literallayout class='monospaced'>
+     &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
+                    </literallayout>
+                </para></listitem>
+                <listitem><para>Once located, the feature description is either compiled into a simple script
+                    of actions, or into an existing equivalent script that is already part of the
+                    shipped kernel.</para></listitem>
+                <listitem><para>Extra features are appended to the top-level feature description.
+                    These features can come from the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
+                    variable in recipes.</para></listitem>
+                <listitem><para>Each extra feature is located, compiled and appended to the script
+                    as described in step three.</para></listitem>
+                <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
+                    directories.
+                    These directories are descriptions of all the branches, tags, patches and configurations that
+                    need to be applied to the base Git repository to completely create the
+                    source (build) branch for the new BSP or feature.</para></listitem>
+                <listitem><para>The base repository is cloned, and the actions
+                    listed in the <filename>meta-*</filename> directories are applied to the
+                    tree.</para></listitem>
+                <listitem><para>The Git repository is left with the desired branch checked out and any
+                    required branching, patching and tagging has been performed.</para></listitem>
+            </orderedlist>
+        </para>
+        <para>
+            The kernel tree is now ready for developer consumption to be locally cloned,
+            configured, and built into a Yocto Project kernel specific to some target hardware.
+            <note><para>The generated <filename>meta-*</filename> directories add to the kernel
+                as shipped with the Yocto Project release.
+                Any add-ons and configuration data are applied to the end of an existing branch.
+                The full repository generation that is found in the
+                official Yocto Project kernel repositories at
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
+                is the combination of all supported boards and configurations.</para>
+                <para>The technique the Yocto Project team uses is flexible and allows for seamless
+                blending of an immutable history with additional patches specific to a
+                deployment.
+                Any additions to the kernel become an integrated part of the branches.</para>
+            </note>
+        </para>
+    </section>
+
+    <section id='build-strategy'>
+        <title>Build Strategy</title>
+        <para>
+            Once a local Git repository of the Yocto Project kernel exists on a development system,
+            you can consider the compilation phase of kernel development - building a kernel image.
+            Some prerequisites exist that are validated by the build process before compilation
+            starts:
+        </para>
+
+        <itemizedlist>
+            <listitem><para>The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
+                to the kernel Git repository.</para></listitem>
+            <listitem><para>A BSP build branch exists.
+                This branch has the following form:
+                <literallayout class='monospaced'>
+     &lt;kernel_type&gt;/&lt;bsp_name&gt;
+                </literallayout></para></listitem>
+        </itemizedlist>
+
+        <para>
+            The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
+            Other means, however, do exist, such as as bootstrapping a BSP, see
+            the "<link linkend='workflow-examples'>Workflow Examples</link>".
+        </para>
+
+        <para>
+            Before building a kernel, the build process verifies the tree
+            and configures the kernel by processing all of the
+            configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
+            files.
+            As the features are compiled, associated kernel configuration fragments are noted
+            and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
+            The fragments are migrated, pre-processed and passed to the Linux Kernel
+            Configuration subsystem (<filename>lkc</filename>) as raw input in the form
+            of a <filename>.config</filename> file.
+            The <filename>lkc</filename> uses its own internal dependency constraints to do the final
+            processing of that information and generates the final <filename>.config</filename> file
+            that is used during compilation.
+        </para>
+
+        <para>
+            Using the board's architecture and other relevant values from the board's template,
+            kernel compilation is started and a kernel image is produced.
+        </para>
+
+        <para>
+            The other thing that you notice once you configure a kernel is that
+            the build process generates a build tree that is separate from your kernel's local Git
+            source repository tree.
+            This build tree has a name that uses the following form, where
+            <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
+            of the Yocto Project supported kernel types (e.g. "standard"):
+        <literallayout class='monospaced'>
+     linux-${MACHINE}-&lt;kernel_type&gt;-build
+        </literallayout>
+        </para>
+
+        <para>
+            The existing support in the <filename>kernel.org</filename> tree achieves this
+            default functionality.
+        </para>
+
+        <para>
+            This behavior means that all the generated files for a particular machine or BSP are now in
+            the build tree directory.
+            The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
+            files, the <filename>.a</filename> files, and so forth.
+            Since each machine or BSP has its own separate build directory in its own separate branch
+            of the Git repository, you can easily switch between different builds.
+        </para>
+    </section>
+
+    <section id='workflow-examples'>
+        <title>Workflow Examples</title>
+
+        <para>
+            As previously noted, the Yocto Project kernel has built-in Git integration.
+            However, these utilities are not the only way to work with the kernel repository.
+            The Yocto Project has not made changes to Git or to other tools that
+            would invalidate alternate workflows.
+            Additionally, the way the kernel repository is constructed results in using
+            only core Git functionality, thus allowing any number of tools or front ends to use the
+            resulting tree.
+        </para>
+
+        <para>
+            This section contains several workflow examples.
+            Many of the examples use Git commands.
+            You can find Git documentation at
+            <ulink url='http://git-scm.com/documentation'></ulink>.
+            You can find a simple overview of using Git with the Yocto Project in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink>"
+            section of the Yocto Project Development Manual.
+        </para>
+
+        <section id='change-inspection-kernel-changes-commits'>
+            <title>Change Inspection: Changes/Commits</title>
+
+            <para>
+                A common question when working with a kernel is:
+                "What changes have been applied to this tree?"
+            </para>
+
+            <para>
+                In projects that have a collection of directories that
+                contain patches to the kernel, it is possible to inspect or "grep" the contents
+                of the directories to get a general feel for the changes.
+                This sort of patch inspection is not an efficient way to determine what has been
+                done to the kernel.
+                The reason it is inefficient is because there are many optional patches that are
+                selected based on the kernel type and the feature description.
+                Additionally, patches could exist in directories that are not included in the search.
+            </para>
+
+            <para>
+                A more efficient way to determine what has changed in the branch is to use
+                Git and inspect or search the kernel tree.
+                This method gives you a full view of not only the source code modifications,
+                but also provides the reasons for the changes.
+            </para>
+
+            <section id='what-changed-in-a-kernel'>
+                <title>What Changed in a Kernel?</title>
+
+                <para>
+                    Following are a few examples that show how to use Git commands to examine changes.
+                    Because Git repositories in the Yocto Project do not break existing Git
+                    functionality, and because there exists many permutations of these types of
+                    Git commands, many methods exist by which you can discover changes.
+                    <note>
+                        In the following examples, unless you provide a commit range,
+                        <filename>kernel.org</filename> history is blended with Yocto Project
+                        kernel changes.
+                        You can form ranges by using branch names from the kernel tree as the
+                        upper and lower commit markers with the Git commands.
+                        You can see the branch names through the web interface to the
+                        Yocto Project source repositories at
+                        <ulink url='http://git.yoctoproject.org/cgit.cgi'></ulink>.
+                        For example, the branch names for the <filename>linux-yocto-3.4</filename>
+                        kernel repository can be seen at
+                        <ulink url='http://git.yoctoproject.org/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
+                    </note>
+                    To see a full range of the changes, use the
+                    <filename>git whatchanged</filename> command and specify a commit range
+                    for the branch (<filename>&lt;commit&gt;..&lt;commit&gt;</filename>).
+                </para>
+
+                <para>
+                    Here is an example that looks at what has changed in the
+                    <filename>emenlow</filename> branch of the
+                    <filename>linux-yocto-3.4</filename> kernel.
+                    The lower commit range is the commit associated with the
+                    <filename>standard/base</filename> branch, while
+                    the upper commit range is the commit associated with the
+                    <filename>standard/emenlow</filename> branch.
+                    <literallayout class='monospaced'>
+     $ git whatchanged origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+
+                <para>
+                    To see a summary of changes use the <filename>git log</filename> command.
+                    Here is an example using the same branches:
+                    <literallayout class='monospaced'>
+     $ git log --oneline origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                    The <filename>git log</filename> output might be more useful than
+                    the <filename>git whatchanged</filename> as you get
+                    a short, one-line summary of each change and not the entire commit.
+                </para>
+
+                <para>
+                    If you want to see code differences associated with all the changes, use
+                    the <filename>git diff</filename> command.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ git diff origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can see the commit log messages and the text differences using the
+                    <filename>git show</filename> command:
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ git show origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can create individual patches for each change by using the
+                    <filename>git format-patch</filename> command.
+                    Here is an example that that creates patch files for each commit and
+                    places them in your <filename>Documents</filename> directory:
+                    <literallayout class='monospaced'>
+     $ git format-patch -o $HOME/Documents origin/standard/base..origin/standard/emenlow
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='show-a-particular-feature-or-branch-change'>
+                <title>Show a Particular Feature or Branch Change</title>
+
+                <para>
+                    Developers use tags in the Yocto Project kernel tree to divide changes for significant
+                    features or branches.
+                    Once you know a particular tag, you can use Git commands
+                    to show changes associated with the tag and find the branches that contain
+                    the feature.
+                    <note>
+                        Because BSP branch, <filename>kernel.org</filename>, and feature tags are all
+                        present, there could be many tags.
+                    </note>
+                    The <filename>git show &lt;tag&gt;</filename> command shows changes that are tagged by
+                    a feature.
+                    Here is an example that shows changes tagged by the <filename>systemtap</filename>
+                    feature:
+                    <literallayout class='monospaced'>
+     $ git show systemtap
+                    </literallayout>
+                    You can use the <filename>git branch --contains &lt;tag&gt;</filename> command
+                    to show the branches that contain a particular feature.
+                    This command shows the branches that contain the <filename>systemtap</filename>
+                    feature:
+                    <literallayout class='monospaced'>
+     $ git branch --contains systemtap
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can use many other comparisons to isolate BSP and kernel changes.
+                    For example, you can compare against <filename>kernel.org</filename> tags
+                    such as the <filename>v3.4</filename> tag.
+                </para>
+            </section>
+        </section>
+
+        <section id='development-saving-kernel-modifications'>
+            <title>Development: Saving Kernel Modifications</title>
+
+            <para>
+                Another common operation is to build a BSP supplied by the Yocto Project, make some
+                changes, rebuild, and then test.
+                Those local changes often need to be exported, shared or otherwise maintained.
+            </para>
+
+            <para>
+                Since the Yocto Project kernel source tree is backed by Git, this activity is
+                much easier as compared to with previous releases.
+                Because Git tracks file modifications, additions and deletions, it is easy
+                to modify the code and later realize that you need to save the changes.
+                It is also easy to determine what has changed.
+                This method also provides many tools to commit, undo and export those modifications.
+            </para>
+
+            <para>
+                This section and its sub-sections, describe general application of Git's
+                <filename>push</filename> and <filename>pull</filename> commands, which are used to
+                get your changes upstream or source your code from an upstream repository.
+                The Yocto Project provides scripts that help you work in a collaborative development
+                environment.
+                For information on these scripts, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#pushing-a-change-upstream'>Using Scripts to Push a Change
+                Upstream and Request a Pull</ulink>" and
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-patch'>Using Email to Submit a Patch</ulink>"
+                sections in the Yocto Project Development Manual.
+            </para>
+
+            <para>
+                There are many ways to save kernel modifications.
+                The technique employed
+                depends on the destination for the patches:
+
+                <itemizedlist>
+                    <listitem><para>Bulk storage</para></listitem>
+                    <listitem><para>Internal sharing either through patches or by using Git</para></listitem>
+                    <listitem><para>External submissions</para></listitem>
+                    <listitem><para>Exporting for integration into another Source Code
+                        Manager (SCM)</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Because of the following list of issues, the destination of the patches also influences
+                the method for gathering them:
+
+                <itemizedlist>
+                    <listitem><para>Bisectability</para></listitem>
+                    <listitem><para>Commit headers</para></listitem>
+                    <listitem><para>Division of subsystems for separate submission or review</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <section id='bulk-export'>
+                <title>Bulk Export</title>
+
+                <para>
+                    This section describes how you can "bulk" export changes that have not
+                    been separated or divided.
+                    This situation works well when you are simply storing patches outside of the kernel
+                    source repository, either permanently or temporarily, and you are not committing
+                    incremental changes during development.
+                    <note>
+                        This technique is not appropriate for full integration of upstream submission
+                        because changes are not properly divided and do not provide an avenue for per-change
+                        commit messages.
+                        Therefore, this example assumes that changes have not been committed incrementally
+                        during development and that you simply must gather and export them.
+                    </note>
+                    <literallayout class='monospaced'>
+     # bulk export of ALL modifications without separation or division
+     # of the changes
+
+     $ git add .
+     $ git commit -s -a -m &lt;msg&gt;
+        or
+     $ git commit -s -a # and interact with $EDITOR
+                    </literallayout>
+                </para>
+
+                <para>
+                    The previous operations capture all the local changes in the project source
+                    tree in a single Git commit.
+                    And, that commit is also stored in the project's source tree.
+                </para>
+
+                <para>
+                    Once the changes are exported, you can restore them manually using a template
+                    or through integration with the <filename>default_kernel</filename>.
+                </para>
+
+            </section>
+
+            <section id='incremental-planned-sharing'>
+                <title>Incremental/Planned Sharing</title>
+
+                <para>
+                    This section describes how to save modifications when you are making incremental
+                    commits or practicing planned sharing.
+                    The examples in this section assume that you have incrementally committed
+                    changes to the tree during development and now need to export them.
+                    The sections that follow
+                    describe how you can export your changes internally through either patches or by
+                    using Git commands.
+                </para>
+
+                <para>
+                    During development, the following commands are of interest.
+                    For full Git documentation, refer to the Git documentation at
+                    <ulink url='http://github.com'></ulink>.
+
+                    <literallayout class='monospaced'>
+     # edit a file
+     $ vi &lt;path&gt;/file
+     # stage the change
+     $ git add &lt;path&gt;/file
+     # commit the change
+     $ git commit -s
+     # remove a file
+     $ git rm &lt;path&gt;/file
+     # commit the change
+     $ git commit -s
+
+     ... etc.
+                    </literallayout>
+                </para>
+
+                <para>
+                    Distributed development with Git is possible when you use a universally
+                    agreed-upon unique commit identifier (set by the creator of the commit) that maps to a
+                    specific change set with a specific parent.
+                    This identifier is created for you when
+                    you create a commit, and is re-created when you amend, alter or re-apply
+                    a commit.
+                    As an individual in isolation, this is of no interest.
+                    However, if you
+                    intend to share your tree with normal Git <filename>push</filename> and
+                    <filename>pull</filename> operations for
+                    distributed development, you should consider the ramifications of changing a
+                    commit that you have already shared with others.
+                </para>
+
+                <para>
+                    Assuming that the changes have not been pushed upstream, or pulled into
+                    another repository, you can update both the commit content and commit messages
+                    associated with development by using the following commands:
+
+                    <literallayout class='monospaced'>
+     $ Git add &lt;path&gt;/file
+     $ Git commit --amend
+     $ Git rebase or Git rebase -i
+                    </literallayout>
+                </para>
+
+                <para>
+                    Again, assuming that the changes have not been pushed upstream, and that
+                    no pending works-in-progress exist (use <filename>git status</filename> to check), then
+                    you can revert (undo) commits by using the following commands:
+
+                    <literallayout class='monospaced'>
+     # remove the commit, update working tree and remove all
+     # traces of the change
+     $ git reset --hard HEAD^
+     # remove the commit, but leave the files changed and staged for re-commit
+     $ git reset --soft HEAD^
+     # remove the commit, leave file change, but not staged for commit
+     $ git reset --mixed HEAD^
+                    </literallayout>
+                </para>
+
+                <para>
+                    You can create branches, "cherry-pick" changes, or perform any number of Git
+                    operations until the commits are in good order for pushing upstream
+                    or for pull requests.
+                    After a <filename>push</filename> or <filename>pull</filename> command,
+                    commits are normally considered
+                    "permanent" and you should not modify them.
+                    If the commits need to be changed, you can incrementally do so with new commits.
+                    These practices follow standard Git workflow and the <filename>kernel.org</filename> best
+                    practices, which is recommended.
+                    <note>
+                        It is recommended to tag or branch before adding changes to a Yocto Project
+                        BSP or before creating a new one.
+                        The reason for this recommendation is because the branch or tag provides a
+                        reference point to facilitate locating and exporting local changes.
+                    </note>
+                </para>
+
+                <section id='export-internally-via-patches'>
+                    <title>Exporting Changes Internally by Using Patches</title>
+
+                    <para>
+                        This section describes how you can extract committed changes from a working directory
+                        by exporting them as patches.
+                        Once the changes have been extracted, you can use the patches for upstream submission,
+                        place them in a Yocto Project template for automatic kernel patching,
+                        or apply them in many other common uses.
+                    </para>
+
+                    <para>
+                        This example shows how to create a directory with sequentially numbered patches.
+                        Once the directory is created, you can apply it to a repository using the
+                        <filename>git am</filename> command to reproduce the original commit and all
+                        the related information such as author, date, commit log, and so forth.
+                        <note>
+                            The new commit identifiers (ID) will be generated upon re-application.
+                            This action reflects that the commit is now applied to an underlying commit
+                            with a different ID.
+                        </note>
+                        <literallayout class='monospaced'>
+     # &lt;first-commit&gt; can be a tag if one was created before development
+     # began. It can also be the parent branch if a branch was created
+     # before development began.
+
+     $ git format-patch -o &lt;dir&gt; &lt;first commit&gt;..&lt;last commit&gt;
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        In other words:
+                        <literallayout class='monospaced'>
+     # Identify commits of interest.
+
+     # If the tree was tagged before development
+     $ git format-patch -o &lt;save dir&gt; &lt;tag&gt;
+
+     # If no tags are available
+     $ git format-patch -o &lt;save dir&gt; HEAD^  # last commit
+     $ git format-patch -o &lt;save dir&gt; HEAD^^ # last 2 commits
+     $ git whatchanged # identify last commit
+     $ git format-patch -o &lt;save dir&gt; &lt;commit id&gt;
+     $ git format-patch -o &lt;save dir&gt; &lt;rev-list&gt;
+                        </literallayout>
+                    </para>
+                </section>
+
+                <section id='export-internally-via-git'>
+                    <title>Exporting Changes Internally by Using Git</title>
+
+                    <para>
+                        This section describes how you can export changes from a working directory
+                        by pushing the changes into a master repository or by making a pull request.
+                        Once you have pushed the changes to the master repository, you can then
+                        pull those same changes into a new kernel build at a later time.
+                    </para>
+
+                    <para>
+                        Use this command form to push the changes:
+                        <literallayout class='monospaced'>
+     $ git push ssh://&lt;master_server&gt;/&lt;path_to_repo&gt;
+        &lt;local_branch&gt;:&lt;remote_branch&gt;
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        For example, the following command pushes the changes from your local branch
+                        <filename>yocto/standard/common-pc/base</filename> to the remote branch with the same name
+                        in the master repository <filename>//git.mycompany.com/pub/git/kernel-3.4</filename>.
+                        <literallayout class='monospaced'>
+     $ git push ssh://git.mycompany.com/pub/git/kernel-3.4 \
+        yocto/standard/common-pc/base:yocto/standard/common-pc/base
+                        </literallayout>
+                    </para>
+
+                    <para>
+                        A pull request entails using the <filename>git request-pull</filename> command to compose
+                        an email to the
+                        maintainer requesting that a branch be pulled into the master repository, see
+                        <ulink url='http://github.com/guides/pull-requests'></ulink> for an example.
+                        <note>
+                            Other commands such as <filename>git stash</filename> or branching can also be used to save
+                            changes, but are not covered in this document.
+                        </note>
+                    </para>
+                </section>
+            </section>
+
+            <section id='export-for-external-upstream-submission'>
+                <title>Exporting Changes for External (Upstream) Submission</title>
+
+                <para>
+                    This section describes how to export changes for external upstream submission.
+                    If the patch series is large or the maintainer prefers to pull
+                    changes, you can submit these changes by using a pull request.
+                    However, it is common to send patches as an email series.
+                    This method allows easy review and integration of the changes.
+                    <note>
+                        Before sending patches for review be sure you understand the
+                        community standards for submitting and documenting changes and follow their best practices.
+                        For example, kernel patches should follow standards such as:
+                        <itemizedlist>
+                            <listitem><para>
+                                <ulink url='http://linux.yyz.us/patch-format.html'></ulink></para></listitem>
+                            <listitem><para>Documentation/SubmittingPatches (in any linux
+                                kernel source tree)</para></listitem>
+                        </itemizedlist>
+                    </note>
+                </para>
+
+                <para>
+                    The messages used to commit changes are a large part of these standards.
+                    Consequently, be sure that the headers for each commit have the required information.
+                    For information on how to follow the Yocto Project commit message standards, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a
+                    Change</ulink>" section in the Yocto Project Development Manual.
+                </para>
+
+                <para>
+                    If the initial commits were not properly documented or do not meet those standards,
+                    you can re-base by using the <filename>git rebase -i</filename> command to
+                    manipulate the commits and
+                    get them into the required format.
+                    Other techniques such as branching and cherry-picking commits are also viable options.
+                </para>
+
+                <para>
+                    Once you complete the commits, you can generate the email that sends the patches
+                    to the maintainer(s) or lists that review and integrate changes.
+                    The command <filename>git send-email</filename> is commonly used to ensure
+                    that patches are properly
+                    formatted for easy application and avoid mailer-induced patch damage.
+                </para>
+
+                <para>
+                    The following is an example of dumping patches for external submission:
+                    <literallayout class='monospaced'>
+     # dump the last 4 commits
+     $ git format-patch --thread -n -o ~/rr/ HEAD^^^^
+     $ git send-email --compose --subject '[RFC 0/N] &lt;patch series summary&gt;' \
+      --to foo@yoctoproject.org --to bar@yoctoproject.org \
+      --cc list@yoctoproject.org  ~/rr
+     # the editor is invoked for the 0/N patch, and when complete the entire
+     # series is sent via email for review
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='export-for-import-into-other-scm'>
+                <title>Exporting Changes for Import into Another SCM</title>
+
+                <para>
+                    When you want to export changes for import into another
+                    Source Code Manager (SCM), you can use any of the previously discussed
+                    techniques.
+                    However, if the patches are manually applied to a secondary tree and then
+                    that tree is checked into the SCM, you can lose change information such as
+                    commit logs.
+                    This process is not recommended.
+                </para>
+
+                <para>
+                    Many SCMs can directly import Git commits, or can translate Git patches so that
+                    information is not lost.
+                    Those facilities are SCM-dependent and you should use them whenever possible.
+                </para>
+            </section>
+        </section>
+
+        <section id='scm-working-with-the-yocto-project-kernel-in-another-scm'>
+            <title>Working with the Yocto Project Kernel in Another SCM</title>
+
+            <para>
+                This section describes kernel development in an SCM other than Git,
+                which is not the same as exporting changes to another SCM described earlier.
+                For this scenario, you use the OpenEmbedded build system to
+                develop the kernel in a different SCM.
+                The following must be true for you to accomplish this:
+                <itemizedlist>
+                    <listitem><para>The delivered Yocto Project kernel must be exported into the second
+                        SCM.</para></listitem>
+                    <listitem><para>Development must be exported from that secondary SCM into a
+                        format that can be used by the OpenEmbedded build system.</para></listitem>
+                </itemizedlist>
+            </para>
+
+            <section id='exporting-delivered-kernel-to-scm'>
+                <title>Exporting the Delivered Kernel to the SCM</title>
+
+                <para>
+                    Depending on the SCM, it might be possible to export the entire Yocto Project
+                    kernel Git repository, branches and all, into a new environment.
+                    This method is preferred because it has the most flexibility and potential to maintain
+                    the meta data associated with each commit.
+                </para>
+
+                <para>
+                    When a direct import mechanism is not available, it is still possible to
+                    export a branch (or series of branches) and check them into a new repository.
+                </para>
+
+                <para>
+                    The following commands illustrate some of the steps you could use to
+                    import the <filename>yocto/standard/common-pc/base</filename>
+                    kernel into a secondary SCM:
+                    <literallayout class='monospaced'>
+     $ git checkout yocto/standard/common-pc/base
+     $ cd .. ; echo linux/.git &gt; .cvsignore
+     $ cvs import -m "initial import" linux MY_COMPANY start
+                    </literallayout>
+                </para>
+
+                <para>
+                    You could now relocate the CVS repository and use it in a centralized manner.
+                </para>
+
+                <para>
+                    The following commands illustrate how you can condense and merge two BSPs into a
+                    second SCM:
+                    <literallayout class='monospaced'>
+     $ git checkout yocto/standard/common-pc/base
+     $ git merge yocto/standard/common-pc-64/base
+     # resolve any conflicts and commit them
+     $ cd .. ; echo linux/.git &gt; .cvsignore
+     $ cvs import -m "initial import" linux MY_COMPANY start
+                    </literallayout>
+                </para>
+            </section>
+
+            <section id='importing-changes-for-build'>
+                <title>Importing Changes for the Build</title>
+
+                <para>
+                    Once development has reached a suitable point in the second development
+                    environment, you need to export the changes as patches.
+                    To export them, place the changes in a recipe and
+                    automatically apply them to the kernel during patching.
+                </para>
+            </section>
+        </section>
+
+        <section id='bsp-creating'>
+            <title>Creating a BSP Based on an Existing Similar BSP</title>
+
+            <para>
+                This section overviews the process of creating a BSP based on an
+                existing similar BSP.
+                The information is introductory in nature and does not provide step-by-step examples.
+                For detailed information on how to create a new BSP, see
+                the "<ulink url='&YOCTO_DOCS_BSP_URL;#creating-a-new-bsp-layer-using-the-yocto-bsp-script'>Creating a New BSP Layer Using the yocto-bsp Script</ulink>" section in the
+                Yocto Project Board Support Package (BSP) Developer's Guide, or see the
+                <ulink url='&YOCTO_WIKI_URL;/wiki/Transcript:_creating_one_generic_Atom_BSP_from_another'>Transcript:_creating_one_generic_Atom_BSP_from_another</ulink>
+                wiki page.
+            </para>
+
+            <para>
+                The basic steps you need to follow are:
+                <orderedlist>
+                    <listitem><para><emphasis>Make sure you have set up a local Source Directory:</emphasis>
+                        You must create a local
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                        by either creating a Git repository (recommended) or
+                        extracting a Yocto Project release tarball.</para></listitem>
+                    <listitem><para><emphasis>Choose an existing BSP available with the Yocto Project:</emphasis>
+                        Try to map your board features as closely to the features of a BSP that is
+                        already supported and exists in the Yocto Project.
+                        Starting with something as close as possible to your board makes developing
+                        your BSP easier.
+                        You can find all the BSPs that are supported and ship with the Yocto Project
+                        on the Yocto Project's Download page at
+                        <ulink url='&YOCTO_HOME_URL;/download'></ulink>.</para></listitem>
+                    <listitem><para><emphasis>Be sure you have the Base BSP:</emphasis>
+                        You need to either have a local Git repository of the base BSP set up or
+                        have downloaded and extracted the files from a release BSP tarball.
+                        Either method gives you access to the BSP source files.</para></listitem>
+                    <listitem><para><emphasis>Make a copy of the existing BSP, thus isolating your new
+                        BSP work:</emphasis>
+                        Copying the existing BSP file structure gives you a new area in which to work.</para></listitem>
+                    <listitem><para><emphasis>Make configuration and recipe changes to your new BSP:</emphasis>
+                        Configuration changes involve the files in the BSP's <filename>conf</filename>
+                        directory.
+                        Changes include creating a machine-specific configuration file and editing the
+                        <filename>layer.conf</filename> file.
+                        The configuration changes identify the kernel you will be using.
+                        Recipe changes include removing, modifying, or adding new recipe files that
+                        instruct the build process on what features to include in the image.</para></listitem>
+                    <listitem><para><emphasis>Prepare for the build:</emphasis>
+                        Before you actually initiate the build, you need to set up the build environment
+                        by sourcing the environment initialization script.
+                        After setting up the environment, you need to make some build configuration
+                        changes to the <filename>local.conf</filename> and <filename>bblayers.conf</filename>
+                        files.</para></listitem>
+                    <listitem><para><emphasis>Build the image:</emphasis>
+                        The OpenEmbedded build system uses BitBake to create the image.
+                        You need to decide on the type of image you are going to build (e.g. minimal, base,
+                        core, sato, and so forth) and then start the build using the <filename>bitbake</filename>
+                        command.</para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+
+        <section id='tip-dirty-string'>
+            <title>"-dirty" String</title>
+
+            <para>
+                If kernel images are being built with "-dirty" on the end of the version
+                string, this simply means that modifications in the source
+                directory have not been committed.
+                <literallayout class='monospaced'>
+     $ git status
+                </literallayout>
+            </para>
+
+            <para>
+                You can use the above Git command to report modified, removed, or added files.
+                You should commit those changes to the tree regardless of whether they will be saved,
+                exported, or used.
+                Once you commit the changes you need to rebuild the kernel.
+            </para>
+
+            <para>
+                To brute force pickup and commit all such pending changes, enter the following:
+                <literallayout class='monospaced'>
+     $ git add .
+     $ git commit -s -a -m "getting rid of -dirty"
+                </literallayout>
+            </para>
+
+            <para>
+                Next, rebuild the kernel.
+            </para>
+        </section>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-faq.xml b/documentation/kernel-dev/kernel-dev-faq.xml
new file mode 100644
index 0000000000..7389c9c9c5
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-faq.xml
@@ -0,0 +1,131 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<appendix id='kernel-dev-faq'>
+<title>Kernel Development FAQ</title>
+<qandaset>
+    <qandaentry>
+        <question>
+            <para>
+                How do I use my own Linux kernel <filename>.config</filename>
+                file?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Refer to the "<link linkend='changing-the-configuration'>Changing the Configuration</link>"
+                section for information.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I create configuration fragments?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Refer to the "<link linkend='generating-configuration-files'>Generating Configuration Files</link>"
+                section for information.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I use my own Linux kernel sources?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Refer to the "<link linkend='working-with-your-own-sources'>Working With Your Own Sources</link>"
+                section for information.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I install/not-install the kernel image on the rootfs?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The kernel image (e.g. <filename>vmlinuz</filename>) is provided
+                by the <filename>kernel-image</filename> package.
+                Image recipes depend on <filename>kernel-base</filename>.
+                To specify whether or not the kernel
+                image is installed in the generated root filesystem, override
+                <filename>RDEPENDS_kernel-base</filename> to include or not
+                include "kernel-image".</para>
+                <para>See the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
+                section in the Yocto Project Development Manual for information on
+                how to use an append file to override metadata.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I install a specific kernel module?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Linux kernel modules are packaged individually.
+                To ensure a specific kernel module is included in an image,
+                include it in the appropriate machine
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-RRECOMMENDS'><filename>RRECOMMENDS</filename></ulink>
+                variable.</para>
+                <para>These other variables are useful for installing specific
+                modules:
+                <literallayout class='monospaced'>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</filename></ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><filename>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</filename></ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RDEPENDS'><filename>MACHINE_EXTRA_RDEPENDS</filename></ulink>
+     <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE_EXTRA_RRECOMMENDS'><filename>MACHINE_EXTRA_RRECOMMENDS</filename></ulink>
+                </literallayout>
+                For example, set the following in the <filename>qemux86.conf</filename>
+                file to include the <filename>ab123</filename> kernel modules
+                with images built for the <filename>qemux86</filename> machine:
+                <literallayout class='monospaced'>
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-ab123"
+                </literallayout>
+                For more information, see the
+                "<link linkend='incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</link>"
+                section.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I change the Linux kernel command line?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The Linux kernel command line is typically specified in
+                the machine config using the <filename>APPEND</filename> variable.
+                For example, you can add some helpful debug information doing
+                the following:
+                <literallayout class='monospaced'>
+     APPEND += "printk.time=y initcall_debug debug"
+                </literallayout>
+            </para>
+        </answer>
+    </qandaentry>
+
+</qandaset>
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-intro.xml b/documentation/kernel-dev/kernel-dev-intro.xml
new file mode 100644
index 0000000000..297696c965
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-intro.xml
@@ -0,0 +1,147 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='kernel-dev-intro'>
+<title>Introduction</title>
+
+<!--
+<para>
+    <emphasis>AR - Darrren Hart:</emphasis>  See if the concepts in these
+    three bullets are adequately covered in somewhere in this manual:
+    <itemizedlist>
+        <listitem><para>Do we convey that our kernel Git repositories
+            have a clear and continuous history, similar to the way the
+            kernel Git repositories for <filename>kernel.org</filename>
+            do.
+            </para></listitem>
+        <listitem><para>Does the manual note that Yocto Project delivers
+            a key set of supported kernel types, where
+            each type is tailored to meet a specific use (e.g. networking,
+            consumer, devices, and so forth).</para></listitem>
+        <listitem><para>Do we convey that the Yocto Project uses a
+            Git branching strategy that, from a
+            developer's point of view, results in a linear path from the
+            baseline kernel.org, through a select group of features and
+            ends with their BSP-specific commits.</para></listitem>
+    </itemizedlist>
+</para>
+-->
+
+    <section id='kernel-dev-overview'>
+        <title>Overview</title>
+
+        <para>
+            Regardless of how you intend to make use of the Yocto Project,
+            chances are you will work with the Linux kernel.
+            This manual provides background information on the Yocto Linux kernel
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
+            describes common tasks you can perform using the kernel tools,
+            and shows you how to use the kernel Metadata needed to work with
+            the kernel inside the Yocto Project.
+       </para>
+
+       <para>
+            Each Yocto Project release has a set of linux-yocto recipes, whose
+            Git repositories you can view in the Yocto
+            <ulink url='&YOCTO_GIT_URL;'>Source Repositories</ulink> under
+            the "Yocto Linux Kernel" heading.
+            New recipes for the release track the latest upstream developments
+            and introduce newly supported platforms.
+            Previous recipes in the release are refreshed and supported for at
+            least one additional release.
+            As they align, these previous releases are updated to include the
+            latest from the Long Term Support Initiative (LTSI) project.
+            Also included is a linux-yocto development recipe
+            (<filename>linux-yocto-dev.bb</filename>) should you want to work
+            with the very latest in upstream Linux kernel development and
+            kernel Metadata development.
+        </para>
+
+        <para>
+            The Yocto Project also provides a powerful set of kernel
+            tools for managing Linux kernel sources and configuration data.
+            You can use these tools to make a single configuration change,
+            apply multiple patches, or work with your own kernel sources.
+        </para>
+
+        <para>
+            In particular, the kernel tools allow you to generate configuration
+            fragments that specify only what you must, and nothing more.
+            Configuration fragments only need to contain the highest level
+            visible <filename>CONFIG</filename> options as presented by the Linux
+            kernel <filename>menuconfig</filename> system.
+            Contrast this against a complete Linux kernel
+            <filename>.config</filename>, which includes all the automatically
+            selected <filename>CONFIG</filename> options.
+            This efficiency reduces your maintenance effort and allows you
+            to further separate your configuration in ways that make sense for
+            your project.
+            A common split separates policy and hardware.
+            For example, all your kernels might support
+            the <filename>proc</filename> and <filename>sys</filename> filesystems,
+            but only specific boards require sound, USB, or specific drivers.
+            Specifying these configurations individually allows you to aggregate
+            them together as needed, but maintains them in only one place.
+            Similar logic applies to separating source changes.
+        </para>
+
+        <para>
+            If you do not maintain your own kernel sources and need to make
+            only minimal changes to the sources, the released recipes provide a
+            vetted base upon which to layer your changes.
+            Doing so allows you to benefit from the continual kernel
+            integration and testing performed during development of the
+            Yocto Project.
+        </para>
+
+        <para>
+            If, instead, you have a very specific Linux kernel source tree
+            and are unable to align with one of the official linux-yocto
+            recipes, an alternative exists by which you can use the Yocto
+            Project Linux kernel tools with your own kernel sources.
+        </para>
+    </section>
+
+    <section id='kernel-dev-other-resources'>
+        <title>Other Resources</title>
+
+        <para>
+            The sections that follow provide instructions for completing
+            specific Linux kernel development tasks.
+            These instructions assume you are comfortable working with
+            <ulink url='http://developer.berlios.de/projects/bitbake/'>BitBake</ulink>
+            recipes and basic open-source development tools.
+            Understanding these concepts will facilitate the process of working
+            with the kernel recipes.
+            If you find you need some additional background, please be sure to
+            review and understand the following documentation:
+            <itemizedlist>
+                <listitem><para><ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
+                    </para></listitem>
+                <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-temporary-source-code'>Modifying Temporary Source Code</ulink>"
+                    section in the Yocto Project Development Manual
+                    </para></listitem>
+                <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>" section
+                    in the Yocto Project Development Manual</para></listitem>
+                <listitem><para>The "<ulink url='&YOCTO_DOCS_DEV_URL;#modifying-the-kernel'>Modifying the Kernel</ulink>" section
+                    in the Yocto Project Development Manual.</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Finally, while this document focuses on the manual creation of
+            recipes, patches, and configuration files, the Yocto Project
+            Board Support Package (BSP) tools are available to automate
+            this process with existing content and work well to create the
+            initial framework and boilerplate code.
+            For details on these tools, see the
+            "<ulink url='&YOCTO_DOCS_BSP_URL;#using-the-yocto-projects-bsp-tools'>Using the Yocto Project's BSP Tools</ulink>"
+            section in the Yocto Project Board Support Package (BSP) Developer's
+            Guide.
+        </para>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-maint-appx.xml b/documentation/kernel-dev/kernel-dev-maint-appx.xml
new file mode 100644
index 0000000000..5f9788aa31
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-maint-appx.xml
@@ -0,0 +1,220 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<appendix id='kernel-dev-maint-appx'>
+<title>Kernel Maintenance</title>
+
+    <section id='tree-construction'>
+        <title>Tree Construction</title>
+        <para>
+            This section describes construction of the Yocto Project kernel source repositories
+            as accomplished by the Yocto Project team to create kernel repositories.
+            These kernel repositories are found under the heading "Yocto Linux Kernel" at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>&YOCTO_GIT_URL;/cgit.cgi</ulink>
+            and can be shipped as part of a Yocto Project release.
+            The team creates these repositories by
+            compiling and executing the set of feature descriptions for every BSP
+            and feature in the product.
+            Those feature descriptions list all necessary patches,
+            configuration, branching, tagging and feature divisions found in a kernel.
+            Thus, the Yocto Project kernel repository (or tree) is built.
+        </para>
+        <para>
+            The existence of this tree allows you to access and clone a particular
+            Yocto Project kernel repository and use it to build images based on their configurations
+            and features.
+        </para>
+        <para>
+            You can find the files used to describe all the valid features and BSPs
+            in the Yocto Project kernel in any clone of the Yocto Project kernel source repository
+            Git tree.
+            For example, the following command clones the Yocto Project baseline kernel that
+            branched off of <filename>linux.org</filename> version 3.4:
+            <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/linux-yocto-3.4
+            </literallayout>
+            For another example of how to set up a local Git repository of the Yocto Project
+            kernel files, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>" bulleted
+            item in the Yocto Project Development Manual.
+        </para>
+        <para>
+            Once you have cloned the kernel Git repository on your local machine, you can
+            switch to the <filename>meta</filename> branch within the repository.
+            Here is an example that assumes the local Git repository for the kernel is in
+            a top-level directory named <filename>linux-yocto-3.4</filename>:
+            <literallayout class='monospaced'>
+     $ cd ~/linux-yocto-3.4
+     $ git checkout -b meta origin/meta
+            </literallayout>
+            Once you have checked out and switched to the <filename>meta</filename> branch,
+            you can see a snapshot of all the kernel configuration and feature descriptions that are
+            used to build that particular kernel repository.
+            These descriptions are in the form of <filename>.scc</filename> files.
+        </para>
+        <para>
+            You should realize, however, that browsing your local kernel repository
+            for feature descriptions and patches is not an effective way to determine what is in a
+            particular kernel branch.
+            Instead, you should use Git directly to discover the changes in a branch.
+            Using Git is an efficient and flexible way to inspect changes to the kernel.
+            <note>
+                Ground up reconstruction of the complete kernel tree is an action only taken by the
+                Yocto Project team during an active development cycle.
+                When you create a clone of the kernel Git repository, you are simply making it
+                efficiently available for building and development.
+            </note>
+        </para>
+        <para>
+            The following steps describe what happens when the Yocto Project Team constructs
+            the Yocto Project kernel source Git repository (or tree) found at
+            <ulink url='&YOCTO_GIT_URL;/cgit.cgi'></ulink> given the
+            introduction of a new top-level kernel feature or BSP.
+            These are the actions that effectively create the tree
+            that includes the new feature, patch or BSP:
+            <orderedlist>
+                <listitem><para>A top-level kernel feature is passed to the kernel build subsystem.
+                    Normally, this feature is a BSP for a particular kernel type.</para></listitem>
+                <listitem><para>The file that describes the top-level feature is located by searching
+                    these system directories:
+                    <itemizedlist>
+                        <listitem><para>The in-tree kernel-cache directories, which are located
+                            in <filename>meta/cfg/kernel-cache</filename></para></listitem>
+                        <listitem><para>Areas pointed to by <filename>SRC_URI</filename> statements
+                            found in recipes</para></listitem>
+                    </itemizedlist>
+                    For a typical build, the target of the search is a
+                    feature description in an <filename>.scc</filename> file
+                    whose name follows this format:
+                    <literallayout class='monospaced'>
+     &lt;bsp_name&gt;-&lt;kernel_type&gt;.scc
+                    </literallayout>
+                </para></listitem>
+                <listitem><para>Once located, the feature description is either compiled into a simple script
+                    of actions, or into an existing equivalent script that is already part of the
+                    shipped kernel.</para></listitem>
+                <listitem><para>Extra features are appended to the top-level feature description.
+                    These features can come from the
+                    <ulink url='&YOCTO_DOCS_REF_URL;#var-KERNEL_FEATURES'><filename>KERNEL_FEATURES</filename></ulink>
+                    variable in recipes.</para></listitem>
+                <listitem><para>Each extra feature is located, compiled and appended to the script
+                    as described in step three.</para></listitem>
+                <listitem><para>The script is executed to produce a series of <filename>meta-*</filename>
+                    directories.
+                    These directories are descriptions of all the branches, tags, patches and configurations that
+                    need to be applied to the base Git repository to completely create the
+                    source (build) branch for the new BSP or feature.</para></listitem>
+                <listitem><para>The base repository is cloned, and the actions
+                    listed in the <filename>meta-*</filename> directories are applied to the
+                    tree.</para></listitem>
+                <listitem><para>The Git repository is left with the desired branch checked out and any
+                    required branching, patching and tagging has been performed.</para></listitem>
+            </orderedlist>
+        </para>
+        <para>
+            The kernel tree is now ready for developer consumption to be locally cloned,
+            configured, and built into a Yocto Project kernel specific to some target hardware.
+            <note><para>The generated <filename>meta-*</filename> directories add to the kernel
+                as shipped with the Yocto Project release.
+                Any add-ons and configuration data are applied to the end of an existing branch.
+                The full repository generation that is found in the
+                official Yocto Project kernel repositories at
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi'>http://git.yoctoproject.org/cgit.cgi</ulink>
+                is the combination of all supported boards and configurations.</para>
+                <para>The technique the Yocto Project team uses is flexible and allows for seamless
+                blending of an immutable history with additional patches specific to a
+                deployment.
+                Any additions to the kernel become an integrated part of the branches.</para>
+            </note>
+        </para>
+    </section>
+
+    <section id='build-strategy'>
+        <title>Build Strategy</title>
+
+<!--
+        <para>
+            <emphasis>AR - Darrren Hart:</emphasis>  Some parts of this section
+            need to be in the
+            "<link linkend='using-an-iterative-development-process'>Using an Iterative Development Process</link>"
+            section.
+            Darren needs to figure out which parts and identify them.
+        </para>
+-->
+
+        <para>
+            Once a local Git repository of the Yocto Project kernel exists on a development system,
+            you can consider the compilation phase of kernel development - building a kernel image.
+            Some prerequisites exist that are validated by the build process before compilation
+            starts:
+        </para>
+
+        <itemizedlist>
+            <listitem><para>The
+                <ulink url='&YOCTO_DOCS_REF_URL;#var-SRC_URI'><filename>SRC_URI</filename></ulink> points
+                to the kernel Git repository.</para></listitem>
+            <listitem><para>A BSP build branch exists.
+                This branch has the following form:
+                <literallayout class='monospaced'>
+     &lt;kernel_type&gt;/&lt;bsp_name&gt;
+                </literallayout></para></listitem>
+        </itemizedlist>
+
+        <para>
+            The OpenEmbedded build system makes sure these conditions exist before attempting compilation.
+            Other means, however, do exist, such as as bootstrapping a BSP.
+        </para>
+
+        <para>
+            Before building a kernel, the build process verifies the tree
+            and configures the kernel by processing all of the
+            configuration "fragments" specified by feature descriptions in the <filename>.scc</filename>
+            files.
+            As the features are compiled, associated kernel configuration fragments are noted
+            and recorded in the <filename>meta-*</filename> series of directories in their compilation order.
+            The fragments are migrated, pre-processed and passed to the Linux Kernel
+            Configuration subsystem (<filename>lkc</filename>) as raw input in the form
+            of a <filename>.config</filename> file.
+            The <filename>lkc</filename> uses its own internal dependency constraints to do the final
+            processing of that information and generates the final <filename>.config</filename> file
+            that is used during compilation.
+        </para>
+
+        <para>
+            Using the board's architecture and other relevant values from the board's template,
+            kernel compilation is started and a kernel image is produced.
+        </para>
+
+        <para>
+            The other thing that you notice once you configure a kernel is that
+            the build process generates a build tree that is separate from your kernel's local Git
+            source repository tree.
+            This build tree has a name that uses the following form, where
+            <filename>${MACHINE}</filename> is the metadata name of the machine (BSP) and "kernel_type" is one
+            of the Yocto Project supported kernel types (e.g. "standard"):
+        <literallayout class='monospaced'>
+     linux-${MACHINE}-&lt;kernel_type&gt;-build
+        </literallayout>
+        </para>
+
+        <para>
+            The existing support in the <filename>kernel.org</filename> tree achieves this
+            default functionality.
+        </para>
+
+        <para>
+            This behavior means that all the generated files for a particular machine or BSP are now in
+            the build tree directory.
+            The files include the final <filename>.config</filename> file, all the <filename>.o</filename>
+            files, the <filename>.a</filename> files, and so forth.
+            Since each machine or BSP has its own separate 
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            in its own separate branch
+            of the Git repository, you can easily switch between different builds.
+        </para>
+    </section>
+</appendix>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/kernel-dev/kernel-dev-style.css b/documentation/kernel-dev/kernel-dev-style.css
new file mode 100644
index 0000000000..52be14388d
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev-style.css
@@ -0,0 +1,978 @@
+/*
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("figures/kernel-dev-title.png");
+  background-position: left top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 0px;
+  text-align: right;
+  width: 740px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+}
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption,
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2;
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title,
+div.colophon .title,
+div.chapter .titlepage .title,
+div.article .titlepage .title
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/yocto-project-bw.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2;
+   color: #333;
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;
+}
+
+.tip a,
+.note a {
+   color: #333;
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
diff --git a/documentation/kernel-dev/kernel-dev.xml b/documentation/kernel-dev/kernel-dev.xml
new file mode 100644
index 0000000000..f4cddba76e
--- /dev/null
+++ b/documentation/kernel-dev/kernel-dev.xml
@@ -0,0 +1,95 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='kernel-dev' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='figures/kernel-dev-title.png'
+                    format='SVG'
+                    align='left' scalefit='1' width='100%'/>
+            </imageobject>
+        </mediaobject>
+
+        <title>
+                  Yocto Project Linux Kernel Development Manual
+                </title>
+
+        <authorgroup>
+            <author>
+                <firstname>Darren</firstname> <surname>Hart</surname>
+                <affiliation>
+                    <orgname>Intel Corporation</orgname>
+                </affiliation>
+                <email>darren.hart@intel.com</email>
+            </author>
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>April 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5</revnumber>
+                <date>October 2013</date>
+                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5.1</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
+            </revision>
+        </revhistory>
+
+    <copyright>
+      <year>&COPYRIGHT_YEAR;</year>
+      <holder>Linux Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this document under
+        the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
+      </para>
+      <note>
+          For the latest version of this manual associated with this
+          Yocto Project release, see the
+          <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>
+          from the Yocto Project website.
+      </note>
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="kernel-dev-intro.xml"/>
+
+    <xi:include href="kernel-dev-common.xml"/>
+
+    <xi:include href="kernel-dev-advanced.xml"/>
+
+    <xi:include href="kernel-dev-concepts-appx.xml"/>
+
+    <xi:include href="kernel-dev-maint-appx.xml"/>
+
+<!--
+    <xi:include href="kernel-dev-examples.xml"/>
+-->
+
+    <xi:include href="kernel-dev-faq.xml"/>
+
+<!--    <index id='index'>
+      <title>Index</title>
+    </index>
+-->
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/mega-manual/figures/adt-title.png b/documentation/mega-manual/figures/adt-title.png
new file mode 100644
index 0000000000..6e71e41f1a
--- /dev/null
+++ b/documentation/mega-manual/figures/adt-title.png
diff --git a/documentation/mega-manual/figures/analysis-for-package-splitting.png b/documentation/mega-manual/figures/analysis-for-package-splitting.png
new file mode 100644
index 0000000000..04f2794ea9
--- /dev/null
+++ b/documentation/mega-manual/figures/analysis-for-package-splitting.png
diff --git a/documentation/mega-manual/figures/app-dev-flow.png b/documentation/mega-manual/figures/app-dev-flow.png
new file mode 100644
index 0000000000..4927b93d67
--- /dev/null
+++ b/documentation/mega-manual/figures/app-dev-flow.png
diff --git a/documentation/mega-manual/figures/bsp-dev-flow.png b/documentation/mega-manual/figures/bsp-dev-flow.png
new file mode 100644
index 0000000000..b20ee19223
--- /dev/null
+++ b/documentation/mega-manual/figures/bsp-dev-flow.png
diff --git a/documentation/mega-manual/figures/bsp-title.png b/documentation/mega-manual/figures/bsp-title.png
new file mode 100644
index 0000000000..f624dd4f94
--- /dev/null
+++ b/documentation/mega-manual/figures/bsp-title.png
diff --git a/documentation/mega-manual/figures/buildhistory-web.png b/documentation/mega-manual/figures/buildhistory-web.png
new file mode 100644
index 0000000000..f6db86c977
--- /dev/null
+++ b/documentation/mega-manual/figures/buildhistory-web.png
diff --git a/documentation/mega-manual/figures/buildhistory.png b/documentation/mega-manual/figures/buildhistory.png
new file mode 100644
index 0000000000..edf98d95cf
--- /dev/null
+++ b/documentation/mega-manual/figures/buildhistory.png
diff --git a/documentation/mega-manual/figures/building-an-image.png b/documentation/mega-manual/figures/building-an-image.png
new file mode 100755
index 0000000000..1fbea5ab00
--- /dev/null
+++ b/documentation/mega-manual/figures/building-an-image.png
diff --git a/documentation/mega-manual/figures/configuration-compile-autoreconf.png b/documentation/mega-manual/figures/configuration-compile-autoreconf.png
new file mode 100644
index 0000000000..a07464f04c
--- /dev/null
+++ b/documentation/mega-manual/figures/configuration-compile-autoreconf.png
diff --git a/documentation/mega-manual/figures/cross-development-toolchains.png b/documentation/mega-manual/figures/cross-development-toolchains.png
new file mode 100644
index 0000000000..d36670a198
--- /dev/null
+++ b/documentation/mega-manual/figures/cross-development-toolchains.png
diff --git a/documentation/mega-manual/figures/dev-title.png b/documentation/mega-manual/figures/dev-title.png
new file mode 100644
index 0000000000..d3cac4a7e5
--- /dev/null
+++ b/documentation/mega-manual/figures/dev-title.png
diff --git a/documentation/mega-manual/figures/git-workflow.png b/documentation/mega-manual/figures/git-workflow.png
new file mode 100644
index 0000000000..4fdf42f89c
--- /dev/null
+++ b/documentation/mega-manual/figures/git-workflow.png
diff --git a/documentation/mega-manual/figures/image-generation.png b/documentation/mega-manual/figures/image-generation.png
new file mode 100644
index 0000000000..5594658200
--- /dev/null
+++ b/documentation/mega-manual/figures/image-generation.png
diff --git a/documentation/mega-manual/figures/images.png b/documentation/mega-manual/figures/images.png
new file mode 100644
index 0000000000..d99eac1fbf
--- /dev/null
+++ b/documentation/mega-manual/figures/images.png
diff --git a/documentation/mega-manual/figures/index-downloads.png b/documentation/mega-manual/figures/index-downloads.png
new file mode 100644
index 0000000000..c907997db2
--- /dev/null
+++ b/documentation/mega-manual/figures/index-downloads.png
diff --git a/documentation/mega-manual/figures/kernel-architecture-overview.png b/documentation/mega-manual/figures/kernel-architecture-overview.png
new file mode 100755
index 0000000000..2aad172db3
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-architecture-overview.png
diff --git a/documentation/mega-manual/figures/kernel-dev-flow.png b/documentation/mega-manual/figures/kernel-dev-flow.png
new file mode 100644
index 0000000000..edd9e82af7
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-dev-flow.png
diff --git a/documentation/mega-manual/figures/kernel-dev-title.png b/documentation/mega-manual/figures/kernel-dev-title.png
new file mode 100644
index 0000000000..7a8dd54372
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-dev-title.png
diff --git a/documentation/mega-manual/figures/kernel-overview-1.png b/documentation/mega-manual/figures/kernel-overview-1.png
new file mode 100644
index 0000000000..116c0b9bd4
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-overview-1.png
diff --git a/documentation/mega-manual/figures/kernel-overview-2-generic.png b/documentation/mega-manual/figures/kernel-overview-2-generic.png
new file mode 100644
index 0000000000..889ff1bf0d
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-overview-2-generic.png
diff --git a/documentation/mega-manual/figures/kernel-title.png b/documentation/mega-manual/figures/kernel-title.png
new file mode 100644
index 0000000000..59d86c00dc
--- /dev/null
+++ b/documentation/mega-manual/figures/kernel-title.png
diff --git a/documentation/mega-manual/figures/kernelshark-all.png b/documentation/mega-manual/figures/kernelshark-all.png
new file mode 100644
index 0000000000..99b40bafe5
--- /dev/null
+++ b/documentation/mega-manual/figures/kernelshark-all.png
diff --git a/documentation/mega-manual/figures/kernelshark-choose-events.png b/documentation/mega-manual/figures/kernelshark-choose-events.png
new file mode 100644
index 0000000000..e8dd62a571
--- /dev/null
+++ b/documentation/mega-manual/figures/kernelshark-choose-events.png
diff --git a/documentation/mega-manual/figures/kernelshark-i915-display.png b/documentation/mega-manual/figures/kernelshark-i915-display.png
new file mode 100644
index 0000000000..bb0edfb7fd
--- /dev/null
+++ b/documentation/mega-manual/figures/kernelshark-i915-display.png
diff --git a/documentation/mega-manual/figures/kernelshark-output-display.png b/documentation/mega-manual/figures/kernelshark-output-display.png
new file mode 100644
index 0000000000..ae2d0e5730
--- /dev/null
+++ b/documentation/mega-manual/figures/kernelshark-output-display.png
diff --git a/documentation/mega-manual/figures/layer-input.png b/documentation/mega-manual/figures/layer-input.png
new file mode 100644
index 0000000000..0a4f2e74f3
--- /dev/null
+++ b/documentation/mega-manual/figures/layer-input.png
diff --git a/documentation/mega-manual/figures/lttngmain0.png b/documentation/mega-manual/figures/lttngmain0.png
new file mode 100644
index 0000000000..5f60113cc3
--- /dev/null
+++ b/documentation/mega-manual/figures/lttngmain0.png
diff --git a/documentation/mega-manual/figures/oprofileui-busybox.png b/documentation/mega-manual/figures/oprofileui-busybox.png
new file mode 100644
index 0000000000..a8275c65d2
--- /dev/null
+++ b/documentation/mega-manual/figures/oprofileui-busybox.png
diff --git a/documentation/mega-manual/figures/oprofileui-copy-to-user.png b/documentation/mega-manual/figures/oprofileui-copy-to-user.png
new file mode 100644
index 0000000000..deb6470204
--- /dev/null
+++ b/documentation/mega-manual/figures/oprofileui-copy-to-user.png
diff --git a/documentation/mega-manual/figures/oprofileui-downloading.png b/documentation/mega-manual/figures/oprofileui-downloading.png
new file mode 100644
index 0000000000..57742d6723
--- /dev/null
+++ b/documentation/mega-manual/figures/oprofileui-downloading.png
diff --git a/documentation/mega-manual/figures/oprofileui-processes.png b/documentation/mega-manual/figures/oprofileui-processes.png
new file mode 100644
index 0000000000..ae547028f4
--- /dev/null
+++ b/documentation/mega-manual/figures/oprofileui-processes.png
diff --git a/documentation/mega-manual/figures/package-feeds.png b/documentation/mega-manual/figures/package-feeds.png
new file mode 100644
index 0000000000..4bc311f3d6
--- /dev/null
+++ b/documentation/mega-manual/figures/package-feeds.png
diff --git a/documentation/mega-manual/figures/patching.png b/documentation/mega-manual/figures/patching.png
new file mode 100644
index 0000000000..8ecd018502
--- /dev/null
+++ b/documentation/mega-manual/figures/patching.png
diff --git a/documentation/mega-manual/figures/perf-probe-do_fork-profile.png b/documentation/mega-manual/figures/perf-probe-do_fork-profile.png
new file mode 100644
index 0000000000..1a1070deb8
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-probe-do_fork-profile.png
diff --git a/documentation/mega-manual/figures/perf-report-cycles-u.png b/documentation/mega-manual/figures/perf-report-cycles-u.png
new file mode 100644
index 0000000000..68ec6af80b
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-report-cycles-u.png
diff --git a/documentation/mega-manual/figures/perf-systemwide-libc.png b/documentation/mega-manual/figures/perf-systemwide-libc.png
new file mode 100644
index 0000000000..2b72869c77
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-systemwide-libc.png
diff --git a/documentation/mega-manual/figures/perf-systemwide.png b/documentation/mega-manual/figures/perf-systemwide.png
new file mode 100644
index 0000000000..12ce2444ae
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-systemwide.png
diff --git a/documentation/mega-manual/figures/perf-wget-busybox-annotate-menu.png b/documentation/mega-manual/figures/perf-wget-busybox-annotate-menu.png
new file mode 100644
index 0000000000..ceb34eaead
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-busybox-annotate-menu.png
diff --git a/documentation/mega-manual/figures/perf-wget-busybox-annotate-udhcpc.png b/documentation/mega-manual/figures/perf-wget-busybox-annotate-udhcpc.png
new file mode 100644
index 0000000000..3581e9daa6
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-busybox-annotate-udhcpc.png
diff --git a/documentation/mega-manual/figures/perf-wget-busybox-debuginfo.png b/documentation/mega-manual/figures/perf-wget-busybox-debuginfo.png
new file mode 100644
index 0000000000..c317b49a4e
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-busybox-debuginfo.png
diff --git a/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom-menu.png b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom-menu.png
new file mode 100644
index 0000000000..1913c867d0
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom-menu.png
diff --git a/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom.png b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom.png
new file mode 100644
index 0000000000..a1962c437a
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-busybox-dso-zoom.png
diff --git a/documentation/mega-manual/figures/perf-wget-busybox-expanded-stripped.png b/documentation/mega-manual/figures/perf-wget-busybox-expanded-stripped.png
new file mode 100644
index 0000000000..b642d06c8b
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-busybox-expanded-stripped.png
diff --git a/documentation/mega-manual/figures/perf-wget-flat-stripped.png b/documentation/mega-manual/figures/perf-wget-flat-stripped.png
new file mode 100644
index 0000000000..c8f395ab53
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-flat-stripped.png
diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png b/documentation/mega-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png
new file mode 100644
index 0000000000..bb7c764ce0
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png
diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png
new file mode 100644
index 0000000000..a799af5127
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png
diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png
new file mode 100644
index 0000000000..e91808ae40
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png
diff --git a/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png
new file mode 100644
index 0000000000..812302d0a8
--- /dev/null
+++ b/documentation/mega-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png
diff --git a/documentation/mega-manual/figures/poky-title.png b/documentation/mega-manual/figures/poky-title.png
new file mode 100644
index 0000000000..2893d84620
--- /dev/null
+++ b/documentation/mega-manual/figures/poky-title.png
diff --git a/documentation/mega-manual/figures/profile-title.png b/documentation/mega-manual/figures/profile-title.png
new file mode 100644
index 0000000000..ce5c682b58
--- /dev/null
+++ b/documentation/mega-manual/figures/profile-title.png
diff --git a/documentation/mega-manual/figures/pybootchartgui-linux-yocto.png b/documentation/mega-manual/figures/pybootchartgui-linux-yocto.png
new file mode 100644
index 0000000000..2b6bfdacf9
--- /dev/null
+++ b/documentation/mega-manual/figures/pybootchartgui-linux-yocto.png
diff --git a/documentation/mega-manual/figures/pychart-linux-yocto-rpm-nostrip.png b/documentation/mega-manual/figures/pychart-linux-yocto-rpm-nostrip.png
new file mode 100644
index 0000000000..444675c543
--- /dev/null
+++ b/documentation/mega-manual/figures/pychart-linux-yocto-rpm-nostrip.png
diff --git a/documentation/mega-manual/figures/pychart-linux-yocto-rpm.png b/documentation/mega-manual/figures/pychart-linux-yocto-rpm.png
new file mode 100644
index 0000000000..8ee35352d8
--- /dev/null
+++ b/documentation/mega-manual/figures/pychart-linux-yocto-rpm.png
diff --git a/documentation/mega-manual/figures/sched-wakeup-profile.png b/documentation/mega-manual/figures/sched-wakeup-profile.png
new file mode 100644
index 0000000000..2f25811889
--- /dev/null
+++ b/documentation/mega-manual/figures/sched-wakeup-profile.png
diff --git a/documentation/mega-manual/figures/sdk-generation.png b/documentation/mega-manual/figures/sdk-generation.png
new file mode 100644
index 0000000000..c37e2748ca
--- /dev/null
+++ b/documentation/mega-manual/figures/sdk-generation.png
diff --git a/documentation/mega-manual/figures/sdk.png b/documentation/mega-manual/figures/sdk.png
new file mode 100644
index 0000000000..a539cc52f0
--- /dev/null
+++ b/documentation/mega-manual/figures/sdk.png
diff --git a/documentation/mega-manual/figures/source-fetching.png b/documentation/mega-manual/figures/source-fetching.png
new file mode 100644
index 0000000000..26aefb50c2
--- /dev/null
+++ b/documentation/mega-manual/figures/source-fetching.png
diff --git a/documentation/mega-manual/figures/source-input.png b/documentation/mega-manual/figures/source-input.png
new file mode 100644
index 0000000000..f7515058ef
--- /dev/null
+++ b/documentation/mega-manual/figures/source-input.png
diff --git a/documentation/mega-manual/figures/source-repos.png b/documentation/mega-manual/figures/source-repos.png
new file mode 100644
index 0000000000..65c5f29a43
--- /dev/null
+++ b/documentation/mega-manual/figures/source-repos.png
diff --git a/documentation/mega-manual/figures/sysprof-callers.png b/documentation/mega-manual/figures/sysprof-callers.png
new file mode 100644
index 0000000000..640c8d9140
--- /dev/null
+++ b/documentation/mega-manual/figures/sysprof-callers.png
diff --git a/documentation/mega-manual/figures/sysprof-copy-from-user.png b/documentation/mega-manual/figures/sysprof-copy-from-user.png
new file mode 100644
index 0000000000..8d31427824
--- /dev/null
+++ b/documentation/mega-manual/figures/sysprof-copy-from-user.png
diff --git a/documentation/mega-manual/figures/sysprof-copy-to-user.png b/documentation/mega-manual/figures/sysprof-copy-to-user.png
new file mode 100644
index 0000000000..7a5bab7991
--- /dev/null
+++ b/documentation/mega-manual/figures/sysprof-copy-to-user.png
diff --git a/documentation/mega-manual/figures/user-configuration.png b/documentation/mega-manual/figures/user-configuration.png
new file mode 100644
index 0000000000..f2b3f8e7fe
--- /dev/null
+++ b/documentation/mega-manual/figures/user-configuration.png
diff --git a/documentation/mega-manual/figures/using-a-pre-built-image.png b/documentation/mega-manual/figures/using-a-pre-built-image.png
new file mode 100644
index 0000000000..b03130d123
--- /dev/null
+++ b/documentation/mega-manual/figures/using-a-pre-built-image.png
diff --git a/documentation/mega-manual/figures/yocto-environment-ref.png b/documentation/mega-manual/figures/yocto-environment-ref.png
new file mode 100644
index 0000000000..650c6c8030
--- /dev/null
+++ b/documentation/mega-manual/figures/yocto-environment-ref.png
diff --git a/documentation/mega-manual/figures/yocto-environment.png b/documentation/mega-manual/figures/yocto-environment.png
new file mode 100644
index 0000000000..82b7a55a35
--- /dev/null
+++ b/documentation/mega-manual/figures/yocto-environment.png
diff --git a/documentation/mega-manual/figures/yocto-project-transp.png b/documentation/mega-manual/figures/yocto-project-transp.png
new file mode 100755
index 0000000000..31d2b147fd
--- /dev/null
+++ b/documentation/mega-manual/figures/yocto-project-transp.png
diff --git a/documentation/mega-manual/figures/yp-download.png b/documentation/mega-manual/figures/yp-download.png
new file mode 100644
index 0000000000..7f1e5ca118
--- /dev/null
+++ b/documentation/mega-manual/figures/yp-download.png
diff --git a/documentation/mega-manual/mega-manual-customization.xsl b/documentation/mega-manual/mega-manual-customization.xsl
new file mode 100644
index 0000000000..3be182d6c2
--- /dev/null
+++ b/documentation/mega-manual/mega-manual-customization.xsl
@@ -0,0 +1,8 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+  
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+  <xsl:param name="generate.toc" select="'chapter toc'"></xsl:param>  
+
+</xsl:stylesheet>
diff --git a/documentation/mega-manual/mega-manual.xml b/documentation/mega-manual/mega-manual.xml
new file mode 100644
index 0000000000..01af789aed
--- /dev/null
+++ b/documentation/mega-manual/mega-manual.xml
@@ -0,0 +1,53 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+
+<book id='mega-manual' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../yocto-project-qs/yocto-project-qs.xml"/>
+
+<para><imagedata fileref="figures/dev-title.png" width="100%" align="left" scalefit="1" /></para>
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../dev-manual/dev-manual.xml"/>
+
+<para><imagedata fileref="figures/adt-title.png" width="100%" align="left" scalefit="1" /></para>
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../adt-manual/adt-manual.xml"/>
+
+<para><imagedata fileref="figures/bsp-title.png" width="100%" align="left" scalefit="1" /></para>
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../bsp-guide/bsp-guide.xml"/>
+
+<para><imagedata fileref="figures/kernel-dev-title.png" width="100%" align="left" scalefit="1" /></para>
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../kernel-dev/kernel-dev.xml"/>
+
+<para><imagedata fileref="figures/profile-title.png" width="100%" align="left" scalefit="1" /></para>
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../profile-manual/profile-manual.xml"/>
+
+<para><imagedata fileref="figures/poky-title.png" width="100%" align="left" scalefit="1" /></para>
+
+    <xi:include
+        xmlns:xi="http://www.w3.org/2003/XInclude" href="../ref-manual/ref-manual.xml"/>
+
+<!--    <index id='index'>
+      <title>Index</title>
+    </index>
+-->
+
+</book>
+
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/mega-manual/mega-style.css b/documentation/mega-manual/mega-style.css
new file mode 100644
index 0000000000..a97d691836
--- /dev/null
+++ b/documentation/mega-manual/mega-style.css
@@ -0,0 +1,979 @@
+/* 
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+   
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+ 
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("../figures/yocto-project-bw.png");
+  background-position: top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 50px;
+  text-align: center;
+  width: 600px;
+}
+
+h3.author {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+  
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+} 
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption, 
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;  
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+  
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2; 
+}
+
+.glossary dl dt, 
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title, 
+div.colophon .title, 
+div.chapter .titlepage .title,
+div.article .titlepage .title 
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/yocto-project-bw.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2; 
+   color: #333;   
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;   
+}
+
+.tip a,
+.note a {
+   color: #333;   
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
+
diff --git a/documentation/poky.ent b/documentation/poky.ent
new file mode 100644
index 0000000000..ef00fcec74
--- /dev/null
+++ b/documentation/poky.ent
@@ -0,0 +1,65 @@
+<!ENTITY DISTRO "1.5.1">
+<!ENTITY DISTRO_COMPRESSED "151">
+<!ENTITY DISTRO_NAME "dora">
+<!ENTITY YOCTO_DOC_VERSION "1.5.1">
+<!ENTITY POKYVERSION "10.0.1">
+<!ENTITY POKYVERSION_COMPRESSED "1001">
+<!ENTITY YOCTO_POKY "poky-&DISTRO_NAME;-&POKYVERSION;">
+<!ENTITY COPYRIGHT_YEAR "2010-2013">
+<!ENTITY YOCTO_DL_URL "http://downloads.yoctoproject.org">
+<!ENTITY YOCTO_HOME_URL "http://www.yoctoproject.org">
+<!ENTITY YOCTO_LISTS_URL "http://lists.yoctoproject.org">
+<!ENTITY YOCTO_BUGZILLA_URL "http://bugzilla.yoctoproject.org">
+<!ENTITY YOCTO_WIKI_URL "https://wiki.yoctoproject.org">
+<!ENTITY YOCTO_AB_URL "http://autobuilder.yoctoproject.org">
+<!ENTITY YOCTO_GIT_URL "http://git.yoctoproject.org">
+<!ENTITY YOCTO_ADTREPO_URL "http://adtrepo.yoctoproject.org">
+<!ENTITY YOCTO_RELEASE_NOTES "&YOCTO_HOME_URL;/download/yocto-project-&DISTRO_COMPRESSED;-poky-&POKYVERSION_COMPRESSED;">
+<!ENTITY OE_HOME_URL "http://www.openembedded.org">
+<!ENTITY OE_LISTS_URL "http://lists.linuxtogo.org/cgi-bin/mailman">
+<!ENTITY OE_DOCS_URL "http://docs.openembedded.org">
+<!ENTITY OH_HOME_URL "http://o-hand.com">
+<!ENTITY BITBAKE_HOME_URL "http://developer.berlios.de/projects/bitbake/">
+<!ENTITY ECLIPSE_MAIN_URL "http://www.eclipse.org/downloads">
+<!ENTITY ECLIPSE_DL_URL "http://download.eclipse.org">
+<!ENTITY ECLIPSE_DL_PLUGIN_URL "&YOCTO_DL_URL;/releases/eclipse-plugin/&DISTRO;">
+<!ENTITY ECLIPSE_UPDATES_URL "&ECLIPSE_DL_URL;/tm/updates/3.3">
+<!ENTITY ECLIPSE_INDIGO_URL "&ECLIPSE_DL_URL;/releases/indigo">
+<!ENTITY ECLIPSE_JUNO_URL "&ECLIPSE_DL_URL;/releases/juno">
+<!ENTITY ECLIPSE_KEPLER_URL "&ECLIPSE_DL_URL;/releases/kepler">
+<!ENTITY ECLIPSE_INDIGO_CDT_URL "&ECLIPSE_DL_URL;tools/cdt/releases/indigo">
+<!ENTITY YOCTO_DOCS_URL "&YOCTO_HOME_URL;/docs">
+<!ENTITY YOCTO_SOURCES_URL "&YOCTO_HOME_URL;/sources/">
+<!ENTITY YOCTO_AB_PORT_URL "&YOCTO_AB_URL;:8010">
+<!ENTITY YOCTO_AB_NIGHTLY_URL "&YOCTO_AB_URL;/nightly/">
+<!ENTITY YOCTO_POKY_URL "&YOCTO_DL_URL;/releases/poky/">
+<!ENTITY YOCTO_RELEASE_DL_URL "&YOCTO_DL_URL;/releases/yocto/yocto-&DISTRO;">
+<!ENTITY YOCTO_TOOLCHAIN_DL_URL "&YOCTO_RELEASE_DL_URL;/toolchain/">
+<!ENTITY YOCTO_ECLIPSE_DL_URL "&YOCTO_RELEASE_DL_URL;/eclipse-plugin/indigo;">
+<!ENTITY YOCTO_ADTINSTALLER_DL_URL "&YOCTO_RELEASE_DL_URL;/adt-installer">
+<!ENTITY YOCTO_POKY_DL_URL "&YOCTO_RELEASE_DL_URL;/&YOCTO_POKY;.tar.bz2">
+<!ENTITY YOCTO_MACHINES_DL_URL "&YOCTO_RELEASE_DL_URL;/machines">
+<!ENTITY YOCTO_QEMU_DL_URL "&YOCTO_MACHINES_DL_URL;/qemu">
+<!ENTITY YOCTO_PYTHON-i686_DL_URL "&YOCTO_DL_URL;/releases/miscsupport/python-nativesdk-standalone-i686.tar.bz2">
+<!ENTITY YOCTO_PYTHON-x86_64_DL_URL "&YOCTO_DL_URL;/releases/miscsupport/python-nativesdk-standalone-x86_64.tar.bz2">
+<!ENTITY YOCTO_DOCS_QS_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/yocto-project-qs/yocto-project-qs.html">
+<!ENTITY YOCTO_DOCS_ADT_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/adt-manual/adt-manual.html">
+<!ENTITY YOCTO_DOCS_REF_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/ref-manual/ref-manual.html">
+<!ENTITY YOCTO_DOCS_BSP_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/bsp-guide/bsp-guide.html">
+<!ENTITY YOCTO_DOCS_DEV_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/dev-manual/dev-manual.html">
+<!ENTITY YOCTO_DOCS_KERNEL_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/kernel-manual/kernel-manual.html">
+<!ENTITY YOCTO_DOCS_KERNEL_DEV_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/kernel-dev/kernel-dev.html">
+<!ENTITY YOCTO_DOCS_PROF_URL "&YOCTO_DOCS_URL;/&YOCTO_DOC_VERSION;/profile-manual/profile-manual.html">
+<!ENTITY YOCTO_ADTPATH_DIR "/opt/poky/&DISTRO;">
+<!ENTITY YOCTO_POKY_TARBALL "&YOCTO_POKY;.tar.bz2">
+<!ENTITY OE_INIT_PATH "&YOCTO_POKY;/oe-init-build-env">
+<!ENTITY OE_INIT_FILE "oe-init-build-env">
+<!ENTITY UBUNTU_HOST_PACKAGES_ESSENTIAL "gawk wget git-core diffstat unzip texinfo \
+     build-essential chrpath">
+<!ENTITY FEDORA_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \
+     diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath \
+     ccache perl-Data-Dumper perl-Text-ParseWords">
+<!ENTITY OPENSUSE_HOST_PACKAGES_ESSENTIAL "python gcc gcc-c++ git chrpath make wget python-xml \
+     diffstat texinfo python-curses patch">
+<!ENTITY CENTOS_HOST_PACKAGES_ESSENTIAL "gawk make wget tar bzip2 gzip python unzip perl patch \
+     diffutils diffstat git cpp gcc gcc-c++ glibc-devel texinfo chrpath">
diff --git a/documentation/profile-manual/figures/kernelshark-all.png b/documentation/profile-manual/figures/kernelshark-all.png
new file mode 100644
index 0000000000..99b40bafe5
--- /dev/null
+++ b/documentation/profile-manual/figures/kernelshark-all.png
diff --git a/documentation/profile-manual/figures/kernelshark-choose-events.png b/documentation/profile-manual/figures/kernelshark-choose-events.png
new file mode 100644
index 0000000000..e8dd62a571
--- /dev/null
+++ b/documentation/profile-manual/figures/kernelshark-choose-events.png
diff --git a/documentation/profile-manual/figures/kernelshark-i915-display.png b/documentation/profile-manual/figures/kernelshark-i915-display.png
new file mode 100644
index 0000000000..bb0edfb7fd
--- /dev/null
+++ b/documentation/profile-manual/figures/kernelshark-i915-display.png
diff --git a/documentation/profile-manual/figures/kernelshark-output-display.png b/documentation/profile-manual/figures/kernelshark-output-display.png
new file mode 100644
index 0000000000..ae2d0e5730
--- /dev/null
+++ b/documentation/profile-manual/figures/kernelshark-output-display.png
diff --git a/documentation/profile-manual/figures/lttngmain0.png b/documentation/profile-manual/figures/lttngmain0.png
new file mode 100644
index 0000000000..5f60113cc3
--- /dev/null
+++ b/documentation/profile-manual/figures/lttngmain0.png
diff --git a/documentation/profile-manual/figures/oprofileui-busybox.png b/documentation/profile-manual/figures/oprofileui-busybox.png
new file mode 100644
index 0000000000..a8275c65d2
--- /dev/null
+++ b/documentation/profile-manual/figures/oprofileui-busybox.png
diff --git a/documentation/profile-manual/figures/oprofileui-copy-to-user.png b/documentation/profile-manual/figures/oprofileui-copy-to-user.png
new file mode 100644
index 0000000000..deb6470204
--- /dev/null
+++ b/documentation/profile-manual/figures/oprofileui-copy-to-user.png
diff --git a/documentation/profile-manual/figures/oprofileui-downloading.png b/documentation/profile-manual/figures/oprofileui-downloading.png
new file mode 100644
index 0000000000..57742d6723
--- /dev/null
+++ b/documentation/profile-manual/figures/oprofileui-downloading.png
diff --git a/documentation/profile-manual/figures/oprofileui-processes.png b/documentation/profile-manual/figures/oprofileui-processes.png
new file mode 100644
index 0000000000..ae547028f4
--- /dev/null
+++ b/documentation/profile-manual/figures/oprofileui-processes.png
diff --git a/documentation/profile-manual/figures/perf-probe-do_fork-profile.png b/documentation/profile-manual/figures/perf-probe-do_fork-profile.png
new file mode 100644
index 0000000000..1a1070deb8
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-probe-do_fork-profile.png
diff --git a/documentation/profile-manual/figures/perf-report-cycles-u.png b/documentation/profile-manual/figures/perf-report-cycles-u.png
new file mode 100644
index 0000000000..68ec6af80b
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-report-cycles-u.png
diff --git a/documentation/profile-manual/figures/perf-systemwide-libc.png b/documentation/profile-manual/figures/perf-systemwide-libc.png
new file mode 100644
index 0000000000..2b72869c77
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-systemwide-libc.png
diff --git a/documentation/profile-manual/figures/perf-systemwide.png b/documentation/profile-manual/figures/perf-systemwide.png
new file mode 100644
index 0000000000..12ce2444ae
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-systemwide.png
diff --git a/documentation/profile-manual/figures/perf-wget-busybox-annotate-menu.png b/documentation/profile-manual/figures/perf-wget-busybox-annotate-menu.png
new file mode 100644
index 0000000000..ceb34eaead
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-busybox-annotate-menu.png
diff --git a/documentation/profile-manual/figures/perf-wget-busybox-annotate-udhcpc.png b/documentation/profile-manual/figures/perf-wget-busybox-annotate-udhcpc.png
new file mode 100644
index 0000000000..3581e9daa6
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-busybox-annotate-udhcpc.png
diff --git a/documentation/profile-manual/figures/perf-wget-busybox-debuginfo.png b/documentation/profile-manual/figures/perf-wget-busybox-debuginfo.png
new file mode 100644
index 0000000000..c317b49a4e
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-busybox-debuginfo.png
diff --git a/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom-menu.png b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom-menu.png
new file mode 100644
index 0000000000..1913c867d0
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom-menu.png
diff --git a/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom.png b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom.png
new file mode 100644
index 0000000000..a1962c437a
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-busybox-dso-zoom.png
diff --git a/documentation/profile-manual/figures/perf-wget-busybox-expanded-stripped.png b/documentation/profile-manual/figures/perf-wget-busybox-expanded-stripped.png
new file mode 100644
index 0000000000..b642d06c8b
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-busybox-expanded-stripped.png
diff --git a/documentation/profile-manual/figures/perf-wget-flat-stripped.png b/documentation/profile-manual/figures/perf-wget-flat-stripped.png
new file mode 100644
index 0000000000..c8f395ab53
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-flat-stripped.png
diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png b/documentation/profile-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png
new file mode 100644
index 0000000000..bb7c764ce0
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-g-copy-from-user-expanded-stripped.png
diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png
new file mode 100644
index 0000000000..a799af5127
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-debuginfo.png
diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png
new file mode 100644
index 0000000000..e91808ae40
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped-unresolved-hidden.png
diff --git a/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png
new file mode 100644
index 0000000000..812302d0a8
--- /dev/null
+++ b/documentation/profile-manual/figures/perf-wget-g-copy-to-user-expanded-stripped.png
diff --git a/documentation/profile-manual/figures/profile-title.png b/documentation/profile-manual/figures/profile-title.png
new file mode 100644
index 0000000000..ce5c682b58
--- /dev/null
+++ b/documentation/profile-manual/figures/profile-title.png
diff --git a/documentation/profile-manual/figures/pybootchartgui-linux-yocto.png b/documentation/profile-manual/figures/pybootchartgui-linux-yocto.png
new file mode 100644
index 0000000000..2b6bfdacf9
--- /dev/null
+++ b/documentation/profile-manual/figures/pybootchartgui-linux-yocto.png
diff --git a/documentation/profile-manual/figures/pychart-linux-yocto-rpm-nostrip.png b/documentation/profile-manual/figures/pychart-linux-yocto-rpm-nostrip.png
new file mode 100644
index 0000000000..444675c543
--- /dev/null
+++ b/documentation/profile-manual/figures/pychart-linux-yocto-rpm-nostrip.png
diff --git a/documentation/profile-manual/figures/pychart-linux-yocto-rpm.png b/documentation/profile-manual/figures/pychart-linux-yocto-rpm.png
new file mode 100644
index 0000000000..8ee35352d8
--- /dev/null
+++ b/documentation/profile-manual/figures/pychart-linux-yocto-rpm.png
diff --git a/documentation/profile-manual/figures/sched-wakeup-profile.png b/documentation/profile-manual/figures/sched-wakeup-profile.png
new file mode 100644
index 0000000000..2f25811889
--- /dev/null
+++ b/documentation/profile-manual/figures/sched-wakeup-profile.png
diff --git a/documentation/profile-manual/figures/sysprof-callers.png b/documentation/profile-manual/figures/sysprof-callers.png
new file mode 100644
index 0000000000..640c8d9140
--- /dev/null
+++ b/documentation/profile-manual/figures/sysprof-callers.png
diff --git a/documentation/profile-manual/figures/sysprof-copy-from-user.png b/documentation/profile-manual/figures/sysprof-copy-from-user.png
new file mode 100644
index 0000000000..8d31427824
--- /dev/null
+++ b/documentation/profile-manual/figures/sysprof-copy-from-user.png
diff --git a/documentation/profile-manual/figures/sysprof-copy-to-user.png b/documentation/profile-manual/figures/sysprof-copy-to-user.png
new file mode 100644
index 0000000000..7a5bab7991
--- /dev/null
+++ b/documentation/profile-manual/figures/sysprof-copy-to-user.png
diff --git a/documentation/profile-manual/profile-manual-arch.xml b/documentation/profile-manual/profile-manual-arch.xml
new file mode 100644
index 0000000000..19d1155229
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-arch.xml
@@ -0,0 +1,45 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='profile-manual-arch'>
+
+<title>Overall Architecture of the Linux Tracing and Profiling Tools</title>
+
+<section id='architecture-of-the-tracing-and-profiling-tools'>
+    <title>Architecture of the Tracing and Profiling Tools</title>
+
+    <para>
+        It may seem surprising to see a section covering an 'overall architecture'
+        for what seems to be a random collection of tracing tools that together
+        make up the Linux tracing and profiling space.
+        The fact is, however, that in recent years this seemingly disparate
+        set of tools has started to converge on a 'core' set of underlying
+        mechanisms:
+    </para>
+
+    <para>
+        <itemizedlist>
+            <listitem>static tracepoints</listitem>
+            <listitem>dynamic tracepoints
+                 <itemizedlist>
+                     <listitem>kprobes</listitem>
+                     <listitem>uprobes</listitem>
+                 </itemizedlist>
+            </listitem>
+            <listitem>the perf_events subsystem</listitem>
+            <listitem>debugfs</listitem>
+        </itemizedlist>
+    </para>
+
+    <informalexample>
+        <emphasis>Tying it Together:</emphasis> Rather than enumerating here how each tool makes use of
+        these common mechanisms, textboxes like this will make note of the
+        specific usages in each tool as they come up in the course
+        of the text.
+    </informalexample>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/profile-manual/profile-manual-customization.xsl b/documentation/profile-manual/profile-manual-customization.xsl
new file mode 100644
index 0000000000..ead52ee7ac
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-customization.xsl
@@ -0,0 +1,11 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+  <xsl:param name="html.stylesheet" select="'profile-manual-style.css'" />
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel">A</xsl:param>
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/profile-manual/profile-manual-eclipse-customization.xsl b/documentation/profile-manual/profile-manual-eclipse-customization.xsl
new file mode 100644
index 0000000000..e4ff6e99ab
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-eclipse-customization.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+        xmlns="http://www.w3.org/1999/xhtml"
+        xmlns:fo="http://www.w3.org/1999/XSL/Format"
+        version="1.0">
+
+  <xsl:import
+          href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="chunk.quietly" select="1"/>
+  <xsl:param name="chunk.first.sections" select="1"/>
+  <xsl:param name="chunk.section.depth" select="10"/>
+  <xsl:param name="use.id.as.filename" select="1"/>
+  <xsl:param name="ulink.target" select="'_self'" />
+  <xsl:param name="base.dir" select="'html/profile-manual/'"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel">A</xsl:param>
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/profile-manual/profile-manual-examples.xml b/documentation/profile-manual/profile-manual-examples.xml
new file mode 100644
index 0000000000..9630c6c307
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-examples.xml
@@ -0,0 +1,39 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='profile-manual-examples'>
+
+<title>Real-World Examples</title>
+
+<para>
+    This chapter contains real-world examples.
+</para>
+
+<section id='slow-write-speed-on-live-images'>
+    <title>Slow Write Speed on Live Images</title>
+
+    <para>
+        In one of our previous releases (denzil), users noticed that booting
+        off of a live image and writing to disk was noticeably slower.
+        This included the boot itself, especially the first one, since first
+        boots tend to do a significant amount of writing due to certain
+        post-install scripts.
+    </para>
+
+    <para>
+        The problem (and solution) was discovered by using the Yocto tracing
+        tools, in this case 'perf stat', 'perf script', 'perf record'
+        and 'perf report'.
+    </para>
+
+    <para>
+        See all the unvarnished details of how this bug was diagnosed and
+        solved here: Yocto Bug #3049
+    </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/profile-manual/profile-manual-intro.xml b/documentation/profile-manual/profile-manual-intro.xml
new file mode 100644
index 0000000000..9ed807f356
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-intro.xml
@@ -0,0 +1,102 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='profile-manual-intro'>
+
+<title>Yocto Project Tracing and Profiling Manual</title>
+    <section id='intro'>
+        <title>Introduction</title>
+
+        <para>
+            Yocto bundles a number of tracing and profiling tools - this 'HOWTO'
+            describes their basic usage and shows by example how to make use
+            of them to examine application and system behavior.
+        </para>
+
+        <para>
+            The tools presented are for the most part completely open-ended and
+            have quite good and/or extensive documentation of their own which
+            can be used to solve just about any problem you might come across
+            in Linux.
+            Each section that describes a particular tool has links to that
+            tool's documentation and website.
+        </para>
+
+        <para>
+            The purpose of this 'HOWTO' is to present a set of common and
+            generally useful tracing and profiling idioms along with their
+            application (as appropriate) to each tool, in the context of a
+            general-purpose 'drill-down' methodology that can be applied
+            to solving a large number (90%?) of problems.
+            For help with more advanced usages and problems, please see
+            the documentation and/or websites listed for each tool.
+        </para>
+
+        <para>
+            The final section of this 'HOWTO' is a collection of real-world
+            examples which we'll be continually adding to as we solve more
+            problems using the tools - feel free to add your own examples
+            to the list!
+        </para>
+    </section>
+
+    <section id='profile-manual-general-setup'>
+        <title>General Setup</title>
+
+        <para>
+            Most of the tools are available only in 'sdk' images or in images
+            built after adding 'tools-profile' to your local.conf.
+            So, in order to be able to access all of the tools described here,
+            please first build and boot an 'sdk' image e.g.
+            <literallayout class='monospaced'>
+     $ bitbake core-image-sato-sdk
+            </literallayout>
+            or alternatively by adding 'tools-profile' to the
+            EXTRA_IMAGE_FEATURES line in your local.conf:
+            <literallayout class='monospaced'>
+      EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile"
+            </literallayout>
+            If you use the 'tools-profile' method, you don't need to build an
+            sdk image - the tracing and profiling tools will be included in
+            non-sdk images as well e.g.:
+            <literallayout class='monospaced'>
+     $ bitbake core-image-sato
+            </literallayout>
+            <note><para>
+                By default, the Yocto build system strips symbols from the
+                binaries it packages, which makes it difficult to use some
+                of the tools.
+                </para><para>You can prevent that by putting the following
+                in your local.conf when you build the image:
+                </para>
+            </note>
+            <literallayout class='monospaced'>
+     INHIBIT_PACKAGE_STRIP = "1"
+            </literallayout>
+            The above setting will noticeably increase the size of your image.
+        </para>
+
+        <para>
+            If you've already build a stripped image, you can generate
+            debug packages (xxx-dbg) which you can manually install as
+            needed.
+        </para>
+
+        <para>
+            To generate debug info for packages, you can add dbg-pkgs to
+            EXTRA_IMAGE_FEATURES in local.conf. For example:
+            <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
+            </literallayout>
+            Additionally, in order to generate the right type of
+            debuginfo, we also need to add the following to local.conf:
+            <literallayout class='monospaced'>
+     PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
+            </literallayout>
+        </para>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/profile-manual/profile-manual-style.css b/documentation/profile-manual/profile-manual-style.css
new file mode 100644
index 0000000000..7b1b342087
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-style.css
@@ -0,0 +1,978 @@
+/*
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("figures/profile-title.png");
+  background-position: left top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 0px;
+  text-align: right;
+  width: 740px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+}
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption,
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2;
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title,
+div.colophon .title,
+div.chapter .titlepage .title,
+div.article .titlepage .title
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/yocto-project-bw.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2;
+   color: #333;
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;
+}
+
+.tip a,
+.note a {
+   color: #333;
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
diff --git a/documentation/profile-manual/profile-manual-usage.xml b/documentation/profile-manual/profile-manual-usage.xml
new file mode 100644
index 0000000000..9116d5bf71
--- /dev/null
+++ b/documentation/profile-manual/profile-manual-usage.xml
@@ -0,0 +1,3684 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='profile-manual-usage'>
+
+<title>Basic Usage (with examples) for each of the Yocto Tracing Tools</title>
+
+<para>
+    This chapter presents basic usage examples for each of the tracing
+    tools.
+</para>
+
+<section id='profile-manual-perf'>
+    <title>perf</title>
+
+    <para>
+        The 'perf' tool is the profiling and tracing tool that comes
+        bundled with the Linux kernel.
+    </para>
+
+    <para>
+        Don't let the fact that it's part of the kernel fool you into thinking
+        that it's only for tracing and profiling the kernel - you can indeed
+        use it to trace and profile just the kernel , but you can also use it
+        to profile specific applications separately (with or without kernel
+        context), and you can also use it to trace and profile the kernel
+        and all applications on the system simultaneously to gain a system-wide
+        view of what's going on.
+    </para>
+
+    <para>
+        In many ways, it aims to be a superset of all the tracing and profiling
+        tools available in Linux today, including all the other tools covered
+        in this HOWTO. The past couple of years have seen perf subsume a lot
+        of the functionality of those other tools, and at the same time those
+        other tools have removed large portions of their previous functionality
+        and replaced it with calls to the equivalent functionality now
+        implemented by the perf subsystem. Extrapolation suggests that at
+        some point those other tools will simply become completely redundant
+        and go away; until then, we'll cover those other tools in these pages
+        and in many cases show how the same things can be accomplished in
+        perf and the other tools when it seems useful to do so.
+    </para>
+
+    <para>
+        The coverage below details some of the most common ways you'll likely
+        want to apply the tool; full documentation can be found either within
+        the tool itself or in the man pages at
+        <ulink url='http://linux.die.net/man/1/perf'>perf(1)</ulink>.
+    </para>
+
+    <section id='perf-setup'>
+        <title>Setup</title>
+
+        <para>
+            For this section, we'll assume you've already performed the basic
+            setup outlined in the General Setup section.
+        </para>
+
+        <para>
+            In particular, you'll get the most mileage out of perf if you
+            profile an image built with INHIBIT_PACKAGE_STRIP = "1" in your
+            local.conf.
+        </para>
+
+        <para>
+            perf runs on the target system for the most part. You can archive
+            profile data and copy it to the host for analysis, but for the
+            rest of this document we assume you've ssh'ed to the host and
+            will be running the perf commands on the target.
+        </para>
+    </section>
+
+    <section id='perf-basic-usage'>
+        <title>Basic Usage</title>
+
+        <para>
+            The perf tool is pretty much self-documenting. To remind yourself
+            of the available commands, simply type 'perf', which will show you
+            basic usage along with the available perf subcommands:
+            <literallayout class='monospaced'>
+     root@crownbay:~# perf
+
+     usage: perf [--version] [--help] COMMAND [ARGS]
+
+     The most commonly used perf commands are:
+       annotate        Read perf.data (created by perf record) and display annotated code
+       archive         Create archive with object files with build-ids found in perf.data file
+       bench           General framework for benchmark suites
+       buildid-cache   Manage build-id cache.
+       buildid-list    List the buildids in a perf.data file
+       diff            Read two perf.data files and display the differential profile
+       evlist          List the event names in a perf.data file
+       inject          Filter to augment the events stream with additional information
+       kmem            Tool to trace/measure kernel memory(slab) properties
+       kvm             Tool to trace/measure kvm guest os
+       list            List all symbolic event types
+       lock            Analyze lock events
+       probe           Define new dynamic tracepoints
+       record          Run a command and record its profile into perf.data
+       report          Read perf.data (created by perf record) and display the profile
+       sched           Tool to trace/measure scheduler properties (latencies)
+       script          Read perf.data (created by perf record) and display trace output
+       stat            Run a command and gather performance counter statistics
+       test            Runs sanity tests.
+       timechart       Tool to visualize total system behavior during a workload
+       top             System profiling tool.
+
+     See 'perf help COMMAND' for more information on a specific command.
+            </literallayout>
+        </para>
+
+        <section id='using-perf-to-do-basic-profiling'>
+            <title>Using perf to do Basic Profiling</title>
+
+            <para>
+                As a simple test case, we'll profile the 'wget' of a fairly large
+                file, which is a minimally interesting case because it has both
+                file and network I/O aspects, and at least in the case of standard
+                Yocto images, it's implemented as part of busybox, so the methods
+                we use to analyze it can be used in a very similar way to the whole
+                host of supported busybox applets in Yocto.
+                <literallayout class='monospaced'>
+     root@crownbay:~# rm linux-2.6.19.2.tar.bz2; \
+     wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+                </literallayout>
+                The quickest and easiest way to get some basic overall data about
+                what's going on for a particular workload it to profile it using
+                'perf stat'. 'perf stat' basically profiles using a few default
+                counters and displays the summed counts at the end of the run:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf stat wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |***************************************************| 41727k  0:00:00 ETA
+
+     Performance counter stats for 'wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>':
+
+           4597.223902 task-clock                #    0.077 CPUs utilized
+                 23568 context-switches          #    0.005 M/sec
+                    68 CPU-migrations            #    0.015 K/sec
+                   241 page-faults               #    0.052 K/sec
+            3045817293 cycles                    #    0.663 GHz
+       &lt;not supported&gt; stalled-cycles-frontend
+       &lt;not supported&gt; stalled-cycles-backend
+             858909167 instructions              #    0.28  insns per cycle
+             165441165 branches                  #   35.987 M/sec
+              19550329 branch-misses             #   11.82% of all branches
+
+          59.836627620 seconds time elapsed
+                </literallayout>
+                Many times such a simple-minded test doesn't yield much of
+                interest, but sometimes it does (see Real-world Yocto bug
+                (slow loop-mounted write speed)).
+            </para>
+
+            <para>
+                Also, note that 'perf stat' isn't restricted to a fixed set of
+                counters - basically any event listed in the output of 'perf list'
+                can be tallied by 'perf stat'. For example, suppose we wanted to
+                see a summary of all the events related to kernel memory
+                allocation/freeing along with cache hits and misses:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf stat -e kmem:* -e cache-references -e cache-misses wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |***************************************************| 41727k  0:00:00 ETA
+
+     Performance counter stats for 'wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>':
+
+                  5566 kmem:kmalloc
+                125517 kmem:kmem_cache_alloc
+                     0 kmem:kmalloc_node
+                     0 kmem:kmem_cache_alloc_node
+                 34401 kmem:kfree
+                 69920 kmem:kmem_cache_free
+                   133 kmem:mm_page_free
+                    41 kmem:mm_page_free_batched
+                 11502 kmem:mm_page_alloc
+                 11375 kmem:mm_page_alloc_zone_locked
+                     0 kmem:mm_page_pcpu_drain
+                     0 kmem:mm_page_alloc_extfrag
+              66848602 cache-references
+               2917740 cache-misses              #    4.365 % of all cache refs
+
+          44.831023415 seconds time elapsed
+                </literallayout>
+                So 'perf stat' gives us a nice easy way to get a quick overview of
+                what might be happening for a set of events, but normally we'd
+                need a little more detail in order to understand what's going on
+                in a way that we can act on in a useful way.
+            </para>
+
+            <para>
+                To dive down into a next level of detail, we can use 'perf
+                record'/'perf report' which will collect profiling data and
+                present it to use using an interactive text-based UI (or
+                simply as text if we specify --stdio to 'perf report').
+            </para>
+
+            <para>
+                As our first attempt at profiling this workload, we'll simply
+                run 'perf record', handing it the workload we want to profile
+                (everything after 'perf record' and any perf options we hand
+                it - here none - will be executedin a new shell). perf collects
+                samples until the process exits and records them in a file named
+                'perf.data' in the current working directory.
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |************************************************| 41727k  0:00:00 ETA
+     [ perf record: Woken up 1 times to write data ]
+     [ perf record: Captured and wrote 0.176 MB perf.data (~7700 samples) ]
+            </literallayout>
+            To see the results in a 'text-based UI' (tui), simply run
+            'perf report', which will read the perf.data file in the current
+            working directory and display the results in an interactive UI:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf report
+                </literallayout>
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-flat-stripped.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                The above screenshot displays a 'flat' profile, one entry for
+                each 'bucket' corresponding to the functions that were profiled
+                during the profiling run, ordered from the most popular to the
+                least (perf has options to sort in various orders and keys as
+                well as display entries only above a certain threshold and so
+                on - see the perf documentation for details). Note that this
+                includes both userspace functions (entries containing a [.]) and
+                kernel functions accounted to the process (entries containing
+                a [k]). (perf has command-line modifiers that can be used to
+                restrict the profiling to kernel or userspace, among others).
+            </para>
+
+            <para>
+                Notice also that the above report shows an entry for 'busybox',
+                which is the executable that implements 'wget' in Yocto, but that
+                instead of a useful function name in that entry, it displays
+                an not-so-friendly hex value instead. The steps below will show
+                how to fix that problem.
+            </para>
+
+            <para>
+                Before we do that, however, let's try running a different profile,
+                one which shows something a little more interesting. The only
+                difference between the new profile and the previous one is that
+                we'll add the -g option, which will record not just the address
+                of a sampled function, but the entire callchain to the sampled
+                function as well:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record -g wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |************************************************| 41727k  0:00:00 ETA
+     [ perf record: Woken up 3 times to write data ]
+     [ perf record: Captured and wrote 0.652 MB perf.data (~28476 samples) ]
+
+
+     root@crownbay:~# perf report
+                </literallayout>
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-g-copy-to-user-expanded-stripped.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                Using the callgraph view, we can actually see not only which
+                functions took the most time, but we can also see a summary of
+                how those functions were called and learn something about how the
+                program interacts with the kernel in the process.
+            </para>
+
+            <para>
+                Notice that each entry in the above screenshot now contains a '+'
+                on the left-hand side. This means that we can expand the entry and
+                drill down into the callchains that feed into that entry.
+                Pressing 'enter' on any one of them will expand the callchain
+                (you can also press 'E' to expand them all at the same time or 'C'
+                to collapse them all).
+            </para>
+
+            <para>
+                In the screenshot above, we've toggled the __copy_to_user_ll()
+                entry and several subnodes all the way down. This lets us see
+                which callchains contributed to the profiled __copy_to_user_ll()
+                function which contributed 1.77% to the total profile.
+            </para>
+
+            <para>
+                As a bit of background explanation for these callchains, think
+                about what happens at a high level when you run wget to get a file
+                out on the network. Basically what happens is that the data comes
+                into the kernel via the network connection (socket) and is passed
+                to the userspace program 'wget' (which is actually a part of
+                busybox, but that's not important for now), which takes the buffers
+                the kernel passes to it and writes it to a disk file to save it.
+            </para>
+
+            <para>
+                The part of this process that we're looking at in the above call
+                stacks is the part where the kernel passes the data it's read from
+                the socket down to wget i.e. a copy-to-user.
+            </para>
+
+            <para>
+                Notice also that here there's also a case where the a hex value
+                is displayed in the callstack, here in the expanded
+                sys_clock_gettime() function. Later we'll see it resolve to a
+                userspace function call in busybox.
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-g-copy-from-user-expanded-stripped.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                The above screenshot shows the other half of the journey for the
+                data - from the wget program's userspace buffers to disk. To get
+                the buffers to disk, the wget program issues a write(2), which
+                does a copy-from-user to the kernel, which then takes care via
+                some circuitous path (probably also present somewhere in the
+                profile data), to get it safely to disk.
+            </para>
+
+            <para>
+                Now that we've seen the basic layout of the profile data and the
+                basics of how to extract useful information out of it, let's get
+                back to the task at hand and see if we can get some basic idea
+                about where the time is spent in the program we're profiling,
+                wget. Remember that wget is actually implemented as an applet
+                in busybox, so while the process name is 'wget', the executable
+                we're actually interested in is busybox. So let's expand the
+                first entry containing busybox:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-busybox-expanded-stripped.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                Again, before we expanded we saw that the function was labeled
+                with a hex value instead of a symbol as with most of the kernel
+                entries. Expanding the busybox entry doesn't make it any better.
+            </para>
+
+            <para>
+                The problem is that perf can't find the symbol information for the
+                busybox binary, which is actually stripped out by the Yocto build
+                system.
+            </para>
+
+            <para>
+                One way around that is to put the following in your local.conf
+                when you build the image:
+                <literallayout class='monospaced'>
+     INHIBIT_PACKAGE_STRIP = "1"
+                </literallayout>
+                However, we already have an image with the binaries stripped,
+                so what can we do to get perf to resolve the symbols? Basically
+                we need to install the debuginfo for the busybox package.
+            </para>
+
+            <para>
+                To generate the debug info for the packages in the image, we can
+                to add dbg-pkgs to EXTRA_IMAGE_FEATURES in local.conf. For example:
+                <literallayout class='monospaced'>
+     EXTRA_IMAGE_FEATURES = "debug-tweaks tools-profile dbg-pkgs"
+                </literallayout>
+                Additionally, in order to generate the type of debuginfo that
+                perf understands, we also need to add the following to local.conf:
+                <literallayout class='monospaced'>
+     PACKAGE_DEBUG_SPLIT_STYLE = 'debug-file-directory'
+                </literallayout>
+                Once we've done that, we can install the debuginfo for busybox.
+                The debug packages once built can be found in
+                build/tmp/deploy/rpm/* on the host system. Find the
+                busybox-dbg-...rpm file and copy it to the target. For example:
+                <literallayout class='monospaced'>
+     [trz@empanada core2]$ scp /home/trz/yocto/crownbay-tracing-dbg/build/tmp/deploy/rpm/core2/busybox-dbg-1.20.2-r2.core2.rpm root@192.168.1.31:
+     root@192.168.1.31's password:
+     busybox-dbg-1.20.2-r2.core2.rpm                     100% 1826KB   1.8MB/s   00:01
+                </literallayout>
+                Now install the debug rpm on the target:
+                <literallayout class='monospaced'>
+     root@crownbay:~# rpm -i busybox-dbg-1.20.2-r2.core2.rpm
+                </literallayout>
+                Now that the debuginfo is installed, we see that the busybox
+                entries now display their functions symbolically:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-busybox-debuginfo.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                If we expand one of the entries and press 'enter' on a leaf node,
+                we're presented with a menu of actions we can take to get more
+                information related to that entry:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-busybox-dso-zoom-menu.png" width="6in" depth="2in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                One of these actions allows us to show a view that displays a
+                busybox-centric view of the profiled functions (in this case we've
+                also expanded all the nodes using the 'E' key):
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-busybox-dso-zoom.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                Finally, we can see that now that the busybox debuginfo is
+                installed, the previously unresolved symbol in the
+                sys_clock_gettime() entry mentioned previously is now resolved,
+                and shows that the sys_clock_gettime system call that was the
+                source of 6.75% of the copy-to-user overhead was initiated by
+                the handle_input() busybox function:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-g-copy-to-user-expanded-debuginfo.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                At the lowest level of detail, we can dive down to the assembly
+                level and see which instructions caused the most overhead in a
+                function. Pressing 'enter' on the 'udhcpc_main' function, we're
+                again presented with a menu:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-busybox-annotate-menu.png" width="6in" depth="2in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                Selecting 'Annotate udhcpc_main', we get a detailed listing of
+                percentages by instruction for the udhcpc_main function. From the
+                display, we can see that over 50% of the time spent in this
+                function is taken up by a couple tests and the move of a
+                constant (1) to a register:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-wget-busybox-annotate-udhcpc.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                As a segue into tracing, let's try another profile using a
+                different counter, something other than the default 'cycles'.
+            </para>
+
+            <para>
+                The tracing and profiling infrastructure in Linux has become
+                unified in a way that allows us to use the same tool with a
+                completely different set of counters, not just the standard
+                hardware counters that traditionally tools have had to restrict
+                themselves to (of course the traditional tools can also make use
+                of the expanded possibilities now available to them, and in some
+                cases have, as mentioned previously).
+            </para>
+
+            <para>
+                We can get a list of the available events that can be used to
+                profile a workload via 'perf list':
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf list
+
+     List of pre-defined events (to be used in -e):
+      cpu-cycles OR cycles                               [Hardware event]
+      stalled-cycles-frontend OR idle-cycles-frontend    [Hardware event]
+      stalled-cycles-backend OR idle-cycles-backend      [Hardware event]
+      instructions                                       [Hardware event]
+      cache-references                                   [Hardware event]
+      cache-misses                                       [Hardware event]
+      branch-instructions OR branches                    [Hardware event]
+      branch-misses                                      [Hardware event]
+      bus-cycles                                         [Hardware event]
+      ref-cycles                                         [Hardware event]
+
+      cpu-clock                                          [Software event]
+      task-clock                                         [Software event]
+      page-faults OR faults                              [Software event]
+      minor-faults                                       [Software event]
+      major-faults                                       [Software event]
+      context-switches OR cs                             [Software event]
+      cpu-migrations OR migrations                       [Software event]
+      alignment-faults                                   [Software event]
+      emulation-faults                                   [Software event]
+
+      L1-dcache-loads                                    [Hardware cache event]
+      L1-dcache-load-misses                              [Hardware cache event]
+      L1-dcache-prefetch-misses                          [Hardware cache event]
+      L1-icache-loads                                    [Hardware cache event]
+      L1-icache-load-misses                              [Hardware cache event]
+      .
+      .
+      .
+      rNNN                                               [Raw hardware event descriptor]
+      cpu/t1=v1[,t2=v2,t3 ...]/modifier                  [Raw hardware event descriptor]
+       (see 'perf list --help' on how to encode it)
+
+      mem:&lt;addr&gt;[:access]                                [Hardware breakpoint]
+
+      sunrpc:rpc_call_status                             [Tracepoint event]
+      sunrpc:rpc_bind_status                             [Tracepoint event]
+      sunrpc:rpc_connect_status                          [Tracepoint event]
+      sunrpc:rpc_task_begin                              [Tracepoint event]
+      skb:kfree_skb                                      [Tracepoint event]
+      skb:consume_skb                                    [Tracepoint event]
+      skb:skb_copy_datagram_iovec                        [Tracepoint event]
+      net:net_dev_xmit                                   [Tracepoint event]
+      net:net_dev_queue                                  [Tracepoint event]
+      net:netif_receive_skb                              [Tracepoint event]
+      net:netif_rx                                       [Tracepoint event]
+      napi:napi_poll                                     [Tracepoint event]
+      sock:sock_rcvqueue_full                            [Tracepoint event]
+      sock:sock_exceed_buf_limit                         [Tracepoint event]
+      udp:udp_fail_queue_rcv_skb                         [Tracepoint event]
+      hda:hda_send_cmd                                   [Tracepoint event]
+      hda:hda_get_response                               [Tracepoint event]
+      hda:hda_bus_reset                                  [Tracepoint event]
+      scsi:scsi_dispatch_cmd_start                       [Tracepoint event]
+      scsi:scsi_dispatch_cmd_error                       [Tracepoint event]
+      scsi:scsi_eh_wakeup                                [Tracepoint event]
+      drm:drm_vblank_event                               [Tracepoint event]
+      drm:drm_vblank_event_queued                        [Tracepoint event]
+      drm:drm_vblank_event_delivered                     [Tracepoint event]
+      random:mix_pool_bytes                              [Tracepoint event]
+      random:mix_pool_bytes_nolock                       [Tracepoint event]
+      random:credit_entropy_bits                         [Tracepoint event]
+      gpio:gpio_direction                                [Tracepoint event]
+      gpio:gpio_value                                    [Tracepoint event]
+      block:block_rq_abort                               [Tracepoint event]
+      block:block_rq_requeue                             [Tracepoint event]
+      block:block_rq_issue                               [Tracepoint event]
+      block:block_bio_bounce                             [Tracepoint event]
+      block:block_bio_complete                           [Tracepoint event]
+      block:block_bio_backmerge                          [Tracepoint event]
+      .
+      .
+      writeback:writeback_wake_thread                    [Tracepoint event]
+      writeback:writeback_wake_forker_thread             [Tracepoint event]
+      writeback:writeback_bdi_register                   [Tracepoint event]
+      .
+      .
+      writeback:writeback_single_inode_requeue           [Tracepoint event]
+      writeback:writeback_single_inode                   [Tracepoint event]
+      kmem:kmalloc                                       [Tracepoint event]
+      kmem:kmem_cache_alloc                              [Tracepoint event]
+      kmem:mm_page_alloc                                 [Tracepoint event]
+      kmem:mm_page_alloc_zone_locked                     [Tracepoint event]
+      kmem:mm_page_pcpu_drain                            [Tracepoint event]
+      kmem:mm_page_alloc_extfrag                         [Tracepoint event]
+      vmscan:mm_vmscan_kswapd_sleep                      [Tracepoint event]
+      vmscan:mm_vmscan_kswapd_wake                       [Tracepoint event]
+      vmscan:mm_vmscan_wakeup_kswapd                     [Tracepoint event]
+      vmscan:mm_vmscan_direct_reclaim_begin              [Tracepoint event]
+      .
+      .
+      module:module_get                                  [Tracepoint event]
+      module:module_put                                  [Tracepoint event]
+      module:module_request                              [Tracepoint event]
+      sched:sched_kthread_stop                           [Tracepoint event]
+      sched:sched_wakeup                                 [Tracepoint event]
+      sched:sched_wakeup_new                             [Tracepoint event]
+      sched:sched_process_fork                           [Tracepoint event]
+      sched:sched_process_exec                           [Tracepoint event]
+      sched:sched_stat_runtime                           [Tracepoint event]
+      rcu:rcu_utilization                                [Tracepoint event]
+      workqueue:workqueue_queue_work                     [Tracepoint event]
+      workqueue:workqueue_execute_end                    [Tracepoint event]
+      signal:signal_generate                             [Tracepoint event]
+      signal:signal_deliver                              [Tracepoint event]
+      timer:timer_init                                   [Tracepoint event]
+      timer:timer_start                                  [Tracepoint event]
+      timer:hrtimer_cancel                               [Tracepoint event]
+      timer:itimer_state                                 [Tracepoint event]
+      timer:itimer_expire                                [Tracepoint event]
+      irq:irq_handler_entry                              [Tracepoint event]
+      irq:irq_handler_exit                               [Tracepoint event]
+      irq:softirq_entry                                  [Tracepoint event]
+      irq:softirq_exit                                   [Tracepoint event]
+      irq:softirq_raise                                  [Tracepoint event]
+      printk:console                                     [Tracepoint event]
+      task:task_newtask                                  [Tracepoint event]
+      task:task_rename                                   [Tracepoint event]
+      syscalls:sys_enter_socketcall                      [Tracepoint event]
+      syscalls:sys_exit_socketcall                       [Tracepoint event]
+      .
+      .
+      .
+      syscalls:sys_enter_unshare                         [Tracepoint event]
+      syscalls:sys_exit_unshare                          [Tracepoint event]
+      raw_syscalls:sys_enter                             [Tracepoint event]
+      raw_syscalls:sys_exit                              [Tracepoint event]
+                </literallayout>
+            </para>
+
+            <informalexample>
+                <emphasis>Tying it Together:</emphasis> These are exactly the same set of events defined
+                by the trace event subsystem and exposed by
+                ftrace/tracecmd/kernelshark as files in
+                /sys/kernel/debug/tracing/events, by SystemTap as
+                kernel.trace("tracepoint_name") and (partially) accessed by LTTng.
+            </informalexample>
+
+            <para>
+                Only a subset of these would be of interest to us when looking at
+                this workload, so let's choose the most likely subsystems
+                (identified by the string before the colon in the Tracepoint events)
+                and do a 'perf stat' run using only those wildcarded subsystems:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf stat -e skb:* -e net:* -e napi:* -e sched:* -e workqueue:* -e irq:* -e syscalls:* wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+     Performance counter stats for 'wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>':
+
+                 23323 skb:kfree_skb
+                     0 skb:consume_skb
+                 49897 skb:skb_copy_datagram_iovec
+                  6217 net:net_dev_xmit
+                  6217 net:net_dev_queue
+                  7962 net:netif_receive_skb
+                     2 net:netif_rx
+                  8340 napi:napi_poll
+                     0 sched:sched_kthread_stop
+                     0 sched:sched_kthread_stop_ret
+                  3749 sched:sched_wakeup
+                     0 sched:sched_wakeup_new
+                     0 sched:sched_switch
+                    29 sched:sched_migrate_task
+                     0 sched:sched_process_free
+                     1 sched:sched_process_exit
+                     0 sched:sched_wait_task
+                     0 sched:sched_process_wait
+                     0 sched:sched_process_fork
+                     1 sched:sched_process_exec
+                     0 sched:sched_stat_wait
+         2106519415641 sched:sched_stat_sleep
+                     0 sched:sched_stat_iowait
+             147453613 sched:sched_stat_blocked
+           12903026955 sched:sched_stat_runtime
+                     0 sched:sched_pi_setprio
+                  3574 workqueue:workqueue_queue_work
+                  3574 workqueue:workqueue_activate_work
+                     0 workqueue:workqueue_execute_start
+                     0 workqueue:workqueue_execute_end
+                 16631 irq:irq_handler_entry
+                 16631 irq:irq_handler_exit
+                 28521 irq:softirq_entry
+                 28521 irq:softirq_exit
+                 28728 irq:softirq_raise
+                     1 syscalls:sys_enter_sendmmsg
+                     1 syscalls:sys_exit_sendmmsg
+                     0 syscalls:sys_enter_recvmmsg
+                     0 syscalls:sys_exit_recvmmsg
+                    14 syscalls:sys_enter_socketcall
+                    14 syscalls:sys_exit_socketcall
+                       .
+                       .
+                       .
+                 16965 syscalls:sys_enter_read
+                 16965 syscalls:sys_exit_read
+                 12854 syscalls:sys_enter_write
+                 12854 syscalls:sys_exit_write
+                       .
+                       .
+                       .
+
+          58.029710972 seconds time elapsed
+                </literallayout>
+                Let's pick one of these tracepoints and tell perf to do a profile
+                using it as the sampling event:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record -g -e sched:sched_wakeup wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+                </literallayout>
+            </para>
+
+            <para>
+                <imagedata fileref="figures/sched-wakeup-profile.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                The screenshot above shows the results of running a profile using
+                sched:sched_switch tracepoint, which shows the relative costs of
+                various paths to sched_wakeup (note that sched_wakeup is the
+                name of the tracepoint - it's actually defined just inside
+                ttwu_do_wakeup(), which accounts for the function name actually
+                displayed in the profile:
+                <literallayout class='monospaced'>
+     /*
+      * Mark the task runnable and perform wakeup-preemption.
+      */
+     static void
+     ttwu_do_wakeup(struct rq *rq, struct task_struct *p, int wake_flags)
+     {
+          trace_sched_wakeup(p, true);
+          .
+          .
+          .
+     }
+                </literallayout>
+                A couple of the more interesting callchains are expanded and
+                displayed above, basically some network receive paths that
+                presumably end up waking up wget (busybox) when network data is
+                ready.
+            </para>
+
+            <para>
+                Note that because tracepoints are normally used for tracing,
+                the default sampling period for tracepoints is 1 i.e. for
+                tracepoints perf will sample on every event occurrence (this
+                can be changed using the -c option). This is in contrast to
+                hardware counters such as for example the default 'cycles'
+                hardware counter used for normal profiling, where sampling
+                periods are much higher (in the thousands) because profiling should
+                have as low an overhead as possible and sampling on every cycle
+                would be prohibitively expensive.
+            </para>
+        </section>
+
+        <section id='using-perf-to-do-basic-tracing'>
+            <title>Using perf to do Basic Tracing</title>
+
+            <para>
+                Profiling is a great tool for solving many problems or for
+                getting a high-level view of what's going on with a workload or
+                across the system. It is however by definition an approximation,
+                as suggested by the most prominent word associated with it,
+                'sampling'. On the one hand, it allows a representative picture of
+                what's going on in the system to be cheaply taken, but on the other
+                hand, that cheapness limits its utility when that data suggests a
+                need to 'dive down' more deeply to discover what's really going
+                on. In such cases, the only way to see what's really going on is
+                to be able to look at (or summarize more intelligently) the
+                individual steps that go into the higher-level behavior exposed
+                by the coarse-grained profiling data.
+            </para>
+
+            <para>
+                As a concrete example, we can trace all the events we think might
+                be applicable to our workload:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record -g -e skb:* -e net:* -e napi:* -e sched:sched_switch -e sched:sched_wakeup -e irq:*
+      -e syscalls:sys_enter_read -e syscalls:sys_exit_read -e syscalls:sys_enter_write -e syscalls:sys_exit_write
+      wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+                </literallayout>
+                We can look at the raw trace output using 'perf script' with no
+                arguments:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf script
+
+           perf  1262 [000] 11624.857082: sys_exit_read: 0x0
+           perf  1262 [000] 11624.857193: sched_wakeup: comm=migration/0 pid=6 prio=0 success=1 target_cpu=000
+           wget  1262 [001] 11624.858021: softirq_raise: vec=1 [action=TIMER]
+           wget  1262 [001] 11624.858074: softirq_entry: vec=1 [action=TIMER]
+           wget  1262 [001] 11624.858081: softirq_exit: vec=1 [action=TIMER]
+           wget  1262 [001] 11624.858166: sys_enter_read: fd: 0x0003, buf: 0xbf82c940, count: 0x0200
+           wget  1262 [001] 11624.858177: sys_exit_read: 0x200
+           wget  1262 [001] 11624.858878: kfree_skb: skbaddr=0xeb248d80 protocol=0 location=0xc15a5308
+           wget  1262 [001] 11624.858945: kfree_skb: skbaddr=0xeb248000 protocol=0 location=0xc15a5308
+           wget  1262 [001] 11624.859020: softirq_raise: vec=1 [action=TIMER]
+           wget  1262 [001] 11624.859076: softirq_entry: vec=1 [action=TIMER]
+           wget  1262 [001] 11624.859083: softirq_exit: vec=1 [action=TIMER]
+           wget  1262 [001] 11624.859167: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400
+           wget  1262 [001] 11624.859192: sys_exit_read: 0x1d7
+           wget  1262 [001] 11624.859228: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400
+           wget  1262 [001] 11624.859233: sys_exit_read: 0x0
+           wget  1262 [001] 11624.859573: sys_enter_read: fd: 0x0003, buf: 0xbf82c580, count: 0x0200
+           wget  1262 [001] 11624.859584: sys_exit_read: 0x200
+           wget  1262 [001] 11624.859864: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400
+           wget  1262 [001] 11624.859888: sys_exit_read: 0x400
+           wget  1262 [001] 11624.859935: sys_enter_read: fd: 0x0003, buf: 0xb7720000, count: 0x0400
+           wget  1262 [001] 11624.859944: sys_exit_read: 0x400
+                </literallayout>
+                This gives us a detailed timestamped sequence of events that
+                occurred within the workload with respect to those events.
+            </para>
+
+            <para>
+                In many ways, profiling can be viewed as a subset of tracing -
+                theoretically, if you have a set of trace events that's sufficient
+                to capture all the important aspects of a workload, you can derive
+                any of the results or views that a profiling run can.
+            </para>
+
+            <para>
+                Another aspect of traditional profiling is that while powerful in
+                many ways, it's limited by the granularity of the underlying data.
+                Profiling tools offer various ways of sorting and presenting the
+                sample data, which make it much more useful and amenable to user
+                experimentation, but in the end it can't be used in an open-ended
+                way to extract data that just isn't present as a consequence of
+                the fact that conceptually, most of it has been thrown away.
+            </para>
+
+            <para>
+                Full-blown detailed tracing data does however offer the opportunity
+                to manipulate and present the information collected during a
+                tracing run in an infinite variety of ways.
+            </para>
+
+            <para>
+                Another way to look at it is that there are only so many ways that
+                the 'primitive' counters can be used on their own to generate
+                interesting output; to get anything more complicated than simple
+                counts requires some amount of additional logic, which is typically
+                very specific to the problem at hand. For example, if we wanted to
+                make use of a 'counter' that maps to the value of the time
+                difference between when a process was scheduled to run on a
+                processor and the time it actually ran, we wouldn't expect such
+                a counter to exist on its own, but we could derive one called say
+                'wakeup_latency' and use it to extract a useful view of that metric
+                from trace data. Likewise, we really can't figure out from standard
+                profiling tools how much data every process on the system reads and
+                writes, along with how many of those reads and writes fail
+                completely. If we have sufficient trace data, however, we could
+                with the right tools easily extract and present that information,
+                but we'd need something other than pre-canned profiling tools to
+                do that.
+            </para>
+
+            <para>
+                Luckily, there is general-purpose way to handle such needs,
+                called 'programming languages'. Making programming languages
+                easily available to apply to such problems given the specific
+                format of data is called a 'programming language binding' for
+                that data and language. Perf supports two programming language
+                bindings, one for Python and one for Perl.
+            </para>
+
+            <informalexample>
+                <emphasis>Tying it Together:</emphasis> Language bindings for manipulating and
+                aggregating trace data are of course not a new
+                idea.  One of the first projects to do this was IBM's DProbes
+                dpcc compiler, an ANSI C compiler which targeted a low-level
+                assembly language running on an in-kernel interpreter on the
+                target system.  This is exactly analagous to what Sun's DTrace
+                did, except that DTrace invented its own language for the purpose.
+                Systemtap, heavily inspired by DTrace, also created its own
+                one-off language, but rather than running the product on an
+                in-kernel interpreter, created an elaborate compiler-based
+                machinery to translate its language into kernel modules written
+                in C.
+            </informalexample>
+
+            <para>
+                Now that we have the trace data in perf.data, we can use
+                'perf script -g' to generate a skeleton script with handlers
+                for the read/write entry/exit events we recorded:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf script -g python
+     generated Python script: perf-script.py
+                </literallayout>
+                The skeleton script simply creates a python function for each
+                event type in the perf.data file. The body of each function simply
+                prints the event name along with its parameters. For example:
+                <literallayout class='monospaced'>
+     def net__netif_rx(event_name, context, common_cpu,
+            common_secs, common_nsecs, common_pid, common_comm,
+            skbaddr, len, name):
+                    print_header(event_name, common_cpu, common_secs, common_nsecs,
+                            common_pid, common_comm)
+
+                     print "skbaddr=%u, len=%u, name=%s\n" % (skbaddr, len, name),
+                </literallayout>
+                We can run that script directly to print all of the events
+                contained in the perf.data file:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf script -s perf-script.py
+
+     in trace_begin
+     syscalls__sys_exit_read     0 11624.857082795     1262 perf                  nr=3, ret=0
+     sched__sched_wakeup      0 11624.857193498     1262 perf                  comm=migration/0, pid=6, prio=0,      success=1, target_cpu=0
+     irq__softirq_raise       1 11624.858021635     1262 wget                  vec=TIMER
+     irq__softirq_entry       1 11624.858074075     1262 wget                  vec=TIMER
+     irq__softirq_exit        1 11624.858081389     1262 wget                  vec=TIMER
+     syscalls__sys_enter_read     1 11624.858166434     1262 wget                  nr=3, fd=3, buf=3213019456,      count=512
+     syscalls__sys_exit_read     1 11624.858177924     1262 wget                  nr=3, ret=512
+     skb__kfree_skb           1 11624.858878188     1262 wget                  skbaddr=3945041280,           location=3243922184, protocol=0
+     skb__kfree_skb           1 11624.858945608     1262 wget                  skbaddr=3945037824,      location=3243922184, protocol=0
+     irq__softirq_raise       1 11624.859020942     1262 wget                  vec=TIMER
+     irq__softirq_entry       1 11624.859076935     1262 wget                  vec=TIMER
+     irq__softirq_exit        1 11624.859083469     1262 wget                  vec=TIMER
+     syscalls__sys_enter_read     1 11624.859167565     1262 wget                  nr=3, fd=3, buf=3077701632,      count=1024
+     syscalls__sys_exit_read     1 11624.859192533     1262 wget                  nr=3, ret=471
+     syscalls__sys_enter_read     1 11624.859228072     1262 wget                  nr=3, fd=3, buf=3077701632,      count=1024
+     syscalls__sys_exit_read     1 11624.859233707     1262 wget                  nr=3, ret=0
+     syscalls__sys_enter_read     1 11624.859573008     1262 wget                  nr=3, fd=3, buf=3213018496,      count=512
+     syscalls__sys_exit_read     1 11624.859584818     1262 wget                  nr=3, ret=512
+     syscalls__sys_enter_read     1 11624.859864562     1262 wget                  nr=3, fd=3, buf=3077701632,      count=1024
+     syscalls__sys_exit_read     1 11624.859888770     1262 wget                  nr=3, ret=1024
+     syscalls__sys_enter_read     1 11624.859935140     1262 wget                  nr=3, fd=3, buf=3077701632,      count=1024
+     syscalls__sys_exit_read     1 11624.859944032     1262 wget                  nr=3, ret=1024
+                </literallayout>
+                That in itself isn't very useful; after all, we can accomplish
+                pretty much the same thing by simply running 'perf script'
+                without arguments in the same directory as the perf.data file.
+            </para>
+
+            <para>
+                We can however replace the print statements in the generated
+                function bodies with whatever we want, and thereby make it
+                infinitely more useful.
+            </para>
+
+            <para>
+                As a simple example, let's just replace the print statements in
+                the function bodies with a simple function that does nothing but
+                increment a per-event count. When the program is run against a
+                perf.data file, each time a particular event is encountered,
+                a tally is incremented for that event. For example:
+                <literallayout class='monospaced'>
+     def net__netif_rx(event_name, context, common_cpu,
+            common_secs, common_nsecs, common_pid, common_comm,
+            skbaddr, len, name):
+                          inc_counts(event_name)
+                </literallayout>
+                Each event handler function in the generated code is modified
+                to do this. For convenience, we define a common function called
+                inc_counts() that each handler calls; inc_counts simply tallies
+                a count for each event using the 'counts' hash, which is a
+                specialized has function that does Perl-like autovivification, a
+                capability that's extremely useful for kinds of multi-level
+                aggregation commonly used in processing traces (see perf's
+                documentation on the Python language binding for details):
+                <literallayout class='monospaced'>
+     counts = autodict()
+
+     def inc_counts(event_name):
+            try:
+                    counts[event_name] += 1
+            except TypeError:
+                    counts[event_name] = 1
+                </literallayout>
+                Finally, at the end of the trace processing run, we want to
+                print the result of all the per-event tallies. For that, we
+                use the special 'trace_end()' function:
+                <literallayout class='monospaced'>
+     def trace_end():
+            for event_name, count in counts.iteritems():
+                    print "%-40s %10s\n" % (event_name, count)
+                </literallayout>
+                The end result is a summary of all the events recorded in the
+                trace:
+                <literallayout class='monospaced'>
+     skb__skb_copy_datagram_iovec                  13148
+     irq__softirq_entry                             4796
+     irq__irq_handler_exit                          3805
+     irq__softirq_exit                              4795
+     syscalls__sys_enter_write                      8990
+     net__net_dev_xmit                               652
+     skb__kfree_skb                                 4047
+     sched__sched_wakeup                            1155
+     irq__irq_handler_entry                         3804
+     irq__softirq_raise                             4799
+     net__net_dev_queue                              652
+     syscalls__sys_enter_read                      17599
+     net__netif_receive_skb                         1743
+     syscalls__sys_exit_read                       17598
+     net__netif_rx                                     2
+     napi__napi_poll                                1877
+     syscalls__sys_exit_write                       8990
+                </literallayout>
+                Note that this is pretty much exactly the same information we get
+                from 'perf stat', which goes a little way to support the idea
+                mentioned previously that given the right kind of trace data,
+                higher-level profiling-type summaries can be derived from it.
+            </para>
+
+            <para>
+                Documentation on using the
+                <ulink url='http://linux.die.net/man/1/perf-script-python'>'perf script' python binding</ulink>.
+            </para>
+        </section>
+
+        <section id='system-wide-tracing-and-profiling'>
+            <title>System-Wide Tracing and Profiling</title>
+
+            <para>
+                The examples so far have focused on tracing a particular program or
+                workload - in other words, every profiling run has specified the
+                program to profile in the command-line e.g. 'perf record wget ...'.
+            </para>
+
+            <para>
+                It's also possible, and more interesting in many cases, to run a
+                system-wide profile or trace while running the workload in a
+                separate shell.
+            </para>
+
+            <para>
+                To do system-wide profiling or tracing, you typically use
+                the -a flag to 'perf record'.
+            </para>
+
+            <para>
+                To demonstrate this, open up one window and start the profile
+                using the -a flag (press Ctrl-C to stop tracing):
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record -g -a
+     ^C[ perf record: Woken up 6 times to write data ]
+     [ perf record: Captured and wrote 1.400 MB perf.data (~61172 samples) ]
+                </literallayout>
+                In another window, run the wget test:
+                <literallayout class='monospaced'>
+     root@crownbay:~# wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |*******************************| 41727k  0:00:00 ETA
+                </literallayout>
+                Here we see entries not only for our wget load, but for other
+                processes running on the system as well:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-systemwide.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                In the snapshot above, we can see callchains that originate in
+                libc, and a callchain from Xorg that demonstrates that we're
+                using a proprietary X driver in userspace (notice the presence
+                of 'PVR' and some other unresolvable symbols in the expanded
+                Xorg callchain).
+            </para>
+
+            <para>
+                Note also that we have both kernel and userspace entries in the
+                above snapshot. We can also tell perf to focus on userspace but
+                providing a modifier, in this case 'u', to the 'cycles' hardware
+                counter when we record a profile:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record -g -a -e cycles:u
+     ^C[ perf record: Woken up 2 times to write data ]
+     [ perf record: Captured and wrote 0.376 MB perf.data (~16443 samples) ]
+                </literallayout>
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-report-cycles-u.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                Notice in the screenshot above, we see only userspace entries ([.])
+            </para>
+
+            <para>
+                Finally, we can press 'enter' on a leaf node and select the 'Zoom
+                into DSO' menu item to show only entries associated with a
+                specific DSO. In the screenshot below, we've zoomed into the
+                'libc' DSO which shows all the entries associated with the
+                libc-xxx.so DSO.
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-systemwide-libc.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                We can also use the system-wide -a switch to do system-wide
+                tracing. Here we'll trace a couple of scheduler events:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record -a -e sched:sched_switch -e sched:sched_wakeup
+     ^C[ perf record: Woken up 38 times to write data ]
+     [ perf record: Captured and wrote 9.780 MB perf.data (~427299 samples) ]
+                </literallayout>
+                We can look at the raw output using 'perf script' with no
+                arguments:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf script
+
+                perf  1383 [001]  6171.460045: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                perf  1383 [001]  6171.460066: sched_switch: prev_comm=perf prev_pid=1383 prev_prio=120 prev_state=R+ ==> next_comm=kworker/1:1 next_pid=21 next_prio=120
+         kworker/1:1    21 [001]  6171.460093: sched_switch: prev_comm=kworker/1:1 prev_pid=21 prev_prio=120 prev_state=S ==> next_comm=perf next_pid=1383 next_prio=120
+             swapper     0 [000]  6171.468063: sched_wakeup: comm=kworker/0:3 pid=1209 prio=120 success=1 target_cpu=000
+             swapper     0 [000]  6171.468107: sched_switch: prev_comm=swapper/0 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/0:3 next_pid=1209 next_prio=120
+         kworker/0:3  1209 [000]  6171.468143: sched_switch: prev_comm=kworker/0:3 prev_pid=1209 prev_prio=120 prev_state=S ==> next_comm=swapper/0 next_pid=0 next_prio=120
+                perf  1383 [001]  6171.470039: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                perf  1383 [001]  6171.470058: sched_switch: prev_comm=perf prev_pid=1383 prev_prio=120 prev_state=R+ ==> next_comm=kworker/1:1 next_pid=21 next_prio=120
+         kworker/1:1    21 [001]  6171.470082: sched_switch: prev_comm=kworker/1:1 prev_pid=21 prev_prio=120 prev_state=S ==> next_comm=perf next_pid=1383 next_prio=120
+                perf  1383 [001]  6171.480035: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                </literallayout>
+            </para>
+
+            <section id='perf-filtering'>
+                <title>Filtering</title>
+
+                <para>
+                    Notice that there are a lot of events that don't really have
+                    anything to do with what we're interested in, namely events
+                    that schedule 'perf' itself in and out or that wake perf up.
+                    We can get rid of those by using the '--filter' option -
+                    for each event we specify using -e, we can add a --filter
+                    after that to filter out trace events that contain fields
+                    with specific values:
+                    <literallayout class='monospaced'>
+     root@crownbay:~# perf record -a -e sched:sched_switch --filter 'next_comm != perf &amp;&amp; prev_comm != perf' -e sched:sched_wakeup --filter 'comm != perf'
+     ^C[ perf record: Woken up 38 times to write data ]
+     [ perf record: Captured and wrote 9.688 MB perf.data (~423279 samples) ]
+
+
+     root@crownbay:~# perf script
+
+             swapper     0 [000]  7932.162180: sched_switch: prev_comm=swapper/0 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/0:3 next_pid=1209 next_prio=120
+         kworker/0:3  1209 [000]  7932.162236: sched_switch: prev_comm=kworker/0:3 prev_pid=1209 prev_prio=120 prev_state=S ==> next_comm=swapper/0 next_pid=0 next_prio=120
+                perf  1407 [001]  7932.170048: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                perf  1407 [001]  7932.180044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                perf  1407 [001]  7932.190038: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                perf  1407 [001]  7932.200044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                perf  1407 [001]  7932.210044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+                perf  1407 [001]  7932.220044: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+             swapper     0 [001]  7932.230111: sched_wakeup: comm=kworker/1:1 pid=21 prio=120 success=1 target_cpu=001
+             swapper     0 [001]  7932.230146: sched_switch: prev_comm=swapper/1 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/1:1 next_pid=21 next_prio=120
+         kworker/1:1    21 [001]  7932.230205: sched_switch: prev_comm=kworker/1:1 prev_pid=21 prev_prio=120 prev_state=S ==> next_comm=swapper/1 next_pid=0 next_prio=120
+             swapper     0 [000]  7932.326109: sched_wakeup: comm=kworker/0:3 pid=1209 prio=120 success=1 target_cpu=000
+             swapper     0 [000]  7932.326171: sched_switch: prev_comm=swapper/0 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=kworker/0:3 next_pid=1209 next_prio=120
+         kworker/0:3  1209 [000]  7932.326214: sched_switch: prev_comm=kworker/0:3 prev_pid=1209 prev_prio=120 prev_state=S ==> next_comm=swapper/0 next_pid=0 next_prio=120
+                    </literallayout>
+                    In this case, we've filtered out all events that have 'perf'
+                    in their 'comm' or 'comm_prev' or 'comm_next' fields. Notice
+                    that there are still events recorded for perf, but notice
+                    that those events don't have values of 'perf' for the filtered
+                    fields. To completely filter out anything from perf will
+                    require a bit more work, but for the purpose of demonstrating
+                    how to use filters, it's close enough.
+                </para>
+
+                <informalexample>
+                    <emphasis>Tying it Together:</emphasis> These are exactly the same set of event
+                    filters defined by the trace event subsystem. See the
+                    ftrace/tracecmd/kernelshark section for more discussion about
+                    these event filters.
+                </informalexample>
+
+                <informalexample>
+                    <emphasis>Tying it Together:</emphasis> These event filters are implemented by a
+                    special-purpose pseudo-interpreter in the kernel and are an
+                    integral and indispensable part of the perf design as it
+                    relates to tracing.  kernel-based event filters provide a
+                    mechanism to precisely throttle the event stream that appears
+                    in user space, where it makes sense to provide bindings to real
+                    programming languages for postprocessing the event stream.
+                    This architecture allows for the intelligent and flexible
+                    partitioning of processing between the kernel and user space.
+                    Contrast this with other tools such as SystemTap, which does
+                    all of its processing in the kernel and as such requires a
+                    special project-defined language in order to accommodate that
+                    design, or LTTng, where everything is sent to userspace and
+                    as such requires a super-efficient kernel-to-userspace
+                    transport mechanism in order to function properly.  While
+                    perf certainly can benefit from for instance advances in
+                    the design of the transport, it doesn't fundamentally depend
+                    on them.  Basically, if you find that your perf tracing
+                    application is causing buffer I/O overruns, it probably
+                    means that you aren't taking enough advantage of the
+                    kernel filtering engine.
+                </informalexample>
+            </section>
+        </section>
+
+        <section id='using-dynamic-tracepoints'>
+            <title>Using Dynamic Tracepoints</title>
+
+            <para>
+                perf isn't restricted to the fixed set of static tracepoints
+                listed by 'perf list'. Users can also add their own 'dynamic'
+                tracepoints anywhere in the kernel. For instance, suppose we
+                want to define our own tracepoint on do_fork(). We can do that
+                using the 'perf probe' perf subcommand:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf probe do_fork
+     Added new event:
+       probe:do_fork        (on do_fork)
+
+     You can now use it in all perf tools, such as:
+
+             perf record -e probe:do_fork -aR sleep 1
+                </literallayout>
+                Adding a new tracepoint via 'perf probe' results in an event
+                with all the expected files and format in
+                /sys/kernel/debug/tracing/events, just the same as for static
+                tracepoints (as discussed in more detail in the trace events
+                subsystem section:
+                <literallayout class='monospaced'>
+     root@crownbay:/sys/kernel/debug/tracing/events/probe/do_fork# ls -al
+     drwxr-xr-x    2 root     root             0 Oct 28 11:42 .
+     drwxr-xr-x    3 root     root             0 Oct 28 11:42 ..
+     -rw-r--r--    1 root     root             0 Oct 28 11:42 enable
+     -rw-r--r--    1 root     root             0 Oct 28 11:42 filter
+     -r--r--r--    1 root     root             0 Oct 28 11:42 format
+     -r--r--r--    1 root     root             0 Oct 28 11:42 id
+
+     root@crownbay:/sys/kernel/debug/tracing/events/probe/do_fork# cat format
+     name: do_fork
+     ID: 944
+     format:
+             field:unsigned short common_type;  offset:0;       size:2; signed:0;
+             field:unsigned char common_flags;  offset:2;       size:1; signed:0;
+             field:unsigned char common_preempt_count;  offset:3;       size:1; signed:0;
+             field:int common_pid;      offset:4;       size:4; signed:1;
+             field:int common_padding;  offset:8;       size:4; signed:1;
+
+             field:unsigned long __probe_ip;    offset:12;      size:4; signed:0;
+
+     print fmt: "(%lx)", REC->__probe_ip
+                </literallayout>
+                We can list all dynamic tracepoints currently in existence:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf probe -l
+      probe:do_fork        (on do_fork)
+      probe:schedule       (on schedule)
+                </literallayout>
+                Let's record system-wide ('sleep 30' is a trick for recording
+                system-wide but basically do nothing and then wake up after
+                30 seconds):
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf record -g -a -e probe:do_fork sleep 30
+     [ perf record: Woken up 1 times to write data ]
+     [ perf record: Captured and wrote 0.087 MB perf.data (~3812 samples) ]
+                </literallayout>
+                Using 'perf script' we can see each do_fork event that fired:
+                <literallayout class='monospaced'>
+     root@crownbay:~# perf script
+
+     # ========
+     # captured on: Sun Oct 28 11:55:18 2012
+     # hostname : crownbay
+     # os release : 3.4.11-yocto-standard
+     # perf version : 3.4.11
+     # arch : i686
+     # nrcpus online : 2
+     # nrcpus avail : 2
+     # cpudesc : Intel(R) Atom(TM) CPU E660 @ 1.30GHz
+     # cpuid : GenuineIntel,6,38,1
+     # total memory : 1017184 kB
+     # cmdline : /usr/bin/perf record -g -a -e probe:do_fork sleep 30
+     # event : name = probe:do_fork, type = 2, config = 0x3b0, config1 = 0x0, config2 = 0x0, excl_usr = 0, excl_kern
+      = 0, id = { 5, 6 }
+     # HEADER_CPU_TOPOLOGY info available, use -I to display
+     # ========
+     #
+      matchbox-deskto  1197 [001] 34211.378318: do_fork: (c1028460)
+      matchbox-deskto  1295 [001] 34211.380388: do_fork: (c1028460)
+              pcmanfm  1296 [000] 34211.632350: do_fork: (c1028460)
+              pcmanfm  1296 [000] 34211.639917: do_fork: (c1028460)
+      matchbox-deskto  1197 [001] 34217.541603: do_fork: (c1028460)
+      matchbox-deskto  1299 [001] 34217.543584: do_fork: (c1028460)
+               gthumb  1300 [001] 34217.697451: do_fork: (c1028460)
+               gthumb  1300 [001] 34219.085734: do_fork: (c1028460)
+               gthumb  1300 [000] 34219.121351: do_fork: (c1028460)
+               gthumb  1300 [001] 34219.264551: do_fork: (c1028460)
+              pcmanfm  1296 [000] 34219.590380: do_fork: (c1028460)
+      matchbox-deskto  1197 [001] 34224.955965: do_fork: (c1028460)
+      matchbox-deskto  1306 [001] 34224.957972: do_fork: (c1028460)
+      matchbox-termin  1307 [000] 34225.038214: do_fork: (c1028460)
+      matchbox-termin  1307 [001] 34225.044218: do_fork: (c1028460)
+      matchbox-termin  1307 [000] 34225.046442: do_fork: (c1028460)
+      matchbox-deskto  1197 [001] 34237.112138: do_fork: (c1028460)
+      matchbox-deskto  1311 [001] 34237.114106: do_fork: (c1028460)
+                 gaku  1312 [000] 34237.202388: do_fork: (c1028460)
+                </literallayout>
+                And using 'perf report' on the same file, we can see the
+                callgraphs from starting a few programs during those 30 seconds:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/perf-probe-do_fork-profile.png" width="6in" depth="7in" align="center" scalefit="1" />
+            </para>
+
+            <informalexample>
+                <emphasis>Tying it Together:</emphasis> The trace events subsystem accomodate static
+                and dynamic tracepoints in exactly the same way - there's no
+                difference as far as the infrastructure is concerned.  See the
+                ftrace section for more details on the trace event subsystem.
+            </informalexample>
+
+            <informalexample>
+                <emphasis>Tying it Together:</emphasis> Dynamic tracepoints are implemented under the
+                covers by kprobes and uprobes.  kprobes and uprobes are also used
+                by and in fact are the main focus of SystemTap.
+            </informalexample>
+        </section>
+    </section>
+
+    <section id='perf-documentation'>
+        <title>Documentation</title>
+
+        <para>
+            Online versions of the man pages for the commands discussed in this
+            section can be found here:
+            <itemizedlist>
+                <listitem><para>The <ulink url='http://linux.die.net/man/1/perf-stat'>'perf stat' manpage</ulink>.
+                    </para></listitem>
+                <listitem><para>The <ulink url='http://linux.die.net/man/1/perf-record'>'perf record' manpage</ulink>.
+                    </para></listitem>
+                <listitem><para>The <ulink url='http://linux.die.net/man/1/perf-report'>'perf report' manpage</ulink>.
+                    </para></listitem>
+                <listitem><para>The <ulink url='http://linux.die.net/man/1/perf-probe'>'perf probe' manpage</ulink>.
+                    </para></listitem>
+                <listitem><para>The <ulink url='http://linux.die.net/man/1/perf-script'>'perf script' manpage</ulink>.
+                    </para></listitem>
+                <listitem><para>Documentation on using the
+                    <ulink url='http://linux.die.net/man/1/perf-script-python'>'perf script' python binding</ulink>.
+                    </para></listitem>
+                <listitem><para>The top-level
+                    <ulink url='http://linux.die.net/man/1/perf'>perf(1) manpage</ulink>.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Normally, you should be able to invoke the man pages via perf
+            itself e.g. 'perf help' or 'perf help record'.
+        </para>
+
+        <para>
+            However, by default Yocto doesn't install man pages, but perf
+            invokes the man pages for most help functionality. This is a bug
+            and is being addressed by a Yocto bug:
+            <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=3388'>Bug 3388 - perf: enable man pages for basic 'help' functionality</ulink>.
+        </para>
+
+        <para>
+            The man pages in text form, along with some other files, such as
+            a set of examples, can be found in the 'perf' directory of the
+            kernel tree:
+            <literallayout class='monospaced'>
+     tools/perf/Documentation
+            </literallayout>
+            There's also a nice perf tutorial on the perf wiki that goes
+            into more detail than we do here in certain areas:
+            <ulink url='https://perf.wiki.kernel.org/index.php/Tutorial'>Perf Tutorial</ulink>
+        </para>
+    </section>
+</section>
+
+<section id='profile-manual-ftrace'>
+    <title>ftrace</title>
+
+    <para>
+        'ftrace' literally refers to the 'ftrace function tracer' but in
+        reality this encompasses a number of related tracers along with
+        the infrastructure that they all make use of.
+    </para>
+
+    <section id='ftrace-setup'>
+        <title>Setup</title>
+
+        <para>
+            For this section, we'll assume you've already performed the basic
+            setup outlined in the General Setup section.
+        </para>
+
+        <para>
+            ftrace, trace-cmd, and kernelshark run on the target system,
+            and are ready to go out-of-the-box - no additional setup is
+            necessary. For the rest of this section we assume you've ssh'ed
+            to the host and will be running ftrace on the target. kernelshark
+            is a GUI application and if you use the '-X' option to ssh you
+            can have the kernelshark GUI run on the target but display
+            remotely on the host if you want.
+        </para>
+    </section>
+
+    <section id='basic-ftrace-usage'>
+        <title>Basic ftrace usage</title>
+
+        <para>
+            'ftrace' essentially refers to everything included in
+            the /tracing directory of the mounted debugfs filesystem
+            (Yocto follows the standard convention and mounts it
+            at /sys/kernel/debug). Here's a listing of all the files
+            found in /sys/kernel/debug/tracing on a Yocto system.:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# ls
+     README                      kprobe_events               trace
+     available_events            kprobe_profile              trace_clock
+     available_filter_functions  options                     trace_marker
+     available_tracers           per_cpu                     trace_options
+     buffer_size_kb              printk_formats              trace_pipe
+     buffer_total_size_kb        saved_cmdlines              tracing_cpumask
+     current_tracer              set_event                   tracing_enabled
+     dyn_ftrace_total_info       set_ftrace_filter           tracing_on
+     enabled_functions           set_ftrace_notrace          tracing_thresh
+     events                      set_ftrace_pid
+     free_buffer                 set_graph_function
+            </literallayout>
+            The files listed above are used for various purposes -
+            some relate directly to the tracers themselves, others are
+            used to set tracing options, and yet others actually contain
+            the tracing output when a tracer is in effect. Some of the
+            functions can be guessed from their names, others need
+            explanation; in any case, we'll cover some of the files we
+            see here below but for an explanation of the others, please
+            see the ftrace documentation.
+        </para>
+
+        <para>
+            We'll start by looking at some of the available built-in
+            tracers.
+        </para>
+
+        <para>
+            cat'ing the 'available_tracers' file lists the set of
+            available tracers:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# cat available_tracers
+     blk function_graph function nop
+            </literallayout>
+            The 'current_tracer' file contains the tracer currently in
+            effect:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer
+     nop
+            </literallayout>
+            The above listing of current_tracer shows that
+            the 'nop' tracer is in effect, which is just another
+            way of saying that there's actually no tracer
+            currently in effect.
+        </para>
+
+        <para>
+            echo'ing one of the available_tracers into current_tracer
+            makes the specified tracer the current tracer:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# echo function > current_tracer
+     root@sugarbay:/sys/kernel/debug/tracing# cat current_tracer
+     function
+            </literallayout>
+            The above sets the current tracer to be the
+            'function tracer'. This tracer traces every function
+            call in the kernel and makes it available as the
+            contents of the 'trace' file. Reading the 'trace' file
+            lists the currently buffered function calls that have been
+            traced by the function tracer:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# cat trace | less
+
+     # tracer: function
+     #
+     # entries-in-buffer/entries-written: 310629/766471   #P:8
+     #
+     #                              _-----=&gt; irqs-off
+     #                             / _----=&gt; need-resched
+     #                            | / _---=&gt; hardirq/softirq
+     #                            || / _--=&gt; preempt-depth
+     #                            ||| /     delay
+     #           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
+     #              | |       |   ||||       |         |
+              &lt;idle&gt;-0     [004] d..1   470.867169: ktime_get_real &lt;-intel_idle
+              &lt;idle&gt;-0     [004] d..1   470.867170: getnstimeofday &lt;-ktime_get_real
+              &lt;idle&gt;-0     [004] d..1   470.867171: ns_to_timeval &lt;-intel_idle
+              &lt;idle&gt;-0     [004] d..1   470.867171: ns_to_timespec &lt;-ns_to_timeval
+              &lt;idle&gt;-0     [004] d..1   470.867172: smp_apic_timer_interrupt &lt;-apic_timer_interrupt
+              &lt;idle&gt;-0     [004] d..1   470.867172: native_apic_mem_write &lt;-smp_apic_timer_interrupt
+              &lt;idle&gt;-0     [004] d..1   470.867172: irq_enter &lt;-smp_apic_timer_interrupt
+              &lt;idle&gt;-0     [004] d..1   470.867172: rcu_irq_enter &lt;-irq_enter
+              &lt;idle&gt;-0     [004] d..1   470.867173: rcu_idle_exit_common.isra.33 &lt;-rcu_irq_enter
+              &lt;idle&gt;-0     [004] d..1   470.867173: local_bh_disable &lt;-irq_enter
+              &lt;idle&gt;-0     [004] d..1   470.867173: add_preempt_count &lt;-local_bh_disable
+              &lt;idle&gt;-0     [004] d.s1   470.867174: tick_check_idle &lt;-irq_enter
+              &lt;idle&gt;-0     [004] d.s1   470.867174: tick_check_oneshot_broadcast &lt;-tick_check_idle
+              &lt;idle&gt;-0     [004] d.s1   470.867174: ktime_get &lt;-tick_check_idle
+              &lt;idle&gt;-0     [004] d.s1   470.867174: tick_nohz_stop_idle &lt;-tick_check_idle
+              &lt;idle&gt;-0     [004] d.s1   470.867175: update_ts_time_stats &lt;-tick_nohz_stop_idle
+              &lt;idle&gt;-0     [004] d.s1   470.867175: nr_iowait_cpu &lt;-update_ts_time_stats
+              &lt;idle&gt;-0     [004] d.s1   470.867175: tick_do_update_jiffies64 &lt;-tick_check_idle
+              &lt;idle&gt;-0     [004] d.s1   470.867175: _raw_spin_lock &lt;-tick_do_update_jiffies64
+              &lt;idle&gt;-0     [004] d.s1   470.867176: add_preempt_count &lt;-_raw_spin_lock
+              &lt;idle&gt;-0     [004] d.s2   470.867176: do_timer &lt;-tick_do_update_jiffies64
+              &lt;idle&gt;-0     [004] d.s2   470.867176: _raw_spin_lock &lt;-do_timer
+              &lt;idle&gt;-0     [004] d.s2   470.867176: add_preempt_count &lt;-_raw_spin_lock
+              &lt;idle&gt;-0     [004] d.s3   470.867177: ntp_tick_length &lt;-do_timer
+              &lt;idle&gt;-0     [004] d.s3   470.867177: _raw_spin_lock_irqsave &lt;-ntp_tick_length
+              .
+              .
+              .
+            </literallayout>
+            Each line in the trace above shows what was happening in
+            the kernel on a given cpu, to the level of detail of
+            function calls. Each entry shows the function called,
+            followed by its caller (after the arrow).
+        </para>
+
+        <para>
+            The function tracer gives you an extremely detailed idea
+            of what the kernel was doing at the point in time the trace
+            was taken, and is a great way to learn about how the kernel
+            code works in a dynamic sense.
+        </para>
+
+        <informalexample>
+            <emphasis>Tying it Together:</emphasis> The ftrace function tracer is also
+            available from within perf, as the ftrace:function tracepoint.
+        </informalexample>
+
+        <para>
+            It is a little more difficult to follow the call chains than
+            it needs to be - luckily there's a variant of the function
+            tracer that displays the callchains explicitly, called the
+            'function_graph' tracer:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# echo function_graph &gt; current_tracer
+     root@sugarbay:/sys/kernel/debug/tracing# cat trace | less
+
+      tracer: function_graph
+
+      CPU  DURATION                  FUNCTION CALLS
+      |     |   |                     |   |   |   |
+     7)   0.046 us    |      pick_next_task_fair();
+     7)   0.043 us    |      pick_next_task_stop();
+     7)   0.042 us    |      pick_next_task_rt();
+     7)   0.032 us    |      pick_next_task_fair();
+     7)   0.030 us    |      pick_next_task_idle();
+     7)               |      _raw_spin_unlock_irq() {
+     7)   0.033 us    |        sub_preempt_count();
+     7)   0.258 us    |      }
+     7)   0.032 us    |      sub_preempt_count();
+     7) + 13.341 us   |    } /* __schedule */
+     7)   0.095 us    |  } /* sub_preempt_count */
+     7)               |  schedule() {
+     7)               |    __schedule() {
+     7)   0.060 us    |      add_preempt_count();
+     7)   0.044 us    |      rcu_note_context_switch();
+     7)               |      _raw_spin_lock_irq() {
+     7)   0.033 us    |        add_preempt_count();
+     7)   0.247 us    |      }
+     7)               |      idle_balance() {
+     7)               |        _raw_spin_unlock() {
+     7)   0.031 us    |          sub_preempt_count();
+     7)   0.246 us    |        }
+     7)               |        update_shares() {
+     7)   0.030 us    |          __rcu_read_lock();
+     7)   0.029 us    |          __rcu_read_unlock();
+     7)   0.484 us    |        }
+     7)   0.030 us    |        __rcu_read_lock();
+     7)               |        load_balance() {
+     7)               |          find_busiest_group() {
+     7)   0.031 us    |            idle_cpu();
+     7)   0.029 us    |            idle_cpu();
+     7)   0.035 us    |            idle_cpu();
+     7)   0.906 us    |          }
+     7)   1.141 us    |        }
+     7)   0.022 us    |        msecs_to_jiffies();
+     7)               |        load_balance() {
+     7)               |          find_busiest_group() {
+     7)   0.031 us    |            idle_cpu();
+     .
+     .
+     .
+     4)   0.062 us    |        msecs_to_jiffies();
+     4)   0.062 us    |        __rcu_read_unlock();
+     4)               |        _raw_spin_lock() {
+     4)   0.073 us    |          add_preempt_count();
+     4)   0.562 us    |        }
+     4) + 17.452 us   |      }
+     4)   0.108 us    |      put_prev_task_fair();
+     4)   0.102 us    |      pick_next_task_fair();
+     4)   0.084 us    |      pick_next_task_stop();
+     4)   0.075 us    |      pick_next_task_rt();
+     4)   0.062 us    |      pick_next_task_fair();
+     4)   0.066 us    |      pick_next_task_idle();
+     ------------------------------------------
+     4)   kworker-74   =&gt;    &lt;idle&gt;-0
+     ------------------------------------------
+
+     4)               |      finish_task_switch() {
+     4)               |        _raw_spin_unlock_irq() {
+     4)   0.100 us    |          sub_preempt_count();
+     4)   0.582 us    |        }
+     4)   1.105 us    |      }
+     4)   0.088 us    |      sub_preempt_count();
+     4) ! 100.066 us  |    }
+     .
+     .
+     .
+     3)               |  sys_ioctl() {
+     3)   0.083 us    |    fget_light();
+     3)               |    security_file_ioctl() {
+     3)   0.066 us    |      cap_file_ioctl();
+     3)   0.562 us    |    }
+     3)               |    do_vfs_ioctl() {
+     3)               |      drm_ioctl() {
+     3)   0.075 us    |        drm_ut_debug_printk();
+     3)               |        i915_gem_pwrite_ioctl() {
+     3)               |          i915_mutex_lock_interruptible() {
+     3)   0.070 us    |            mutex_lock_interruptible();
+     3)   0.570 us    |          }
+     3)               |          drm_gem_object_lookup() {
+     3)               |            _raw_spin_lock() {
+     3)   0.080 us    |              add_preempt_count();
+     3)   0.620 us    |            }
+     3)               |            _raw_spin_unlock() {
+     3)   0.085 us    |              sub_preempt_count();
+     3)   0.562 us    |            }
+     3)   2.149 us    |          }
+     3)   0.133 us    |          i915_gem_object_pin();
+     3)               |          i915_gem_object_set_to_gtt_domain() {
+     3)   0.065 us    |            i915_gem_object_flush_gpu_write_domain();
+     3)   0.065 us    |            i915_gem_object_wait_rendering();
+     3)   0.062 us    |            i915_gem_object_flush_cpu_write_domain();
+     3)   1.612 us    |          }
+     3)               |          i915_gem_object_put_fence() {
+     3)   0.097 us    |            i915_gem_object_flush_fence.constprop.36();
+     3)   0.645 us    |          }
+     3)   0.070 us    |          add_preempt_count();
+     3)   0.070 us    |          sub_preempt_count();
+     3)   0.073 us    |          i915_gem_object_unpin();
+     3)   0.068 us    |          mutex_unlock();
+     3)   9.924 us    |        }
+     3) + 11.236 us   |      }
+     3) + 11.770 us   |    }
+     3) + 13.784 us   |  }
+     3)               |  sys_ioctl() {
+            </literallayout>
+            As you can see, the function_graph display is much easier to
+            follow. Also note that in addition to the function calls and
+            associated braces, other events such as scheduler events
+            are displayed in context. In fact, you can freely include
+            any tracepoint available in the trace events subsystem described
+            in the next section by simply enabling those events, and they'll
+            appear in context in the function graph display. Quite a
+            powerful tool for understanding kernel dynamics.
+        </para>
+
+        <para>
+            Also notice that there are various annotations on the left
+            hand side of the display. For example if the total time it
+            took for a given function to execute is above a certain
+            threshold, and exclamation point or plus sign appears on the
+            left hand side. Please see the ftrace documentation for
+            details on all these fields.
+        </para>
+    </section>
+
+    <section id='the-trace-events-subsystem'>
+        <title>The 'trace events' Subsystem</title>
+
+        <para>
+            One especially important directory contained within
+            the /sys/kernel/debug/tracing directory is the 'events'
+            subdirectory, which contains representations of every
+            tracepoint in the system. Listing out the contents of
+            the 'events' subdirectory, we see mainly another set of
+            subdirectories:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# cd events
+     root@sugarbay:/sys/kernel/debug/tracing/events# ls -al
+     drwxr-xr-x   38 root     root             0 Nov 14 23:19 .
+     drwxr-xr-x    5 root     root             0 Nov 14 23:19 ..
+     drwxr-xr-x   19 root     root             0 Nov 14 23:19 block
+     drwxr-xr-x   32 root     root             0 Nov 14 23:19 btrfs
+     drwxr-xr-x    5 root     root             0 Nov 14 23:19 drm
+     -rw-r--r--    1 root     root             0 Nov 14 23:19 enable
+     drwxr-xr-x   40 root     root             0 Nov 14 23:19 ext3
+     drwxr-xr-x   79 root     root             0 Nov 14 23:19 ext4
+     drwxr-xr-x   14 root     root             0 Nov 14 23:19 ftrace
+     drwxr-xr-x    8 root     root             0 Nov 14 23:19 hda
+     -r--r--r--    1 root     root             0 Nov 14 23:19 header_event
+     -r--r--r--    1 root     root             0 Nov 14 23:19 header_page
+     drwxr-xr-x   25 root     root             0 Nov 14 23:19 i915
+     drwxr-xr-x    7 root     root             0 Nov 14 23:19 irq
+     drwxr-xr-x   12 root     root             0 Nov 14 23:19 jbd
+     drwxr-xr-x   14 root     root             0 Nov 14 23:19 jbd2
+     drwxr-xr-x   14 root     root             0 Nov 14 23:19 kmem
+     drwxr-xr-x    7 root     root             0 Nov 14 23:19 module
+     drwxr-xr-x    3 root     root             0 Nov 14 23:19 napi
+     drwxr-xr-x    6 root     root             0 Nov 14 23:19 net
+     drwxr-xr-x    3 root     root             0 Nov 14 23:19 oom
+     drwxr-xr-x   12 root     root             0 Nov 14 23:19 power
+     drwxr-xr-x    3 root     root             0 Nov 14 23:19 printk
+     drwxr-xr-x    8 root     root             0 Nov 14 23:19 random
+     drwxr-xr-x    4 root     root             0 Nov 14 23:19 raw_syscalls
+     drwxr-xr-x    3 root     root             0 Nov 14 23:19 rcu
+     drwxr-xr-x    6 root     root             0 Nov 14 23:19 rpm
+     drwxr-xr-x   20 root     root             0 Nov 14 23:19 sched
+     drwxr-xr-x    7 root     root             0 Nov 14 23:19 scsi
+     drwxr-xr-x    4 root     root             0 Nov 14 23:19 signal
+     drwxr-xr-x    5 root     root             0 Nov 14 23:19 skb
+     drwxr-xr-x    4 root     root             0 Nov 14 23:19 sock
+     drwxr-xr-x   10 root     root             0 Nov 14 23:19 sunrpc
+     drwxr-xr-x  538 root     root             0 Nov 14 23:19 syscalls
+     drwxr-xr-x    4 root     root             0 Nov 14 23:19 task
+     drwxr-xr-x   14 root     root             0 Nov 14 23:19 timer
+     drwxr-xr-x    3 root     root             0 Nov 14 23:19 udp
+     drwxr-xr-x   21 root     root             0 Nov 14 23:19 vmscan
+     drwxr-xr-x    3 root     root             0 Nov 14 23:19 vsyscall
+     drwxr-xr-x    6 root     root             0 Nov 14 23:19 workqueue
+     drwxr-xr-x   26 root     root             0 Nov 14 23:19 writeback
+            </literallayout>
+            Each one of these subdirectories corresponds to a
+            'subsystem' and contains yet again more subdirectories,
+            each one of those finally corresponding to a tracepoint.
+            For example, here are the contents of the 'kmem' subsystem:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing/events# cd kmem
+     root@sugarbay:/sys/kernel/debug/tracing/events/kmem# ls -al
+     drwxr-xr-x   14 root     root             0 Nov 14 23:19 .
+     drwxr-xr-x   38 root     root             0 Nov 14 23:19 ..
+     -rw-r--r--    1 root     root             0 Nov 14 23:19 enable
+     -rw-r--r--    1 root     root             0 Nov 14 23:19 filter
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 kfree
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 kmalloc
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 kmalloc_node
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 kmem_cache_alloc
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 kmem_cache_alloc_node
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 kmem_cache_free
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 mm_page_alloc
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 mm_page_alloc_extfrag
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 mm_page_alloc_zone_locked
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 mm_page_free
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 mm_page_free_batched
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 mm_page_pcpu_drain
+            </literallayout>
+            Let's see what's inside the subdirectory for a specific
+            tracepoint, in this case the one for kmalloc:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing/events/kmem# cd kmalloc
+     root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# ls -al
+     drwxr-xr-x    2 root     root             0 Nov 14 23:19 .
+     drwxr-xr-x   14 root     root             0 Nov 14 23:19 ..
+     -rw-r--r--    1 root     root             0 Nov 14 23:19 enable
+     -rw-r--r--    1 root     root             0 Nov 14 23:19 filter
+     -r--r--r--    1 root     root             0 Nov 14 23:19 format
+     -r--r--r--    1 root     root             0 Nov 14 23:19 id
+            </literallayout>
+            The 'format' file for the tracepoint describes the event
+            in memory, which is used by the various tracing tools
+            that now make use of these tracepoint to parse the event
+            and make sense of it, along with a 'print fmt' field that
+            allows tools like ftrace to display the event as text.
+            Here's what the format of the kmalloc event looks like:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# cat format
+     name: kmalloc
+     ID: 313
+     format:
+             field:unsigned short common_type;  offset:0;       size:2; signed:0;
+             field:unsigned char common_flags;  offset:2;       size:1; signed:0;
+             field:unsigned char common_preempt_count;  offset:3;       size:1; signed:0;
+             field:int common_pid;      offset:4;       size:4; signed:1;
+             field:int common_padding;  offset:8;       size:4; signed:1;
+
+             field:unsigned long call_site;     offset:16;      size:8; signed:0;
+             field:const void * ptr;    offset:24;      size:8; signed:0;
+             field:size_t bytes_req;    offset:32;      size:8; signed:0;
+             field:size_t bytes_alloc;  offset:40;      size:8; signed:0;
+             field:gfp_t gfp_flags;     offset:48;      size:4; signed:0;
+
+     print fmt: "call_site=%lx ptr=%p bytes_req=%zu bytes_alloc=%zu gfp_flags=%s", REC->call_site, REC->ptr, REC->bytes_req, REC->bytes_alloc,
+     (REC->gfp_flags) ? __print_flags(REC->gfp_flags, "|", {(unsigned long)(((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | ((
+     gfp_t)0x20000u) | (( gfp_t)0x02u) | (( gfp_t)0x08u)) | (( gfp_t)0x4000u) | (( gfp_t)0x10000u) | (( gfp_t)0x1000u) | (( gfp_t)0x200u) | ((
+     gfp_t)0x400000u)), "GFP_TRANSHUGE"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | (( gfp_t)0x20000u) | ((
+     gfp_t)0x02u) | (( gfp_t)0x08u)), "GFP_HIGHUSER_MOVABLE"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | ((
+     gfp_t)0x20000u) | (( gfp_t)0x02u)), "GFP_HIGHUSER"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | ((
+     gfp_t)0x20000u)), "GFP_USER"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u) | (( gfp_t)0x80000u)), GFP_TEMPORARY"},
+     {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u) | (( gfp_t)0x80u)), "GFP_KERNEL"}, {(unsigned long)((( gfp_t)0x10u) | (( gfp_t)0x40u)),
+     "GFP_NOFS"}, {(unsigned long)((( gfp_t)0x20u)), "GFP_ATOMIC"}, {(unsigned long)((( gfp_t)0x10u)), "GFP_NOIO"}, {(unsigned long)((
+     gfp_t)0x20u), "GFP_HIGH"}, {(unsigned long)(( gfp_t)0x10u), "GFP_WAIT"}, {(unsigned long)(( gfp_t)0x40u), "GFP_IO"}, {(unsigned long)((
+     gfp_t)0x100u), "GFP_COLD"}, {(unsigned long)(( gfp_t)0x200u), "GFP_NOWARN"}, {(unsigned long)(( gfp_t)0x400u), "GFP_REPEAT"}, {(unsigned
+     long)(( gfp_t)0x800u), "GFP_NOFAIL"}, {(unsigned long)(( gfp_t)0x1000u), "GFP_NORETRY"},      {(unsigned long)(( gfp_t)0x4000u), "GFP_COMP"},
+     {(unsigned long)(( gfp_t)0x8000u), "GFP_ZERO"}, {(unsigned long)(( gfp_t)0x10000u), "GFP_NOMEMALLOC"}, {(unsigned long)(( gfp_t)0x20000u),
+     "GFP_HARDWALL"}, {(unsigned long)(( gfp_t)0x40000u), "GFP_THISNODE"}, {(unsigned long)(( gfp_t)0x80000u), "GFP_RECLAIMABLE"}, {(unsigned
+     long)(( gfp_t)0x08u), "GFP_MOVABLE"}, {(unsigned long)(( gfp_t)0), "GFP_NOTRACK"}, {(unsigned long)(( gfp_t)0x400000u), "GFP_NO_KSWAPD"},
+     {(unsigned long)(( gfp_t)0x800000u), "GFP_OTHER_NODE"} ) : "GFP_NOWAIT"
+            </literallayout>
+            The 'enable' file in the tracepoint directory is what allows
+            the user (or tools such as trace-cmd) to actually turn the
+            tracepoint on and off. When enabled, the corresponding
+            tracepoint will start appearing in the ftrace 'trace'
+            file described previously. For example, this turns on the
+            kmalloc tracepoint:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 1 > enable
+            </literallayout>
+            At the moment, we're not interested in the function tracer or
+            some other tracer that might be in effect, so we first turn
+            it off, but if we do that, we still need to turn tracing on in
+            order to see the events in the output buffer:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# echo nop > current_tracer
+     root@sugarbay:/sys/kernel/debug/tracing# echo 1 > tracing_on
+            </literallayout>
+            Now, if we look at the the 'trace' file, we see nothing
+            but the kmalloc events we just turned on:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing# cat trace | less
+     # tracer: nop
+     #
+     # entries-in-buffer/entries-written: 1897/1897   #P:8
+     #
+     #                              _-----=&gt; irqs-off
+     #                             / _----=&gt; need-resched
+     #                            | / _---=&gt; hardirq/softirq
+     #                            || / _--=&gt; preempt-depth
+     #                            ||| /     delay
+     #           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
+     #              | |       |   ||||       |         |
+            dropbear-1465  [000] ...1 18154.620753: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL
+              &lt;idle&gt;-0     [000] ..s3 18154.621640: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+              &lt;idle&gt;-0     [000] ..s3 18154.621656: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+     matchbox-termin-1361  [001] ...1 18154.755472: kmalloc: call_site=ffffffff81614050 ptr=ffff88006d5f0e00 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_KERNEL|GFP_REPEAT
+                Xorg-1264  [002] ...1 18154.755581: kmalloc: call_site=ffffffff8141abe8 ptr=ffff8800734f4cc0 bytes_req=168 bytes_alloc=192 gfp_flags=GFP_KERNEL|GFP_NOWARN|GFP_NORETRY
+                Xorg-1264  [002] ...1 18154.755583: kmalloc: call_site=ffffffff814192a3 ptr=ffff88001f822520 bytes_req=24 bytes_alloc=32 gfp_flags=GFP_KERNEL|GFP_ZERO
+                Xorg-1264  [002] ...1 18154.755589: kmalloc: call_site=ffffffff81419edb ptr=ffff8800721a2f00 bytes_req=64 bytes_alloc=64 gfp_flags=GFP_KERNEL|GFP_ZERO
+     matchbox-termin-1361  [001] ...1 18155.354594: kmalloc: call_site=ffffffff81614050 ptr=ffff88006db35400 bytes_req=576 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_REPEAT
+                Xorg-1264  [002] ...1 18155.354703: kmalloc: call_site=ffffffff8141abe8 ptr=ffff8800734f4cc0 bytes_req=168 bytes_alloc=192 gfp_flags=GFP_KERNEL|GFP_NOWARN|GFP_NORETRY
+                Xorg-1264  [002] ...1 18155.354705: kmalloc: call_site=ffffffff814192a3 ptr=ffff88001f822520 bytes_req=24 bytes_alloc=32 gfp_flags=GFP_KERNEL|GFP_ZERO
+                Xorg-1264  [002] ...1 18155.354711: kmalloc: call_site=ffffffff81419edb ptr=ffff8800721a2f00 bytes_req=64 bytes_alloc=64 gfp_flags=GFP_KERNEL|GFP_ZERO
+              &lt;idle&gt;-0     [000] ..s3 18155.673319: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+            dropbear-1465  [000] ...1 18155.673525: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL
+              &lt;idle&gt;-0     [000] ..s3 18155.674821: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+              &lt;idle&gt;-0     [000] ..s3 18155.793014: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+            dropbear-1465  [000] ...1 18155.793219: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL
+              &lt;idle&gt;-0     [000] ..s3 18155.794147: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+              &lt;idle&gt;-0     [000] ..s3 18155.936705: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+            dropbear-1465  [000] ...1 18155.936910: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL
+              &lt;idle&gt;-0     [000] ..s3 18155.937869: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+     matchbox-termin-1361  [001] ...1 18155.953667: kmalloc: call_site=ffffffff81614050 ptr=ffff88006d5f2000 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_KERNEL|GFP_REPEAT
+                Xorg-1264  [002] ...1 18155.953775: kmalloc: call_site=ffffffff8141abe8 ptr=ffff8800734f4cc0 bytes_req=168 bytes_alloc=192 gfp_flags=GFP_KERNEL|GFP_NOWARN|GFP_NORETRY
+                Xorg-1264  [002] ...1 18155.953777: kmalloc: call_site=ffffffff814192a3 ptr=ffff88001f822520 bytes_req=24 bytes_alloc=32 gfp_flags=GFP_KERNEL|GFP_ZERO
+                Xorg-1264  [002] ...1 18155.953783: kmalloc: call_site=ffffffff81419edb ptr=ffff8800721a2f00 bytes_req=64 bytes_alloc=64 gfp_flags=GFP_KERNEL|GFP_ZERO
+              &lt;idle&gt;-0     [000] ..s3 18156.176053: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+            dropbear-1465  [000] ...1 18156.176257: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL
+              &lt;idle&gt;-0     [000] ..s3 18156.177717: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+              &lt;idle&gt;-0     [000] ..s3 18156.399229: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d555800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+            dropbear-1465  [000] ...1 18156.399434: kmalloc: call_site=ffffffff816650d4 ptr=ffff8800729c3000 bytes_http://rostedt.homelinux.com/kernelshark/req=2048 bytes_alloc=2048 gfp_flags=GFP_KERNEL
+              &lt;idle&gt;-0     [000] ..s3 18156.400660: kmalloc: call_site=ffffffff81619b36 ptr=ffff88006d554800 bytes_req=512 bytes_alloc=512 gfp_flags=GFP_ATOMIC
+     matchbox-termin-1361  [001] ...1 18156.552800: kmalloc: call_site=ffffffff81614050 ptr=ffff88006db34800 bytes_req=576 bytes_alloc=1024 gfp_flags=GFP_KERNEL|GFP_REPEAT
+            </literallayout>
+            To again disable the kmalloc event, we need to send 0 to the
+            enable file:
+            <literallayout class='monospaced'>
+     root@sugarbay:/sys/kernel/debug/tracing/events/kmem/kmalloc# echo 0 > enable
+            </literallayout>
+            You can enable any number of events or complete subsystems
+            (by using the 'enable' file in the subsystem directory) and
+            get am arbitrarily fine-grained idea of what's going on in the
+            system by enabling as many of the appropriate tracepoints
+            as applicable.
+        </para>
+
+        <para>
+            A number of the tools described in this HOWTO do just that,
+            including trace-cmd and kernelshark in the next section.
+        </para>
+
+        <informalexample>
+            <emphasis>Tying it Together:</emphasis> These tracepoints and their representation
+            are used not only by ftrace,  but by many of the other tools
+            covered in this document and they form a central point of
+            integration for the various tracers available in Linux.
+            They form a central part of the instrumentation for the
+            following tools: perf, lttng, ftrace, blktrace and SystemTap
+        </informalexample>
+
+        <informalexample>
+            <emphasis>Tying it Together:</emphasis> Eventually all the special-purpose tracers
+            currently available in /sys/kernel/debug/tracing will be
+            removed and replaced with equivalent tracers based on the
+            'trace events' subsystem.
+        </informalexample>
+    </section>
+
+    <section id='trace-cmd-kernelshark'>
+        <title>trace-cmd/kernelshark</title>
+
+        <para>
+            trace-cmd is essentially an extensive command-line 'wrapper'
+            interface that hides the details of all the individual files
+            in /sys/kernel/debug/tracing, allowing users to specify
+            specific particular events within the
+            /sys/kernel/debug/tracing/events/ subdirectory and to collect
+            traces and avoiding having to deal with those details directly.
+        </para>
+
+        <para>
+            As yet another layer on top of that, kernelshark provides a GUI
+            that allows users to start and stop traces and specify sets
+            of events using an intuitive interface, and view the
+            output as both trace events and as a per-cpu graphical
+            display. It directly uses 'trace-cmd' as the plumbing
+            that accomplishes all that underneath the covers (and
+            actually displays the trace-cmd command it uses, as we'll see).
+        </para>
+
+        <para>
+            To start a trace using kernelshark, first start kernelshark:
+            <literallayout class='monospaced'>
+     root@sugarbay:~# kernelshark
+            </literallayout>
+            The bring up the 'Capture' dialog by choosing from the
+            kernelshark menu:
+            <literallayout class='monospaced'>
+     Capture | Record
+            </literallayout>
+            That will display the following dialog, which allows you to
+            choose on or more events (or even one or more complete
+            subsystems) to trace:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/kernelshark-choose-events.png" width="6in" depth="6in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            Note that these are exactly the same set of events described
+            in the previous trace events subsystem section, and in fact
+            is where trace-cmd gets them for kernelshark.
+        </para>
+
+        <para>
+            In the above screenshot, we've decided to explore the
+            graphics subsystem a bit and so have chosen to trace all
+            the tracepoints contained within the 'i915' and 'drm'
+            subsystems.
+        </para>
+
+        <para>
+            After doing that, we can start and stop the trace using
+            the 'Run' and 'Stop' button on the lower right corner of
+            the dialog (the same button will turn into the 'Stop'
+            button after the trace has started):
+        </para>
+
+        <para>
+            <imagedata fileref="figures/kernelshark-output-display.png" width="6in" depth="6in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            Notice that the right-hand pane shows the exact trace-cmd
+            command-line that's used to run the trace, along with the
+            results of the trace-cmd run.
+        </para>
+
+        <para>
+            Once the 'Stop' button is pressed, the graphical view magically
+            fills up with a colorful per-cpu display of the trace data,
+            along with the detailed event listing below that:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/kernelshark-i915-display.png" width="6in" depth="7in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            Here's another example, this time a display resulting
+            from tracing 'all events':
+        </para>
+
+        <para>
+            <imagedata fileref="figures/kernelshark-all.png" width="6in" depth="7in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            The tool is pretty self-explanatory, but for more detailed
+            information on navigating through the data, see the
+            <ulink url='http://rostedt.homelinux.com/kernelshark/'>kernelshark website</ulink>.
+        </para>
+    </section>
+
+    <section id='ftrace-documentation'>
+        <title>Documentation</title>
+
+        <para>
+            The documentation for ftrace can be found in the kernel
+            Documentation directory:
+            <literallayout class='monospaced'>
+     Documentation/trace/ftrace.txt
+            </literallayout>
+            The documentation for the trace event subsystem can also
+            be found in the kernel Documentation directory:
+            <literallayout class='monospaced'>
+     Documentation/trace/events.txt
+            </literallayout>
+            There are a nice series of articles on using
+            ftrace and trace-cmd at LWN:
+            <itemizedlist>
+                <listitem><para><ulink url='http://lwn.net/Articles/365835/'>Debugging the kernel using Ftrace - part 1</ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='http://lwn.net/Articles/366796/'>Debugging the kernel using Ftrace - part 2</ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='https://lwn.net/Articles/410200/'>trace-cmd: A front-end for Ftrace</ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            There's more detailed documentation kernelshark usage here:
+            <ulink url='http://rostedt.homelinux.com/kernelshark/'>KernelShark</ulink>
+        </para>
+
+        <para>
+            An amusing yet useful README (a tracing mini-HOWTO) can be
+            found in /sys/kernel/debug/tracing/README.
+        </para>
+    </section>
+</section>
+
+<section id='profile-manual-systemtap'>
+    <title>systemtap</title>
+
+    <para>
+        SystemTap is a system-wide script-based tracing and profiling tool.
+    </para>
+
+    <para>
+        SystemTap scripts are C-like programs that are executed in the
+        kernel to gather/print/aggregate data extracted from the context
+        they end up being invoked under.
+    </para>
+
+    <para>
+        For example, this probe from the
+        <ulink url='http://sourceware.org/systemtap/tutorial/'>SystemTap tutorial</ulink>
+        simply prints a line every time any process on the system open()s
+        a file. For each line, it prints the executable name of the
+        program that opened the file, along with its pid, and the name
+        of the file it opened (or tried to open), which it extracts
+        from the open syscall's argstr.
+        <literallayout class='monospaced'>
+     probe syscall.open
+     {
+             printf ("%s(%d) open (%s)\n", execname(), pid(), argstr)
+     }
+
+     probe timer.ms(4000) # after 4 seconds
+     {
+             exit ()
+     }
+        </literallayout>
+        Normally, to execute this probe, you'd simply install
+        systemtap on the system you want to probe, and directly run
+        the probe on that system e.g. assuming the name of the file
+        containing the above text is trace_open.stp:
+        <literallayout class='monospaced'>
+     # stap trace_open.stp
+        </literallayout>
+        What systemtap does under the covers to run this probe is 1)
+        parse and convert the probe to an equivalent 'C' form, 2)
+        compile the 'C' form into a kernel module, 3) insert the
+        module into the kernel, which arms it, and 4) collect the data
+        generated by the probe and display it to the user.
+     </para>
+
+     <para>
+        In order to accomplish steps 1 and 2, the 'stap' program needs
+        access to the kernel build system that produced the kernel
+        that the probed system is running. In the case of a typical
+        embedded system (the 'target'), the kernel build system
+        unfortunately isn't typically part of the image running on
+        the target. It is normally available on the 'host' system
+        that produced the target image however; in such cases,
+        steps 1 and 2 are executed on the host system, and steps
+        3 and 4 are executed on the target system, using only the
+        systemtap 'runtime'.
+    </para>
+
+    <para>
+        The systemtap support in Yocto assumes that only steps
+        3 and 4 are run on the target; it is possible to do
+        everything on the target, but this section assumes only
+        the typical embedded use-case.
+    </para>
+
+    <para>
+        So basically what you need to do in order to run a systemtap
+        script on the target is to 1) on the host system, compile the
+        probe into a kernel module that makes sense to the target, 2)
+        copy the module onto the target system and 3) insert the
+        module into the target kernel, which arms it, and 4) collect
+        the data generated by the probe and display it to the user.
+    </para>
+
+    <section id='systemtap-setup'>
+        <title>Setup</title>
+
+        <para>
+            Those are a lot of steps and a lot of details, but
+            fortunately Yocto includes a script called 'crosstap'
+            that will take care of those details, allowing you to
+            simply execute a systemtap script on the remote target,
+            with arguments if necessary.
+        </para>
+
+        <para>
+            In order to do this from a remote host, however, you
+            need to have access to the build for the image you
+            booted. The 'crosstap' script provides details on how
+            to do this if you run the script on the host without having
+            done a build:
+            <note>
+                SystemTap, which uses 'crosstap', assumes you can establish an
+                ssh connection to the remote target.
+                Please refer to crosstap wiki page for details on verifying
+                ssh connections at
+                <ulink url='https://wiki.yoctoproject.org/wiki/Tracing_and_Profiling#systemtap'></ulink>.
+                Also, the ability to ssh into the target system is not enabled
+                by default in -minimal images.
+            </note>
+            <literallayout class='monospaced'>
+     $ crosstap root@192.168.1.88 trace_open.stp
+
+     Error: No target kernel build found.
+     Did you forget to create a local build of your image?
+
+     'crosstap' requires a local sdk build of the target system
+     (or a build that includes 'tools-profile') in order to build
+     kernel modules that can probe the target system.
+
+     Practically speaking, that means you need to do the following:
+      - If you're running a pre-built image, download the release
+        and/or BSP tarballs used to build the image.
+      - If you're working from git sources, just clone the metadata
+        and BSP layers needed to build the image you'll be booting.
+      - Make sure you're properly set up to build a new image (see
+        the BSP README and/or the widely available basic documentation
+        that discusses how to build images).
+      - Build an -sdk version of the image e.g.:
+          $ bitbake core-image-sato-sdk
+      OR
+      - Build a non-sdk image but include the profiling tools:
+          [ edit local.conf and add 'tools-profile' to the end of
+            the EXTRA_IMAGE_FEATURES variable ]
+          $ bitbake core-image-sato
+
+     Once you've build the image on the host system, you're ready to
+     boot it (or the equivalent pre-built image) and use 'crosstap'
+     to probe it (you need to source the environment as usual first):
+
+        $ source oe-init-build-env
+        $ cd ~/my/systemtap/scripts
+        $ crosstap root@192.168.1.xxx myscript.stp
+            </literallayout>
+            So essentially what you need to do is build an SDK image or
+            image with 'tools-profile' as detailed in the
+            "<link linkend='profile-manual-general-setup'>General Setup</link>"
+            section of this manual, and boot the resulting target image.
+        </para>
+
+        <note>
+            If you have a build directory containing multiple machines,
+            you need to have the MACHINE you're connecting to selected
+            in local.conf, and the kernel in that machine's build
+            directory must match the kernel on the booted system exactly,
+            or you'll get the above 'crosstap' message when you try to
+            invoke a script.
+        </note>
+    </section>
+
+    <section id='running-a-script-on-a-target'>
+        <title>Running a Script on a Target</title>
+
+        <para>
+            Once you've done that, you should be able to run a systemtap
+            script on the target:
+            <literallayout class='monospaced'>
+     $ cd /path/to/yocto
+     $ source oe-init-build-env
+
+     ### Shell environment set up for builds. ###
+
+     You can now run 'bitbake &lt;target&gt;'
+
+     Common targets are:
+        core-image-minimal
+        core-image-sato
+        meta-toolchain
+        meta-toolchain-sdk
+        adt-installer
+        meta-ide-support
+
+     You can also run generated qemu images with a command like 'runqemu qemux86'
+            </literallayout>
+            Once you've done that, you can cd to whatever directory
+            contains your scripts and use 'crosstap' to run the script:
+            <literallayout class='monospaced'>
+     $ cd /path/to/my/systemap/script
+     $ crosstap root@192.168.7.2 trace_open.stp
+            </literallayout>
+            If you get an error connecting to the target e.g.:
+            <literallayout class='monospaced'>
+     $ crosstap root@192.168.7.2 trace_open.stp
+     error establishing ssh connection on remote 'root@192.168.7.2'
+            </literallayout>
+            Try ssh'ing to the target and see what happens:
+            <literallayout class='monospaced'>
+     $ ssh root@192.168.7.2
+            </literallayout>
+            A lot of the time, connection problems are due specifying a
+            wrong IP address or having a 'host key verification error'.
+        </para>
+
+        <para>
+            If everything worked as planned, you should see something
+            like this (enter the password when prompted, or press enter
+            if its set up to use no password):
+            <literallayout class='monospaced'>
+     $ crosstap root@192.168.7.2 trace_open.stp
+     root@192.168.7.2's password:
+     matchbox-termin(1036) open ("/tmp/vte3FS2LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600)
+     matchbox-termin(1036) open ("/tmp/vteJMC7LW", O_RDWR|O_CREAT|O_EXCL|O_LARGEFILE, 0600)
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='systemtap-documentation'>
+        <title>Documentation</title>
+
+        <para>
+            The SystemTap language reference can be found here:
+            <ulink url='http://sourceware.org/systemtap/langref/'>SystemTap Language Reference</ulink>
+        </para>
+
+        <para>
+            Links to other SystemTap documents, tutorials, and examples can be
+            found here:
+            <ulink url='http://sourceware.org/systemtap/documentation.html'>SystemTap documentation page</ulink>
+        </para>
+    </section>
+</section>
+
+<section id='profile-manual-oprofile'>
+    <title>oprofile</title>
+
+    <para>
+        oprofile itself is a command-line application that runs on the
+        target system.
+    </para>
+
+    <section id='oprofile-setup'>
+        <title>Setup</title>
+
+        <para>
+            For this section, we'll assume you've already performed the
+            basic setup outlined in the
+            "<link linkend='profile-manual-general-setup'>General Setup</link>"
+            section.
+        </para>
+
+        <para>
+            For the the section that deals with oprofile from the command-line,
+            we assume you've ssh'ed to the host and will be running
+            oprofile on the target.
+        </para>
+
+        <para>
+            oprofileui (oprofile-viewer) is a GUI-based program that runs
+            on the host and interacts remotely with the target.
+            See the oprofileui section for the exact steps needed to
+            install oprofileui on the host.
+        </para>
+    </section>
+
+    <section id='oprofile-basic-usage'>
+        <title>Basic Usage</title>
+
+        <para>
+            Oprofile as configured in Yocto is a system-wide profiler
+            (i.e. the version in Yocto doesn't yet make use of the
+            perf_events interface which would allow it to profile
+            specific processes and workloads). It's relies on hardware
+            counter support in the hardware (but can fall back to a
+            timer-based mode), which means that it doesn't take
+            advantage of tracepoints or other event sources for example.
+        </para>
+
+        <para>
+            It consists of a kernel module that collects samples and a
+            userspace daemon that writes the sample data to disk.
+        </para>
+
+        <para>
+            The 'opcontrol' shell script is used for transparently
+            managing these components and starting and stopping
+            profiles, and the 'opreport' command is used to
+            display the results.
+        </para>
+
+        <para>
+            The oprofile daemon should already be running, but before
+            you start profiling, you may need to change some settings
+            and some of these settings may require the daemon not
+            be running. One of these settings is the path the the
+            vmlinux file, which you'll want to set using the --vmlinux
+            option if you want the kernel profiled:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --vmlinux=/boot/vmlinux-`uname -r`
+     The profiling daemon is currently active, so changes to the configuration
+     will be used the next time you restart oprofile after a --shutdown or --deinit.
+            </literallayout>
+            You can check if vmlinux file: is set using opcontrol --status:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --status
+     Daemon paused: pid 1334
+     Separate options: library
+     vmlinux file: none
+     Image filter: none
+     Call-graph depth: 6
+            </literallayout>
+            If it's not, you need to shutdown the daemon, add the setting
+            and restart the daemon:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --shutdown
+     Killing daemon.
+
+     root@crownbay:~# opcontrol --vmlinux=/boot/vmlinux-`uname -r`
+     root@crownbay:~# opcontrol --start-daemon
+     Using default event: CPU_CLK_UNHALTED:100000:0:1:1
+     Using 2.6+ OProfile kernel interface.
+     Reading module info.
+     Using log file /var/lib/oprofile/samples/oprofiled.log
+     Daemon started.
+            </literallayout>
+            If we get the status again we now see our updated settings:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --status
+     Daemon paused: pid 1649
+     Separate options: library
+     vmlinux file: /boot/vmlinux-3.4.11-yocto-standard
+     Image filter: none
+     Call-graph depth: 6
+            </literallayout>
+            We're now in a position to run a profile. For that we used
+            'opcontrol --start':
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --start
+     Profiler running.
+            </literallayout>
+            In another window, run our wget workload:
+            <literallayout class='monospaced'>
+     root@crownbay:~# rm linux-2.6.19.2.tar.bz2; wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>; sync
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |*******************************| 41727k  0:00:00 ETA
+            </literallayout>
+            To stop the profile we use 'opcontrol --shudown', which not
+            only stops the profile but shuts down the daemon as well:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --start
+     Stopping profiling.
+     Killing daemon.
+            </literallayout>
+            Oprofile writes sample data to /var/lib/oprofile/samples,
+            which you can look at if you're interested in seeing how the
+            samples are structured. This is also interesting because
+            it's related to how you dive down to get further details
+            about specific executables in OProfile.
+        </para>
+
+        <para>
+            To see the default display output for a profile, simply type
+            'opreport', which will show the results using the data in
+            /var/lib/oprofile/samples:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opreport
+
+     WARNING! The OProfile kernel driver reports sample buffer overflows.
+     Such overflows can result in incorrect sample attribution, invalid sample
+     files and other symptoms.  See the oprofiled.log for details.
+     You should adjust your sampling frequency to eliminate (or at least minimize)
+     these overflows.
+     CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated)
+     Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000
+     CPU_CLK_UNHALT...|
+      samples|      %|
+     ------------------
+       464365 79.8156 vmlinux-3.4.11-yocto-standard
+        65108 11.1908 oprofiled
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                 64416 98.9372 oprofiled
+                   692  1.0628 libc-2.16.so
+        36959  6.3526 no-vmlinux
+         4378  0.7525 busybox
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                  2844 64.9612 libc-2.16.so
+                  1337 30.5391 busybox
+                   193  4.4084 ld-2.16.so
+                     2  0.0457 libnss_compat-2.16.so
+                     1  0.0228 libnsl-2.16.so
+                     1  0.0228 libnss_files-2.16.so
+         4344  0.7467 bash
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                  2657 61.1648 bash
+                  1665 38.3287 libc-2.16.so
+                    18  0.4144 ld-2.16.so
+                     3  0.0691 libtinfo.so.5.9
+                     1  0.0230 libdl-2.16.so
+         3118  0.5359 nf_conntrack
+          686  0.1179 matchbox-terminal
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                   214 31.1953 libglib-2.0.so.0.3200.4
+                   114 16.6181 libc-2.16.so
+                    79 11.5160 libcairo.so.2.11200.2
+                    78 11.3703 libgdk-x11-2.0.so.0.2400.8
+                    51  7.4344 libpthread-2.16.so
+                    45  6.5598 libgobject-2.0.so.0.3200.4
+                    29  4.2274 libvte.so.9.2800.2
+                    25  3.6443 libX11.so.6.3.0
+                    19  2.7697 libxcb.so.1.1.0
+                    17  2.4781 libgtk-x11-2.0.so.0.2400.8
+                    12  1.7493 librt-2.16.so
+                     3  0.4373 libXrender.so.1.3.0
+          671  0.1153 emgd
+          411  0.0706 nf_conntrack_ipv4
+          391  0.0672 iptable_nat
+          378  0.0650 nf_nat
+          263  0.0452 Xorg
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                   106 40.3042 Xorg
+                    53 20.1521 libc-2.16.so
+                    31 11.7871 libpixman-1.so.0.27.2
+                    26  9.8859 emgd_drv.so
+                    16  6.0837 libemgdsrv_um.so.1.5.15.3226
+                    11  4.1825 libEMGD2d.so.1.5.15.3226
+                     9  3.4221 libfb.so
+                     7  2.6616 libpthread-2.16.so
+                     1  0.3802 libudev.so.0.9.3
+                     1  0.3802 libdrm.so.2.4.0
+                     1  0.3802 libextmod.so
+                     1  0.3802 mouse_drv.so
+     .
+     .
+     .
+           9  0.0015 connmand
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                     4 44.4444 libglib-2.0.so.0.3200.4
+                     2 22.2222 libpthread-2.16.so
+                     1 11.1111 connmand
+                     1 11.1111 libc-2.16.so
+                     1 11.1111 librt-2.16.so
+            6  0.0010 oprofile-server
+         CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                     3 50.0000 libc-2.16.so
+                     1 16.6667 oprofile-server
+                     1 16.6667 libpthread-2.16.so
+                     1 16.6667 libglib-2.0.so.0.3200.4
+           5 8.6e-04 gconfd-2
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                     2 40.0000 libdbus-1.so.3.7.2
+                     2 40.0000 libglib-2.0.so.0.3200.4
+                     1 20.0000 libc-2.16.so
+            </literallayout>
+            The output above shows the breakdown or samples by both
+            number of samples and percentage for each executable.
+            Within an executable, the sample counts are broken down
+            further into executable and shared libraries (DSOs) used
+            by the executable.
+        </para>
+
+        <para>
+            To get even more detailed breakdowns by function, we need to
+            have the full paths to the DSOs, which we can get by
+            using -f with opreport:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opreport -f
+
+     CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated)
+     Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000
+     CPU_CLK_UNHALT...|
+      samples|      %|
+
+       464365 79.8156 /boot/vmlinux-3.4.11-yocto-standard
+       65108 11.1908 /usr/bin/oprofiled
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                 64416 98.9372 /usr/bin/oprofiled
+                   692  1.0628 /lib/libc-2.16.so
+        36959  6.3526 /no-vmlinux
+         4378  0.7525 /bin/busybox
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                  2844 64.9612 /lib/libc-2.16.so
+                  1337 30.5391 /bin/busybox
+                   193  4.4084 /lib/ld-2.16.so
+                     2  0.0457 /lib/libnss_compat-2.16.so
+                     1  0.0228 /lib/libnsl-2.16.so
+                     1  0.0228 /lib/libnss_files-2.16.so
+         4344  0.7467 /bin/bash
+             CPU_CLK_UNHALT...|
+               samples|      %|
+             ------------------
+                  2657 61.1648 /bin/bash
+                  1665 38.3287 /lib/libc-2.16.so
+                    18  0.4144 /lib/ld-2.16.so
+                     3  0.0691 /lib/libtinfo.so.5.9
+                     1  0.0230 /lib/libdl-2.16.so
+     .
+     .
+     .
+            </literallayout>
+            Using the paths shown in the above output and the -l option to
+            opreport, we can see all the functions that have hits in the
+            profile and their sample counts and percentages. Here's a
+            portion of what we get for the kernel:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opreport -l /boot/vmlinux-3.4.11-yocto-standard
+
+     CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated)
+     Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000
+     samples  %        symbol name
+     233981   50.3873  intel_idle
+     15437     3.3243  rb_get_reader_page
+     14503     3.1232  ring_buffer_consume
+     14092     3.0347  mutex_spin_on_owner
+     13024     2.8047  read_hpet
+     8039      1.7312  sub_preempt_count
+     7096      1.5281  ioread32
+     6997      1.5068  add_preempt_count
+     3985      0.8582  rb_advance_reader
+     3488      0.7511  add_event_entry
+     3303      0.7113  get_parent_ip
+     3104      0.6684  rb_buffer_peek
+     2960      0.6374  op_cpu_buffer_read_entry
+     2614      0.5629  sync_buffer
+     2545      0.5481  debug_smp_processor_id
+     2456      0.5289  ohci_irq
+     2397      0.5162  memset
+     2349      0.5059  __copy_to_user_ll
+     2185      0.4705  ring_buffer_event_length
+     1918      0.4130  in_lock_functions
+     1850      0.3984  __schedule
+     1767      0.3805  __copy_from_user_ll_nozero
+     1575      0.3392  rb_event_data_length
+     1256      0.2705  memcpy
+     1233      0.2655  system_call
+     1213      0.2612  menu_select
+            </literallayout>
+            Notice that above we see an entry for the __copy_to_user_ll()
+            function that we've looked at with other profilers as well.
+        </para>
+
+        <para>
+            Here's what we get when we do the same thing for the
+            busybox executable:
+            <literallayout class='monospaced'>
+     CPU: Intel Architectural Perfmon, speed 1.3e+06 MHz (estimated)
+     Counted CPU_CLK_UNHALTED events (Clock cycles when not halted) with a unit mask of 0x00 (No unit mask) count 100000
+     samples  %        image name               symbol name
+     349       8.4198  busybox                  retrieve_file_data
+     308       7.4306  libc-2.16.so             _IO_file_xsgetn
+     283       6.8275  libc-2.16.so             __read_nocancel
+     235       5.6695  libc-2.16.so             syscall
+     233       5.6212  libc-2.16.so             clearerr
+     215       5.1870  libc-2.16.so             fread
+     181       4.3667  libc-2.16.so             __write_nocancel
+     158       3.8118  libc-2.16.so             __underflow
+     151       3.6429  libc-2.16.so             _dl_addr
+     150       3.6188  busybox                  progress_meter
+     150       3.6188  libc-2.16.so             __poll_nocancel
+     148       3.5706  libc-2.16.so             _IO_file_underflow@@GLIBC_2.1
+     137       3.3052  busybox                  safe_poll
+     125       3.0157  busybox                  bb_progress_update
+     122       2.9433  libc-2.16.so             __x86.get_pc_thunk.bx
+     95        2.2919  busybox                  full_write
+     81        1.9542  busybox                  safe_write
+     77        1.8577  busybox                  xwrite
+     72        1.7370  libc-2.16.so             _IO_file_read
+     71        1.7129  libc-2.16.so             _IO_sgetn
+     67        1.6164  libc-2.16.so             poll
+     52        1.2545  libc-2.16.so             _IO_switch_to_get_mode
+     45        1.0856  libc-2.16.so             read
+     34        0.8203  libc-2.16.so             write
+     32        0.7720  busybox                  monotonic_sec
+     25        0.6031  libc-2.16.so             vfprintf
+     22        0.5308  busybox                  get_mono
+     14        0.3378  ld-2.16.so               strcmp
+     14        0.3378  libc-2.16.so             __x86.get_pc_thunk.cx
+     .
+     .
+     .
+            </literallayout>
+            Since we recorded the profile with a callchain depth of 6, we
+            should be able to see our __copy_to_user_ll() callchains in
+            the output, and indeed we can if we search around a bit in
+            the 'opreport --callgraph' output:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opreport --callgraph /boot/vmlinux-3.4.11-yocto-standard
+
+       392       6.9639  vmlinux-3.4.11-yocto-standard sock_aio_read
+       736      13.0751  vmlinux-3.4.11-yocto-standard __generic_file_aio_write
+       3255     57.8255  vmlinux-3.4.11-yocto-standard inet_recvmsg
+     785       0.1690  vmlinux-3.4.11-yocto-standard tcp_recvmsg
+       1790     31.7940  vmlinux-3.4.11-yocto-standard local_bh_enable
+       1238     21.9893  vmlinux-3.4.11-yocto-standard __kfree_skb
+       992      17.6199  vmlinux-3.4.11-yocto-standard lock_sock_nested
+       785      13.9432  vmlinux-3.4.11-yocto-standard tcp_recvmsg [self]
+       525       9.3250  vmlinux-3.4.11-yocto-standard release_sock
+       112       1.9893  vmlinux-3.4.11-yocto-standard tcp_cleanup_rbuf
+       72        1.2789  vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec
+
+     170       0.0366  vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec
+       1491     73.3038  vmlinux-3.4.11-yocto-standard memcpy_toiovec
+       327      16.0767  vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec
+       170       8.3579  vmlinux-3.4.11-yocto-standard skb_copy_datagram_iovec [self]
+       20        0.9833  vmlinux-3.4.11-yocto-standard copy_to_user
+
+       2588     98.2909  vmlinux-3.4.11-yocto-standard copy_to_user
+     2349      0.5059  vmlinux-3.4.11-yocto-standard __copy_to_user_ll
+       2349     89.2138  vmlinux-3.4.11-yocto-standard __copy_to_user_ll [self]
+       166       6.3046  vmlinux-3.4.11-yocto-standard do_page_fault
+            </literallayout>
+            Remember that by default OProfile sessions are cumulative
+            i.e. if you start and stop a profiling session, then start a
+            new one, the new one will not erase the previous run(s) but
+            will build on it. If you want to restart a profile from scratch,
+            you need to reset:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --reset
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='oprofileui-a-gui-for-oprofile'>
+        <title>OProfileUI - A GUI for OProfile</title>
+
+        <para>
+            Yocto also supports a graphical UI for controlling and viewing
+            OProfile traces, called OProfileUI. To use it, you first need
+            to clone the oprofileui git repo, then configure, build, and
+            install it:
+            <literallayout class='monospaced'>
+     [trz@empanada tmp]$ git clone git://git.yoctoproject.org/oprofileui
+     [trz@empanada tmp]$ cd oprofileui
+     [trz@empanada oprofileui]$ ./autogen.sh
+     [trz@empanada oprofileui]$ sudo make install
+            </literallayout>
+            OprofileUI replaces the 'opreport' functionality with a GUI,
+            and normally doesn't require the user to use 'opcontrol' either.
+            If you want to profile the kernel, however, you need to either
+            use the UI to specify a vmlinux or use 'opcontrol' to specify
+            it on the target:
+        </para>
+
+        <para>
+            First, on the target, check if vmlinux file: is set:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --status
+            </literallayout>
+            If not:
+            <literallayout class='monospaced'>
+     root@crownbay:~# opcontrol --shutdown
+     root@crownbay:~# opcontrol --vmlinux=/boot/vmlinux-`uname -r`
+     root@crownbay:~# opcontrol --start-daemon
+            </literallayout>
+            Now, start the oprofile UI on the host system:
+            <literallayout class='monospaced'>
+     [trz@empanada oprofileui]$ oprofile-viewer
+            </literallayout>
+            To run a profile on the remote system, first connect to the
+            remote system by pressing the 'Connect' button and supplying
+            the IP address and port of the remote system (the default
+            port is 4224).
+        </para>
+
+        <para>
+            The oprofile server should automatically be started already.
+            If not, the connection will fail and you either typed in the
+            wrong IP address and port (see below), or you need to start
+            the server yourself:
+            <literallayout class='monospaced'>
+     root@crownbay:~# oprofile-server
+            </literallayout>
+            Or, to specify a specific port:
+            <literallayout class='monospaced'>
+     root@crownbay:~# oprofile-server --port 8888
+            </literallayout>
+            Once connected, press the 'Start' button and then run the
+            wget workload on the remote system:
+            <literallayout class='monospaced'>
+     root@crownbay:~# rm linux-2.6.19.2.tar.bz2; wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>; sync
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |*******************************| 41727k  0:00:00 ETA
+            </literallayout>
+            Once the workload completes, press the 'Stop' button. At that
+            point the OProfile viewer will download the profile files it's
+            collected (this may take some time, especially if the kernel
+            was profiled). While it downloads the files, you should see
+            something like the following:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/oprofileui-downloading.png" width="6in" depth="7in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            Once the profile files have been retrieved, you should see a
+            list of the processes that were profiled:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/oprofileui-processes.png" width="6in" depth="7in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            If you select one of them, you should see all the symbols that
+            were hit during the profile. Selecting one of them will show a
+            list of callers and callees of the chosen function in two
+            panes below the top pane. For example, here's what we see
+            when we select __copy_to_user_ll():
+        </para>
+
+        <para>
+            <imagedata fileref="figures/oprofileui-copy-to-user.png" width="6in" depth="7in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            As another example, we can look at the busybox process and see
+            that the progress meter made a system call:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/oprofileui-busybox.png" width="6in" depth="7in" align="center" scalefit="1" />
+        </para>
+    </section>
+
+    <section id='oprofile-documentation'>
+        <title>Documentation</title>
+
+        <para>
+            Yocto already has some information on setting up and using
+            OProfile and oprofileui. As this document doesn't cover
+            everything in detail, it may be worth taking a look at the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-oprofile'>Profiling with OProfile</ulink>"
+            section in the Yocto Project Development Manual
+        </para>
+
+        <para>
+            The OProfile manual can be found here:
+            <ulink url='http://oprofile.sourceforge.net/doc/index.html'>OProfile manual</ulink>
+        </para>
+
+        <para>
+            The OProfile website contains links to the above manual and
+            bunch of other items including an extensive set of examples:
+            <ulink url='http://oprofile.sourceforge.net/about/'>About OProfile</ulink>
+        </para>
+    </section>
+</section>
+
+<section id='profile-manual-sysprof'>
+    <title>Sysprof</title>
+
+    <para>
+        Sysprof is a very easy to use system-wide profiler that consists
+        of a single window with three panes and a few buttons which allow
+        you to start, stop, and view the profile from one place.
+    </para>
+
+    <section id='sysprof-setup'>
+        <title>Setup</title>
+
+        <para>
+            For this section, we'll assume you've already performed the
+            basic setup outlined in the General Setup section.
+        </para>
+
+        <para>
+            Sysprof is a GUI-based application that runs on the target
+            system. For the rest of this document we assume you've
+            ssh'ed to the host and will be running Sysprof on the
+            target (you can use the '-X' option to ssh and have the
+            Sysprof GUI run on the target but display remotely on the
+            host if you want).
+        </para>
+    </section>
+
+    <section id='sysprof-basic-usage'>
+        <title>Basic Usage</title>
+
+        <para>
+            To start profiling the system, you simply press the 'Start'
+            button. To stop profiling and to start viewing the profile data
+            in one easy step, press the 'Profile' button.
+        </para>
+
+        <para>
+            Once you've pressed the profile button, the three panes will
+            fill up with profiling data:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/sysprof-copy-to-user.png" width="6in" depth="4in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            The left pane shows a list of functions and processes.
+            Selecting one of those expands that function in the right
+            pane, showing all its callees. Note that this caller-oriented
+            display is essentially the inverse of perf's default
+            callee-oriented callchain display.
+        </para>
+
+        <para>
+            In the screenshot above, we're focusing on __copy_to_user_ll()
+            and looking up the callchain we can see that one of the callers
+            of __copy_to_user_ll is sys_read() and the complete callpath
+            between them. Notice that this is essentially a portion of the
+            same information we saw in the perf display shown in the perf
+            section of this page.
+        </para>
+
+        <para>
+            <imagedata fileref="figures/sysprof-copy-from-user.png" width="6in" depth="4in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            Similarly, the above is a snapshot of the Sysprof display of a
+            copy-from-user callchain.
+        </para>
+
+        <para>
+            Finally, looking at the third Sysprof pane in the lower left,
+            we can see a list of all the callers of a particular function
+            selected in the top left pane. In this case, the lower pane is
+            showing all the callers of __mark_inode_dirty:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/sysprof-callers.png" width="6in" depth="4in" align="center" scalefit="1" />
+        </para>
+
+        <para>
+            Double-clicking on one of those functions will in turn change the
+            focus to the selected function, and so on.
+        </para>
+
+        <informalexample>
+            <emphasis>Tying it Together:</emphasis> If you like sysprof's 'caller-oriented'
+            display, you may be able to approximate it in other tools as
+            well.  For example, 'perf report' has the -g (--call-graph)
+            option that you can experiment with; one of the options is
+            'caller' for an inverted caller-based callgraph display.
+        </informalexample>
+    </section>
+
+    <section id='sysprof-documentation'>
+        <title>Documentation</title>
+
+        <para>
+            There doesn't seem to be any documentation for Sysprof, but
+            maybe that's because it's pretty self-explanatory.
+            The Sysprof website, however, is here:
+            <ulink url='http://sysprof.com/'>Sysprof, System-wide Performance Profiler for Linux</ulink>
+        </para>
+    </section>
+</section>
+
+<section id='lttng-linux-trace-toolkit-next-generation'>
+    <title>LTTng (Linux Trace Toolkit, next generation)</title>
+
+    <section id='lttng-setup'>
+        <title>Setup</title>
+
+        <para>
+            For this section, we'll assume you've already performed the
+            basic setup outlined in the General Setup section.
+        </para>
+
+        <para>
+            LTTng is run on the target system by ssh'ing to it.
+            However, if you want to see the traces graphically,
+            install Eclipse as described in section
+            "<link linkend='manually-copying-a-trace-to-the-host-and-viewing-it-in-eclipse'>Manually copying a trace to the host and viewing it in Eclipse (i.e. using Eclipse without network support)</link>"
+            and follow the directions to manually copy traces to the host and
+            view them in Eclipse (i.e. using Eclipse without network support).
+        </para>
+
+        <note>
+            Be sure to download and install/run the 'SR1' or later Juno release
+            of eclipse e.g.:
+            <ulink url='http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR1/eclipse-cpp-juno-SR1-linux-gtk-x86_64.tar.gz'>http://www.eclipse.org/downloads/download.php?file=/technology/epp/downloads/release/juno/SR1/eclipse-cpp-juno-SR1-linux-gtk-x86_64.tar.gz</ulink>
+        </note>
+    </section>
+
+    <section id='collecting-and-viewing-traces'>
+        <title>Collecting and Viewing Traces</title>
+
+        <para>
+            Once you've applied the above commits and built and booted your
+            image (you need to build the core-image-sato-sdk image or the
+            other methods described in the General Setup section), you're
+            ready to start tracing.
+        </para>
+
+        <section id='collecting-and-viewing-a-trace-on-the-target-inside-a-shell'>
+            <title>Collecting and viewing a trace on the target (inside a shell)</title>
+
+            <para>
+                First, from the target, ssh to the target:
+                <literallayout class='monospaced'>
+     $ ssh -l root 192.168.1.47
+     The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established.
+     RSA key fingerprint is 23:bd:c8:b1:a8:71:52:00:ee:00:4f:64:9e:10:b9:7e.
+     Are you sure you want to continue connecting (yes/no)? yes
+     Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts.
+     root@192.168.1.47's password:
+                </literallayout>
+                Once on the target, use these steps to create a trace:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng create
+     Spawning a session daemon
+     Session auto-20121015-232120 created.
+     Traces will be written in /home/root/lttng-traces/auto-20121015-232120
+                </literallayout>
+                Enable the events you want to trace (in this case all
+                kernel events):
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng enable-event --kernel --all
+     All kernel events are enabled in channel channel0
+                </literallayout>
+                Start the trace:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng start
+     Tracing started for session auto-20121015-232120
+                </literallayout>
+                And then stop the trace after awhile or after running
+                a particular workload that you want to trace:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng stop
+     Tracing stopped for session auto-20121015-232120
+                </literallayout>
+                You can now view the trace in text form on the target:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng view
+     [23:21:56.989270399] (+?.?????????) sys_geteuid: { 1 }, { }
+     [23:21:56.989278081] (+0.000007682) exit_syscall: { 1 }, { ret = 0 }
+     [23:21:56.989286043] (+0.000007962) sys_pipe: { 1 }, { fildes = 0xB77B9E8C }
+     [23:21:56.989321802] (+0.000035759) exit_syscall: { 1 }, { ret = 0 }
+     [23:21:56.989329345] (+0.000007543) sys_mmap_pgoff: { 1 }, { addr = 0x0, len = 10485760, prot = 3, flags = 131362, fd = 4294967295, pgoff = 0 }
+     [23:21:56.989351694] (+0.000022349) exit_syscall: { 1 }, { ret = -1247805440 }
+     [23:21:56.989432989] (+0.000081295) sys_clone: { 1 }, { clone_flags = 0x411, newsp = 0xB5EFFFE4, parent_tid = 0xFFFFFFFF, child_tid = 0x0 }
+     [23:21:56.989477129] (+0.000044140) sched_stat_runtime: { 1 }, { comm = "lttng-consumerd", tid = 1193, runtime = 681660, vruntime = 43367983388 }
+     [23:21:56.989486697] (+0.000009568) sched_migrate_task: { 1 }, { comm = "lttng-consumerd", tid = 1193, prio = 20, orig_cpu = 1, dest_cpu = 1 }
+     [23:21:56.989508418] (+0.000021721) hrtimer_init: { 1 }, { hrtimer = 3970832076, clockid = 1, mode = 1 }
+     [23:21:56.989770462] (+0.000262044) hrtimer_cancel: { 1 }, { hrtimer = 3993865440 }
+     [23:21:56.989771580] (+0.000001118) hrtimer_cancel: { 0 }, { hrtimer = 3993812192 }
+     [23:21:56.989776957] (+0.000005377) hrtimer_expire_entry: { 1 }, { hrtimer = 3993865440, now = 79815980007057, function = 3238465232 }
+     [23:21:56.989778145] (+0.000001188) hrtimer_expire_entry: { 0 }, { hrtimer = 3993812192, now = 79815980008174, function = 3238465232 }
+     [23:21:56.989791695] (+0.000013550) softirq_raise: { 1 }, { vec = 1 }
+     [23:21:56.989795396] (+0.000003701) softirq_raise: { 0 }, { vec = 1 }
+     [23:21:56.989800635] (+0.000005239) softirq_raise: { 0 }, { vec = 9 }
+     [23:21:56.989807130] (+0.000006495) sched_stat_runtime: { 1 }, { comm = "lttng-consumerd", tid = 1193, runtime = 330710, vruntime = 43368314098 }
+     [23:21:56.989809993] (+0.000002863) sched_stat_runtime: { 0 }, { comm = "lttng-sessiond", tid = 1181, runtime = 1015313, vruntime = 36976733240 }
+     [23:21:56.989818514] (+0.000008521) hrtimer_expire_exit: { 0 }, { hrtimer = 3993812192 }
+     [23:21:56.989819631] (+0.000001117) hrtimer_expire_exit: { 1 }, { hrtimer = 3993865440 }
+     [23:21:56.989821866] (+0.000002235) hrtimer_start: { 0 }, { hrtimer = 3993812192, function = 3238465232, expires = 79815981000000, softexpires = 79815981000000 }
+     [23:21:56.989822984] (+0.000001118) hrtimer_start: { 1 }, { hrtimer = 3993865440, function = 3238465232, expires = 79815981000000, softexpires = 79815981000000 }
+     [23:21:56.989832762] (+0.000009778) softirq_entry: { 1 }, { vec = 1 }
+     [23:21:56.989833879] (+0.000001117) softirq_entry: { 0 }, { vec = 1 }
+     [23:21:56.989838069] (+0.000004190) timer_cancel: { 1 }, { timer = 3993871956 }
+     [23:21:56.989839187] (+0.000001118) timer_cancel: { 0 }, { timer = 3993818708 }
+     [23:21:56.989841492] (+0.000002305) timer_expire_entry: { 1 }, { timer = 3993871956, now = 79515980, function = 3238277552 }
+     [23:21:56.989842819] (+0.000001327) timer_expire_entry: { 0 }, { timer = 3993818708, now = 79515980, function = 3238277552 }
+     [23:21:56.989854831] (+0.000012012) sched_stat_runtime: { 1 }, { comm = "lttng-consumerd", tid = 1193, runtime = 49237, vruntime = 43368363335 }
+     [23:21:56.989855949] (+0.000001118) sched_stat_runtime: { 0 }, { comm = "lttng-sessiond", tid = 1181, runtime = 45121, vruntime = 36976778361 }
+     [23:21:56.989861257] (+0.000005308) sched_stat_sleep: { 1 }, { comm = "kworker/1:1", tid = 21, delay = 9451318 }
+     [23:21:56.989862374] (+0.000001117) sched_stat_sleep: { 0 }, { comm = "kworker/0:0", tid = 4, delay = 9958820 }
+     [23:21:56.989868241] (+0.000005867) sched_wakeup: { 0 }, { comm = "kworker/0:0", tid = 4, prio = 120, success = 1, target_cpu = 0 }
+     [23:21:56.989869358] (+0.000001117) sched_wakeup: { 1 }, { comm = "kworker/1:1", tid = 21, prio = 120, success = 1, target_cpu = 1 }
+     [23:21:56.989877460] (+0.000008102) timer_expire_exit: { 1 }, { timer = 3993871956 }
+     [23:21:56.989878577] (+0.000001117) timer_expire_exit: { 0 }, { timer = 3993818708 }
+     .
+     .
+     .
+                </literallayout>
+                You can now safely destroy the trace session (note that
+                this doesn't delete the trace - it's still there
+                in ~/lttng-traces):
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng destroy
+     Session auto-20121015-232120 destroyed at /home/root
+                </literallayout>
+                Note that the trace is saved in a directory of the same
+                name as returned by 'lttng create', under the ~/lttng-traces
+                directory (note that you can change this by supplying your
+                own name to 'lttng create'):
+                <literallayout class='monospaced'>
+     root@crownbay:~# ls -al ~/lttng-traces
+     drwxrwx---    3 root     root          1024 Oct 15 23:21 .
+     drwxr-xr-x    5 root     root          1024 Oct 15 23:57 ..
+     drwxrwx---    3 root     root          1024 Oct 15 23:21 auto-20121015-232120
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='collecting-and-viewing-a-userspace-trace-on-the-target-inside-a-shell'>
+            <title>Collecting and viewing a userspace trace on the target (inside a shell)</title>
+
+            <para>
+                For lttng userspace tracing, you need to have a properly
+                instrumented userspace program. For this example, we'll use
+                the 'hello' test program generated by the lttng-ust build.
+            </para>
+
+            <para>
+                The 'hello' test program isn't installed on the rootfs by
+                the lttng-ust build, so we need to copy it over manually.
+                First cd into the build directory that contains the hello
+                executable:
+                <literallayout class='monospaced'>
+     $ cd build/tmp/work/core2-poky-linux/lttng-ust/2.0.5-r0/git/tests/hello/.libs
+                </literallayout>
+                Copy that over to the target machine:
+                <literallayout class='monospaced'>
+     $ scp hello root@192.168.1.20:
+                </literallayout>
+                You now have the instrumented lttng 'hello world' test
+                program on the target, ready to test.
+            </para>
+
+            <para>
+                First, from the target, ssh to the target:
+                <literallayout class='monospaced'>
+     $ ssh -l root 192.168.1.47
+     The authenticity of host '192.168.1.47 (192.168.1.47)' can't be established.
+     RSA key fingerprint is 23:bd:c8:b1:a8:71:52:00:ee:00:4f:64:9e:10:b9:7e.
+     Are you sure you want to continue connecting (yes/no)? yes
+     Warning: Permanently added '192.168.1.47' (RSA) to the list of known hosts.
+     root@192.168.1.47's password:
+                </literallayout>
+                Once on the target, use these steps to create a trace:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng create
+     Session auto-20190303-021943 created.
+     Traces will be written in /home/root/lttng-traces/auto-20190303-021943
+                </literallayout>
+                Enable the events you want to trace (in this case all
+                userspace events):
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng enable-event --userspace --all
+     All UST events are enabled in channel channel0
+                </literallayout>
+                Start the trace:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng start
+     Tracing started for session auto-20190303-021943
+                </literallayout>
+                Run the instrumented hello world program:
+                <literallayout class='monospaced'>
+     root@crownbay:~# ./hello
+     Hello, World!
+     Tracing...  done.
+                </literallayout>
+                And then stop the trace after awhile or after running a
+                particular workload that you want to trace:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng stop
+     Tracing stopped for session auto-20190303-021943
+                </literallayout>
+                You can now view the trace in text form on the target:
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng view
+     [02:31:14.906146544] (+?.?????????) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 0, intfield2 = 0x0, longfield = 0, netintfield = 0, netintfieldhex = 0x0, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4,  seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 }
+     [02:31:14.906170360] (+0.000023816) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 1, intfield2 = 0x1, longfield = 1, netintfield = 1, netintfieldhex = 0x1, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 }
+     [02:31:14.906183140] (+0.000012780) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 2, intfield2 = 0x2, longfield = 2, netintfield = 2, netintfieldhex = 0x2, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 }
+     [02:31:14.906194385] (+0.000011245) hello:1424 ust_tests_hello:tptest: { cpu_id = 1 }, { intfield = 3, intfield2 = 0x3, longfield = 3, netintfield = 3, netintfieldhex = 0x3, arrfield1 = [ [0] = 1, [1] = 2, [2] = 3 ], arrfield2 = "test", _seqfield1_length = 4, seqfield1 = [ [0] = 116, [1] = 101, [2] = 115, [3] = 116 ], _seqfield2_length = 4, seqfield2 = "test", stringfield = "test", floatfield = 2222, doublefield = 2, boolfield = 1 }
+     .
+     .
+     .
+                </literallayout>
+                You can now safely destroy the trace session (note that
+                this doesn't delete the trace - it's still
+                there in ~/lttng-traces):
+                <literallayout class='monospaced'>
+     root@crownbay:~# lttng destroy
+     Session auto-20190303-021943 destroyed at /home/root
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='manually-copying-a-trace-to-the-host-and-viewing-it-in-eclipse'>
+            <title>Manually copying a trace to the host and viewing it in Eclipse (i.e. using Eclipse without network support)</title>
+
+            <para>
+                If you already have an LTTng trace on a remote target and
+                would like to view it in Eclipse on the host, you can easily
+                copy it from the target to the host and import it into
+                Eclipse to view it using the LTTng Eclipse plug-in already
+                bundled in the Eclipse (Juno SR1 or greater).
+            </para>
+
+            <para>
+                Using the trace we created in the previous section, archive
+                it and copy it to your host system:
+                <literallayout class='monospaced'>
+     root@crownbay:~/lttng-traces# tar zcvf auto-20121015-232120.tar.gz auto-20121015-232120
+     auto-20121015-232120/
+     auto-20121015-232120/kernel/
+     auto-20121015-232120/kernel/metadata
+     auto-20121015-232120/kernel/channel0_1
+     auto-20121015-232120/kernel/channel0_0
+
+     $ scp root@192.168.1.47:lttng-traces/auto-20121015-232120.tar.gz .
+     root@192.168.1.47's password:
+     auto-20121015-232120.tar.gz                                             100% 1566KB   1.5MB/s   00:01
+                </literallayout>
+                Unarchive it on the host:
+                <literallayout class='monospaced'>
+     $ gunzip -c auto-20121015-232120.tar.gz | tar xvf -
+     auto-20121015-232120/
+     auto-20121015-232120/kernel/
+     auto-20121015-232120/kernel/metadata
+     auto-20121015-232120/kernel/channel0_1
+     auto-20121015-232120/kernel/channel0_0
+                </literallayout>
+                We can now import the trace into Eclipse and view it:
+                <orderedlist>
+                    <listitem><para>First, start eclipse and open the
+                        'LTTng Kernel' perspective by selecting the following
+                        menu item:
+                        <literallayout class='monospaced'>
+     Window | Open Perspective | Other...
+                        </literallayout></para></listitem>
+                    <listitem><para>In the dialog box that opens, select
+                        'LTTng Kernel' from the list.</para></listitem>
+                    <listitem><para>Back at the main menu, select the
+                        following menu item:
+                        <literallayout class='monospaced'>
+     File | New | Project...
+                        </literallayout></para></listitem>
+                    <listitem><para>In the dialog box that opens, select
+                        the 'Tracing | Tracing Project' wizard and press
+                        'Next>'.</para></listitem>
+                    <listitem><para>Give the project a name and press
+                        'Finish'.</para></listitem>
+                    <listitem><para>In the 'Project Explorer' pane under
+                        the project you created, right click on the
+                        'Traces' item.</para></listitem>
+                    <listitem><para>Select 'Import..." and in the dialog
+                        that's displayed:</para></listitem>
+                    <listitem><para>Browse the filesystem and find the
+                        select the 'kernel' directory containing the trace
+                        you copied from the target
+                        e.g. auto-20121015-232120/kernel</para></listitem>
+                    <listitem><para>'Checkmark' the directory in the tree
+                        that's displayed for the trace</para></listitem>
+                    <listitem><para>Below that, select 'Common Trace Format:
+                        Kernel Trace' for the 'Trace Type'</para></listitem>
+                    <listitem><para>Press 'Finish' to close the dialog
+                        </para></listitem>
+                    <listitem><para>Back in the 'Project Explorer' pane,
+                        double-click on the 'kernel' item for the
+                        trace you just imported under 'Traces'
+                        </para></listitem>
+                </orderedlist>
+                You should now see your trace data displayed graphically
+                in several different views in Eclipse:
+            </para>
+
+            <para>
+                <imagedata fileref="figures/lttngmain0.png" width="6in" depth="6in" align="center" scalefit="1" />
+            </para>
+
+            <para>
+                You can access extensive help information on how to use
+                the LTTng plug-in to search and analyze captured traces via
+                the Eclipse help system:
+                <literallayout class='monospaced'>
+     Help | Help Contents | LTTng Plug-in User Guide
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='collecting-and-viewing-a-trace-in-eclipse'>
+            <title>Collecting and viewing a trace in Eclipse</title>
+
+            <note>
+                This section on collecting traces remotely doesn't currently
+                work because of Eclipse 'RSE' connectivity problems. Manually
+                tracing on the target, copying the trace files to the host,
+                and viewing the trace in Eclipse on the host as outlined in
+                previous steps does work however - please use the manual
+                steps outlined above to view traces in Eclipse.
+            </note>
+
+            <para>
+                In order to trace a remote target, you also need to add
+                a 'tracing' group on the target and connect as a user
+                who's part of that group e.g:
+                <literallayout class='monospaced'>
+     # adduser tomz
+     # groupadd -r tracing
+     # usermod -a -G tracing tomz
+                </literallayout>
+                <orderedlist>
+                    <listitem><para>First, start eclipse and open the
+                        'LTTng Kernel' perspective by selecting the following
+                         menu item:
+                         <literallayout class='monospaced'>
+     Window | Open Perspective | Other...
+                         </literallayout></para></listitem>
+                    <listitem><para>In the dialog box that opens, select
+                        'LTTng Kernel' from the list.</para></listitem>
+                    <listitem><para>Back at the main menu, select the
+                        following menu item:
+                        <literallayout class='monospaced'>
+     File | New | Project...
+                        </literallayout></para></listitem>
+                    <listitem><para>In the dialog box that opens, select
+                        the 'Tracing | Tracing Project' wizard and
+                        press 'Next>'.</para></listitem>
+                    <listitem><para>Give the project a name and press
+                        'Finish'. That should result in an entry in the
+                        'Project' subwindow.</para></listitem>
+                    <listitem><para>In the 'Control' subwindow just below
+                        it, press 'New Connection'.</para></listitem>
+                    <listitem><para>Add a new connection, giving it the
+                        hostname or IP address of the target system.
+                        </para></listitem>
+                    <listitem><para>Provide the username and password
+                        of a qualified user (a member of the 'tracing' group)
+                        or root account on the target system.
+                        </para></listitem>
+                    <listitem><para>Provide appropriate answers to whatever
+                        else is asked for e.g. 'secure storage password'
+                        can be anything you want.
+                        If you get an 'RSE Error' it may be due to proxies.
+                        It may be possible to get around the problem by
+                        changing the following setting:
+                        <literallayout class='monospaced'>
+     Window | Preferences | Network Connections
+                        </literallayout>
+                        Switch 'Active Provider' to 'Direct'
+                        </para></listitem>
+                </orderedlist>
+            </para>
+        </section>
+    </section>
+
+    <section id='lltng-documentation'>
+        <title>Documentation</title>
+
+        <para>
+            There doesn't seem to be any current documentation covering
+            LTTng 2.0, but maybe that's because the project is in transition.
+            The LTTng 2.0 website, however, is here:
+            <ulink url='http://lttng.org/lttng2.0'>LTTng Project</ulink>
+        </para>
+
+        <para>
+            You can access extensive help information on how to use the
+            LTTng plug-in to search and analyze captured traces via the
+            Eclipse help system:
+            <literallayout class='monospaced'>
+     Help | Help Contents | LTTng Plug-in User Guide
+            </literallayout>
+        </para>
+    </section>
+</section>
+
+<section id='profile-manual-blktrace'>
+    <title>blktrace</title>
+
+    <para>
+        blktrace is a tool for tracing and reporting low-level disk I/O.
+        blktrace provides the tracing half of the equation; its output can
+        be piped into the blkparse program, which renders the data in a
+        human-readable form and does some basic analysis:
+    </para>
+
+    <section id='blktrace-setup'>
+        <title>Setup</title>
+
+        <para>
+            For this section, we'll assume you've already performed the
+            basic setup outlined in the
+            "<link linkend='profile-manual-general-setup'>General Setup</link>"
+            section.
+        </para>
+
+        <para>
+            blktrace is an application that runs on the target system.
+            You can run the entire blktrace and blkparse pipeline on the
+            target, or you can run blktrace in 'listen' mode on the target
+            and have blktrace and blkparse collect and analyze the data on
+            the host (see the
+            "<link linkend='using-blktrace-remotely'>Using blktrace Remotely</link>"
+            section below).
+            For the rest of this section we assume you've ssh'ed to the
+            host and will be running blkrace on the target.
+        </para>
+    </section>
+
+    <section id='blktrace-basic-usage'>
+        <title>Basic Usage</title>
+
+        <para>
+            To record a trace, simply run the 'blktrace' command, giving it
+            the name of the block device you want to trace activity on:
+            <literallayout class='monospaced'>
+     root@crownbay:~# blktrace /dev/sdc
+            </literallayout>
+            In another shell, execute a workload you want to trace.
+            <literallayout class='monospaced'>
+     root@crownbay:/media/sdc# rm linux-2.6.19.2.tar.bz2; wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>; sync
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |*******************************| 41727k  0:00:00 ETA
+            </literallayout>
+            Press Ctrl-C in the blktrace shell to stop the trace. It will
+            display how many events were logged, along with the per-cpu file
+            sizes (blktrace records traces in per-cpu kernel buffers and
+            simply dumps them to userspace for blkparse to merge and sort
+            later).
+            <literallayout class='monospaced'>
+     ^C=== sdc ===
+      CPU  0:                 7082 events,      332 KiB data
+      CPU  1:                 1578 events,       74 KiB data
+      Total:                  8660 events (dropped 0),      406 KiB data
+            </literallayout>
+            If you examine the files saved to disk, you see multiple files,
+            one per CPU and with the device name as the first part of the
+            filename:
+            <literallayout class='monospaced'>
+     root@crownbay:~# ls -al
+     drwxr-xr-x    6 root     root          1024 Oct 27 22:39 .
+     drwxr-sr-x    4 root     root          1024 Oct 26 18:24 ..
+     -rw-r--r--    1 root     root        339938 Oct 27 22:40 sdc.blktrace.0
+     -rw-r--r--    1 root     root         75753 Oct 27 22:40 sdc.blktrace.1
+            </literallayout>
+            To view the trace events, simply invoke 'blkparse' in the
+            directory containing the trace files, giving it the device name
+            that forms the first part of the filenames:
+            <literallayout class='monospaced'>
+     root@crownbay:~# blkparse sdc
+
+      8,32   1        1     0.000000000  1225  Q  WS 3417048 + 8 [jbd2/sdc-8]
+      8,32   1        2     0.000025213  1225  G  WS 3417048 + 8 [jbd2/sdc-8]
+      8,32   1        3     0.000033384  1225  P   N [jbd2/sdc-8]
+      8,32   1        4     0.000043301  1225  I  WS 3417048 + 8 [jbd2/sdc-8]
+      8,32   1        0     0.000057270     0  m   N cfq1225 insert_request
+      8,32   1        0     0.000064813     0  m   N cfq1225 add_to_rr
+      8,32   1        5     0.000076336  1225  U   N [jbd2/sdc-8] 1
+      8,32   1        0     0.000088559     0  m   N cfq workload slice:150
+      8,32   1        0     0.000097359     0  m   N cfq1225 set_active wl_prio:0 wl_type:1
+      8,32   1        0     0.000104063     0  m   N cfq1225 Not idling. st->count:1
+      8,32   1        0     0.000112584     0  m   N cfq1225 fifo=  (null)
+      8,32   1        0     0.000118730     0  m   N cfq1225 dispatch_insert
+      8,32   1        0     0.000127390     0  m   N cfq1225 dispatched a request
+      8,32   1        0     0.000133536     0  m   N cfq1225 activate rq, drv=1
+      8,32   1        6     0.000136889  1225  D  WS 3417048 + 8 [jbd2/sdc-8]
+      8,32   1        7     0.000360381  1225  Q  WS 3417056 + 8 [jbd2/sdc-8]
+      8,32   1        8     0.000377422  1225  G  WS 3417056 + 8 [jbd2/sdc-8]
+      8,32   1        9     0.000388876  1225  P   N [jbd2/sdc-8]
+      8,32   1       10     0.000397886  1225  Q  WS 3417064 + 8 [jbd2/sdc-8]
+      8,32   1       11     0.000404800  1225  M  WS 3417064 + 8 [jbd2/sdc-8]
+      8,32   1       12     0.000412343  1225  Q  WS 3417072 + 8 [jbd2/sdc-8]
+      8,32   1       13     0.000416533  1225  M  WS 3417072 + 8 [jbd2/sdc-8]
+      8,32   1       14     0.000422121  1225  Q  WS 3417080 + 8 [jbd2/sdc-8]
+      8,32   1       15     0.000425194  1225  M  WS 3417080 + 8 [jbd2/sdc-8]
+      8,32   1       16     0.000431968  1225  Q  WS 3417088 + 8 [jbd2/sdc-8]
+      8,32   1       17     0.000435251  1225  M  WS 3417088 + 8 [jbd2/sdc-8]
+      8,32   1       18     0.000440279  1225  Q  WS 3417096 + 8 [jbd2/sdc-8]
+      8,32   1       19     0.000443911  1225  M  WS 3417096 + 8 [jbd2/sdc-8]
+      8,32   1       20     0.000450336  1225  Q  WS 3417104 + 8 [jbd2/sdc-8]
+      8,32   1       21     0.000454038  1225  M  WS 3417104 + 8 [jbd2/sdc-8]
+      8,32   1       22     0.000462070  1225  Q  WS 3417112 + 8 [jbd2/sdc-8]
+      8,32   1       23     0.000465422  1225  M  WS 3417112 + 8 [jbd2/sdc-8]
+      8,32   1       24     0.000474222  1225  I  WS 3417056 + 64 [jbd2/sdc-8]
+      8,32   1        0     0.000483022     0  m   N cfq1225 insert_request
+      8,32   1       25     0.000489727  1225  U   N [jbd2/sdc-8] 1
+      8,32   1        0     0.000498457     0  m   N cfq1225 Not idling. st->count:1
+      8,32   1        0     0.000503765     0  m   N cfq1225 dispatch_insert
+      8,32   1        0     0.000512914     0  m   N cfq1225 dispatched a request
+      8,32   1        0     0.000518851     0  m   N cfq1225 activate rq, drv=2
+      .
+      .
+      .
+      8,32   0        0    58.515006138     0  m   N cfq3551 complete rqnoidle 1
+      8,32   0     2024    58.516603269     3  C  WS 3156992 + 16 [0]
+      8,32   0        0    58.516626736     0  m   N cfq3551 complete rqnoidle 1
+      8,32   0        0    58.516634558     0  m   N cfq3551 arm_idle: 8 group_idle: 0
+      8,32   0        0    58.516636933     0  m   N cfq schedule dispatch
+      8,32   1        0    58.516971613     0  m   N cfq3551 slice expired t=0
+      8,32   1        0    58.516982089     0  m   N cfq3551 sl_used=13 disp=6 charge=13 iops=0 sect=80
+      8,32   1        0    58.516985511     0  m   N cfq3551 del_from_rr
+      8,32   1        0    58.516990819     0  m   N cfq3551 put_queue
+
+     CPU0 (sdc):
+      Reads Queued:           0,        0KiB     Writes Queued:         331,   26,284KiB
+      Read Dispatches:        0,        0KiB     Write Dispatches:      485,   40,484KiB
+      Reads Requeued:         0          Writes Requeued:         0
+      Reads Completed:        0,        0KiB     Writes Completed:      511,   41,000KiB
+      Read Merges:            0,        0KiB     Write Merges:           13,      160KiB
+      Read depth:             0          Write depth:             2
+      IO unplugs:            23          Timer unplugs:           0
+     CPU1 (sdc):
+      Reads Queued:           0,        0KiB     Writes Queued:         249,   15,800KiB
+      Read Dispatches:        0,        0KiB     Write Dispatches:       42,    1,600KiB
+      Reads Requeued:         0          Writes Requeued:         0
+      Reads Completed:        0,        0KiB     Writes Completed:       16,    1,084KiB
+      Read Merges:            0,        0KiB     Write Merges:           40,      276KiB
+      Read depth:             0          Write depth:             2
+      IO unplugs:            30          Timer unplugs:           1
+
+     Total (sdc):
+      Reads Queued:           0,        0KiB     Writes Queued:         580,   42,084KiB
+      Read Dispatches:        0,        0KiB     Write Dispatches:      527,   42,084KiB
+      Reads Requeued:         0          Writes Requeued:         0
+      Reads Completed:        0,        0KiB     Writes Completed:      527,   42,084KiB
+      Read Merges:            0,        0KiB     Write Merges:           53,      436KiB
+      IO unplugs:            53          Timer unplugs:           1
+
+     Throughput (R/W): 0KiB/s / 719KiB/s
+     Events (sdc): 6,592 entries
+     Skips: 0 forward (0 -   0.0%)
+     Input file sdc.blktrace.0 added
+     Input file sdc.blktrace.1 added
+            </literallayout>
+            The report shows each event that was found in the blktrace data,
+            along with a summary of the overall block I/O traffic during
+            the run. You can look at the
+            <ulink url='http://linux.die.net/man/1/blkparse'>blkparse</ulink>
+            manpage to learn the
+            meaning of each field displayed in the trace listing.
+        </para>
+
+        <section id='blktrace-live-mode'>
+            <title>Live Mode</title>
+
+            <para>
+                blktrace and blkparse are designed from the ground up to
+                be able to operate together in a 'pipe mode' where the
+                stdout of blktrace can be fed directly into the stdin of
+                blkparse:
+                <literallayout class='monospaced'>
+     root@crownbay:~# blktrace /dev/sdc -o - | blkparse -i -
+                </literallayout>
+                This enables long-lived tracing sessions to run without
+                writing anything to disk, and allows the user to look for
+                certain conditions in the trace data in 'real-time' by
+                viewing the trace output as it scrolls by on the screen or
+                by passing it along to yet another program in the pipeline
+                such as grep which can be used to identify and capture
+                conditions of interest.
+            </para>
+
+            <para>
+                There's actually another blktrace command that implements
+                the above pipeline as a single command, so the user doesn't
+                have to bother typing in the above command sequence:
+                <literallayout class='monospaced'>
+     root@crownbay:~# btrace /dev/sdc
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='using-blktrace-remotely'>
+            <title>Using blktrace Remotely</title>
+
+            <para>
+                Because blktrace traces block I/O and at the same time
+                normally writes its trace data to a block device, and
+                in general because it's not really a great idea to make
+                the device being traced the same as the device the tracer
+                writes to, blktrace provides a way to trace without
+                perturbing the traced device at all by providing native
+                support for sending all trace data over the network.
+            </para>
+
+            <para>
+                To have blktrace operate in this mode, start blktrace on
+                the target system being traced with the -l option, along with
+                the device to trace:
+                <literallayout class='monospaced'>
+     root@crownbay:~# blktrace -l /dev/sdc
+     server: waiting for connections...
+                </literallayout>
+                On the host system, use the -h option to connect to the
+                target system, also passing it the device to trace:
+                <literallayout class='monospaced'>
+     $ blktrace -d /dev/sdc -h 192.168.1.43
+     blktrace: connecting to 192.168.1.43
+     blktrace: connected!
+                </literallayout>
+                On the target system, you should see this:
+                <literallayout class='monospaced'>
+     server: connection from 192.168.1.43
+                </literallayout>
+                In another shell, execute a workload you want to trace.
+                <literallayout class='monospaced'>
+     root@crownbay:/media/sdc# rm linux-2.6.19.2.tar.bz2; wget <ulink url='http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2'>http://downloads.yoctoproject.org/mirror/sources/linux-2.6.19.2.tar.bz2</ulink>; sync
+     Connecting to downloads.yoctoproject.org (140.211.169.59:80)
+     linux-2.6.19.2.tar.b 100% |*******************************| 41727k  0:00:00 ETA
+                </literallayout>
+                When it's done, do a Ctrl-C on the host system to
+                stop the trace:
+                <literallayout class='monospaced'>
+     ^C=== sdc ===
+      CPU  0:                 7691 events,      361 KiB data
+      CPU  1:                 4109 events,      193 KiB data
+      Total:                 11800 events (dropped 0),      554 KiB data
+                </literallayout>
+                On the target system, you should also see a trace
+                summary for the trace just ended:
+                <literallayout class='monospaced'>
+     server: end of run for 192.168.1.43:sdc
+     === sdc ===
+      CPU  0:                 7691 events,      361 KiB data
+      CPU  1:                 4109 events,      193 KiB data
+      Total:                 11800 events (dropped 0),      554 KiB data
+                </literallayout>
+                The blktrace instance on the host will save the target
+                output inside a hostname-timestamp directory:
+                <literallayout class='monospaced'>
+     $ ls -al
+     drwxr-xr-x   10 root     root          1024 Oct 28 02:40 .
+     drwxr-sr-x    4 root     root          1024 Oct 26 18:24 ..
+     drwxr-xr-x    2 root     root          1024 Oct 28 02:40 192.168.1.43-2012-10-28-02:40:56
+                </literallayout>
+                cd into that directory to see the output files:
+                <literallayout class='monospaced'>
+     $ ls -l
+     -rw-r--r--    1 root     root        369193 Oct 28 02:44 sdc.blktrace.0
+     -rw-r--r--    1 root     root        197278 Oct 28 02:44 sdc.blktrace.1
+                </literallayout>
+                And run blkparse on the host system using the device name:
+                <literallayout class='monospaced'>
+     $ blkparse sdc
+
+      8,32   1        1     0.000000000  1263  Q  RM 6016 + 8 [ls]
+      8,32   1        0     0.000036038     0  m   N cfq1263 alloced
+      8,32   1        2     0.000039390  1263  G  RM 6016 + 8 [ls]
+      8,32   1        3     0.000049168  1263  I  RM 6016 + 8 [ls]
+      8,32   1        0     0.000056152     0  m   N cfq1263 insert_request
+      8,32   1        0     0.000061600     0  m   N cfq1263 add_to_rr
+      8,32   1        0     0.000075498     0  m   N cfq workload slice:300
+      .
+      .
+      .
+      8,32   0        0   177.266385696     0  m   N cfq1267 arm_idle: 8 group_idle: 0
+      8,32   0        0   177.266388140     0  m   N cfq schedule dispatch
+      8,32   1        0   177.266679239     0  m   N cfq1267 slice expired t=0
+      8,32   1        0   177.266689297     0  m   N cfq1267 sl_used=9 disp=6 charge=9 iops=0 sect=56
+      8,32   1        0   177.266692649     0  m   N cfq1267 del_from_rr
+      8,32   1        0   177.266696560     0  m   N cfq1267 put_queue
+
+     CPU0 (sdc):
+      Reads Queued:           0,        0KiB     Writes Queued:         270,   21,708KiB
+      Read Dispatches:       59,    2,628KiB     Write Dispatches:      495,   39,964KiB
+      Reads Requeued:         0          Writes Requeued:         0
+      Reads Completed:       90,    2,752KiB     Writes Completed:      543,   41,596KiB
+      Read Merges:            0,        0KiB     Write Merges:            9,      344KiB
+      Read depth:             2          Write depth:             2
+      IO unplugs:            20          Timer unplugs:           1
+     CPU1 (sdc):
+      Reads Queued:         688,    2,752KiB     Writes Queued:         381,   20,652KiB
+      Read Dispatches:       31,      124KiB     Write Dispatches:       59,    2,396KiB
+      Reads Requeued:         0          Writes Requeued:         0
+      Reads Completed:        0,        0KiB     Writes Completed:       11,      764KiB
+      Read Merges:          598,    2,392KiB     Write Merges:           88,      448KiB
+      Read depth:             2          Write depth:             2
+      IO unplugs:            52          Timer unplugs:           0
+
+     Total (sdc):
+      Reads Queued:         688,    2,752KiB     Writes Queued:         651,   42,360KiB
+      Read Dispatches:       90,    2,752KiB     Write Dispatches:      554,   42,360KiB
+      Reads Requeued:         0          Writes Requeued:         0
+      Reads Completed:       90,    2,752KiB     Writes Completed:      554,   42,360KiB
+      Read Merges:          598,    2,392KiB     Write Merges:           97,      792KiB
+      IO unplugs:            72          Timer unplugs:           1
+
+     Throughput (R/W): 15KiB/s / 238KiB/s
+     Events (sdc): 9,301 entries
+     Skips: 0 forward (0 -   0.0%)
+                </literallayout>
+                You should see the trace events and summary just as
+                you would have if you'd run the same command on the target.
+            </para>
+        </section>
+
+        <section id='tracing-block-io-via-ftrace'>
+            <title>Tracing Block I/O via 'ftrace'</title>
+
+            <para>
+                It's also possible to trace block I/O using only
+                <link linkend='the-trace-events-subsystem'>trace events subsystem</link>,
+                which can be useful for casual tracing
+                if you don't want bother dealing with the userspace tools.
+            </para>
+
+            <para>
+                To enable tracing for a given device, use
+                /sys/block/xxx/trace/enable, where xxx is the device name.
+                This for example enables tracing for /dev/sdc:
+                <literallayout class='monospaced'>
+     root@crownbay:/sys/kernel/debug/tracing# echo 1 > /sys/block/sdc/trace/enable
+                </literallayout>
+                Once you've selected the device(s) you want to trace,
+                selecting the 'blk' tracer will turn the blk tracer on:
+                <literallayout class='monospaced'>
+     root@crownbay:/sys/kernel/debug/tracing# cat available_tracers
+     blk function_graph function nop
+
+     root@crownbay:/sys/kernel/debug/tracing# echo blk > current_tracer
+                </literallayout>
+                Execute the workload you're interested in:
+                <literallayout class='monospaced'>
+     root@crownbay:/sys/kernel/debug/tracing# cat /media/sdc/testfile.txt
+                </literallayout>
+                And look at the output (note here that we're using
+                'trace_pipe' instead of trace to capture this trace -
+                this allows us to wait around on the pipe for data to
+                appear):
+                <literallayout class='monospaced'>
+     root@crownbay:/sys/kernel/debug/tracing# cat trace_pipe
+                 cat-3587  [001] d..1  3023.276361:   8,32   Q   R 1699848 + 8 [cat]
+                 cat-3587  [001] d..1  3023.276410:   8,32   m   N cfq3587 alloced
+                 cat-3587  [001] d..1  3023.276415:   8,32   G   R 1699848 + 8 [cat]
+                 cat-3587  [001] d..1  3023.276424:   8,32   P   N [cat]
+                 cat-3587  [001] d..2  3023.276432:   8,32   I   R 1699848 + 8 [cat]
+                 cat-3587  [001] d..1  3023.276439:   8,32   m   N cfq3587 insert_request
+                 cat-3587  [001] d..1  3023.276445:   8,32   m   N cfq3587 add_to_rr
+                 cat-3587  [001] d..2  3023.276454:   8,32   U   N [cat] 1
+                 cat-3587  [001] d..1  3023.276464:   8,32   m   N cfq workload slice:150
+                 cat-3587  [001] d..1  3023.276471:   8,32   m   N cfq3587 set_active wl_prio:0 wl_type:2
+                 cat-3587  [001] d..1  3023.276478:   8,32   m   N cfq3587 fifo=  (null)
+                 cat-3587  [001] d..1  3023.276483:   8,32   m   N cfq3587 dispatch_insert
+                 cat-3587  [001] d..1  3023.276490:   8,32   m   N cfq3587 dispatched a request
+                 cat-3587  [001] d..1  3023.276497:   8,32   m   N cfq3587 activate rq, drv=1
+                 cat-3587  [001] d..2  3023.276500:   8,32   D   R 1699848 + 8 [cat]
+                </literallayout>
+                And this turns off tracing for the specified device:
+                <literallayout class='monospaced'>
+     root@crownbay:/sys/kernel/debug/tracing# echo 0 > /sys/block/sdc/trace/enable
+                </literallayout>
+            </para>
+        </section>
+    </section>
+
+    <section id='blktrace-documentation'>
+        <title>Documentation</title>
+
+        <para>
+            Online versions of the man pages for the commands discussed
+            in this section can be found here:
+            <itemizedlist>
+                <listitem><para><ulink url='http://linux.die.net/man/8/blktrace'>http://linux.die.net/man/8/blktrace</ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='http://linux.die.net/man/1/blkparse'>http://linux.die.net/man/1/blkparse</ulink>
+                    </para></listitem>
+                <listitem><para><ulink url='http://linux.die.net/man/8/btrace'>http://linux.die.net/man/8/btrace</ulink>
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            The above manpages, along with manpages for the other
+            blktrace utilities (btt, blkiomon, etc) can be found in the
+            /doc directory of the blktrace tools git repo:
+            <literallayout class='monospaced'>
+     $ git clone git://git.kernel.dk/blktrace.git
+            </literallayout>
+        </para>
+    </section>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/profile-manual/profile-manual.xml b/documentation/profile-manual/profile-manual.xml
new file mode 100644
index 0000000000..bafecff7e2
--- /dev/null
+++ b/documentation/profile-manual/profile-manual.xml
@@ -0,0 +1,85 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='profile-manual' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='figures/profile-title.png'
+                    format='SVG'
+                    align='left' scalefit='1' width='100%'/>
+            </imageobject>
+        </mediaobject>
+
+        <title>
+                  Yocto Project Profiling and Tracing Manual
+                </title>
+
+        <authorgroup>
+            <author>
+                <firstname>Tom</firstname> <surname>Zanussi</surname>
+                <affiliation>
+                    <orgname>Intel Corporation</orgname>
+                </affiliation>
+                <email>tom.zanussi@intel.com</email>
+            </author>
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>April 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5</revnumber>
+                <date>October 2013</date>
+                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5.1</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
+            </revision>
+        </revhistory>
+
+    <copyright>
+     <year>&COPYRIGHT_YEAR;</year>
+      <holder>Linux Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+          Permission is granted to copy, distribute and/or modify this document under
+          the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">
+          Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by
+          Creative Commons.
+      </para>
+
+      <note>
+          For the latest version of this manual associated with this
+          Yocto Project release, see the
+          <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>
+          from the Yocto Project website.
+      </note>
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="profile-manual-intro.xml"/>
+
+    <xi:include href="profile-manual-arch.xml"/>
+
+    <xi:include href="profile-manual-usage.xml"/>
+
+    <xi:include href="profile-manual-examples.xml"/>
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/TODO b/documentation/ref-manual/TODO
new file mode 100644
index 0000000000..ee0db977cc
--- /dev/null
+++ b/documentation/ref-manual/TODO
@@ -0,0 +1,11 @@
+Handbook Todo List:
+
+  * Document adding a new IMAGE_FEATURE to the customising images section 
+  * Add instructions about using zaurus/openmoko emulation
+  * Add component overview/block diagrams
+  * Software Deevelopment intro should mention its software development for 
+    intended target and could be a different arch etc and thus special case. 
+  * Expand insane.bbclass documentation to cover tests
+  * Document remaining classes (see list in ref-classes)
+  * Document formfactor
+
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
new file mode 100644
index 0000000000..25c03e0a52
--- /dev/null
+++ b/documentation/ref-manual/closer-look.xml
@@ -0,0 +1,1224 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='closer-look'>
+<title>A Closer Look at the Yocto Project Development Environment</title>
+
+    <para>
+        This chapter takes a more detailed look at the Yocto Project
+        development environment.
+        The following diagram represents the development environment at a
+        high level.
+        The remainder of this chapter expands on the fundamental input, output,
+        process, and
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>) blocks
+        in the Yocto Project development environment.
+    </para>
+
+    <para id='general-yocto-environment-figure'>
+        <imagedata fileref="figures/yocto-environment-ref.png" align="center" width="8in" depth="4.25in" />
+    </para>
+
+    <para>
+        The generalized Yocto Project Development Environment consists of
+        several functional areas:
+        <itemizedlist>
+            <listitem><para><emphasis>User Configuration:</emphasis>
+                Metadata you can use to control the build process.
+                </para></listitem>
+            <listitem><para><emphasis>Metadata Layers:</emphasis>
+                Various layers that provide software, machine, and
+                distro Metadata.</para></listitem>
+            <listitem><para><emphasis>Source Files:</emphasis>
+                Upstream releases, local projects, and SCMs.</para></listitem>
+            <listitem><para><emphasis>Build System:</emphasis>
+                Processes under the control of BitBake.
+                This block expands on how BitBake fetches source, applies
+                patches, completes compilation, analyzes output for package
+                generation, creates and tests packages, generates images, and
+                generates cross-development tools.</para></listitem>
+            <listitem><para><emphasis>Package Feeds:</emphasis>
+                Directories containing output packages (rpm, deb or ipk),
+                which are subsequently used in the construction of an image or
+                SDK, produced by the build system.
+                These feeds can also be copied and shared using a web server or
+                other means to facilitate extending or updating existing
+                images on devices at runtime if runtime package management is
+                enabled.</para></listitem>
+            <listitem><para><emphasis>Images:</emphasis>
+                Images produced by the development process.
+                Where do they go?
+                Can you mess with them (i.e. freely delete them or move them?).
+                </para></listitem>
+            <listitem><para><emphasis>Application Development SDK:</emphasis>
+                Cross-development tools that are produced along with an image
+                or separately with BitBake.</para></listitem>
+        </itemizedlist>
+    </para>
+
+    <section id="user-configuration">
+        <title>User Configuration</title>
+
+        <para>
+            User configuration helps define the build.
+            Through user configuration, you can tell BitBake the
+            target architecture for which you are building the image,
+            where to store downloaded source, and other build properties.
+        </para>
+
+        <para>
+            The following figure shows an expanded representation of the
+            "User Configuration" box of the
+            <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/user-configuration.png" align="center" width="5.5in" depth="3.5in" />
+        </para>
+
+        <para>
+            BitBake needs some basic configuration files in order to complete
+            a build.
+            These files are <filename>*.conf</filename> files.
+            The minimally necessary ones reside as example files in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            For simplicity, this section refers to the Source Directory as
+            the "Poky Directory."
+        </para>
+
+        <para>
+            When you clone the <filename>poky</filename> Git repository or you
+            download and unpack a Yocto Project release, you can set up the
+            Source Directory to be named anything you want.
+            For this discussion, the cloned repository uses the default
+            name <filename>poky</filename>.
+            <note>
+                The Poky repository is primarily an aggregation of existing
+                repositories.
+                It is not a canonical upstream source.
+            </note>
+        </para>
+
+        <para>
+            The <filename>meta-yocto</filename> layer inside Poky contains
+            a <filename>conf</filename> directory that has example
+            configuration files.
+            These example files are used as a basis for creating actual
+            configuration files when you source the build environment
+            script
+            (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+        </para>
+
+        <para>
+            Sourcing the build environment script creates a
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            if one does not already exist.
+            BitBake uses the Build Directory for all its work during builds.
+            The Build Directory has a <filename>conf</filename> directory that
+            contains default versions of your <filename>local.conf</filename>
+            and <filename>bblayers.conf</filename> configuration files.
+            These default configuration files are created only if versions
+            do not already exist in the Build Directory at the time you
+            source the build environment setup script.
+        </para>
+
+        <para>
+            Because the Poky repository is fundamentally an aggregation of
+            existing repositories, some users might be familiar with running
+            the <filename>&OE_INIT_FILE;</filename> or
+            <filename>oe-init-build-env-memres</filename> script in the context
+            of separate OpenEmbedded-Core and BitBake repositories rather than a
+            single Poky repository.
+            This discussion assumes the script is executed from within a cloned
+            or unpacked version of Poky.
+        </para>
+
+        <para>
+            Depending on where the script is sourced, different sub-scripts
+            are called to set up the Build Directory (Yocto or OpenEmbedded).
+            Specifically, the script
+            <filename>scripts/oe-setup-builddir</filename> inside the
+            poky directory sets up the Build Directory and seeds the directory
+            (if necessary) with configuration files appropriate for the
+            Yocto Project development environment.
+            <note>
+                The <filename>scripts/oe-setup-builddir</filename> script
+                uses the <filename>$TEMPLATECONF</filename> variable to
+                determine which sample configuration files to locate.
+            </note>
+        </para>
+
+        <para>
+            The <filename>local.conf</filename> file provides many
+            basic variables that define a build environment.
+            Here is a list of a few.
+            To see the default configurations in a <filename>local.conf</filename>
+            file created by the build environment script, see the
+            <filename>local.conf.sample</filename> in the
+            <filename>meta-yocto</filename> layer:
+            <itemizedlist>
+                <listitem><para><emphasis>Parallelism Options:</emphasis>
+                    Controlled by the
+                    <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
+                    and
+                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
+                    variables.</para></listitem>
+                <listitem><para><emphasis>Target Machine Selection:</emphasis>
+                    Controlled by the
+                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
+                    variable.</para></listitem>
+                <listitem><para><emphasis>Download Directory:</emphasis>
+                    Controlled by the
+                    <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+                    variable.</para></listitem>
+                <listitem><para><emphasis>Shared State Directory:</emphasis>
+                    Controlled by the
+                    <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>
+                    variable.</para></listitem>
+                <listitem><para><emphasis>Build Output:</emphasis>
+                    Controlled by the
+                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+                    variable.</para></listitem>
+            </itemizedlist>
+            <note>
+                Configurations set in the <filename>conf/local.conf</filename>
+                file can also be set in the
+                <filename>conf/site.conf</filename> and
+                <filename>conf/auto.conf</filename> configuration files.
+            </note>
+        </para>
+
+        <para>
+            The <filename>bblayers.conf</filename> file tells BitBake what
+            layers you want considered during the build.
+            By default, the layers listed in this file include layers
+            minimally needed by the build system.
+            However, you must manually add any custom layers you have created.
+            You can find more information on working with the
+            <filename>bblayers.conf</filename> file in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#enabling-your-layer'>Enabling Your Layer</ulink>"
+            section in the Yocto Project Development Manual.
+        </para>
+
+        <para>
+            The files <filename>site.conf</filename> and
+            <filename>auto.conf</filename> are not created by the environment
+            initialization script.
+            If you want these configuration files, you must create them
+            yourself:
+            <itemizedlist>
+                <listitem><para><emphasis><filename>site.conf</filename>:</emphasis>
+                    You can use the <filename>conf/site.conf</filename>
+                    configuration file to configure multiple build directories.
+                    For example, suppose you had several build environments and
+                    they shared some common features.
+                    You can set these default build properties here.
+                    A good example is perhaps the level of parallelism you want
+                    to use through the
+                    <link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link>
+                    and
+                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>
+                    variables.</para>
+                    <para>One useful scenario for using the
+                    <filename>conf/site.conf</filename> file is to extend your
+                    <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+                    variable to include the path to a
+                    <filename>conf/site.conf</filename>.
+                    Then, when BitBake looks for Metadata using
+                    <filename>BBPATH</filename>, it finds the
+                    <filename>conf/site.conf</filename> file and applies your
+                    common configurations found in the file.
+                    To override configurations in a particular build directory,
+                    alter the similar configurations within that build
+                    directory's <filename>conf/local.conf</filename> file.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>auto.conf</filename>:</emphasis>
+                    This file is not hand-created.
+                    Rather, the file is usually created and written to by
+                    an autobuilder.
+                    The settings put into the file are typically the same as
+                    you would find in the <filename>conf/local.conf</filename>
+                    or the <filename>conf/site.conf</filename> files.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            You can edit all configuration files to further define
+            any particular build environment.
+            This process is represented by the "User Configuration Edits"
+            box in the figure.
+        </para>
+
+        <para>
+            When you launch your build with the
+            <filename>bitbake &lt;target&gt;</filename> command, BitBake
+            sorts out the configurations to ultimately define your build
+            environment.
+        </para>
+    </section>
+
+    <section id="metadata-machine-configuration-and-policy-configuration">
+        <title>Metadata, Machine Configuration, and Policy Configuration</title>
+
+        <para>
+            The previous section described the user configurations that
+            define the BitBake's global behavior.
+            This section takes a closer look at the layers the build system
+            uses to further control the build.
+            These layers provide Metadata for the software, machine, and
+            policy.
+        </para>
+
+        <para>
+            In general, three types of layer input exist:
+            <itemizedlist>
+                <listitem><para><emphasis>Policy Configuration:</emphasis>
+                    Distribution Layers provide top-level or general
+                    policies for the image or SDK being built.
+                    For example, this layer would dictate whether BitBake
+                    produces RPM or IPK packages.</para></listitem>
+                <listitem><para><emphasis>Machine Configuration:</emphasis>
+                    Board Support Package (BSP) layers provide machine
+                    configurations.
+                    This type of information is specific to a particular
+                    target architecture.</para></listitem>
+                <listitem><para><emphasis>Metadata:</emphasis>
+                    Software layers contain user-supplied recipe files,
+                    patches, and append files.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            The following figure shows an expanded representation of the
+            Metadata, Machine Configuration, and Policy Configuration input
+            (layers) boxes of the
+            <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>:
+        </para>
+
+        <para>
+            <imagedata fileref="figures/layer-input.png" align="center" width="8in" depth="7.5in" />
+        </para>
+
+        <para>
+            In general, all layers have a similar structure.
+            They all contain a licensing file
+            (e.g. <filename>COPYING</filename>) if the layer is to be
+            distributed, a <filename>README</filename> file as good practice
+            and especially if the layer is to be distributed, a
+            configuration directory, and recipe directories.
+        </para>
+
+        <para>
+            The Yocto Project has many layers that can be used.
+            You can see a web-interface listing of them on the
+            <ulink url="http://git.yoctoproject.org/">Source Repositories</ulink>
+            page.
+            The layers are shown at the bottom categorized under
+            "Yocto Metadata Layers."
+            These layers are fundamentally a subset of the
+            <ulink url="http://layers.openembedded.org/layerindex/layers/">OpenEmbedded Metadata Index</ulink>,
+            which lists all layers provided by the OpenEmbedded community.
+            <note>
+                Layers exist in the Yocto Project Source Repositories that
+                cannot be found in the OpenEmbedded Metadata Index.
+                These layers are either deprecated or experimental in nature.
+            </note>
+        </para>
+
+        <para>
+            BitBake uses the <filename>conf/bblayers.conf</filename> file,
+            which is part of the user configuration, to find what layers it
+            should be using as part of the build.
+        </para>
+
+        <para>
+            For more information on layers, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+            section in the Yocto Project Development Manual.
+        </para>
+
+        <section id="distro-layer">
+            <title>Distro Layer</title>
+
+            <para>
+                The distribution layer provides policy configurations for your
+                distribution.
+                Best practices dictate that you isolate these types of
+                configurations into their own layer.
+                Settings you provide in
+                <filename>conf/&lt;distro&gt;.conf</filename> override similar
+                settings that BitBake finds in your
+                <filename>conf/local.conf</filename> file in the Build
+                Directory.
+            </para>
+
+            <para>
+                The following list provides some explanation and references
+                for what you typically find in the distribution layer:
+                <itemizedlist>
+                    <listitem><para><emphasis>classes:</emphasis>
+                        Class files (<filename>.bbclass</filename>) holds
+                        common functionality that can be shared among
+                        recipes in the distribution.
+                        When your recipes inherit a class, they take on the
+                        settings and functions for that class.
+                        You can read more about class files in the
+                        "<link linkend='ref-classes'>Classes</link>" section.
+                        </para></listitem>
+                    <listitem><para><emphasis>conf:</emphasis>
+                        This area holds configuration files for the
+                        layer (<filename>conf/layer.conf</filename>),
+                        the distribution
+                        (<filename>conf/distro/&lt;distro&gt;.conf</filename>),
+                        and any distribution-wide include files.
+                        </para></listitem>
+                    <listitem><para><emphasis>recipes-*:</emphasis>
+                        Recipes and append files that affect common
+                        functionality across the distribution.
+                        This area could include recipes and append files to
+                        to add distribution-specific configuration,
+                        initialization scripts, custom image recipes,
+                        and so forth.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id="bsp-layer">
+            <title>BSP Layer</title>
+
+            <para>
+                The BSP Layer provides machine configurations.
+                Everything in this layer is specific to the machine for which
+                you are building the image or the SDK.
+                A common structure or form is defined for BSP layers.
+                You can learn more about this structure in the
+                <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+                <note>
+                    In order for a BSP layer to be considered compliant with the
+                    Yocto Project, it must meet some structural requirements.
+                </note>
+            </para>
+
+            <para>
+                The BSP Layer's configuration directory contains
+                configuration files for the machine
+                (<filename>conf/machine/&lt;machine&gt;.conf</filename>) and,
+                of course, the layer (<filename>conf/layer.conf</filename>).
+            </para>
+
+            <para>
+                The remainder of the layer is dedicated to specific recipes
+                by function: <filename>recipes-bsp</filename>,
+                <filename>recipes-core</filename>,
+                <filename>recipes-graphics</filename>, and
+                <filename>recipes-kernel</filename>.
+                Metadata can exist for multiple formfactors, graphics
+                support systems, and so forth.
+                <note>
+                    While the figure shows several <filename>recipe-*</filename>
+                    directories, not all these directories appear in all
+                    BSP layers.
+                </note>
+            </para>
+        </section>
+
+        <section id="software-layer">
+            <title>Software Layer</title>
+
+            <para>
+                The software layer provides the Metadata for additional
+                software packages used during the build.
+                This layer does not include Metadata that is specific to the
+                distribution or the machine, which are found in their
+                respective layers.
+            </para>
+
+            <para>
+                This layer contains any new recipes that your project needs
+                in the form of recipe files.
+            </para>
+        </section>
+    </section>
+
+    <section id="sources-dev-environment">
+        <title>Sources</title>
+
+        <para>
+            In order for the OpenEmbedded build system to create an image or
+            any target, it must be able to access source files.
+            The
+            <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
+            represents source files using the "Upstream Project Releases",
+            "Local Projects", and "SCMs (optional)" boxes.
+            The figure represents mirrors, which also play a role in locating
+            source files, with the "Source Mirror(s)" box.
+        </para>
+
+        <para>
+            The method by which source files are ultimately organized is
+            a function of the project.
+            For example, for released software, projects tend to use tarballs
+            or other archived files that can capture the state of a release
+            guaranteeing that it is statically represented.
+            On the other hand, for a project that is more dynamic or
+            experimental in nature, a project might keep source files in a
+            repository controlled by a Source Control Manager (SCM) such as
+            Git.
+            Pulling source from a repository allows you to control
+            the point in the repository (the revision) from which you want to
+            build software.
+            Finally, a combination of the two might exist, which would give the
+            consumer a choice when deciding where to get source files.
+        </para>
+
+        <para>
+            BitBake uses the
+            <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+            variable to point to source files regardless of their location.
+            Each recipe must have a <filename>SRC_URI</filename> variable
+            that points to the source.
+        </para>
+
+        <para>
+            Another area that plays a significant role in where source files
+            comes from is pointed to by the
+            <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+            variable.
+            This area is a cache that can hold previously downloaded source.
+            You can also instruct the OpenEmbedded build system to create
+            tarballs from Git repositories, which is not the default behavior,
+            and store them in the <filename>DL_DIR</filename> by using the
+            <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
+            variable.
+        </para>
+
+        <para>
+            Judicious use of a <filename>DL_DIR</filename> directory can
+            save the build system a trip across the Internet when looking
+            for files.
+            A good method for using a download directory is to have
+            <filename>DL_DIR</filename> point to an area outside of your
+            Build Directory.
+            Doing so allows you to safely delete the Build Directory
+            if needed without fear of removing any downloaded source file.
+        </para>
+
+        <para>
+            The remainder of this section provides a deeper look into the
+            source files and the mirrors.
+            Here is a more detailed look at the source file area of the
+            base figure:
+            <imagedata fileref="figures/source-input.png" align="center" width="7in" depth="7.5in" />
+        </para>
+
+        <section id='upstream-project-releases'>
+            <title>Upstream Project Releases</title>
+
+            <para>
+                Upstream project releases exist anywhere in the form of an
+                archived file (e.g. tarball or zip file).
+                These files correspond to individual recipes.
+                For example, the figure uses specific releases each for
+                BusyBox, Qt, and Dbus.
+                An archive file can be for any released product that can be
+                built using a recipe.
+            </para>
+        </section>
+
+        <section id='local-projects'>
+            <title>Local Projects</title>
+
+            <para>
+                Local projects are custom bits of software the user provides.
+                These bits reside somewhere local to a project - perhaps
+                a directory into which the user checks in items (e.g.
+                a local directory containing a development source tree
+                used by the group).
+            </para>
+
+            <para>
+                The canonical method through which to include a local project
+                is to use the
+                <link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>
+                class to include local project.
+                You use either the <filename>local.conf</filename> or a
+                recipe's append file to override or set the
+                recipe to point to the local directory on your disk to pull
+                in the whole source tree.
+            </para>
+
+            <para>
+                For information on how to use the
+                <filename>externalsrc.bbclass</filename>, see the
+                "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
+                section.
+            </para>
+        </section>
+
+        <section id='scms'>
+            <title>Source Control Managers (Optional)</title>
+
+            <para>
+                Another place the build system can get source files from is
+                through an SCM such as Git or Subversion.
+                In this case, a repository is cloned or checked out.
+                The <filename>do_fetch</filename> task inside BitBake uses
+                the <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+                variable and the argument's prefix to determine the correct
+                fetcher module.
+            </para>
+
+            <note>
+                For information on how to have the OpenEmbedded build system
+                generate tarballs for Git repositories and place them in the
+                <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+                directory, see the
+                <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
+                variable.
+            </note>
+
+            <para>
+                When fetching a repository, BitBake uses the
+                <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
+                variable to determine the specific revision from which to
+                build.
+            </para>
+        </section>
+
+        <section id='source-mirrors'>
+            <title>Source Mirror(s)</title>
+
+            <para>
+                Two kinds of mirrors exist: pre-mirrors and regular mirrors.
+                The <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
+                and
+                <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
+                variables point to these, respectively.
+                BitBake checks pre-mirrors before looking upstream for any
+                source files.
+                Pre-mirrors are appropriate when you have a shared directory
+                that is not a directory defined by the
+                <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+                variable.
+                A Pre-mirror typically points to a shared directory that is
+                local to your organization.
+            </para>
+
+            <para>
+                Regular mirrors can be any site across the Internet that is
+                used as an alternative location for source code should the
+                primary site not be functioning for some reason or another.
+            </para>
+        </section>
+    </section>
+
+    <section id="package-feeds-dev-environment">
+        <title>Package Feeds</title>
+
+        <para>
+            When the OpenEmbedded build system generates an image or an SDK,
+            it gets the packages from a package feed area located in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+            The
+            <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
+            shows this package feeds area in the upper-right corner.
+        </para>
+
+        <para>
+            This section looks a little closer into the package feeds area used
+            by the build system.
+            Here is a more detailed look at the area:
+            <imagedata fileref="figures/package-feeds.png" align="center" width="7in" depth="6in" />
+        </para>
+
+        <para>
+            Package feeds are an intermediary step in the build process.
+            BitBake generates packages whose type is defined by the
+            <link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>
+            variable.
+            Before placing the packages into package feeds,
+            the build process validates them with generated output quality
+            assurance checks through the
+            <link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>
+            class.
+        </para>
+
+        <para>
+            The package feed area resides in
+            <filename>tmp/deploy</filename> of the Build Directory.
+            Folders are created that correspond to the package type
+            (IPK, DEB, or RPM) created.
+            Further organization is derived through the value of the
+            <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
+            variable for each package.
+            For example, packages can exist for the i586 or qemux86
+            architectures.
+            The package files themselves reside within the appropriate
+            architecture folder.
+        </para>
+
+        <para>
+            BitBake uses the <filename>do_package_write_*</filename> task to
+            place generated packages into the package holding area (e.g.
+            <filename>do_package_write_ipk</filename> for IPK packages).
+        </para>
+    </section>
+
+    <section id='bitbake-dev-environment'>
+        <title>BitBake</title>
+
+        <para>
+            The OpenEmbedded build system uses BitBake to produce images.
+            You can see from the
+            <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
+            the BitBake area consists of several functional areas.
+            This section takes a closer look at each of those areas.
+        </para>
+
+        <section id='source-fetching-dev-environment'>
+            <title>Source Fetching</title>
+
+            <para>
+                The first stages of building a recipe are to fetch and unpack
+                the source code:
+                <imagedata fileref="figures/source-fetching.png" align="center" width="6.5in" depth="5in" />
+            </para>
+
+            <para>
+                The <filename>do_fetch</filename> and
+                <filename>do_unpack</filename> tasks fetch the source files
+                and unpack them into a working directory.
+                By default, everything is accomplished in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+                which has a defined structure.
+                For additional general information on the Build Directory,
+                see the
+                "<link linkend='structure-core-build'><filename>build/</filename></link>"
+                section.
+            </para>
+
+            <para>
+                Unpacked source source files are pointed to by the
+                <link linkend='var-S'><filename>S</filename></link> variable.
+                Each recipe has an area in the Build Directory where the
+                unpacked source code resides.
+                The name of directory for any given recipe is defined from
+                several different variables.
+                You can see the variables that define these directories
+                by looking at the figure:
+                <itemizedlist>
+                    <listitem><para><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PN'><filename>PN</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PV'><filename>PV</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PR'><filename>PR</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-S'><filename>S</filename></link>
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Briefly, the <filename>S</filename> directory contains the
+                unpacked source files for a recipe.
+                The <filename>WORKDIR</filename> directory is where all the
+                building goes on for a given recipe.
+            </para>
+        </section>
+
+        <section id='patching-dev-environment'>
+            <title>Patching</title>
+
+            <para>
+                Once source code is fetched and unpacked, BitBake locates
+                patch files and applies them to the source files:
+                <imagedata fileref="figures/patching.png" align="center" width="6in" depth="5in" />
+            </para>
+
+            <para>
+                The <filename>do_patch</filename> task processes recipes by
+                using the
+                <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+                variable to locate applicable patch files, which by default
+                are <filename>*.patch</filename> or
+                <filename>*.diff</filename> files, or any file if
+                "apply=yes" is specified for the file in
+                <filename>SRC_URI</filename>.
+            </para>
+
+            <para>
+                BitBake finds and applies multiple patches for a single recipe
+                in the order in which it finds the patches.
+                Patches are applied to the recipe's source files located in the
+                <link linkend='var-S'><filename>S</filename></link> directory.
+            </para>
+
+            <para>
+                For more information on how the source directories are
+                created, see the
+                "<link linkend='source-fetching-dev-environment'>Source Fetching</link>"
+                section.
+            </para>
+        </section>
+
+        <section id='configuration-and-compilation-dev-environment'>
+            <title>Configuration and Compilation</title>
+
+            <para>
+                After source code is patched, BitBake executes tasks that
+                configure and compile the source code:
+                <imagedata fileref="figures/configuration-compile-autoreconf.png" align="center" width="7in" depth="5in" />
+            </para>
+
+            <para>
+                This step in the build process consists of three tasks:
+                <itemizedlist>
+                    <listitem><para><emphasis><filename>do_configure</filename>:</emphasis>
+                        This task configures the source by enabling and
+                        disabling any build-time and configuration options for
+                        the software being built.
+                        Configurations can come from the recipe itself as well
+                        as from an inherited class.
+                        Additionally, the software itself might configure itself
+                        depending on the target for which it is being built.
+                        </para>
+
+                        <para>The configurations handled by the
+                        <filename>do_configure</filename> task are specific
+                        to source code configuration for the source code
+                        being built by the recipe.</para>
+
+                        <para>If you are using
+                        <link linkend='ref-classes-autotools'><filename>autotools.bbclass</filename></link>,
+                        you can add additional configuration options by using
+                        the <link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>
+                        variable.
+                        For information on how this variable works within
+                        that class, see the
+                        <filename>meta/classes/autotools.bbclass</filename>.
+                        </para></listitem>
+                    <listitem><para><emphasis><filename>do_compile</filename>:</emphasis>
+                        Once a configuration task has been satisfied, BitBake
+                        compiles the source using the
+                        <filename>do_compile</filename> task.
+                        Compilation occurs in the directory pointed to by the
+                        <link linkend='var-B'><filename>B</filename></link>
+                        variable.
+                        Realize that the <filename>B</filename> directory, by
+                        default, is the same as the
+                        <link linkend='var-S'><filename>S</filename></link>
+                        directory.</para></listitem>
+                    <listitem><para><emphasis><filename>do_install</filename>:</emphasis>
+                        Once compilation is done, BitBake executes the
+                        <filename>do_install</filename> task.
+                        This task copies files from the <filename>B</filename>
+                        directory and places them in a holding area pointed to
+                        by the
+                        <link linkend='var-D'><filename>D</filename></link>
+                        variable.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='package-splitting-dev-environment'>
+            <title>Package Splitting</title>
+
+            <para>
+                After source code is configured and compiled, the
+                OpenEmbedded build system analyzes
+                the results and splits the output into packages:
+                <imagedata fileref="figures/analysis-for-package-splitting.png" align="center" width="7in" depth="7in" />
+            </para>
+
+            <para>
+                The <filename>do_package</filename> and
+                <filename>do_packagedata</filename> tasks combine to analyze
+                the files found in the
+                <link linkend='var-D'><filename>D</filename></link> directory
+                and split them into subsets based on available packages and
+                files.
+                The analyzing process involves the following as well as other
+                items: splitting out debugging symbols,
+                looking at shared library dependencies between packages,
+                and looking at package relationships.
+                The <filename>do_packagedata</filename> task creates package
+                metadata based on the analysis such that the
+                OpenEmbedded build system can generate the final packages.
+                Working, staged, and intermediate results of the analysis
+                and package splitting process use these areas:
+                <itemizedlist>
+                    <listitem><para><link linkend='var-PKGD'><filename>PKGD</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PKGDESTWORK'><filename>PKGDESTWORK</filename></link>
+                        </para></listitem>
+                    <listitem><para><link linkend='var-PKGDEST'><filename>PKGDEST</filename></link>
+                        </para></listitem>
+                </itemizedlist>
+                The <link linkend='var-FILES'><filename>FILES</filename></link>
+                variable defines the files that go into each package in
+                <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
+                If you want details on how this is accomplished, you can
+                look at
+                <link linkend='ref-classes-package'><filename>package.bbclass</filename></link>.
+            </para>
+
+            <para>
+                Depending on the type of packages being created (RPM, DEB, or
+                IPK), the <filename>do_package_write_*</filename> task
+                creates the actual packages and places them in the
+                Package Feed area, which is
+                <filename>${TMPDIR}/deploy</filename>.
+                You can see the
+                "<link linkend='package-feeds-dev-environment'>Package Feeds</link>"
+                section for more detail on that part of the build process.
+                <note>
+                    Support for creating feeds directly from the
+                    <filename>deploy/*</filename> directories does not exist.
+                    Creating such feeds usually requires some kind of feed
+                    maintenance mechanism that would upload the new packages
+                    into an official package feed (e.g. the
+                    Ångström distribution).
+                    This functionality is highly distribution-specific
+                    and thus is not provided out of the box.
+                </note>
+            </para>
+        </section>
+
+        <section id='image-generation-dev-environment'>
+            <title>Image Generation</title>
+
+            <para>
+                Once packages are split and stored in the Package Feeds area,
+                the OpenEmbedded build system uses BitBake to generate the
+                root filesystem image:
+                <imagedata fileref="figures/image-generation.png" align="center" width="6in" depth="7in" />
+            </para>
+
+            <para>
+                The image generation process consists of several stages and
+                depends on many variables.
+                The <filename>do_rootfs</filename> task uses these key variables
+                to help create the list of packages to actually install:
+                <itemizedlist>
+                    <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
+                        Lists out the base set of packages to install from
+                        the Package Feeds area.</para></listitem>
+                    <listitem><para><link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>:
+                        Specifies packages that should not be installed.
+                        </para></listitem>
+                    <listitem><para><link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
+                        Specifies features to include in the image.
+                        Most of these features map to additional packages for
+                        installation.</para></listitem>
+                    <listitem><para><link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>:
+                        Specifies the package backend to use and consequently
+                        helps determine where to locate packages within the
+                        Package Feeds area.</para></listitem>
+                    <listitem><para><link linkend='var-IMAGE_LINGUAS'><filename>IMAGE_LINGUAS</filename></link>:
+                        Determines the language(s) for which additional
+                        language support packages are installed.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Package installation is under control of the package manager
+                (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
+                not package management is enabled for the target.
+                At the end of the process, if package management is not
+                enabled for the target, the package manager's data files
+                are deleted from the root filesystem.
+            </para>
+
+            <para>
+                During image generation, the build system attempts to run
+                all post installation scripts.
+                Any that fail to run on the build host are run on the
+                target when the target system is first booted.
+                If you are using a
+                <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
+                all the post installation scripts must succeed during the
+                package installation phase since the root filesystem cannot be
+                written into.
+            </para>
+
+            <para>
+                During Optimization, optimizing processes are run across
+                the image.
+                These processes include <filename>mklibs</filename> and
+                <filename>prelink</filename>.
+                The <filename>mklibs</filename> process optimizes the size
+                of the libraries.
+                A <filename>prelink</filename> process optimizes the dynamic
+                linking of shared libraries to reduce start up time of
+                executables.
+            </para>
+
+            <para>
+                Part of the image generation process includes compressing the
+                root filesystem image.
+                Compression is accomplished through several optimization
+                routines designed to reduce the overall size of the image.
+            </para>
+
+            <para>
+                After the root filesystem has been constructed, the image
+                generation process turns everything into an image file or
+                a set of image files.
+                The formats used for the root filesystem depend on the
+                <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
+                variable.
+            </para>
+
+            <note>
+                The entire image generation process is run under Pseudo.
+                Running under Pseudo ensures that the files in the root
+                filesystem have correct ownership.
+            </note>
+        </section>
+
+        <section id='sdk-generation-dev-environment'>
+            <title>SDK Generation</title>
+
+            <para>
+                The OpenEmbedded build system uses BitBake to generate the
+                Software Development Kit (SDK) installer script:
+                <imagedata fileref="figures/sdk-generation.png" align="center" width="6in" depth="7in" />
+            </para>
+
+            <note>
+                For more information on the cross-development toolchain
+                generation, see the
+                "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+                section.
+            </note>
+
+            <para>
+                Like image generation, the SDK script process consists of
+                several stages and depends on many variables.
+                The <filename>do_populate_sdk</filename> task uses these
+                key variables to help create the list of packages to actually
+                install.
+                For information on the variables listed in the figure, see the
+                "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+                section.
+            </para>
+
+            <para>
+                The <filename>do_populate_sdk</filename> task handles two
+                parts: a target part and a host part.
+                The target part is the part built for the target hardware and
+                includes libraries and headers.
+                The host part is the part of the SDK that runs on the
+                <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
+            </para>
+
+            <para>
+                Once both parts are constructed, the
+                <filename>do_populate_sdk</filename> task performs some cleanup
+                on both parts.
+                After the cleanup, the task creates a cross-development
+                environment setup script and any configuration files that
+                might be needed.
+            </para>
+
+            <para>
+                The final output of the task is the Cross-development
+                toolchain installation script (<filename>.sh</filename> file),
+                which includes the environment setup script.
+            </para>
+        </section>
+    </section>
+
+    <section id='images-dev-environment'>
+        <title>Images</title>
+
+        <para>
+            The images produced by the OpenEmbedded build system
+            are compressed forms of the
+            root filesystems that are ready to boot on a target device.
+            You can see from the
+            <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>
+            that BitBake output in part consists of images.
+            This section is going to look more closely at this output:
+            <imagedata fileref="figures/images.png" align="center" width="5.5in" depth="5.5in" />
+        </para>
+
+        <para>
+            For a list of example images that the Yocto Project provides,
+            the
+            "<link linkend='ref-images'>Images</link>" chapter.
+        </para>
+
+        <para>
+            Images are written out to the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            inside the <filename>deploy/images/&lt;machine&gt;/</filename>
+            folder as shown in the figure.
+            This folder contains any files expected to be loaded on the
+            target device.
+            The
+            <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
+            variable points to the <filename>deploy</filename> directory,
+            while the
+            <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
+            variable points to the appropriate directory containing images for
+            the current configuration.
+            <itemizedlist>
+                <listitem><para><filename>&lt;kernel-image&gt;</filename>:
+                    A kernel binary file.
+                    The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
+                    variable setting determines the naming scheme for the
+                    kernel image file.
+                    Depending on that variable, the file could begin with
+                    a variety of naming strings.
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple image files for the
+                    machine.</para></listitem>
+                <listitem><para><filename>&lt;root-filesystem-image&gt;</filename>:
+                    Root filesystems for the target device (e.g.
+                    <filename>*.ext3</filename> or <filename>*.bz2</filename>
+                    files).
+                    The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
+                    variable setting determines the root filesystem image
+                    type.
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple root filesystems for the
+                    machine.</para></listitem>
+                <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
+                    Tarballs that contain all the modules built for the kernel.
+                    Kernel module tarballs exist for legacy purposes and
+                    can be suppressed by setting the
+                    <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
+                    variable to "0".
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple kernel module tarballs
+                    for the machine.</para></listitem>
+                <listitem><para><filename>&lt;bootloaders&gt;</filename>:
+                    Bootloaders supporting the image, if applicable to the
+                    target machine.
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    directory can contain multiple bootloaders for the
+                    machine.</para></listitem>
+                <listitem><para><filename>&lt;symlinks&gt;</filename>:
+                    The <filename>deploy/images/&lt;machine&gt;</filename>
+                    folder contains
+                    a symbolic link that points to the most recently built file
+                    for each machine.
+                    These links might be useful for external scripts that
+                    need to obtain the latest version of each file.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='sdk-dev-environment'>
+        <title>Application Development SDK</title>
+
+        <para>
+            In the
+            <link linkend='general-yocto-environment-figure'>general Yocto Project Development Environment figure</link>,
+            the output labeled "Application Development SDK" represents an
+            SDK.
+            This section is going to take a closer look at this output:
+            <imagedata fileref="figures/sdk.png" align="center" width="5in" depth="4in" />
+        </para>
+
+        <para>
+            The specific form of this output is a self-extracting
+            SDK installer (<filename>*.sh</filename>) that, when run,
+            installs the SDK, which consists of a cross-development
+            toolchain, a set of libraries and headers, and an SDK
+            environment setup script.
+            Running this installer essentially sets up your
+            cross-development environment.
+            You can think of the cross-toolchain as the "host"
+            part because it runs on the SDK machine.
+            You can think of the libraries and headers as the "target"
+            part because they are built for the target hardware.
+            The setup script is added so that you can initialize the
+            environment before using the tools.
+        </para>
+
+        <note>
+            <para>
+                The Yocto Project supports several methods by which you can
+                set up this cross-development environment.
+                These methods include downloading pre-built SDK installers,
+                building and installing your own SDK installer, or running
+                an Application Development Toolkit (ADT) installer to
+                install not just cross-development toolchains
+                but also additional tools to help in this type of
+                development.
+            </para>
+
+            <para>
+                For background information on cross-development toolchains
+                in the Yocto Project development environment, see the
+                "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+                section.
+                For information on setting up a cross-development
+                environment, see the
+                "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
+                section in the Yocto Project Application Developer's Guide.
+            </para>
+        </note>
+
+        <para>
+            Once built, the SDK installers are written out to the
+            <filename>deploy/sdk</filename> folder inside the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            as shown in the figure at the beginning of this section.
+            Several variables exist that help configure these files:
+            <itemizedlist>
+                <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
+                    Points to the <filename>deploy</filename>
+                    directory.</para></listitem>
+                <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
+                    Specifies the architecture of the machine
+                    on which the cross-development tools are run to
+                    create packages for the target hardware.
+                    </para></listitem>
+                <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
+                    Lists the features to include in the "target" part
+                    of the SDK.
+                    </para></listitem>
+                <listitem><para><link linkend='var-TOOLCHAIN_HOST_TASK'><filename>TOOLCHAIN_HOST_TASK</filename></link>:
+                    Lists packages that make up the host
+                    part of the SDK (i.e. the part that runs on
+                    the <filename>SDKMACHINE</filename>).
+                    When you use
+                    <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>
+                    to create the SDK, a set of default packages
+                    apply.
+                    This variable allows you to add more packages.
+                    </para></listitem>
+                <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASK'><filename>TOOLCHAIN_TARGET_TASK</filename></link>:
+                    Lists packages that make up the target part
+                    of the SDK (i.e. the part built for the
+                    target hardware).
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb
new file mode 100644
index 0000000000..5dfb0b30cf
--- /dev/null
+++ b/documentation/ref-manual/examples/hello-autotools/hello_2.3.bb
@@ -0,0 +1,8 @@
+DESCRIPTION = "GNU Helloworld application"
+SECTION = "examples"
+LICENSE = "GPLv3"
+LIC_FILES_CHKSUM = "file://COPYING;md5=adefda309052235aa5d1e99ce7557010"
+
+SRC_URI = "${GNU_MIRROR}/hello/hello-${PV}.tar.bz2"
+
+inherit autotools
diff --git a/documentation/ref-manual/examples/hello-single/files/helloworld.c b/documentation/ref-manual/examples/hello-single/files/helloworld.c
new file mode 100644
index 0000000000..fc7169b7b8
--- /dev/null
+++ b/documentation/ref-manual/examples/hello-single/files/helloworld.c
@@ -0,0 +1,8 @@
+#include <stdio.h>
+
+int main(void)
+{
+        printf("Hello world!\n");
+
+        return 0;
+}
diff --git a/documentation/ref-manual/examples/hello-single/hello.bb b/documentation/ref-manual/examples/hello-single/hello.bb
new file mode 100644
index 0000000000..0812743e39
--- /dev/null
+++ b/documentation/ref-manual/examples/hello-single/hello.bb
@@ -0,0 +1,17 @@
+DESCRIPTION = "Simple helloworld application"
+SECTION = "examples"
+LICENSE = "MIT"
+LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
+
+SRC_URI = "file://helloworld.c"
+
+S = "${WORKDIR}"
+
+do_compile() {
+        ${CC} helloworld.c -o helloworld
+}
+
+do_install() {
+        install -d ${D}${bindir}
+        install -m 0755 helloworld ${D}${bindir}
+}
diff --git a/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb
new file mode 100644
index 0000000000..b58d4d7bd1
--- /dev/null
+++ b/documentation/ref-manual/examples/libxpm/libxpm_3.5.6.bb
@@ -0,0 +1,14 @@
+require xorg-lib-common.inc
+
+DESCRIPTION = "X11 Pixmap library"
+LICENSE = "X-BSD"
+LIC_FILES_CHKSUM = "file://COPYING;md5=3e07763d16963c3af12db271a31abaa5"
+DEPENDS += "libxext"
+PR = "r2"
+PE = "1"
+
+XORG_PN = "libXpm"
+
+PACKAGES =+ "sxpm cxpm"
+FILES_cxpm = "${bindir}/cxpm"
+FILES_sxpm = "${bindir}/sxpm"
diff --git a/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
new file mode 100644
index 0000000000..5d05a437a4
--- /dev/null
+++ b/documentation/ref-manual/examples/mtd-makefile/mtd-utils_1.0.0.bb
@@ -0,0 +1,15 @@
+DESCRIPTION = "Tools for managing memory technology devices."
+SECTION = "base"
+DEPENDS = "zlib"
+HOMEPAGE = "http://www.linux-mtd.infradead.org/"
+LICENSE = "GPLv2"
+LIC_FILES_CHKSUM = "file://COPYING;md5=0636e73ff0215e8d672dc4c32c317bb3 \
+                    file://include/common.h;beginline=1;endline=17;md5=ba05b07912a44ea2bf81ce409380049c"
+
+SRC_URI = "ftp://ftp.infradead.org/pub/mtd-utils/mtd-utils-${PV}.tar.gz"
+
+CFLAGS_prepend = "-I ${S}/include "
+
+do_install() {
+        oe_runmake install DESTDIR=${D}
+}
diff --git a/documentation/ref-manual/faq.xml b/documentation/ref-manual/faq.xml
new file mode 100644
index 0000000000..69b679bbf7
--- /dev/null
+++ b/documentation/ref-manual/faq.xml
@@ -0,0 +1,710 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='faq'>
+<title>FAQ</title>
+<qandaset>
+    <qandaentry>
+        <question>
+            <para>
+                How does Poky differ from <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The term "<ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>"
+                refers to the specific reference build system that
+                the Yocto Project provides.
+                Poky is based on <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink>
+                and <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>.
+                Thus, the generic term used here for the build system is
+                the "OpenEmbedded build system."
+                Development in the Yocto Project using Poky is closely tied to OpenEmbedded, with
+                changes always being merged to OE-Core or BitBake first before being pulled back
+                into Poky.
+                This practice benefits both projects immediately.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                I only have Python 2.4 or 2.5 but BitBake requires Python 2.6 or 2.7.
+                Can I still use the Yocto Project?
+            </para>
+        </question>
+        <answer>
+            <para>
+                You can use a stand-alone tarball to provide Python 2.6.
+                You can find pre-built 32 and 64-bit versions of Python 2.6 at the following locations:
+                <itemizedlist>
+                    <listitem><para><ulink url='&YOCTO_PYTHON-i686_DL_URL;'>32-bit tarball</ulink></para></listitem>
+                    <listitem><para><ulink url='&YOCTO_PYTHON-x86_64_DL_URL;'>64-bit tarball</ulink></para></listitem>
+                </itemizedlist>
+            </para>
+            <para>
+                These tarballs are self-contained with all required libraries and should work
+                on most Linux systems.
+                To use the tarballs extract them into the root
+                directory and run the appropriate command:
+                <literallayout class='monospaced'>
+     $ export PATH=/opt/poky/sysroots/i586-pokysdk-linux/usr/bin/:$PATH
+     $ export PATH=/opt/poky/sysroots/x86_64-pokysdk-linux/usr/bin/:$PATH
+                </literallayout>
+            </para>
+            <para>
+                Once you run the command, BitBake uses Python 2.6.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How can you claim Poky / OpenEmbedded-Core is stable?
+            </para>
+        </question>
+        <answer>
+            <para>
+                There are three areas that help with stability;
+                <itemizedlist>
+                    <listitem><para>The Yocto Project team keeps
+                        <ulink url='&YOCTO_DOCS_DEV_URL;#oe-core'>OE-Core</ulink> small
+                        and focused, containing around 830 recipes as opposed to the thousands
+                        available in other OpenEmbedded community layers.
+                        Keeping it small makes it easy to test and maintain.</para></listitem>
+                    <listitem><para>The Yocto Project team runs manual and automated tests
+                        using a small, fixed set of reference hardware as well as emulated
+                        targets.</para></listitem>
+                    <listitem><para>The Yocto Project uses an autobuilder,
+                        which provides continuous build and integration tests.</para></listitem>
+                </itemizedlist>
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I get support for my board added to the Yocto Project?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Support for an additional board is added by creating a
+                Board Support Package (BSP) layer for it.
+                For more information on how to create a BSP layer, see the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and Creating Layers</ulink>"
+                section in the Yocto Project Development Manual and the
+                <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+            </para>
+            <para>
+                Usually, if the board is not completely exotic, adding support in
+                the Yocto Project is fairly straightforward.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                Are there any products built using the OpenEmbedded build system?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The software running on the <ulink url='http://vernier.com/labquest/'>Vernier LabQuest</ulink>
+                is built using the OpenEmbedded build system.
+                See the <ulink url='http://www.vernier.com/products/interfaces/labq/'>Vernier LabQuest</ulink>
+                website for more information.
+                There are a number of pre-production devices using the OpenEmbedded build system
+                and the Yocto Project team
+                announces them as soon as they are released.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                What does the OpenEmbedded build system produce as output?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Because you can use the same set of recipes to create output of
+                various formats, the output of an OpenEmbedded build depends on
+                how you start it.
+                Usually, the output is a flashable image ready for the target
+                device.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I add my package to the Yocto Project?
+            </para>
+        </question>
+        <answer>
+            <para>
+                To add a package, you need to create a BitBake recipe.
+                For information on how to add a package, see the section
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg'>Writing a Recipe to Add a Package to Your Image</ulink>"
+                in the Yocto Project Development Manual.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                Do I have to reflash my entire board with a new Yocto Project image when recompiling
+                a package?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The OpenEmbedded build system can build packages in various
+                formats such as IPK for OPKG, Debian package
+                (<filename>.deb</filename>), or RPM.
+                You can then upgrade the packages using the package tools on
+                the device, much like on a desktop distribution such as
+                Ubuntu or Fedora.
+                However, package management on the target is entirely optional.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                What is GNOME Mobile and what is the difference between GNOME Mobile and GNOME?
+            </para>
+        </question>
+        <answer>
+            <para>
+                GNOME Mobile is a subset of the <ulink url='http://www.gnome.org'>GNOME</ulink>
+                platform targeted at mobile and embedded devices.
+                The main difference between GNOME Mobile and standard GNOME is that
+                desktop-orientated libraries have been removed, along with deprecated libraries,
+                creating a much smaller footprint.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                I see the error '<filename>chmod: XXXXX new permissions are r-xrwxrwx, not r-xr-xr-x</filename>'.
+                What is wrong?
+            </para>
+        </question>
+        <answer>
+            <para>
+                You are probably running the build on an NTFS filesystem.
+                Use <filename>ext2</filename>, <filename>ext3</filename>, or <filename>ext4</filename> instead.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I make the Yocto Project work in RHEL/CentOS?
+            </para>
+        </question>
+        <answer>
+            <para>
+                To get the Yocto Project working under RHEL/CentOS 5.1 you need to first
+                install some required packages.
+                The standard CentOS packages needed are:
+                <itemizedlist>
+                    <listitem><para>"Development tools" (selected during installation)</para></listitem>
+                    <listitem><para><filename>texi2html</filename></para></listitem>
+                    <listitem><para><filename>compat-gcc-34</filename></para></listitem>
+                </itemizedlist>
+                On top of these, you need the following external packages:
+                <itemizedlist>
+                    <listitem><para><filename>python-sqlite2</filename> from
+                        <ulink url='http://dag.wieers.com/rpm/packages/python-sqlite2/'>DAG repository</ulink>
+                        </para></listitem>
+                    <listitem><para><filename>help2man</filename> from
+                        <ulink url='http://centos.karan.org/el4/extras/stable/x86_64/RPMS/repodata/repoview/help2man-0-1.33.1-2.html'>Karan repository</ulink></para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Once these packages are installed, the OpenEmbedded build system will be able
+                to build standard images.
+                However, there might be a problem with the QEMU emulator segfaulting.
+                You can either disable the generation of binary locales by setting
+                <filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>ENABLE_BINARY_LOCALE_GENERATION</link>
+                </filename> to "0" or by removing the <filename>linux-2.6-execshield.patch</filename>
+                from the kernel and rebuilding it since that is the patch that causes the problems with QEMU.
+            </para>
+
+            <note>
+                <para>For information on distributions that the Yocto Project
+                uses during validation, see the
+                <ulink url='&YOCTO_WIKI_URL;/wiki/Distribution_Support'>Distribution Support</ulink>
+                Wiki page.</para>
+                <para>For notes about using the Yocto Project on a RHEL 4-based
+                host, see the
+                <ulink url='&YOCTO_WIKI_URL;/wiki/BuildingOnRHEL4'>Building on RHEL4</ulink>
+                Wiki page.</para>
+            </note>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                I see lots of 404 responses for files on
+                <filename>&YOCTO_HOME_URL;/sources/*</filename>. Is something wrong?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Nothing is wrong.
+                The OpenEmbedded build system checks any configured source mirrors before downloading
+                from the upstream sources.
+                The build system does this searching for both source archives and
+                pre-checked out versions of SCM-managed software.
+                These checks help in large installations because it can reduce load on the SCM servers
+                themselves.
+                The address above is one of the default mirrors configured into the
+                build system.
+                Consequently, if an upstream source disappears, the team
+                can place sources there so builds continue to work.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                I have machine-specific data in a package for one machine only but the package is
+                being marked as machine-specific in all cases, how do I prevent this?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Set <filename><link linkend='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'>SRC_URI_OVERRIDES_PACKAGE_ARCH</link>
+                </filename> = "0" in the <filename>.bb</filename> file but make sure the package is
+                manually marked as
+                machine-specific for the case that needs it.
+                The code that handles
+                <filename>SRC_URI_OVERRIDES_PACKAGE_ARCH</filename> is in
+                the <filename>meta/classes/base.bbclass</filename> file.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                I'm behind a firewall and need to use a proxy server. How do I do that?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Most source fetching by the OpenEmbedded build system is done by <filename>wget</filename>
+                and you therefore need to specify the proxy settings in a
+                <filename>.wgetrc</filename> file in your home directory.
+                Here are some example settings:
+                <literallayout class='monospaced'>
+     http_proxy = http://proxy.yoyodyne.com:18023/
+     ftp_proxy = http://proxy.yoyodyne.com:18023/
+                </literallayout>
+                The Yocto Project also includes a
+                <filename>site.conf.sample</filename> file that shows how to
+                configure CVS and Git proxy servers if needed.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                What’s the difference between <filename>foo</filename> and <filename>foo-native</filename>?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The <filename>*-native</filename> targets are designed to run on the system
+                being used for the build.
+                These are usually tools that are needed to assist the build in some way such as
+                <filename>quilt-native</filename>, which is used to apply patches.
+                The non-native version is the one that runs on the target device.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                I'm seeing random build failures. Help?!
+            </para>
+        </question>
+        <answer>
+            <para>
+                If the same build is failing in totally different and random
+                ways, the most likely explanation is:
+                <itemizedlist>
+                    <listitem><para>The hardware you are running the build on
+                        has some problem.</para></listitem>
+                    <listitem><para>You are running the build under
+                        virtualization, in which case the virtualization
+                        probably has bugs.</para></listitem>
+                </itemizedlist>
+                The OpenEmbedded build system processes a massive amount of
+                data that causes lots of network, disk and CPU activity and
+                is sensitive to even single-bit failures in any of these areas.
+                True random failures have always been traced back to hardware
+                or virtualization issues.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                What do we need to ship for license compliance?
+            </para>
+        </question>
+        <answer>
+            <para>
+                This is a difficult question and you need to consult your lawyer
+                for the answer for your specific case.
+                It is worth bearing in mind that for GPL compliance, there needs
+                to be enough information shipped to allow someone else to
+                rebuild and produce the same end result you are shipping.
+                This means sharing the source code, any patches applied to it,
+                and also any configuration information about how that package
+                was configured and built.
+            </para>
+
+            <para>
+                You can find more information on licensing in the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#licensing'>Licensing</ulink>"
+                and "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+                sections, both of which are in the Yocto Project Development
+                Manual.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I disable the cursor on my touchscreen device?
+            </para>
+        </question>
+        <answer>
+            <para>
+                You need to create a form factor file as described in the
+                "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
+                section in the Yocto Project Board Support Packages (BSP)
+                Developer's Guide.
+                Set the <filename>HAVE_TOUCHSCREEN</filename> variable equal to
+                one as follows:
+                <literallayout class='monospaced'>
+     HAVE_TOUCHSCREEN=1
+                </literallayout>
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I make sure connected network interfaces are brought up by default?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The default interfaces file provided by the netbase recipe does not
+                automatically bring up network interfaces.
+                Therefore, you will need to add a BSP-specific netbase that includes an interfaces
+                file.
+                See the "<ulink url='&YOCTO_DOCS_BSP_URL;#bsp-filelayout-misc-recipes'>Miscellaneous BSP-Specific Recipe Files</ulink>"
+                section in the Yocto Project Board Support Packages (BSP)
+                Developer's Guide for information on creating these types of
+                miscellaneous recipe files.
+            </para>
+            <para>
+                For example, add the following files to your layer:
+                <literallayout class='monospaced'>
+     meta-MACHINE/recipes-bsp/netbase/netbase/MACHINE/interfaces
+     meta-MACHINE/recipes-bsp/netbase/netbase_5.0.bbappend
+                </literallayout>
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I create images with more free space?
+            </para>
+        </question>
+        <answer>
+            <para>
+                By default, the OpenEmbedded build system creates images
+                that are 1.3 times the size of the populated root filesystem.
+                To affect the image size, you need to set various
+                configurations:
+                <itemizedlist>
+                    <listitem><para><emphasis>Image Size:</emphasis>
+                        The OpenEmbedded build system uses the
+                        <link linkend='var-IMAGE_ROOTFS_SIZE'><filename>IMAGE_ROOTFS_SIZE</filename></link>
+                        variable to define the size of the image in Kbytes.
+                        The build system determines the size by taking into
+                        account the initial root filesystem size before any
+                        modifications such as requested size for the image and
+                        any requested additional free disk space to be
+                        added to the image.</para></listitem>
+                    <listitem><para><emphasis>Overhead:</emphasis>
+                        Use the
+                        <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
+                        variable to define the multiplier that the build system
+                        applies to the initial image size, which is 1.3 by
+                        default.</para></listitem>
+                    <listitem><para><emphasis>Additional Free Space:</emphasis>
+                        Use the
+                        <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
+                        variable to add additional free space to the image.
+                        The build system adds this space to the image after
+                        it determines its
+                        <filename>IMAGE_ROOTFS_SIZE</filename>.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                Why don't you support directories with spaces in the pathnames?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The Yocto Project team has tried to do this before but too
+                many of the tools the OpenEmbedded build system depends on,
+                such as <filename>autoconf</filename>, break when they find
+                spaces in pathnames.
+                Until that situation changes, the team will not support spaces
+                in pathnames.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                How do I use an external toolchain?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The toolchain configuration is very flexible and customizable.
+                It is primarily controlled with the
+                <filename><link linkend='var-TCMODE'>TCMODE</link></filename>
+                variable.
+                This variable controls which <filename>tcmode-*.inc</filename>
+                file to include from the
+                <filename>meta/conf/distro/include</filename> directory within
+                the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            </para>
+
+            <para>
+                The default value of <filename>TCMODE</filename> is "default"
+                (i.e. <filename>tcmode-default.inc</filename>).
+                However, other patterns are accepted.
+                In particular, "external-*" refers to external toolchains of
+                which there are some basic examples included in the
+                OpenEmbedded Core (<filename>meta</filename>).
+                You can use your own custom toolchain definition in your own
+                layer (or as defined in the <filename>local.conf</filename>
+                file) at the location
+                <filename>conf/distro/include/tcmode-*.inc</filename>.
+            </para>
+
+            <para>
+                In addition to the toolchain configuration, you also need a
+                corresponding toolchain recipe file.
+                This recipe file needs to package up any pre-built objects in
+                the toolchain such as <filename>libgcc</filename>,
+                <filename>libstdcc++</filename>, any locales, and
+                <filename>libc</filename>.
+                An example is the
+                <filename>external-sourcery-toolchain.bb</filename>, which is
+                located in <filename>meta/recipes-core/meta/</filename> within
+                the Source Directory.
+            </para>
+
+            <para>
+                For information on installing and using cross-development
+                toolchains, see the
+                "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
+                section in the Yocto Project Application Developer's Guide.
+                For general information on cross-development toolchains, see
+                the
+                "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+                section.
+            </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para id='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>
+                How does the OpenEmbedded build system obtain source code and
+                will it work behind my firewall or proxy server?
+            </para>
+        </question>
+        <answer>
+            <para>
+                The way the build system obtains source code is highly
+                configurable.
+                You can setup the build system to get source code in most
+                environments if HTTP transport is available.
+            </para>
+            <para>
+                When the build system searches for source code, it first
+                tries the local download directory.
+                If that location fails, Poky tries
+                <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
+                the upstream source, and then
+                <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
+                in that order.
+            </para>
+            <para>
+                Assuming your distribution is "poky", the OpenEmbedded build
+                system uses the Yocto Project source
+                <filename>PREMIRRORS</filename> by default for SCM-based
+                sources, upstreams for normal tarballs, and then falls back
+                to a number of other mirrors including the Yocto Project
+                source mirror if those fail.
+            </para>
+            <para>
+                As an example, you could add a specific server for the
+                build system to attempt before any others by adding something
+                like the following to the <filename>local.conf</filename>
+                configuration file:
+                <literallayout class='monospaced'>
+     PREMIRRORS_prepend = "\
+     git://.*/.* http://www.yoctoproject.org/sources/ \n \
+     ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+     http://.*/.* http://www.yoctoproject.org/sources/ \n \
+     https://.*/.* http://www.yoctoproject.org/sources/ \n"
+                </literallayout>
+            </para>
+            <para>
+                These changes cause the build system to intercept Git, FTP,
+                HTTP, and HTTPS requests and direct them to the
+                <filename>http://</filename> sources mirror.
+                You can use <filename>file://</filename> URLs to point to
+                local directories or network shares as well.
+            </para>
+            <para>
+                Aside from the previous technique, these options also exist:
+                <literallayout class='monospaced'>
+     BB_NO_NETWORK = "1"
+                </literallayout>
+                 This statement tells BitBake to issue an error instead of
+                 trying to access the Internet.
+                 This technique is useful if you want to ensure code builds
+                 only from local sources.
+             </para>
+             <para>
+                 Here is another technique:
+                 <literallayout class='monospaced'>
+     BB_FETCH_PREMIRRORONLY = "1"
+                 </literallayout>
+                 This statement limits the build system to pulling source
+                 from the <filename>PREMIRRORS</filename> only.
+                 Again, this technique is useful for reproducing builds.
+             </para>
+             <para>
+                 Here is another technique:
+                 <literallayout class='monospaced'>
+     BB_GENERATE_MIRROR_TARBALLS = "1"
+                 </literallayout>
+                 This statement tells the build system to generate mirror
+                 tarballs.
+                 This technique is useful if you want to create a mirror server.
+                 If not, however, the technique can simply waste time during
+                 the build.
+             </para>
+             <para>
+                 Finally, consider an example where you are behind an
+                 HTTP-only firewall.
+                 You could make the following changes to the
+                 <filename>local.conf</filename> configuration file as long as
+                 the <filename>PREMIRRORS</filename> server is current:
+                 <literallayout class='monospaced'>
+     PREMIRRORS_prepend = "\
+     ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+     http://.*/.* http://www.yoctoproject.org/sources/ \n \
+     https://.*/.* http://www.yoctoproject.org/sources/ \n"
+     BB_FETCH_PREMIRRORONLY = "1"
+                 </literallayout>
+                 These changes would cause the build system to successfully
+                 fetch source over HTTP and any network accesses to anything
+                 other than the <filename>PREMIRRORS</filename> would fail.
+             </para>
+             <para>
+                 The build system also honors the standard shell environment
+                 variables <filename>http_proxy</filename>,
+                 <filename>ftp_proxy</filename>,
+                 <filename>https_proxy</filename>, and
+                 <filename>all_proxy</filename> to redirect requests through
+                 proxy servers.
+             </para>
+        </answer>
+    </qandaentry>
+
+    <qandaentry>
+        <question>
+            <para>
+                Can I get rid of build output so I can start over?
+            </para>
+        </question>
+        <answer>
+            <para>
+                Yes - you can easily do this.
+                When you use BitBake to build an image, all the build output
+                goes into the directory created when you run the 
+                build environment setup script (i.e.
+                <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+                or
+                <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+                By default, this <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                is named <filename>build</filename> but can be named
+                anything you want.
+            </para>
+
+            <para>
+                Within the Build Directory, is the <filename>tmp</filename>
+                directory.
+                To remove all the build output yet preserve any source code or
+                downloaded files from previous builds, simply remove the
+                <filename>tmp</filename> directory.
+            </para>
+        </answer>
+    </qandaentry>
+
+
+</qandaset>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/figures/analysis-for-package-splitting.png b/documentation/ref-manual/figures/analysis-for-package-splitting.png
new file mode 100644
index 0000000000..04f2794ea9
--- /dev/null
+++ b/documentation/ref-manual/figures/analysis-for-package-splitting.png
diff --git a/documentation/ref-manual/figures/buildhistory-web.png b/documentation/ref-manual/figures/buildhistory-web.png
new file mode 100644
index 0000000000..f6db86c977
--- /dev/null
+++ b/documentation/ref-manual/figures/buildhistory-web.png
diff --git a/documentation/ref-manual/figures/buildhistory.png b/documentation/ref-manual/figures/buildhistory.png
new file mode 100644
index 0000000000..edf98d95cf
--- /dev/null
+++ b/documentation/ref-manual/figures/buildhistory.png
diff --git a/documentation/ref-manual/figures/configuration-compile-autoreconf.png b/documentation/ref-manual/figures/configuration-compile-autoreconf.png
new file mode 100644
index 0000000000..a07464f04c
--- /dev/null
+++ b/documentation/ref-manual/figures/configuration-compile-autoreconf.png
diff --git a/documentation/ref-manual/figures/cross-development-toolchains.png b/documentation/ref-manual/figures/cross-development-toolchains.png
new file mode 100644
index 0000000000..d36670a198
--- /dev/null
+++ b/documentation/ref-manual/figures/cross-development-toolchains.png
diff --git a/documentation/ref-manual/figures/image-generation.png b/documentation/ref-manual/figures/image-generation.png
new file mode 100644
index 0000000000..5594658200
--- /dev/null
+++ b/documentation/ref-manual/figures/image-generation.png
diff --git a/documentation/ref-manual/figures/images.png b/documentation/ref-manual/figures/images.png
new file mode 100644
index 0000000000..d99eac1fbf
--- /dev/null
+++ b/documentation/ref-manual/figures/images.png
diff --git a/documentation/ref-manual/figures/layer-input.png b/documentation/ref-manual/figures/layer-input.png
new file mode 100644
index 0000000000..0a4f2e74f3
--- /dev/null
+++ b/documentation/ref-manual/figures/layer-input.png
diff --git a/documentation/ref-manual/figures/package-feeds.png b/documentation/ref-manual/figures/package-feeds.png
new file mode 100644
index 0000000000..4bc311f3d6
--- /dev/null
+++ b/documentation/ref-manual/figures/package-feeds.png
diff --git a/documentation/ref-manual/figures/patching.png b/documentation/ref-manual/figures/patching.png
new file mode 100644
index 0000000000..8ecd018502
--- /dev/null
+++ b/documentation/ref-manual/figures/patching.png
diff --git a/documentation/ref-manual/figures/poky-title.png b/documentation/ref-manual/figures/poky-title.png
new file mode 100644
index 0000000000..2893d84620
--- /dev/null
+++ b/documentation/ref-manual/figures/poky-title.png
diff --git a/documentation/ref-manual/figures/sdk-generation.png b/documentation/ref-manual/figures/sdk-generation.png
new file mode 100644
index 0000000000..c37e2748ca
--- /dev/null
+++ b/documentation/ref-manual/figures/sdk-generation.png
diff --git a/documentation/ref-manual/figures/sdk.png b/documentation/ref-manual/figures/sdk.png
new file mode 100644
index 0000000000..a539cc52f0
--- /dev/null
+++ b/documentation/ref-manual/figures/sdk.png
diff --git a/documentation/ref-manual/figures/source-fetching.png b/documentation/ref-manual/figures/source-fetching.png
new file mode 100644
index 0000000000..26aefb50c2
--- /dev/null
+++ b/documentation/ref-manual/figures/source-fetching.png
diff --git a/documentation/ref-manual/figures/source-input.png b/documentation/ref-manual/figures/source-input.png
new file mode 100644
index 0000000000..f7515058ef
--- /dev/null
+++ b/documentation/ref-manual/figures/source-input.png
diff --git a/documentation/ref-manual/figures/user-configuration.png b/documentation/ref-manual/figures/user-configuration.png
new file mode 100644
index 0000000000..f2b3f8e7fe
--- /dev/null
+++ b/documentation/ref-manual/figures/user-configuration.png
diff --git a/documentation/ref-manual/figures/yocto-environment-ref.png b/documentation/ref-manual/figures/yocto-environment-ref.png
new file mode 100644
index 0000000000..650c6c8030
--- /dev/null
+++ b/documentation/ref-manual/figures/yocto-environment-ref.png
diff --git a/documentation/ref-manual/introduction.xml b/documentation/ref-manual/introduction.xml
new file mode 100644
index 0000000000..b1a5c0e175
--- /dev/null
+++ b/documentation/ref-manual/introduction.xml
@@ -0,0 +1,444 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='intro'>
+<title>Introduction</title>
+
+<section id='intro-welcome'>
+    <title>Introduction</title>
+
+    <para>
+        This manual provides reference information for the current release of the Yocto Project.
+        The Yocto Project is an open-source collaboration project focused on embedded Linux
+        developers.
+        Amongst other things, the Yocto Project uses the OpenEmbedded build system, which
+        is based on the Poky project, to construct complete Linux images.
+        You can find complete introductory and getting started information on the Yocto Project
+        by reading the
+        <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>.
+        For task-based information using the Yocto Project, see the
+        <ulink url='&YOCTO_DOCS_DEV_URL;'>Yocto Project Development Manual</ulink>
+        and the <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;'>Yocto Project Linux Kernel Development Manual</ulink>.
+        For Board Support Package (BSP) structure information, see the
+        <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support Package (BSP) Developer's Guide</ulink>.
+        You can also find lots of Yocto Project information on the
+        <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>.
+    </para>
+</section>
+
+<section id='intro-manualoverview'>
+    <title>Documentation Overview</title>
+    <para>
+        This reference manual consists of the following:
+        <itemizedlist>
+            <listitem><para><emphasis>
+                <link linkend='usingpoky'>Using the Yocto Project</link>:</emphasis>
+                Provides an overview of the components that make up the Yocto Project
+                followed by information about debugging images created in the Yocto Project.
+                </para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='technical-details'>Technical Details</link>:</emphasis>
+                Describes fundamental Yocto Project components as well as an explanation
+                behind how the Yocto Project uses shared state (sstate) cache to speed build time.
+                </para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='ref-structure'>Directory Structure</link>:</emphasis>
+                Describes the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> created
+                either by unpacking a released Yocto Project tarball on your host development system,
+                or by cloning the upstream
+                <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
+                </para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='ref-bitbake'>BitBake</link>:</emphasis>
+                Provides an overview of the BitBake tool and its role within
+                the Yocto Project.</para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='ref-classes'>Classes</link>:</emphasis>
+                Describes the classes used in the Yocto Project.</para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='ref-images'>Images</link>:</emphasis>
+                Describes the standard images that the Yocto Project supports.
+                </para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='ref-features'>Features</link>:</emphasis>
+                Describes mechanisms for creating distribution, machine, and image
+                features during the build process using the OpenEmbedded build system.</para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='ref-variables-glos'>Variables Glossary</link>:</emphasis>
+                Presents most variables used by the OpenEmbedded build system, which
+                uses BitBake.
+                Entries describe the function of the variable and how to apply them.
+                </para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='ref-varlocality'>Variable Context</link>:</emphasis>
+                Provides variable locality or context.</para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='faq'>FAQ</link>:</emphasis>
+                Provides answers for commonly asked questions in the Yocto Project
+                development environment.</para></listitem>
+            <listitem><para><emphasis>
+                <link linkend='resources'>Contributing to the Yocto Project</link>:</emphasis>
+                Provides guidance on how you can contribute back to the Yocto
+                Project.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+
+<section id='intro-requirements'>
+<title>System Requirements</title>
+    <para>
+        For general Yocto Project system requirements, see the
+        "<ulink url='&YOCTO_DOCS_QS_URL;#yp-resources'>What You Need and How You Get It</ulink>" section
+        in the Yocto Project Quick Start.
+        The remainder of this section provides details on system requirements
+        not covered in the Yocto Project Quick Start.
+    </para>
+
+    <section id='detailed-supported-distros'>
+        <title>Supported Linux Distributions</title>
+
+        <para>
+            Currently, the Yocto Project is supported on the following
+            distributions:
+            <note>
+                <para>
+                    Yocto Project releases are tested against the stable Linux
+                    distributions in the following list.
+                    The Yocto Project should work on other distributions but
+                    validation is not performed against them.
+                </para>
+
+                <para>
+                    In particular, the Yocto Project does not support
+                    and currently has no plans to support
+                    rolling-releases or development distributions due to their
+                    constantly changing nature.
+                    We welcome patches and bug reports, but keep in mind that
+                    our priority is on the supported platforms listed below.
+                </para>
+
+                <para>
+                    Refer to
+                    <ulink url='&OE_HOME_URL;/index.php?title=OEandYourDistro'>OE and Your Distro</ulink> and
+                    <ulink url='&OE_HOME_URL;/index.php?title=Required_software'>Required Software</ulink>
+                    for information for information about dependencies and
+                    requirements.
+                    If you encounter problems, please go to
+                    <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
+                    and submit a bug.
+                    We are interested in hearing about your experience.
+                </para>
+            </note>
+            <itemizedlist>
+<!--                <listitem><para>Ubuntu 10.04</para></listitem>
+                <listitem><para>Ubuntu 11.10</para></listitem> -->
+                <listitem><para>Ubuntu 12.04 (LTS)</para></listitem>
+                <listitem><para>Ubuntu 12.10</para></listitem>
+                <listitem><para>Ubuntu 13.04</para></listitem>
+<!--                <listitem><para>Fedora 16 (Verne)</para></listitem>
+                <listitem><para>Fedora 17 (Spherical)</para></listitem> -->
+                <listitem><para>Fedora release 18 (Spherical Cow)</para></listitem>
+                <listitem><para>Fedora release 19 (Schrödinger's Cat)</para></listitem>
+<!--                <listitem><para>CentOS release 5.6 (Final)</para></listitem>
+                <listitem><para>CentOS release 5.7 (Final)</para></listitem>
+                <listitem><para>CentOS release 5.8 (Final)</para></listitem>
+                <listitem><para>CentOS release 6.3 (Final)</para></listitem> -->
+                <listitem><para>CentOS release 6.4</para></listitem>
+<!--                <listitem><para>Debian GNU/Linux 6.0 (Squeeze)</para></listitem> -->
+                <listitem><para>Debian GNU/Linux 6.0.7 (Squeeze)</para></listitem>
+                <listitem><para>Debian GNU/Linux 7.0 (Wheezy)</para></listitem>
+                <listitem><para>Debian GNU/Linux 7.1 (Wheezy)</para></listitem>
+<!--                <listitem><para>openSUSE 11.4</para></listitem>
+                <listitem><para>openSUSE 12.1</para></listitem> -->
+                <listitem><para>openSUSE 12.2</para></listitem>
+                <listitem><para>openSUSE 12.3</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <note>
+            While the Yocto Project Team attempts to ensure all Yocto Project
+            releases are one hundred percent compatible with each officially
+            supported Linux distribution, instances might exist where you
+            encounter a problem while using the Yocto Project on a specific
+            distribution.
+            For example, the CentOS 6.4 distribution does not include the
+            Gtk+ 2.20.0 and PyGtk 2.21.0 (or higher) packages, which are
+            required to run
+            <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob</ulink>.
+        </note>
+    </section>
+
+    <section id='required-packages-for-the-host-development-system'>
+    <title>Required Packages for the Host Development System</title>
+
+        <para>
+            The list of packages you need on the host development system can
+            be large when covering all build scenarios using the Yocto Project.
+            This section provides required packages according to
+            Linux distribution and function.
+        </para>
+
+        <section id='ubuntu-packages'>
+            <title>Ubuntu and Debian</title>
+
+            <para>
+                The following list shows the required packages by function
+                given a supported Ubuntu or Debian Linux distribution:
+                <itemizedlist>
+                    <listitem><para><emphasis>Essentials:</emphasis>
+                        Packages needed to build an image on a headless
+                        system:
+                        <literallayout class='monospaced'>
+     $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL;
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Graphical Extras:</emphasis>
+                        Packages recommended if the host system has graphics support:
+                        <literallayout class='monospaced'>
+     $ sudo apt-get install libsdl1.2-dev xterm
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Documentation:</emphasis>
+                        Packages needed if you are going to build out the
+                        Yocto Project documentation manuals:
+                        <literallayout class='monospaced'>
+     $ sudo apt-get install make xsltproc docbook-utils fop dblatex xmlto
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>ADT Installer Extras:</emphasis>
+                        Packages needed if you are going to be using the
+                        <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
+                        <literallayout class='monospaced'>
+     $ sudo apt-get install autoconf automake libtool libglib2.0-dev
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='fedora-packages'>
+            <title>Fedora Packages</title>
+
+            <para>
+                The following list shows the required packages by function
+                given a supported Fedora Linux distribution:
+                <itemizedlist>
+                    <listitem><para><emphasis>Essentials:</emphasis>
+                        Packages needed to build an image for a headless
+                        system:
+                        <literallayout class='monospaced'>
+     $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL;
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Graphical Extras:</emphasis>
+                        Packages recommended if the host system has graphics support:
+                        <literallayout class='monospaced'>
+     $ sudo yum install SDL-devel xterm
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Documentation:</emphasis>
+                        Packages needed if you are going to build out the
+                        Yocto Project documentation manuals:
+                        <literallayout class='monospaced'>
+     $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
+     docbook-dtds docbook-utils fop libxslt dblatex xmlto
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>ADT Installer Extras:</emphasis>
+                        Packages needed if you are going to be using the
+                        <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
+                        <literallayout class='monospaced'>
+     $ sudo yum install autoconf automake libtool glib2-devel
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='opensuse-packages'>
+            <title>OpenSUSE Packages</title>
+
+            <para>
+                The following list shows the required packages by function
+                given a supported OpenSUSE Linux distribution:
+                <itemizedlist>
+                    <listitem><para><emphasis>Essentials:</emphasis>
+                        Packages needed to build an image for a headless
+                        system:
+                        <literallayout class='monospaced'>
+     $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL;
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Graphical Extras:</emphasis>
+                        Packages recommended if the host system has graphics support:
+                        <literallayout class='monospaced'>
+     $ sudo zypper install libSDL-devel xterm
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Documentation:</emphasis>
+                        Packages needed if you are going to build out the
+                        Yocto Project documentation manuals:
+                        <literallayout class='monospaced'>
+     $ sudo zypper install make fop xsltproc dblatex xmlto
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>ADT Installer Extras:</emphasis>
+                        Packages needed if you are going to be using the
+                        <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
+                        <literallayout class='monospaced'>
+     $ sudo zypper install autoconf automake libtool glib2-devel
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='centos-packages'>
+            <title>CentOS Packages</title>
+
+            <para>
+                The following list shows the required packages by function
+                given a supported CentOS Linux distribution:
+                <note>Depending on the CentOS version you are using, other requirements
+                    and dependencies might exist.
+                    For details, you should look at the CentOS sections on the
+                    <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
+                    wiki page.
+                </note>
+                <itemizedlist>
+                    <listitem><para><emphasis>Essentials:</emphasis>
+                        Packages needed to build an image for a headless
+                        system:
+                        <literallayout class='monospaced'>
+     $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL;
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Graphical Extras:</emphasis>
+                        Packages recommended if the host system has graphics support:
+                        <literallayout class='monospaced'>
+     $ sudo yum install SDL-devel xterm
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>Documentation:</emphasis>
+                        Packages needed if you are going to build out the
+                        Yocto Project documentation manuals:
+                        <literallayout class='monospaced'>
+     $ sudo yum install make docbook-style-dsssl docbook-style-xsl \
+     docbook-dtds docbook-utils fop libxslt dblatex xmlto
+                        </literallayout></para></listitem>
+                    <listitem><para><emphasis>ADT Installer Extras:</emphasis>
+                        Packages needed if you are going to be using the
+                        <ulink url='&YOCTO_DOCS_ADT_URL;#using-the-adt-installer'>Application Development Toolkit (ADT) Installer</ulink>:
+                        <literallayout class='monospaced'>
+     $ sudo yum install autoconf automake libtool glib2-devel
+                        </literallayout></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+    </section>
+
+    <section id='required-git-tar-and-python-versions'>
+        <title>Required Git, tar, and Python Versions</title>
+
+        <para>
+            In order to use the build system, your host development system
+            must meet the following version requirements for Git, tar, and
+            Python:
+            <itemizedlist>
+                <listitem><para>Git 1.7.5 or greater</para></listitem>
+                <listitem><para>tar 1.24 or greater</para></listitem>
+                <listitem><para>Python 2.7.3 or greater not including
+                    Python 3.x, which is not supported.</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            If your host development system does not meet all these requirements,
+            you can resolve this by either downloading a pre-built tarball
+            containing these tools, or building such a tarball on another
+            system.
+            Regardless of the method, once you have the tarball you simply
+            install it somewhere on you system, such as a directory in your
+            home directory, and then source the environment script provided,
+            which adds the tools into <filename>PATH</filename> and sets
+            any other environment variables required to run the tools.
+            Doing so gives you working versions of Git, tar, Python and
+            <filename>chrpath</filename>.
+        </para>
+
+        <para>
+            If downloading a pre-built tarball, locate the
+            <filename>*.sh</filename> at
+            <ulink url='&YOCTO_DL_URL;/releases/yocto/yocto-1.5/buildtools/'></ulink>.
+        </para>
+
+        <para>
+            If building your own tarball, do so using this command:
+            <literallayout class='monospaced'>
+     $ bitbake buildtools-tarball
+            </literallayout>
+            <note>
+                The <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>
+                variable determines whether you build tools for a 32-bit
+                or 64-bit system.
+            </note>
+            Once the build completes, you can find the file that installs the
+            the tools in the <filename>tmp/deploy/sdk</filename> subdirectory
+            of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+            The file used to install the tarball has the string "buildtools"
+            in the name.
+        </para>
+
+        <para>
+            After you have either built the tarball or downloaded it, you need
+            to install it.
+            Install the tools by executing the <filename>*.sh</filename> file.
+            During execution, a prompt appears that allows you to choose the
+            installation directory.
+            For example, you could choose the following:
+            <literallayout class='monospaced'>
+     /home/your-username/sdk
+            </literallayout>
+        </para>
+
+        <para>
+            The final step before you can actually use the tools is to source
+            the tools environment with a command like the following:
+            <literallayout class='monospaced'>
+     $ source /home/your-username/sdk/environment-setup-i586-poky-linux
+            </literallayout>
+            Of course, you need to supply your installation directory and be
+            sure to use the right file (i.e. i585 or x86-64).
+        </para>
+    </section>
+</section>
+
+<section id='intro-getit'>
+    <title>Obtaining the Yocto Project</title>
+    <para>
+        The Yocto Project development team makes the Yocto Project available through a number
+        of methods:
+        <itemizedlist>
+            <listitem><para><emphasis>Releases:</emphasis> Stable, tested releases are available through
+                <ulink url='&YOCTO_DL_URL;/releases/yocto/'/>.</para></listitem>
+            <listitem><para><emphasis>Nightly Builds:</emphasis> These releases are available at
+                <ulink url='http://autobuilder.yoctoproject.org/nightly'/>.
+                These builds include Yocto Project releases, meta-toolchain tarball installation scripts, and
+                experimental builds.</para></listitem>
+            <listitem><para><emphasis>Yocto Project Website:</emphasis> You can find releases
+                of the Yocto Project and supported BSPs at the
+                <ulink url='&YOCTO_HOME_URL;'>Yocto Project website</ulink>.
+                Along with these downloads, you can find lots of other information at this site.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='intro-getit-dev'>
+    <title>Development Checkouts</title>
+    <para>
+        Development using the Yocto Project requires a local
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        You can set up the Source Directory by downloading a Yocto Project release tarball and unpacking it,
+        or by cloning a copy of the upstream
+        <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink> Git repository.
+        For information on both these methods, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/migration.xml b/documentation/ref-manual/migration.xml
new file mode 100644
index 0000000000..bb6203998b
--- /dev/null
+++ b/documentation/ref-manual/migration.xml
@@ -0,0 +1,1089 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='migration'>
+<title>Migrating to a Newer Yocto Project Release</title>
+
+    <para>
+        This chapter provides information you can use to migrate work to a
+        newer Yocto Project release.  You can find the same information in the
+        release notes for a given release.
+    </para>
+
+<section id='moving-to-the-yocto-project-1.3-release'>
+    <title>Moving to the Yocto Project 1.3 Release</title>
+
+    <para>
+        This section provides migration information for moving to the
+        Yocto Project 1.3 Release from the prior release.
+    </para>
+
+    <section id='1.3-local-configuration'>
+        <title>Local Configuration</title>
+
+        <para>
+            Differences include changes for
+            <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
+            and <filename>bblayers.conf</filename>.
+        </para>
+
+        <section id='migration-1.3-sstate-mirrors'>
+            <title>SSTATE_MIRRORS</title>
+
+            <para>
+                The shared state cache (sstate-cache), as pointed to by
+                <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>, by default
+                now has two-character subdirectories to prevent issues rising
+                from too many files in the same directory.
+                Also, native sstate-cache packages will go into a subdirectory named using
+                the distro ID string.
+                If you copy the newly structured sstate-cache to a mirror location
+                (either local or remote) and then point to it in
+                <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>,
+                you need to append "PATH" to the end of the mirror URL so that
+                the path used by BitBake before the mirror substitution is
+                appended to the path used to access the mirror.
+                Here is an example:
+                <literallayout class='monospaced'>
+     SSTATE_MIRRORS = "file://.* http://someserver.tld/share/sstate/PATH"
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='migration-1.3-bblayers-conf'>
+            <title>bblayers.conf</title>
+
+            <para>
+                The <filename>meta-yocto</filename> layer consists of two parts
+                that correspond to the Poky reference distribution and the
+                reference hardware Board Support Packages (BSPs), respectively:
+                <filename>meta-yocto</filename> and
+                <filename>meta-yocto-bsp</filename>.
+                When running BitBake or Hob for the first time after upgrading,
+                your <filename>conf/bblayers.conf</filename> file will be
+                updated to handle this change and you will be asked to
+                re-run or restart for the changes to take effect.
+            </para>
+        </section>
+    </section>
+
+    <section id='1.3-recipes'>
+        <title>Recipes</title>
+
+        <para>
+            Differences include changes for the following:
+            <itemizedlist>
+                <listitem><para>Python function whitespace</para></listitem>
+                <listitem><para><filename>proto=</filename> in <filename>SRC_URI</filename></para></listitem>
+                <listitem><para><filename>nativesdk</filename></para></listitem>
+                <listitem><para>Task recipes</para></listitem>
+                <listitem><para><filename>IMAGE_FEATURES</filename></para></listitem>
+                <listitem><para>Removed recipes</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <section id='migration-1.3-python-function-whitespace'>
+            <title>Python Function Whitespace</title>
+
+            <para>
+                All Python functions must now use four spaces for indentation.
+                Previously, an inconsistent mix of spaces and tabs existed,
+                which made extending these functions using
+                <filename>_append</filename> or <filename>_prepend</filename>
+                complicated given that Python treats whitespace as
+                syntactically significant.
+                If you are defining or extending any Python functions (e.g.
+                <filename>populate_packages</filename>, <filename>do_unpack</filename>,
+                <filename>do_patch</filename> and so forth) in custom recipes
+                or classes, you need to ensure you are using consistent
+                four-space indentation.
+            </para>
+        </section>
+
+        <section id='migration-1.3-proto=-in-src-uri'>
+            <title>proto= in SRC_URI</title>
+
+            <para>
+                Any use of <filename>proto=</filename> in
+                <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>
+                needs to be changed to <filename>protocol=</filename>.
+                In particular, this applies to the following URIs:
+                <itemizedlist>
+                    <listitem><para><filename>svn://</filename></para></listitem>
+                    <listitem><para><filename>bzr://</filename></para></listitem>
+                    <listitem><para><filename>hg://</filename></para></listitem>
+                    <listitem><para><filename>osc://</filename></para></listitem>
+                </itemizedlist>
+                Other URIs were already using <filename>protocol=</filename>.
+                This change improves consistency.
+            </para>
+        </section>
+
+        <section id='migration-1.3-nativesdk'>
+            <title>nativesdk</title>
+
+            <para>
+                The suffix <filename>nativesdk</filename> is now implemented
+                as a prefix, which simplifies a lot of the packaging code for
+                <filename>nativesdk</filename> recipes.
+                All custom <filename>nativesdk</filename> recipes and any
+                references need to be updated to use
+                <filename>nativesdk-*</filename> instead of
+                <filename>*-nativesdk</filename>.
+            </para>
+        </section>
+
+        <section id='migration-1.3-task-recipes'>
+            <title>Task Recipes</title>
+
+            <para>
+                "Task" recipes are now known as "Package groups" and have
+                been renamed from <filename>task-*.bb</filename> to
+                <filename>packagegroup-*.bb</filename>.
+                Existing references to the previous <filename>task-*</filename>
+                names should work in most cases as there is an automatic
+                upgrade path for most packages.
+                However, you should update references in your own recipes and
+                configurations as they could be removed in future releases.
+                You should also rename any custom <filename>task-*</filename>
+                recipes to <filename>packagegroup-*</filename>, and change
+                them to inherit <filename>packagegroup</filename> instead of
+                <filename>task</filename>, as well as taking the opportunity
+                to remove anything now handled by
+                <filename>packagegroup.bbclass</filename>, such as providing
+                <filename>-dev</filename> and <filename>-dbg</filename>
+                packages, setting
+                <link linkend='var-LIC_FILES_CHKSUM'><filename>LIC_FILES_CHKSUM</filename></link>,
+                and so forth.
+                See the
+                "<link linkend='ref-classes-packagegroup'>Package Groups - packagegroup.bbclass</link>"
+                section for further details.
+            </para>
+        </section>
+
+        <section id='migration-1.3-image-features'>
+            <title>IMAGE_FEATURES</title>
+
+            <para>
+                Image recipes that previously included "apps-console-core"
+                in <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
+                should now include "splash" instead to enable the boot-up
+                splash screen.
+                Retaining "apps-console-core" will still include the splash
+                screen but generates a warning.
+                The "apps-x11-core" and "apps-x11-games"
+                <filename>IMAGE_FEATURES</filename> features have been removed.
+            </para>
+        </section>
+
+        <section id='migration-1.3-removed-recipes'>
+            <title>Removed Recipes</title>
+
+            <para>
+                The following recipes have been removed.
+                For most of them, it is unlikely that you would have any
+                references to them in your own
+                <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>.
+                However, you should check your metadata against this list to be sure:
+                <itemizedlist>
+                    <listitem><para><emphasis><filename>libx11-trim</filename></emphasis>:
+                        Replaced by <filename>libx11</filename>, which has a negligible
+                        size difference with modern Xorg.</para></listitem>
+                    <listitem><para><emphasis><filename>xserver-xorg-lite</filename></emphasis>:
+                        Use <filename>xserver-xorg</filename>, which has a negligible
+                        size difference when DRI and GLX modules are not installed.</para></listitem>
+                    <listitem><para><emphasis><filename>xserver-kdrive</filename></emphasis>:
+                        Effectively unmaintained for many years.</para></listitem>
+                    <listitem><para><emphasis><filename>mesa-xlib</filename></emphasis>:
+                        No longer serves any purpose.</para></listitem>
+                    <listitem><para><emphasis><filename>galago</filename></emphasis>:
+                        Replaced by telepathy.</para></listitem>
+                    <listitem><para><emphasis><filename>gail</filename></emphasis>:
+                        Functionality was integrated into GTK+ 2.13.</para></listitem>
+                    <listitem><para><emphasis><filename>eggdbus</filename></emphasis>:
+                        No longer needed.</para></listitem>
+                    <listitem><para><emphasis><filename>gcc-*-intermediate</filename></emphasis>:
+                        The build has been restructured to avoid the need for
+                        this step.</para></listitem>
+                    <listitem><para><emphasis><filename>libgsmd</filename></emphasis>:
+                        Unmaintained for many years.
+                        Functionality now provided by
+                        <filename>ofono</filename> instead.</para></listitem>
+                    <listitem><para><emphasis>contacts, dates, tasks, eds-tools</emphasis>:
+                        Largely unmaintained PIM application suite.
+                        It has been moved to <filename>meta-gnome</filename>
+                        in <filename>meta-openembedded</filename>.</para></listitem>
+                </itemizedlist>
+                In addition to the previously listed changes, the
+                <filename>meta-demoapps</filename> directory has also been removed
+                because the recipes in it were not being maintained and many
+                had become obsolete or broken.
+                Additionally, these recipes were not parsed in the default configuration.
+                Many of these recipes are already provided in an updated and
+                maintained form within the OpenEmbedded community layers such as
+                <filename>meta-oe</filename> and <filename>meta-gnome</filename>.
+                For the remainder, you can now find them in the
+                <filename>meta-extras</filename> repository, which is in the
+                Yocto Project
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>.
+            </para>
+        </section>
+    </section>
+
+    <section id='1.3-linux-kernel-naming'>
+        <title>Linux Kernel Naming</title>
+
+        <para>
+            The naming scheme for kernel output binaries has been changed to
+            now include
+            <link linkend='var-PE'><filename>PE</filename></link> as part of the
+            filename:
+            <literallayout class='monospaced'>
+     KERNEL_IMAGE_BASE_NAME ?= "${KERNEL_IMAGETYPE}-${PE}-${PV}-${PR}-${MACHINE}-${DATETIME}"
+            </literallayout>
+        </para>
+
+        <para>
+            Because the <filename>PE</filename> variable is not set by default,
+            these binary files could result with names that include two dash
+            characters.
+            Here is an example:
+            <literallayout class='monospaced'>
+     bzImage--3.10.9+git0+cd502a8814_7144bcc4b8-r0-qemux86-64-20130830085431.bin
+            </literallayout>
+        </para>
+    </section>
+</section>
+
+<section id='moving-to-the-yocto-project-1.4-release'>
+    <title>Moving to the Yocto Project 1.4 Release</title>
+
+    <para>
+        This section provides migration information for moving to the
+        Yocto Project 1.4 Release from the prior release.
+    </para>
+
+    <section id='migration-1.4-bitbake'>
+        <title>BitBake</title>
+
+        <para>
+            Differences include the following:
+            <itemizedlist>
+                <listitem><para><emphasis>Comment Continuation:</emphasis>
+                    If a comment ends with a line continuation (\) character,
+                    then the next line must also be a comment.
+                    Any instance where this is not the case, now triggers
+                    a warning.
+                    You must either remove the continuation character, or be
+                    sure the next line is a comment.
+                    </para></listitem>
+                <listitem><para><emphasis>Package Name Overrides:</emphasis>
+                    The runtime package specific variables
+                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
+                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
+                    <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
+                    <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
+                    <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
+                    <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
+                    <link linkend='var-FILES'><filename>FILES</filename></link>,
+                    <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
+                    and the pre, post, install, and uninstall script functions
+                    <filename>pkg_preinst</filename>,
+                    <filename>pkg_postinst</filename>,
+                    <filename>pkg_prerm</filename>, and
+                    <filename>pkg_postrm</filename> should always have a
+                    package name override.
+                    For example, use <filename>RDEPENDS_${PN}</filename> for
+                    the main package instead of <filename>RDEPENDS</filename>.
+                    BitBake uses more strict checks when it parses recipes.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.4-build-behavior'>
+        <title>Build Behavior</title>
+
+        <para>
+            Differences include the following:
+            <itemizedlist>
+                <listitem><para><emphasis>Shared State Code:</emphasis>
+                    The shared state code has been optimized to avoid running
+                    unnecessary tasks.
+                    For example,
+                    <filename>bitbake -c rootfs some-image</filename> from
+                    shared state no longer populates the target sysroot
+                    since that is not necessary.
+                    Instead, the system just needs to extract the output
+                    package contents, re-create the packages, and construct
+                    the root filesystem.
+                    This change is unlikely to cause any problems unless
+                    you have missing declared dependencies.
+                    </para></listitem>
+                <listitem><para><emphasis>Scanning Directory Names:</emphasis>
+                    When scanning for files in
+                    <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>,
+                    the build system now uses
+                    <link linkend='var-FILESOVERRIDES'><filename>FILESOVERRIDES</filename></link>
+                    instead of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
+                    for the directory names.
+                    In general, the values previously in
+                    <filename>OVERRIDES</filename> are now in
+                    <filename>FILESOVERRIDES</filename> as well.
+                    However, if you relied upon an additional value
+                    you previously added to <filename>OVERRIDES</filename>,
+                    you might now need to add it to
+                    <filename>FILESOVERRIDES</filename> unless you are already
+                    adding it through the
+                    <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>
+                    or <link linkend='var-DISTROOVERRIDES'><filename>DISTROOVERRIDES</filename></link>
+                    variables, as appropriate.
+                    For more related changes, see the
+                    "<link linkend='migration-1.4-variables'>Variables</link>"
+                    section.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+
+    <section id='migration-1.4-proxies-and-fetching-source'>
+        <title>Proxies and Fetching Source</title>
+
+        <para>
+            A new <filename>oe-git-proxy</filename> script has been added to
+            replace previous methods of handling proxies and fetching source
+            from Git.
+            See the <filename>meta-yocto/conf/site.conf.sample</filename> file
+            for information on how to use this script.
+        </para>
+    </section>
+
+    <section id='migration-1.4-custom-interfaces-file-netbase-change'>
+        <title>Custom Interfaces File (netbase change)</title>
+
+        <para>
+            If you have created your own custom
+            <filename>etc/network/interfaces</filename> file by creating
+            an append file for the <filename>netbase</filename> recipe,
+            you now need to create an append file for the
+            <filename>init-ifupdown</filename> recipe instead, which you can
+            find in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            at <filename>meta/recipes-core/init-ifupdown</filename>.
+            For information on how to use append files, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#using-bbappend-files'>Using .bbappend Files</ulink>"
+            in the Yocto Project Development Manual.
+        </para>
+    </section>
+
+    <section id='migration-1.4-remote-debugging'>
+        <title>Remote Debugging</title>
+
+        <para>
+            Support for remote debugging with the Eclipse IDE is now
+            separated into an image feature
+            (<filename>eclipse-debug</filename>) that corresponds to the
+            <filename>packagegroup-core-eclipse-debug</filename> package group.
+            Previously, the debugging feature was included through the
+            <filename>tools-debug</filename> image feature, which corresponds
+            to the <filename>packagegroup-core-tools-debug</filename>
+            package group.
+        </para>
+    </section>
+
+    <section id='migration-1.4-variables'>
+        <title>Variables</title>
+
+        <para>
+            The following variables have changed:
+            <itemizedlist>
+                <listitem><para><emphasis><filename>SANITY_TESTED_DISTROS</filename>:</emphasis>
+                    This variable now uses a distribution ID, which is composed
+                    of the host distributor ID followed by the release.
+                    Previously,
+                    <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
+                    was composed of the description field.
+                    For example, "Ubuntu 12.10" becomes "Ubuntu-12.10".
+                    You do not need to worry about this change if you are not
+                    specifically setting this variable, or if you are
+                    specifically setting it to "".
+                    </para></listitem>
+                <listitem><para><emphasis><filename>SRC_URI</filename>:</emphasis>
+                    The <filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>,
+                    <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>,
+                    <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>,
+                    and <filename>FILE_DIRNAME</filename> directories have been
+                    dropped from the default value of the
+                    <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
+                    variable, which is used as the search path for finding files
+                    referred to in
+                    <link linkend='var-SRC_URI'><filename>SRC_URI</filename></link>.
+                    If you have a recipe that relied upon these directories,
+                    which would be unusual, then you will need to add the
+                    appropriate paths within the recipe or, alternatively,
+                    rearrange the files.
+                    The most common locations are still covered by
+                    <filename>${BP}</filename>, <filename>${BPN}</filename>,
+                    and "files", which all remain in the default value of
+                    <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-target-package-management-with-rpm'>
+        <title>Target Package Management with RPM</title>
+
+        <para>
+            If runtime package management is enabled and the RPM backend
+            is selected, Smart is now installed for package download, dependency
+            resolution, and upgrades instead of Zypper.
+            For more information on how to use Smart, run the following command
+            on the target:
+            <literallayout class='monospaced'>
+     smart --help
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='migration-1.4-recipes-moved'>
+        <title>Recipes Moved</title>
+
+        <para>
+            The following recipes were moved from their previous locations
+            because they are no longer used by anything in
+            the OpenEmbedded-Core:
+            <itemizedlist>
+                <listitem><para><emphasis><filename>clutter-box2d</filename>:</emphasis>
+                    Now resides in the <filename>meta-oe</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>evolution-data-server</filename>:</emphasis>
+                    Now resides in the <filename>meta-gnome</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>gthumb</filename>:</emphasis>
+                    Now resides in the <filename>meta-gnome</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>gtkhtml2</filename>:</emphasis>
+                    Now resides in the <filename>meta-oe</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>gupnp</filename>:</emphasis>
+                    Now resides in the <filename>meta-multimedia</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>gypsy</filename>:</emphasis>
+                    Now resides in the <filename>meta-oe</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>libcanberra</filename>:</emphasis>
+                    Now resides in the <filename>meta-gnome</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>libgdata</filename>:</emphasis>
+                    Now resides in the <filename>meta-gnome</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>libmusicbrainz</filename>:</emphasis>
+                    Now resides in the <filename>meta-multimedia</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>metacity</filename>:</emphasis>
+                    Now resides in the <filename>meta-gnome</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>polkit</filename>:</emphasis>
+                    Now resides in the <filename>meta-oe</filename> layer.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>zeroconf</filename>:</emphasis>
+                    Now resides in the <filename>meta-networking</filename> layer.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.4-removals-and-renames'>
+        <title>Removals and Renames</title>
+
+        <para>
+            The following list shows what has been removed or renamed:
+            <itemizedlist>
+                <listitem><para><emphasis><filename>evieext</filename>:</emphasis>
+                    Removed because it has been removed from
+                    <filename>xserver</filename> since 2008.
+                    </para></listitem>
+                <listitem><para><emphasis>Gtk+ DirectFB:</emphasis>
+                    Removed support because upstream Gtk+ no longer supports it
+                    as of version 2.18.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>libxfontcache / xfontcacheproto</filename>:</emphasis>
+                    Removed because they were removed from the Xorg server in 2008.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>libxp / libxprintapputil / libxprintutil / printproto</filename>:</emphasis>
+                    Removed because the XPrint server was removed from
+                    Xorg in 2008.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>libxtrap / xtrapproto</filename>:</emphasis>
+                    Removed because their functionality was broken upstream.
+                    </para></listitem>
+                <listitem><para><emphasis>linux-yocto 3.0 kernel:</emphasis>
+                    Removed with linux-yocto 3.8 kernel being added.
+                    The linux-yocto 3.2 and linux-yocto 3.4 kernels remain
+                    as part of the release.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>lsbsetup</filename>:</emphasis>
+                    Removed with functionality now provided by
+                    <filename>lsbtest</filename>.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>matchbox-stroke</filename>:</emphasis>
+                    Removed because it was never more than a proof-of-concept.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>matchbox-wm-2 / matchbox-theme-sato-2</filename>:</emphasis>
+                    Removed because they are not maintained.
+                    However, <filename>matchbox-wm</filename> and
+                    <filename>matchbox-theme-sato</filename> are still
+                    provided.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>mesa-dri</filename>:</emphasis>
+                    Renamed to <filename>mesa</filename>.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>mesa-xlib</filename>:</emphasis>
+                    Removed because it was no longer useful.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>mutter</filename>:</emphasis>
+                    Removed because nothing ever uses it and the recipe is
+                    very old.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>orinoco-conf</filename>:</emphasis>
+                    Removed because it has become obsolete.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>update-modules</filename>:</emphasis>
+                    Removed because it is no longer used.
+                    The kernel module <filename>postinstall</filename> and
+                    <filename>postrm</filename> scripts can now do the same
+                    task without the use of this script.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>web</filename>:</emphasis>
+                    Removed because it is not maintained.  Superseded by
+                    <filename>web-webkit</filename>.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>xf86bigfontproto</filename>:</emphasis>
+                    Removed because upstream it has been disabled by default
+                    since 2007.
+                    Nothing uses <filename>xf86bigfontproto</filename>.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>xf86rushproto</filename>:</emphasis>
+                    Removed because its dependency in
+                    <filename>xserver</filename> was spurious and it was
+                    removed in 2005.
+                    </para></listitem>
+                <listitem><para><emphasis><filename>zypper / libzypp / sat-solver</filename>:</emphasis>
+                    Removed and been functionally replaced with Smart
+                    (<filename>python-smartpm</filename>) when RPM packaging
+                    is used and package management is enabled on the target.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+
+<section id='moving-to-the-yocto-project-1.5-release'>
+    <title>Moving to the Yocto Project 1.5 Release</title>
+
+    <para>
+        This section provides migration information for moving to the
+        Yocto Project 1.5 Release from the prior release.
+    </para>
+
+    <section id='migration-1.5-host-dependency-changes'>
+        <title>Host Dependency Changes</title>
+
+        <para>
+            The OpenEmbedded build system now has some additional requirements
+            on the host system:
+            <itemizedlist>
+                <listitem><para>Python 2.7.3+</para></listitem>
+                <listitem><para>Tar 1.24+</para></listitem>
+                <listitem><para>Git 1.7.5+</para></listitem>
+                <listitem><para>Patched version of Make if you are using
+                    3.82.
+                    Most distributions that provide Make 3.82 use the patched
+                    version.</para></listitem>
+            </itemizedlist>
+            If the Linux distribution you are using on your build host
+            does not provide packages for these, you can install and use
+            the Buildtools tarball, which provides an SDK-like environment
+            containing them.
+        </para>
+
+        <para>
+            For more information on this requirement, see the
+            "<link linkend='required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</link>"
+            section.
+        </para>
+    </section>
+
+    <section id='migration-1.5-atom-pc-bsp'>
+        <title><filename>atom-pc</filename> Board Support Package (BSP)</title>
+
+        <para>
+            The <filename>atom-pc</filename> hardware reference BSP has been
+            replaced by a <filename>genericx86</filename> BSP.
+            This BSP is not necessarily guaranteed to work on all x86
+            hardware, but it will run on a wider range of systems than the
+            <filename>atom-pc</filename> did.
+            <note>
+                Additionally, a <filename>genericx86-64</filename> BSP has been
+                added for 64-bit systems.
+            </note>
+        </para>
+    </section>
+
+    <section id='migration-1.5-bitbake'>
+        <title>BitBake</title>
+
+        <para>
+            The following changes have been made that relate to BitBake:
+            <itemizedlist>
+                <listitem><para>
+                    BitBake now supports a <filename>_remove</filename>
+                    operator.
+                    The addition of this operator means you will have to
+                    rename any items in recipe space (functions, variables)
+                    whose names currently contain
+                    <filename>_remove_</filename> or end with
+                    <filename>_remove</filename> to avoid unexpected behavior.
+                    </para></listitem>
+                <listitem><para>
+                    BitBake's global method pool has been removed.
+                    This method is not particularly useful and led to clashes
+                    between recipes containing functions that had the
+                    same name.</para></listitem>
+                <listitem><para>
+                    The "none" server backend has been removed.
+                    The "process" server backend has been serving well as the
+                    default for a long time now.</para></listitem>
+                <listitem><para>
+                    The <filename>bitbake-runtask</filename> script has been
+                    removed.</para></listitem>
+                <listitem><para>
+                    <filename>${</filename><link linkend='var-P'><filename>P</filename></link><filename>}</filename>
+                    and
+                    <filename>${</filename><link linkend='var-PF'><filename>PF</filename></link><filename>}</filename>
+                    are no longer added to
+                    <link linkend='var-PROVIDES'><filename>PROVIDES</filename></link>
+                    by default in <filename>bitbake.conf</filename>.
+                    These version-specific <filename>PROVIDES</filename>
+                    items were seldom used.
+                    Attempting to use them could result in two versions being
+                    built simultaneously rather than just one version due to
+                    the way BitBake resolves dependencies.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.5-qa-warnings'>
+        <title>QA Warnings</title>
+
+        <para>
+            The following changes have been made to the package QA checks:
+            <itemizedlist>
+                <listitem><para>
+                    If you have customized
+                    <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
+                    or <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link>
+                    values in your configuration, check that they contain all of
+                    the issues that you wish to be reported.
+                    Previous Yocto Project versions contained a bug that meant
+                    that any item not mentioned in <filename>ERROR_QA</filename>
+                    or <filename>WARN_QA</filename> would be treated as a
+                    warning.
+                    Consequently, several important items were not already in
+                    the default value of <filename>WARN_QA</filename>.
+                    All of the possible QA checks are now documented in the
+                    "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
+                    section.</para></listitem>
+                <listitem><para>
+                    An additional QA check has been added to check if
+                    <filename>/usr/share/info/dir</filename> is being installed.
+                    Your recipe should delete this file within
+                    <filename>do_install</filename> if "make install" is
+                    installing it.</para></listitem>
+                <listitem><para>
+                    If you are using the buildhistory class, the check for the
+                    package version going backwards is now controlled using a
+                    standard QA check.
+                    Thus, if you have customized your
+                    <filename>ERROR_QA</filename> or
+                    <filename>WARN_QA</filename> values and still wish to have
+                    this check performed, you should add
+                    "version-going-backwards" to your value for one or the
+                    other variables depending on how you wish it to be handled.
+                    See the documented QA checks in the
+                    "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
+                    section.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.5-directory-layout-changes'>
+        <title>Directory Layout Changes</title>
+
+        <para>
+            The following directory changes exist:
+            <itemizedlist>
+                <listitem><para>
+                    Output SDK installer files are now named to include the
+                    image name and tuning architecture through the
+                    <link linkend='var-SDK_NAME'><filename>SDK_NAME</filename></link>
+                    variable.</para></listitem>
+                <listitem><para>
+                    Images and related files are now installed into a directory
+                    that is specific to the machine, instead of a parent
+                    directory containing output files for multiple machines.
+                    The
+                    <link linkend='var-DEPLOY_DIR_IMAGE'><filename>DEPLOY_DIR_IMAGE</filename></link>
+                    variable continues to point to the directory containing
+                    images for the current
+                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
+                    and should be used anywhere there is a need to refer to
+                    this directory.
+                    The <filename>runqemu</filename> script now uses this
+                    variable to find images and kernel binaries and will use
+                    BitBake to determine the directory.
+                    Alternatively, you can set the
+                    <filename>DEPLOY_DIR_IMAGE</filename> variable in the
+                    external environment.</para></listitem>
+                <listitem><para>
+                    When buildhistory is enabled, its output is now written
+                    under the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    rather than
+                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>.
+                    Doing so makes it a easier to delete
+                    <filename>TMPDIR</filename> and preserve the build history.
+                    Additionally, data for produced SDKs is now split by
+                    <link linkend='var-IMAGE_NAME'><filename>IMAGE_NAME</filename></link>.
+                    </para></listitem>
+                <listitem><para>
+                    The <filename>pkgdata</filename> directory produced as
+                    part of the packaging process has been collapsed into a
+                    single machine-specific directory.
+                    This directory is located under
+                    <filename>sysroots</filename> and uses a machine-specific
+                    name (i.e.
+                    <filename>tmp/sysroots/&lt;machine&gt;/pkgdata</filename>).
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.5-shortened-git-srcrev-values'>
+        <title>Shortened Git <filename>SRCREV</filename> Values</title>
+
+        <para>
+            BitBake will now shorten revisions from Git repositories from the
+            normal 40 characters down to 10 characters within
+            <link linkend='var-SRCPV'><filename>SRCPV</filename></link>
+            for improved usability in path and file names.
+            This change should be safe within contexts where these revisions
+            are used because the chances of spatially close collisions
+            is very low.
+            Distant collisions are not a major issue in the way
+            the values are used.
+        </para>
+    </section>
+
+    <section id='migration-1.5-image-features'>
+        <title><filename>IMAGE_FEATURES</filename></title>
+
+        <para>
+            The following changes have been made that relate to
+            <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>:
+            <itemizedlist>
+                <listitem><para>
+                    The value of
+                    <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
+                    is now validated to ensure invalid feature items are not
+                    added.
+                    Some users mistakenly add package names to this variable
+                    instead of using
+                    <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
+                    in order to have the package added to the image, which does
+                    not work.
+                    This change is intended to catch those kinds of situations.
+                    Valid <filename>IMAGE_FEATURES</filename> are drawn from
+                    <link linkend='var-PACKAGE_GROUP'><filename>PACKAGE_GROUP</filename></link>
+                    definitions,
+                    <link linkend='var-COMPLEMENTARY_GLOB'><filename>COMPLEMENTARY_GLOB</filename></link>
+                    and a new "validitems" varflag on
+                    <filename>IMAGE_FEATURES</filename>.
+                    The "validitems" varflag change allows additional features
+                    to be added if they are not provided using the previous
+                    two mechanisms.
+                    </para></listitem>
+                <listitem><para>
+                    The previously deprecated "apps-console-core"
+                    <filename>IMAGE_FEATURES</filename> item is no longer
+                    supported.
+                    Add "splash" to <filename>IMAGE_FEATURES</filename> if you
+                    wish to have the splash screen enabled, since this is
+                    all that apps-console-core was doing.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='migration-1.5-run'>
+        <title><filename>/run</filename></title>
+
+        <para>
+            The <filename>/run</filename> directory from the Filesystem
+            Hierarchy Standard 3.0 has been introduced.
+            You can find some of the implications for this change
+            <ulink url='http://cgit.openembedded.org/openembedded-core/commit/?id=0e326280a15b0f2c4ef2ef4ec441f63f55b75873'>here</ulink>.
+            The change also means that recipes that install files to
+            <filename>/var/run</filename> must be changed.
+            You can find a guide on how to make these changes
+            <ulink url='http://permalink.gmane.org/gmane.comp.handhelds.openembedded/58530'>here</ulink>.
+        </para>
+    </section>
+
+    <section id='migration-1.5-removal-of-package-manager-database-within-image-recipes'>
+        <title>Removal of Package Manager Database Within Image Recipes</title>
+
+        <para>
+            The image <filename>core-image-minimal</filename> no longer adds
+            <filename>remove_packaging_data_files</filename> to
+            <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>.
+            This addition is now handled automatically when "package-management"
+            is not in
+            <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
+            If you have custom image recipes that make this addition,
+            you should remove the lines, as they are not needed and might
+            interfere with correct operation of postinstall scripts.
+        </para>
+    </section>
+
+    <section id='migration-1.5-images-now-rebuild-only-on-changes-instead-of-every-time'>
+        <title>Images Now Rebuild Only on Changes Instead of Every Time</title>
+
+        <para>
+            The <filename>do_rootfs</filename> and other related image
+            construction tasks are no longer marked as "nostamp".
+            Consequently, they will only be re-executed when their inputs have
+            changed.
+            Previous versions of the OpenEmbedded build system always rebuilt
+            the image when requested rather when necessary.
+        </para>
+    </section>
+
+    <section id='migration-1.5-task-recipes'>
+        <title>Task Recipes</title>
+
+        <para>
+            The previously deprecated <filename>task.bbclass</filename> has
+            now been dropped.
+            For recipes that previously inherited from this task, you should
+            rename them from <filename>task-*</filename> to
+            <filename>packagegroup-*</filename> and inherit packagegroup
+            instead.
+        </para>
+
+        <para>
+            For more information, see the
+            "<link linkend='ref-classes-packagegroup'>Package Groups - <filename>packagegroup.bbclass</filename></link>"
+            section.
+        </para>
+    </section>
+
+    <section id='migration-1.5-busybox'>
+        <title>BusyBox</title>
+
+        <para>
+            By default, we now split BusyBox into two binaries:
+            one that is suid root for those components that need it, and
+            another for the rest of the components.
+            Splitting BusyBox allows for optimization that eliminates the
+            <filename>tinylogin</filename> recipe as recommended by upstream.
+            You can disable this split by setting
+            <link linkend='var-BUSYBOX_SPLIT_SUID'><filename>BUSYBOX_SPLIT_SUID</filename></link>
+            to "0".
+        </para>
+    </section>
+
+    <section id='migration-1.5-automated-image-testing'>
+        <title>Automated Image Testing</title>
+
+        <para>
+            A new automated image testing framework has been added
+            through the
+            <link linkend='ref-classes-testimage'><filename>testimage*.bbclass</filename></link>
+            class.
+            This framework replaces the older
+            <filename>imagetest-qemu</filename> framework.
+        </para>
+
+        <para>
+            You can learn more about performing automated image tests in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+            section.
+        </para>
+    </section>
+
+    <section id='migration-1.5-build-history'>
+        <title>Build History</title>
+
+        <para>
+            Following are changes to Build History:
+            <itemizedlist>
+                <listitem><para>
+                     Installed package sizes:
+                     <filename>installed-package-sizes.txt</filename> for an
+                     image now records the size of the files installed by each
+                     package instead of the size of each compressed package
+                     archive file.</para></listitem>
+                <listitem><para>
+                    The dependency graphs (<filename>depends*.dot</filename>)
+                    now use the actual package names instead of replacing
+                    dashes, dots and plus signs with underscores.
+                    </para></listitem>
+                <listitem><para>
+                    The <filename>buildhistory-diff</filename> and
+                    <filename>buildhistory-collect-srcrevs</filename>
+                    utilities have improved command-line handling.
+                    Use the <filename>&dash;&dash;help</filename> option for
+                    each utility for more information on the new syntax.
+                    </para></listitem>
+            </itemizedlist>
+            For more information on Build History, see the
+            "<link linkend='maintaining-build-output-quality'>Maintaining Build Output Quality</link>"
+            section.
+        </para>
+    </section>
+
+    <section id='migration-1.5-udev'>
+        <title><filename>udev</filename></title>
+
+        <para>
+            Following are changes to <filename>udev</filename>:
+            <itemizedlist>
+                <listitem><para>
+                    <filename>udev</filename> no longer brings in
+                    <filename>udev-extraconf</filename> automatically
+                    through
+                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
+                    since this was originally intended to be optional.
+                    If you need the extra rules, then add
+                    <filename>udev-extraconf</filename> to your image.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>udev</filename> no longer brings in
+                    <filename>pciutils-ids</filename> or
+                    <filename>usbutils-ids</filename> through
+                    <filename>RRECOMMENDS</filename>.
+                    These are not needed by <filename>udev</filename> itself
+                    and removing them saves around 350KB.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='removed-renamed-recipes'>
+        <title>Removed and Renamed Recipes</title>
+
+        <itemizedlist>
+            <listitem><para>
+                The <filename>linux-yocto</filename> 3.2 kernel has been
+                removed.</para></listitem>
+            <listitem><para>
+                <filename>libtool-nativesdk</filename> has been renamed to
+                <filename>nativesdk-libtool</filename>.</para></listitem>
+            <listitem><para>
+                <filename>tinylogin</filename> has been removed.
+                It has been replaced by a suid portion of Busybox.
+                See the
+                "<link linkend='migration-1.5-busybox'>BusyBox</link>" section
+                for more information.</para></listitem>
+            <listitem><para>
+                <filename>external-python-tarball</filename> has been renamed
+                to <filename>buildtools-tarball</filename>.
+                </para></listitem>
+            <listitem><para>
+                <filename>web-webkit</filename> has been removed.
+                It has been functionally replaced by
+                <filename>midori</filename>.</para></listitem>
+            <listitem><para>
+                <filename>imake</filename> has been removed.
+                It is no longer needed by any other recipe.
+                </para></listitem>
+            <listitem><para>
+                <filename>transfig-native</filename> has been removed.
+                It is no longer needed by any other recipe.
+                </para></listitem>
+            <listitem><para>
+                <filename>anjuta-remote-run</filename> has been removed.
+                Anjuta IDE integration has not been officially supported for
+                several releases.</para></listitem>
+        </itemizedlist>
+    </section>
+
+    <section id='migration-1.5-other-changes'>
+        <title>Other Changes</title>
+
+        <para>
+            Following is a list of short entries describing other changes:
+            <itemizedlist>
+                <listitem><para>
+                    <filename>run-postinsts</filename>: Make this generic.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>base-files</filename>: Remove the unnecessary
+                    <filename>/media/xxx</filename> directories.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>alsa-state</filename>: Provide an empty
+                    <filename>asound.conf</filename> by default.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>classes/image</filename>: Ensure
+                    <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
+                    supports pre-renamed package names.</para></listitem>
+                <listitem><para>
+                    <filename>classes/rootfs_rpm</filename>: Implement
+                    <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
+                    for RPM.</para></listitem>
+                <listitem><para>
+                    <filename>systemd</filename>: Remove
+                    <filename>systemd_unitdir</filename> if
+                    <filename>systemd</filename> is not in
+                    <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>systemd</filename>: Remove
+                    <filename>init.d</filename> dir if
+                    <filename>systemd</filename> unit file is present and
+                    <filename>sysvinit</filename> is not a distro feature.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>libpam</filename>: Deny all services for the
+                    <filename>OTHER</filename> entries.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>image.bbclass</filename>: Move
+                    <filename>runtime_mapping_rename</filename> to avoid
+                    conflict with <filename>multilib</filename>.
+                    See
+                    <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=4993'><filename>YOCTO #4993</filename></ulink>
+                    in Bugzilla for more information.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>linux-dtb</filename>: Use kernel build system
+                    to generate the <filename>dtb</filename> files.
+                    </para></listitem>
+                <listitem><para>
+                    <filename>kern-tools</filename>: Switch from guilt to
+                    new <filename>kgit-s2q</filename> tool.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/ref-bitbake.xml b/documentation/ref-manual/ref-bitbake.xml
new file mode 100644
index 0000000000..b587d46caa
--- /dev/null
+++ b/documentation/ref-manual/ref-bitbake.xml
@@ -0,0 +1,432 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-bitbake'>
+
+    <title>BitBake</title>
+
+    <para>
+        BitBake is a program written in Python that interprets the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> used by
+        the OpenEmbedded build system.
+        At some point, developers wonder what actually happens when you enter:
+        <literallayout class='monospaced'>
+     $ bitbake core-image-sato
+        </literallayout>
+    </para>
+
+    <para>
+        This chapter provides an overview of what happens behind the scenes from BitBake's perspective.
+    </para>
+
+    <note>
+        BitBake strives to be a generic "task" executor that is capable of handling complex dependency relationships.
+        As such, it has no real knowledge of what the tasks being executed actually do.
+        BitBake just considers a list of tasks with dependencies and handles
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+        consisting of variables in a certain format that get passed to the tasks.
+    </note>
+
+    <section id='ref-bitbake-parsing'>
+        <title>Parsing</title>
+
+        <para>
+            BitBake parses configuration files, classes, and <filename>.bb</filename> files.
+        </para>
+
+        <para>
+            The first thing BitBake does is look for the <filename>bitbake.conf</filename> file.
+            This file resides in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            within the <filename>meta/conf/</filename> directory.
+            BitBake finds it by examining its
+            <link linkend='var-BBPATH'><filename>BBPATH</filename></link> environment
+            variable and looking for the <filename>meta/conf/</filename>
+            directory.
+        </para>
+
+        <para>
+            The <filename>bitbake.conf</filename> file lists other configuration
+            files to include from a <filename>conf/</filename>
+            directory below the directories listed in <filename>BBPATH</filename>.
+            In general, the most important configuration file from a user's perspective
+            is <filename>local.conf</filename>, which contains a user's customized
+            settings for the OpenEmbedded build environment.
+            Other notable configuration files are the distribution
+            configuration file (set by the
+            <filename><link linkend='var-DISTRO'>DISTRO</link></filename> variable)
+            and the machine configuration file
+            (set by the
+            <filename><link linkend='var-MACHINE'>MACHINE</link></filename> variable).
+            The <filename>DISTRO</filename> and <filename>MACHINE</filename> BitBake environment
+            variables are both usually set in
+            the <filename>local.conf</filename> file.
+            Valid distribution
+            configuration files are available in the <filename>meta/conf/distro/</filename> directory
+            and valid machine configuration
+            files in the <filename>meta/conf/machine/</filename> directory.
+            Within the <filename>meta/conf/machine/include/</filename>
+            directory are various <filename>tune-*.inc</filename> configuration files that provide common
+            "tuning" settings specific to and shared between particular architectures and machines.
+        </para>
+
+        <para>
+            After the parsing of the configuration files, some standard classes are included.
+            The <filename>base.bbclass</filename> file is always included.
+            Other classes that are specified in the configuration using the
+            <filename><link linkend='var-INHERIT'>INHERIT</link></filename>
+            variable are also included.
+            Class files are searched for in a <filename>classes</filename> subdirectory
+            under the paths in <filename>BBPATH</filename> in the same way as
+            configuration files.
+        </para>
+
+        <para>
+            After classes are included, the variable
+            <filename><link linkend='var-BBFILES'>BBFILES</link></filename>
+            is set, usually in
+            <filename>local.conf</filename>, and defines the list of places to search for
+            <filename>.bb</filename> files.
+            By default, the <filename>BBFILES</filename> variable specifies the
+            <filename>meta/recipes-*/</filename> directory within Poky.
+            Adding extra content to <filename>BBFILES</filename> is best achieved through the use of
+            BitBake layers as described in the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
+            Creating Layers</ulink>" section of the Yocto Project Development Manual.
+        </para>
+
+        <para>
+            BitBake parses each <filename>.bb</filename> file in <filename>BBFILES</filename> and
+            stores the values of various variables.
+            In summary, for each <filename>.bb</filename>
+            file the configuration plus the base class of variables are set, followed
+            by the data in the <filename>.bb</filename> file
+            itself, followed by any inherit commands that
+            <filename>.bb</filename> file might contain.
+        </para>
+
+        <para>
+            Because parsing <filename>.bb</filename> files is a time
+            consuming process, a cache is kept to speed up subsequent parsing.
+            This cache is invalid if the timestamp of the <filename>.bb</filename>
+            file itself changes, or if the timestamps of any of the include,
+            configuration files or class files on which the
+            <filename>.bb</filename> file depends change.
+        </para>
+    </section>
+
+    <section id='ref-bitbake-providers'>
+        <title>Preferences and Providers</title>
+
+        <para>
+            Once all the <filename>.bb</filename> files have been
+            parsed, BitBake starts to build the target (<filename>core-image-sato</filename>
+            in the previous section's example) and looks for providers of that target.
+            Once a provider is selected, BitBake resolves all the dependencies for
+            the target.
+            In the case of <filename>core-image-sato</filename>, it would lead to
+            <filename>packagegroup-core-x11-sato</filename>,
+            which in turn leads to recipes like <filename>matchbox-terminal</filename>,
+            <filename>pcmanfm</filename> and <filename>gthumb</filename>.
+            These recipes in turn depend on <filename>eglibc</filename> and the toolchain.
+        </para>
+
+        <para>
+            Sometimes a target might have multiple providers.
+            A common example is "virtual/kernel", which is provided by each kernel package.
+            Each machine often selects the best kernel provider by using a line similar to the
+            following in the machine configuration file:
+        </para>
+
+        <literallayout class='monospaced'>
+     PREFERRED_PROVIDER_virtual/kernel = "linux-yocto"
+        </literallayout>
+
+        <para>
+            The default <filename><link linkend='var-PREFERRED_PROVIDER'>PREFERRED_PROVIDER</link></filename>
+            is the provider with the same name as the target.
+        </para>
+
+        <para>
+            Understanding how providers are chosen is made complicated by the fact
+            that multiple versions might exist.
+            BitBake defaults to the highest version of a provider.
+            Version comparisons are made using the same method as Debian.
+            You can use the
+            <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
+            variable to specify a particular version (usually in the distro configuration).
+            You can influence the order by using the
+            <filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE</link></filename>
+            variable.
+            By default, files have a preference of "0".
+            Setting the <filename>DEFAULT_PREFERENCE</filename> to "-1" makes the
+            package unlikely to be used unless it is explicitly referenced.
+            Setting the <filename>DEFAULT_PREFERENCE</filename> to "1" makes it likely the package is used.
+            <filename>PREFERRED_VERSION</filename> overrides any <filename>DEFAULT_PREFERENCE</filename> setting.
+            <filename>DEFAULT_PREFERENCE</filename> is often used to mark newer and more experimental package
+            versions until they have undergone sufficient testing to be considered stable.
+        </para>
+
+        <para>
+            In summary, BitBake has created a list of providers, which is prioritized, for each target.
+        </para>
+    </section>
+
+    <section id='ref-bitbake-dependencies'>
+        <title>Dependencies</title>
+
+        <para>
+            Each target BitBake builds consists of multiple tasks such as
+            <filename>fetch</filename>, <filename>unpack</filename>,
+            <filename>patch</filename>, <filename>configure</filename>,
+            and <filename>compile</filename>.
+            For best performance on multi-core systems, BitBake considers each task as an independent
+            entity with its own set of dependencies.
+        </para>
+
+        <para>
+            Dependencies are defined through several variables.
+            You can find information about variables BitBake uses in the BitBake documentation,
+            which is found in the <filename>bitbake/doc/manual</filename> directory within the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            At a basic level, it is sufficient to know that BitBake uses the
+            <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename> and
+            <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename> variables when
+            calculating dependencies.
+        </para>
+    </section>
+
+    <section id='ref-bitbake-tasklist'>
+        <title>The Task List</title>
+
+        <para>
+            Based on the generated list of providers and the dependency information,
+            BitBake can now calculate exactly what tasks it needs to run and in what
+            order it needs to run them.
+            The build now starts with BitBake forking off threads up to the limit set in the
+            <filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link></filename> variable.
+            BitBake continues to fork threads as long as there are tasks ready to run,
+            those tasks have all their dependencies met, and the thread threshold has not been
+            exceeded.
+        </para>
+
+        <para>
+            It is worth noting that you can greatly speed up the build time by properly setting
+            the <filename>BB_NUMBER_THREADS</filename> variable.
+            See the
+            "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+            section in the Yocto Project Quick Start for more information.
+        </para>
+
+        <para>
+            As each task completes, a timestamp is written to the directory specified by the
+            <filename><link linkend='var-STAMP'>STAMP</link></filename> variable.
+            On subsequent runs, BitBake looks within the <filename>/build/tmp/stamps</filename>
+            directory and does not rerun
+            tasks that are already completed unless a timestamp is found to be invalid.
+            Currently, invalid timestamps are only considered on a per
+            <filename>.bb</filename> file basis.
+            So, for example, if the configure stamp has a timestamp greater than the
+            compile timestamp for a given target, then the compile task would rerun.
+            Running the compile task again, however, has no effect on other providers
+            that depend on that target.
+            This behavior could change or become configurable in future versions of BitBake.
+        </para>
+
+        <note>
+            Some tasks are marked as "nostamp" tasks.
+            No timestamp file is created when these tasks are run.
+            Consequently, "nostamp" tasks are always rerun.
+        </note>
+    </section>
+
+    <section id='ref-bitbake-runtask'>
+        <title>Running a Task</title>
+
+        <para>
+            Tasks can either be a shell task or a Python task.
+            For shell tasks, BitBake writes a shell script to
+            <filename>${WORKDIR}/temp/run.do_taskname.pid</filename> and then executes the script.
+            The generated shell script contains all the exported variables, and the shell functions
+            with all variables expanded.
+            Output from the shell script goes to the file <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
+            Looking at the expanded shell functions in the run file and the output in the log files
+            is a useful debugging technique.
+        </para>
+
+        <para>
+            For Python tasks, BitBake executes the task internally and logs information to the
+            controlling terminal.
+            Future versions of BitBake will write the functions to files similar to the way
+            shell tasks are handled.
+            Logging will be handled in a way similar to shell tasks as well.
+        </para>
+
+        <para>
+            Once all the tasks have been completed BitBake exits.
+        </para>
+
+        <para>
+            When running a task, BitBake tightly controls the execution environment
+            of the build tasks to make sure unwanted contamination from the build machine
+            cannot influence the build.
+            Consequently, if you do want something to get passed into the build
+            task's environment, you must take a few steps:
+            <orderedlist>
+                <listitem><para>Tell BitBake to load what you want from the environment
+                    into the data store.
+                    You can do so through the <filename>BB_ENV_EXTRAWHITE</filename>
+                    variable.
+                    For example, assume you want to prevent the build system from
+                    accessing your <filename>$HOME/.ccache</filename> directory.
+                    The following command tells BitBake to load
+                    <filename>CCACHE_DIR</filename> from the environment into the data
+                    store:
+                    <literallayout class='monospaced'>
+     export BB_ENV_EXTRAWHITE="$BB_ENV_EXTRAWHITE CCACHE_DIR"
+                    </literallayout></para></listitem>
+                <listitem><para>Tell BitBake to export what you have loaded into the
+                    environment store to the task environment of every running task.
+                    Loading something from the environment into the data store
+                    (previous step) only makes it available in the datastore.
+                    To export it to the task environment of every running task,
+                    use a command similar to the following in your
+                    <filename>local.conf</filename> or distro configuration file:
+                    <literallayout class='monospaced'>
+     export CCACHE_DIR
+                    </literallayout></para></listitem>
+            </orderedlist>
+        </para>
+
+        <note>
+            A side effect of the previous steps is that BitBake records the variable
+            as a dependency of the build process in things like the shared state
+            checksums.
+            If doing so results in unnecessary rebuilds of tasks, you can whitelist the
+            variable so that the shared state code ignores the dependency when it creates
+            checksums.
+            For information on this process, see the <filename>BB_HASHBASE_WHITELIST</filename>
+            example in the "<link linkend='checksums'>Checksums (Signatures)</link>" section.
+        </note>
+    </section>
+
+    <section id='ref-bitbake-commandline'>
+        <title>BitBake Command Line</title>
+
+        <para>
+            Following is the BitBake help output:
+        </para>
+
+        <screen>
+$ bitbake --help
+Usage: bitbake [options] [recipename/target ...]
+
+    Executes the specified task (default is 'build') for a given set of target recipes (.bb files).
+    It is assumed there is a conf/bblayers.conf available in cwd or in BBPATH which
+    will provide the layer, BBFILES and other configuration information.
+
+Options:
+  --version             show program's version number and exit
+  -h, --help            show this help message and exit
+  -b BUILDFILE, --buildfile=BUILDFILE
+                        Execute tasks from a specific .bb recipe directly.
+                        WARNING: Does not handle any dependencies from other
+                        recipes.
+  -k, --continue        Continue as much as possible after an error. While the
+                        target that failed and anything depending on it cannot
+                        be built, as much as possible will be built before
+                        stopping.
+  -a, --tryaltconfigs   Continue with builds by trying to use alternative
+                        providers where possible.
+  -f, --force           Force the specified targets/task to run (invalidating
+                        any existing stamp file).
+  -c CMD, --cmd=CMD     Specify the task to execute. The exact options
+                        available depend on the metadata. Some examples might
+                        be 'compile' or 'populate_sysroot' or 'listtasks' may
+                        give a list of the tasks available.
+  -C INVALIDATE_STAMP, --clear-stamp=INVALIDATE_STAMP
+                        Invalidate the stamp for the specified task such as
+                        'compile' and then run the default task for the
+                        specified target(s).
+  -r PREFILE, --read=PREFILE
+                        Read the specified file before bitbake.conf.
+  -R POSTFILE, --postread=POSTFILE
+                        Read the specified file after bitbake.conf.
+  -v, --verbose         Output more log message data to the terminal.
+  -D, --debug           Increase the debug level. You can specify this more
+                        than once.
+  -n, --dry-run         Don't execute, just go through the motions.
+  -S, --dump-signatures
+                        Don't execute, just dump out the signature
+                        construction information.
+  -p, --parse-only      Quit after parsing the BB recipes.
+  -s, --show-versions   Show current and preferred versions of all recipes.
+  -e, --environment     Show the global or per-package environment complete
+                        with information about where variables were
+                        set/changed.
+  -g, --graphviz        Save dependency tree information for the specified
+                        targets in the dot syntax.
+  -I EXTRA_ASSUME_PROVIDED, --ignore-deps=EXTRA_ASSUME_PROVIDED
+                        Assume these dependencies don't exist and are already
+                        provided (equivalent to ASSUME_PROVIDED). Useful to
+                        make dependency graphs more appealing
+  -l DEBUG_DOMAINS, --log-domains=DEBUG_DOMAINS
+                        Show debug logging for the specified logging domains
+  -P, --profile         Profile the command and save reports.
+  -u UI, --ui=UI        The user interface to use (e.g. knotty, hob, depexp).
+  -t SERVERTYPE, --servertype=SERVERTYPE
+                        Choose which server to use, process or xmlrpc.
+  --revisions-changed   Set the exit code depending on whether upstream
+                        floating revisions have changed or not.
+  --server-only         Run bitbake without a UI, only starting a server
+                        (cooker) process.
+  -B BIND, --bind=BIND  The name/address for the bitbake server to bind to.
+  --no-setscene         Do not run any setscene tasks. sstate will be ignored
+                        and everything needed, built.
+  --remote-server=REMOTE_SERVER
+                        Connect to the specified server.
+  -m, --kill-server     Terminate the remote server.
+  --observe-only        Connect to a server as an observing-only client.
+        </screen>
+    </section>
+
+    <section id='ref-bitbake-fetchers'>
+        <title>Fetchers</title>
+
+        <para>
+            BitBake also contains a set of "fetcher" modules that allow
+            retrieval of source code from various types of sources.
+            For example, BitBake can get source code from a disk with the metadata, from websites,
+            from remote shell accounts, or from Source Code Management (SCM) systems
+            like <filename>cvs/subversion/git</filename>.
+        </para>
+
+        <para>
+            Fetchers are usually triggered by entries in
+            <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>.
+            You can find information about the options and formats of entries for specific
+            fetchers in the BitBake manual located in the
+            <filename>bitbake/doc/manual</filename> directory of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        </para>
+
+        <para>
+            One useful feature for certain Source Code Manager (SCM) fetchers is the ability to
+            "auto-update" when the upstream SCM changes version.
+            Since this ability requires certain functionality from the SCM, not all
+            systems support it.
+            Currently Subversion, Bazaar and to a limited extent, Git support the ability to "auto-update".
+            This feature works using the <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
+            variable.
+            See the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-srcrev'>Using an External SCM</ulink>" section
+            in the Yocto Project Development Manual for more information.
+        </para>
+
+    </section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4 spell spelllang=en_gb
+-->
diff --git a/documentation/ref-manual/ref-classes.xml b/documentation/ref-manual/ref-classes.xml
new file mode 100644
index 0000000000..27edfde33d
--- /dev/null
+++ b/documentation/ref-manual/ref-classes.xml
@@ -0,0 +1,1104 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-classes'>
+<title>Classes</title>
+
+<para>
+    Class files are used to abstract common functionality and share it amongst multiple
+    <filename>.bb</filename> files.
+    Any <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> usually
+    found in a <filename>.bb</filename> file can also be placed in a class
+    file.
+    Class files are identified by the extension <filename>.bbclass</filename> and are usually placed
+    in a <filename>classes/</filename> directory beneath the
+    <filename>meta*/</filename> directory found in the
+    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+    Class files can also be pointed to by
+    <link linkend='var-BUILDDIR'><filename>BUILDDIR</filename></link>
+    (e.g. <filename>build/</filename>) in the same way as
+    <filename>.conf</filename> files in the <filename>conf</filename> directory.
+    Class files are searched for in <link linkend='var-BBPATH'><filename>BBPATH</filename></link>
+    using the same method by which <filename>.conf</filename> files are searched.
+</para>
+
+<para>
+    In most cases inheriting the class is enough to enable its features, although
+    for some classes you might need to set variables or override some of the
+    default behavior.
+</para>
+
+<para>
+    This chapter discusses only the most useful and important classes.
+        Other classes do exist within the <filename>meta/classes</filename>
+        directory in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        You can reference the <filename>.bbclass</filename> files directly
+        for more information.
+</para>
+
+<section id='ref-classes-base'>
+    <title>The base Class - <filename>base.bbclass</filename></title>
+
+    <para>
+        The base class is special in that every <filename>.bb</filename>
+        file inherits it automatically.
+        This class contains definitions for standard basic
+        tasks such as fetching, unpacking, configuring (empty by default), compiling
+        (runs any <filename>Makefile</filename> present), installing (empty by default) and packaging
+        (empty by default).
+        These classes are often overridden or extended by other classes
+        such as <filename>autotools.bbclass</filename> or <filename>package.bbclass</filename>.
+        The class also contains some commonly used functions such as <filename>oe_runmake</filename>.
+    </para>
+</section>
+
+<section id='ref-classes-autotools'>
+    <title>Autotooled Packages - <filename>autotools.bbclass</filename></title>
+
+    <para>
+        Autotools (<filename>autoconf</filename>, <filename>automake</filename>,
+        and <filename>libtool</filename>) bring standardization.
+        This class defines a set of tasks (configure, compile etc.) that
+        work for all Autotooled packages.
+        It should usually be enough to define a few standard variables
+        and then simply <filename>inherit autotools</filename>.
+        This class can also work with software that emulates Autotools.
+        For more information, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-addpkg-autotools'>Autotooled Package</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+
+    <para>
+        It's useful to have some idea of how the tasks defined by this class work
+        and what they do behind the scenes.
+        <itemizedlist>
+            <listitem><para><filename>do_configure</filename> &dash; Regenerates the
+                configure script (using <filename>autoreconf</filename>) and then launches it
+                with a standard set of arguments used during cross-compilation.
+                You can pass additional parameters to <filename>configure</filename> through the
+                <filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link></filename> variable.
+                </para></listitem>
+            <listitem><para><filename>do_compile</filename> &dash; Runs <filename>make</filename> with
+                arguments that specify the compiler and linker.
+                You can pass additional arguments through
+                the <filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link></filename> variable.
+                </para></listitem>
+            <listitem><para><filename>do_install</filename> &dash; Runs <filename>make install</filename>
+                and passes in
+                <filename>${</filename><link linkend='var-D'><filename>D</filename></link><filename>}</filename>
+                as <filename>DESTDIR</filename>.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-update-alternatives'>
+    <title>Alternatives - <filename>update-alternatives.bbclass</filename></title>
+
+    <para>
+        This class helps the alternatives system when multiple sources provide
+        the same command.
+        This situation occurs when several programs that have the same or
+        similar function are installed with the same name.
+        For example, the <filename>ar</filename> command is available from the
+        <filename>busybox</filename>, <filename>binutils</filename> and
+        <filename>elfutils</filename> packages.
+        The <filename>update-alternatives.bbclass</filename> class handles
+        renaming the binaries so that multiple packages can be installed
+        without conflicts.
+        The <filename>ar</filename> command still works regardless of which
+        packages are installed or subsequently removed.
+        The class renames the conflicting binary in each package and symlinks
+        the highest priority binary during installation or removal of packages.
+    </para>
+
+    <para>
+        To use this class, you need to define a number of variables:
+        <itemizedlist>
+            <listitem><para><link linkend='var-ALTERNATIVE'><filename>ALTERNATIVE</filename></link>
+                </para></listitem>
+            <listitem><para><link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
+                </para></listitem>
+            <listitem><para><link linkend='var-ALTERNATIVE_TARGET'><filename>ALTERNATIVE_TARGET</filename></link>
+                </para></listitem>
+            <listitem><para><link linkend='var-ALTERNATIVE_PRIORITY'><filename>ALTERNATIVE_PRIORITY</filename></link>
+                </para></listitem>
+        </itemizedlist>
+        These variables list alternative commands needed by a package,
+        provide pathnames for links, default links for targets, and
+        so forth.
+        For details on how to use this class, see the comments in the
+        <ulink url='&YOCTO_GIT_URL;/cgit/cgit.cgi/poky/tree/meta/classes/update-alternatives.bbclass'><filename>update-alternatives.bbclass</filename></ulink>.
+    </para>
+
+    <note>
+        You can use the <filename>update-alternatives</filename> command
+        directly in your recipes.
+        However, this class simplifies things in most cases.
+    </note>
+</section>
+
+<section id='ref-classes-update-rc.d'>
+    <title>Initscripts - <filename>update-rc.d.bbclass</filename></title>
+
+    <para>
+        This class uses <filename>update-rc.d</filename> to safely install an
+        initialization script on behalf of the package.
+        The OpenEmbedded build system takes care of details such as making sure the script is stopped before
+        a package is removed and started when the package is installed.
+        Three variables control this class:
+        <filename><link linkend='var-INITSCRIPT_PACKAGES'>INITSCRIPT_PACKAGES</link></filename>,
+        <filename><link linkend='var-INITSCRIPT_NAME'>INITSCRIPT_NAME</link></filename> and
+        <filename><link linkend='var-INITSCRIPT_PARAMS'>INITSCRIPT_PARAMS</link></filename>.
+        See the variable links for details.
+    </para>
+</section>
+
+<section id='ref-classes-binconfig'>
+    <title><filename>binconfig.bbclass</filename></title>
+
+    <para>
+        This class helps to correct paths in shell scripts.
+    </para>
+
+    <para>
+        Before <filename>pkg-config</filename> had become widespread, libraries
+        shipped shell scripts to give information about the libraries and
+        include paths needed to build software (usually named
+        <filename>LIBNAME-config</filename>).
+        This class assists any recipe using such scripts.
+    </para>
+
+    <para>
+        During staging, the OpenEmbedded build system installs such scripts
+        into the <filename>sysroots/</filename> directory.
+        Inheriting this class results in all paths in these scripts being
+        changed to point into the <filename>sysroots/</filename> directory so
+        that all builds that use the script use the correct directories
+        for the cross compiling layout.
+        See the
+        <link linkend='var-BINCONFIG_GLOB'><filename>BINCONFIG_GLOB</filename></link>
+        variable for more information.
+    </para>
+</section>
+
+<section id='ref-classes-debian'>
+    <title>Debian Renaming - <filename>debian.bbclass</filename></title>
+
+    <para>
+        This class renames packages so that they follow the Debian naming
+        policy (i.e. <filename>eglibc</filename> becomes <filename>libc6</filename>
+        and <filename>eglibc-devel</filename> becomes <filename>libc6-dev</filename>.)
+    </para>
+</section>
+
+<section id='ref-classes-pkgconfig'>
+    <title>Pkg-config - <filename>pkgconfig.bbclass</filename></title>
+
+    <para>
+        <filename>pkg-config</filename> provides a standard way to get
+        header and library information.
+        This class aims to smooth integration of
+        <filename>pkg-config</filename> into libraries that use it.
+    </para>
+
+    <para>
+        During staging, BitBake installs <filename>pkg-config</filename> data into the
+        <filename>sysroots/</filename> directory.
+        By making use of sysroot functionality within <filename>pkg-config</filename>,
+        this class no longer has to manipulate the files.
+    </para>
+</section>
+
+<section id='ref-classes-archiver'>
+    <title>Archiving Sources - <filename>archive*.bbclass</filename></title>
+
+    <para>
+        Many software licenses require that source code and other materials be
+        released with the binaries.
+        To help with that task, the following classes are provided:
+        <itemizedlist>
+            <listitem><filename>archive-original-sources.bbclass</filename></listitem>
+            <listitem><filename>archive-patched-sources.bbclass</filename></listitem>
+            <listitem><filename>archive-configured-sources.bbclass</filename></listitem>
+            <listitem><filename>archiver.bbclass</filename></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        For more details on the source archiver, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+</section>
+
+<section id='ref-classes-perl'>
+    <title>Perl Modules - <filename>cpan.bbclass</filename></title>
+
+    <para>
+        Recipes for Perl modules are simple.
+        These recipes usually only need to point to the source's archive and then inherit the
+        proper <filename>.bbclass</filename> file.
+        Building is split into two methods depending on which method the module authors used.
+        <itemizedlist>
+            <listitem><para>Modules that use old
+                <filename>Makefile.PL</filename>-based build system require
+                <filename>cpan.bbclass</filename> in their recipes.
+                </para></listitem>
+            <listitem><para>Modules that use
+                <filename>Build.PL</filename>-based build system require
+                using <filename>cpan_build.bbclass</filename> in their recipes.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-distutils'>
+    <title>Python Extensions - <filename>distutils.bbclass</filename></title>
+
+    <para>
+        Recipes for Python extensions are simple.
+        These recipes usually only need to point to the source's archive and then inherit
+        the proper <filename>.bbclass</filename> file.
+        Building is split into two methods depending on which method the module authors used.
+        <itemizedlist>
+            <listitem><para>Extensions that use an Autotools-based build system
+                require Autotools and
+                <filename>distutils</filename>-based
+                <filename>.bbclasse</filename> files in their recipes.
+                </para></listitem>
+            <listitem><para>Extensions that use
+                <filename>distutils</filename>-based build systems require
+                <filename>distutils.bbclass</filename> in their recipes.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-devshell'>
+    <title>Developer Shell - <filename>devshell.bbclass</filename></title>
+
+    <para>
+        This class adds the <filename>devshell</filename> task.
+        Distribution policy dictates whether to include this class.
+        See the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
+        in the Yocto Project Development Manual for more information about using <filename>devshell</filename>.
+    </para>
+</section>
+
+<section id='ref-classes-packagegroup'>
+    <title>Package Groups - <filename>packagegroup.bbclass</filename></title>
+
+    <para>
+        This class sets default values appropriate for package group recipes (e.g.
+        <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>,
+        <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>,
+        <filename><link linkend='var-ALLOW_EMPTY'>ALLOW_EMPTY</link></filename>,
+        and so forth).
+        It is highly recommended that all package group recipes inherit this class.
+    </para>
+    <para>
+        For information on how to use this class, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-customtasks'>Customizing Images Using Custom Package Groups</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+    <para>
+        Previously, this class was named <filename>task.bbclass</filename>.
+    </para>
+</section>
+
+
+<section id='ref-classes-package'>
+    <title>Packaging - <filename>package*.bbclass</filename></title>
+
+    <para>
+        The packaging classes add support for generating packages from a build's
+        output.
+        The core generic functionality is in <filename>package.bbclass</filename>.
+        The code specific to particular package types is contained in various sub-classes such as
+        <filename>package_deb.bbclass</filename>, <filename>package_ipk.bbclass</filename>,
+        and <filename>package_rpm.bbclass</filename>.
+        Most users will want one or more of these classes.
+    </para>
+
+    <para>
+        You can control the list of resulting package formats by using the
+        <filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link></filename>
+        variable defined in the <filename>local.conf</filename> configuration file,
+        which is located in the <filename>conf</filename> folder of the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        When defining the variable, you can specify one or more package types.
+        Since images are generated from packages, a packaging class is
+        needed to enable image generation.
+        The first class listed in this variable is used for image generation.
+    </para>
+
+    <para>
+        If you take the optional step to set up a repository (package feed)
+        on the development host that can be used by Smart, you can
+        install packages from the feed while you are running the image
+        on the target (i.e. runtime installation of packages).
+        For more information, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#using-runtime-package-management'>Using Runtime Package Management</ulink>"
+         section in the Yocto Project Development Manual.
+    </para>
+
+    <para>
+        The package class you choose can affect build-time performance and has space
+        ramifications.
+        In general, building a package with IPK takes about thirty percent less
+        time as compared to using RPM to build the same or similar package.
+        This comparison takes into account a complete build of the package with
+        all dependencies previously built.
+        The reason for this discrepancy is because the RPM package manager
+        creates and processes more
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> than the
+        IPK package manager.
+        Consequently, you might consider setting <filename>PACKAGE_CLASSES</filename>
+        to "package_ipk" if you are building smaller systems.
+    </para>
+
+    <para>
+        Before making your decision on package manager, however, you should
+        consider some further things about using RPM:
+        <itemizedlist>
+            <listitem><para>
+                RPM starts to provide more abilities than IPK due to
+                the fact that it processes more metadata.
+                For example, this information includes individual file types,
+                file checksum generation and evaluation on install, sparse file
+                support, conflict detection and resolution for Multilib systems,
+                ACID style upgrade, and repackaging abilities for rollbacks.
+                </para></listitem>
+            <listitem><para>
+                For smaller systems, the extra space used for the Berkley
+                Database and the amount of metadata when using RPM can affect
+                your ability to perform on-device upgrades.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        You can find additional information on the effects of the package
+        class at these two Yocto Project mailing list links:
+        <itemizedlist>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006362.html'>
+                https://lists.yoctoproject.org/pipermail/poky/2011-May/006362.html</ulink></para></listitem>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/pipermail/poky/2011-May/006363.html'>
+                https://lists.yoctoproject.org/pipermail/poky/2011-May/006363.html</ulink></para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-kernel'>
+    <title>Building Kernels - <filename>kernel.bbclass</filename></title>
+
+    <para>
+        This class handles building Linux kernels.
+        The class contains code to build all kernel trees.
+        All needed headers are staged into the
+        <filename><link linkend='var-STAGING_KERNEL_DIR'>STAGING_KERNEL_DIR</link></filename>
+        directory to allow out-of-tree module builds using <filename>module.bbclass</filename>.
+    </para>
+
+    <para>
+        This means that each built kernel module is packaged separately and inter-module
+        dependencies are created by parsing the <filename>modinfo</filename> output.
+        If all modules are required, then installing the <filename>kernel-modules</filename>
+        package installs all packages with modules and various other kernel packages
+        such as <filename>kernel-vmlinux</filename>.
+    </para>
+
+    <para>
+        Various other classes are used by the kernel and module classes internally including
+        <filename>kernel-arch.bbclass</filename>, <filename>module_strip.bbclass</filename>,
+        <filename>module-base.bbclass</filename>, and <filename>linux-kernel-base.bbclass</filename>.
+    </para>
+</section>
+
+<section id='ref-classes-image'>
+    <title>Creating Images - <filename>image.bbclass</filename> and <filename>rootfs*.bbclass</filename></title>
+
+    <para>
+        These classes add support for creating images in several formats.
+        First, the root filesystem is created from packages using
+        one of the <filename>rootfs_*.bbclass</filename>
+        files (depending on the package format used) and then the image is created.
+        <itemizedlist>
+            <listitem><para>The
+                <filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link></filename>
+                variable controls the types of images to generate.
+                </para></listitem>
+            <listitem><para>The
+                <filename><link linkend='var-IMAGE_INSTALL'>IMAGE_INSTALL</link></filename>
+                variable controls the list of packages to install into the
+                image.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-sanity'>
+    <title>Host System Sanity Checks - <filename>sanity.bbclass</filename></title>
+
+    <para>
+        This class checks to see if prerequisite software is present on the host system
+        so that users can be notified of potential problems that might affect their build.
+        The class also performs basic user configuration checks from
+        the <filename>local.conf</filename> configuration file to
+        prevent common mistakes that cause build failures.
+        Distribution policy usually determines whether to include this class.
+    </para>
+</section>
+
+<section id='ref-classes-insane'>
+<title><filename>insane.bbclass</filename></title>
+
+    <para>
+        This class adds a step to the package generation process so that
+        output quality assurance checks are generated by the OpenEmbedded
+        build system.
+        A range of checks are performed that check the build's output
+        for common problems that show up during runtime.
+        Distribution policy usually dictates whether to include this class.
+    </para>
+
+    <para>
+        You can configure the sanity checks so that specific test failures
+        either raise a warning or an error message.
+        Typically, failures for new tests generate a warning.
+        Subsequent failures for the same test would then generate an error
+        message once the metadata is in a known and good condition.
+    </para>
+
+    <para>
+        Use the
+        <link linkend='var-WARN_QA'><filename>WARN_QA</filename></link> and
+        <link linkend='var-ERROR_QA'><filename>ERROR_QA</filename></link>
+         variables to control the behavior of
+        these checks at the global level (i.e. in your custom distro
+        configuration).
+        However, to skip one or more checks in recipes, you should use
+        <link linkend='var-INSANE_SKIP'><filename>INSANE_SKIP</filename></link>.
+        For example, to skip the check for symbolic link
+        <filename>.so</filename> files in the main package of a recipe,
+        add the following to the recipe.
+        You need to realize that the package name override, in this example
+        <filename>${PN}</filename>, must be used:
+        <literallayout class='monospaced'>
+     INSANE_SKIP_${PN} += "dev-so"
+        </literallayout>
+        Please keep in mind that the QA checks exist in order to detect real
+        or potential problems in the packaged output.
+        So exercise caution when disabling these checks.
+    </para>
+
+    <para>
+        The following list shows the tests you can list with the
+        <filename>WARN_QA</filename> and <filename>ERROR_QA</filename>
+        variables:
+        <itemizedlist>
+            <listitem><para><emphasis><filename>ldflags:</filename></emphasis>
+                Ensures that the binaries were linked with the
+                <filename>LDFLAGS</filename> options provided by the build system.
+                If this test fails, check that the <filename>LDFLAGS</filename> variable
+                is being passed to the linker command.</para></listitem>
+            <listitem><para><emphasis><filename>useless-rpaths:</filename></emphasis>
+                Checks for dynamic library load paths (rpaths) in the binaries that
+                by default on a standard system are searched by the linker (e.g.
+                <filename>/lib</filename> and <filename>/usr/lib</filename>).
+                While these paths will not cause any breakage, they do waste space and
+                are unnecessary.</para></listitem>
+            <listitem><para><emphasis><filename>rpaths:</filename></emphasis>
+                Checks for rpaths in the binaries that contain build system paths such
+                as <filename>TMPDIR</filename>.
+                If this test fails, bad <filename>-rpath</filename> options are being
+                passed to the linker commands and your binaries have potential security
+                issues.</para></listitem>
+            <listitem><para><emphasis><filename>dev-so:</filename></emphasis>
+                Checks that the <filename>.so</filename> symbolic links are in the
+                <filename>-dev</filename> package and not in any of the other packages.
+                In general, these symlinks are only useful for development purposes.
+                Thus, the <filename>-dev</filename> package is the correct location for
+                them.
+                Some very rare cases do exist for dynamically loaded modules where
+                these symlinks are needed instead in the main package.
+                </para></listitem>
+            <listitem><para><emphasis><filename>debug-files:</filename></emphasis>
+                Checks for <filename>.debug</filename> directories in anything but the
+                <filename>-dbg</filename> package.
+                The debug files should all be in the <filename>-dbg</filename> package.
+                Thus, anything packaged elsewhere is incorrect packaging.</para></listitem>
+            <listitem><para><emphasis><filename>arch:</filename></emphasis>
+                Checks the Executable and Linkable Format (ELF) type, bit size, and endianness
+                of any binaries to ensure they match the target architecture.
+                This test fails if any binaries don't match the type since there would be an
+                incompatibility.
+                Sometimes software, like bootloaders, might need to bypass this check.
+                </para></listitem>
+            <listitem><para><emphasis><filename>debug-deps:</filename></emphasis>
+                Checks that <filename>-dbg</filename> packages only depend on other
+                <filename>-dbg</filename> packages and not on any other types of packages,
+                which would cause a packaging bug.</para></listitem>
+            <listitem><para><emphasis><filename>dev-deps:</filename></emphasis>
+                Checks that <filename>-dev</filename> packages only depend on other
+                <filename>-dev</filename> packages and not on any other types of packages,
+                which would be a packaging bug.</para></listitem>
+            <listitem><para><emphasis><filename>pkgconfig:</filename></emphasis>
+                Checks <filename>.pc</filename> files for any
+                <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>/<link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+                paths.
+                Any <filename>.pc</filename> file containing these paths is incorrect
+                since <filename>pkg-config</filename> itself adds the correct sysroot prefix
+                when the files are accessed.</para></listitem>
+            <listitem><para><emphasis><filename>textrel:</filename></emphasis>
+                Checks for ELF binaries that contain relocations in their
+                <filename>.text</filename> sections, which can result in a
+                performance impact at runtime.</para></listitem>
+            <listitem><para><emphasis><filename>pkgvarcheck:</filename></emphasis>
+                Checks through the variables
+                <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
+                <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
+                <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
+                <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>,
+                <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
+                <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
+                <link linkend='var-FILES'><filename>FILES</filename></link>,
+                <link linkend='var-ALLOW_EMPTY'><filename>ALLOW_EMPTY</filename></link>,
+                <filename>pkg_preinst</filename>,
+                <filename>pkg_postinst</filename>,
+                <filename>pkg_prerm</filename>
+                and <filename>pkg_postrm</filename>, and reports if there are
+                variable sets that are not package-specific.
+                Using these variables without a package suffix is bad practice,
+                and might unnecessarily complicate dependencies of other packages
+                within the same recipe or have other unintended consequences.
+                </para></listitem>
+            <listitem><para><emphasis><filename>xorg-driver-abi:</filename></emphasis>
+                Checks that all packages containing Xorg drivers have ABI
+                dependencies.
+                The <filename>xserver-xorg</filename> recipe provides driver
+                ABI names.
+                All drivers should depend on the ABI versions that they have
+                been built against.
+                Driver recipes that include
+                <filename>xorg-driver-input.inc</filename>
+                or <filename>xorg-driver-video.inc</filename> will
+                automatically get these versions.
+                Consequently, you should only need to explicitly add
+                dependencies to binary driver recipes.
+                </para></listitem>
+            <listitem><para><emphasis><filename>libexec:</filename></emphasis>
+                Checks if a package contains files in
+                <filename>/usr/libexec</filename>.
+                This check is not performed if the
+                <filename>libexecdir</filename> variable has been set
+                explicitly to <filename>/usr/libexec</filename>.
+                </para></listitem>
+            <listitem><para><emphasis><filename>staticdev:</filename></emphasis>
+                Checks for static library files (<filename>*.a</filename>) in
+                non-<filename>staticdev</filename> packages.
+                </para></listitem>
+            <listitem><para><emphasis><filename>la:</filename></emphasis>
+                Checks <filename>.la</filename> files for any <filename>TMPDIR</filename>
+                paths.
+                Any <filename>.la</filename> file containing these paths is incorrect since
+                <filename>libtool</filename> adds the correct sysroot prefix when using the
+                files automatically itself.</para></listitem>
+            <listitem><para><emphasis><filename>desktop:</filename></emphasis>
+                Runs the <filename>desktop-file-validate</filename> program
+                against any <filename>.desktop</filename> files to validate
+                their contents against the specification for
+                <filename>.desktop</filename> files.</para></listitem>
+            <listitem><para><emphasis><filename>already-stripped:</filename></emphasis>
+                Checks that produced binaries have not already been
+                stripped prior to the build system extracting debug symbols.
+                It is common for upstream software projects to default to
+                stripping debug symbols for output binaries.
+                In order for debugging to work on the target using
+                <filename>-dbg</filename> packages, this stripping must be
+                disabled.
+                </para></listitem>
+            <listitem><para><emphasis><filename>split-strip:</filename></emphasis>
+                Reports that splitting or stripping debug symbols from binaries
+                has failed.
+                </para></listitem>
+            <listitem><para><emphasis><filename>arch:</filename></emphasis>
+                Checks to ensure the architecture, bit size, and endianness
+                of all output binaries matches that of the target.
+                This test can detect when the wrong compiler or compiler options
+                have been used.
+                </para></listitem>
+            <listitem><para><emphasis><filename>installed-vs-shipped:</filename></emphasis>
+                Reports when files have been installed within
+                <filename>do_install</filename> but have not been included in
+                any package by way of the
+                <link linkend='var-FILES'><filename>FILES</filename></link>
+                variable.
+                Files that do not appear in any package cannot be present in
+                an image later on in the build process.
+                Ideally, all installed files should be packaged or not
+                installed at all.
+                These files can be deleted at the end of
+                <filename>do_install</filename> if the files are not
+                needed in any package.
+                </para></listitem>
+            <listitem><para><emphasis><filename>dep-cmp:</filename></emphasis>
+                Checks for invalid version comparison statements in runtime
+                dependency relationships between packages (i.e. in
+                <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>,
+                <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>,
+                <link linkend='var-RSUGGESTS'><filename>RSUGGESTS</filename></link>,
+                <link linkend='var-RPROVIDES'><filename>RPROVIDES</filename></link>,
+                <link linkend='var-RREPLACES'><filename>RREPLACES</filename></link>,
+                and
+                <link linkend='var-RCONFLICTS'><filename>RCONFLICTS</filename></link>
+                variable values).
+                Any invalid comparisons might trigger failures or undesirable
+                behavior when passed to the package manager.
+                </para></listitem>
+            <listitem><para><emphasis><filename>files-invalid:</filename></emphasis>
+                Checks for
+                <link linkend='var-FILES'><filename>FILES</filename></link>
+                variable values that contain "//", which is invalid.
+                </para></listitem>
+            <listitem><para><emphasis><filename>incompatible-license:</filename></emphasis>
+                Report when packages are excluded from being created due to
+                being marked with a license that is in
+                <link linkend='var-INCOMPATIBLE_LICENSE'><filename>INCOMPATIBLE_LICENSE</filename></link>.
+                </para></listitem>
+            <listitem><para><emphasis><filename>compile-host-path:</filename></emphasis>
+                Checks the <filename>do_compile</filename> log for indications
+                that paths to locations on the build host were used.
+                Using such paths might result in host contamination of the
+                build output.
+                </para></listitem>
+            <listitem><para><emphasis><filename>install-host-path:</filename></emphasis>
+                Checks the <filename>do_install</filename> log for indications
+                that paths to locations on the build host were used.
+                Using such paths might result in host contamination of the
+                build output.
+                </para></listitem>
+            <listitem><para><emphasis><filename>libdir:</filename></emphasis>
+                Checks for libraries being installed into incorrect
+                (possibly hardcoded) installation paths.
+                For example, this test will catch recipes that install
+                <filename>/lib/bar.so</filename> when
+                <filename>${base_libdir}</filename> is "lib32".
+                Another example is when recipes install
+                <filename>/usr/lib64/foo.so</filename> when
+                <filename>${libdir}</filename> is "/usr/lib".
+                </para></listitem>
+            <listitem><para><emphasis><filename>packages-list:</filename></emphasis>
+                Checks for the same package being listed multiple times through
+                the <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
+                variable value.
+                Installing the package in this manner can cause errors during
+                packaging.
+                </para></listitem>
+            <listitem><para><emphasis><filename>perm-config:</filename></emphasis>
+                Reports lines in <filename>fs-perms.txt</filename> that have
+                an invalid format.
+                </para></listitem>
+            <listitem><para><emphasis><filename>perm-line:</filename></emphasis>
+                Reports lines in <filename>fs-perms.txt</filename> that have
+                an invalid format.
+                </para></listitem>
+            <listitem><para><emphasis><filename>perm-link:</filename></emphasis>
+                Reports lines in <filename>fs-perms.txt</filename> that
+                specify 'link' where the specified target already exists.
+                </para></listitem>
+            <listitem><para><emphasis><filename>pkgname:</filename></emphasis>
+                Checks that all packages in
+                <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
+                have names that do not contain invalid characters (i.e.
+                characters other than 0-9, a-z, ., +, and -).
+                </para></listitem>
+            <listitem><para><emphasis><filename>pn-overrides:</filename></emphasis>
+                Checks that a recipe does not have a name
+                (<link linkend='var-PN'><filename>PN</filename></link>) value
+                that appears in
+                <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>.
+                If a recipe is named such that its <filename>PN</filename>
+                value matches something already in
+                <filename>OVERRIDES</filename> (e.g. <filename>PN</filename>
+                happens to be the same as
+                <link linkend='var-MACHINE'><filename>MACHINE</filename></link>
+                or
+                <link linkend='var-DISTRO'><filename>DISTRO</filename></link>),
+                it can have unexpected consequences.
+                For example, assignments such as
+                <filename>FILES_${PN} = "xyz"</filename> effectively turn into
+                <filename>FILES = "xyz"</filename>.
+                </para></listitem>
+            <listitem><para><emphasis><filename>unsafe-references-in-binaries:</filename></emphasis>
+                Reports when a binary installed in
+                <filename>${base_libdir}</filename>,
+                <filename>${base_bindir}</filename>, or
+                <filename>${base_sbindir}</filename>, depends on another
+                binary installed under <filename>${exec_prefix}</filename>.
+                This dependency is a concern if you want the system to remain
+                basically operable if <filename>/usr</filename> is mounted
+                separately and is not mounted.
+                <note>
+                    Defaults for binaries installed in
+                    <filename>${base_libdir}</filename>,
+                    <filename>${base_bindir}</filename>, and
+                    <filename>${base_sbindir}</filename> are
+                    <filename>/lib</filename>, <filename>/bin</filename>, and
+                    <filename>/sbin</filename>, respectively.
+                    The default for a binary installed
+                    under <filename>${exec_prefix}</filename> is
+                    <filename>/usr</filename>.
+                </note>
+                </para></listitem>
+            <listitem><para><emphasis><filename>unsafe-references-in-scripts:</filename></emphasis>
+                Reports when a script file installed in
+                <filename>${base_libdir}</filename>,
+                <filename>${base_bindir}</filename>, or
+                <filename>${base_sbindir}</filename>, depends on files
+                installed under <filename>${exec_prefix}</filename>.
+                This dependency is a concern if you want the system to remain
+                basically operable if <filename>/usr</filename> is mounted
+                separately and is not mounted.
+                <note>
+                    Defaults for binaries installed in
+                    <filename>${base_libdir}</filename>,
+                    <filename>${base_bindir}</filename>, and
+                    <filename>${base_sbindir}</filename> are
+                    <filename>/lib</filename>, <filename>/bin</filename>, and
+                    <filename>/sbin</filename>, respectively.
+                    The default for a binary installed
+                    under <filename>${exec_prefix}</filename> is
+                    <filename>/usr</filename>.
+                </note>
+                </para></listitem>
+            <listitem><para><emphasis><filename>var-undefined:</filename></emphasis>
+                Reports when variables fundamental to packaging (i.e.
+                <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
+                <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>,
+                <link linkend='var-D'><filename>D</filename></link>,
+                <link linkend='var-PN'><filename>PN</filename></link>, and
+                <link linkend='var-PKGD'><filename>PKGD</filename></link>) are
+                undefined during <filename>do_package</filename>.
+                </para></listitem>
+            <listitem><para><emphasis><filename>pkgv-undefined:</filename></emphasis>
+                Checks to see if the <filename>PKGV</filename> variable
+                is undefined during <filename>do_package</filename>.
+                </para></listitem>
+            <listitem><para><emphasis><filename>buildpaths:</filename></emphasis>
+                Checks for paths to locations on the build host inside the
+                output files.
+                Currently, this test triggers too many false positives and
+                thus is not normally enabled.
+                </para></listitem>
+            <listitem><para><emphasis><filename>perms:</filename></emphasis>
+                Currently, this check is unused but reserved.
+                </para></listitem>
+            <listitem><para><emphasis><filename>version-going-backwards:</filename></emphasis>
+                If Build History is enabled, reports when a package
+                being written out has a lower version than the previously
+                written package under the same name.
+                If you are placing output packages into a feed and
+                upgrading packages on a target system using that feed, the
+                version of a package going backwards can result in the target
+                system not correctly upgrading to the "new" version of the
+                package.
+                <note>
+                    If you are not using runtime package management on your
+                    target system, then you do not need to worry about
+                    this situation.
+                </note>
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='ref-classes-rm-work'>
+    <title>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></title>
+
+    <para>
+        The OpenEmbedded build system can use a substantial amount of disk
+        space during the build process.
+        A portion of this space is the work files under the
+        <filename>${TMPDIR}/work</filename> directory for each recipe.
+        Once the build system generates the packages for a recipe, the work
+        files for that recipe are no longer needed.
+        However, by default, the build system preserves these files
+        for inspection and possible debugging purposes.
+        If you would rather have these files deleted to save disk space
+        as the build progresses, you can enable <filename>rm_work</filename>
+        by adding the following to your <filename>local.conf</filename> file,
+        which is found in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+        <literallayout class='monospaced'>
+    INHERIT += "rm_work"
+        </literallayout>
+        If you are modifying and building source code out of the work directory
+        for a recipe, enabling <filename>rm_work</filename> will potentially
+        result in your changes to the source being lost.
+        To exclude some recipes from having their work directories deleted by
+        <filename>rm_work</filename>, you can add the names of the recipe or
+        recipes you are working on to the <filename>RM_WORK_EXCLUDE</filename>
+        variable, which can also be set in your <filename>local.conf</filename>
+        file.
+        Here is an example:
+        <literallayout class='monospaced'>
+    RM_WORK_EXCLUDE += "busybox eglibc"
+        </literallayout>
+    </para>
+</section>
+
+
+<section id='ref-classes-siteinfo'>
+    <title>Autotools Configuration Data Cache - <filename>siteinfo.bbclass</filename></title>
+
+    <para>
+        Autotools can require tests that must execute on the target hardware.
+        Since this is not possible in general when cross compiling, site information is
+        used to provide cached test results so these tests can be skipped over but
+        still make the correct values available.
+        The <filename><link linkend='structure-meta-site'>meta/site directory</link></filename>
+        contains test results sorted into different categories such as architecture, endianness, and
+        the <filename>libc</filename> used.
+        Site information provides a list of files containing data relevant to
+        the current build in the
+        <filename><link linkend='var-CONFIG_SITE'>CONFIG_SITE</link></filename> variable
+        that Autotools automatically picks up.
+    </para>
+
+    <para>
+        The class also provides variables like
+        <filename><link linkend='var-SITEINFO_ENDIANNESS'>SITEINFO_ENDIANNESS</link></filename>
+        and <filename><link linkend='var-SITEINFO_BITS'>SITEINFO_BITS</link></filename>
+        that can be used elsewhere in the metadata.
+    </para>
+
+    <para>
+        Because this class is included from <filename>base.bbclass</filename>, it is always active.
+    </para>
+</section>
+
+<section id='ref-classes-useradd'>
+    <title>Adding Users - <filename>useradd.bbclass</filename></title>
+
+    <para>
+        If you have packages that install files that are owned by custom users or groups,
+        you can use this class to specify those packages and associate the users and groups
+        with those packages.
+        The <filename>meta-skeleton/recipes-skeleton/useradd/useradd-example.bb</filename>
+        recipe in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+        provides a simple example that shows how to add three
+        users and groups to two packages.
+        See the <filename>useradd-example.bb</filename> for more information on how to
+        use this class.
+    </para>
+</section>
+
+<section id='ref-classes-externalsrc'>
+    <title><filename>externalsrc.bbclass</filename></title>
+
+    <para>
+        You can use this class to build software from source code that is
+        external to the OpenEmbedded build system.
+        Building software from an external source tree means that the build
+        system's normal fetch, unpack, and patch process is not used.
+    </para>
+
+    <para>
+        By default, the OpenEmbedded build system uses the
+        <link linkend='var-S'><filename>S</filename></link> and
+        <link linkend='var-B'><filename>B</filename></link> variables to
+        locate unpacked recipe source code and to build it, respectively.
+        When your recipe inherits <filename>externalsrc.bbclass</filename>,
+        you use the
+        <link linkend='var-EXTERNALSRC'><filename>EXTERNALSRC</filename></link>
+        and
+        <link linkend='var-EXTERNALSRC_BUILD'><filename>EXTERNALSRC_BUILD</filename></link>
+        variables to ultimately define <filename>S</filename> and
+        <filename>B</filename>.
+    </para>
+
+    <para>
+        By default, this class expects the source code to support recipe builds
+        that use the <link linkend='var-B'><filename>B</filename></link>
+        variable to point to the directory in which the OpenEmbedded build
+        system places the generated objects built from the recipes.
+        By default, the <filename>B</filename> directory is set to the
+        following, which is separate from the source directory
+        (<filename>S</filename>):
+        <literallayout class='monospaced'>
+     ${WORKDIR}/${BPN}/{PV}/
+        </literallayout>
+        See the glossary entries for the
+        <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>,
+        <link linkend='var-BPN'><filename>BPN</filename></link>,
+        <link linkend='var-PV'><filename>PV</filename></link>,
+    </para>
+
+    <para>
+        For more information on
+        <filename>externalsrc.bbclass</filename>, see the comments in
+        <filename>meta/classes/externalsrc.bbclass</filename> in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        For information on how to use <filename>externalsrc.bbclass</filename>,
+        see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+</section>
+
+<section id='ref-classes-testimage'>
+    <title><filename>testimage.bbclass</filename></title>
+
+    <para>
+        You can use this class to enable running a series of automated tests
+        for images.
+        The class handles loading the tests and starting the image.
+        <note>
+            Currently, there is only support for running these tests
+            under QEMU.
+        </note>
+    </para>
+
+    <para>
+        To use the class, you need to perform steps to set up the
+        environment.
+        The tests are commands that run on the target system over
+        <filename>ssh</filename>.
+        they are written in Python and make use of the
+        <filename>unittest</filename> module.
+    </para>
+
+    <para>
+        For information on how to enable, run, and create new tests, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+        section.
+    </para>
+</section>
+
+<section id='ref-classes-others'>
+    <title>Other Classes</title>
+
+    <para>
+        Thus far, this chapter has discussed only the most useful and important
+        classes.
+        However, other classes exist within the <filename>meta/classes</filename> directory
+        in the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        You can examine the <filename>.bbclass</filename> files directly for more
+        information.
+    </para>
+</section>
+
+<!-- Undocumented classes are:
+        allarch.bbclass
+        archive*.bbclass
+        binconfig.bbclass
+        bin_package.bbclass
+        blacklist.bbclass
+        bootimg.bbclass
+        boot-directdisk.bbclass
+        bugzilla.bbclass
+        buildhistory.bbclass
+        buildstats.bbclass
+        ccache.bbclass
+        chrpath.bbclass
+        clutter.bbclass
+        cmake.bbclass
+        cml1.bbclass
+        copyleft_compliance.bbclass
+        core-image.bbclass
+        cross.bbclass
+        cross-canadian.bbclass
+        crosssdk.bbclass
+        deploy.bbclass
+        distrodata.bbclass
+        distro_features_check.bbclass
+        dummy.bbclass
+        extrausers.bbclass
+        fontcache.bbclass
+        gconf.bbclass
+        gettext.bbclass
+        gnomebase.bbclass
+        gnome.bbclass
+        grub-efi.bbclass
+        gsettings.bbclass
+        gtk-doc.bbclass
+        gtk-icon-cache.bbclass
+        gtk-immodules-cache.bbclass
+        gzipnative.bbclass
+        icecc.bbclass
+        image-empty.bbclass
+        image-live.bbclass
+        image-vmdk.bbclass
+        image-mklibs.bbclass
+        image-prelink.bbclass
+        image-swab.bbclass
+        image_types.bbclass
+        image_types_uboot.bbclass
+        insserv.bbclass
+        kernel-arch.bbclass
+        kernel-module-split.bbclass
+        kernel-yocto.bbclass
+        lib_package.bbclass
+        linux-kernel-base.bbclass
+        license.bbclass
+        logging.bbclass
+        meta.bbclass
+        metadata_scm.bbclass
+        migrate_localcount.bbclass
+        mime.bbclass
+        mirrors.bbclass
+        multilib*.bbclass
+        native.bbclass
+        nativesdk.bbclass
+        oelint.bbclass
+        own-mirrors.bbclass
+        packagedata.bbclass
+        packageinfo.bbclass
+        patch.bbclass
+        perlnative.bbclass
+        pixbufcache.bbclass
+        pkg_distribute.bbclass
+        pkg_metainfo.bbclass
+        populate_sdk*.bbclass
+        prexport.bbclass
+        primport.bbclass
+        prserv.bbclass
+        ptest.bbclass
+        python-dir.bbclass
+        pythonnative.bbclass
+        qemu.bbclass
+        qmake*.bbclass
+        qt4*.bbclass
+        recipe_sanity.bbclass
+        relocatable.bbclass
+        scons.bbclass
+        sdl.bbclass
+        setuptools.bbclass
+        sip.bbclass
+        siteconfig.bbclass
+        sourcepkg.bbclass
+        spdx.bbclass
+        sstate.bbclass
+        staging.bbclass
+        syslinux.bbclass
+        systemd.bbclass
+        terminal.bbclass
+        tinderclient.bbclass
+        toolchain-scripts.bbclass
+        typecheck.bbclass
+        uboot-config.bbclass
+        utility-tasks.bbclass
+        utils.bbclass
+        vala.bbclass
+        waf.bbclass
+-->
+
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/ref-features.xml b/documentation/ref-manual/ref-features.xml
new file mode 100644
index 0000000000..3f216e3a64
--- /dev/null
+++ b/documentation/ref-manual/ref-features.xml
@@ -0,0 +1,334 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-features'>
+    <title>Reference: Features</title>
+
+    <para>
+        This chapter provides a reference of shipped machine and distro features
+        you can include as part of the image, a reference on image types you can
+        build, and a reference on feature backfilling.
+    </para>
+
+    <para>
+        Features provide a mechanism for working out which packages
+        should be included in the generated images.
+        Distributions can select which features they want to support through the
+        <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+        variable, which is set in the <filename>poky.conf</filename> distribution configuration file.
+        Machine features are set in the
+        <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
+        variable, which is set in the machine configuration file and
+        specifies the hardware features for a given machine.
+    </para>
+
+    <para>
+        These two variables combine to work out which kernel modules,
+        utilities, and other packages to include.
+        A given distribution can support a selected subset of features so some machine features might not
+        be included if the distribution itself does not support them.
+    </para>
+
+    <para>
+        One method you can use to determine which recipes are checking to see if a
+        particular feature is contained or not is to <filename>grep</filename> through
+        the <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+        for the feature.
+        Here is an example that discovers the recipes whose build is potentially
+        changed based on a given feature:
+        <literallayout class='monospaced'>
+     $ cd $HOME/poky
+     $ git grep 'contains.*MACHINE_FEATURES.*&lt;feature&gt;'
+        </literallayout>
+    </para>
+
+    <section id='ref-features-distro'>
+        <title>Distro</title>
+
+        <para>
+            The items below are features you can use with
+            <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+            Features do not have a one-to-one correspondence to packages, and they can
+            go beyond simply controlling the installation of a package or packages.
+            Sometimes a feature can influence how certain recipes are built.
+            For example, a feature might determine whether a particular configure option
+            is specified within <filename>do_configure</filename> for a particular
+            recipe.
+        </para>
+
+        <para>
+            This list only represents features as shipped with the Yocto Project metadata:
+            <itemizedlist>
+                <listitem><para><emphasis>alsa:</emphasis> Include ALSA support
+                    (OSS compatibility kernel modules installed if available).
+                    </para></listitem>
+                <listitem><para><emphasis>bluetooth:</emphasis> Include
+                    bluetooth support (integrated BT only).</para></listitem>
+                <listitem><para><emphasis>cramfs:</emphasis> Include CramFS
+                    support.</para></listitem>
+                <listitem><para><emphasis>ext2:</emphasis> Include tools for
+                    supporting for devices with internal HDD/Microdrive for
+                    storing files (instead of Flash only devices).
+                    </para></listitem>
+                <listitem><para><emphasis>ipsec:</emphasis> Include IPSec
+                    support.</para></listitem>
+                <listitem><para><emphasis>ipv6:</emphasis> Include IPv6 support.
+                    </para></listitem>
+                <listitem><para><emphasis>irda:</emphasis> Include Irda support.
+                    </para></listitem>
+                <listitem><para><emphasis>keyboard:</emphasis> Include keyboard
+                    support (e.g. keymaps will be loaded during boot).
+                    </para></listitem>
+                <listitem><para><emphasis>nfs:</emphasis> Include NFS client
+                    support (for mounting NFS exports on device).
+                    </para></listitem>
+                <listitem><para><emphasis>opengl:</emphasis>
+                    Include the Open Graphics Library, which is a
+                    cross-language, multi-platform application programming
+                    interface used for rendering two and three-dimensional
+                    graphics.</para></listitem>
+                <listitem><para><emphasis>pci:</emphasis> Include PCI bus
+                    support.</para></listitem>
+                <listitem><para><emphasis>pcmcia:</emphasis> Include
+                    PCMCIA/CompactFlash support.</para></listitem>
+                <listitem><para><emphasis>ppp:</emphasis> Include PPP dialup
+                    support.</para></listitem>
+                <listitem><para><emphasis>smbfs:</emphasis> Include SMB networks
+                    client support (for mounting Samba/Microsoft Windows shares
+                    on device).</para></listitem>
+                <listitem><para><emphasis>systemd:</emphasis> Include support
+                    for this <filename>init</filename> manager, which is a full
+                    replacement of for <filename>init</filename> with parallel
+                    starting of services, reduced shell overhead, and other
+                    features.
+                    This <filename>init</filename> manager is used by many
+                    distributions.</para></listitem>
+                <listitem><para><emphasis>usbgadget:</emphasis> Include USB
+                    Gadget Device support (for USB networking/serial/storage).
+                    </para></listitem>
+                <listitem><para><emphasis>usbhost:</emphasis> Include USB Host
+                    support (allows to connect external keyboard, mouse,
+                    storage, network etc).</para></listitem>
+                <listitem><para><emphasis>wayland:</emphasis> Include the
+                    Wayland display server protocol and the library that
+                    supports it.</para></listitem>
+                <listitem><para><emphasis>wifi:</emphasis> Include WiFi support
+                    (integrated only).</para></listitem>
+                <listitem><para><emphasis>sdk-pms:</emphasis> Include Package
+                    Management Tools in the
+                    <filename>nativesdk</filename> toolchain tarball.
+                    Including these tools allows for easy sandbox use when
+                    creating the root filesystem while using the SDK tarball.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='ref-features-machine'>
+        <title>Machine</title>
+
+        <para>
+            The items below are features you can use with
+            <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>.
+            Features do not have a one-to-one correspondence to packages, and they can
+            go beyond simply controlling the installation of a package or packages.
+            Sometimes a feature can influence how certain recipes are built.
+            For example, a feature might determine whether a particular configure option
+            is specified within <filename>do_configure</filename> for a particular
+            recipe.
+        </para>
+
+        <para>
+            This feature list only represents features as shipped with the Yocto Project metadata:
+            <itemizedlist>
+                <listitem><para><emphasis>acpi:</emphasis> Hardware has ACPI (x86/x86_64 only)
+                    </para></listitem>
+                <listitem><para><emphasis>alsa:</emphasis> Hardware has ALSA audio drivers
+                    </para></listitem>
+                <listitem><para><emphasis>apm:</emphasis> Hardware uses APM (or APM emulation)
+                    </para></listitem>
+                <listitem><para><emphasis>bluetooth:</emphasis> Hardware has integrated BT
+                    </para></listitem>
+                <listitem><para><emphasis>ext2:</emphasis> Hardware HDD or Microdrive
+                    </para></listitem>
+                <listitem><para><emphasis>irda:</emphasis> Hardware has Irda support
+                    </para></listitem>
+                <listitem><para><emphasis>keyboard:</emphasis> Hardware has a keyboard
+                    </para></listitem>
+                <listitem><para><emphasis>pci:</emphasis> Hardware has a PCI bus
+                    </para></listitem>
+                <listitem><para><emphasis>pcmcia:</emphasis> Hardware has PCMCIA or CompactFlash sockets
+                    </para></listitem>
+                <listitem><para><emphasis>screen:</emphasis> Hardware has a screen
+                    </para></listitem>
+                <listitem><para><emphasis>serial:</emphasis> Hardware has serial support (usually RS232)
+                    </para></listitem>
+                <listitem><para><emphasis>touchscreen:</emphasis> Hardware has a touchscreen
+                    </para></listitem>
+                <listitem><para><emphasis>usbgadget:</emphasis> Hardware is USB gadget device capable
+                    </para></listitem>
+                <listitem><para><emphasis>usbhost:</emphasis> Hardware is USB Host capable
+                    </para></listitem>
+                <listitem><para><emphasis>wifi:</emphasis> Hardware has integrated WiFi
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='ref-features-image'>
+        <title>Images</title>
+
+        <para>
+            The contents of images generated by the OpenEmbedded build system can be controlled by the
+            <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>
+            and <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename>
+            variables that you typically configure in your image recipes.
+            Through these variables, you can add several different
+            predefined packages such as development utilities or packages with debug
+            information needed to investigate application problems or profile applications.
+        </para>
+
+        <para>
+            Current list of
+            <filename>IMAGE_FEATURES</filename> contains the following:
+            <itemizedlist>
+                <listitem><para><emphasis>dbg-pkgs:</emphasis> Installs debug symbol packages for all packages
+                    installed in a given image.</para></listitem>
+                <listitem><para><emphasis>dev-pkgs:</emphasis> Installs development packages (headers and
+                    extra library links) for all packages installed in a given image.</para></listitem>
+                <listitem><para><emphasis>doc-pkgs:</emphasis> Installs documentation packages for all packages
+                    installed in a given image.</para></listitem>
+                <listitem><para><emphasis>nfs-server:</emphasis> Installs an NFS server.</para></listitem>
+                <listitem><para><emphasis>read-only-rootfs:</emphasis> Creates
+                    an image whose root filesystem is read-only.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
+                    section in the Yocto Project Development Manual for more
+                    information.</para></listitem>
+                <listitem><para><emphasis>splash:</emphasis> Enables showing a splash screen during boot.
+                    By default, this screen is provided by <filename>psplash</filename>, which does
+                    allow customization.
+                    If you prefer to use an alternative splash screen package, you can do so by
+                    setting the <filename>SPLASH</filename> variable
+                    to a different package name (or names) within the image recipe or at the distro
+                    configuration level.</para></listitem>
+                <listitem><para><emphasis>ssh-server-dropbear:</emphasis> Installs the Dropbear minimal
+                    SSH server.
+                    </para></listitem>
+                <listitem><para><emphasis>ssh-server-openssh:</emphasis> Installs the OpenSSH SSH server,
+                    which is more full-featured than Dropbear.
+                    Note that if both the OpenSSH SSH server and the Dropbear minimal SSH server
+                    are present in <filename>IMAGE_FEATURES</filename>, then OpenSSH will take
+                    precedence and Dropbear will not be installed.</para></listitem>
+                <listitem><para><emphasis>staticdev-pkgs:</emphasis> Installs static development
+                    packages (i.e. static libraries containing <filename>*.a</filename> files) for all
+                    packages installed in a given image.</para></listitem>
+                <listitem><para><emphasis>tools-debug:</emphasis> Installs debugging tools such as
+                    <filename>strace</filename> and <filename>gdb</filename>.
+                    For information on GDB, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
+                    section in the Yocto Project Development Manual.
+                    For information on tracing and profiling, see the
+                    <ulink url='&YOCTO_DOCS_PROF_URL;'>Yocto Project Profiling and Tracing Manual</ulink>.
+                    </para></listitem>
+                <listitem><para><emphasis>tools-profile:</emphasis> Installs profiling tools such as
+                    <filename>oprofile</filename>, <filename>exmap</filename>, and
+                    <filename>LTTng</filename>.
+                    For general information on user-space tools, see the
+                    "<ulink url='&YOCTO_DOCS_ADT_URL;#user-space-tools'>User-Space Tools</ulink>"
+                    section in the Yocto Project Application Developer's Guide.</para></listitem>
+                <listitem><para><emphasis>tools-sdk:</emphasis> Installs a full SDK that runs on the device.
+                    </para></listitem>
+                <listitem><para><emphasis>tools-testapps:</emphasis> Installs device testing tools (e.g.
+                    touchscreen debugging).</para></listitem>
+                <listitem><para><emphasis>x11:</emphasis> Installs the X server</para></listitem>
+                <listitem><para><emphasis>x11-base:</emphasis> Installs the X server with a
+                    minimal environment.</para></listitem>
+                <listitem><para><emphasis>x11-sato:</emphasis> Installs the OpenedHand Sato environment.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='ref-features-backfill'>
+        <title>Feature Backfilling</title>
+
+        <para>
+            Sometimes it is necessary in the OpenEmbedded build system to extend
+            <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
+            or <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>
+            to control functionality that was previously enabled and not able
+            to be disabled.
+            For these cases, we need to add an
+            additional feature item to appear in one of these variables,
+            but we do not want to force developers who have existing values
+            of the variables in their configuration to add the new feature
+            in order to retain the same overall level of functionality.
+            Thus, the OpenEmbedded build system has a mechanism to
+            automatically "backfill" these added features into existing
+            distro or machine configurations.
+            You can see the list of features for which this is done by
+            finding the
+            <link linkend='var-DISTRO_FEATURES_BACKFILL'><filename>DISTRO_FEATURES_BACKFILL</filename></link>
+            and <link linkend='var-MACHINE_FEATURES_BACKFILL'><filename>MACHINE_FEATURES_BACKFILL</filename></link>
+            variables in the <filename>meta/conf/bitbake.conf</filename> file.
+        </para>
+
+        <para>
+            Because such features are backfilled by default into all
+            configurations as described in the previous paragraph, developers
+            who wish to disable the new features need to be able to selectively
+            prevent the backfilling from occurring.
+            They can do this by adding the undesired feature or features to the
+            <link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename></link>
+            or <link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename></link>
+            variables for distro features and machine features respectively.
+        </para>
+
+        <para>
+            Here are two examples to help illustrate feature backfilling:
+            <itemizedlist>
+                <listitem><para><emphasis>The "pulseaudio" distro feature option</emphasis>:
+                    Previously, PulseAudio support was enabled within the Qt and
+                    GStreamer frameworks.
+                    Because of this, the feature is backfilled and thus
+                    enabled for all distros through the
+                    <filename>DISTRO_FEATURES_BACKFILL</filename>
+                    variable in the <filename>meta/conf/bitbake.conf</filename> file.
+                    However, your distro needs to disable the feature.
+                    You can disable the feature without affecting
+                    other existing distro configurations that need PulseAudio support
+                    by adding "pulseaudio" to
+                    <filename>DISTRO_FEATURES_BACKFILL_CONSIDERED</filename>
+                    in your distro's <filename>.conf</filename> file.
+                    Adding the feature to this variable when it also
+                    exists in the <filename>DISTRO_FEATURES_BACKFILL</filename>
+                    variable prevents the build system from adding the feature to
+                    your configuration's <filename>DISTRO_FEATURES</filename>, effectively disabling
+                    the feature for that particular distro.</para></listitem>
+                <listitem><para><emphasis>The "rtc" machine feature option</emphasis>:
+                    Previously, real time clock (RTC) support was enabled for all
+                    target devices.
+                    Because of this, the feature is backfilled and thus enabled
+                    for all machines through the <filename>MACHINE_FEATURES_BACKFILL</filename>
+                    variable in the <filename>meta/conf/bitbake.conf</filename> file.
+                    However, your target device does not have this capability.
+                    You can disable RTC support for your device without
+                    affecting other machines that need RTC support
+                    by adding the feature to your machine's
+                    <filename>MACHINE_FEATURES_BACKFILL_CONSIDERED</filename>
+                    list in the machine's <filename>.conf</filename> file.
+                    Adding the feature to this variable when it also
+                    exists in the <filename>MACHINE_FEATURES_BACKFILL</filename>
+                    variable prevents the build system from adding the feature to
+                    your configuration's <filename>MACHINE_FEATURES</filename>, effectively
+                    disabling RTC support for that particular machine.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</chapter>
+
+<!--
+vim: expandtab tw=80 ts=4 spell spelllang=en_gb
+-->
diff --git a/documentation/ref-manual/ref-images.xml b/documentation/ref-manual/ref-images.xml
new file mode 100644
index 0000000000..37c8051a26
--- /dev/null
+++ b/documentation/ref-manual/ref-images.xml
@@ -0,0 +1,150 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-images'>
+    <title>Images</title>
+
+    <para>
+        The OpenEmbedded build system provides several example
+        images to satisfy different needs.
+        When you issue the <filename>bitbake</filename> command you provide a “top-level” recipe
+        that essentially begins the build for the type of image you want.
+    </para>
+
+    <note>
+        Building an image without GNU General Public License Version 3 (GPLv3) components
+        is only supported for minimal and base images.
+        Furthermore, if you are going to build an image using non-GPLv3 components,
+        you must make the following changes in the <filename>local.conf</filename> file
+        before using the BitBake command to build the minimal or base image:
+        <literallayout class='monospaced'>
+     1. Comment out the EXTRA_IMAGE_FEATURES line
+     2. Set INCOMPATIBLE_LICENSE = "GPLv3"
+        </literallayout>
+    </note>
+
+    <para>
+        From within the <filename>poky</filename> Git repository, use the following command to list
+        the supported images:
+        <literallayout class='monospaced'>
+     $ ls meta*/recipes*/images/*.bb
+        </literallayout>
+        These recipes reside in the <filename>meta/recipes-core/images</filename>,
+        <filename>meta/recipes-extended/images</filename>,
+        <filename>meta/recipes-graphics/images</filename>,
+        <filename>meta/recipes-qt/images</filename>,
+        <filename>meta/recipes-rt/images</filename>,
+        <filename>meta/recipes-sato/images</filename>, and
+        <filename>meta-skeleton/recipes-multilib/images</filename> directories
+        within the <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        Although the recipe names are somewhat explanatory, here is a list that describes them:
+    </para>
+
+    <itemizedlist>
+        <listitem><para><emphasis><filename>build-appliance-image</filename>:</emphasis>
+            An example virtual machine that contains all the pieces required to
+            run builds using the build system as well as the build system itself.
+            You can boot and run the image using either the
+            <ulink url='http://www.vmware.com/products/player/overview.html'>VMware Player</ulink>
+            or <ulink url='http://www.vmware.com/products/workstation/overview.html'>VMware Workstation</ulink>.
+            For more information on this image, see the
+            <ulink url='&YOCTO_HOME_URL;/documentation/build-appliance'>Build Appliance</ulink> page on
+            the Yocto Project website.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-base</filename>:</emphasis>
+            A console-only image that fully supports the target device hardware.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-minimal</filename>:</emphasis>
+            A small image just capable of allowing a device to boot.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-minimal-dev</filename>:</emphasis>
+            A <filename>core-image-minimal</filename> image suitable for development work
+            using the host.
+            The image includes headers and libraries you can use in a host development
+            environment.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-minimal-initramfs</filename>:</emphasis>
+            A <filename>core-image-minimal</filename> image that has the Minimal RAM-based
+            Initial Root Filesystem (<filename>initramfs</filename>) as part of the kernel,
+            which allows the system to find the first “init” program more efficiently.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-minimal-mtdutils</filename>:</emphasis>
+            A <filename>core-image-minimal</filename> image that has support
+            for the Minimal MTD Utilities, which let the user interact with the
+            MTD subsystem in the kernel to perform operations on flash devices.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-basic</filename>:</emphasis>
+            A console-only image with more full-featured Linux system
+            functionality installed.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-lsb</filename>:</emphasis>
+            An image that conforms to the Linux Standard Base (LSB) specification.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-lsb-dev</filename>:</emphasis>
+            A <filename>core-image-lsb</filename> image that is suitable for development work
+            using the host.
+            The image includes headers and libraries you can use in a host development
+            environment.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-lsb-sdk</filename>:</emphasis>
+            A <filename>core-image-lsb</filename> that includes everything in meta-toolchain
+            but also includes development headers and libraries to form a complete standalone SDK.
+            This image is suitable for development using the target.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-clutter</filename>:</emphasis>
+            An image with support for the Open GL-based toolkit Clutter, which enables development of
+            rich and animated graphical user interfaces.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-gtk-directfb</filename>:</emphasis>
+            An image that uses <filename>gtk+</filename> over <filename>directfb</filename>
+            instead of X11.
+            In order to build, this image requires specific distro configuration that enables
+            <filename>gtk</filename> over <filename>directfb</filename>.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-x11</filename>:</emphasis>
+            A very basic X11 image with a terminal.
+            </para></listitem>
+        <listitem><para><emphasis><filename>qt4e-demo-image</filename>:</emphasis>
+            An image that launches into the demo application for the embedded
+            (not based on X11) version of Qt.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-rt</filename>:</emphasis>
+            A <filename>core-image-minimal</filename> image plus a real-time test suite and
+            tools appropriate for real-time use.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-rt-sdk</filename>:</emphasis>
+            A <filename>core-image-rt</filename> image that includes everything in
+            <filename>meta-toolchain</filename>.
+            The image also includes development headers and libraries to form a complete
+            stand-alone SDK and is suitable for development using the target.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-sato</filename>:</emphasis>
+            An image with Sato support, a mobile environment and visual style that works well
+            with mobile devices.
+            The image supports X11 with a Sato theme and applications such as
+            a terminal, editor, file manager, media player, and so forth.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-sato-dev</filename>:</emphasis>
+            A <filename>core-image-sato</filename> image suitable for development
+            using the host.
+            The image includes libraries needed to build applications on the device itself,
+            testing and profiling tools, and debug symbols.
+            This image was formerly <filename>core-image-sdk</filename>.
+            </para></listitem>
+        <listitem><para><emphasis><filename>core-image-sato-sdk</filename>:</emphasis>
+            A <filename>core-image-sato</filename> image that includes everything in meta-toolchain.
+            The image also includes development headers and libraries to form a complete standalone SDK
+            and is suitable for development using the target.</para></listitem>
+        <listitem><para><emphasis><filename>core-image-multilib-example</filename>:</emphasis>
+            An example image that includes a <filename>lib32</filename> version
+            of Bash into an otherwise standard <filename>sato</filename> image.
+            The image assumes a "lib32" multilib has been enabled in the your
+            configuration.</para></listitem>
+    </itemizedlist>
+
+    <tip>
+        From the Yocto Project release 1.1 onwards, <filename>-live</filename> and
+        <filename>-directdisk</filename> images have been replaced by a "live"
+        option in <filename>IMAGE_FSTYPES</filename> that will work with any image to produce an
+        image file that can be
+        copied directly to a CD or USB device and run as is.
+        To build a live image, simply add
+        "live" to <filename>IMAGE_FSTYPES</filename> within the <filename>local.conf</filename>
+        file or wherever appropriate and then build the desired image as normal.
+    </tip>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/ref-manual-customization.xsl b/documentation/ref-manual/ref-manual-customization.xsl
new file mode 100644
index 0000000000..3ad3a315c0
--- /dev/null
+++ b/documentation/ref-manual/ref-manual-customization.xsl
@@ -0,0 +1,11 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+  
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+
+  <xsl:param name="html.stylesheet" select="'ref-style.css'" />
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel" select="A" />
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/ref-manual/ref-manual-eclipse-customization.xsl b/documentation/ref-manual/ref-manual-eclipse-customization.xsl
new file mode 100644
index 0000000000..4e6b7997b8
--- /dev/null
+++ b/documentation/ref-manual/ref-manual-eclipse-customization.xsl
@@ -0,0 +1,27 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+        xmlns="http://www.w3.org/1999/xhtml"
+        xmlns:fo="http://www.w3.org/1999/XSL/Format"
+        version="1.0">
+
+  <xsl:import
+          href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="chunk.quietly" select="1"/>
+  <xsl:param name="chunk.first.sections" select="1"/>
+  <xsl:param name="chunk.section.depth" select="10"/>
+  <xsl:param name="use.id.as.filename" select="1"/>
+  <xsl:param name="ulink.target" select="'_self'" />
+  <xsl:param name="base.dir" select="'html/ref-manual/'"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="chapter.autolabel" select="1" />
+  <xsl:param name="appendix.autolabel">A</xsl:param>
+  <xsl:param name="section.autolabel" select="1" />
+  <xsl:param name="section.label.includes.component.label" select="1" />
+</xsl:stylesheet>
diff --git a/documentation/ref-manual/ref-manual.xml b/documentation/ref-manual/ref-manual.xml
new file mode 100644
index 0000000000..7db880b404
--- /dev/null
+++ b/documentation/ref-manual/ref-manual.xml
@@ -0,0 +1,138 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<book id='ref-manual' lang='en'
+      xmlns:xi="http://www.w3.org/2003/XInclude"
+      xmlns="http://docbook.org/ns/docbook"
+      >
+    <bookinfo>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref='figures/poky-title.png'
+                    format='SVG'
+                    align='left' scalefit='1' width='100%'/>
+            </imageobject>
+        </mediaobject>
+
+        <title>
+            Yocto Project Reference Manual
+        </title>
+
+        <authorgroup>
+            <author>
+                <firstname>Richard</firstname> <surname>Purdie</surname>
+                <affiliation>
+                    <orgname>Linux Foundation</orgname>
+                </affiliation>
+                <email>richard.purdie@linuxfoundation.org</email>
+            </author>
+
+        </authorgroup>
+
+        <revhistory>
+            <revision>
+                <revnumber>4.0+git</revnumber>
+                <date>24 November 2010</date>
+                <revremark>Released with the Yocto Project 0.9 Release</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.0</revnumber>
+                <date>6 April 2011</date>
+                <revremark>Released with the Yocto Project 1.0 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.0.1</revnumber>
+                <date>23 May 2011</date>
+                <revremark>Released with the Yocto Project 1.0.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.1</revnumber>
+                <date>6 October 2011</date>
+                <revremark>Released with the Yocto Project 1.1 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.2</revnumber>
+                <date>April 2012</date>
+                <revremark>Released with the Yocto Project 1.2 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.3</revnumber>
+                <date>October 2012</date>
+                <revremark>Released with the Yocto Project 1.3 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.4</revnumber>
+                <date>April 2013</date>
+                <revremark>Released with the Yocto Project 1.4 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5</revnumber>
+                <date>October 2013</date>
+                <revremark>Released with the Yocto Project 1.5 Release.</revremark>
+            </revision>
+            <revision>
+                <revnumber>1.5.1</revnumber>
+                <date>Sometime in 2013</date>
+                <revremark>Released with the Yocto Project 1.5.1 Release.</revremark>
+            </revision>
+        </revhistory>
+
+    <copyright>
+      <year>&COPYRIGHT_YEAR;</year>
+      <holder>Linux Foundation</holder>
+    </copyright>
+
+    <legalnotice>
+      <para>
+        Permission is granted to copy, distribute and/or modify this document under
+        the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
+      </para>
+      <note>
+          For the latest version of this manual associated with this
+          Yocto Project release, see the
+          <ulink url='&YOCTO_DOCS_REF_URL;'>Yocto Project Reference Manual</ulink>
+          from the Yocto Project website.
+      </note>
+    </legalnotice>
+
+    </bookinfo>
+
+    <xi:include href="introduction.xml"/>
+
+    <xi:include href="usingpoky.xml"/>
+
+    <xi:include href="closer-look.xml"/>
+
+    <xi:include href="technical-details.xml"/>
+
+    <xi:include href="migration.xml"/>
+
+    <xi:include href="ref-structure.xml"/>
+
+    <xi:include href="ref-bitbake.xml"/>
+
+    <xi:include href="ref-classes.xml"/>
+
+    <xi:include href="ref-images.xml"/>
+
+    <xi:include href="ref-features.xml"/>
+
+    <xi:include href="ref-variables.xml"/>
+
+    <xi:include href="ref-varlocality.xml"/>
+
+    <xi:include href="faq.xml"/>
+
+    <xi:include href="resources.xml"/>
+
+<!--    <index id='index'>
+      <title>Index</title>
+    </index>
+-->
+
+</book>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
new file mode 100644
index 0000000000..13803f5a41
--- /dev/null
+++ b/documentation/ref-manual/ref-structure.xml
@@ -0,0 +1,953 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-structure'>
+
+<title>Source Directory Structure</title>
+
+<para>
+    The <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> consists of several components.
+    Understanding them and knowing where they are located is key to using the Yocto Project well.
+    This chapter describes the Source Directory and gives information about the various
+    files and directories.
+</para>
+
+<para>
+    For information on how to establish a local Source Directory on your development system, see the
+    "<ulink url='&YOCTO_DOCS_DEV_URL;#getting-setup'>Getting Set Up</ulink>"
+    section in the Yocto Project Development Manual.
+</para>
+
+<note>
+    The OpenEmbedded build system does not support file or directory names that
+    contain spaces.
+    Be sure that the Source Directory you use does not contain these types
+    of names.
+</note>
+
+<section id='structure-core'>
+    <title>Top-Level Core Components</title>
+
+    <para>
+        This section describes the top-level components of the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+    </para>
+
+    <section id='structure-core-bitbake'>
+        <title><filename>bitbake/</filename></title>
+
+        <para>
+            This directory includes a copy of BitBake for ease of use.
+            The copy usually matches the current stable BitBake release from the BitBake project.
+            BitBake, a
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+            interpreter, reads the Yocto Project metadata and runs the tasks
+            defined by that data.
+            Failures are usually from the metadata and not from BitBake itself.
+            Consequently, most users do not need to worry about BitBake.
+        </para>
+
+        <para>
+            When you run the <filename>bitbake</filename> command, the wrapper script in
+            <filename>scripts/</filename> is executed to run the main BitBake executable,
+            which resides in the <filename>bitbake/bin/</filename> directory.
+            Sourcing the <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
+            script places the <filename>scripts</filename> and <filename>bitbake/bin</filename>
+            directories (in that order) into the shell's <filename>PATH</filename> environment
+            variable.
+        </para>
+
+        <para>
+            For more information on BitBake, see the BitBake documentation
+            included in the <filename>bitbake/doc/manual</filename> directory of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        </para>
+    </section>
+
+    <section id='structure-core-build'>
+        <title><filename>build/</filename></title>
+
+        <para>
+            This directory contains user configuration files and the output
+            generated by the OpenEmbedded build system in its standard configuration where
+            the source tree is combined with the output.
+            The <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            is created initially when you <filename>source</filename>
+            the OpenEmbedded build environment setup script 
+            (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+        </para>
+
+        <para>
+            It is also possible to place output and configuration
+            files in a directory separate from the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            by providing a directory name when you <filename>source</filename>
+            the setup script.
+            For information on separating output from your local
+            Source Directory files, see the
+            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            and
+            "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
+            sections.
+        </para>
+    </section>
+
+    <section id='handbook'>
+        <title><filename>documentation</filename></title>
+
+        <para>
+            This directory holds the source for the Yocto Project documentation
+            as well as templates and tools that allow you to generate PDF and HTML
+            versions of the manuals.
+            Each manual is contained in a sub-folder.
+            For example, the files for this manual reside in
+            <filename>ref-manual</filename>.
+        </para>
+    </section>
+
+    <section id='structure-core-meta'>
+        <title><filename>meta/</filename></title>
+
+        <para>
+            This directory contains the OpenEmbedded Core metadata.
+            The directory holds recipes, common classes, and machine
+            configuration for emulated targets (<filename>qemux86</filename>,
+            <filename>qemuarm</filename>, and so forth.)
+        </para>
+    </section>
+
+    <section id='structure-core-meta-yocto'>
+        <title><filename>meta-yocto/</filename></title>
+
+        <para>
+            This directory contains the configuration for the Poky
+            reference distribution.
+        </para>
+    </section>
+
+    <section id='structure-core-meta-yocto-bsp'>
+        <title><filename>meta-yocto-bsp/</filename></title>
+
+        <para>
+            This directory contains the Yocto Project reference
+            hardware Board Support Packages (BSPs).
+            For more information on BSPs, see the
+            <ulink url='&YOCTO_DOCS_BSP_URL;'>Yocto Project Board Support
+            Package (BSP) Developer's Guide</ulink>.
+        </para>
+    </section>
+
+    <section id='structure-meta-hob'>
+        <title><filename>meta-hob/</filename></title>
+
+        <para>
+            This directory contains template recipes used by Hob,
+            which is a Yocto Project build user interface.
+            For more information on the Hob, see the
+            <ulink url='&YOCTO_HOME_URL;/tools-resources/projects/hob'>Hob Project</ulink>
+            web page.
+        </para>
+    </section>
+
+    <section id='structure-meta-skeleton'>
+        <title><filename>meta-skeleton/</filename></title>
+
+        <para>
+            This directory contains template recipes for BSP and kernel development.
+        </para>
+    </section>
+
+    <section id='structure-core-scripts'>
+        <title><filename>scripts/</filename></title>
+
+        <para>
+            This directory contains various integration scripts that implement
+            extra functionality in the Yocto Project environment (e.g. QEMU scripts).
+            The <link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>
+            and
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
+            scripts append this directory to the shell's
+            <filename>PATH</filename> environment variable.
+        </para>
+
+        <para>
+            The <filename>scripts</filename> directory has useful scripts that assist contributing
+            back to the Yocto Project, such as <filename>create_pull_request</filename> and
+            <filename>send_pull_request</filename>.
+        </para>
+    </section>
+
+    <section id='structure-core-script'>
+        <title><filename>&OE_INIT_FILE;</filename></title>
+
+        <para>
+            This script is one of two scripts that set up the OpenEmbedded build 
+            environment.
+            For information on the other script, see the 
+            "<link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>"
+            section.
+        </para>
+
+        <para>
+            Running this script with the <filename>source</filename> command in
+            a shell makes changes to <filename>PATH</filename> and sets other
+            core BitBake variables based on the current working directory.
+            You need to run an environment setup script before running BitBake 
+            commands.
+            The script uses other scripts within the
+            <filename>scripts</filename> directory to do the bulk of the work.
+        </para>
+
+        <para>
+            By default, running this script without a
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            argument creates the <filename>build</filename> directory.
+            If you provide a Build Directory argument when you
+            <filename>source</filename> the script, you direct the OpenEmbedded
+            build system to create a Build Directory of your choice.
+            For example, the following command creates a Build Directory named
+            <filename>mybuilds</filename> that is outside of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
+            <literallayout class='monospaced'>
+     $ source &OE_INIT_FILE; ~/mybuilds
+            </literallayout>
+            <note>
+                The OpenEmbedded build system does not support file or directory names that
+                contain spaces.
+                If you attempt to run the <filename>&OE_INIT_FILE;</filename> script
+                from a Source Directory that contains spaces in either the filenames
+                or directory names, the script returns an error indicating no such
+                file or directory.
+                Be sure to use a Source Directory free of names containing spaces.
+            </note>
+        </para>
+    </section>
+
+    <section id='structure-memres-core-script'>
+        <title><filename>oe-init-build-env-memres</filename></title>
+
+        <para>
+            This script is one of two scripts that set up the OpenEmbedded build 
+            environment.
+            Setting up the environment with this script uses a 
+            memory-resident BitBake.
+            For information on the other setup script, see the 
+            "<link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>"
+            section.
+        </para>
+
+        <para>
+            Memory-resident BitBake resides in memory until you specifically
+            remove it using the following BitBake command:
+            <literallayout class='monospaced'>
+     $ bitbake -m
+            </literallayout>
+        </para>
+
+        <para>
+            Running this script with the <filename>source</filename> command in
+            a shell makes changes to <filename>PATH</filename> and sets other
+            core BitBake variables based on the current working directory.
+            One of these variables is the 
+            <link linkend='var-BBSERVER'><filename>BBSERVER</filename></link>
+            variable, which allows the OpenEmbedded build system to locate 
+            the server that is running BitBake.
+        </para>
+
+        <para>
+            You need to run an environment setup script before running BitBake 
+            commands.
+            Following is the script syntax:
+            <literallayout class='monospaced'>
+     $ source oe-init-build-env-memres &lt;port_number&gt; &lt;build_dir&gt;
+            </literallayout>
+            The script uses other scripts within the
+            <filename>scripts</filename> directory to do the bulk of the work.
+        </para>
+
+        <para>
+            If you do not provide a port number with the script, the default
+            port "12345" is used.
+        </para>
+
+        <para>
+            By default, running this script without a
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            argument creates the <filename>build</filename> directory.
+            If you provide a Build Directory argument when you
+            <filename>source</filename> the script, you direct the OpenEmbedded
+            build system to create a Build Directory of your choice.
+            For example, the following command uses the default port number
+            "12345" and creates a Build Directory named
+            <filename>mybuilds</filename> that is outside of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
+            <literallayout class='monospaced'>
+     $ source oe-init-build-env-memres ~/mybuilds
+            </literallayout>
+            <note>
+                The OpenEmbedded build system does not support file or 
+                directory names that contain spaces.
+                If you attempt to run the 
+                <filename>oe-init-build-env-memres</filename> script
+                from a Source Directory that contains spaces in either the 
+                filenames or directory names, the script returns an error 
+                indicating no such file or directory.
+                Be sure to use a Source Directory free of names containing 
+                spaces.
+            </note>
+        </para>
+    </section>
+
+    <section id='structure-basic-top-level'>
+        <title><filename>LICENSE, README, and README.hardware</filename></title>
+
+        <para>
+            These files are standard top-level files.
+        </para>
+    </section>
+</section>
+
+<section id='structure-build'>
+    <title>The Build Directory - <filename>build/</filename></title>
+
+    <para>
+        The OpenEmbedded build system creates the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+        during the build.
+        By default, this directory is named <filename>build</filename>.
+    </para>
+
+    <section id='structure-build-pseudodone'>
+        <title><filename>build/pseudodone</filename></title>
+
+        <para>
+            This tag file indicates that the initial pseudo binary was created.
+            The file is built the first time BitBake is invoked.
+        </para>
+    </section>
+
+    <section id='structure-build-conf-local.conf'>
+        <title><filename>build/conf/local.conf</filename></title>
+
+        <para>
+            This configuration file contains all the local user configurations 
+            for your build environment.
+            The <filename>local.conf</filename> file contains documentation on 
+            the various configuration options.
+            Any variable set here overrides any variable set elsewhere within 
+            the environment unless that variable is hard-coded within a file 
+            (e.g. by using '=' instead of '?=').
+            Some variables are hard-coded for various reasons but these 
+            variables are relatively rare.
+        </para>
+
+        <para>
+            Edit this file to set the 
+            <filename><link linkend='var-MACHINE'>MACHINE</link></filename>
+            for which you want to build, which package types you wish to use
+            (<link linkend='var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></link>),
+            the location from which you want to downloaded files
+            (<filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>),
+            and how you want your host machine to use resources
+            (<link linkend='var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></link> 
+            and
+            <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>).
+        </para>
+
+        <para>
+            If <filename>local.conf</filename> is not present when you 
+            start the build, the OpenEmbedded build system creates it from 
+            <filename>local.conf.sample</filename> when
+            you <filename>source</filename> the top-level build environment 
+            setup script (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or 
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+        </para>
+
+        <para>
+            The source <filename>local.conf.sample</filename> file used 
+            depends on the <filename>$TEMPLATECONF</filename> script variable,
+            which defaults to <filename>/meta-yocto/conf</filename>
+            when you are building from the Yocto Project development 
+            environment and defaults to <filename>/meta/conf</filename> when 
+            you are building from the OpenEmbedded Core environment.
+            Because the script variable points to the source of the 
+            <filename>local.conf.sample</filename> file, this implies that 
+            you can configure your build environment from any layer by setting     
+            the variable in the top-level build environment setup script as 
+            follows:
+            <literallayout class='monospaced'>
+     TEMPLATECONF=&lt;your_layer&gt;/conf
+            </literallayout>
+            Once the build process gets the sample file, it uses 
+            <filename>sed</filename> to substitute final 
+            <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename> 
+            values for all <filename>##OEROOT##</filename> values.
+            <note>
+                You can see how the <filename>TEMPLATECONF</filename> variable
+                is used by looking at the       
+                <filename>/scripts/oe-setup-builddir</filename> script in the 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                You can find the Yocto Project version of the 
+                <filename>local.conf.sample</filename> file in the 
+                <filename>/meta-yocto/conf</filename> directory.                
+            </note>
+        </para>
+    </section>
+
+    <section id='structure-build-conf-bblayers.conf'>
+        <title><filename>build/conf/bblayers.conf</filename></title>
+
+        <para>
+            This configuration file defines
+            <ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>layers</ulink>,
+            which are directory trees, traversed (or walked) by BitBake.
+            The <filename>bblayers.conf</filename> file uses the
+            <link linkend='var-BBLAYERS'><filename>BBLAYERS</filename></link> 
+            variable to list the layers BitBake tries to find, and uses the
+            <link linkend='var-BBLAYERS_NON_REMOVABLE'><filename>BBLAYERS_NON_REMOVABLE</filename></link>
+            variable to list layers that must not be removed.
+        </para>
+
+        <para>
+            If <filename>bblayers.conf</filename> is not present when you 
+            start the build, the OpenEmbedded build system creates it from 
+            <filename>bblayers.conf.sample</filename> when
+            you <filename>source</filename> the top-level build environment 
+            setup script (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or 
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+        </para>
+
+        <para>
+            The source <filename>bblayers.conf.sample</filename> file used 
+            depends on the <filename>$TEMPLATECONF</filename> script variable,
+            which defaults to <filename>/meta-yocto/conf</filename>
+            when you are building from the Yocto Project development 
+            environment and defaults to <filename>/meta/conf</filename> when 
+            you are building from the OpenEmbedded Core environment.
+            Because the script variable points to the source of the 
+            <filename>bblayers.conf.sample</filename> file, this implies that 
+            you can base your build from any layer by setting the variable in
+            the top-level build environment setup script as follows:
+            <literallayout class='monospaced'>
+     TEMPLATECONF=&lt;your_layer&gt;/conf
+            </literallayout>
+            Once the build process gets the sample file, it uses 
+            <filename>sed</filename> to substitute final 
+            <filename>${</filename><link linkend='var-OEROOT'><filename>OEROOT</filename></link><filename>}</filename> 
+            values for all <filename>##OEROOT##</filename> values.
+            <note>
+                You can see how the <filename>TEMPLATECONF</filename> variable
+                <filename>/scripts/oe-setup-builddir</filename> script in the 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                You can find the Yocto Project version of the 
+                <filename>bblayers.conf.sample</filename> file in the 
+                <filename>/meta-yocto/conf</filename> directory.                
+            </note>
+        </para>
+    </section>
+
+    <section id='structure-build-conf-sanity_info'>
+        <title><filename>build/conf/sanity_info</filename></title>
+
+        <para>
+            This file indicates the state of the sanity checks and is created
+            during the build.
+        </para>
+    </section>
+
+    <section id='structure-build-downloads'>
+        <title><filename>build/downloads/</filename></title>
+
+        <para>
+            This directory contains downloaded upstream source tarballs.
+            You can reuse the directory for multiple builds or move
+            the directory to another location.
+            You can control the location of this directory through the
+            <filename><link linkend='var-DL_DIR'>DL_DIR</link></filename> variable.
+        </para>
+    </section>
+
+    <section id='structure-build-sstate-cache'>
+        <title><filename>build/sstate-cache/</filename></title>
+
+        <para>
+            This directory contains the shared state cache.
+            You can reuse the directory for multiple builds or move
+            the directory to another location.
+            You can control the location of this directory through the
+            <filename><link linkend='var-SSTATE_DIR'>SSTATE_DIR</link></filename> variable.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp'>
+        <title><filename>build/tmp/</filename></title>
+
+        <para>
+            This directory receives all the OpenEmbedded build system's output.
+            BitBake creates this directory if it does not exist.
+            As a last resort, to clean up a build and start it from scratch (other than the downloads),
+            you can remove everything in the <filename>tmp</filename> directory or get rid of the
+            directory completely.
+            If you do, you should also completely remove the
+            <filename>build/sstate-cache</filename> directory.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-buildstats'>
+        <title><filename>build/tmp/buildstats/</filename></title>
+
+        <para>
+            This directory stores the build statistics.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-cache'>
+        <title><filename>build/tmp/cache/</filename></title>
+
+        <para>
+            When BitBake parses the metadata, it creates a cache file of the result that can
+            be used when subsequently running commands.
+            BitBake stores these results here on a per-machine basis.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-deploy'>
+        <title><filename>build/tmp/deploy/</filename></title>
+
+        <para>
+            This directory contains any "end result" output from the
+            OpenEmbedded build process.
+            The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
+            variable points to this directory.
+            For more detail on the contents of the <filename>deploy</filename>
+            directory, see the
+            "<link linkend='images-dev-environment'>Images</link>" and
+            "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+            sections.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-deploy-deb'>
+        <title><filename>build/tmp/deploy/deb/</filename></title>
+
+        <para>
+            This directory receives any <filename>.deb</filename> packages produced by
+            the build process.
+            The packages are sorted into feeds for different architecture types.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-deploy-rpm'>
+        <title><filename>build/tmp/deploy/rpm/</filename></title>
+
+        <para>
+            This directory receives any <filename>.rpm</filename> packages produced by
+            the build process.
+            The packages are sorted into feeds for different architecture types.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-deploy-licenses'>
+        <title><filename>build/tmp/deploy/licenses/</filename></title>
+
+        <para>
+            This directory receives package licensing information.
+            For example, the directory contains sub-directories for <filename>bash</filename>,
+            <filename>busybox</filename>, and <filename>eglibc</filename> (among others) that in turn
+            contain appropriate <filename>COPYING</filename> license files with other licensing information.
+            For information on licensing, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Product's Lifecycle</ulink>"
+            section.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-deploy-images'>
+        <title><filename>build/tmp/deploy/images/</filename></title>
+
+        <para>
+            This directory receives complete filesystem images.
+            If you want to flash the resulting image from a build onto a device, look here for the image.
+        </para>
+
+        <para>
+            Be careful when deleting files in this directory.
+            You can safely delete old images from this directory (e.g.
+            <filename>core-image-*</filename>, <filename>hob-image-*</filename>,
+            etc.).
+            However, the kernel (<filename>*zImage*</filename>, <filename>*uImage*</filename>, etc.),
+            bootloader and other supplementary files might be deployed here prior to building an
+            image.
+            Because these files are not directly produced from the image, if you
+            delete them they will not be automatically re-created when you build the image again.
+        </para>
+
+        <para>
+            If you do accidentally delete files here, you will need to force them to be
+            re-created.
+            In order to do that, you will need to know the target that produced them.
+            For example, these commands rebuild and re-create the kernel files:
+            <literallayout class='monospaced'>
+     $ bitbake -c clean virtual/kernel
+     $ bitbake virtual/kernel
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-deploy-ipk'>
+        <title><filename>build/tmp/deploy/ipk/</filename></title>
+
+        <para>
+            This directory receives <filename>.ipk</filename> packages produced by
+            the build process.</para>
+    </section>
+
+    <section id='structure-build-tmp-sysroots'>
+        <title><filename>build/tmp/sysroots/</filename></title>
+
+        <para>
+            This directory contains shared header files and libraries as well as other shared
+            data.
+            Packages that need to share output with other packages do so within this directory.
+            The directory is subdivided by architecture so multiple builds can run within
+            the one Build Directory.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-stamps'>
+        <title><filename>build/tmp/stamps/</filename></title>
+
+        <para>
+            This directory holds information that BitBake uses for accounting purposes
+            to track what tasks have run and when they have run.
+            The directory is sub-divided by architecture, package name, and
+            version.
+            Following is an example:
+            <literallayout class='monospaced'>
+     stamps/all-poky-linux/distcc-config/1.0-r0.do_build-2fdd....2do
+            </literallayout>
+            Although the files in the directory are empty of data,
+            BitBake uses the filenames and timestamps for tracking purposes.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-log'>
+        <title><filename>build/tmp/log/</filename></title>
+
+        <para>
+            This directory contains general logs that are not otherwise placed using the
+            package's <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
+            Examples of logs are the output from the <filename>check_pkg</filename> or
+            <filename>distro_check</filename> tasks.
+            Running a build does not necessarily mean this directory is created.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-pkgdata'>
+        <title><filename>build/tmp/pkgdata/</filename></title>
+
+        <para>
+            This directory contains intermediate packaging data that is used later in the packaging process.
+            For more information, see the "<link linkend='ref-classes-package'>Packaging - package*.bbclass</link>" section.
+        </para>
+    </section>
+
+    <section id='structure-build-tmp-work'>
+        <title><filename>build/tmp/work/</filename></title>
+
+        <para>
+            This directory contains architecture-specific work sub-directories
+            for packages built by BitBake.
+            All tasks execute from the appropriate work directory.
+            For example, the source for a particular package is unpacked,
+            patched, configured and compiled all within its own work directory.
+            Within the work directory, organization is based on the package group
+            and version for which the source is being compiled
+            as defined by the
+            <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
+        </para>
+
+        <para>
+            It is worth considering the structure of a typical work directory.
+            As an example, consider <filename>linux-yocto-kernel-3.0</filename>
+            on the machine <filename>qemux86</filename>
+            built within the Yocto Project.
+            For this package, a work directory of
+            <filename>tmp/work/qemux86-poky-linux/linux-yocto/3.0+git1+&lt;.....&gt;</filename>,
+            referred to as the
+            <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, is created.
+            Within this directory, the source is unpacked to
+            <filename>linux-qemux86-standard-build</filename> and then patched by Quilt.
+            (See the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#using-a-quilt-workflow'>Using a Quilt Flow</ulink>"
+            section in the Yocto Project Development Manual for more information.)
+            Within the <filename>linux-qemux86-standard-build</filename> directory,
+            standard Quilt directories <filename>linux-3.0/patches</filename>
+            and <filename>linux-3.0/.pc</filename> are created,
+            and standard Quilt commands can be used.
+        </para>
+
+        <para>
+            There are other directories generated within <filename>WORKDIR</filename>.
+            The most important directory is <filename>WORKDIR/temp/</filename>,
+            which has log files for each task (<filename>log.do_*.pid</filename>)
+            and contains the scripts BitBake runs for each task
+            (<filename>run.do_*.pid</filename>).
+            The <filename>WORKDIR/image/</filename> directory is where "make
+            install" places its output that is then split into sub-packages
+            within <filename>WORKDIR/packages-split/</filename>.
+        </para>
+    </section>
+</section>
+
+<section id='structure-meta'>
+    <title>The Metadata - <filename>meta/</filename></title>
+
+    <para>
+        As mentioned previously,
+        <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> is the core
+        of the Yocto Project.
+        Metadata has several important subdivisions:
+    </para>
+
+    <section id='structure-meta-classes'>
+        <title><filename>meta/classes/</filename></title>
+
+        <para>
+            This directory contains the <filename>*.bbclass</filename> files.
+            Class files are used to abstract common code so it can be reused by multiple
+            packages.
+            Every package inherits the <filename>base.bbclass</filename> file.
+            Examples of other important classes are <filename>autotools.bbclass</filename>, which
+            in theory allows any Autotool-enabled package to work with the Yocto Project with minimal effort.
+            Another example is <filename>kernel.bbclass</filename> that contains common code and functions
+            for working with the Linux kernel.
+            Functions like image generation or packaging also have their specific class files
+            such as <filename>image.bbclass</filename>, <filename>rootfs_*.bbclass</filename> and
+            <filename>package*.bbclass</filename>.
+        </para>
+
+        <para>
+            For reference information on classes, see the
+            "<link linkend='ref-classes'>Classes</link>" chapter.
+        </para>
+    </section>
+
+    <section id='structure-meta-conf'>
+        <title><filename>meta/conf/</filename></title>
+
+        <para>
+            This directory contains the core set of configuration files that start from
+            <filename>bitbake.conf</filename> and from which all other configuration
+            files are included.
+            See the include statements at the end of the
+            <filename>bitbake.conf</filename> file and you will note that even
+            <filename>local.conf</filename> is loaded from there.
+            While <filename>bitbake.conf</filename> sets up the defaults, you can often override
+            these by using the (<filename>local.conf</filename>) file, machine file or
+            the distribution configuration file.
+        </para>
+    </section>
+
+    <section id='structure-meta-conf-machine'>
+        <title><filename>meta/conf/machine/</filename></title>
+
+        <para>
+            This directory contains all the machine configuration files.
+            If you set <filename>MACHINE = "qemux86"</filename>,
+            the OpenEmbedded build system looks for a <filename>qemux86.conf</filename> file in this
+            directory.
+            The <filename>include</filename> directory contains various data common to multiple machines.
+            If you want to add support for a new machine to the Yocto Project, look in this directory.
+        </para>
+    </section>
+
+    <section id='structure-meta-conf-distro'>
+        <title><filename>meta/conf/distro/</filename></title>
+
+        <para>
+            The contents of this directory controls any distribution-specific
+            configurations.
+            For the Yocto Project, the <filename>defaultsetup.conf</filename> is the main file here.
+            This directory includes the versions and the
+            <filename>SRCDATE</filename> definitions for applications that are configured here.
+            An example of an alternative configuration might be <filename>poky-bleeding.conf</filename>.
+            Although this file mainly inherits its configuration from Poky.
+        </para>
+    </section>
+
+    <section id='structure-meta-files'>
+        <title><filename>meta/files/</filename></title>
+
+        <para>
+            This directory contains common license files and several text files
+            used by the build system.
+            The text files contain minimal device information and
+            lists of files and directories with knows permissions.
+        </para>
+    </section>
+
+    <section id='structure-meta-lib'>
+        <title><filename>meta/lib/</filename></title>
+
+        <para>
+            This directory contains OpenEmbedded Python library code
+            used during the build process.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-bsp'>
+        <title><filename>meta/recipes-bsp/</filename></title>
+
+        <para>
+            This directory contains anything linking to specific hardware or hardware
+            configuration information such as "u-boot" and "grub".
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-connectivity'>
+        <title><filename>meta/recipes-connectivity/</filename></title>
+
+        <para>
+            This directory contains libraries and applications related to communication with other devices.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-core'>
+        <title><filename>meta/recipes-core/</filename></title>
+
+        <para>
+            This directory contains what is needed to build a basic working Linux image
+            including commonly used dependencies.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-devtools'>
+        <title><filename>meta/recipes-devtools/</filename></title>
+
+        <para>
+            This directory contains tools that are primarily used by the build system.
+            The tools, however, can also be used on targets.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-extended'>
+        <title><filename>meta/recipes-extended/</filename></title>
+
+        <para>
+            This directory contains non-essential applications that add features compared to the
+            alternatives in core.
+            You might need this directory for full tool functionality or for Linux Standard Base (LSB)
+            compliance.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-gnome'>
+        <title><filename>meta/recipes-gnome/</filename></title>
+
+        <para>
+            This directory contains all things related to the GTK+ application framework.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-graphics'>
+        <title><filename>meta/recipes-graphics/</filename></title>
+
+        <para>
+            This directory contains X and other graphically related system libraries
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-kernel'>
+        <title><filename>meta/recipes-kernel/</filename></title>
+
+        <para>
+            This directory contains the kernel and generic applications and libraries that
+            have strong kernel dependencies.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-lsb4'>
+        <title><filename>meta/recipes-lsb4/</filename></title>
+
+        <para>
+            This directory contains recipes specifically added to support
+            the Linux Standard Base (LSB) version 4.x.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-multimedia'>
+        <title><filename>meta/recipes-multimedia/</filename></title>
+
+        <para>
+            This directory contains codecs and support utilities for audio, images and video.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-qt'>
+        <title><filename>meta/recipes-qt/</filename></title>
+
+        <para>
+            This directory contains all things related to the Qt application framework.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-rt'>
+        <title><filename>meta/recipes-rt/</filename></title>
+
+        <para>
+            This directory contains package and image recipes for using and testing
+            the <filename>PREEMPT_RT</filename> kernel.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-sato'>
+        <title><filename>meta/recipes-sato/</filename></title>
+
+        <para>
+            This directory contains the Sato demo/reference UI/UX and its associated applications
+            and configuration data.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-support'>
+        <title><filename>meta/recipes-support/</filename></title>
+
+        <para>
+            This directory contains recipes used by other recipes, but that are
+            not directly included in images (i.e. dependencies of other
+            recipes).
+        </para>
+    </section>
+
+    <section id='structure-meta-site'>
+        <title><filename>meta/site/</filename></title>
+
+        <para>
+            This directory contains a list of cached results for various architectures.
+            Because certain "autoconf" test results cannot be determined when cross-compiling due to
+            the tests not able to run on a live system, the information in this directory is
+            passed to "autoconf" for the various architectures.
+        </para>
+    </section>
+
+    <section id='structure-meta-recipes-txt'>
+        <title><filename>meta/recipes.txt</filename></title>
+
+        <para>
+            This file is a description of the contents of <filename>recipes-*</filename>.
+        </para>
+    </section>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/ref-style.css b/documentation/ref-manual/ref-style.css
new file mode 100644
index 0000000000..e896a39d33
--- /dev/null
+++ b/documentation/ref-manual/ref-style.css
@@ -0,0 +1,979 @@
+/* 
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+   
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+ 
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("figures/poky-title.png");
+  background-position: left top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 0px;
+  text-align: right;
+  width: 740px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+  
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+} 
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption, 
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;  
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+  
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2; 
+}
+
+.glossary dl dt, 
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title, 
+div.colophon .title, 
+div.chapter .titlepage .title,
+div.article .titlepage .title 
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/poky-title.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2; 
+   color: #333;   
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;   
+}
+
+.tip a,
+.note a {
+   color: #333;   
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
+
diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml
new file mode 100644
index 0000000000..f3211f84ed
--- /dev/null
+++ b/documentation/ref-manual/ref-variables.xml
@@ -0,0 +1,5888 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<!-- Dummy chapter -->
+<chapter id='ref-variables-glos'>
+
+<title>Variables Glossary</title>
+
+<para>
+    This chapter lists common variables used in the OpenEmbedded build system and gives an overview
+    of their function and contents.
+</para>
+
+<glossary id='ref-variables-glossary'>
+
+
+    <para>
+       <link linkend='var-ALLOW_EMPTY'>A</link>
+       <link linkend='var-B'>B</link>
+       <link linkend='var-CFLAGS'>C</link>
+       <link linkend='var-D'>D</link>
+       <link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>E</link>
+       <link linkend='var-FILES'>F</link>
+<!--               <link linkend='var-glossary-g'>G</link> -->
+       <link linkend='var-HOMEPAGE'>H</link>
+       <link linkend='var-IMAGE_BASENAME'>I</link>
+<!--               <link linkend='var-glossary-j'>J</link> -->
+       <link linkend='var-KARCH'>K</link>
+       <link linkend='var-LAYERDEPENDS'>L</link>
+       <link linkend='var-MACHINE'>M</link>
+<!--               <link linkend='var-glossary-n'>N</link> -->
+       <link linkend='var-OE_BINCONFIG_EXTRA_MANGLE'>O</link>
+       <link linkend='var-P'>P</link>
+<!--               <link linkend='var-glossary-q'>Q</link> -->
+       <link linkend='var-RCONFLICTS'>R</link>
+       <link linkend='var-S'>S</link>
+       <link linkend='var-T'>T</link>
+       <link linkend='var-UBOOT_ENTRYPOINT'>U</link>
+<!--               <link linkend='var-glossary-v'>V</link> -->
+       <link linkend='var-WARN_QA'>W</link>
+<!--               <link linkend='var-glossary-x'>X</link> -->
+<!--               <link linkend='var-glossary-y'>Y</link> -->
+<!--               <link linkend='var-glossary-z'>Z</link>-->
+    </para>
+
+    <glossdiv id='var-glossary-a'><title>A</title>
+
+         <glossentry id='var-ALLOW_EMPTY'><glossterm>ALLOW_EMPTY</glossterm>
+            <glossdef>
+                <para>
+                   Specifies if an output package should still be produced if it is empty.
+                   By default, BitBake does not produce empty packages.
+                   This default behavior can cause issues when there is an
+                   <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link> or
+                   some other runtime hard-requirement on the existence of the package.
+                </para>
+
+                <para>
+                   Like all package-controlling variables, you must always use them in
+                   conjunction with a package name override.
+                   Here is an example:
+                   <literallayout class='monospaced'>
+     ALLOW_EMPTY_${PN} = "1"
+                   </literallayout>
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-ALTERNATIVE'><glossterm>ALTERNATIVE</glossterm>
+            <glossdef>
+                <para>
+                    Lists commands in a package that need an alternative
+                    binary naming scheme.
+                    Sometimes the same command is provided in multiple packages.
+                    When this occurs, the OpenEmbedded build system needs to
+                    use the alternatives system to create a different binary
+                    naming scheme so the commands can co-exist.
+                </para>
+
+                <para>
+                    To use the variable, list out the package's commands
+                    that also exist as part of another package.
+                    For example, if the <filename>busybox</filename> package
+                    has four commands that also exist as part of another
+                    package, you identify them as follows:
+                    <literallayout class='monospaced'>
+     ALTERNATIVE_busybox = "sh sed test bracket"
+                    </literallayout>
+                    For more information on the alternatives system, see the
+                    "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-ALTERNATIVE_LINK_NAME'><glossterm>ALTERNATIVE_LINK_NAME</glossterm>
+            <glossdef>
+                <para>
+                    Used by the alternatives system to map duplicated commands
+                    to actual locations.
+                    For example, if the <filename>bracket</filename> command
+                    provided by the <filename>busybox</filename> package is
+                    duplicated through another package, you must use the
+                    <filename>ALTERNATIVE_LINK_NAME</filename> variable to
+                    specify the actual location:
+                    <literallayout class='monospaced'>
+     ALTERNATIVE_LINK_NAME[bracket] = "/usr/bin/["
+                    </literallayout>
+                    In this example, the binary for the
+                    <filename>bracket</filename> command (i.e.
+                    <filename>[</filename>) from the
+                    <filename>busybox</filename> package resides in
+                    <filename>/usr/bin/</filename>.
+                    <note>
+                        If <filename>ALTERNATIVE_LINK_NAME</filename> is not
+                        defined, it defaults to
+                        <filename>${bindir}/&lt;name&gt;</filename>.
+                    </note>
+                </para>
+
+                <para>
+                    For more information on the alternatives system, see the
+                    "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-ALTERNATIVE_PRIORITY'><glossterm>ALTERNATIVE_PRIORITY</glossterm>
+            <glossdef>
+                <para>
+                    Used by the alternatives system to create default
+                    priorities for duplicated commands.
+                    You can use the variable to create a single default
+                    regardless of the command name or package, a default for
+                    specific duplicated commands regardless of the package, or
+                    a default for specific commands tied to particular packages.
+                    Here are the available syntax forms:
+                    <literallayout class='monospaced'>
+     ALTERNATIVE_PRIORITY = "&lt;priority&gt;"
+     ALTERNATIVE_PRIORITY[&lt;name&gt;] = "&lt;priority&gt;"
+     ALTERNATIVE_PRIORITY_&lt;pkg&gt;[&lt;name&gt;] = "&lt;priority&gt;"
+                    </literallayout>
+                </para>
+
+                <para>
+                    For more information on the alternatives system, see the
+                    "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-ALTERNATIVE_TARGET'><glossterm>ALTERNATIVE_TARGET</glossterm>
+            <glossdef>
+                <para>
+                    Used by the alternatives system to create default link
+                    locations for duplicated commands.
+                    You can use the variable to create a single default
+                    location for all duplicated commands regardless of the
+                    command name or package, a default for
+                    specific duplicated commands regardless of the package, or
+                    a default for specific commands tied to particular packages.
+                    Here are the available syntax forms:
+                    <literallayout class='monospaced'>
+     ALTERNATIVE_TARGET = "&lt;target&gt;"
+     ALTERNATIVE_TARGET[&lt;name&gt;] = "&lt;target&gt;"
+     ALTERNATIVE_TARGET_&lt;pkg&gt;[&lt;name&gt;] = "&lt;target&gt;"
+                    </literallayout>
+                    <note>
+                        <para>
+                            If <filename>ALTERNATIVE_TARGET</filename> is not
+                            defined, it inherits the value from the
+                            <link linkend='var-ALTERNATIVE_LINK_NAME'><filename>ALTERNATIVE_LINK_NAME</filename></link>
+                            variable.
+                        </para>
+
+                        <para>
+                            If <filename>ALTERNATIVE_LINK_NAME</filename> and
+                            <filename>ALTERNATIVE_TARGET</filename> are the
+                            same, the target for
+                            <filename>ALTERNATIVE_TARGET</filename>
+                            has "<filename>.{BPN}</filename>" appended to it.
+                        </para>
+
+                        <para>
+                            Finally, if the file referenced has not been
+                            renamed, the alternatives system will rename it to
+                            avoid the need to rename alternative files in the
+                            <filename>do_install</filename> task while
+                            retaining support for the command if necessary.
+                        </para>
+                    </note>
+                </para>
+
+                <para>
+                    For more information on the alternatives system, see the
+                    "<link linkend='ref-classes-update-alternatives'>Alternatives - <filename>update-alternatives.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-AUTHOR'><glossterm>AUTHOR</glossterm>
+            <glossdef>
+                <para>The email address used to contact the original author
+                    or authors in order to send patches and forward bugs.</para>
+            </glossdef>
+         </glossentry>
+
+        <glossentry id='var-AUTOREV'><glossterm>AUTOREV</glossterm>
+            <glossdef>
+                <para>When <filename><link linkend='var-SRCREV'>SRCREV</link></filename>
+                    is set to the value of this variable, it specifies to use the latest
+                    source revision in the repository.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     SRCREV = "${AUTOREV}"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-b'><title>B</title>
+
+        <glossentry id='var-B'><glossterm>B</glossterm>
+            <glossdef>
+                <para>
+                    The directory within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    in which the OpenEmbedded build system places generated
+                    objects during a recipe's build process.
+                    By default, this directory is the same as the <link linkend='var-S'><filename>S</filename></link>
+                    directory:
+                    <literallayout class='monospaced'>
+     B = "${WORKDIR}/${BPN}/{PV}/"
+                    </literallayout>
+                    You can separate the (<filename>S</filename>) directory
+                    and the directory pointed to by the <filename>B</filename>
+                    variable.
+                    Most Autotools-based recipes support separating these
+                    directories.
+                    The build system defaults to using separate directories for
+                    <filename>gcc</filename> and some kernel recipes.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BAD_RECOMMENDATIONS'><glossterm>BAD_RECOMMENDATIONS</glossterm>
+            <glossdef>
+                <para>
+                    Lists "recommended-only" packages to not install.
+                    Recommended-only packages are packages installed only
+                    through the
+                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
+                    variable.
+                    You can prevent any of these "recommended" packages from
+                    being installed by listing them with the
+                    <filename>BAD_RECOMMENDATIONS</filename> variable:
+                    <literallayout class='monospaced'>
+     BAD_RECOMMENDATIONS = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
+                    </literallayout>
+                    You can set this variable globally in your
+                    <filename>local.conf</filename> file or you can attach it to
+                    a specific image recipe by using the recipe name override:
+                    <literallayout class='monospaced'>
+     BAD_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
+                    </literallayout>
+                </para>
+
+                <para>
+                    It is important to realize that if you choose to not install
+                    packages using this variable and some other packages are
+                    dependent on them (i.e. listed in a recipe's
+                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+                    variable), the OpenEmbedded build system ignores your
+                    request and will install the packages to avoid dependency
+                    errors.
+                </para>
+
+                <para>
+                    Support for this variable exists only when using the
+                    IPK and RPM packaging backend.
+                    Support does not exist for DEB.
+                </para>
+
+                <para>
+                    See the
+                    <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
+                    and the
+                    <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
+                    variables for related information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BB_DANGLINGAPPENDS_WARNONLY'><glossterm>BB_DANGLINGAPPENDS_WARNONLY</glossterm>
+            <glossdef>
+                <para>
+                    Defines how BitBake handles situations where an append
+                    file (<filename>.bbappend</filename>) has no
+                    corresponding recipe file (<filename>.bb</filename>).
+                    This condition often occurs when layers get out of sync
+                    (e.g. <filename>oe-core</filename> bumps a
+                    recipe version and the old recipe no longer exists and the
+                    other layer has not been updated to the new version
+                    of the recipe yet).
+                </para>
+
+                <para>
+                    The default fatal behavior is safest because it is
+                    the sane reaction given something is out of sync.
+                    It is important to realize when your changes are no longer
+                    being applied.
+                </para>
+
+                <para>
+                    You can change the default behavior by setting this
+                    variable to "1" in the <filename>local.conf</filename>
+                    file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    as follows:
+                    <literallayout class='monospaced'>
+     BB_DANGLINGAPPENDS_WARNONLY = "1"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BB_DISKMON_DIRS'><glossterm>BB_DISKMON_DIRS</glossterm>
+            <glossdef>
+                <para>
+                    Monitors disk space and available inodes during the build
+                    and allows you to control the build based on these
+                    parameters.
+                </para>
+
+                <para>
+                    Disk space monitoring is disabled by default.
+                    To enable monitoring, add the <filename>BB_DISKMON_DIRS</filename>
+                    variable to your <filename>conf/local.conf</filename> file found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    Use the following form:
+                    <literallayout class='monospaced'>
+     BB_DISKMON_DIRS = "&lt;action&gt;,&lt;dir&gt;,&lt;threshold&gt; [...]"
+
+     where:
+
+        &lt;action&gt; is:
+           ABORT:     Immediately abort the build when
+                      a threshold is broken.
+           STOPTASKS: Stop the build after the currently
+                      executing tasks have finished when
+                      a threshold is broken.
+           WARN:      Issue a warning but continue the
+                      build when a threshold is broken.
+                      Subsequent warnings are issued as
+                      defined by the
+                      <link linkend='var-BB_DISKMON_WARNINTERVAL'>BB_DISKMON_WARNINTERVAL</link> variable,
+                      which must be defined in the
+                      conf/local.conf file.
+
+        &lt;dir&gt; is:
+           Any directory you choose. You can specify one or
+           more directories to monitor by separating the
+           groupings with a space.  If two directories are
+           on the same device, only the first directory
+           is monitored.
+
+        &lt;threshold&gt; is:
+           Either the minimum available disk space,
+           the minimum number of free inodes, or
+           both.  You must specify at least one.  To
+           omit one or the other, simply omit the value.
+           Specify the threshold using G, M, K for Gbytes,
+           Mbytes, and Kbytes, respectively. If you do
+           not specify G, M, or K, Kbytes is assumed by
+           default.  Do not use GB, MB, or KB.
+                    </literallayout>
+                </para>
+
+                <para>
+                    Here are some examples:
+                    <literallayout class='monospaced'>
+     BB_DISKMON_DIRS = "ABORT,${TMPDIR},1G,100K WARN,${SSTATE_DIR},1G,100K"
+     BB_DISKMON_DIRS = "STOPTASKS,${TMPDIR},1G"
+     BB_DISKMON_DIRS = "ABORT,${TMPDIR},,100K"
+                    </literallayout>
+                    The first example works only if you also provide
+                    the <link linkend='var-BB_DISKMON_WARNINTERVAL'><filename>BB_DISKMON_WARNINTERVAL</filename></link> variable
+                    in the <filename>conf/local.conf</filename>.
+                    This example causes the build system to immediately
+                    abort when either the disk space in <filename>${TMPDIR}</filename> drops
+                    below 1 Gbyte or the available free inodes drops below
+                    100 Kbytes.
+                    Because two directories are provided with the variable, the
+                    build system also issue a
+                    warning when the disk space in the
+                    <filename>${SSTATE_DIR}</filename> directory drops
+                    below 1 Gbyte or the number of free inodes drops
+                    below 100 Kbytes.
+                    Subsequent warnings are issued during intervals as
+                    defined by the <filename>BB_DISKMON_WARNINTERVAL</filename>
+                    variable.
+                </para>
+
+                <para>
+                    The second example stops the build after all currently
+                    executing tasks complete when the minimum disk space
+                    in the <filename>${<link linkend='var-TMPDIR'>TMPDIR</link>}</filename>
+                    directory drops below 1 Gbyte.
+                    No disk monitoring occurs for the free inodes in this case.
+                </para>
+
+                <para>
+                    The final example immediately aborts the build when the
+                    number of free inodes in the <filename>${TMPDIR}</filename> directory
+                    drops below 100 Kbytes.
+                    No disk space monitoring for the directory itself occurs
+                    in this case.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BB_DISKMON_WARNINTERVAL'><glossterm>BB_DISKMON_WARNINTERVAL</glossterm>
+            <glossdef>
+                <para>
+                    Defines the disk space and free inode warning intervals.
+                    To set these intervals, define the variable in your
+                    <filename>conf/local.conf</filename> file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                </para>
+
+                <para>
+                    If you are going to use the
+                    <filename>BB_DISKMON_WARNINTERVAL</filename> variable, you must
+                    also use the
+                    <link linkend='var-BB_DISKMON_DIRS'><filename>BB_DISKMON_DIRS</filename></link> variable
+                    and define its action as "WARN".
+                    During the build, subsequent warnings are issued each time
+                    disk space or number of free inodes further reduces by
+                    the respective interval.
+                </para>
+
+                <para>
+                    If you do not provide a <filename>BB_DISKMON_WARNINTERVAL</filename>
+                    variable and you do use <filename>BB_DISKMON_DIRS</filename> with
+                    the "WARN" action, the disk monitoring interval defaults to
+                    the following:
+                    <literallayout class='monospaced'>
+     BB_DISKMON_WARNINTERVAL = "50M,5K"
+                    </literallayout>
+                </para>
+
+                <para>
+                    When specifying the variable in your configuration file,
+                    use the following form:
+                    <literallayout class='monospaced'>
+     BB_DISKMON_WARNINTERVAL = "&lt;disk_space_interval&gt;,&lt;disk_inode_interval&gt;"
+
+     where:
+
+        &lt;disk_space_interval&gt; is:
+           An interval of memory expressed in either
+           G, M, or K for Gbytes, Mbytes, or Kbytes,
+           respectively. You cannot use GB, MB, or KB.
+
+        &lt;disk_inode_interval&gt; is:
+           An interval of free inodes expressed in either
+           G, M, or K for Gbytes, Mbytes, or Kbytes,
+           respectively. You cannot use GB, MB, or KB.
+                    </literallayout>
+                </para>
+
+                <para>
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     BB_DISKMON_DIRS = "WARN,${SSTATE_DIR},1G,100K"
+     BB_DISKMON_WARNINTERVAL = "50M,5K"
+                    </literallayout>
+                    These variables cause the OpenEmbedded build system to
+                    issue subsequent warnings each time the available
+                    disk space further reduces by 50 Mbytes or the number
+                    of free inodes further reduces by 5 Kbytes in the
+                    <filename>${SSTATE_DIR}</filename> directory.
+                    Subsequent warnings based on the interval occur each time
+                    a respective interval is reached beyond the initial warning
+                    (i.e. 1 Gbytes and 100 Kbytes).
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BB_GENERATE_MIRROR_TARBALLS'><glossterm>BB_GENERATE_MIRROR_TARBALLS</glossterm>
+            <glossdef>
+                <para>
+                    Causes tarballs of the Git repositories to be placed in the
+                    <link linkend='var-DL_DIR'><filename>DL_DIR</filename></link>
+                    directory.
+                    For performance reasons, creating and placing tarballs of
+                    the Git repositories is not the default action by the
+                    OpenEmbedded build system.
+                    <literallayout class='monospaced'>
+     BB_Generate_MIRROR_TARBALLS = "1"
+                    </literallayout>
+                    Set this variable in your <filename>local.conf</filename>
+                    file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BB_NUMBER_THREADS'><glossterm>BB_NUMBER_THREADS</glossterm>
+            <glossdef>
+                <para>The maximum number of tasks BitBake should run in parallel at any one time.
+                    If your host development system supports multiple cores a good rule of thumb
+                    is to set this variable to twice the number of cores.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBCLASSEXTEND'><glossterm>BBCLASSEXTEND</glossterm>
+            <glossdef>
+                <para>
+                    Allows you to extend a recipe so that it builds variants of the software.
+                    Common variants for recipes exist such as "natives" like <filename>quilt-native</filename>,
+                    which is a copy of Quilt built to run on the build system;
+                    "crosses" such as <filename>gcc-cross</filename>,
+                    which is a compiler built to run on the build machine but produces binaries
+                    that run on the target <link linkend='var-MACHINE'><filename>MACHINE</filename></link>;
+                    "nativesdk", which targets the SDK machine instead of <filename>MACHINE</filename>;
+                    and "mulitlibs" in the form "<filename>multilib:&lt;multilib_name&gt;</filename>".
+                </para>
+
+                <para>
+                    To build a different variant of the recipe with a minimal amount of code, it usually
+                    is as simple as adding the following to your recipe:
+                    <literallayout class='monospaced'>
+     BBCLASSEXTEND =+ "native nativesdk"
+     BBCLASSEXTEND =+ "multilib:&lt;multilib_name&gt;"
+                    </literallayout>
+                </para>
+             </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBFILE_COLLECTIONS'><glossterm>BBFILE_COLLECTIONS</glossterm>
+            <glossdef>
+                <para>Lists the names of configured layers.
+                    These names are used to find the other <filename>BBFILE_*</filename>
+                    variables.
+                    Typically, each layer will append its name to this variable in its
+                    <filename>conf/layer.conf</filename> file.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBFILE_PATTERN'><glossterm>BBFILE_PATTERN</glossterm>
+            <glossdef>
+                <para>Variable that expands to match files from
+                    <link linkend='var-BBFILES'><filename>BBFILES</filename></link>
+                    in a particular layer.
+                    This variable is used in the <filename>conf/layer.conf</filename> file and must
+                    be suffixed with the name of the specific layer (e.g.
+                    <filename>BBFILE_PATTERN_emenlow</filename>).</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBFILE_PRIORITY'><glossterm>BBFILE_PRIORITY</glossterm>
+            <glossdef>
+                <para>Assigns the priority for recipe files in each layer.</para>
+                <para>This variable is useful in situations where the same recipe appears in
+                    more than one layer.
+                    Setting this variable allows you to prioritize a
+                    layer against other layers that contain the same recipe - effectively
+                    letting you control the precedence for the multiple layers.
+                    The precedence established through this variable stands regardless of a
+                    recipe's version
+                    (<link linkend='var-PV'><filename>PV</filename></link> variable).
+                    For example, a layer that has a recipe with a higher <filename>PV</filename> value but for
+                    which the <filename>BBFILE_PRIORITY</filename> is set to have a lower precedence still has a
+                    lower precedence.</para>
+                <para>A larger value for the <filename>BBFILE_PRIORITY</filename> variable results in a higher
+                    precedence.
+                    For example, the value 6 has a higher precedence than the value 5.
+                    If not specified, the <filename>BBFILE_PRIORITY</filename> variable is set based on layer
+                    dependencies (see the
+                    <filename><link linkend='var-LAYERDEPENDS'>LAYERDEPENDS</link></filename> variable for
+                    more information.
+                    The default priority, if unspecified
+                    for a layer with no dependencies, is the lowest defined priority + 1
+                    (or 1 if no priorities are defined).</para>
+                <tip>
+                    You can use the command <filename>bitbake-layers show_layers</filename> to list
+                    all configured layers along with their priorities.
+                </tip>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBFILES'><glossterm>BBFILES</glossterm>
+            <glossdef>
+                <para>List of recipe files used by BitBake to build software.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBINCLUDELOGS'><glossterm>BBINCLUDELOGS</glossterm>
+            <glossdef>
+                <para>Variable that controls how BitBake displays logs on build failure.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBLAYERS'><glossterm>BBLAYERS</glossterm>
+            <glossdef>
+                <para>Lists the layers to enable during the build.
+                    This variable is defined in the <filename>bblayers.conf</filename> configuration
+                    file in the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     BBLAYERS = " \
+       /home/scottrif/poky/meta \
+       /home/scottrif/poky/meta-yocto \
+       /home/scottrif/poky/meta-yocto-bsp \
+       /home/scottrif/poky/meta-mykernel \
+       "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+       /home/scottrif/poky/meta \
+       /home/scottrif/poky/meta-yocto \
+       "
+                    </literallayout>
+                    This example enables four layers, one of which is a custom, user-defined layer
+                    named <filename>meta-mykernel</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBLAYERS_NON_REMOVABLE'><glossterm>BBLAYERS_NON_REMOVABLE</glossterm>
+            <glossdef>
+Core layer for images cannot be removed
+                <para>Lists core layers that cannot be removed from the
+                    <filename>bblayers.conf</filename> file.
+                    In order for BitBake to build your image, your
+                    <filename>bblayers.conf</filename> file must include the
+                    <filename>meta</filename> and <filename>meta-yocto</filename>
+                    core layers.
+                    Here is an example that shows these two layers listed in
+                    the <filename>BBLAYERS_NON_REMOVABLE</filename> statement:
+                    <literallayout class='monospaced'>
+     BBLAYERS = " \
+       /home/scottrif/poky/meta \
+       /home/scottrif/poky/meta-yocto \
+       /home/scottrif/poky/meta-yocto-bsp \
+       /home/scottrif/poky/meta-mykernel \
+       "
+
+     BBLAYERS_NON_REMOVABLE ?= " \
+       /home/scottrif/poky/meta \
+       /home/scottrif/poky/meta-yocto \
+       "
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBMASK'><glossterm>BBMASK</glossterm>
+            <glossdef>
+                <para>
+                    Prevents BitBake from processing recipes and recipe
+                    append files.
+                    Use the <filename>BBMASK</filename> variable from within the
+                    <filename>conf/local.conf</filename> file found
+                    in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                </para>
+
+                <para>
+                    You can use the <filename>BBMASK</filename> variable
+                    to "hide" these <filename>.bb</filename> and
+                    <filename>.bbappend</filename> files.
+                    BitBake ignores any recipe or recipe append files that
+                    match the expression.
+                    It is as if BitBake does not see them at all.
+                    Consequently, matching files are not parsed or otherwise
+                    used by BitBake.</para>
+                <para>
+                    The value you provide is passed to Python's regular
+                    expression compiler.
+                    The expression is compared against the full paths to
+                    the files.
+                    For complete syntax information, see Python's
+                    documentation at
+                    <ulink url='http://docs.python.org/release/2.3/lib/re-syntax.html'></ulink>.
+                </para>
+
+                <para>
+                    The following example uses a complete regular expression
+                    to tell BitBake to ignore all recipe and recipe append
+                    files in the <filename>/meta-ti/recipes-misc/</filename>
+                    directory:
+                    <literallayout class='monospaced'>
+     BBMASK = "/meta-ti/recipes-misc/"
+                    </literallayout>
+                    If you want to mask out multiple directories or recipes,
+                    use the vertical bar to separate the regular expression
+                    fragments.
+                    This next example masks out multiple directories and
+                    individual recipes:
+                    <literallayout class='monospaced'>
+     BBMASK = "meta-ti/recipes-misc/|meta-ti/recipes-ti/packagegroup/"
+     BBMASK .= "|.*meta-oe/recipes-support/"
+     BBMASK .= "|.*openldap"
+     BBMASK .= "|.*opencv"
+     BBMASK .= "|.*lzma"
+                    </literallayout>
+                    Notice how the vertical bar is used to append the fragments.
+                    <note>
+                        When specifying a directory name, use the trailing
+                        slash character to ensure you match just that directory
+                        name.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBPATH'><glossterm>BBPATH</glossterm>
+            <glossdef>
+                <para>
+                    Used by BitBake to locate
+                    <filename>.bbclass</filename> and configuration files.
+                    This variable is analogous to the
+                    <filename>PATH</filename> variable.
+                    <note>
+                        If you run BitBake from a directory outside of the
+                        <ulink url='&YOCTO_DOCS_DEV_URL;build-directory'>Build Directory</ulink>,
+                        you must be sure to set
+                        <filename>BBPATH</filename> to point to the
+                        Build Directory.
+                        Set the variable as you would any environment variable
+                        and then run BitBake:
+                        <literallayout class='monospaced'>
+     $ BBPATH = "&lt;build_directory&gt;"
+     $ export BBPATH
+     $ bitbake &lt;target&gt;
+                        </literallayout>
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BBSERVER'><glossterm>BBSERVER</glossterm>
+            <glossdef>
+                <para>
+                    Points to the server that runs memory-resident BitBake.
+                    This variable is set by the
+                    <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
+                    setup script and should not be hand-edited.
+                    The variable is only used when you employ memory-resident
+                    BitBake.
+                    The setup script exports the value as follows:
+                    <literallayout class='monospaced'>
+     export BBSERVER=localhost:$port
+                    </literallayout>
+                    For more information on how the
+                    <filename>BBSERVER</filename> is used, see the
+                    <filename>oe-init-build-env-memres</filename> script, which
+                    is located in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BINCONFIG_GLOB'><glossterm>BINCONFIG_GLOB</glossterm>
+            <glossdef>
+                <para>
+                    When inheriting <filename>binconfig.bbclass</filename>
+                    from a recipe, this variable specifies a wildcard for
+                    configuration scripts that need editing.
+                    The scripts are edited to correct any paths that have been
+                    set up during compilation so that they are correct for
+                    use when installed into the sysroot and called by the
+                    build processes of other recipes.
+                </para>
+
+                <para>
+                    For more information on how this variable works, see
+                    <filename>meta/classes/binconfig.bbclass</filename> in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                    You can also find general information on the class in the
+                    "<link linkend='ref-classes-binconfig'><filename>binconfig.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BP'><glossterm>BP</glossterm>
+            <glossdef>
+                <para>The base recipe name and version but without any special
+                    recipe name suffix (i.e. <filename>-native</filename>, <filename>lib64-</filename>,
+                    and so forth).
+                    <filename>BP</filename> is comprised of the following:
+                    <literallayout class="monospaced">
+     ${BPN}-${PV}
+                    </literallayout></para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BPN'><glossterm>BPN</glossterm>
+            <glossdef>
+                <para>The bare name of the recipe.
+                    This variable is a version of the <link linkend='var-PN'><filename>PN</filename></link> variable
+                    but removes common suffixes such as "-native" and "-cross" as well
+                    as removes common prefixes such as multilib's "lib64-" and "lib32-".
+                    The exact list of suffixes removed is specified by the
+                    <link linkend='var-SPECIAL_PKGSUFFIX'><filename>SPECIAL_PKGSUFFIX</filename></link> variable.
+                    The exact list of prefixes removed is specified by the
+                    <link linkend='var-MLPREFIX'><filename>MLPREFIX</filename></link> variable.
+                    Prefixes are removed for <filename>multilib</filename>
+                    and <filename>nativesdk</filename> cases.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BUILDDIR'><glossterm>BUILDDIR</glossterm>
+            <glossdef>
+                <para>
+                    Points to the location of the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    You can define this directory indirectly through the
+                    <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+                    and
+                    <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>
+                    scripts by passing in a Build Directory path when you run
+                    the scripts.
+                    If you run the scripts and do not provide a Build Directory
+                    path, the <filename>BUILDDIR</filename> defaults to
+                    <filename>build</filename> in the current directory.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-BUSYBOX_SPLIT_SUID'><glossterm>BUSYBOX_SPLIT_SUID</glossterm>
+            <glossdef>
+                <para>
+                    For the BusyBox recipe, specifies whether to split the
+                    output executable file into two parts: one for features
+                    that require <filename>setuid root</filename>, and one for
+                    the remaining features (i.e. those that do not require
+                    <filename>setuid root</filename>).
+                </para>
+
+                <para>
+                    The <filename>BUSYBOX_SPLIT_SUID</filename> variable
+                    defaults to "1", which results in a single output
+                    executable file.
+                    Set the variable to "0" to split the output file.
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-c'><title>C</title>
+
+        <glossentry id='var-CFLAGS'><glossterm>CFLAGS</glossterm>
+            <glossdef>
+                <para>
+                    Flags passed to the C compiler for the target system.
+                    This variable evaluates to the same as
+                    <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-COMBINED_FEATURES'><glossterm>COMBINED_FEATURES</glossterm>
+            <glossdef>
+                <para>A set of features common between
+                    <link linkend='var-MACHINE_FEATURES'><filename>MACHINE_FEATURES</filename></link>
+                    and <link linkend='var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></link>.
+                    See the glossary descriptions for these variables for more information.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-COMMON_LICENSE_DIR'><glossterm>COMMON_LICENSE_DIR</glossterm>
+            <glossdef>
+                <para>
+                    Points to <filename>meta/files/common-licenses</filename>
+                    in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
+                    which is where generic license files reside.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-COMPATIBLE_HOST'><glossterm>COMPATIBLE_HOST</glossterm>
+            <glossdef>
+                <para>A regular expression that resolves to one or more hosts
+                    (when the recipe is native) or one or more targets (when
+                    the recipe is non-native) with which a recipe is compatible.
+                    The regular expression is matched against
+                    <link linkend="var-HOST_SYS"><filename>HOST_SYS</filename></link>.
+                    You can use the variable to stop recipes from being built
+                    for classes of systems with which the recipes are not
+                    compatible.
+                    Stopping these builds is particularly useful with kernels.
+                    The variable also helps to increase parsing speed
+                    since the build system skips parsing recipes not
+                    compatible with the current system.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-COMPATIBLE_MACHINE'><glossterm>COMPATIBLE_MACHINE</glossterm>
+            <glossdef>
+                <para>A regular expression that resolves to one or more
+                    target machines with which a recipe is compatible.
+                    The regular expression is matched against
+                    <link linkend="var-MACHINEOVERRIDES"><filename>MACHINEOVERRIDES</filename></link>.
+                    You can use the variable to stop recipes from being built
+                    for machines with which the recipes are not compatible.
+                    Stopping these builds is particularly useful with kernels.
+                    The variable also helps to increase parsing speed
+                    since the build system skips parsing recipes not
+                    compatible with the current machine.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-COMPLEMENTARY_GLOB'><glossterm>COMPLEMENTARY_GLOB</glossterm>
+            <glossdef>
+                <para>
+                    Defines wildcards to match when installing a list of
+                    complementary packages for all the packages explicitly
+                    (or implicitly) installed in an image.
+                    The resulting list of complementary packages is associated
+                    with an item that can be added to
+                    <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
+                    An example usage of this is the "dev-pkgs" item that when
+                    added to <filename>IMAGE_FEATURES</filename> will
+                    install -dev packages (containing headers and other
+                    development files) for every package in the image.
+                </para>
+
+                <para>
+                    To add a new feature item pointing to a wildcard, use a
+                    variable flag to specify the feature item name and
+                    use the value to specify the wildcard.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     COMPLEMENTARY_GLOB[dev-pkgs] = '*-dev'
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-CONFFILES'><glossterm>CONFFILES</glossterm>
+            <glossdef>
+                <para>
+                    Identifies editable or configurable files that are part of a package.
+                    If the Package Management System (PMS) is being used to update
+                    packages on the target system, it is possible that
+                    configuration files you have changed after the original installation
+                    and that you now want to remain unchanged are overwritten.
+                    In other words, editable files might exist in the package that you do not
+                    want reset as part of the package update process.
+                    You can use the <filename>CONFFILES</filename> variable to list the files in the
+                    package that you wish to prevent the PMS from overwriting during this update process.
+                </para>
+
+                <para>
+                    To use the <filename>CONFFILES</filename> variable, provide a package name
+                    override that identifies the resulting package.
+                    Then, provide a space-separated list of files.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+  CONFFILES_${PN} += "${sysconfdir}/file1 \
+     ${sysconfdir}/file2 ${sysconfdir}/file3"
+                    </literallayout>
+                </para>
+
+                <para>
+                    A relationship exists between the <filename>CONFFILES</filename> and
+                    <filename><link linkend='var-FILES'>FILES</link></filename> variables.
+                    The files listed within <filename>CONFFILES</filename> must be a subset of
+                    the files listed within <filename>FILES</filename>.
+                    Because the configuration files you provide with <filename>CONFFILES</filename>
+                    are simply being identified so that the PMS will not overwrite them,
+                    it makes sense that
+                    the files must already be included as part of the package through the
+                    <filename>FILES</filename> variable.
+                </para>
+
+                <note>
+                    When specifying paths as part of the <filename>CONFFILES</filename> variable,
+                    it is good practice to use appropriate path variables.
+                    For example, <filename>${sysconfdir}</filename> rather than
+                    <filename>/etc</filename> or <filename>${bindir}</filename> rather
+                    than <filename>/usr/bin</filename>.
+                    You can find a list of these variables at the top of the
+                    <filename>/meta/conf/bitbake.conf</filename> file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </note>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-CONFIG_SITE'><glossterm>CONFIG_SITE</glossterm>
+            <glossdef>
+                <para>
+                    A list of files that contains <filename>autoconf</filename> test results relevant
+                    to the current build.
+                    This variable is used by the Autotools utilities when running
+                    <filename>configure</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-CORE_IMAGE_EXTRA_INSTALL'><glossterm>CORE_IMAGE_EXTRA_INSTALL</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the list of packages to be added to the image.
+                    You should only set this variable in the
+                    <filename>local.conf</filename> configuration file found
+                    in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                </para>
+
+                <para>
+                    This variable replaces <filename>POKY_EXTRA_INSTALL</filename>, which is no longer supported.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-COREBASE'><glossterm>COREBASE</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the parent directory of the OpenEmbedded
+                    Core Metadata layer (i.e. <filename>/meta</filename>).
+                </para>
+
+                <para>
+                    It is an important distinction that
+                    <filename>COREBASE</filename> points to the parent of this
+                    layer and not the layer itself.
+                    Consider an example where you have cloned the Poky Git
+                    repository and retained the <filename>poky</filename>
+                    name for your local copy of the repository.
+                    In this case, <filename>COREBASE</filename> points to
+                    the <filename>poky</filename> folder because it is the
+                    parent directory of the <filename>poky/meta</filename>
+                    layer.
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-d'><title>D</title>
+
+        <glossentry id='var-D'><glossterm>D</glossterm>
+            <glossdef>
+                <para>The destination directory.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DATETIME'><glossterm>DATETIME</glossterm>
+            <glossdef>
+                <para>
+                    The date and time on which the current build started.
+                    The format is suitable for timestamps.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEBUG_BUILD'><glossterm>DEBUG_BUILD</glossterm>
+            <glossdef>
+                <para>
+                    Specifies to build packages with debugging information.
+                    This influences the value of the
+                    <filename><link linkend='var-SELECTED_OPTIMIZATION'>SELECTED_OPTIMIZATION</link></filename>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEBUG_OPTIMIZATION'><glossterm>DEBUG_OPTIMIZATION</glossterm>
+            <glossdef>
+                <para>
+                    The options to pass in
+                    <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
+                    and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename> when compiling
+                    a system for debugging.
+                    This variable defaults to "-O -fno-omit-frame-pointer -g".
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEFAULT_PREFERENCE'><glossterm>DEFAULT_PREFERENCE</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a weak bias for recipe selection priority.
+                </para>
+                <para>
+                    The most common usage of this is variable is to set
+                    it to "-1" within a recipe for a development version of a
+                    piece of software.
+                    Using the variable in this way causes the stable version
+                    of the recipe to build by default in the absence of
+                    <filename><link linkend='var-PREFERRED_VERSION'>PREFERRED_VERSION</link></filename>
+                    being used to build the development version.
+                </para>
+                <note>
+                    The bias provided by <filename>DEFAULT_PREFERENCE</filename>
+                    is weak and is overridden by
+                    <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename>
+                    if the that variable is different between two layers
+                    that contain different versions of the same recipe.
+                </note>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEPENDS'><glossterm>DEPENDS</glossterm>
+            <glossdef>
+                <para>
+                    Lists a recipe's build-time dependencies
+                    (i.e. other recipe files).
+                    The system ensures that all the dependencies listed
+                    have been built and have their contents in the appropriate
+                    sysroots before the recipe's configure task is executed.
+                </para>
+
+                <para>
+                    Consider this simple example for two recipes named "a" and
+                    "b" that produce similarly named packages.
+                    In this example, the <filename>DEPENDS</filename>
+                    statement appears in the "a" recipe:
+                    <literallayout class='monospaced'>
+     DEPENDS = "b"
+                    </literallayout>
+                    Here, the dependency is such that the
+                    <filename>do_configure</filename> task for recipe "a"
+                    depends on the <filename>do_populate_sysroot</filename>
+                    task of recipe "b".
+                    This means anything that recipe "b" puts into sysroot
+                    is available when recipe "a" is configuring itself.
+                </para>
+
+                <para>
+                    For information on runtime dependencies, see the
+                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEPLOY_DIR'><glossterm>DEPLOY_DIR</glossterm>
+            <glossdef>
+                <para>
+                    Points to the general area that the OpenEmbedded build
+                    system uses to place images, packages, SDKs and other output
+                    files that are ready to be used outside of the build system.
+                    By default, this directory resides within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    as <filename>tmp/deploy</filename>.
+                </para>
+
+                <para>
+                    For more information on the structure of the Build
+                    Directory, see
+                    "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
+                    section.
+                    For more detail on the contents of the
+                    <filename>deploy</filename> directory, see the
+                    "<link linkend='images-dev-environment'>Images</link>" and
+                    "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+                    sections.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DEPLOY_DIR_IMAGE'><glossterm>DEPLOY_DIR_IMAGE</glossterm>
+            <glossdef>
+                <para>
+                    Points to the area that the OpenEmbedded build system uses
+                    to place images and other associated output files that are
+                    ready to be deployed onto the target machine.
+                    The directory is machine-specific as it contains the
+                    <filename>${MACHINE}</filename> name.
+                    By default, this directory resides within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    as <filename>tmp/deploy/images/${MACHINE}/</filename>.
+                </para>
+
+                <para>
+                    For more information on the structure of the Build
+                    Directory, see
+                    "<link linkend='structure-build'>The Build Directory - <filename>build/</filename></link>"
+                    section.
+                    For more detail on the contents of the
+                    <filename>deploy</filename> directory, see the
+                    "<link linkend='images-dev-environment'>Images</link>" and
+                    "<link linkend='sdk-dev-environment'>Application Development SDK</link>"
+                    sections.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DESCRIPTION'><glossterm>DESCRIPTION</glossterm>
+            <glossdef>
+                <para>The package description used by package managers.
+                      If not set, <filename>DESCRIPTION</filename> takes
+                      the value of the
+                      <link linkend='var-SUMMARY'><filename>SUMMARY</filename></link>
+                      variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO'><glossterm>DISTRO</glossterm>
+            <glossdef>
+                <para>
+                    The short name of the distribution.
+                    This variable corresponds to a file with the
+                    extension <filename>.conf</filename>
+                    located in a <filename>conf/distro</filename> directory
+                    within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                    that contains the distribution configuration.
+                    The value must not contain spaces, and is typically all lower-case.
+                </para>
+                <para>
+                    If the variable is blank, a set of default configuration
+                    will be used, which is specified
+                    within <filename>meta/conf/distro/defaultsetup.conf</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_EXTRA_RDEPENDS'><glossterm>DISTRO_EXTRA_RDEPENDS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a list of distro-specific packages to add to all images.
+                    This variable takes affect through
+                    <filename>packagegroup-base</filename> so the
+                    variable only really applies to the more full-featured
+                    images that include <filename>packagegroup-base</filename>.
+                    You can use this variable to keep distro policy out of
+                    generic images.
+                    As with all other distro variables, you set this variable
+                    in the distro <filename>.conf</filename> file.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_EXTRA_RRECOMMENDS'><glossterm>DISTRO_EXTRA_RRECOMMENDS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a list of distro-specific packages to add to all images
+                    if the packages exist.
+                    The packages might not exist or be empty (e.g. kernel modules).
+                    The list of packages are automatically installed but you can
+                    remove them.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES'><glossterm>DISTRO_FEATURES</glossterm>
+            <glossdef>
+                <para>The features enabled for the distribution.
+                    For a list of supported features that ship with the
+                    Yocto Project, see the
+                    "<link linkend='ref-features-distro'>Distro</link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES_BACKFILL'><glossterm>DISTRO_FEATURES_BACKFILL</glossterm>
+            <glossdef>
+                <para>Features to be added to
+                    <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>
+                    if not also present in
+                    <filename><link linkend='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'>DISTRO_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+                </para>
+
+                <para>
+                    This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
+                    It is not intended to be user-configurable.
+                    It is best to just reference the variable to see which distro features are
+                    being backfilled for all distro configurations.
+                    See the <link linkend='ref-features-backfill'>Feature backfilling</link> section for
+                    more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_FEATURES_BACKFILL_CONSIDERED'><glossterm>DISTRO_FEATURES_BACKFILL_CONSIDERED</glossterm>
+            <glossdef>
+                <para>Features from
+                    <filename><link linkend='var-DISTRO_FEATURES_BACKFILL'>DISTRO_FEATURES_BACKFILL</link></filename>
+                    that should not be backfilled (i.e. added to
+                    <filename><link linkend='var-DISTRO_FEATURES'>DISTRO_FEATURES</link></filename>)
+                    during the build.
+                    See the "<link linkend='ref-features-backfill'>Feature Backfilling</link>" section for
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_NAME'><glossterm>DISTRO_NAME</glossterm>
+            <glossdef>
+                <para>The long name of the distribution.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_PN_ALIAS'><glossterm>DISTRO_PN_ALIAS</glossterm>
+            <glossdef>
+                <para>Alias names used for the recipe in various Linux distributions.</para>
+                <para>See the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-configuring-DISTRO_PN_ALIAS'>Handling
+                    a Package Name Alias</ulink>" section in the Yocto Project Development
+                    Manual for more information.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTRO_VERSION'><glossterm>DISTRO_VERSION</glossterm>
+            <glossdef>
+                <para>the version of the distribution.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DISTROOVERRIDES'><glossterm>DISTROOVERRIDES</glossterm>
+            <glossdef>
+                <para>
+                    This variable lists overrides specific to the current
+                    distribution.
+                    By default, the variable list includes the value of the
+                    <filename><link linkend='var-DISTRO'>DISTRO</link></filename>
+                    variable.
+                    You can extend the variable to apply any variable overrides
+                    you want as part of the distribution and are not
+                    already in <filename>OVERRIDES</filename> through
+                    some other means.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-DL_DIR'><glossterm>DL_DIR</glossterm>
+            <glossdef>
+                <para>
+                    The central download directory used by the build process to
+                    store downloads.
+                    By default, <filename>DL_DIR</filename> gets files
+                    suitable for mirroring for everything except Git
+                    repositories.
+                    If you want tarballs of Git repositories, use the
+                    <link linkend='var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></link>
+                    variable.
+                </para>
+
+                <para>
+                    You can set this directory by defining the
+                    <filename>DL_DIR</filename> variable in the
+                    <filename>/conf/local.conf</filename> file.
+                    This directory is self-maintaining and you should not have
+                    to touch it.
+                    By default, the directory is <filename>downloads</filename>
+                    in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    <literallayout class='monospaced'>
+     #DL_DIR ?= "${TOPDIR}/downloads"
+                    </literallayout>
+                    To specify a different download directory, simply remove
+                    the comment from the line and provide your directory.
+                </para>
+
+                <para>
+                    During a first build, the system downloads many different
+                    source code tarballs from various upstream projects.
+                    Downloading can take a while, particularly if your network
+                    connection is slow.
+                    Tarballs are all stored in the directory defined by
+                    <filename>DL_DIR</filename> and the build system looks there
+                    first to find source tarballs.
+                    <note>
+                        When wiping and rebuilding, you can preserve this
+                        directory to speed up this part of subsequent
+                        builds.
+                    </note>
+                </para>
+
+                <para>
+                    You can safely share this directory between multiple builds
+                    on the same development machine.
+                    For additional information on how the build process gets
+                    source files when working behind a firewall or proxy server,
+                    see this specific question in the
+                    "<link linkend='how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>FAQ</link>"
+                    chapter.
+                </para>
+            </glossdef>
+
+        </glossentry>
+    </glossdiv>
+
+    <glossdiv id='var-glossary-e'><title>E</title>
+
+        <glossentry id='var-ENABLE_BINARY_LOCALE_GENERATION'><glossterm>ENABLE_BINARY_LOCALE_GENERATION</glossterm>
+            <glossdef>
+                <para></para>
+                <para>Variable that controls which locales for
+                    <filename>eglibc</filename> are generated during the
+                    build (useful if the target device has 64Mbytes
+                    of RAM or less).</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-ERROR_QA'><glossterm>ERROR_QA</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the quality assurance checks whose failures are
+                    reported as errors by the OpenEmbedded build system.
+                    You set this variable in your distribution configuration
+                    file.
+                    For a list of the checks you can control with this variable,
+                    see the
+                    "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXCLUDE_FROM_WORLD'><glossterm>EXCLUDE_FROM_WORLD</glossterm>
+            <glossdef>
+                <para>
+                    Directs BitBake to exclude a recipe from world builds (i.e.
+                    <filename>bitbake world</filename>).
+                    During world builds, BitBake locates, parses and builds all
+                    recipes found in every layer exposed in the
+                    <filename>bblayers.conf</filename> configuration file.
+                </para>
+
+                <para>
+                    To exclude a recipe from a world build using this variable,
+                    set the variable to "1" in the recipe.
+                </para>
+
+                <note>
+                    Recipes added to <filename>EXCLUDE_FROM_WORLD</filename>
+                    may still be built during a world build in order to satisfy
+                    dependencies of other recipes.
+                    Adding a recipe to <filename>EXCLUDE_FROM_WORLD</filename>
+                    only ensures that the recipe is not explicitly added
+                    to the list of build targets in a world build.
+                </note>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTENDPE'><glossterm>EXTENDPE</glossterm>
+            <glossdef>
+                <para>
+                    Used with file and pathnames to create a prefix for a recipe's
+                    version based on the recipe's
+                    <link linkend='var-PE'><filename>PE</filename></link> value.
+                    If <filename>PE</filename> is set and greater than zero for a recipe,
+                    <filename>EXTENDPE</filename> becomes that value (e.g if
+                    <filename>PE</filename> is equal to "1" then <filename>EXTENDPE</filename>
+                    becomes "1_").
+                    If a recipe's <filename>PE</filename> is not set (the default) or is equal to
+                    zero, <filename>EXTENDPE</filename> becomes "".</para>
+                    <para>See the <link linkend='var-STAMP'><filename>STAMP</filename></link>
+                    variable for an example.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTENDPKGV'><glossterm>EXTENDPKGV</glossterm>
+            <glossdef>
+                <para>
+                    The full package version specification as it appears on the
+                    final packages produced by a recipe.
+                    The variable's value is normally used to fix a runtime
+                    dependency to the exact same version of another package
+                    in the same recipe:
+                    <literallayout class='monospaced'>
+     RDEPENDS_${PN}-additional-module = "${PN} (= ${EXTENDPKGV})"
+                    </literallayout>
+                </para>
+
+                <para>
+                    The dependency relationships are intended to force the
+                    package manager to upgrade these types of packages in
+                    lock-step.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTERNALSRC'><glossterm>EXTERNALSRC</glossterm>
+            <glossdef>
+                <para>
+                    If <filename>externalsrc.bbclass</filename> is inherited,
+                    this variable points to the source tree, which is
+                    outside of the OpenEmbedded build system.
+                    When set, this variable sets the
+                    <link linkend='var-S'><filename>S</filename></link>
+                    variable, which is what the OpenEmbedded build system uses
+                    to locate unpacked recipe source code.
+                </para>
+
+                <para>
+                    For more information on
+                    <filename>externalsrc.bbclass</filename>, see the
+                    "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
+                    section.
+                    You can also find information on how to use this variable
+                    in the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTERNALSRC_BUILD'><glossterm>EXTERNALSRC_BUILD</glossterm>
+            <glossdef>
+                <para>
+                    If <filename>externalsrc.bbclass</filename> is inherited,
+                    this variable points to the directory in which the recipe's
+                    source code is built,
+                    which is outside of the OpenEmbedded build system.
+                    When set, this variable sets the
+                    <link linkend='var-B'><filename>B</filename></link>
+                    variable, which is what the OpenEmbedded build system uses
+                    to locate the Build Directory.
+                </para>
+
+                <para>
+                    For more information on
+                    <filename>externalsrc.bbclass</filename>, see the
+                    "<link linkend='ref-classes-externalsrc'><filename>externalsrc.bbclass</filename></link>"
+                    section.
+                    You can also find information on how to use this variable
+                    in the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#building-software-from-an-external-source'>Building Software from an External Source</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTRA_IMAGE_FEATURES'><glossterm>EXTRA_IMAGE_FEATURES</glossterm>
+            <glossdef>
+                <para>
+                    The list of additional features to include in an image.
+                    Typically, you configure this variable in your
+                    <filename>local.conf</filename> file, which is found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    Although you can use this variable from within a recipe,
+                    best practices dictate that you do not.
+                    <note>
+                        To enable primary features from within the image
+                        recipe, use the
+                        <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>
+                        variable.
+                    </note>
+                </para>
+
+                <para>
+                    Here are some examples of features you can add:
+                    <literallayout class='monospaced'>
+"dbg-pkgs" - Adds -dbg packages for all installed packages
+             including symbol information for debugging and
+             profiling.
+
+"debug-tweaks" - Makes an image suitable for development.
+                 For example, ssh root access has a blank
+                 password.  You should remove this feature
+                 before you produce a production image.
+
+"dev-pkgs" - Adds -dev packages for all installed packages.
+             This is useful if you want to develop against
+             the libraries in the image.
+
+"read-only-rootfs" - Creates an image whose root
+                     filesystem is read-only. See the
+                     "<ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>Creating a Read-Only Root Filesystem</ulink>"
+                     section in the Yocto Project
+                     Development Manual for more
+                     information
+
+"tools-debug" - Adds debugging tools such as gdb and
+                strace.
+
+"tools-profile" - Adds profiling tools such as oprofile,
+                  exmap, lttng and valgrind (x86 only).
+
+"tools-sdk" - Adds development tools such as gcc, make,
+              pkgconfig and so forth.
+
+"tools-testapps" - Adds useful testing tools such as
+                   ts_print, aplay, arecord and so
+                   forth.
+
+                    </literallayout>
+                </para>
+
+                <para>
+                    For a complete list of image features that ships with the
+                    Yocto Project, see the
+                    "<link linkend="ref-features-image">Images</link>"
+                    section.
+                </para>
+
+                <para>
+                    For an example that shows how to customize your image by
+                    using this variable, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTRA_IMAGEDEPENDS'><glossterm>EXTRA_IMAGEDEPENDS</glossterm>
+            <glossdef>
+                <para>A list of recipes to build that do not provide packages
+                    for installing into the root filesystem.
+                </para>
+                <para>Sometimes a recipe is required to build the final image but is not
+                    needed in the root filesystem.
+                    You can use the <filename>EXTRA_IMAGEDEPENDS</filename> variable to
+                    list these recipes and thus, specify the dependencies.
+                    A typical example is a required bootloader in a machine configuration.
+                </para>
+                <note>
+                    To add packages to the root filesystem, see the various
+                    <filename>*<link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
+                    and <filename>*<link linkend='var-RRECOMMENDS'>RRECOMMENDS</link></filename>
+                    variables.
+                </note>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTRA_OECMAKE'><glossterm>EXTRA_OECMAKE</glossterm>
+            <glossdef>
+                <para>Additional <filename>cmake</filename> options.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTRA_OECONF'><glossterm>EXTRA_OECONF</glossterm>
+            <glossdef>
+                <para>Additional <filename>configure</filename> script options.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-EXTRA_OEMAKE'><glossterm>EXTRA_OEMAKE</glossterm>
+            <glossdef>
+                <para>Additional GNU <filename>make</filename> options.</para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-f'><title>F</title>
+
+        <glossentry id='var-FILES'><glossterm>FILES</glossterm>
+            <glossdef>
+                <para>
+                    The list of directories or files that are placed in packages.
+                </para>
+
+                <para>
+                    To use the <filename>FILES</filename> variable, provide a package name
+                    override that identifies the resulting package.
+                    Then, provide a space-separated list of files or paths that identifies the
+                    files you want included as part of the resulting package.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+  FILES_${PN} += "${bindir}/mydir1/ ${bindir}/mydir2/myfile"
+                    </literallayout>
+                </para>
+
+                <note>
+                    When specifying paths as part of the <filename>FILES</filename> variable,
+                    it is good practice to use appropriate path variables.
+                    For example, <filename>${sysconfdir}</filename> rather than
+                    <filename>/etc</filename> or <filename>${bindir}</filename> rather
+                    than <filename>/usr/bin</filename>.
+                    You can find a list of these variables at the top of the
+                    <filename>/meta/conf/bitbake.conf</filename> file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </note>
+
+                <para>
+                    If some of the files you provide with the <filename>FILES</filename> variable
+                    are editable and you know they should not be
+                    overwritten during the package update process by the Package Management
+                    System (PMS), you can identify these files so that the PMS will not
+                    overwrite them.
+                    See the <filename><link linkend='var-CONFFILES'>CONFFILES</link></filename>
+                    variable for information on how to identify these files to the PMS.
+                </para>
+
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-FILESEXTRAPATHS'><glossterm>FILESEXTRAPATHS</glossterm>
+            <glossdef>
+                <para>
+                    Extends the search path the OpenEmbedded build system uses
+                    when looking for files and patches as it processes recipes
+                    and append files.
+                    The default directories BitBake uses when it processes
+                    recipes are initially defined by the
+                    <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
+                    variable.
+                    You can extend <filename>FILESPATH</filename> variable
+                    by using <filename>FILESEXTRAPATHS</filename>.
+                </para>
+
+                <para>
+                    Best practices dictate that you accomplish this by using
+                    <filename>FILESEXTRAPATHS</filename> from within a
+                    <filename>.bbappend</filename> file and that you prepend
+                    paths as follows:
+                    <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/${PN}:"
+                    </literallayout>
+                    In the above example, the build system first looks for files
+                    in a directory that has the same name as the corresponding
+                    append file.
+                    <note>
+                        <para>When extending <filename>FILESEXTRAPATHS</filename>,
+                        be sure to use the immediate expansion
+                        (<filename>:=</filename>) operator.
+                        Immediate expansion makes sure that BitBake evaluates
+                        <link linkend='var-THISDIR'><filename>THISDIR</filename></link>
+                        at the time the directive is encountered rather than at
+                        some later time when expansion might result in a
+                        directory that does not contain the files you need.
+                        </para>
+                        <para>Also, include the trailing separating colon
+                        character if you are prepending.
+                        The trailing colon character is necessary because you
+                        are directing BitBake to extend the path by prepending
+                        directories to the search path.</para>
+                    </note>
+                    Here is another common use:
+                    <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "${THISDIR}/files:"
+                    </literallayout>
+                    In this example, the build system extends the
+                    <filename>FILESPATH</filename> variable to include a
+                    directory named <filename>files</filename> that is in the
+                    same directory as the corresponding append file.
+                </para>
+
+                <para>
+                    Here is a final example that specifically adds three paths:
+                    <literallayout class='monospaced'>
+     FILESEXTRAPATHS_prepend := "path_1:path_2:path_3:"
+                    </literallayout>
+                </para>
+
+                <para>
+                    By prepending paths in <filename>.bbappend</filename>
+                    files, you allow multiple append files that reside in
+                    different layers but are used for the same recipe to
+                    correctly extend the path.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-FILESOVERRIDES'><glossterm>FILESOVERRIDES</glossterm>
+            <glossdef>
+                <para>
+                    A subset of <link linkend='var-OVERRIDES'><filename>OVERRIDES</filename></link>
+                    used by the OpenEmbedded build system for creating
+                    <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>.
+                    You can find more information on how overrides are handled
+                    in the BitBake Manual that is located at
+                    <filename>bitbake/doc/manual</filename> in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+
+                <para>
+                    By default, the <filename>FILESOVERRIDES</filename>
+                    variable is defined as:
+                    <literallayout class='monospaced'>
+     FILESOVERRIDES = "${TRANSLATED_TARGET_ARCH}:${MACHINEOVERRIDES}:${DISTROOVERRIDES}"
+                    </literallayout>
+
+                    <note>
+                        Do not hand-edit the <filename>FILESOVERRIDES</filename>
+                        variable.
+                        The values match up with expected overrides and are
+                        used in an expected manner by the build system.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-FILESPATH'><glossterm>FILESPATH</glossterm>
+            <glossdef>
+                <para>
+                    The default set of directories the OpenEmbedded build system
+                    uses when searching for patches and files.
+                    During the build process, BitBake searches each directory in
+                    <filename>FILESPATH</filename> in the specified order when
+                    looking for files and patches specified by each
+                    <filename>file://</filename> URI in a recipe.
+                </para>
+
+                <para>
+                    The default value for the <filename>FILESPATH</filename>
+                    variable is defined in the <filename>base.bbclass</filename>
+                    class found in <filename>meta/classes</filename> in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
+                    <literallayout class='monospaced'>
+     FILESPATH = "${@base_set_filespath(["${FILE_DIRNAME}/${BP}", \
+        "${FILE_DIRNAME}/${BPN}", "${FILE_DIRNAME}/files"], d)}"
+                    </literallayout>
+                    <note>
+                        Do not hand-edit the <filename>FILESPATH</filename>
+                        variable.
+                        If you want the build system to look in directories
+                        other than the defaults, extend the
+                        <filename>FILESPATH</filename> variable by using the
+                        <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
+                        variable.
+                    </note>
+                    Be aware that the default <filename>FILESPATH</filename>
+                    directories do not map to directories in custom layers
+                    where append files (<filename>.bbappend</filename>)
+                    are used.
+                    If you want the build system to find patches or files
+                    that reside with your append files, you need to extend
+                    the <filename>FILESPATH</filename> variable by using
+                    the
+                    <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-FILESYSTEM_PERMS_TABLES'><glossterm>FILESYSTEM_PERMS_TABLES</glossterm>
+            <glossdef>
+                <para>Allows you to define your own file permissions settings table as part of
+                    your configuration for the packaging process.
+                    For example, suppose you need a consistent set of custom permissions for
+                    a set of groups and users across an entire work project.
+                    It is best to do this in the packages themselves but this is not always
+                    possible.
+                </para>
+                <para>
+                    By default, the OpenEmbedded build system uses the <filename>fs-perms.txt</filename>, which
+                    is located in the <filename>meta/files</filename> folder in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                    If you create your own file permissions setting table, you should place it in your
+                    layer or the distros layer.
+                </para>
+                <para>
+                    You define the <filename>FILESYSTEM_PERMS_TABLES</filename> variable in the
+                    <filename>conf/local.conf</filename> file, which is found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>, to
+                    point to your custom <filename>fs-perms.txt</filename>.
+                    You can specify more than a single file permissions setting table.
+                    The paths you specify to these files must be defined within the
+                    <link linkend='var-BBPATH'><filename>BBPATH</filename></link> variable.
+                </para>
+                <para>
+                    For guidance on how to create your own file permissions settings table file,
+                    examine the existing <filename>fs-perms.txt</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-FULL_OPTIMIZATION'><glossterm>FULL_OPTIMIZATION</glossterm>
+            <glossdef>
+                <para>
+                    The options to pass in
+                    <filename><link linkend='var-TARGET_CFLAGS'>TARGET_CFLAGS</link></filename>
+                    and <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>
+                    when compiling an optimized system.
+                    This variable defaults to
+                    "-fexpensive-optimizations -fomit-frame-pointer -frename-registers -O2".
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+<!--            <glossdiv id='var-glossary-g'><title>G</title>-->
+<!--            </glossdiv>-->
+
+    <glossdiv id='var-glossary-h'><title>H</title>
+
+        <glossentry id='var-HOMEPAGE'><glossterm>HOMEPAGE</glossterm>
+            <glossdef>
+                <para>Website where more information about the software the recipe is building
+                    can be found.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-HOST_SYS'><glossterm>HOST_SYS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the system, including the architecture and the
+                    operating system, for with the build is occurring
+                    in the context of the current
+                    recipe.
+                    The OpenEmbedded build system automatically sets this
+                    variable.
+                    You do not need to set the variable yourself.
+                </para>
+
+                <para>
+                    Here are two examples:
+                    <itemizedlist>
+                        <listitem><para>Given a native recipe on a 32-bit
+                            x86 machine running Linux, the value is
+                            "i686-linux".
+                            </para></listitem>
+                        <listitem><para>Given a recipe being built for a
+                            little-endian MIPS target running Linux,
+                            the value might be "mipsel-linux".
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-i'><title>I</title>
+
+        <glossentry id='var-IMAGE_BASENAME'><glossterm>IMAGE_BASENAME</glossterm>
+            <glossdef>
+                <para>
+                    The base name of image output files.
+                    This variable defaults to the recipe name
+                    (<filename>${</filename><link linkend='var-PN'><filename>PN</filename></link><filename>}</filename>).
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_CLASSES'><glossterm>IMAGE_CLASSES</glossterm>
+            <glossdef>
+                <para>
+                    A list of classes that all images should inherit.
+                    You typically use this variable to specify the list of
+                    classes that register the different types of images
+                    the OpenEmbedded build system creates.
+                </para>
+
+                <para>
+                    The default value for <filename>IMAGE_CLASSES</filename> is
+                    <filename>image_types</filename>.
+                    You can set this variable in your
+                    <filename>local.conf</filename> or in a distribution
+                    configuration file.
+                </para>
+
+                <para>
+                    For more information, see
+                    <filename>meta/classes/image_types.bbclass</filename> in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_FEATURES'><glossterm>IMAGE_FEATURES</glossterm>
+            <glossdef>
+                <para>
+                    The primary list of features to include in an image.
+                    Typically, you configure this variable in an image recipe.
+                    Although you can use this variable from your
+                    <filename>local.conf</filename> file, which is found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+                    best practices dictate that you do not.
+                    <note>
+                        To enable extra features from outside the image recipe,
+                        use the
+                        <filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES</link></filename> variable.
+                    </note>
+                    For a list of image features that ships with the Yocto
+                    Project, see the
+                    "<link linkend="ref-features-image">Images</link>"
+                    section.
+                </para>
+
+                <para>
+                    For example that shows how to customize your image by
+                    using this variable, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#usingpoky-extend-customimage-imagefeatures'>Customizing Images Using Custom <filename>IMAGE_FEATURES</filename> and <filename>EXTRA_IMAGE_FEATURES</filename></ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_FSTYPES'><glossterm>IMAGE_FSTYPES</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the formats the OpenEmbedded build system uses
+                    during the build when creating the root filesystem.
+                    For example, setting <filename>IMAGE_FSTYPES</filename>
+                    as follows causes the build system to create root
+                    filesystems using two formats: <filename>.ext3</filename>
+                    and <filename>tar.bz2</filename>:
+                    <literallayout class='monospaced'>
+     IMAGE_FSTYPES = "ext3 tar.bz2"
+                    </literallayout>
+                    For the complete list of supported image formats from which
+                    you can choose, see
+                    <link linkend='var-IMAGE_TYPES'><filename>IMAGE_TYPES</filename></link>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_INSTALL'><glossterm>IMAGE_INSTALL</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the packages to install into an image.
+                    The <filename>IMAGE_INSTALL</filename> variable is a mechanism for an image
+                    recipe and you should use it with care to avoid ordering issues.
+                </para>
+
+                <para>
+                    Image recipes set <filename>IMAGE_INSTALL</filename> to specify the
+                    packages to install into an image through <filename>image.bbclass</filename>.
+                    Additionally, "helper" classes exist, such as <filename>core-image.bbclass</filename>,
+                    that can take
+                    <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename> lists
+                    and turn these into auto-generated entries in
+                    <filename>IMAGE_INSTALL</filename> in addition to its default contents.
+                </para>
+
+                <para>
+                    Using <filename>IMAGE_INSTALL</filename> with the <filename>+=</filename>
+                    operator from the <filename>/conf/local.conf</filename> file or from within
+                    an image recipe is not recommended as it can cause ordering issues.
+                    Since <filename>core-image.bbclass</filename> sets <filename>IMAGE_INSTALL</filename>
+                    to a default value using the <filename>?=</filename> operator, using a
+                    <filename>+=</filename> operation against <filename>IMAGE_INSTALL</filename>
+                    will result in unexpected behavior when used in
+                    <filename>/conf/local.conf</filename>.
+                    Furthermore, the same operation from with an image recipe may or may not
+                    succeed depending on the specific situation.
+                    In both these cases, the behavior is contrary to how most users expect
+                    the <filename>+=</filename> operator to work.
+                </para>
+
+                <para>
+                    When you use this variable, it is best to use it as follows:
+                    <literallayout class='monospaced'>
+     IMAGE_INSTALL_append = " package-name"
+                    </literallayout>
+                    Be sure to include the space between the quotation character and the start of the
+                    package name.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_LINGUAS'><glossterm>IMAGE_LINGUAS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the list of locales to install into the image
+                    during the root filesystem construction process.
+                    The OpenEmbedded build system automatically splits locale
+                    files, which are used for localization, into separate
+                    packages.
+                    Setting the <filename>IMAGE_LINGUAS</filename> variable
+                    ensures that any locale packages that correspond to packages
+                    already selected for installation into the image are also
+                    installed.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     IMAGE_LINGUAS = "pt-br de-de"
+                    </literallayout>
+                    In this example, the build system ensures any Brazilian
+                    Portuguese and German locale files that correspond to
+                    packages in the image are installed (i.e.
+                    <filename>*-locale-pt-br</filename>
+                    and <filename>*-locale-de-de</filename> as well as
+                    <filename>*-locale-pt</filename>
+                    and <filename>*-locale-de</filename>, since some software
+                    packages only provide locale files by language and not by
+                    country-specific language).
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_NAME'><glossterm>IMAGE_NAME</glossterm>
+            <glossdef>
+                <para>
+                    The name of the output image files minus the extension.
+                    This variable is derived using the
+                    <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
+                    <link linkend='var-MACHINE'><filename>MACHINE</filename></link>,
+                    and
+                    <link linkend='var-DATETIME'><filename>DATETIME</filename></link>
+                    variables:
+                    <literallayout class='monospaced'>
+     IMAGE_NAME = "${IMAGE_BASENAME}-${MACHINE}-${DATETIME}"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_OVERHEAD_FACTOR'><glossterm>IMAGE_OVERHEAD_FACTOR</glossterm>
+            <glossdef>
+                <para>
+                    Defines a multiplier that the build system applies to the initial image
+                    size for cases when the multiplier times the returned disk usage value
+                    for the image is greater than the sum of
+                    <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
+                    and
+                    <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>.
+                    The result of the multiplier applied to the initial image size creates
+                    free disk space in the image as overhead.
+                    By default, the build process uses a multiplier of 1.3 for this variable.
+                    This default value results in 30% free disk space added to the image when this
+                    method is used to determine the final generated image size.
+                    You should be aware that post install scripts and the package management
+                    system uses disk space inside this overhead area.
+                    Consequently, the multiplier does not produce an image with
+                    all the theoretical free disk space.
+                    See <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>
+                    for information on how the build system determines the overall image size.
+                </para>
+
+                <para>
+                    The default 30% free disk space typically gives the image enough room to boot
+                    and allows for basic post installs while still leaving a small amount of
+                    free disk space.
+                    If 30% free space is inadequate, you can increase the default value.
+                    For example, the following setting gives you 50% free space added to the image:
+                    <literallayout class='monospaced'>
+     IMAGE_OVERHEAD_FACTOR = "1.5"
+                    </literallayout>
+                </para>
+
+                <para>
+                    Alternatively, you can ensure a specific amount of free disk space is added
+                    to the image by using
+                    <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
+                    the variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_POSTPROCESS_COMMAND'><glossterm>IMAGE_POSTPROCESS_COMMAND</glossterm>
+            <glossdef>
+                <para>
+                    Added by classes to run post processing commands once the
+                    OpenEmbedded build system has created the image.
+                    You can specify shell commands separated by semicolons:
+                    <literallayout class='monospaced'>
+     IMAGE_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
+                    </literallayout>
+                    If you need to pass the path to the root filesystem within
+                    the command, you can use
+                    <filename>${IMAGE_ROOTFS}</filename>, which points to
+                    the root filesystem image.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_ROOTFS'><glossterm>IMAGE_ROOTFS</glossterm>
+            <glossdef>
+                <para>
+                    The location of the root filesystem while it is under
+                    construction (i.e. during <filename>do_rootfs</filename>).
+                    This variable is not configurable.
+                    Do not change it.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_ROOTFS_EXTRA_SPACE'><glossterm>IMAGE_ROOTFS_EXTRA_SPACE</glossterm>
+            <glossdef>
+                <para>
+                    Defines additional free disk space created in the image in Kbytes.
+                    By default, this variable is set to "0".
+                    This free disk space is added to the image after the build system determines
+                    the image size as described in
+                    <filename><link linkend='var-IMAGE_ROOTFS_SIZE'>IMAGE_ROOTFS_SIZE</link></filename>.
+                </para>
+
+                <para>
+                    This variable is particularly useful when you want to ensure that a
+                    specific amount of free disk space is available on a device after an image
+                    is installed and running.
+                    For example, to be sure 5 Gbytes of free disk space is available, set the
+                    variable as follows:
+                    <literallayout class='monospaced'>
+     IMAGE_ROOTFS_EXTRA_SPACE = "5242880"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_ROOTFS_SIZE'><glossterm>IMAGE_ROOTFS_SIZE</glossterm>
+            <glossdef>
+                <para>
+                    Defines the size in Kbytes for the generated image.
+                    The OpenEmbedded build system determines the final size for the generated
+                    image using an algorithm that takes into account the initial disk space used
+                    for the generated image, a requested size for the image, and requested
+                    additional free disk space to be added to the image.
+                    Programatically, the build system determines the final size of the
+                    generated image as follows:
+                    <literallayout class='monospaced'>
+    if (image-du * overhead) &lt; rootfs-size:
+        internal-rootfs-size = rootfs-size + xspace
+    else:
+        internal-rootfs-size = (image-du * overhead) + xspace
+
+    where:
+
+      image-du = Returned value of the du command on
+                 the image.
+
+      overhead = IMAGE_OVERHEAD_FACTOR
+
+      rootfs-size = IMAGE_ROOTFS_SIZE
+
+      internal-rootfs-size = Initial root filesystem
+                             size before any modifications.
+
+      xspace = IMAGE_ROOTFS_EXTRA_SPACE
+                    </literallayout>
+                    See the <link linkend='var-IMAGE_OVERHEAD_FACTOR'><filename>IMAGE_OVERHEAD_FACTOR</filename></link>
+                    and <link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'><filename>IMAGE_ROOTFS_EXTRA_SPACE</filename></link>
+                    variables for related information.
+<!--                    In the above example, <filename>overhead</filename> is defined by the
+                    <filename><link linkend='var-IMAGE_OVERHEAD_FACTOR'>IMAGE_OVERHEAD_FACTOR</link></filename>
+                    variable, <filename>xspace</filename> is defined by the
+                    <filename><link linkend='var-IMAGE_ROOTFS_EXTRA_SPACE'>IMAGE_ROOTFS_EXTRA_SPACE</link></filename>
+                    variable, and <filename>du</filename> is the results of the disk usage command
+                    on the initially generated image. -->
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IMAGE_TYPES'><glossterm>IMAGE_TYPES</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the complete list of supported image types
+                    by default:
+                    <literallayout class='monospaced'>
+     jffs2
+     sum.jffs2
+     cramfs
+     ext2
+     ext2.gz
+     ext2.bz2
+     ext3
+     ext3.gz
+     ext2.lzma
+     btrfs
+     live
+     squashfs
+     squashfs-xz
+     ubi
+     ubifs
+     tar
+     tar.gz
+     tar.bz2
+     tar.xz
+     cpio
+     cpio.gz
+     cpio.xz
+     cpio.lzma
+     vmdk
+     elf
+                    </literallayout>
+                    For more information on how these types of images, see
+                    <filename>meta/classes/image_types*.bbclass</filename>
+                    in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INC_PR'><glossterm>INC_PR</glossterm>
+            <glossdef>
+                <para>Helps define the recipe revision for recipes that share
+                    a common <filename>include</filename> file.
+                    You can think of this variable as part of the recipe revision
+                    as set from within an include file.</para>
+                <para>Suppose, for example, you have a set of recipes that
+                    are used across several projects.
+                    And, within each of those recipes the revision
+                    (its <link linkend='var-PR'><filename>PR</filename></link>
+                    value) is set accordingly.
+                    In this case, when the revision of those recipes changes,
+                    the burden is on you to find all those recipes and
+                    be sure that they get changed to reflect the updated
+                    version of the recipe.
+                    In this scenario, it can get complicated when recipes
+                    that are used in many places and provide common functionality
+                    are upgraded to a new revision.</para>
+                <para>A more efficient way of dealing with this situation is
+                    to set the <filename>INC_PR</filename> variable inside
+                    the <filename>include</filename> files that the recipes
+                    share and then expand the <filename>INC_PR</filename>
+                    variable within the recipes to help
+                    define the recipe revision.
+                    </para>
+                <para>
+                    The following provides an example that shows how to use
+                    the <filename>INC_PR</filename> variable
+                    given a common <filename>include</filename> file that
+                    defines the variable.
+                    Once the variable is defined in the
+                    <filename>include</filename> file, you can use the
+                    variable to set the <filename>PR</filename> values in
+                    each recipe.
+                    You will notice that when you set a recipe's
+                    <filename>PR</filename> you can provide more granular
+                    revisioning by appending values to the
+                    <filename>INC_PR</filename> variable:
+                    <literallayout class='monospaced'>
+recipes-graphics/xorg-font/xorg-font-common.inc:INC_PR = "r2"
+recipes-graphics/xorg-font/encodings_1.0.4.bb:PR = "${INC_PR}.1"
+recipes-graphics/xorg-font/font-util_1.3.0.bb:PR = "${INC_PR}.0"
+recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3"
+                    </literallayout>
+                    The first line of the example establishes the baseline
+                    revision to be used for all recipes that use the
+                    <filename>include</filename> file.
+                    The remaining lines in the example are from individual
+                    recipes and show how the <filename>PR</filename> value
+                    is set.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INCOMPATIBLE_LICENSE'><glossterm>INCOMPATIBLE_LICENSE</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a space-separated list of license names
+                    (as they would appear in
+                    <link linkend='var-LICENSE'><filename>LICENSE</filename></link>)
+                    that should be excluded from the build.
+                    Recipes that provide no alternatives to listed incompatible
+                    licenses are not built.
+                    Packages that are individually licensed with the specified
+                    incompatible licenses will be deleted.
+                </para>
+
+                <note>
+                    This functionality is only regularly tested using
+                    the following setting:
+                    <literallayout class='monospaced'>
+     INCOMPATIBLE_LICENSE = "GPLv3"
+                    </literallayout>
+                    Although you can use other settings, you might be required
+                    to remove dependencies on or provide alternatives to
+                    components that are required to produce a functional system
+                    image.
+                </note>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INHIBIT_DEFAULT_DEPS'><glossterm>INHIBIT_DEFAULT_DEPS</glossterm>
+            <glossdef>
+                <para>
+                    Prevents the default dependencies, namely the C compiler
+                    and standard C library (libc), from being added to
+                    <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>.
+                    This variable is usually used within recipes that do not
+                    require any compilation using the C compiler.
+                </para>
+
+                <para>
+                    Set the variable to "1" to prevent the default dependencies
+                    from being added.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INHIBIT_PACKAGE_STRIP'><glossterm>INHIBIT_PACKAGE_STRIP</glossterm>
+            <glossdef>
+                <para>
+                    If set to "1", causes the build to not strip binaries in resulting packages.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INHERIT'><glossterm>INHERIT</glossterm>
+            <glossdef>
+                <para>
+                    Causes the named class to be inherited at
+                    this point during parsing.
+                    The variable is only valid in configuration files.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INITRAMFS_FSTYPES'><glossterm>INITRAMFS_FSTYPES</glossterm>
+            <glossdef>
+                <para>
+                    Defines the format for the output image of an initial
+                    RAM disk (initramfs), which is used during boot.
+                    Supported formats are the same as those supported by the
+                    <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INITSCRIPT_NAME'><glossterm>INITSCRIPT_NAME</glossterm>
+            <glossdef>
+                <para>
+                    The filename of the initscript as installed to <filename>${etcdir}/init.d</filename>.
+                </para>
+                <para>
+                    This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
+                    The variable is Mandatory.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INITSCRIPT_PACKAGES'><glossterm>INITSCRIPT_PACKAGES</glossterm>
+            <glossdef>
+                <para>
+                    A list of the packages that contain initscripts.
+                    If multiple packages are specified, you need to append the package name
+                    to the other <filename>INITSCRIPT_*</filename> as an override.</para>
+                 <para>
+                    This variable is used in recipes when using <filename>update-rc.d.bbclass</filename>.
+                    The variable is optional and defaults to the
+                    <link linkend='var-PN'><filename>PN</filename></link> variable.
+                </para>
+           </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INITSCRIPT_PARAMS'><glossterm>INITSCRIPT_PARAMS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the options to pass to <filename>update-rc.d</filename>.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     INITSCRIPT_PARAMS = "start 99 5 2 . stop 20 0 1 6 ."
+                    </literallayout>
+                    In this example, the script has a runlevel of 99,
+                    starts the script in initlevels 2 and 5, and
+                    stops the script in levels 0, 1 and 6.
+                </para>
+                <para>
+                    The variable is mandatory and is used in recipes when using
+                    <filename>update-rc.d.bbclass</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-INSANE_SKIP'><glossterm>INSANE_SKIP</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the QA checks to skip for a specific package
+                    within a recipe.
+                    For example, to skip the check for symbolic link
+                    <filename>.so</filename> files in the main package of a
+                    recipe, add the following to the recipe.
+                    The package name override must be used, which in this
+                    example is <filename>${PN}</filename>:
+                    <literallayout class='monospaced'>
+     INSANE_SKIP_${PN} += "dev-so"
+                    </literallayout>
+                </para>
+                <para>
+                    See the "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
+                    section for a list of the valid QA checks you can
+                    specify using this variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-IPK_FEED_URIS'><glossterm>IPK_FEED_URIS</glossterm>
+            <glossdef>
+                <para>
+                    When the IPK backend is in use and package management
+                    is enabled on the target, you can use this variable to
+                    set up <filename>opkg</filename> in the target image
+                    to point to package feeds on a nominated server.
+                    Once the feed is established, you can perform
+                    installations or upgrades using the package manager
+                    at runtime.
+                </para>
+            </glossdef>
+        </glossentry>
+
+<!--
+        <glossentry id='var-INTERCEPT_DIR'><glossterm>INTERCEPT_DIR</glossterm>
+            <glossdef>
+                <para>
+                    An environment variable that defines the directory where
+                    post installation hooks are installed for the
+                    post install environment.
+                    This variable is fixed as follows:
+                    <literallayout class='monospaced'>
+     ${WORKDIR}/intercept_scripts
+                    </literallayout>
+                </para>
+
+                <para>
+                    After installation of a target's root filesystem,
+                    post installation scripts, which are essentially bash scripts,
+                    are all executed just a single time.
+                    Limiting execution of these scripts minimizes installation
+                    time that would be lengthened due to  certain packages
+                    triggering redundant operations.
+                    For example, consider the installation of font packages
+                    as a common example.
+                    Without limiting the execution of post installation scripts,
+                    all font directories would be rescanned to create the
+                    cache after each individual font package was installed.
+                </para>
+
+                <para>
+                    Do not edit the <filename>INTERCEPT_DIR</filename>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+-->
+
+    </glossdiv>
+
+<!--            <glossdiv id='var-glossary-j'><title>J</title>-->
+<!--            </glossdiv>-->
+
+   <glossdiv id='var-glossary-k'><title>K</title>
+
+        <glossentry id='var-KARCH'><glossterm>KARCH</glossterm>
+            <glossdef>
+                <para>
+                    Defines the kernel architecture used when assembling
+                    the configuration.
+                    Architectures supported for this release are:
+                    <literallayout class='monospaced'>
+     powerpc
+     i386
+     x86_64
+     arm
+     qemu
+     mips
+                    </literallayout>
+                </para>
+
+                <para>
+                    You define the <filename>KARCH</filename> variable in the
+                    <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KBRANCH'><glossterm>KBRANCH</glossterm>
+            <glossdef>
+                <para>
+                    A regular expression used by the build process to explicitly identify the kernel
+                    branch that is validated, patched and configured during a build.
+                    The <filename>KBRANCH</filename> variable is optional.
+                    You can use it to trigger checks to ensure the exact kernel branch you want is
+                    being used by the build process.
+                </para>
+
+                <para>
+                    Values for this variable are set in the kernel's recipe file and the kernel's
+                    append file.
+                    For example, if you are using the Yocto Project kernel that is based on the
+                    Linux 3.4 kernel, the kernel recipe file is the
+                    <filename>meta/recipes-kernel/linux/linux-yocto_3.4.bb</filename> file.
+                    Following is the default value for <filename>KBRANCH</filename> and the default
+                    override for the architectures the Yocto Project supports:
+                    <literallayout class='monospaced'>
+     KBRANCH_DEFAULT = "standard/base"
+     KBRANCH = "${KBRANCH_DEFAULT}"
+                    </literallayout>
+                    This branch exists in the <filename>linux-yocto-3.4</filename> kernel Git
+                    repository <ulink url='&YOCTO_GIT_URL;/cgit.cgi/linux-yocto-3.4/refs/heads'></ulink>.
+                </para>
+
+                <para>
+                    This variable is also used from the kernel's append file to identify the kernel
+                    branch specific to a particular machine or target hardware.
+                    The kernel's append file is located in the BSP layer for a given machine.
+                    For example, the kernel append file for the Crown Bay BSP is in the
+                    <filename>meta-intel</filename> Git repository and is named
+                    <filename>meta-crownbay/recipes-kernel/linux/linux-yocto_3.4.bbappend</filename>.
+                    Here are the related statements from the append file:
+                    <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE_crownbay = "crownbay"
+     KMACHINE_crownbay  = "crownbay"
+     KBRANCH_crownbay  = "standard/crownbay"
+
+     COMPATIBLE_MACHINE_crownbay-noemgd = "crownbay-noemgd"
+     KMACHINE_crownbay-noemgd  = "crownbay"
+     KBRANCH_crownbay-noemgd  = "standard/crownbay"
+                    </literallayout>
+                        The <filename>KBRANCH_*</filename> statements identify the kernel branch to
+                        use when building for the Crown Bay BSP.
+                        In this case there are two identical statements: one for each type of
+                        Crown Bay machine.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KBRANCH_DEFAULT'><glossterm>KBRANCH_DEFAULT</glossterm>
+            <glossdef>
+                <para>
+                    Defines the Linux kernel source repository's default
+                    branch used to build the Linux kernel.
+                    The <filename>KBRANCH_DEFAULT</filename> value is
+                    the default value for
+                    <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link>.
+                    Unless you specify otherwise,
+                    <filename>KBRANCH_DEFAULT</filename> initializes to
+                    "master".
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KERNEL_EXTRA_ARGS'><glossterm>KERNEL_EXTRA_ARGS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies additional <filename>make</filename>
+                    command-line arguments the OpenEmbedded build system
+                    passes on when compiling the kernel.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KERNEL_FEATURES'><glossterm>KERNEL_FEATURES</glossterm>
+            <glossdef>
+                <para>Includes additional metadata from the Yocto Project kernel Git repository.
+                    In the OpenEmbedded build system, the default Board Support Packages (BSPs)
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                    is provided through
+                    the <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>
+                    and <link linkend='var-KBRANCH'><filename>KBRANCH</filename></link> variables.
+                    You can use the <filename>KERNEL_FEATURES</filename> variable to further
+                    add metadata for all BSPs.</para>
+                <para>The metadata you add through this variable includes config fragments and
+                    features descriptions,
+                    which usually includes patches as well as config fragments.
+                    You typically override the <filename>KERNEL_FEATURES</filename> variable
+                    for a specific machine.
+                    In this way, you can provide validated, but optional, sets of kernel
+                    configurations and features.</para>
+                <para>For example, the following adds <filename>netfilter</filename> to all
+                    the Yocto Project kernels and adds sound support to the <filename>qemux86</filename>
+                    machine:
+                    <literallayout class='monospaced'>
+     # Add netfilter to all linux-yocto kernels
+     KERNEL_FEATURES="features/netfilter"
+
+     # Add sound support to the qemux86 machine
+     KERNEL_FEATURES_append_qemux86=" cfg/sound"
+                    </literallayout></para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KERNEL_IMAGETYPE'><glossterm>KERNEL_IMAGETYPE</glossterm>
+            <glossdef>
+                <para>The type of kernel to build for a device, usually set by the
+                    machine configuration files and defaults to "zImage".
+                    This variable is used
+                    when building the kernel and is passed to <filename>make</filename> as the target to
+                    build.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KERNEL_PATH'><glossterm>KERNEL_PATH</glossterm>
+            <glossdef>
+                <para>
+                    The location of the kernel sources.
+                    This variable is set to the value of the
+                    <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
+                    within the <filename>module.bbclass</filename> class.
+                    For information on how this variable is used, see the
+                    "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
+                    section.
+                </para>
+
+                <para>
+                    The <link linkend='var-KERNEL_SRC'><filename>KERNEL_SRC</filename></link>
+                    variable is identical to the <filename>KERNEL_PATH</filename>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KERNEL_SRC'><glossterm>KERNEL_SRC</glossterm>
+            <glossdef>
+                <para>
+                    The location of the kernel sources.
+                    This variable is set to the value of the
+                    <link linkend='var-STAGING_KERNEL_DIR'><filename>STAGING_KERNEL_DIR</filename></link>
+                    within the <filename>module.bbclass</filename> class.
+                    For information on how this variable is used, see the
+                    "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#incorporating-out-of-tree-modules'>Incorporating Out-of-Tree Modules</ulink>"
+                    section.
+                </para>
+
+                <para>
+                    The <link linkend='var-KERNEL_PATH'><filename>KERNEL_PATH</filename></link>
+                    variable is identical to the <filename>KERNEL_SRC</filename>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KFEATURE_DESCRIPTION'><glossterm>KFEATURE_DESCRIPTION</glossterm>
+            <glossdef>
+                <para>
+                    Provides a short description of a configuration fragment.
+                    You use this variable in the <filename>.scc</filename>
+                    file that describes a configuration fragment file.
+                    Here is the variable used in a file named
+                    <filename>smp.scc</filename> to describe SMP being
+                    enabled:
+                    <literallayout class='monospaced'>
+     define KFEATURE_DESCRIPTION "Enable SMP"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KMACHINE'><glossterm>KMACHINE</glossterm>
+            <glossdef>
+                <para>
+                    The machine as known by the kernel.
+                    Sometimes the machine name used by the kernel does not match the machine name
+                    used by the OpenEmbedded build system.
+                    For example, the machine name that the OpenEmbedded build system understands as
+                    <filename>qemuarm</filename> goes by a different name in the Linux Yocto kernel.
+                    The kernel understands that machine as <filename>arm_versatile926ejs</filename>.
+                    For cases like these, the <filename>KMACHINE</filename> variable maps the
+                    kernel machine name to the OpenEmbedded build system machine name.
+                </para>
+
+                <para>
+                    Kernel machine names are initially defined in the
+                    Yocto Linux Kernel's <filename>meta</filename> branch.
+                    From the <filename>meta</filename> branch, look in
+                    the <filename>meta/cfg/kernel-cache/bsp/&lt;bsp_name&gt;/&lt;bsp-name&gt;-&lt;kernel-type&gt;.scc</filename> file.
+                    For example, from the <filename>meta</filename> branch in the
+                    <filename>linux-yocto-3.0</filename> kernel, the
+                    <filename>meta/cfg/kernel-cache/bsp/cedartrail/cedartrail-standard.scc</filename> file
+                    has the following:
+                    <literallayout class='monospaced'>
+     define KMACHINE cedartrail
+     define KTYPE standard
+     define KARCH i386
+
+     include ktypes/standard
+     branch cedartrail
+
+     include cedartrail.scc
+                    </literallayout>
+                    You can see that the kernel understands the machine name for
+                    the Cedar Trail Board Support Package (BSP) as
+                    <filename>cedartrail</filename>.
+                </para>
+
+                <para>
+                    If you look in the Cedar Trail BSP layer in the
+                    <filename>meta-intel</filename>
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-repositories'>Source Repositories</ulink>
+                    at <filename>meta-cedartrail/recipes-kernel/linux/linux-yocto_3.0.bbappend</filename>,
+                    you will find the following statements among others:
+                    <literallayout class='monospaced'>
+     COMPATIBLE_MACHINE_cedartrail = "cedartrail"
+     KMACHINE_cedartrail  = "cedartrail"
+     KBRANCH_cedartrail  = "yocto/standard/cedartrail"
+     KERNEL_FEATURES_append_cedartrail += "bsp/cedartrail/cedartrail-pvr-merge.scc"
+     KERNEL_FEATURES_append_cedartrail += "cfg/efi-ext.scc"
+
+     COMPATIBLE_MACHINE_cedartrail-nopvr = "cedartrail"
+     KMACHINE_cedartrail-nopvr  = "cedartrail"
+     KBRANCH_cedartrail-nopvr  = "yocto/standard/cedartrail"
+     KERNEL_FEATURES_append_cedartrail-nopvr += " cfg/smp.scc"
+                    </literallayout>
+                    The <filename>KMACHINE</filename> statements in the kernel's append file make sure that
+                    the OpenEmbedded build system and the Yocto Linux kernel understand the same machine
+                    names.
+                </para>
+
+                <para>
+                    This append file uses two <filename>KMACHINE</filename> statements.
+                    The first is not really necessary but does ensure that the machine known to the
+                    OpenEmbedded build system as <filename>cedartrail</filename> maps to the machine
+                    in the kernel also known as <filename>cedartrail</filename>:
+                    <literallayout class='monospaced'>
+     KMACHINE_cedartrail  = "cedartrail"
+                    </literallayout>
+                </para>
+
+                <para>
+                    The second statement is a good example of why the <filename>KMACHINE</filename> variable
+                    is needed.
+                    In this example, the OpenEmbedded build system uses the <filename>cedartrail-nopvr</filename>
+                    machine name to refer to the Cedar Trail BSP that does not support the proprietary
+                    PowerVR driver.
+                    The kernel, however, uses the machine name <filename>cedartrail</filename>.
+                    Thus, the append file must map the <filename>cedartrail-nopvr</filename> machine name to
+                    the kernel's <filename>cedartrail</filename> name:
+                    <literallayout class='monospaced'>
+     KMACHINE_cedartrail-nopvr  = "cedartrail"
+                    </literallayout>
+                </para>
+
+                <para>
+                    BSPs that ship with the Yocto Project release provide all mappings between the Yocto
+                    Project kernel machine names and the OpenEmbedded machine names.
+                    Be sure to use the <filename>KMACHINE</filename> if you create a BSP and the machine
+                    name you use is different than that used in the kernel.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-KTYPE'><glossterm>KTYPE</glossterm>
+            <glossdef>
+                <para>
+                    Defines the kernel type to be used in assembling the
+                    configuration.
+                    The linux-yocto recipes define "standard", "tiny",
+                    and "preempt-rt" kernel types.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
+                    section in the Yocto Project Linux Kernel Development
+                    Manual for more information on kernel types.
+                </para>
+
+                <para>
+                    You define the <filename>KTYPE</filename> variable in the
+                    <ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#bsp-descriptions'>BSP Descriptions</ulink>.
+                    The value you use must match the value used for the
+                    <link linkend='var-LINUX_KERNEL_TYPE'><filename>LINUX_KERNEL_TYPE</filename></link>
+                    value used by the kernel recipe.
+                </para>
+            </glossdef>
+        </glossentry>
+   </glossdiv>
+
+    <glossdiv id='var-glossary-l'><title>L</title>
+
+        <glossentry id='var-LAYERDEPENDS'><glossterm>LAYERDEPENDS</glossterm>
+            <glossdef>
+                <para>Lists the layers that this recipe depends upon, separated by spaces.
+                    Optionally, you can specify a specific layer version for a dependency
+                    by adding it to the end of the layer name with a colon, (e.g. "anotherlayer:3"
+                    to be compared against
+                    <link linkend='var-LAYERVERSION'><filename>LAYERVERSION</filename></link><filename>_anotherlayer</filename>
+                    in this case).
+                    An error will be produced if any dependency is missing or
+                    the version numbers do not match exactly (if specified).
+                    This variable is used in the <filename>conf/layer.conf</filename> file
+                    and must be suffixed with the name of the specific layer (e.g.
+                    <filename>LAYERDEPENDS_mylayer</filename>).</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LAYERDIR'><glossterm>LAYERDIR</glossterm>
+            <glossdef>
+                <para>When used inside the <filename>layer.conf</filename> configuration
+                    file, this variable provides the path of the current layer.
+                    This variable is not available outside of <filename>layer.conf</filename>
+                    and references are expanded immediately when parsing of the file completes.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LAYERVERSION'><glossterm>LAYERVERSION</glossterm>
+            <glossdef>
+                <para>Optionally specifies the version of a layer as a single number.
+                    You can use this within
+                    <link linkend='var-LAYERDEPENDS'><filename>LAYERDEPENDS</filename></link>
+                    for another layer in order to depend on a specific version
+                    of the layer.
+                    This variable is used in the <filename>conf/layer.conf</filename> file
+                    and must be suffixed with the name of the specific layer (e.g.
+                    <filename>LAYERVERSION_mylayer</filename>).</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LIC_FILES_CHKSUM'><glossterm>LIC_FILES_CHKSUM</glossterm>
+            <glossdef>
+                <para>Checksums of the license text in the recipe source code.</para>
+                <para>This variable tracks changes in license text of the source
+                    code files.
+                    If the license text is changed, it will trigger a build
+                    failure, which gives the developer an opportunity to review any
+                    license change.</para>
+                <para>
+                    This variable must be defined for all recipes (unless
+                    <link linkend='var-LICENSE'><filename>LICENSE</filename></link>
+                    is set to "CLOSED")</para>
+                <para>For more information, see the
+                    <link linkend='usingpoky-configuring-LIC_FILES_CHKSUM'>
+                    Tracking License Changes</link> section</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LICENSE'><glossterm>LICENSE</glossterm>
+            <glossdef>
+                <para>
+                    The list of source licenses for the recipe.
+                    Follow these rules:
+                    <itemizedlist>
+                        <listitem><para>Do not use spaces within individual
+                            license names.</para></listitem>
+                        <listitem><para>Separate license names using
+                            | (pipe) when there is a choice between licenses.
+                            </para></listitem>
+                        <listitem><para>Separate license names using
+                            &amp; (ampersand) when multiple licenses exist
+                            that cover different parts of the source.
+                            </para></listitem>
+                        <listitem><para>You can use spaces between license
+                            names.</para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    Here are some examples:
+                    <literallayout class='monospaced'>
+     LICENSE = "LGPLv2.1 | GPLv3"
+     LICENSE = "MPL-1 &amp; LGPLv2.1"
+     LICENSE = "GPLv2+"
+                    </literallayout>
+                    The first example is from the recipes for Qt, which the user
+                    may choose to distribute under either the LGPL version
+                    2.1 or GPL version 3.
+                    The second example is from Cairo where two licenses cover
+                    different parts of the source code.
+                    The final example is from <filename>sysstat</filename>,
+                    which presents a single license.
+                </para>
+
+                <para>
+                    You can also specify licenses on a per-package basis to
+                    handle situations where components of the output have
+                    different licenses.
+                    For example, a piece of software whose code is
+                    licensed under GPLv2 but has accompanying documentation
+                    licensed under the GNU Free Documentation License 1.2 could
+                    be specified as follows:
+                    <literallayout class='monospaced'>
+     LICENSE = "GFDL-1.2 &amp; GPLv2"
+     LICENSE_${PN} = "GPLv2"
+     LICENSE_${PN}-doc = "GFDL-1.2"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LICENSE_PATH'><glossterm>LICENSE_PATH</glossterm>
+            <glossdef>
+                <para>Path to additional licenses used during the build.
+                    By default, the OpenEmbedded build system uses <filename>COMMON_LICENSE_DIR</filename>
+                    to define the directory that holds common license text used during the build.
+                    The <filename>LICENSE_PATH</filename> variable allows you to extend that
+                    location to other areas that have additional licenses:
+                    <literallayout class='monospaced'>
+     LICENSE_PATH += "/path/to/additional/common/licenses"
+                    </literallayout></para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LINUX_KERNEL_TYPE'><glossterm>LINUX_KERNEL_TYPE</glossterm>
+            <glossdef>
+                <para>
+                    Defines the kernel type to be used in assembling the
+                    configuration.
+                    The linux-yocto recipes define "standard", "tiny", and
+                    "preempt-rt" kernel types.
+                    See the
+                    "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#kernel-types'>Kernel Types</ulink>"
+                    section in the Yocto Project Linux Kernel Development
+                    Manual for more information on kernel types.
+                </para>
+
+                <para>
+                    If you do not specify a
+                    <filename>LINUX_KERNEL_TYPE</filename>, it defaults to
+                    "standard".
+                    Together with
+                    <link linkend='var-KMACHINE'><filename>KMACHINE</filename></link>,
+                    the <filename>LINUX_KERNEL_TYPE</filename> variable
+                    defines the search
+                    arguments used by the kernel tools to find the appropriate
+                    description within the kernel
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+                    with which to build out the sources and configuration.
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LINUX_VERSION'><glossterm>LINUX_VERSION</glossterm>
+            <glossdef>
+                <para>The Linux version from <filename>kernel.org</filename>
+                    on which the Linux kernel image being built using the
+                    OpenEmbedded build system is based.
+                    You define this variable in the kernel recipe.
+                    For example, the <filename>linux-yocto-3.4.bb</filename>
+                    kernel recipe found in
+                    <filename>meta/recipes-kernel/linux</filename>
+                    defines the variables as follows:
+                    <literallayout class='monospaced'>
+     LINUX_VERSION ?= "3.4.24"
+                    </literallayout>
+                    The <filename>LINUX_VERSION</filename> variable is used to
+                    define <link linkend='var-PV'><filename>PV</filename></link>
+                    for the recipe:
+                    <literallayout class='monospaced'>
+     PV = "${LINUX_VERSION}+git${SRCPV}"
+                    </literallayout></para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LINUX_VERSION_EXTENSION'><glossterm>LINUX_VERSION_EXTENSION</glossterm>
+            <glossdef>
+                <para>A string extension compiled into the version
+                    string of the Linux kernel built with the OpenEmbedded
+                    build system.
+                    You define this variable in the kernel recipe.
+                    For example, the linux-yocto kernel recipes all define
+                    the variable as follows:
+                    <literallayout class='monospaced'>
+     LINUX_VERSION_EXTENSION ?= "-yocto-${<link linkend='var-LINUX_KERNEL_TYPE'>LINUX_KERNEL_TYPE</link>}"
+                    </literallayout>
+                    Defining this variable essentially sets the
+                    Linux kernel configuration item
+                    <filename>CONFIG_LOCALVERSION</filename>, which is visible
+                    through the <filename>uname</filename> command.
+                    Here is an example that shows the extension assuming it
+                    was set as previously shown:
+                    <literallayout class='monospaced'>
+     $ uname -r
+     3.7.0-rc8-custom
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-LOG_DIR'><glossterm>LOG_DIR</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the directory to which the OpenEmbedded build
+                    system writes overall log files.
+                    The default directory is <filename>${TMPDIR}/log</filename>.
+                </para>
+                <para>
+                    For the directory containing logs specific to each task,
+                    see the <link linkend='var-T'><filename>T</filename></link>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-m'><title>M</title>
+
+         <glossentry id='var-MACHINE'><glossterm>MACHINE</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the target device for which the image is built.
+                    You define <filename>MACHINE</filename> in the
+                    <filename>local.conf</filename> file found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    By default, <filename>MACHINE</filename> is set to
+                    "qemux86", which is an x86-based architecture machine to
+                    be emulated using QEMU:
+                    <literallayout class='monospaced'>
+     MACHINE ?= "qemux86"
+                    </literallayout>
+                    The variable corresponds to a machine configuration file of the
+                    same name, through which machine-specific configurations are set.
+                    Thus, when <filename>MACHINE</filename> is set to "qemux86" there
+                    exists the corresponding <filename>qemux86.conf</filename> machine
+                    configuration file, which can be found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                    in <filename>meta/conf/machine</filename>.
+                </para>
+
+                <para>
+                    The list of machines supported by the Yocto Project as
+                    shipped include the following:
+                    <literallayout class='monospaced'>
+     MACHINE ?= "qemuarm"
+     MACHINE ?= "qemumips"
+     MACHINE ?= "qemuppc"
+     MACHINE ?= "qemux86"
+     MACHINE ?= "qemux86-64"
+     MACHINE ?= "genericx86"
+     MACHINE ?= "beagleboard"
+     MACHINE ?= "mpc8315e-rdb"
+     MACHINE ?= "routerstationpro"
+                    </literallayout>
+                    The last four are Yocto Project reference hardware boards, which
+                    are provided in the <filename>meta-yocto-bsp</filename> layer.
+                    <note>Adding additional Board Support Package (BSP) layers
+                        to your configuration adds new possible settings for
+                        <filename>MACHINE</filename>.
+                    </note>
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</glossterm>
+            <glossdef>
+                <para></para>
+                <para>
+                    A list of required machine-specific packages to install as part of
+                    the image being built.
+                    The build process depends on these packages being present.
+                    Furthermore, because this is a "machine essential" variable, the list of
+                    packages are essential for the machine to boot.
+                    The impact of this variable affects images based on
+                    <filename>packagegroup-core-boot</filename>,
+                    including the <filename>core-image-minimal</filename> image.
+                </para>
+                <para>
+                    This variable is similar to the
+                    <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename>
+                    variable with the exception that the image being built has a build
+                    dependency on the variable's list of packages.
+                    In other words, the image will not build if a file in this list is not found.
+                </para>
+                <para>
+                    As an example, suppose the machine for which you are building requires
+                    <filename>example-init</filename> to be run during boot to initialize the hardware.
+                    In this case, you would use the following in the machine's
+                    <filename>.conf</filename> configuration file:
+                    <literallayout class='monospaced'>
+     MACHINE_ESSENTIAL_EXTRA_RDEPENDS += "example-init"
+                    </literallayout>
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'><glossterm>MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</glossterm>
+            <glossdef>
+                <para></para>
+                <para>
+                    A list of recommended machine-specific packages to install as part of
+                    the image being built.
+                    The build process does not depend on these packages being present.
+                    However, because this is a "machine essential" variable, the list of
+                    packages are essential for the machine to boot.
+                    The impact of this variable affects images based on
+                    <filename>packagegroup-core-boot</filename>,
+                    including the <filename>core-image-minimal</filename> image.
+                </para>
+                <para>
+                    This variable is similar to the
+                    <filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS</link></filename>
+                    variable with the exception that the image being built does not have a build
+                    dependency on the variable's list of packages.
+                    In other words, the image will still build if a package in this list is not found.
+                    Typically, this variable is used to handle essential kernel modules, whose
+                    functionality may be selected to be built into the kernel rather than as a module,
+                    in which case a package will not be produced.
+                </para>
+                <para>
+                    Consider an example where you have a custom kernel where a specific touchscreen
+                    driver is required for the machine to be usable.
+                    However, the driver can be built as a module or
+                    into the kernel depending on the kernel configuration.
+                    If the driver is built as a module, you want it to be installed.
+                    But, when the driver is built into the kernel, you still want the
+                    build to succeed.
+                    This variable sets up a "recommends" relationship so that in the latter case,
+                    the build will not fail due to the missing package.
+                    To accomplish this, assuming the package for the module was called
+                    <filename>kernel-module-ab123</filename>, you would use the
+                    following in the machine's <filename>.conf</filename> configuration
+                    file:
+                    <literallayout class='monospaced'>
+     MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS += "kernel-module-ab123"
+                    </literallayout>
+                </para>
+                <para>
+                    Some examples of these machine essentials are flash, screen, keyboard, mouse,
+                    or touchscreen drivers (depending on the machine).
+                </para>
+            </glossdef>
+        </glossentry>
+
+         <glossentry id='var-MACHINE_EXTRA_RDEPENDS'><glossterm>MACHINE_EXTRA_RDEPENDS</glossterm>
+            <glossdef>
+                <para>
+                    A list of machine-specific packages to install as part of the
+                    image being built that are not essential for the machine to boot.
+                    However, the build process for more fully-featured images
+                    depends on the packages being present.
+                </para>
+                <para>
+                    This variable affects all images based on
+                    <filename>packagegroup-base</filename>, which does not include the
+                    <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
+                    images.
+                </para>
+                <para>
+                    The variable is similar to the
+                    <filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS</link></filename>
+                    variable with the exception that the image being built has a build
+                    dependency on the variable's list of packages.
+                    In other words, the image will not build if a file in this list is not found.
+                </para>
+                <para>
+                    An example is a machine that has WiFi capability but is not
+                    essential for the machine to boot the image.
+                    However, if you are building a more fully-featured image, you want to enable
+                    the WiFi.
+                    The package containing the firmware for the WiFi hardware is always
+                    expected to exist, so it is acceptable for the build process to depend upon
+                    finding the package.
+                    In this case, assuming the package for the firmware was called
+                    <filename>wifidriver-firmware</filename>, you would use the following in the
+                    <filename>.conf</filename> file for the machine:
+                    <literallayout class='monospaced'>
+     MACHINE_EXTRA_RDEPENDS += "wifidriver-firmware"
+                    </literallayout>
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-MACHINE_EXTRA_RRECOMMENDS'><glossterm>MACHINE_EXTRA_RRECOMMENDS</glossterm>
+            <glossdef>
+                <para></para>
+                <para>
+                    A list of machine-specific packages to install as part of the
+                    image being built that are not essential for booting the machine.
+                    The image being built has no build dependency on this list of packages.
+                </para>
+                <para>
+                    This variable affects only images based on
+                    <filename>packagegroup-base</filename>, which does not include the
+                    <filename>core-image-minimal</filename> or <filename>core-image-basic</filename>
+                    images.
+                </para>
+                <para>
+                    This variable is similar to the
+                    <filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS</link></filename>
+                    variable with the exception that the image being built does not have a build
+                    dependency on the variable's list of packages.
+                    In other words, the image will build if a file in this list is not found.
+                </para>
+                <para>
+                    An example is a machine that has WiFi capability but is not essential
+                    For the machine to boot the image.
+                    However, if you are building a more fully-featured image, you want to enable
+                    WiFi.
+                    In this case, the package containing the WiFi kernel module will not be produced
+                    if the WiFi driver is built into the kernel, in which case you still want the
+                    build to succeed instead of failing as a result of the package not being found.
+                    To accomplish this, assuming the package for the module was called
+                    <filename>kernel-module-examplewifi</filename>, you would use the
+                    following in the <filename>.conf</filename> file for the machine:
+                    <literallayout class='monospaced'>
+     MACHINE_EXTRA_RRECOMMENDS += "kernel-module-examplewifi"
+                    </literallayout>
+                </para>
+            </glossdef>
+         </glossentry>
+
+         <glossentry id='var-MACHINE_FEATURES'><glossterm>MACHINE_FEATURES</glossterm>
+            <glossdef>
+                <para>Specifies the list of hardware features the
+                    <link linkend='var-MACHINE'>MACHINE</link> supports.
+                    For example, including the "bluetooth" feature causes the
+                    <filename>bluez</filename> bluetooth daemon to be built and
+                    added to the image.
+                    It also causes the <filename>connman</filename> recipe
+                    to look at <filename>MACHINE_FEATURES</filename> and when it
+                    finds "bluetooth" there it enables the bluetooth
+                    support in ConnMan.
+                </para>
+
+                <para>
+                    For a list of features supported by the Yocto Project as shipped,
+                    see the "<link linkend='ref-features-machine'>Machine</link>" section.
+                </para>
+            </glossdef>
+         </glossentry>
+
+        <glossentry id='var-MACHINE_FEATURES_BACKFILL'><glossterm>MACHINE_FEATURES_BACKFILL</glossterm>
+            <glossdef>
+                <para>Features to be added to
+                    <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>
+                    if not also present in
+                    <filename><link linkend='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'>MACHINE_FEATURES_BACKFILL_CONSIDERED</link></filename>.
+                </para>
+
+                <para>
+                    This variable is set in the <filename>meta/conf/bitbake.conf</filename> file.
+                    It is not intended to be user-configurable.
+                    It is best to just reference the variable to see which machine features are
+                    being backfilled for all machine configurations.
+                    See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
+                    more information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MACHINE_FEATURES_BACKFILL_CONSIDERED'><glossterm>MACHINE_FEATURES_BACKFILL_CONSIDERED</glossterm>
+            <glossdef>
+                <para>Features from
+                    <filename><link linkend='var-MACHINE_FEATURES_BACKFILL'>MACHINE_FEATURES_BACKFILL</link></filename>
+                    that should not be backfilled (i.e. added to
+                    <filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link></filename>)
+                    during the build.
+                    See the "<link linkend='ref-features-backfill'>Feature backfilling</link>" section for
+                    more information.
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MACHINEOVERRIDES'><glossterm>MACHINEOVERRIDES</glossterm>
+            <glossdef>
+                <para>
+                    Lists overrides specific to the current machine.
+                    By default, this list includes the value
+                    of <filename><link linkend='var-MACHINE'>MACHINE</link></filename>.
+                    You can extend the list to apply variable overrides for
+                    classes of machines.
+                    For example, all QEMU emulated machines (e.g. qemuarm,
+                    qemux86, and so forth) include a common file named
+                    <filename>meta/conf/machine/include/qemu.inc</filename>
+                    that prepends <filename>MACHINEOVERRIDES</filename> with
+                    the following variable override:
+                    <literallayout class='monospaced'>
+    MACHINEOVERRIDES =. "qemuall:"
+                    </literallayout>
+                    Applying an override like <filename>qemuall</filename>
+                    affects all QEMU emulated machines elsewhere.
+                    Here is an example from the
+                    <filename>connman-conf</filename> recipe:
+                    <literallayout class='monospaced'>
+    SRC_URI_append_qemuall = "file://wired.config \
+                              file://wired-setup \
+                             "
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MAINTAINER'><glossterm>MAINTAINER</glossterm>
+            <glossdef>
+                <para>The email address of the distribution maintainer.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MIRRORS'><glossterm>MIRRORS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies additional paths from which the OpenEmbedded
+                    build system gets source code.
+                    When the build system searches for source code, it first
+                    tries the local download directory.
+                    If that location fails, the build system tries locations
+                    defined by
+                    <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>,
+                    the upstream source, and then locations specified by
+                    <filename>MIRRORS</filename> in that order.
+                </para>
+
+                <para>
+                    Assuming your distribution
+                    (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
+                    is "poky", the default value for
+                    <filename>MIRRORS</filename> is defined in the
+                    <filename>conf/distro/poky.conf</filename> file in the
+                    <filename>meta-yocto</filename> Git repository.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MLPREFIX'><glossterm>MLPREFIX</glossterm>
+            <glossdef>
+                <para>
+                    Specifies a prefix has been added to
+                    <link linkend='var-PN'><filename>PN</filename></link> to create a special version
+                    of a recipe or package, such as a Multilib version.
+                    The variable is used in places where the prefix needs to be
+                    added to or removed from a the name (e.g. the
+                    <link linkend='var-BPN'><filename>BPN</filename></link> variable).
+                    <filename>MLPREFIX</filename> gets set when a prefix has been
+                    added to <filename>PN</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MODULE_TARBALL_DEPLOY'><glossterm>MODULE_TARBALL_DEPLOY</glossterm>
+            <glossdef>
+                <para>
+                    Controls creation of the <filename>modules-*.tgz</filename>
+                    file.
+                    Set this variable to "0" to disable creation of this
+                    file, which contains all of the kernel modules resulting
+                    from a kernel build.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-MULTIMACH_TARGET_SYS'><glossterm>MULTIMACH_TARGET_SYS</glossterm>
+            <glossdef>
+                <para>
+                    Separates files for different machines such that you can build
+                    for multiple target machines using the same output directories.
+                    See the <link linkend='var-STAMP'><filename>STAMP</filename></link> variable
+                    for an example.
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-n'><title>N</title>
+
+        <glossentry id='var-NATIVELSBSTRING'><glossterm>NATIVELSBSTRING</glossterm>
+            <glossdef>
+                <para>
+                    A string identifying the host distribution.
+                    Strings consist of the host distributor ID
+                    followed by the release, as reported by the
+                    <filename>lsb_release</filename> tool
+                    or as read from <filename>/etc/lsb-release</filename>.
+                    For example, when running a build on Ubuntu 12.10, the value
+                    is "Ubuntu-12.10".
+                    If this information is unable to be determined, the value
+                    resolves to "Unknown".
+                </para>
+                <para>
+                    This variable is used by default to isolate native shared
+                    state packages for different distributions (e.g. to avoid
+                    problems with <filename>glibc</filename> version
+                    incompatibilities).
+                    Additionally, the variable is checked against
+                    <link linkend='var-SANITY_TESTED_DISTROS'><filename>SANITY_TESTED_DISTROS</filename></link>
+                    if that variable is set.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-NO_RECOMMENDATIONS'><glossterm>NO_RECOMMENDATIONS</glossterm>
+            <glossdef>
+                <para>
+                    Prevents installation of all "recommended-only" packages.
+                    Recommended-only packages are packages installed only
+                    through the
+                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
+                    variable).
+                    Setting the <filename>NO_RECOMMENDATIONS</filename> variable
+                    to "1" turns this feature on:
+                    <literallayout class='monospaced'>
+     NO_RECOMMENDATIONS = "1"
+                    </literallayout>
+                    You can set this variable globally in your
+                    <filename>local.conf</filename> file or you can attach it to
+                    a specific image recipe by using the recipe name override:
+                    <literallayout class='monospaced'>
+     NO_RECOMMENDATIONS_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
+                    </literallayout>
+                </para>
+
+                <para>
+                    It is important to realize that if you choose to not install
+                    packages using this variable and some other packages are
+                    dependent on them (i.e. listed in a recipe's
+                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+                    variable), the OpenEmbedded build system ignores your
+                    request and will install the packages to avoid dependency
+                    errors.
+                    <note>
+                        Some recommended packages might be required for certain
+                        system functionality, such as kernel modules.
+                        It is up to you to add packages with
+                        <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
+                        variable.
+                    </note>
+                </para>
+
+                <para>
+                    Support for this variable exists only when using the
+                    IPK and RPM packaging backend.
+                    Support does not exist for DEB.
+                </para>
+
+                <para>
+                    See the
+                    <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
+                    and the
+                    <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
+                    variables for related information.
+                </para>
+            </glossdef>
+        </glossentry>
+    </glossdiv>
+
+    <glossdiv id='var-glossary-o'><title>O</title>
+
+        <glossentry id='var-OE_BINCONFIG_EXTRA_MANGLE'><glossterm>OE_BINCONFIG_EXTRA_MANGLE</glossterm>
+            <glossdef>
+                <para>
+                    When a recipe inherits the
+                    <filename>binconfig.bbclass</filename> class, this variable
+                    specifies additional arguments passed to the "sed" command.
+                    The sed command alters any paths in configuration scripts
+                    that have been set up during compilation.
+                    Inheriting this class results in all paths in these scripts
+                    being changed to point into the
+                    <filename>sysroots/</filename> directory so that all builds
+                    that use the script will use the correct directories
+                    for the cross compiling layout.
+                </para>
+
+                <para>
+                    See the <filename>meta/classes/binconfig.bbclass</filename>
+                    in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                    for details on how this class applies these additional
+                    sed command arguments.
+                    For general information on the
+                    <filename>binconfig.bbclass</filename> class, see the
+                    "<link linkend='ref-classes-binconfig'>Binary Configuration Scripts - <filename>binconfig.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-OE_IMPORTS'><glossterm>OE_IMPORTS</glossterm>
+            <glossdef>
+                <para>
+                    An internal variable used to tell the OpenEmbedded build
+                    system what Python modules to import for every Python
+                    function run by the system.
+                </para>
+
+                <note>
+                    Do not set this variable.
+                    It is for internal use only.
+                </note>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-OE_TERMINAL'><glossterm>OE_TERMINAL</glossterm>
+            <glossdef>
+                <para>
+                    Controls how the OpenEmbedded build system spawns
+                    interactive terminals on the host development system
+                    (e.g. using the BitBake command with the
+                    <filename>-c devshell</filename> command-line option).
+                    For more information, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-appdev-devshell'>Using a Development Shell</ulink>" section
+                    in the Yocto Project Development Manual.
+                 </para>
+
+                 <para>
+                    You can use the following values for the
+                    <filename>OE_TERMINAL</filename> variable:
+                    <literallayout class='monospaced'>
+     auto
+     gnome
+     xfce
+     rxvt
+     screen
+     konsole
+     none
+                    </literallayout>
+                    <note>Konsole support only works for KDE 3.x.
+                        Also, "auto" is the default behavior for
+                        <filename>OE_TERMINAL</filename></note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-OEROOT'><glossterm>OEROOT</glossterm>
+            <glossdef>
+                <para>
+                    The directory from which the top-level build environment
+                    setup script is sourced.
+                    The Yocto Project makes two top-level build environment
+                    setup scripts available:
+                    <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+                    and
+                    <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>.
+                    When you run one of these scripts, the
+                    <filename>OEROOT</filename> variable resolves to the
+                    directory that holds the script.
+                </para>
+
+                <para>
+                    For additional information on how this variable is used,
+                    see the initialization scripts.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-OLDEST_KERNEL'><glossterm>OLDEST_KERNEL</glossterm>
+            <glossdef>
+                <para>
+                    Declares the oldest version of the Linux kernel that the
+                    produced binaries must support.
+                    This variable is passed into the build of the Embedded
+                    GNU C Library (<filename>eglibc</filename>).
+                </para>
+
+                <para>
+                    The default for this variable comes from the
+                    <filename>meta/conf/bitbake.conf</filename> configuration
+                    file.
+                    You can override this default by setting the variable
+                    in a custom distribution configuration file.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-OVERRIDES'><glossterm>OVERRIDES</glossterm>
+            <glossdef>
+                <para>
+                    BitBake uses <filename>OVERRIDES</filename> to control
+                    what variables are overridden after BitBake parses
+                    recipes and configuration files.
+                    You can find more information on how overrides are handled
+                    in the BitBake Manual that is located at
+                    <filename>bitbake/doc/manual</filename> in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+    </glossdiv>
+
+    <glossdiv id='var-glossary-p'><title>P</title>
+
+        <glossentry id='var-P'><glossterm>P</glossterm>
+            <glossdef>
+                <para>The recipe name and version.
+                    <filename>P</filename> is comprised of the following:
+                    <literallayout class='monospaced'>
+     ${PN}-${PV}
+                    </literallayout></para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGE_ARCH'><glossterm>PACKAGE_ARCH</glossterm>
+            <glossdef>
+                <para>The architecture of the resulting package or packages.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGE_BEFORE_PN'><glossterm>PACKAGE_BEFORE_PN</glossterm>
+            <glossdef>
+                <para>Enables easily adding packages to
+                <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
+                before <filename>${<link linkend='var-PN'>PN</link>}</filename>
+                so that the packages can pick up files that would normally be
+                included in the default package.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGE_CLASSES'><glossterm>PACKAGE_CLASSES</glossterm>
+            <glossdef>
+                <para>This variable, which is set in the <filename>local.conf</filename> configuration
+                    file found in the <filename>conf</filename> folder of the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
+                    specifies the package manager to use when packaging data.
+                    You can provide one or more arguments for the variable with the first
+                    argument being the package manager used to create images:
+                    <literallayout class='monospaced'>
+     PACKAGE_CLASSES ?= "package_rpm package_deb package_ipk"
+                    </literallayout>
+                    For information on build performance effects as a result of the
+                    package manager use, see
+                    <link linkend='ref-classes-package'>Packaging - <filename>package*.bbclass</filename></link>
+                    in this manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGE_EXCLUDE'><glossterm>PACKAGE_EXCLUDE</glossterm>
+            <glossdef>
+                <para>
+                    Lists packages that should not be installed into an image.
+                    For example:
+                    <literallayout class='monospaced'>
+     PACKAGE_EXCLUDE = "&lt;package_name&gt; &lt;package_name&gt; &lt;package_name&gt; ..."
+                    </literallayout>
+                    You can set this variable globally in your
+                    <filename>local.conf</filename> file or you can attach it to
+                    a specific image recipe by using the recipe name override:
+                    <literallayout class='monospaced'>
+     PACKAGE_EXCLUDE_pn-&lt;target_image&gt; = "&lt;package_name&gt;"
+                    </literallayout>
+                </para>
+
+                <para>
+                    If you choose to not install
+                    a package using this variable and some other package is
+                    dependent on it (i.e. listed in a recipe's
+                    <link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>
+                    variable), the OpenEmbedded build system generates a fatal
+                    installation error.
+                    Because the build system halts the process with a fatal
+                    error, you can use the variable with an iterative
+                    development process to remove specific components from a
+                    system.
+                </para>
+
+                <para>
+                    Support for this variable exists only when using the
+                    IPK and RPM packaging backend.
+                    Support does not exist for DEB.
+                </para>
+
+                <para>
+                    See the
+                    <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>
+                    and the
+                    <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>
+                    variables for related information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGE_EXTRA_ARCHS'><glossterm>PACKAGE_EXTRA_ARCHS</glossterm>
+            <glossdef>
+                <para>Specifies the list of architectures compatible with the device CPU.
+                    This variable is useful when you build for several different devices that use
+                    miscellaneous processors such as XScale and ARM926-EJS).</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGE_GROUP'><glossterm>PACKAGE_GROUP</glossterm>
+            <glossdef>
+                <para>
+                    Defines one or more packages to include in an image when
+                    a specific item is included in
+                    <link linkend='var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></link>.
+                    When setting the value, <filename>PACKAGE_GROUP</filename>
+                    should have the name of the feature item as an override.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     PACKAGE_GROUP_widget = "package1 package2"
+                    </literallayout>
+                    In this example, if "widget" were added to
+                    <filename>IMAGE_FEATURES</filename>, "package1" and
+                    "package2" would be included in the image.
+                    <note>
+                        Packages installed by features defined through
+                        <filename>PACKAGE_GROUP</filename> are often package
+                        groups.
+                        While similarly named, you should not confuse the
+                        <filename>PACKAGE_GROUP</filename> variable with
+                        package groups, which are discussed elsewhere in the
+                        documentation.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGE_INSTALL'><glossterm>PACKAGE_INSTALL</glossterm>
+            <glossdef>
+                <para>
+                    The final list of packages passed to the package manager
+                    for installation into the image.
+                    Because the package manager controls actual installation
+                    of all packages, the list of packages passed using
+                    <filename>PACKAGE_INSTALL</filename> is not the final list
+                    of packages that are actually installed.
+                </para>
+
+                <para>
+                    This variable is internal to the image construction
+                    code.
+                    Use the
+                    <link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>
+                    variable to specify packages for installation.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGECONFIG'><glossterm>PACKAGECONFIG</glossterm>
+            <glossdef>
+                <para>
+                    This variable provides a means of enabling or disabling
+                    features of a recipe on a per-recipe basis.
+                    <filename>PACKAGECONFIG</filename> blocks are defined
+                    in recipes when you specify features and then arguments
+                    that define feature behaviors.
+                    Here is the basic block structure:
+                    <literallayout class='monospaced'>
+     PACKAGECONFIG ??= "f1 f2 f3 ..."
+     PACKAGECONFIG[f1] = "--with-f1,--without-f1,build-deps-f1,rt-deps-f1"
+     PACKAGECONFIG[f2] = "--with-f2,--without-f2,build-deps-f2,rt-deps-f2"
+     PACKAGECONFIG[f3] = "--with-f3,--without-f3,build-deps-f3,rt-deps-f3"
+                    </literallayout>
+                    The <filename>PACKAGECONFIG</filename>
+                    variable itself specifies a space-separated list of the
+                    features to enable.
+                    Following the features, you can determine the behavior of
+                    each feature by providing up to four order-dependent
+                    arguments, which are separated by commas.
+                    You can omit any argument you like but must retain the
+                    separating commas.
+                    The order is important and specifies the following:
+                    <orderedlist>
+                        <listitem><para>Extra arguments
+                            that should be added to the configure script
+                            argument list
+                            (<link linkend='var-EXTRA_OECONF'><filename>EXTRA_OECONF</filename></link>)
+                            if the feature is enabled.</para></listitem>
+                        <listitem><para>Extra arguments
+                            that should be added to <filename>EXTRA_OECONF</filename>
+                            if the feature is disabled.
+                            </para></listitem>
+                        <listitem><para>Additional build dependencies
+                            (<link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>)
+                            that should be added if the feature is enabled.
+                            </para></listitem>
+                        <listitem><para>Additional runtime dependencies
+                            (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
+                            that should be added if the feature is enabled.
+                            </para></listitem>
+                    </orderedlist>
+                </para>
+
+                <para>
+                    Consider the following
+                    <filename>PACKAGECONFIG</filename> block taken from the
+                    <filename>librsvg</filename> recipe.
+                    In this example the feature is <filename>croco</filename>,
+                    which has three arguments that determine the feature's
+                    behavior.
+                    <literallayout class='monospaced'>
+     PACKAGECONFIG ??= "croco"
+     PACKAGECONFIG[croco] = "--with-croco,--without-croco,libcroco"
+                    </literallayout>
+                    The <filename>--with-croco</filename> and
+                    <filename>libcroco</filename> arguments apply only if
+                    the feature is enabled.
+                    In this case, <filename>--with-croco</filename> is
+                    added to the configure script argument list and
+                    <filename>libcroco</filename> is added to
+                    <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>.
+                    On the other hand, if the feature is disabled say through
+                    a <filename>.bbappend</filename> file in another layer, then
+                    the second argument <filename>--without-croco</filename> is
+                    added to the configure script rather than
+                    <filename>--with-croco</filename>.
+                </para>
+
+                <para>
+                    The basic <filename>PACKAGECONFIG</filename> structure
+                    previously described holds true regardless of whether you
+                    are creating a block or changing a block.
+                    When creating a block, use the structure inside your
+                    recipe.
+                </para>
+
+                <para>
+                    If you want to change an existing
+                    <filename>PACKAGECONFIG</filename> block, you can do so
+                    one of two ways:
+                    <itemizedlist>
+                        <listitem><para><emphasis>Append file:</emphasis>
+                            Create an append file named
+                            <filename>&lt;recipename&gt;.bbappend</filename> in your
+                            layer and override the value of
+                            <filename>PACKAGECONFIG</filename>.
+                            You can either completely override the variable:
+                            <literallayout class='monospaced'>
+     PACKAGECONFIG="f4 f5"
+                            </literallayout>
+                            Or, you can just amended the variable:
+                            <literallayout class='monospaced'>
+     PACKAGECONFIG_append = " f4"
+                            </literallayout></para></listitem>
+                        <listitem><para><emphasis>Configuration file:</emphasis>
+                            This method is identical to changing the block
+                            through an append file except you edit your
+                            <filename>local.conf</filename> or
+                            <filename>&lt;mydistro&gt;.conf</filename> file.
+                            As with append files previously described,
+                            you can either completely override the variable:
+                            <literallayout class='monospaced'>
+     PACKAGECONFIG_pn-&lt;recipename&gt;="f4 f5"
+                            </literallayout>
+                            Or, you can just amended the variable:
+                            <literallayout class='monospaced'>
+     PACKAGECONFIG_append_pn-&lt;recipename&gt; = " f4"
+                            </literallayout></para></listitem>
+                    </itemizedlist>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGES'><glossterm>PACKAGES</glossterm>
+            <glossdef>
+                <para>The list of packages to be created from the recipe.
+                    The default value is the following:
+                    <literallayout class='monospaced'>
+     ${PN}-dbg ${PN}-staticdev ${PN}-dev ${PN}-doc ${PN}-locale ${PACKAGE_BEFORE_PN} ${PN}
+                    </literallayout></para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PACKAGES_DYNAMIC'><glossterm>PACKAGES_DYNAMIC</glossterm>
+            <glossdef>
+                <para>
+                    A promise that your recipe satisfies runtime dependencies
+                    for optional modules that are found in other recipes.
+                    <filename>PACKAGES_DYNAMIC</filename>
+                    does not actually satisfy the dependencies, it only states that
+                    they should be satisfied.
+                    For example, if a hard, runtime dependency
+                    (<link linkend='var-RDEPENDS'><filename>RDEPENDS</filename></link>)
+                    of another package is satisfied
+                    at build time through the <filename>PACKAGES_DYNAMIC</filename>
+                    variable, but a package with the module name is never actually
+                    produced, then the other package will be broken.
+                    Thus, if you attempt to include that package in an image,
+                    you will get a dependency failure from the packaging system
+                    during <filename>do_rootfs</filename>.
+                </para>
+                <para>
+                    Typically, if there is a chance that such a situation can
+                    occur and the package that is not created is valid
+                    without the dependency being satisfied, then you should use
+                    <link linkend='var-RRECOMMENDS'><filename>RRECOMMENDS</filename></link>
+                    (a soft runtime dependency) instead of
+                    <filename>RDEPENDS</filename>.
+                </para>
+
+                <para>
+                    For an example of how to use the <filename>PACKAGES_DYNAMIC</filename>
+                    variable when you are splitting packages, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#handling-optional-module-packaging'>Handling Optional Module Packaging</ulink>" section
+                    in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PARALLEL_MAKE'><glossterm>PARALLEL_MAKE</glossterm>
+            <glossdef>
+                <para>
+                    Extra options that are passed to the
+                    <filename>make</filename> command during the
+                    <filename>do_compile</filename> task in order to specify
+                    parallel compilation.
+                    This variable is usually in the form
+                    <filename>-j 4</filename>, where the number
+                    represents the maximum number of parallel threads make can
+                    run.
+                    If you development host supports multiple cores a good
+                    rule of thumb is to set this variable to twice the number
+                    of cores on the host.
+                    <note>
+                        Individual recipes might clear out this variable if
+                        the software being built has problems running its
+                        <filename>make</filename> process in parallel.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PARALLEL_MAKEINST'><glossterm>PARALLEL_MAKEINST</glossterm>
+            <glossdef>
+                <para>
+                    Extra options passed to the
+                    <filename>make install</filename> command during the
+                    <filename>do_install</filename> task in order to specify
+                    parallel installation.
+                    This variable defaults to the value of
+                    <link linkend='var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></link>.
+                    <note>
+                        Individual recipes might clear out this variable if
+                        the software being built has problems running its
+                        <filename>make install</filename> process in parallel.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+
+
+
+PARALLEL_MAKEINST with the description ".
+
+
+
+
+
+        <glossentry id='var-PATCHRESOLVE'><glossterm>PATCHRESOLVE</glossterm>
+            <glossdef>
+                <para>
+                    Determines the action to take when a patch fails.
+                    You can set this variable to one of two values: "noop" and
+                    "user".
+                </para>
+
+                <para>
+                    The default value of "noop" causes the build to simply fail
+                    when the OpenEmbedded build system cannot successfully
+                    apply a patch.
+                    Setting the value to "user" causes the build system to
+                    launch a shell and places you in the right location so that
+                    you can manually resolve the conflicts.
+                </para>
+
+                <para>
+                    Set this variable in your
+                    <filename>local.conf</filename> file.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PATCHTOOL'><glossterm>PATCHTOOL</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the utility used to apply patches for a recipe
+                    during <filename>do_patch</filename>.
+                    You can specify one of three utilities: "patch", "quilt", or
+                    "git".
+                    The default utility used is "quilt" except for the
+                    quilt-native recipe itself.
+                    Because the quilt tool is not available at the
+                    time quilt-native is being patched, it uses "patch".
+                </para>
+
+                <para>
+                    If you wish to use an alternative patching tool, set the
+                    variable in the recipe using one of the following:
+                    <literallayout class='monospaced'>
+     PATCHTOOL = "patch"
+     PATCHTOOL = "quilt"
+     PATCHTOOL = "git"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PE'><glossterm>PE</glossterm>
+            <glossdef>
+                <para>
+                    the epoch of the recipe.
+                    By default, this variable is unset.
+                    The field is used to make upgrades possible when the
+                    versioning scheme changes in some backwards incompatible
+                    way.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PF'><glossterm>PF</glossterm>
+            <glossdef>
+                <para>Specifies the recipe or package name and includes all version and revision
+                    numbers (i.e. <filename>eglibc-2.13-r20+svnr15508/</filename> and
+                    <filename>bash-4.2-r1/</filename>).
+                    This variable is comprised of the following:
+                    <literallayout class='monospaced'>
+     ${<link linkend='var-PN'>PN</link>}-${<link linkend='var-EXTENDPE'>EXTENDPE</link>}${<link linkend='var-PV'>PV</link>}-${<link linkend='var-PR'>PR</link>}
+                    </literallayout></para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PKGD'><glossterm>PKGD</glossterm>
+            <glossdef>
+                <para>
+                    Points to the destination directory for files to be
+                    packaged before they are split into individual packages.
+                    This directory defaults to the following:
+                    <literallayout class='monospaced'>
+     ${WORKDIR}/package
+                    </literallayout>
+                    Do not change this default.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PKGDATA_DIR'><glossterm>PKGDATA_DIR</glossterm>
+            <glossdef>
+                <para>
+                    Points to a shared, global-state directory that holds data
+                    generated during the packaging process.
+                    During the packaging process, the
+                    <filename>do_packagedata</filename> task packages
+                    data for each recipe and installs it into this temporary,
+                    shared area.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PKGDEST'><glossterm>PKGDEST</glossterm>
+            <glossdef>
+                <para>
+                    Points to the parent directory for files to be packaged
+                    after they have been split into individual packages.
+                    This directory defaults to the following:
+                    <literallayout class='monospaced'>
+     ${WORKDIR}/packages-split
+                    </literallayout>
+                    Under this directory, the build system creates
+                    directories for each package specified in
+                    <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>.
+                    Do not change this default.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PKGDESTWORK'><glossterm>PKGDESTWORK</glossterm>
+            <glossdef>
+                <para>
+                    Points to a temporary work area used by the
+                    <filename>do_package</filename> task to write output
+                    from the <filename>do_packagedata</filename> task.
+                    The <filename>PKGDESTWORK</filename> location defaults to
+                    the following:
+                    <literallayout class='monospaced'>
+     ${WORKDIR}/pkgdata
+                    </literallayout>
+                    The <filename>do_packagedata</filename> task then packages
+                    the data in the temporary work area and installs it into a
+                    shared directory pointed to by
+                    <link linkend='var-PKGDATA_DIR'><filename>PKGDATA_DIR</filename></link>.
+                </para>
+
+                <para>
+                    Do not change this default.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PN'><glossterm>PN</glossterm>
+            <glossdef>
+                <para>This variable can have two separate functions depending on the context: a recipe
+                    name or a resulting package name.</para>
+                <para><filename>PN</filename> refers to a recipe name in the context of a file used
+                    by the OpenEmbedded build system as input to create a package.
+                    The name is normally extracted from the recipe file name.
+                    For example, if the recipe is named
+                    <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PN</filename>
+                    will be "expat".</para>
+                <para>
+                    The variable refers to a package name in the context of a file created or produced by the
+                    OpenEmbedded build system.</para>
+                <para>If applicable, the <filename>PN</filename> variable also contains any special
+                    suffix or prefix.
+                    For example, using <filename>bash</filename> to build packages for the native
+                    machine, <filename>PN</filename> is <filename>bash-native</filename>.
+                    Using <filename>bash</filename> to build packages for the target and for Multilib,
+                    <filename>PN</filename> would be <filename>bash</filename> and
+                    <filename>lib64-bash</filename>, respectively.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PR'><glossterm>PR</glossterm>
+            <glossdef>
+                <para>The revision of the recipe.
+                    The default value for this variable is "r0".
+                    </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PREFERRED_PROVIDER'><glossterm>PREFERRED_PROVIDER</glossterm>
+            <glossdef>
+                <para>
+                    If multiple recipes provide an item, this variable
+                    determines which recipe should be given preference.
+                    You should always suffix the variable with the name of the
+                    provided item, and you should set it to the
+                    <link linkend='var-PN'><filename>PN</filename></link>
+                    of the recipe to which you want to give precedence.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     PREFERRED_PROVIDER_virtual/xserver = "xserver-xf86"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PREFERRED_VERSION'><glossterm>PREFERRED_VERSION</glossterm>
+            <glossdef>
+                <para>
+                    If there are multiple versions of recipes available, this
+                    variable determines which recipe should be given preference.
+                    You must always suffix the variable with the
+                    <link linkend='var-PN'><filename>PN</filename></link>
+                    you want to select, and you should set to the
+                    <link linkend='var-PV'><filename>PV</filename></link>
+                    accordingly for precedence.
+                    You can use the "<filename>%</filename>" character as a
+                    wildcard to match any number of characters, which can be
+                    useful when specifying versions that contain long revision
+                    numbers that could potentially change.
+                    Here are two examples:
+                    <literallayout class='monospaced'>
+     PREFERRED_VERSION_python = "2.6.6"
+     PREFERRED_VERSION_linux-yocto = "3.0+git%"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PREMIRRORS'><glossterm>PREMIRRORS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies additional paths from which the OpenEmbedded
+                    build system gets source code.
+                    When the build system searches for source code, it first
+                    tries the local download directory.
+                    If that location fails, the build system tries locations
+                    defined by <filename>PREMIRRORS</filename>, the upstream
+                    source, and then locations specified by
+                    <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
+                    in that order.
+                </para>
+
+                <para>
+                    Assuming your distribution
+                    (<link linkend='var-DISTRO'><filename>DISTRO</filename></link>)
+                    is "poky", the default value for
+                    <filename>PREMIRRORS</filename> is defined in the
+                    <filename>conf/distro/poky.conf</filename> file in the
+                    <filename>meta-yocto</filename> Git repository.
+                </para>
+
+                <para>
+                    Typically, you could add a specific server for the
+                    build system to attempt before any others by adding
+                    something like the following to the
+                    <filename>local.conf</filename> configuration file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                    <literallayout class='monospaced'>
+     PREMIRRORS_prepend = "\
+     git://.*/.* http://www.yoctoproject.org/sources/ \n \
+     ftp://.*/.* http://www.yoctoproject.org/sources/ \n \
+     http://.*/.* http://www.yoctoproject.org/sources/ \n \
+     https://.*/.* http://www.yoctoproject.org/sources/ \n"
+                    </literallayout>
+                    These changes cause the build system to intercept
+                    Git, FTP, HTTP, and HTTPS requests and direct them to
+                    the <filename>http://</filename> sources mirror.
+                    You can use <filename>file://</filename> URLs to point
+                    to local directories or network shares as well.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PRINC'><glossterm>PRINC</glossterm>
+            <glossdef>
+                <para>Causes the <link linkend='var-PR'><filename>PR</filename></link>
+                    variable of <filename>.bbappend</filename> files to
+                    dynamically increment.
+                    This increment minimizes the impact of layer ordering.</para>
+                <para>In order to ensure multiple <filename>.bbappend</filename> files can co-exist,
+                    <filename>PRINC</filename> should be self referencing.
+                    This variable defaults to 0.</para>
+                <para>Following is an example that increments <filename>PR</filename> by two:
+                    <literallayout class='monospaced'>
+     PRINC := "${@int(PRINC) + 2}"
+                    </literallayout>
+                    It is advisable not to use strings such as ".= '.1'" with the variable because
+                    this usage is very sensitive to layer ordering.
+                    You should avoid explicit assignments as they cannot
+                    adequately represent multiple
+                    <filename>.bbappend</filename> files.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PROVIDES'><glossterm>PROVIDES</glossterm>
+            <glossdef>
+                <para>
+                    A list of aliases that a recipe also provides.
+                    These aliases are useful for satisfying dependencies of
+                    other recipes during the build (as specified by
+                    <filename><link linkend='var-DEPENDS'>DEPENDS</link></filename>).
+                    <note>
+                        A recipe's own
+                        <filename><link linkend='var-PN'>PN</link></filename>
+                        is implicitly already in its
+                        <filename>PROVIDES</filename> list.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-PV'><glossterm>PV</glossterm>
+            <glossdef>
+                <para>The version of the recipe.
+                    The version is normally extracted from the recipe filename.
+                    For example, if the recipe is named
+                    <filename>expat_2.0.1.bb</filename>, then the default value of <filename>PV</filename>
+                    will be "2.0.1".
+                    <filename>PV</filename> is generally not overridden within
+                    a recipe unless it is building an unstable (i.e. development) version from a source code repository
+                    (e.g. Git or Subversion).
+                 </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+<!--            <glossdiv id='var-glossary-q'><title>Q</title>-->
+<!--            </glossdiv>-->
+
+    <glossdiv id='var-glossary-r'><title>R</title>
+
+        <glossentry id='var-RCONFLICTS'><glossterm>RCONFLICTS</glossterm>
+            <glossdef>
+                <para>
+                    The list of packages that conflict with packages.
+                    Note that packages will not be installed if conflicting
+                    packages are not first removed.
+                </para>
+
+                <para>
+                   Like all package-controlling variables, you must always use
+                   them in conjunction with a package name override.
+                   Here is an example:
+                   <literallayout class='monospaced'>
+     RCONFLICTS_${PN} = "another-conflicting-package-name"
+                   </literallayout>
+                </para>
+
+                <para>
+                    BitBake, which the OpenEmbedded build system uses, supports
+                    specifying versioned dependencies.
+                    Although the syntax varies depending on the packaging
+                    format, BitBake hides these differences from you.
+                    Here is the general syntax to specify versions with
+                    the <filename>RCONFLICTS</filename> variable:
+                    <literallayout class='monospaced'>
+     RCONFLICTS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
+                    </literallayout>
+                    For <filename>operator</filename>, you can specify the
+                    following:
+                    <literallayout class='monospaced'>
+     =
+     &lt;
+     &gt;
+     &lt;=
+     &gt;=
+                    </literallayout>
+                    For example, the following sets up a dependency on version
+                    1.2 or greater of the package <filename>foo</filename>:
+                    <literallayout class='monospaced'>
+     RCONFLICTS_${PN} = "foo (>= 1.2)"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-RDEPENDS'><glossterm>RDEPENDS</glossterm>
+            <glossdef>
+                <para>
+                    Lists a package's runtime dependencies (i.e. other packages)
+                    that must be installed in order for the built package to run
+                    correctly.
+                    If a package in this list cannot be found during the build,
+                    you will get a build error.
+                </para>
+
+                <para>
+                    When you use the <filename>RDEPENDS</filename> variable
+                    in a recipe, you are essentially stating that the recipe's
+                    <filename>do_build</filename> task depends on the existence
+                    of a specific package.
+                    Consider this simple example for two recipes named "a" and
+                    "b" that produce similarly named packages.
+                    In this example, the <filename>RDEPENDS</filename>
+                    statement appears in the "a" recipe:
+                    <literallayout class='monospaced'>
+     RDEPENDS_${PN} = "b"
+                    </literallayout>
+                    Here, the dependency is such that the
+                    <filename>do_build</filename> task for recipe "a" depends
+                    on the <filename>do_package_write</filename> task
+                    of recipe "b".
+                    This means the package file for "b" must be available when
+                    the output for recipe "a" has been completely built.
+                    More importantly, package "a" will be marked as depending
+                    on package "b" in a manner that is understood by the
+                    package manager in use (i.e. rpm, opkg, or dpkg).
+                </para>
+
+                <para>
+                    The names of the packages you list within
+                    <filename>RDEPENDS</filename> must be the names of other
+                    packages - they cannot be recipe names.
+                    Although package names and recipe names usually match,
+                    the important point here is that you are
+                    providing package names within the
+                    <filename>RDEPENDS</filename> variable.
+                    For an example of the default list of packages created from
+                    a recipe, see the
+                    <link linkend='var-PACKAGES'><filename>PACKAGES</filename></link>
+                    variable.
+                </para>
+
+                <para>
+                    Because the <filename>RDEPENDS</filename> variable applies
+                    to packages being built, you should always use the variable
+                    in a form with an attached package name.
+                    For example, suppose you are building a development package
+                    that depends on the <filename>perl</filename> package.
+                    In this case, you would use the following
+                    <filename>RDEPENDS</filename> statement:
+                    <literallayout class='monospaced'>
+     RDEPENDS_${PN}-dev += "perl"
+                    </literallayout>
+                    In the example, the development package depends on
+                    the <filename>perl</filename> package.
+                    Thus, the <filename>RDEPENDS</filename> variable has the
+                    <filename>${PN}-dev</filename> package name as part of the
+                    variable.
+                </para>
+
+                <para>
+                    The package name you attach to the
+                    <filename>RDEPENDS</filename> variable must appear
+                    as it would in the <filename>PACKAGES</filename>
+                    namespace before any renaming of the output package by
+                    classes like <filename>debian.bbclass</filename>.
+                </para>
+
+                <para>
+                    In many cases you do not need to explicitly add
+                    runtime dependencies using
+                    <filename>RDEPENDS</filename> since some automatic
+                    handling occurs:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>shlibdeps</filename></emphasis>:  If
+                            a runtime package contains a shared library
+                            (<filename>.so</filename>), the build
+                            processes the library in order to determine other
+                            libraries to which it is dynamically linked.
+                            The build process adds these libraries to
+                            <filename>RDEPENDS</filename> when creating the runtime
+                            package.</para></listitem>
+                        <listitem><para><emphasis><filename>pcdeps</filename></emphasis>:  If
+                            the package ships a <filename>pkg-config</filename>
+                            information file, the build process uses this file
+                            to add items to the <filename>RDEPENDS</filename>
+                            variable to create the runtime packages.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    BitBake, which the OpenEmbedded build system uses, supports
+                    specifying versioned dependencies.
+                    Although the syntax varies depending on the packaging
+                    format, BitBake hides these differences from you.
+                    Here is the general syntax to specify versions with
+                    the <filename>RDEPENDS</filename> variable:
+                    <literallayout class='monospaced'>
+     RDEPENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
+                    </literallayout>
+                    For <filename>operator</filename>, you can specify the
+                    following:
+                    <literallayout class='monospaced'>
+     =
+     &lt;
+     &gt;
+     &lt;=
+     &gt;=
+                    </literallayout>
+                    For example, the following sets up a dependency on version
+                    1.2 or greater of the package <filename>foo</filename>:
+                    <literallayout class='monospaced'>
+     RDEPENDS_${PN} = "foo (>= 1.2)"
+                    </literallayout>
+                </para>
+
+                <para>
+                    For information on build-time dependencies, see the
+                    <link linkend='var-DEPENDS'><filename>DEPENDS</filename></link>
+                    variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-RM_OLD_IMAGE'><glossterm>RM_OLD_IMAGE</glossterm>
+            <glossdef>
+                <para>
+                    Reclaims disk space by removing previously built
+                    versions of the same image from the
+                    <filename>images</filename> directory pointed to by the
+                    <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
+                    variable.
+                </para>
+
+                <para>
+                    Set this variable to "1" in your
+                    <filename>local.conf</filename> file to remove these
+                    images.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-RM_WORK_EXCLUDE'><glossterm>RM_WORK_EXCLUDE</glossterm>
+            <glossdef>
+                <para>
+                    With <filename>rm_work</filename> enabled, this
+                    variable specifies a list of recipes whose work directories
+                    should not be removed.
+                    See the "<link linkend='ref-classes-rm-work'>Removing Work Files During the Build - <filename>rm_work.bbclass</filename></link>"
+                    section for more details.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-ROOTFS_POSTPROCESS_COMMAND'><glossterm>ROOTFS_POSTPROCESS_COMMAND</glossterm>
+            <glossdef>
+                <para>
+                    Added by classes to run post processing commands once the
+                    OpenEmbedded build system has created the root filesystem.
+                    You can specify shell commands separated by semicolons:
+                    <literallayout class='monospaced'>
+     ROOTFS_POSTPROCESS_COMMAND += "&lt;shell_command&gt;; ... "
+                    </literallayout>
+                    If you need to pass the path to the root filesystem within
+                    the command, you can use
+                    <filename>${IMAGE_ROOTFS}</filename>, which points to
+                    the root filesystem image.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-RPROVIDES'><glossterm>RPROVIDES</glossterm>
+            <glossdef>
+                <para>
+                    A list of package name aliases that a package also provides.
+                    These aliases are useful for satisfying runtime dependencies
+                    of other packages both during the build and on the target
+                    (as specified by
+                    <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>).
+                    <note>
+                        A package's own name is implicitly already in its
+                        <filename>RPROVIDES</filename> list.
+                    </note>
+                </para>
+                <para>
+                   As with all package-controlling variables, you must always
+                   use the variable in conjunction with a package name override.
+                   Here is an example:
+                   <literallayout class='monospaced'>
+     RPROVIDES_${PN} = "widget-abi-2"
+                   </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-RRECOMMENDS'><glossterm>RRECOMMENDS</glossterm>
+            <glossdef>
+                <para>
+                    A list of packages that extends the usability of a package
+                    being built.
+                    The package being built does not depend on this list of
+                    packages in order to successfully build, but needs them for
+                    the extended usability.
+                    To specify runtime dependencies for packages, see the
+                    <filename><link linkend='var-RDEPENDS'>RDEPENDS</link></filename>
+                    variable.
+                </para>
+
+                <para>
+                    The OpenEmbedded build process automatically installs the
+                    list of packages as part of the built package.
+                    However, you can remove these packages later if you want.
+                    If, during the build, a package from the
+                    <filename>RRECOMMENDS</filename> list cannot be
+                    found, the build process continues without an error.
+                </para>
+
+                <para>
+                    You can also prevent packages in the list from being
+                    installed by using several variables.
+                    See the
+                    <link linkend='var-BAD_RECOMMENDATIONS'><filename>BAD_RECOMMENDATIONS</filename></link>,
+                    <link linkend='var-NO_RECOMMENDATIONS'><filename>NO_RECOMMENDATIONS</filename></link>,
+                    and
+                    <link linkend='var-PACKAGE_EXCLUDE'><filename>PACKAGE_EXCLUDE</filename></link>
+                    variables for more information.
+                </para>
+
+                <para>
+                    Because the <filename>RRECOMMENDS</filename> variable
+                    applies to packages being built, you should always attach
+                    an override to the variable to specify the particular
+                    package whose usability is being extended.
+                    For example, suppose you are building a development package
+                    that is extended to support wireless functionality.
+                    In this case, you would use the following:
+                    <literallayout class='monospaced'>
+     RRECOMMENDS_${PN}-dev += "&lt;wireless_package_name&gt;"
+                    </literallayout>
+                    In the example, the package name
+                    (<filename>${<link linkend='var-PN'>PN</link>}-dev</filename>)
+                    must appear as it would in the
+                    <filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
+                    namespace before any renaming of the output package by
+                    classes such as <filename>debian.bbclass</filename>.
+                </para>
+
+                <para>
+                    BitBake, which the OpenEmbedded build system uses, supports
+                    specifying versioned recommends.
+                    Although the syntax varies depending on the packaging
+                    format, BitBake hides these differences from you.
+                    Here is the general syntax to specify versions with
+                    the <filename>RRECOMMENDS</filename> variable:
+                    <literallayout class='monospaced'>
+     RRECOMMENDS_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
+                    </literallayout>
+                    For <filename>operator</filename>, you can specify the
+                    following:
+                    <literallayout class='monospaced'>
+     =
+     &lt;
+     &gt;
+     &lt;=
+     &gt;=
+                    </literallayout>
+                    For example, the following sets up a recommend on version
+                    1.2 or greater of the package <filename>foo</filename>:
+                    <literallayout class='monospaced'>
+     RRECOMMENDS_${PN} = "foo (>= 1.2)"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-RREPLACES'><glossterm>RREPLACES</glossterm>
+            <glossdef>
+                <para>
+                    A list of packages replaced by a package.
+                    The package manager uses this variable to determine which
+                    package should be installed to replace other package(s)
+                    during an upgrade.
+                    In order to also have the other package(s) removed at the
+                    same time, you must add the name of the other
+                    package to the
+                    <filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link></filename> variable.
+                </para>
+                <para>
+                   As with all package-controlling variables, you must use
+                   this variable in conjunction with a package name
+                   override.
+                   Here is an example:
+                   <literallayout class='monospaced'>
+     RREPLACES_${PN} = "other-package-being-replaced"
+                   </literallayout>
+                </para>
+
+                <para>
+                    BitBake, which the OpenEmbedded build system uses, supports
+                    specifying versioned replacements.
+                    Although the syntax varies depending on the packaging
+                    format, BitBake hides these differences from you.
+                    Here is the general syntax to specify versions with
+                    the <filename>RREPLACES</filename> variable:
+                    <literallayout class='monospaced'>
+     RREPLACES_${PN} = "&lt;package&gt; (&lt;operator&gt; &lt;version&gt;)"
+                    </literallayout>
+                    For <filename>operator</filename>, you can specify the
+                    following:
+                    <literallayout class='monospaced'>
+     =
+     &lt;
+     &gt;
+     &lt;=
+     &gt;=
+                    </literallayout>
+                    For example, the following sets up a replacement using
+                    version 1.2 or greater of the package
+                    <filename>foo</filename>:
+                    <literallayout class='monospaced'>
+     RREPLACES_${PN} = "foo (>= 1.2)"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-RSUGGESTS'><glossterm>RSUGGESTS</glossterm>
+            <glossdef>
+                <para>
+                    A list of additional packages that you can suggest for
+                    installation by the package manager at the time a package
+                    is installed.
+                    Not all package managers support this functionality.
+                </para>
+                <para>
+                   As with all package-controlling variables, you must always
+                   use this variable in conjunction with a package name
+                   override.
+                   Here is an example:
+                   <literallayout class='monospaced'>
+     RSUGGESTS_${PN} = "useful-package another-package"
+                   </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-s'><title>S</title>
+
+        <glossentry id='var-S'><glossterm>S</glossterm>
+            <glossdef>
+                <para>
+                    The location in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    where unpacked recipe source code resides.
+                    This location is within the working directory
+                    (<filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>),
+                    which is not static.
+                    The unpacked source location depends on the recipe name
+                    (<filename><link linkend='var-PN'>PN</link></filename>) and
+                    recipe version
+                    (<filename><link linkend='var-PV'>PV</link></filename>) as
+                    follows:
+                    <literallayout class='monospaced'>
+ ${WORKDIR}/${PN}-${PV}
+                    </literallayout>
+                    As an example, assume a
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                    top-level folder named <filename>poky</filename> and a
+                    default Build Directory at <filename>poky/build</filename>.
+                    In this case, the working directory the build system uses
+                    to keep the unpacked recipe for <filename>db</filename>
+                    is the following:
+                    <literallayout class='monospaced'>
+ ~/poky/build/tmp/work/qemux86-poky-linux/db/5.1.19-r3/db-5.1.19
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SANITY_TESTED_DISTROS'><glossterm>SANITY_TESTED_DISTROS</glossterm>
+            <glossdef>
+                <para>
+                    A list of the host distribution identifiers that the
+                    build system has been tested against.
+                    Identifiers consist of the host distributor ID
+                    followed by the release,
+                    as reported by the <filename>lsb_release</filename> tool
+                    or as read from <filename>/etc/lsb-release</filename>.
+                    Separate the list items with explicit newline
+                    characters (<filename>\n</filename>).
+                    If <filename>SANITY_TESTED_DISTROS</filename> is not empty
+                    and the current value of
+                    <link linkend='var-NATIVELSBSTRING'><filename>NATIVELSBSTRING</filename></link>
+                    does not appear in the list, then the build system reports
+                    a warning that indicates the current host distribution has
+                    not been tested as a build host.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SDK_ARCH'><glossterm>SDK_ARCH</glossterm>
+            <glossdef>
+                <para>
+                    The target architecture for the SDK.
+                    Typically, you do not directly set this variable.
+                    Instead, use
+                    <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SDK_NAME'><glossterm>SDK_NAME</glossterm>
+            <glossdef>
+                <para>
+                    The base name for SDK output files.
+                    The name is derived from the
+                    <link linkend='var-DISTRO'><filename>DISTRO</filename></link>,
+                    <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>,
+                    <link linkend='var-SDK_ARCH'><filename>SDK_ARCH</filename></link>,
+                    <link linkend='var-IMAGE_BASENAME'><filename>IMAGE_BASENAME</filename></link>,
+                    and
+                    <link linkend='var-TUNE_PKGARCH'><filename>TUNE_PKGARCH</filename></link>
+                    variables:
+                    <literallayout class='monospaced'>
+     SDK_NAME = "${DISTRO}-${TCLIBC}-${SDK_ARCH}-${IMAGE_BASENAME}-${TUNE_PKGARCH}"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SDKIMAGE_FEATURES'><glossterm>SDKIMAGE_FEATURES</glossterm>
+            <glossdef>
+                <para>Equivalent to
+                    <filename><link linkend='var-IMAGE_FEATURES'>IMAGE_FEATURES</link></filename>.
+                    However, this variable applies to the SDK generated from an
+                    image using the following command:
+                    <literallayout class='monospaced'>
+     $ bitbake -c populate_sdk imagename
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SDKMACHINE'><glossterm>SDKMACHINE</glossterm>
+            <glossdef>
+                <para>
+                    The architecture of the machine that runs Application
+                    Development Toolkit (ADT) items.
+                    In other words, packages are built so that they will run
+                    on the target you specify with the argument.
+                    This implies that you can build out ADT/SDK items that
+                    run on an architecture other than that of your build host.
+                    For example, you can use an x86_64-based build host to
+                    create packages that will run on an i686-based
+                    SDK Machine.
+                </para>
+
+                <para>
+                    You can use "i686" and "x86_64" as possible values for this
+                    variable.
+                    The variable defaults to "i686" and is set in the
+                    <filename>local.conf</filename> file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    <literallayout class='monospaced'>
+     SDKMACHINE ?= "i686"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SECTION'><glossterm>SECTION</glossterm>
+            <glossdef>
+                <para>The section in which packages should be categorized.
+                    Package management utilities can make use of this variable.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SELECTED_OPTIMIZATION'><glossterm>SELECTED_OPTIMIZATION</glossterm>
+            <glossdef>
+                <para>
+                    The variable takes the value of
+                    <filename><link linkend='var-FULL_OPTIMIZATION'>FULL_OPTIMIZATION</link></filename>
+                    unless <filename><link linkend='var-DEBUG_BUILD'>DEBUG_BUILD</link></filename> = "1".
+                    In this case the value of
+                    <filename><link linkend='var-DEBUG_OPTIMIZATION'>DEBUG_OPTIMIZATION</link></filename> is used.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SERIAL_CONSOLE'><glossterm>SERIAL_CONSOLE</glossterm>
+            <glossdef>
+                <para>
+                    Defines a serial console (TTY) to enable using getty.
+                    Provide a value that specifies the baud rate followed by
+                    the TTY device name separated by a space.
+                    You cannot specify more than one TTY device:
+                    <literallayout class='monospaced'>
+     SERIAL_CONSOLE = "115200 ttyS0"
+                    </literallayout>
+                    <note>
+                        The <filename>SERIAL_CONSOLE</filename> variable
+                        is deprecated.
+                        Please use the
+                        <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
+                        variable.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SERIAL_CONSOLES'><glossterm>SERIAL_CONSOLES</glossterm>
+            <glossdef>
+                <para>
+                    Defines the serial consoles (TTYs) to enable using getty.
+                    Provide a value that specifies the baud rate followed by
+                    the TTY device name separated by a semicolon.
+                    Use spaces to separate multiple devices:
+                    <literallayout class='monospaced'>
+     SERIAL_CONSOLES = "115200;ttyS0 115200;ttyS1"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SERIAL_CONSOLES_CHECK'><glossterm>SERIAL_CONSOLES_CHECK</glossterm>
+            <glossdef>
+                <para>
+                    Similar to
+                    <link linkend='var-SERIAL_CONSOLES'><filename>SERIAL_CONSOLES</filename></link>
+                    except the device is checked for existence before attempting
+                    to enable it.
+                    This variable is currently only supported with SysVinit
+                    (i.e. not with systemd).
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS'><glossterm>SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS</glossterm>
+            <glossdef>
+                <para>
+                    A list of recipe dependencies that should not be used to
+                    determine signatures of tasks from one recipe when they
+                    depend on tasks from another recipe.
+                    For example:
+                    <literallayout class='monospaced'>
+    SIGGEN_EXCLUDE_SAFE_RECIPE_DEPS += "intone->mplayer2"
+                    </literallayout>
+                    In this example, <filename>intone</filename> depends on
+                    <filename>mplayer2</filename>.
+                </para>
+
+                <para>
+                    Use of this variable is one mechanism to remove dependencies
+                    that affect task signatures and thus force rebuilds when a
+                    recipe changes.
+                    <caution>
+                        If you add an inappropriate dependency for a recipe
+                        relationship, the software might break during
+                        runtime if the interface of the second recipe was
+                        changed after the first recipe had been built.
+                    </caution>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SIGGEN_EXCLUDERECIPES_ABISAFE'><glossterm>SIGGEN_EXCLUDERECIPES_ABISAFE</glossterm>
+            <glossdef>
+                <para>
+                    A list of recipes that are completely stable and will
+                    never change.
+                    The ABI for the recipes in the list are presented by
+                    output from the tasks run to build the recipe.
+                    Use of this variable is one way to remove dependencies from
+                    one recipe on another that affect task signatures and
+                    thus force rebuilds when the recipe changes.
+                    <caution>
+                        If you add an inappropriate variable to this list,
+                        the software might break at runtime if the
+                        interface of the recipe was changed after the other
+                        had been built.
+                    </caution>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SITEINFO_BITS'><glossterm>SITEINFO_BITS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the number of bits for the target system CPU.
+                    The value should be either "32" or "64".
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SITEINFO_ENDIANNESS'><glossterm>SITEINFO_ENDIANNESS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the endian byte order of the target system.
+                    The value should be either "le" for little-endian or "be" for big-endian.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SOC_FAMILY'><glossterm>SOC_FAMILY</glossterm>
+            <glossdef>
+                <para>
+                    Groups together machines based upon the same family
+                    of SOC (System On Chip).
+                    You typically set this variable in a common
+                    <filename>.inc</filename> file that you include in the
+                    configuration files of all the machines.
+                    <note>
+                        You must include
+                        <filename>conf/machine/include/soc-family.inc</filename>
+                        for this variable to appear in
+                    <link linkend='var-MACHINEOVERRIDES'><filename>MACHINEOVERRIDES</filename></link>.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SOLIBS'><glossterm>SOLIBS</glossterm>
+            <glossdef>
+                <para>
+                    Defines the suffix for shared libraries used on the
+                    target platform.
+                    By default, this suffix is ".so.*" for all Linux-based
+                    systems and is defined in the
+                    <filename>meta/conf/bitbake.conf</filename> configuration
+                    file.
+                </para>
+
+                <para>
+                    You will see this variable referenced in the default values
+                    of <filename>FILES_${PN}</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SOLIBSDEV'><glossterm>SOLIBSDEV</glossterm>
+            <glossdef>
+                <para>
+                    Defines the suffix for the development symbolic link
+                    (symlink) for shared libraries on the target platform.
+                    By default, this suffix is ".so" for Linux-based
+                    systems and is defined in the
+                    <filename>meta/conf/bitbake.conf</filename> configuration
+                    file.
+                </para>
+
+                <para>
+                    You will see this variable referenced in the default values
+                    of <filename>FILES_${PN}-dev</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SPECIAL_PKGSUFFIX'><glossterm>SPECIAL_PKGSUFFIX</glossterm>
+            <glossdef>
+                <para>
+                    A list of prefixes for <link linkend='var-PN'><filename>PN</filename></link> used by the
+                    OpenEmbedded build system to create variants of recipes or packages.
+                    The list specifies the prefixes to strip off during certain circumstances
+                    such as the generation of the <link linkend='var-BPN'><filename>BPN</filename></link> variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SRC_URI'><glossterm>SRC_URI</glossterm>
+            <glossdef>
+                <para>The list of source files - local or remote.
+                    This variable tells the OpenEmbedded build system which bits
+                    to pull in for the build and how to pull them in.
+                    For example, if the recipe or append file only needs to
+                    fetch a tarball from the Internet, the recipe or
+                    append file uses a single <filename>SRC_URI</filename>
+                    entry.
+                    On the other hand, if the recipe or append file needs to
+                    fetch a tarball, apply two patches, and include a custom
+                    file, the recipe or append file would include four
+                    instances of the variable.</para>
+                <para>The following list explains the available URI protocols:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>file://</filename> -</emphasis>
+                            Fetches files, which are usually files shipped with
+                            the
+                            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
+                            from the local machine.
+                            The path is relative to the
+                            <link linkend='var-FILESPATH'><filename>FILESPATH</filename></link>
+                            variable.
+                            Thus, the build system searches, in order, from the
+                            following directories, which are assumed to be a
+                            subdirectories of the directory in which the
+                            recipe file (<filename>.bb</filename>) or
+                            append file (<filename>.bbappend</filename>)
+                            resides:
+                            <itemizedlist>
+                                <listitem><para><emphasis><filename>${BPN}</filename> -</emphasis>
+                                    The base recipe name without any special
+                                    suffix or version numbers.
+                                    </para></listitem>
+                                <listitem><para><emphasis><filename>${BP}</filename> -</emphasis>
+                                    <filename>${<link linkend='var-BPN'>BPN</link>}-${PV}</filename>.
+                                    The base recipe name and version but without
+                                    any special package name suffix.
+                                    </para></listitem>
+                                <listitem><para><emphasis>files -</emphasis>
+                                    Files within a directory, which is named
+                                    <filename>files</filename> and is also
+                                    alongside the recipe or append file.
+                                    </para></listitem>
+                            </itemizedlist>
+                            <note>
+                                If you want the build system to pick up files
+                                specified through a
+                                <filename>SRC_URI</filename>
+                                statement from your append file, you need to be
+                                sure to extend the
+                                <filename>FILESPATH</filename>
+                                variable by also using the
+                                <link linkend='var-FILESEXTRAPATHS'><filename>FILESEXTRAPATHS</filename></link>
+                                variable from within your append file.
+                            </note>
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>bzr://</filename> -</emphasis> Fetches files from a
+                            Bazaar revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>git://</filename> -</emphasis> Fetches files from a
+                            Git revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>osc://</filename> -</emphasis> Fetches files from
+                            an OSC (OpenSUSE Build service) revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>repo://</filename> -</emphasis> Fetches files from
+                            a repo (Git) repository.</para></listitem>
+                        <listitem><para><emphasis><filename>svk://</filename> -</emphasis> Fetches files from
+                            an SVK revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>http://</filename> -</emphasis> Fetches files from
+                            the Internet using <filename>http</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>https://</filename> -</emphasis> Fetches files
+                            from the Internet using <filename>https</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>ftp://</filename> -</emphasis> Fetches files
+                            from the Internet using <filename>ftp</filename>.</para></listitem>
+                        <listitem><para><emphasis><filename>cvs://</filename> -</emphasis> Fetches files from
+                            a CVS revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>hg://</filename> -</emphasis> Fetches files from
+                            a Mercurial (<filename>hg</filename>) revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>p4://</filename> -</emphasis> Fetches files from
+                            a Perforce (<filename>p4</filename>) revision control repository.</para></listitem>
+                        <listitem><para><emphasis><filename>ssh://</filename> -</emphasis> Fetches files from
+                            a secure shell.</para></listitem>
+                        <listitem><para><emphasis><filename>svn://</filename> -</emphasis> Fetches files from
+                            a Subversion (<filename>svn</filename>) revision control repository.</para></listitem>
+                    </itemizedlist>
+                </para>
+                <para>Standard and recipe-specific options for <filename>SRC_URI</filename> exist.
+                    Here are standard options:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>apply</filename> -</emphasis> Whether to apply
+                            the patch or not.
+                            The default action is to apply the patch.</para></listitem>
+                        <listitem><para><emphasis><filename>striplevel</filename> -</emphasis> Which
+                            striplevel to use when applying the patch.
+                            The default level is 1.</para></listitem>
+                        <listitem><para><emphasis><filename>patchdir</filename> -</emphasis> Specifies
+                            the directory in which the patch should be applied.
+                            The default is <filename>${</filename><link linkend='var-S'><filename>S</filename></link><filename>}</filename>.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+                <para>Here are options specific to recipes building code from a revision control system:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>mindate</filename> -</emphasis>
+                            Apply the patch only if
+                            <link linkend='var-SRCDATE'><filename>SRCDATE</filename></link>
+                            is equal to or greater than <filename>mindate</filename>.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>maxdate</filename> -</emphasis>
+                            Apply the patch only if <filename>SRCDATE</filename>
+                            is not later than <filename>mindate</filename>.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>minrev</filename> -</emphasis>
+                            Apply the patch only if <filename>SRCREV</filename>
+                            is equal to or greater than <filename>minrev</filename>.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>maxrev</filename> -</emphasis>
+                            Apply the patch only if <filename>SRCREV</filename>
+                            is not later than <filename>maxrev</filename>.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>rev</filename> -</emphasis>
+                            Apply the patch only if <filename>SRCREV</filename>
+                            is equal to <filename>rev</filename>.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>notrev</filename> -</emphasis>
+                            Apply the patch only if <filename>SRCREV</filename>
+                            is not equal to <filename>rev</filename>.
+                            </para></listitem>
+                    </itemizedlist>
+                </para>
+                <para>Here are some additional options worth mentioning:
+                    <itemizedlist>
+                        <listitem><para><emphasis><filename>unpack</filename> -</emphasis> Controls
+                            whether or not to unpack the file if it is an archive.
+                            The default action is to unpack the file.</para></listitem>
+                        <listitem><para><emphasis><filename>subdir</filename> -</emphasis> Places the file
+                            (or extracts its contents) into the specified
+                            subdirectory of <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
+                            This option is useful for unusual tarballs or other archives that
+                            do not have their files already in a subdirectory within the archive.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>name</filename> -</emphasis> Specifies a
+                            name to be used for association with <filename>SRC_URI</filename> checksums
+                            when you have more than one file specified in <filename>SRC_URI</filename>.
+                            </para></listitem>
+                        <listitem><para><emphasis><filename>downloadfilename</filename> -</emphasis> Specifies
+                            the filename used when storing the downloaded file.</para></listitem>
+                    </itemizedlist>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SRC_URI_OVERRIDES_PACKAGE_ARCH'><glossterm>SRC_URI_OVERRIDES_PACKAGE_ARCH</glossterm>
+            <glossdef>
+                <para></para>
+                <para>
+                    By default, the OpenEmbedded build system automatically detects whether
+                    <filename><link linkend='var-SRC_URI'>SRC_URI</link></filename>
+                    contains files that are machine-specific.
+                    If so, the build system automatically changes
+                    <filename><link linkend='var-PACKAGE_ARCH'>PACKAGE_ARCH</link></filename>.
+                    Setting this variable to "0" disables this behavior.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SRCDATE'><glossterm>SRCDATE</glossterm>
+            <glossdef>
+                <para>
+                    The date of the source code used to build the package.
+                    This variable applies only if the source was fetched from a Source Code Manager (SCM).
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SRCPV'><glossterm>SRCPV</glossterm>
+            <glossdef>
+                <para>
+                    Returns the version string of the current package.
+                    This string is used to help define the value of
+                    <link linkend='var-PV'><filename>PV</filename></link>.
+                </para>
+
+                <para>
+                    The <filename>SRCPV</filename> variable is defined in the
+                    <filename>meta/conf/bitbake.conf</filename> configuration
+                    file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                    as follows:
+                    <literallayout class='monospaced'>
+     SRCPV = "${@bb.fetch2.get_srcrev(d)}"
+                    </literallayout>
+                </para>
+
+                <para>
+                    Recipes that need to define <filename>PV</filename> do so
+                    with the help of the <filename>SRCPV</filename>.
+                    For example, the <filename>ofono</filename> recipe
+                    (<filename>ofono_git.bb</filename>) located in
+                    <filename>meta/recipes-connectivity</filename> in the
+                    Source Directory defines <filename>PV</filename> as
+                    follows:
+                    <literallayout class='monospaced'>
+     PV = "1.5.0+git${SRCPV}"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SRCREV'><glossterm>SRCREV</glossterm>
+            <glossdef>
+                <para>
+                    The revision of the source code used to build the package.
+                    This variable applies to Subversion, Git, Mercurial and Bazaar
+                    only.
+                    Note that if you wish to build a fixed revision and you wish
+                    to avoid performing a query on the remote repository every time
+                    BitBake parses your recipe, you should specify a <filename>SRCREV</filename> that is a
+                    full revision identifier and not just a tag.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SSTATE_DIR'><glossterm>SSTATE_DIR</glossterm>
+            <glossdef>
+                <para>The directory for the shared state cache.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SSTATE_MIRRORS'><glossterm>SSTATE_MIRRORS</glossterm>
+            <glossdef>
+                <para>
+                    Configures the OpenEmbedded build system to search other
+                    mirror locations for prebuilt cache data objects before
+                    building out the data.
+                    This variable works like fetcher
+                    <link linkend='var-MIRRORS'><filename>MIRRORS</filename></link>
+                    and <link linkend='var-PREMIRRORS'><filename>PREMIRRORS</filename></link>
+                    and points to the cache locations to check for the shared
+                    objects.
+                </para>
+
+                <para>
+                    You can specify a filesystem directory or a remote URL such
+                    as HTTP or FTP.
+                    The locations you specify need to contain the shared state
+                    cache (sstate-cache) results from previous builds.
+                    The sstate-cache you point to can also be from builds on
+                    other machines.
+                </para>
+
+                <para>
+                    If a mirror uses the same structure as
+                    <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link>,
+                    you need to add
+                    "PATH" at the end as shown in the examples below.
+                    The build system substitutes the correct path within the
+                    directory structure.
+                    <literallayout class='monospaced'>
+     SSTATE_MIRRORS ?= "\
+     file://.* http://someserver.tld/share/sstate/PATH \n \
+     file://.* file:///some/local/dir/sstate/PATH"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-STAGING_KERNEL_DIR'><glossterm>STAGING_KERNEL_DIR</glossterm>
+            <glossdef>
+                <para>
+                    The directory with kernel headers that are required to build out-of-tree
+                    modules.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-STAMP'><glossterm>STAMP</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the base path used to create recipe stamp files.
+                    The path to an actual stamp file is constructed by evaluating this
+                    string and then appending additional information.
+                    Currently, the default assignment for <filename>STAMP</filename>
+                    as set in the <filename>meta/conf/bitbake.conf</filename> file
+                    is:
+                    <literallayout class='monospaced'>
+     STAMP = "${STAMPS_DIR}/${MULTIMACH_TARGET_SYS}/${PN}/${EXTENDPE}${PV}-${PR}"
+                    </literallayout>
+                    See <link linkend='var-STAMPS_DIR'><filename>STAMPS_DIR</filename></link>,
+                    <link linkend='var-MULTIMACH_TARGET_SYS'><filename>MULTIMACH_TARGET_SYS</filename></link>,
+                    <link linkend='var-PN'><filename>PN</filename></link>,
+                    <link linkend='var-EXTENDPE'><filename>EXTENDPE</filename></link>,
+                    <link linkend='var-PV'><filename>PV</filename></link>, and
+                    <link linkend='var-PR'><filename>PR</filename></link> for related variable
+                    information.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-STAMPS_DIR'><glossterm>STAMPS_DIR</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the base directory in which the OpenEmbedded
+                    build system places stamps.
+                    The default directory is
+                    <filename>${TMPDIR}/stamps</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SUMMARY'><glossterm>SUMMARY</glossterm>
+            <glossdef>
+                <para>The short (72 characters or less) summary of the binary package for packaging
+                    systems such as <filename>opkg</filename>, <filename>rpm</filename> or
+                    <filename>dpkg</filename>.
+                    By default, <filename>SUMMARY</filename> is used to define
+                    the <link linkend='var-DESCRIPTION'><filename>DESCRIPTION</filename></link>
+                    variable if <filename>DESCRIPTION</filename> is not set
+                    in the recipe.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-SYSROOT_PREPROCESS_FUNCS'><glossterm>SYSROOT_PREPROCESS_FUNCS</glossterm>
+            <glossdef>
+                <para>
+                    A list of functions to execute after files are staged into
+                    the sysroot.
+                    These functions are usually used to apply additional
+                    processing on the staged files, or to stage additional
+                    files.
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-t'><title>T</title>
+
+        <glossentry id='var-T'><glossterm>T</glossterm>
+            <glossdef>
+                <para>This variable points to a directory were BitBake places
+                    temporary files, which consist mostly of task logs and
+                    scripts, when building a particular recipe.
+                    The variable is typically set as follows:
+                    <literallayout class='monospaced'>
+     T = "${WORKDIR}/temp"
+                    </literallayout>
+                    The <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+                    is the directory into which BitBake unpacks and builds the
+                    recipe.
+                    The default <filename>bitbake.conf</filename> file sets this variable.</para>
+                    <para>The <filename>T</filename> variable is not to be confused with
+                    the <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> variable,
+                    which points to the root of the directory tree where BitBake
+                    places the output of an entire build.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TARGET_ARCH'><glossterm>TARGET_ARCH</glossterm>
+            <glossdef>
+                <para>
+                    The target machine's architecture.
+                    The OpenEmbedded build system supports many
+                    architectures.
+                    Here is an example list of architectures supported.
+                    This list is by no means complete as the architecture
+                    is configurable:
+                    <literallayout class='monospaced'>
+     arm
+     i586
+     x86_64
+     powerpc
+     powerpc64
+     mips
+     mipsel
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TARGET_CFLAGS'><glossterm>TARGET_CFLAGS</glossterm>
+            <glossdef>
+                <para>
+                    Flags passed to the C compiler for the target system.
+                    This variable evaluates to the same as
+                    <filename><link linkend='var-CFLAGS'>CFLAGS</link></filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+
+        <glossentry id='var-TARGET_FPU'><glossterm>TARGET_FPU</glossterm>
+            <glossdef>
+                <para>Specifies the method for handling FPU code.
+                    For FPU-less targets, which include most ARM CPUs, the variable must be
+                    set to "soft".
+                    If not, the kernel emulation gets used, which results in a performance penalty.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TARGET_OS'><glossterm>TARGET_OS</glossterm>
+            <glossdef>
+                <para>Specifies the target's operating system.
+                    The variable can be set to "linux" for <filename>eglibc</filename>-based systems and
+                    to "linux-uclibc" for <filename>uclibc</filename>.
+                    For ARM/EABI targets, there are also "linux-gnueabi" and
+                    "linux-uclibc-gnueabi" values possible.</para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TCLIBC'><glossterm>TCLIBC</glossterm>
+            <glossdef>
+                <para>
+                    Specifies which variant of the GNU standard C library (<filename>libc</filename>)
+                    to use during the build process.
+                    This variable replaces <filename>POKYLIBC</filename>, which is no longer
+                    supported.
+                </para>
+                <para>
+                    You can select <filename>eglibc</filename> or <filename>uclibc</filename>.
+                    <note>
+                        This release of the Yocto Project does not support the
+                        <filename>glibc</filename> implementation of <filename>libc</filename>.
+                    </note>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TCMODE'><glossterm>TCMODE</glossterm>
+            <glossdef>
+                <para>
+                    The toolchain selector.
+                    This variable replaces <filename>POKYMODE</filename>, which is no longer
+                    supported.
+                </para>
+                <para>
+                    The <filename>TCMODE</filename> variable selects the external toolchain
+                    built using the OpenEmbedded build system or a few supported combinations of
+                    the upstream GCC or CodeSourcery Labs toolchain.
+                    The variable identifies the <filename>tcmode-*</filename> files used in
+                    the <filename>meta/conf/distro/include</filename> directory, which is found in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+                <para>
+                    By default, <filename>TCMODE</filename> is set to "default", which
+                    chooses the <filename>tcmode-default.inc</filename> file.
+                    The variable is similar to
+                    <link linkend='var-TCLIBC'><filename>TCLIBC</filename></link>, which controls
+                    the variant of the GNU standard C library (<filename>libc</filename>)
+                    used during the build process: <filename>eglibc</filename> or <filename>uclibc</filename>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TEST_IMAGE'><glossterm>TEST_IMAGE</glossterm>
+            <glossdef>
+                <para>
+                    Automatically runs the series of automated tests for
+                    images when an image is successfully built.
+                    <note>
+                        Currently, there is only support for running these tests
+                        under QEMU.
+                    </note>
+                    These tests are written in Python making use of the
+                    <filename>unittest</filename> module, and the majority of
+                    them run commands on the target system over
+                    <filename>ssh</filename>.
+                    You can set this variable to "1" in your
+                    <filename>local.conf</filename> file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    to have the OpenEmbedded build system automatically run
+                    these tests after an image successfully builds:
+                    <literallayout class='monospaced'>
+     TEST_IMAGE = "1"
+                    </literallayout>
+                    For more information on enabling, running, and writing
+                    these tests, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+                    section in the Yocto Project Development Manual and the
+                    "<link linkend='ref-classes-testimage'><filename>testimage.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TEST_QEMUBOOT_TIMEOUT'><glossterm>TEST_QEMUBOOT_TIMEOUT</glossterm>
+            <glossdef>
+                <para>
+                    The time in seconds allowed for an image to boot before
+                    automated runtime tests begin to run against an
+                    image.
+                    The default timeout period to allow the boot process to
+                    reach the login prompt is 500 seconds.
+                    You can specify a different value in the
+                    <filename>local.conf</filename> file.
+                </para>
+
+                <para>
+                    For more information on testing images, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TEST_SUITES'><glossterm>TEST_SUITES</glossterm>
+            <glossdef>
+                <para>
+                    An ordered list of tests (modules) to run against
+                    an image when performing automated runtime testing.
+                </para>
+
+                <para>
+                    The OpenEmbedded build system provides a core set of tests
+                    that can be used against images.
+                    <note>
+                        Currently, there is only support for running these tests
+                        under QEMU.
+                    </note>
+                    Tests include <filename>ping</filename>,
+                    <filename>ssh</filename>, <filename>df</filename> among
+                    others.
+                    You can add your own tests to the list of tests by
+                    appending <filename>TEST_SUITES</filename> as follows:
+                    <literallayout class='monospaced'>
+     TEST_SUITES_append = " mytest"
+                    </literallayout>
+                    Alternatively, you can provide the "auto" option to
+                    have all applicable tests run against the image.
+                    <literallayout class='monospaced'>
+     TEST_SUITES_append = " auto"
+                    </literallayout>
+                    Using this option causes the build system to automatically
+                    run tests that are applicable to the image.
+                    Tests that are not applicable are skipped.
+                </para>
+
+                <para>
+                    The order in which tests are run is important.
+                    Tests that depend on another test must appear later in the
+                    list than the test on which they depend.
+                    For example, if you append the list of tests with two
+                    tests (<filename>test_A</filename> and
+                    <filename>test_B</filename>) where
+                    <filename>test_B</filename> is dependent on
+                    <filename>test_A</filename>, then you must order the tests
+                    as follows:
+                    <literallayout class='monospaced'>
+     TEST_SUITES = " test_A test_B"
+                    </literallayout>
+                </para>
+
+                <para>
+                    For more information on testing images, see the
+                    "<ulink url='&YOCTO_DOCS_DEV_URL;#performing-automated-runtime-testing'>Performing Automated Runtime Testing</ulink>"
+                    section in the Yocto Project Development Manual.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-THISDIR'><glossterm>THISDIR</glossterm>
+            <glossdef>
+                <para>
+                    The directory in which the file BitBake is currently
+                    parsing is located.
+                    Do not manually set this variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TMPDIR'><glossterm>TMPDIR</glossterm>
+            <glossdef>
+                <para>
+                    This variable is the base directory the OpenEmbedded
+                    build system uses for all build output and intermediate
+                    files (other than the shared state cache).
+                    By default, the <filename>TMPDIR</filename> variable points
+                    to <filename>tmp</filename> within the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                </para>
+
+                <para>
+                    If you want to establish this directory in a location other
+                    than the default, you can uncomment and edit the following
+                    statement in the
+                    <filename>conf/local.conf</filename> file in the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>:
+                    <literallayout class='monospaced'>
+     #TMPDIR = "${TOPDIR}/tmp"
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TOOLCHAIN_HOST_TASK'><glossterm>TOOLCHAIN_HOST_TASK</glossterm>
+            <glossdef>
+                <para>
+                    This variable lists packages the OpenEmbedded build system
+                    uses when building an SDK, which contains a
+                    cross-development environment.
+                    The packages specified by this variable are part of the
+                    toolchain set that runs on the
+                    <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
+                    and each package should usually have the prefix
+                    "nativesdk-".
+                    When building an SDK using
+                    <filename>bitbake -c populate_sdk &lt;imagename&gt;</filename>,
+                    a default list of packages is set in this variable, but
+                    you can add additional packages to the list.
+                </para>
+
+                <para>
+                    For background information on cross-development toolchains
+                    in the Yocto Project development environment, see the
+                    "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+                    section.
+                    For information on setting up a cross-development
+                    environment, see the
+                    "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
+                    section in the Yocto Project Application Developer's Guide.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TOOLCHAIN_TARGET_TASK'><glossterm>TOOLCHAIN_TARGET_TASK</glossterm>
+            <glossdef>
+                <para>
+                    This variable lists packages the OpenEmbedded build system
+                    uses when it creates the target part of an SDK
+                    (i.e. the part built for the target hardware), which
+                    includes libraries and headers.
+                </para>
+
+                <para>
+                    For background information on cross-development toolchains
+                    in the Yocto Project development environment, see the
+                    "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
+                    section.
+                    For information on setting up a cross-development
+                    environment, see the
+                    "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
+                    section in the Yocto Project Application Developer's Guide.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TOPDIR'><glossterm>TOPDIR</glossterm>
+            <glossdef>
+                <para>
+                    This variable points to the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+                    BitBake automatically sets this variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TRANSLATED_TARGET_ARCH'><glossterm>TRANSLATED_TARGET_ARCH</glossterm>
+            <glossdef>
+                <para>
+                    A sanitized version of
+                    <link linkend='var-TARGET_ARCH'><filename>TARGET_ARCH</filename></link>.
+                    This variable is used where the architecture is needed in
+                    a value where underscores are not allowed, for example
+                    within package filenames.
+                    In this case, dash characters replace any underscore
+                    characters used in TARGET_ARCH.
+                </para>
+
+                <para>
+                    Do not edit this variable.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-TUNE_PKGARCH'><glossterm>TUNE_PKGARCH</glossterm>
+            <glossdef>
+                <para>
+                    The package architecture understood by the packaging
+                    system to define the architecture, ABI, and tuning of
+                    output packages.
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+    <glossdiv id='var-glossary-u'><title>U</title>
+
+        <glossentry id='var-UBOOT_ENTRYPOINT'><glossterm>UBOOT_ENTRYPOINT</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the entry point for the U-Boot image.
+                    During U-Boot image creation, the
+                    <filename>UBOOT_ENTRYPOINT</filename> variable is passed
+                    as a command-line parameter to the
+                    <filename>uboot-mkimage</filename> utility.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-UBOOT_LOADADDRESS'><glossterm>UBOOT_LOADADDRESS</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the load address for the U-Boot image.
+                    During U-Boot image creation, the
+                    <filename>UBOOT_LOADADDRESS</filename> variable is passed
+                    as a command-line parameter to the
+                    <filename>uboot-mkimage</filename> utility.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-UBOOT_MACHINE'><glossterm>UBOOT_MACHINE</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the value passed on the
+                    <filename>make</filename> command line when building
+                    a U-Boot image.
+                    The value indicates the target platform configuration.
+                    You typically set this variable from the machine
+                    configuration file (i.e.
+                    <filename>conf/machine/&lt;machine_name&gt;.conf</filename>).
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-UBOOT_TARGET'><glossterm>UBOOT_TARGET</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the target used for building U-Boot.
+                    The target is passed directly as part of the "make" command
+                    (e.g. SPL and AIS).
+                    If you do not specifically set this variable, the
+                    OpenEmbedded build process passes and uses "all" for the
+                    target during the U-Boot building process.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-USER_CLASSES'><glossterm>USER_CLASSES</glossterm>
+            <glossdef>
+                <para>
+                    A list of classes to globally inherit.
+                    These classes are used by the OpenEmbedded build system
+                    to enable extra features (e.g.
+                    <filename>buildstats</filename>,
+                    <filename>image-mklibs</filename>, and so forth).
+                </para>
+
+                <para>
+                    The default list is set in your
+                    <filename>local.conf</filename> file:
+                    <literallayout class='monospaced'>
+     USER_CLASSES ?= "buildstats image-mklibs image-prelink"
+                    </literallayout>
+                    For more information, see
+                    <filename>meta-yocto/conf/local.conf.sample</filename> in
+                    the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+<!--            <glossdiv id='var-glossary-v'><title>V</title>-->
+<!--            </glossdiv>-->
+
+    <glossdiv id='var-glossary-w'><title>W</title>
+
+        <glossentry id='var-WARN_QA'><glossterm>WARN_QA</glossterm>
+            <glossdef>
+                <para>
+                    Specifies the quality assurance checks whose failures are
+                    reported as warnings by the OpenEmbedded build system.
+                    You set this variable in your distribution configuration
+                    file.
+                    For a list of the checks you can control with this variable,
+                    see the
+                    "<link linkend='ref-classes-insane'><filename>insane.bbclass</filename></link>"
+                    section.
+                </para>
+            </glossdef>
+        </glossentry>
+
+        <glossentry id='var-WORKDIR'><glossterm>WORKDIR</glossterm>
+            <glossdef>
+                <para>
+                    The pathname of the working directory in which the OpenEmbedded build system
+                    builds a recipe.
+                    This directory is located within the
+                    <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link> directory structure and changes
+                    as different packages are built.
+                </para>
+
+                <para>
+                    The actual <filename>WORKDIR</filename> directory depends on several things:
+                    <itemizedlist>
+                        <listitem>The temporary directory - <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link></listitem>
+                        <listitem>The package architecture - <link linkend='var-PACKAGE_ARCH'><filename>PACKAGE_ARCH</filename></link></listitem>
+                        <listitem>The target machine - <link linkend='var-MACHINE'><filename>MACHINE</filename></link></listitem>
+                        <listitem>The target operating system - <link linkend='var-TARGET_OS'><filename>TARGET_OS</filename></link></listitem>
+                        <listitem>The recipe name - <link linkend='var-PN'><filename>PN</filename></link></listitem>
+                        <listitem>The recipe version - <link linkend='var-PV'><filename>PV</filename></link></listitem>
+                        <listitem>The recipe revision - <link linkend='var-PR'><filename>PR</filename></link></listitem>
+                    </itemizedlist>
+                </para>
+
+                <para>
+                    For packages that are not dependent on a particular machine,
+                    <filename>WORKDIR</filename> is defined as follows:
+                    <literallayout class='monospaced'>
+ ${TMPDIR}/work/${PACKAGE_ARCH}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
+                    </literallayout>
+                    As an example, assume a
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink> top-level
+                    folder name <filename>poky</filename> and a default
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+                    at <filename>poky/build</filename>.
+                    In this case, the working directory the build system uses to build
+                    the <filename>v86d</filename> package is the following:
+                    <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/qemux86-poky-linux/v86d/01.9-r0
+                    </literallayout>
+                </para>
+
+                <para>
+                    For packages that are dependent on a particular machine, <filename>WORKDIR</filename>
+                    is defined slightly different:
+                    <literallayout class='monospaced'>
+ ${TMPDIR}/work/${MACHINE}-poky-${TARGET_OS}/${PN}/${PV}-${PR}
+                    </literallayout>
+                    As an example, again assume a Source Directory top-level folder
+                    named <filename>poky</filename> and a default Build Directory
+                    at <filename>poky/build</filename>.
+                    In this case, the working directory the build system uses to build
+                    the <filename>acl</filename> recipe, which is being built for a
+                    MIPS-based device, is the following:
+                    <literallayout class='monospaced'>
+     ~/poky/build/tmp/work/mips-poky-linux/acl/2.2.51-r2
+                    </literallayout>
+                </para>
+            </glossdef>
+        </glossentry>
+
+    </glossdiv>
+
+<!--            <glossdiv id='var-glossary-x'><title>X</title>-->
+<!--            </glossdiv>-->
+
+<!--            <glossdiv id='var-glossary-y'><title>Y</title>-->
+<!--            </glossdiv>-->
+
+<!--            <glossdiv id='var-glossary-z'><title>Z</title>-->
+<!--            </glossdiv>-->
+
+</glossary>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/ref-varlocality.xml b/documentation/ref-manual/ref-varlocality.xml
new file mode 100644
index 0000000000..d3f873298d
--- /dev/null
+++ b/documentation/ref-manual/ref-varlocality.xml
@@ -0,0 +1,196 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='ref-varlocality'>
+    <title>Variable Context</title>
+
+    <para>
+        While you can use most variables in almost any context such as
+        <filename>.conf</filename>, <filename>.bbclass</filename>,
+        <filename>.inc</filename>, and <filename>.bb</filename> files,
+        some variables are often associated with a particular locality or context.
+        This chapter describes some common associations.
+    </para>
+
+    <section id='ref-varlocality-configuration'>
+        <title>Configuration</title>
+
+        <para>
+            The following subsections provide lists of variables whose context is
+            configuration: distribution, machine, and local.
+        </para>
+
+        <section id='ref-varlocality-config-distro'>
+            <title>Distribution (Distro)</title>
+
+            <para>
+               This section lists variables whose configuration context is the
+               distribution, or distro.
+               <itemizedlist>
+                   <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename></para></listitem>
+                   <listitem><para><filename><link linkend='var-DISTRO_NAME'>DISTRO_NAME</link></filename>
+                       </para></listitem>
+                   <listitem><para><filename><link linkend='var-DISTRO_VERSION'>DISTRO_VERSION</link>
+                       </filename></para></listitem>
+                   <listitem><para><filename><link linkend='var-MAINTAINER'>MAINTAINER</link></filename>
+                       </para></listitem>
+                   <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
+                       </filename></para></listitem>
+                   <listitem><para><filename><link linkend='var-TARGET_OS'>TARGET_OS</link></filename>
+                       </para></listitem>
+                   <listitem><para><filename><link linkend='var-TARGET_FPU'>TARGET_FPU</link></filename>
+                       </para></listitem>
+                   <listitem><para><filename><link linkend='var-TCMODE'>TCMODE</link></filename>
+                       </para></listitem>
+                   <listitem><para><filename><link linkend='var-TCLIBC'>TCLIBC</link></filename>
+                       </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='ref-varlocality-config-machine'>
+            <title>Machine</title>
+
+            <para>
+                This section lists variables whose configuration context is the
+                machine.
+                <itemizedlist>
+                    <listitem><para><filename><link linkend='var-TARGET_ARCH'>TARGET_ARCH</link></filename>
+                        </para></listitem>
+                    <listitem><para><filename><link linkend='var-SERIAL_CONSOLES'>SERIAL_CONSOLES</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-PACKAGE_EXTRA_ARCHS'>PACKAGE_EXTRA_ARCHS</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-IMAGE_FSTYPES'>IMAGE_FSTYPES</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-MACHINE_FEATURES'>MACHINE_FEATURES</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RDEPENDS'>MACHINE_EXTRA_RDEPENDS
+                        </link></filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-MACHINE_EXTRA_RRECOMMENDS'>MACHINE_EXTRA_RRECOMMENDS
+                        </link></filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RDEPENDS'>MACHINE_ESSENTIAL_EXTRA_RDEPENDS
+                        </link></filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS'>
+                        MACHINE_ESSENTIAL_EXTRA_RRECOMMENDS</link></filename></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='ref-varlocality-config-local'>
+            <title>Local</title>
+
+            <para>
+                This section lists variables whose configuration context is the
+                local configuration through the <filename>local.conf</filename>
+                file.
+                <itemizedlist>
+                    <listitem><para><filename><link linkend='var-DISTRO'>DISTRO</link></filename>
+                        </para></listitem>
+                    <listitem><para><filename><link linkend='var-MACHINE'>MACHINE</link></filename>
+                        </para></listitem>
+                    <listitem><para><filename><link linkend='var-DL_DIR'>DL_DIR</link></filename>
+                        </para></listitem>
+                    <listitem><para><filename><link linkend='var-BBFILES'>BBFILES</link></filename>
+                        </para></listitem>
+                    <listitem><para><filename><link linkend='var-EXTRA_IMAGE_FEATURES'>EXTRA_IMAGE_FEATURES
+                        </link></filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-PACKAGE_CLASSES'>PACKAGE_CLASSES</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-BB_NUMBER_THREADS'>BB_NUMBER_THREADS</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-BBINCLUDELOGS'>BBINCLUDELOGS</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-ENABLE_BINARY_LOCALE_GENERATION'>
+                        ENABLE_BINARY_LOCALE_GENERATION</link></filename></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+    </section>
+
+    <section id='ref-varlocality-recipes'>
+        <title>Recipes</title>
+
+        <para>
+            The following subsections provide lists of variables whose context is
+            recipes: required, dependencies, path, and extra build information.
+        </para>
+
+        <section id='ref-varlocality-recipe-required'>
+            <title>Required</title>
+
+            <para>
+                This section lists variables that are required for recipes.
+                <itemizedlist>
+                    <listitem><para><filename><link linkend='var-LICENSE'>LICENSE</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-SRC_URI'>SRC_URI</link></filename> - used
+                        in recipes that fetch local or remote files.
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='ref-varlocality-recipe-dependencies'>
+            <title>Dependencies</title>
+
+            <para>
+                This section lists variables that define recipe dependencies.
+                <itemizedlist>
+                    <listitem><para><filename><link linkend='var-DEPENDS'>DEPENDS</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-RDEPENDS'>RDEPENDS</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-RRECOMMENDS'>RRECOMMENDS</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-RCONFLICTS'>RCONFLICTS</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-RREPLACES'>RREPLACES</link>
+                        </filename></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='ref-varlocality-recipe-paths'>
+            <title>Paths</title>
+
+            <para>
+                This section lists variables that define recipe paths.
+                <itemizedlist>
+                    <listitem><para><filename><link linkend='var-WORKDIR'>WORKDIR</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-S'>S</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-FILES'>FILES</link>
+                        </filename></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='ref-varlocality-recipe-build'>
+            <title>Extra Build Information</title>
+
+            <para>
+                This section lists variables that define extra build information for recipes.
+                <itemizedlist>
+                    <listitem><para><filename><link linkend='var-EXTRA_OECMAKE'>EXTRA_OECMAKE</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-EXTRA_OECONF'>EXTRA_OECONF</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-EXTRA_OEMAKE'>EXTRA_OEMAKE</link>
+                        </filename></para></listitem>
+                    <listitem><para><filename><link linkend='var-PACKAGES'>PACKAGES</link></filename>
+                        </para></listitem>
+                    <listitem><para><filename><link linkend='var-DEFAULT_PREFERENCE'>DEFAULT_PREFERENCE
+                        </link></filename></para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+    </section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4 spell spelllang=en_gb
+-->
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml
new file mode 100644
index 0000000000..c48951f934
--- /dev/null
+++ b/documentation/ref-manual/resources.xml
@@ -0,0 +1,128 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='resources'>
+<title>Contributing to the Yocto Project</title>
+
+<section id='resources-intro'>
+    <title>Introduction</title>
+    <para>
+        The Yocto Project team is happy for people to experiment with the Yocto Project.
+        A number of places exist to find help if you run into difficulties or find bugs.
+        To find out how to download source code,
+        see the "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto Project Release</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+</section>
+
+<section id='resources-bugtracker'>
+    <title>Tracking Bugs</title>
+
+    <para>
+        If you find problems with the Yocto Project, you should report them using the
+        Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>.
+    </para>
+</section>
+
+<section id='resources-mailinglist'>
+    <title>Mailing lists</title>
+
+    <para>
+        A number of mailing lists maintained by the Yocto Project exist 
+        as well as related OpenEmbedded mailing lists for discussion, 
+        patch submission and announcements.
+        To subscribe to one of the following mailing lists, click on the 
+        appropriate URL in the following list and follow the instructions:
+        <itemizedlist>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> -
+                General Yocto Project discussion mailing list. </para></listitem>
+            <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'></ulink> -
+                Discussion mailing list about OpenEmbedded-Core (the core metadata).</para></listitem>
+            <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'></ulink> -
+                Discussion mailing list about OpenEmbedded.</para></listitem>
+            <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
+                Discussion mailing list about the 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#bitbake-term'>BitBake</ulink>
+                build tool.</para></listitem>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
+                Discussion mailing list about 
+                <ulink url='&YOCTO_DOCS_DEV_URL;#poky'>Poky</ulink>.
+                </para></listitem>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> -
+                Mailing list to receive official Yocto Project release and milestone
+                announcements.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='resources-irc'>
+    <title>Internet Relay Chat (IRC)</title>
+
+    <para>
+        Two IRC channels on freenode are available for the Yocto Project and Poky discussions:
+        <itemizedlist>
+            <listitem><para><filename>#yocto</filename></para></listitem>
+            <listitem><para><filename>#poky</filename></para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='resources-links'>
+    <title>Links</title>
+
+    <para>
+        Here is a list of resources you will find helpful:
+        <itemizedlist>
+            <listitem><para><emphasis>
+                <ulink url='&YOCTO_HOME_URL;'>The Yocto Project website</ulink>:
+                </emphasis> The home site for the Yocto 
+                Project.</para></listitem>
+            <listitem><para><emphasis>
+                <ulink url='http://www.intel.com/'>Intel Corporation</ulink>:</emphasis>
+                The company who acquired OpenedHand in 2008 and began 
+                development on the Yocto Project.</para></listitem>
+            <listitem><para><emphasis>
+                <ulink url='&OE_HOME_URL;'>OpenEmbedded</ulink>:</emphasis>
+                The upstream, generic, embedded distribution used as the basis 
+                for the build system in the Yocto Project.
+                Poky derives from and contributes back to the OpenEmbedded 
+                project.</para></listitem>
+            <listitem><para><emphasis>
+                <ulink url='http://developer.berlios.de/projects/bitbake/'>
+                BitBake</ulink>:</emphasis> The tool used to process metadata.</para></listitem>
+            <listitem><para><emphasis>
+                BitBake User Manual:</emphasis>
+                A comprehensive guide to the BitBake tool.
+                You can find the BitBake User Manual in the 
+                <filename>bitbake/doc/manual</filename> directory, which is 
+                found in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+                </para></listitem>
+            <listitem><para><emphasis>
+                <ulink url='http://wiki.qemu.org/Index.html'>QEMU</ulink>:
+                </emphasis> An open source machine emulator and virtualizer.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='resources-contributions'>
+    <title>Contributions</title>
+
+    <para>
+        The Yocto Project gladly accepts contributions.
+        You can submit changes to the project either by creating and sending 
+        pull requests,
+        or by submitting patches through email.
+        For information on how to do both as well as information on how
+        to find out who is the maintainer for areas of code, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#how-to-submit-a-change'>How to Submit a Change</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
new file mode 100644
index 0000000000..be9c38709a
--- /dev/null
+++ b/documentation/ref-manual/technical-details.xml
@@ -0,0 +1,1335 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='technical-details'>
+<title>Technical Details</title>
+
+    <para>
+        This chapter provides technical details for various parts of the Yocto Project.
+        Currently, topics include Yocto Project components,
+        shared state (sstate) cache, x32, and Licenses.
+    </para>
+
+<section id='usingpoky-components'>
+    <title>Yocto Project Components</title>
+
+    <para>
+        The BitBake task executor together with various types of configuration files form the
+        OpenEmbedded Core.
+        This section overviews these by describing what they are used for
+        and how they interact.
+    </para>
+
+    <para>
+        BitBake handles the parsing and execution of the data files.
+        The data itself is of various types:
+    <itemizedlist>
+        <listitem><para><emphasis>Recipes:</emphasis>  Provides details about particular
+            pieces of software.</para></listitem>
+        <listitem><para><emphasis>Class Data:</emphasis>  Abstracts common build
+            information (e.g. how to build a Linux kernel).</para></listitem>
+        <listitem><para><emphasis>Configuration Data:</emphasis>  Defines machine-specific settings,
+            policy decisions, and so forth.
+            Configuration data acts as the glue to bind everything together.</para></listitem>
+    </itemizedlist>
+        For more information on data, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#yocto-project-terms'>Yocto Project Terms</ulink>"
+        section in the Yocto Project Development Manual.
+    </para>
+
+    <para>
+        BitBake knows how to combine multiple data sources together and refers to each data source
+        as a layer.
+        For information on layers, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#understanding-and-creating-layers'>Understanding and
+        Creating Layers</ulink>" section of the Yocto Project Development Manual.
+    </para>
+
+    <para>
+        Following are some brief details on these core components.
+        For more detailed information on these components, see the
+        "<link linkend='ref-structure'>Source Directory Structure</link>" chapter.
+    </para>
+
+    <section id='usingpoky-components-bitbake'>
+        <title>BitBake</title>
+
+        <para>
+            BitBake is the tool at the heart of the OpenEmbedded build system
+            and is responsible for parsing the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>,
+            generating a list of tasks from it, and then executing those tasks.
+            To see a list of the options BitBake supports, use the following
+            help command:
+            <literallayout class='monospaced'>
+     $ bitbake --help
+            </literallayout>
+        </para>
+
+        <para>
+            The most common usage for BitBake is <filename>bitbake &lt;packagename&gt;</filename>, where
+            <filename>packagename</filename> is the name of the package you want to build
+            (referred to as the "target" in this manual).
+            The target often equates to the first part of a <filename>.bb</filename> filename.
+            So, to run the <filename>matchbox-desktop_1.2.3.bb</filename> file, you
+            might type the following:
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop
+            </literallayout>
+            Several different versions of <filename>matchbox-desktop</filename> might exist.
+            BitBake chooses the one selected by the distribution configuration.
+            You can get more details about how BitBake chooses between different
+            target versions and providers in the
+            "<link linkend='ref-bitbake-providers'>Preferences and Providers</link>" section.
+        </para>
+
+        <para>
+            BitBake also tries to execute any dependent tasks first.
+            So for example, before building <filename>matchbox-desktop</filename>, BitBake
+            would build a cross compiler and <filename>eglibc</filename> if they had not already
+            been built.
+            <note>This release of the Yocto Project does not support the <filename>glibc</filename>
+                GNU version of the Unix standard C library.  By default, the OpenEmbedded build system
+                builds with <filename>eglibc</filename>.</note>
+        </para>
+
+        <para>
+            A useful BitBake option to consider is the <filename>-k</filename> or
+            <filename>--continue</filename> option.
+            This option instructs BitBake to try and continue processing the job as much
+            as possible even after encountering an error.
+            When an error occurs, the target that
+            failed and those that depend on it cannot be remade.
+            However, when you use this option other dependencies can still be processed.
+        </para>
+    </section>
+
+    <section id='usingpoky-components-metadata'>
+        <title>Metadata (Recipes)</title>
+
+        <para>
+            The <filename>.bb</filename> files are usually referred to as "recipes."
+            In general, a recipe contains information about a single piece of software.
+            The information includes the location from which to download the source patches
+            (if any are needed), which special configuration options to apply,
+            how to compile the source files, and how to package the compiled output.
+        </para>
+
+        <para>
+            The term "package" can also be used to describe recipes.
+            However, since the same word is used for the packaged output from the OpenEmbedded
+            build system (i.e. <filename>.ipk</filename> or <filename>.deb</filename> files),
+            this document avoids using the term "package" when referring to recipes.
+        </para>
+    </section>
+
+    <section id='usingpoky-components-classes'>
+        <title>Classes</title>
+
+        <para>
+            Class files (<filename>.bbclass</filename>) contain information that
+            is useful to share between
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files.
+            An example is the Autotools class, which contains
+            common settings for any application that Autotools uses.
+            The "<link linkend='ref-classes'>Classes</link>" chapter provides details
+            about common classes and how to use them.
+        </para>
+    </section>
+
+    <section id='usingpoky-components-configuration'>
+        <title>Configuration</title>
+
+        <para>
+            The configuration files (<filename>.conf</filename>) define various configuration variables
+            that govern the OpenEmbedded build process.
+            These files fall into several areas that define machine configuration options,
+            distribution configuration options, compiler tuning options, general common configuration
+            options, and user configuration options in <filename>local.conf</filename>, which is found
+            in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+        </para>
+    </section>
+</section>
+
+<section id="cross-development-toolchain-generation">
+    <title>Cross-Development Toolchain Generation</title>
+
+    <para>
+        The Yocto Project does most of the work for you when it comes to
+        creating
+        <ulink url='&YOCTO_DOCS_DEV_URL;#cross-development-toolchain'>cross-development toolchains</ulink>.
+        This section provides some technical background information on how
+        cross-development toolchains are created and used.
+        For more information on these toolchain, you can also see the
+        <ulink url='&YOCTO_DOCS_ADT_URL;'>the Yocto Project Application Developer's Guide</ulink>.
+    </para>
+
+    <para>
+        In the Yocto Project development environment, cross-development
+        toolchains are used to build the image and applications that run on the
+        target hardware.
+        With just a few commands, the OpenEmbedded build system creates
+        these necessary toolchains for you.
+    </para>
+
+    <para>
+        The following figure shows a high-level build environment regarding
+        toolchain construction and use.
+    </para>
+
+    <para>
+        <imagedata fileref="figures/cross-development-toolchains.png" width="8in" depth="6in" align="center" />
+    </para>
+
+    <para>
+        Most of the work occurs on the Build Host.
+        This is the machine used to build images and generally work within the
+        the Yocto Project environment.
+        When you run BitBake to create an image, the OpenEmbedded build system
+        uses the host <filename>gcc</filename> compiler to bootstrap a
+        cross-compiler named <filename>gcc-cross</filename>.
+        The <filename>gcc-cross</filename> compiler is what BitBake uses to
+        compile source files when creating the target image.
+        You can think of <filename>gcc-cross</filename> simply as an
+        automatically generated cross-compiler that is used internally within
+        BitBake only.
+    </para>
+
+    <para>
+        The chain of events that occurs when <filename>gcc-cross</filename> is
+        bootstrapped is as follows:
+        <literallayout class='monospaced'>
+     gcc -> binutils-cross -> gcc-cross-initial -> linux-libc-headers -> eglibc-initial -> eglibc -> gcc-cross -> gcc-runtime
+        </literallayout>
+        <itemizedlist>
+            <listitem><para><filename>gcc</filename>:
+                The build host's GNU Compiler Collection (GCC).
+                </para></listitem>
+            <listitem><para><filename>binutils-cross</filename>:
+                The bare minimum binary utilities needed in order to run
+                the <filename>gcc-cross-initial</filename> phase of the
+                bootstrap operation.
+                </para></listitem>
+            <listitem><para><filename>gcc-cross-initial</filename>:
+                An early stage of the bootstrap process for creating
+                the cross-compiler.
+                This stage builds enough of the <filename>gcc-cross</filename>,
+                the C library, and other pieces needed to finish building the
+                final cross-compiler in later stages.
+                This tool is a "native" package (i.e. it is designed to run on
+                the build host).
+                </para></listitem>
+            <listitem><para><filename>linux-libc-headers</filename>:
+                Headers needed for the cross-compiler.
+                </para></listitem>
+            <listitem><para><filename>eglibc-initial</filename>:
+                An initial version of the Embedded GLIBC needed to bootstrap
+                <filename>eglibc</filename>.
+                </para></listitem>
+            <listitem><para><filename>gcc-cross</filename>:
+                The final stage of the bootstrap process for the
+                cross-compiler.
+                This stage results in the actual cross-compiler that
+                BitBake uses when it builds an image for a targeted
+                device.
+                <note>
+                    If you are replacing this cross compiler toolchain
+                    with a custom version, you must replace
+                    <filename>gcc-cross</filename>.
+                </note>
+                This tool is also a "native" package (i.e. it is
+                designed to run on the build host).
+                </para></listitem>
+            <listitem><para><filename>gcc-runtime</filename>:
+                Runtime libraries resulting from the toolchain bootstrapping
+                process.
+                This tool produces a binary that consists of the
+                runtime libraries need for the targeted device.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        You can use the OpenEmbedded build system to build an installer for
+        the relocatable SDK used to develop applications.
+        When you run the installer, it installs the toolchain, which contains
+        the development tools (e.g., the
+        <filename>gcc-cross-canadian</filename>),
+        <filename>binutils-cross-canadian</filename>, and other
+        <filename>nativesdk-*</filename> tools you need to cross-compile and
+        test your software.
+        The figure shows the commands you use to easily build out this
+        toolchain.
+        This cross-development toolchain is built to execute on the
+        <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
+        which might or might not be the same
+        machine as the Build Host.
+        <note>
+            If your target architecture is supported by the Yocto Project,
+            you can take advantage of pre-built images that ship with the
+            Yocto Project and already contain cross-development toolchain
+            installers.
+        </note>
+    </para>
+
+    <para>
+        Here is the bootstrap process for the relocatable toolchain:
+        <literallayout class='monospaced'>
+     gcc -> binutils-crosssdk -> gcc-crosssdk-initial -> linux-libc-headers -> eglibc-initial -> nativesdk-eglibc -> gcc-crosssdk -> gcc-cross-canadian
+        </literallayout>
+        <itemizedlist>
+            <listitem><para><filename>gcc</filename>:
+                The build host's GNU Compiler Collection (GCC).
+                </para></listitem>
+            <listitem><para><filename>binutils-crosssdk</filename>:
+                The bare minimum binary utilities needed in order to run
+                the <filename>gcc-crosssdk-initial</filename> phase of the
+                bootstrap operation.
+                </para></listitem>
+            <listitem><para><filename>gcc-crosssdk-initial</filename>:
+                An early stage of the bootstrap process for creating
+                the cross-compiler.
+                This stage builds enough of the
+                <filename>gcc-crosssdk</filename> and supporting pieces so that
+                the final stage of the bootstrap process can produce the
+                finished cross-compiler.
+                This tool is a "native" binary that runs on the build host.
+                </para></listitem>
+            <listitem><para><filename>linux-libc-headers</filename>:
+                Headers needed for the cross-compiler.
+                </para></listitem>
+            <listitem><para><filename>eglibc-initial</filename>:
+                An initial version of the Embedded GLIBC needed to bootstrap
+                <filename>nativesdk-eglibc</filename>.
+                </para></listitem>
+            <listitem><para><filename>nativesdk-eglibc</filename>:
+                The Embedded GLIBC needed to bootstrap the
+                <filename>gcc-crosssdk</filename>.
+                </para></listitem>
+            <listitem><para><filename>gcc-crosssdk</filename>:
+                The final stage of the bootstrap process for the
+                relocatable cross-compiler.
+                The <filename>gcc-crosssdk</filename> is a transitory compiler
+                and never leaves the build host.
+                Its purpose is to help in the bootstrap process to create the
+                eventual relocatable <filename>gcc-cross-canadian</filename>
+                compiler, which is relocatable.
+                This tool is also a "native" package (i.e. it is
+                designed to run on the build host).
+                </para></listitem>
+            <listitem><para><filename>gcc-cross-canadian</filename>:
+                The final relocatable cross-compiler.
+                When run on the
+                <link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>,
+                this tool
+                produces executable code that runs on the target device.
+                </para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id="shared-state-cache">
+    <title>Shared State Cache</title>
+
+    <para>
+        By design, the OpenEmbedded build system builds everything from scratch unless
+        BitBake can determine that parts do not need to be rebuilt.
+        Fundamentally, building from scratch is attractive as it means all parts are
+        built fresh and there is no possibility of stale data causing problems.
+        When developers hit problems, they typically default back to building from scratch
+        so they know the state of things from the start.
+    </para>
+
+    <para>
+        Building an image from scratch is both an advantage and a disadvantage to the process.
+        As mentioned in the previous paragraph, building from scratch ensures that
+        everything is current and starts from a known state.
+        However, building from scratch also takes much longer as it generally means
+        rebuilding things that do not necessarily need rebuilt.
+    </para>
+
+    <para>
+        The Yocto Project implements shared state code that supports incremental builds.
+        The implementation of the shared state code answers the following questions that
+        were fundamental roadblocks within the OpenEmbedded incremental build support system:
+        <itemizedlist>
+            <listitem>What pieces of the system have changed and what pieces have not changed?</listitem>
+            <listitem>How are changed pieces of software removed and replaced?</listitem>
+            <listitem>How are pre-built components that do not need to be rebuilt from scratch
+                used when they are available?</listitem>
+        </itemizedlist>
+    </para>
+
+    <para>
+        For the first question, the build system detects changes in the "inputs" to a given task by
+        creating a checksum (or signature) of the task's inputs.
+        If the checksum changes, the system assumes the inputs have changed and the task needs to be
+        rerun.
+        For the second question, the shared state (sstate) code tracks which tasks add which output
+        to the build process.
+        This means the output from a given task can be removed, upgraded or otherwise manipulated.
+        The third question is partly addressed by the solution for the second question
+        assuming the build system can fetch the sstate objects from remote locations and
+        install them if they are deemed to be valid.
+    </para>
+
+    <note>
+        The OpenEmbedded build system does not maintain
+        <link linkend='var-PR'><filename>PR</filename></link> information
+        as part of the shared state packages.
+        Consequently, considerations exist that affect maintaining shared
+        state feeds.
+        For information on how the OpenEmbedded works with packages and can
+        track incrementing <filename>PR</filename> information, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#incrementing-a-package-revision-number'>Incrementing a Package Revision Number</ulink>"
+        section.
+    </note>
+
+    <para>
+        The rest of this section goes into detail about the overall incremental build
+        architecture, the checksums (signatures), shared state, and some tips and tricks.
+    </para>
+
+    <section id='overall-architecture'>
+        <title>Overall Architecture</title>
+
+        <para>
+            When determining what parts of the system need to be built, BitBake
+            uses a per-task basis and does not use a per-recipe basis.
+            You might wonder why using a per-task basis is preferred over a per-recipe basis.
+            To help explain, consider having the IPK packaging backend enabled and then switching to DEB.
+            In this case, <filename>do_install</filename> and <filename>do_package</filename>
+            output are still valid.
+            However, with a per-recipe approach, the build would not include the
+            <filename>.deb</filename> files.
+            Consequently, you would have to invalidate the whole build and rerun it.
+            Rerunning everything is not the best situation.
+            Also in this case, the core must be "taught" much about specific tasks.
+            This methodology does not scale well and does not allow users to easily add new tasks
+            in layers or as external recipes without touching the packaged-staging core.
+        </para>
+    </section>
+
+    <section id='checksums'>
+        <title>Checksums (Signatures)</title>
+
+        <para>
+            The shared state code uses a checksum, which is a unique signature of a task's
+            inputs, to determine if a task needs to be run again.
+            Because it is a change in a task's inputs that triggers a rerun, the process
+            needs to detect all the inputs to a given task.
+            For shell tasks, this turns out to be fairly easy because
+            the build process generates a "run" shell script for each task and
+            it is possible to create a checksum that gives you a good idea of when
+            the task's data changes.
+        </para>
+
+        <para>
+            To complicate the problem, there are things that should not be included in
+            the checksum.
+            First, there is the actual specific build path of a given task -
+            the <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
+            It does not matter if the working directory changes because it should not
+            affect the output for target packages.
+            Also, the build process has the objective of making native or cross packages relocatable.
+            The checksum therefore needs to exclude <filename>WORKDIR</filename>.
+            The simplistic approach for excluding the working directory is to set
+            <filename>WORKDIR</filename> to some fixed value and create the checksum
+            for the "run" script.
+        </para>
+
+        <para>
+            Another problem results from the "run" scripts containing functions that
+            might or might not get called.
+            The incremental build solution contains code that figures out dependencies
+            between shell functions.
+            This code is used to prune the "run" scripts down to the minimum set,
+            thereby alleviating this problem and making the "run" scripts much more
+            readable as a bonus.
+        </para>
+
+        <para>
+            So far we have solutions for shell scripts.
+            What about Python tasks?
+            The same approach applies even though these tasks are more difficult.
+            The process needs to figure out what variables a Python function accesses
+            and what functions it calls.
+            Again, the incremental build solution contains code that first figures out
+            the variable and function dependencies, and then creates a checksum for the data
+            used as the input to the task.
+        </para>
+
+        <para>
+            Like the <filename>WORKDIR</filename> case, situations exist where dependencies
+            should be ignored.
+            For these cases, you can instruct the build process to ignore a dependency
+            by using a line like the following:
+            <literallayout class='monospaced'>
+     PACKAGE_ARCHS[vardepsexclude] = "MACHINE"
+            </literallayout>
+            This example ensures that the <filename>PACKAGE_ARCHS</filename> variable does not
+            depend on the value of <filename>MACHINE</filename>, even if it does reference it.
+        </para>
+
+        <para>
+            Equally, there are cases where we need to add dependencies BitBake is not able to find.
+            You can accomplish this by using a line like the following:
+            <literallayout class='monospaced'>
+      PACKAGE_ARCHS[vardeps] = "MACHINE"
+            </literallayout>
+            This example explicitly adds the <filename>MACHINE</filename> variable as a
+            dependency for <filename>PACKAGE_ARCHS</filename>.
+        </para>
+
+        <para>
+            Consider a case with in-line Python, for example, where BitBake is not
+            able to figure out dependencies.
+            When running in debug mode (i.e. using <filename>-DDD</filename>), BitBake
+            produces output when it discovers something for which it cannot figure out
+            dependencies.
+            The Yocto Project team has currently not managed to cover those dependencies
+            in detail and is aware of the need to fix this situation.
+        </para>
+
+        <para>
+            Thus far, this section has limited discussion to the direct inputs into a task.
+            Information based on direct inputs is referred to as the "basehash" in the
+            code.
+            However, there is still the question of a task's indirect inputs - the
+            things that were already built and present in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+            The checksum (or signature) for a particular task needs to add the hashes
+            of all the tasks on which the particular task depends.
+            Choosing which dependencies to add is a policy decision.
+            However, the effect is to generate a master checksum that combines the basehash
+            and the hashes of the task's dependencies.
+        </para>
+
+        <para>
+            At the code level, there are a variety of ways both the basehash and the
+            dependent task hashes can be influenced.
+            Within the BitBake configuration file, we can give BitBake some extra information
+            to help it construct the basehash.
+            The following statements effectively result in a list of global variable
+            dependency excludes - variables never included in any checksum:
+            <literallayout class='monospaced'>
+  BB_HASHBASE_WHITELIST ?= "TMPDIR FILE PATH PWD BB_TASKHASH BBPATH"
+  BB_HASHBASE_WHITELIST += "DL_DIR SSTATE_DIR THISDIR FILESEXTRAPATHS"
+  BB_HASHBASE_WHITELIST += "FILE_DIRNAME HOME LOGNAME SHELL TERM USER"
+  BB_HASHBASE_WHITELIST += "FILESPATH USERNAME STAGING_DIR_HOST STAGING_DIR_TARGET"
+            </literallayout>
+            The previous example actually excludes
+            <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>
+            since it is actually constructed as a path within
+            <link linkend='var-TMPDIR'><filename>TMPDIR</filename></link>, which is on
+            the whitelist.
+        </para>
+
+        <para>
+            The rules for deciding which hashes of dependent tasks to include through
+            dependency chains are more complex and are generally accomplished with a
+            Python function.
+            The code in <filename>meta/lib/oe/sstatesig.py</filename> shows two examples
+            of this and also illustrates how you can insert your own policy into the system
+            if so desired.
+            This file defines the two basic signature generators <filename>OE-Core</filename>
+            uses:  "OEBasic" and "OEBasicHash".
+            By default, there is a dummy "noop" signature handler enabled in BitBake.
+            This means that behavior is unchanged from previous versions.
+            <filename>OE-Core</filename> uses the "OEBasicHash" signature handler by default
+            through this setting in the <filename>bitbake.conf</filename> file:
+            <literallayout class='monospaced'>
+  BB_SIGNATURE_HANDLER ?= "OEBasicHash"
+            </literallayout>
+            The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the
+            "OEBasic" version but adds the task hash to the stamp files.
+            This results in any
+            <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
+            change that changes the task hash, automatically
+            causing the task to be run again.
+            This removes the need to bump <link linkend='var-PR'><filename>PR</filename></link>
+            values and changes to Metadata automatically ripple across the build.
+        </para>
+
+        <para>
+            It is also worth noting that the end result of these signature generators is to
+            make some dependency and hash information available to the build.
+            This information includes:
+            <literallayout class='monospaced'>
+  BB_BASEHASH_task-&lt;taskname&gt; - the base hashes for each task in the recipe
+  BB_BASEHASH_&lt;filename:taskname&gt; - the base hashes for each dependent task
+  BBHASHDEPS_&lt;filename:taskname&gt; - The task dependencies for each task
+  BB_TASKHASH - the hash of the currently running task
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='shared-state'>
+        <title>Shared State</title>
+
+        <para>
+            Checksums and dependencies, as discussed in the previous section, solve half the
+            problem.
+            The other part of the problem is being able to use checksum information during the build
+            and being able to reuse or rebuild specific components.
+        </para>
+
+        <para>
+            The shared state class (<filename>sstate.bbclass</filename>)
+            is a relatively generic implementation of how to "capture" a snapshot of a given task.
+            The idea is that the build process does not care about the source of a task's output.
+            Output could be freshly built or it could be downloaded and unpacked from
+            somewhere - the build process does not need to worry about its source.
+        </para>
+
+        <para>
+            There are two types of output, one is just about creating a directory
+            in <link linkend='var-WORKDIR'><filename>WORKDIR</filename></link>.
+            A good example is the output of either <filename>do_install</filename> or
+            <filename>do_package</filename>.
+            The other type of output occurs when a set of data is merged into a shared directory
+            tree such as the sysroot.
+        </para>
+
+        <para>
+            The Yocto Project team has tried to keep the details of the implementation hidden in
+            <filename>sstate.bbclass</filename>.
+            From a user's perspective, adding shared state wrapping to a task
+            is as simple as this <filename>do_deploy</filename> example taken from
+            <filename>do_deploy.bbclass</filename>:
+            <literallayout class='monospaced'>
+     DEPLOYDIR = "${WORKDIR}/deploy-${PN}"
+     SSTATETASKS += "do_deploy"
+     do_deploy[sstate-name] = "deploy"
+     do_deploy[sstate-inputdirs] = "${DEPLOYDIR}"
+     do_deploy[sstate-outputdirs] = "${DEPLOY_DIR_IMAGE}"
+
+     python do_deploy_setscene () {
+         sstate_setscene(d)
+     }
+     addtask do_deploy_setscene
+            </literallayout>
+            In the example, we add some extra flags to the task, a name field ("deploy"), an
+            input directory where the task sends data, and the output
+            directory where the data from the task should eventually be copied.
+            We also add a <filename>_setscene</filename> variant of the task and add the task
+            name to the <filename>SSTATETASKS</filename> list.
+        </para>
+
+        <para>
+            If you have a directory whose contents you need to preserve, you can do this with
+            a line like the following:
+            <literallayout class='monospaced'>
+     do_package[sstate-plaindirs] = "${PKGD} ${PKGDEST}"
+            </literallayout>
+            This method, as well as the following example, also works for multiple directories.
+            <literallayout class='monospaced'>
+     do_package[sstate-inputdirs] = "${PKGDESTWORK} ${SHLIBSWORKDIR}"
+     do_package[sstate-outputdirs] = "${PKGDATA_DIR} ${SHLIBSDIR}"
+     do_package[sstate-lockfile] = "${PACKAGELOCK}"
+            </literallayout>
+            These methods also include the ability to take a lockfile when manipulating
+            shared state directory structures since some cases are sensitive to file
+            additions or removals.
+        </para>
+
+        <para>
+            Behind the scenes, the shared state code works by looking in
+            <link linkend='var-SSTATE_DIR'><filename>SSTATE_DIR</filename></link> and
+            <link linkend='var-SSTATE_MIRRORS'><filename>SSTATE_MIRRORS</filename></link>
+            for shared state files.
+            Here is an example:
+            <literallayout class='monospaced'>
+     SSTATE_MIRRORS ?= "\
+     file://.* http://someserver.tld/share/sstate/PATH \n \
+     file://.* file:///some/local/dir/sstate/PATH"
+            </literallayout>
+            <note>
+                The shared state directory (<filename>SSTATE_DIR</filename>) is
+                organized into two-character subdirectories, where the subdirectory
+                names are based on the first two characters of the hash.
+                If the shared state directory structure for a mirror has the
+                same structure as <filename>SSTATE_DIR</filename>, you must
+                specify "PATH" as part of the URI to enable the build system
+                to map to the appropriate subdirectory.
+            </note>
+        </para>
+
+        <para>
+            The shared state package validity can be detected just by looking at the
+            filename since the filename contains the task checksum (or signature) as
+            described earlier in this section.
+            If a valid shared state package is found, the build process downloads it
+            and uses it to accelerate the task.
+        </para>
+
+        <para>
+            The build processes use the <filename>*_setscene</filename> tasks
+            for the task acceleration phase.
+            BitBake goes through this phase before the main execution code and tries
+            to accelerate any tasks for which it can find shared state packages.
+            If a shared state package for a task is available, the shared state
+            package is used.
+            This means the task and any tasks on which it is dependent are not
+            executed.
+        </para>
+
+        <para>
+            As a real world example, the aim is when building an IPK-based image,
+            only the <filename>do_package_write_ipk</filename> tasks would have their
+            shared state packages fetched and extracted.
+            Since the sysroot is not used, it would never get extracted.
+            This is another reason why a task-based approach is preferred over a
+            recipe-based approach, which would have to install the output from every task.
+        </para>
+    </section>
+
+    <section id='tips-and-tricks'>
+        <title>Tips and Tricks</title>
+
+        <para>
+            The code in the build system that supports incremental builds is not
+            simple code.
+            This section presents some tips and tricks that help you work around
+            issues related to shared state code.
+        </para>
+
+        <section id='debugging'>
+            <title>Debugging</title>
+
+            <para>
+                When things go wrong, debugging needs to be straightforward.
+                Because of this, the Yocto Project team included strong debugging
+                tools:
+                <itemizedlist>
+                    <listitem><para>Whenever a shared state package is written out, so is a
+                        corresponding <filename>.siginfo</filename> file.
+                        This practice results in a pickled Python database of all
+                        the metadata that went into creating the hash for a given shared state
+                        package.</para></listitem>
+                    <listitem><para>If you run BitBake with the <filename>--dump-signatures</filename>
+                        (or <filename>-S</filename>) option, BitBake dumps out
+                        <filename>.siginfo</filename> files in
+                        the stamp directory for every task it would have executed instead of
+                        building the specified target package.</para></listitem>
+                    <listitem><para>There is a <filename>bitbake-diffsigs</filename> command that
+                        can process <filename>.siginfo</filename> files.
+                        If you specify one of these files, BitBake dumps out the dependency
+                        information in the file.
+                        If you specify two files, BitBake compares the two files and dumps out
+                        the differences between the two.
+                        This more easily helps answer the question of "What
+                        changed between X and Y?"</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id='invalidating-shared-state'>
+            <title>Invalidating Shared State</title>
+
+            <para>
+                The shared state code uses checksums and shared state
+                cache to avoid unnecessarily rebuilding tasks.
+                As with all schemes, this one has some drawbacks.
+                It is possible that you could make implicit changes that are not factored
+                into the checksum calculation, but do affect a task's output.
+                A good example is perhaps when a tool changes its output.
+                Assume that the output of <filename>rpmdeps</filename> needed to change.
+                The result of the change should be that all the
+                <filename>package</filename>, <filename>package_write_rpm</filename>,
+                and <filename>package_deploy-rpm</filename> shared state cache
+                items would become invalid.
+                But, because this is a change that is external to the code and therefore implicit,
+                the associated shared state cache items do not become invalidated.
+                In this case, the build process uses the cached items rather than running the
+                task again.
+                Obviously, these types of implicit changes can cause problems.
+            </para>
+
+            <para>
+                To avoid these problems during the build, you need to understand the effects of any
+                change you make.
+                Note that any changes you make directly to a function automatically are factored into
+                the checksum calculation and thus, will invalidate the associated area of sstate cache.
+                You need to be aware of any implicit changes that are not obvious changes to the
+                code and could affect the output of a given task.
+                Once you are aware of such changes, you can take steps to invalidate the cache
+                and force the tasks to run.
+                The steps to take are as simple as changing function's comments in the source code.
+                For example, to invalidate package shared state files, change the comment statements
+                of <filename>do_package</filename> or the comments of one of the functions it calls.
+                The change is purely cosmetic, but it causes the checksum to be recalculated and
+                forces the task to be run again.
+            </para>
+
+            <note>
+                For an example of a commit that makes a cosmetic change to invalidate
+                a shared state, see this
+                <ulink url='&YOCTO_GIT_URL;/cgit.cgi/poky/commit/meta/classes/package.bbclass?id=737f8bbb4f27b4837047cb9b4fbfe01dfde36d54'>commit</ulink>.
+            </note>
+        </section>
+    </section>
+</section>
+
+<section id='x32'>
+    <title>x32</title>
+
+    <para>
+        x32 is a processor-specific Application Binary Interface (psABI) for x86_64.
+        An ABI defines the calling conventions between functions in a processing environment.
+        The interface determines what registers are used and what the sizes are for various C data types.
+    </para>
+
+    <para>
+        Some processing environments prefer using 32-bit applications even when running
+        on Intel 64-bit platforms.
+        Consider the i386 psABI, which is a very old 32-bit ABI for Intel 64-bit platforms.
+        The i386 psABI does not provide efficient use and access of the Intel 64-bit processor resources,
+        leaving the system underutilized.
+        Now consider the x86_64 psABI.
+        This ABI is newer and uses 64-bits for data sizes and program pointers.
+        The extra bits increase the footprint size of the programs, libraries,
+        and also increases the memory and file system size requirements.
+        Executing under the x32 psABI enables user programs to utilize CPU and system resources
+        more efficiently while keeping the memory footprint of the applications low.
+        Extra bits are used for registers but not for addressing mechanisms.
+    </para>
+
+    <section id='support'>
+        <title>Support</title>
+
+        <para>
+            While the x32 psABI specifications are not fully finalized, this Yocto Project
+            release supports current development specifications of x32 psABI.
+            As of this release of the Yocto Project, x32 psABI support exists as follows:
+            <itemizedlist>
+                <listitem><para>You can create packages and images in x32 psABI format on x86_64 architecture targets.
+                    </para></listitem>
+                <listitem><para>You can successfully build many recipes with the x32 toolchain.</para></listitem>
+                <listitem><para>You can create and boot <filename>core-image-minimal</filename> and
+                    <filename>core-image-sato</filename> images.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='stabilizing-and-completing-x32'>
+        <title>Stabilizing and Completing x32</title>
+
+        <para>
+            As of this Yocto Project release, the x32 psABI kernel and library
+            interfaces specifications are not finalized.
+        </para>
+
+        <para>
+            Future Plans for the x32 psABI in the Yocto Project include the following:
+            <itemizedlist>
+                <listitem><para>Enhance and fix the few remaining recipes so they
+                    work with and support x32 toolchains.</para></listitem>
+                <listitem><para>Enhance RPM Package Manager (RPM) support for x32 binaries.</para></listitem>
+                <listitem><para>Support larger images.</para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='using-x32-right-now'>
+        <title>Using x32 Right Now</title>
+
+        <para>
+            Follow these steps to use the x32 spABI:
+            <itemizedlist>
+                <listitem><para>Enable the x32 psABI tuning file for <filename>x86_64</filename>
+                    machines by editing the <filename>conf/local.conf</filename> like this:
+                    <literallayout class='monospaced'>
+      MACHINE = "qemux86-64"
+      DEFAULTTUNE = "x86-64-x32"
+      baselib = "${@d.getVar('BASE_LIB_tune-' + (d.getVar('DEFAULTTUNE', True) \
+         or 'INVALID'), True) or 'lib'}"
+      #MACHINE = "genericx86"
+      #DEFAULTTUNE = "core2-64-x32"
+                    </literallayout></para></listitem>
+                <listitem><para>As usual, use BitBake to build an image that supports the x32 psABI.
+                    Here is an example:
+                    <literallayout class='monospaced'>
+     $ bitbake core-image-sato
+                    </literallayout></para></listitem>
+                <listitem><para>As usual, run your image using QEMU:
+                    <literallayout class='monospaced'>
+     $ runqemu qemux86-64 core-image-sato
+                    </literallayout></para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+
+<section id="wayland">
+    <title>Wayland</title>
+
+    <para>
+        <ulink url='http://en.wikipedia.org/wiki/Wayland_(display_server_protocol)#Weston'>Wayland</ulink>
+        is a computer display server protocol that when implemented
+        provides a method for compositing window managers to communicate
+        directly with applications and video hardware and expects them to
+        communicate with input hardware using other libraries.
+        Using Wayland with supporting targets can result in better control
+        over graphics frame rendering than an application might otherwise
+        achieve.
+    </para>
+
+    <para>
+        The Yocto Project provides the Wayland protocol libraries and the
+        reference Weston compositor as part of it release.
+        This section describes what you need to do to implement Wayland and
+        use the compositor when building an image for a supporting target.
+    </para>
+
+    <section id="wayland-support">
+        <title>Support</title>
+
+        <para>
+            The Wayland protocol libraries and the reference Weston compositor
+            ship as integrated packages in the <filename>meta</filename> layer
+            of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            Specifically, you can find the recipes that build both Wayland
+            and Weston at <filename>meta/recipes-graphics/wayland</filename>.
+        </para>
+
+        <para>
+            You can build both the Wayland and Weston packages for use only
+            with targets that accept the
+            <ulink url='http://dri.freedesktop.org/wiki/'>Mesa 3D and Direct Rendering Infrastructure</ulink>,
+            which is also known as Mesa DRI.
+            This implies that you cannot build and use the packages if your
+            target uses, for example, the
+            <trademark class='registered'>Intel</trademark> Embedded Media and
+            Graphics Driver (<trademark class='registered'>Intel</trademark>
+            EMGD) that overrides Mesa DRI.
+        </para>
+
+        <note>
+            Due to lack of EGL support, Weston 1.0.3 will not run directly on
+            the emulated QEMU hardware.
+            However, this version of Weston will run under X emulation without
+            issues.
+        </note>
+    </section>
+
+    <section id="enabling-wayland-in-an-image">
+        <title>Enabling Wayland in an Image</title>
+
+        <para>
+            To enable Wayland, you need to enable it to be built and enable
+            it to be included in the image.
+        </para>
+
+        <section id="enable-building">
+            <title>Building</title>
+
+            <para>
+                To cause Mesa to build the <filename>wayland-egl</filename>
+                platform and Weston to build Wayland with Kernel Mode
+                Setting
+                (<ulink url='https://wiki.archlinux.org/index.php/Kernel_Mode_Setting'>KMS</ulink>)
+                support, include the "wayland" flag in the
+                <link linkend="var-DISTRO_FEATURES"><filename>DISTRO_FEATURES</filename></link>
+                statement in your <filename>local.conf</filename> file:
+                <literallayout class='monospaced'>
+     DISTRO_FEATURES_append = " wayland"
+                </literallayout>
+            </para>
+
+            <note>
+                If X11 has been enabled elsewhere, Weston will build Wayland
+                with X11 support
+            </note>
+        </section>
+
+        <section id="enable-installation-in-an-image">
+            <title>Installing</title>
+
+            <para>
+                To install the Wayland feature into an image, you must
+                include the following
+                <link linkend='var-CORE_IMAGE_EXTRA_INSTALL'><filename>CORE_IMAGE_EXTRA_INSTALL</filename></link>
+                statement in your <filename>local.conf</filename> file:
+                <literallayout class='monospaced'>
+     CORE_IMAGE_EXTRA_INSTALL += "wayland weston"
+                </literallayout>
+            </para>
+        </section>
+    </section>
+
+    <section id="running-weston">
+        <title>Running Weston</title>
+
+        <para>
+            To run Weston inside X11, enabling it as described earlier and
+            building a Sato image is sufficient.
+            If you are running your image under Sato, a Weston Launcher appears
+            in the "Utility" category.
+        </para>
+
+        <para>
+            Alternatively, you can run Weston through the command-line
+            interpretor (CLI), which is better suited for development work.
+            To run Weston under the CLI you need to do the following after
+            your image is built:
+            <orderedlist>
+                <listitem><para>Run these commands to export
+                    <filename>XDG_RUNTIME_DIR</filename>:
+                    <literallayout class='monospaced'>
+     mkdir -p /tmp/$USER-weston
+     chmod 0700 /tmp/$USER-weston
+     export XDG_RUNTIME_DIR=/tmp/$USER=weston
+                    </literallayout></para></listitem>
+                <listitem><para>Launch Weston in the shell:
+                    <literallayout class='monospaced'>
+     weston
+                    </literallayout></para></listitem>
+            </orderedlist>
+        </para>
+    </section>
+</section>
+
+<section id="licenses">
+    <title>Licenses</title>
+
+    <para>
+        This section describes the mechanism by which the OpenEmbedded build system
+        tracks changes to licensing text.
+        The section also describes how to enable commercially licensed recipes,
+        which by default are disabled.
+    </para>
+
+    <para>
+        For information that can help you maintain compliance with various open
+        source licensing during the lifecycle of the product, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#maintaining-open-source-license-compliance-during-your-products-lifecycle'>Maintaining Open Source License Compliance During Your Project's Lifecycle</ulink>" section
+        in the Yocto Project Development Manual.
+    </para>
+
+    <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
+        <title>Tracking License Changes</title>
+
+        <para>
+            The license of an upstream project might change in the future.
+            In order to prevent these changes going unnoticed, the
+            <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
+            variable tracks changes to the license text. The checksums are validated at the end of the
+            configure step, and if the checksums do not match, the build will fail.
+        </para>
+
+        <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
+            <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
+
+            <para>
+                The <filename>LIC_FILES_CHKSUM</filename>
+                variable contains checksums of the license text in the source code for the recipe.
+                Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
+                <literallayout class='monospaced'>
+     LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
+                         file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
+                         file://licfile2.txt;endline=50;md5=zzzz \
+                         ..."
+                </literallayout>
+            </para>
+
+            <para>
+                The build system uses the
+                <filename><link linkend='var-S'>S</link></filename> variable as
+                the default directory used when searching files listed in
+                <filename>LIC_FILES_CHKSUM</filename>.
+                The previous example employs the default directory.
+            </para>
+
+            <para>
+                Consider this next example:
+                <literallayout class='monospaced'>
+     LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\
+                                         md5=bb14ed3c4cda583abc85401304b5cd4e"
+     LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
+                </literallayout>
+            </para>
+
+            <para>
+                The first line locates a file in
+                <filename>${S}/src/ls.c</filename>.
+                The second line refers to a file in
+                <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>.
+            </para>
+            <para>
+                Note that <filename>LIC_FILES_CHKSUM</filename> variable is
+                mandatory for all recipes, unless the
+                <filename>LICENSE</filename> variable is set to "CLOSED".
+            </para>
+        </section>
+
+        <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
+            <title>Explanation of Syntax</title>
+            <para>
+                As mentioned in the previous section, the
+                <filename>LIC_FILES_CHKSUM</filename> variable lists all the
+                important files that contain the license text for the source code.
+                It is possible to specify a checksum for an entire file, or a specific section of a
+                file (specified by beginning and ending line numbers with the "beginline" and "endline"
+                parameters, respectively).
+                The latter is useful for source files with a license notice header,
+                README documents, and so forth.
+                If you do not use the "beginline" parameter, then it is assumed that the text begins on the
+                first line of the file.
+                Similarly, if you do not use the "endline" parameter, it is assumed that the license text
+                ends with the last line of the file.
+            </para>
+
+            <para>
+                The "md5" parameter stores the md5 checksum of the license text.
+                If the license text changes in any way as compared to this parameter
+                then a mismatch occurs.
+                This mismatch triggers a build failure and notifies the developer.
+                Notification allows the developer to review and address the license text changes.
+                Also note that if a mismatch occurs during the build, the correct md5
+                checksum is placed in the build log and can be easily copied to the recipe.
+            </para>
+
+            <para>
+                There is no limit to how many files you can specify using the
+                <filename>LIC_FILES_CHKSUM</filename> variable.
+                Generally, however, every project requires a few specifications for license tracking.
+                Many projects have a "COPYING" file that stores the license information for all the source
+                code files.
+                This practice allows you to just track the "COPYING" file as long as it is kept up to date.
+            </para>
+
+            <tip>
+                If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
+                error and displays the correct "md5" parameter value during the build.
+                The correct parameter is also captured in the build log.
+            </tip>
+
+            <tip>
+                If the whole file contains only license text, you do not need to use the "beginline" and
+                "endline" parameters.
+            </tip>
+        </section>
+    </section>
+
+    <section id="enabling-commercially-licensed-recipes">
+        <title>Enabling Commercially Licensed Recipes</title>
+
+        <para>
+            By default, the OpenEmbedded build system disables
+            components that have commercial or other special licensing
+            requirements.
+            Such requirements are defined on a
+            recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
+            definition in the affected recipe.
+            For instance, the
+            <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+            recipe contains the following statement:
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS = "commercial"
+            </literallayout>
+            Here is a slightly more complicated example that contains both an
+            explicit recipe name and version (after variable expansion):
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS = "license_${PN}_${PV}"
+            </literallayout>
+                In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
+                definition to be enabled and included in an image, it
+                needs to have a matching entry in the global
+                <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
+                typically defined in your <filename>local.conf</filename> file.
+            For example, to enable
+                the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
+                package, you could add either the string
+                "commercial_gst-plugins-ugly" or the more general string
+                "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
+            See the
+            "<link linkend='license-flag-matching'>License Flag Matching</link>" section
+            for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
+            Here is the example:
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
+            </literallayout>
+                Likewise, to additionally enable the package built from the recipe containing
+                <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
+                that the actual recipe name was <filename>emgd_1.10.bb</filename>,
+                the following string would enable that package as well as
+                the original <filename>gst-plugins-ugly</filename> package:
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
+            </literallayout>
+                As a convenience, you do not need to specify the complete license string
+                in the whitelist for every package.
+            you can use an abbreviated form, which consists
+                of just the first portion or portions of the license string before
+                the initial underscore character or characters.
+            A partial string will match
+                any license that contains the given string as the first
+                portion of its license.
+            For example, the following
+                whitelist string will also match both of the packages
+                previously mentioned as well as any other packages that have
+                licenses starting with "commercial" or "license".
+            <literallayout class='monospaced'>
+     LICENSE_FLAGS_WHITELIST = "commercial license"
+            </literallayout>
+        </para>
+
+        <section id="license-flag-matching">
+            <title>License Flag Matching</title>
+
+            <para>
+                        License flag matching allows you to control what recipes the
+                OpenEmbedded build system includes in the build.
+                Fundamentally, the build system attempts to match
+                <filename>LICENSE_FLAG</filename> strings found in
+                recipes against <filename>LICENSE_FLAGS_WHITELIST</filename>
+                strings found in the whitelist.
+                A match, causes the build system to include a recipe in the
+                build, while failure to find a match causes the build system to
+                exclude a recipe.
+            </para>
+
+            <para>
+                In general, license flag matching is simple.
+                However, understanding some concepts will help you
+                correctly and effectively use matching.
+            </para>
+
+            <para>
+                Before a flag
+                defined by a particular recipe is tested against the
+                contents of the whitelist, the expanded string
+                <filename>_${PN}</filename> is appended to the flag.
+                This expansion makes each <filename>LICENSE_FLAGS</filename>
+                value recipe-specific.
+                After expansion, the string is then matched against the
+                whitelist.
+                Thus, specifying
+                <filename>LICENSE_FLAGS = "commercial"</filename>
+                in recipe "foo", for example, results in the string
+                <filename>"commercial_foo"</filename>.
+                And, to create a match, that string must appear in the
+                whitelist.
+            </para>
+
+            <para>
+                Judicious use of the <filename>LICENSE_FLAGS</filename>
+                strings and the contents of the
+                <filename>LICENSE_FLAGS_WHITELIST</filename> variable
+                allows you a lot of flexibility for including or excluding
+                recipes based on licensing.
+                For example, you can broaden the matching capabilities by
+                using license flags string subsets in the whitelist.
+                <note>When using a string subset, be sure to use the part of
+                    the expanded string that precedes the appended underscore
+                    character (e.g. <filename>usethispart_1.3</filename>,
+                    <filename>usethispart_1.4</filename>, and so forth).
+                </note>
+                For example, simply specifying the string "commercial" in
+                the whitelist matches any expanded
+                <filename>LICENSE_FLAGS</filename> definition that starts with
+                the string "commercial" such as "commercial_foo" and
+                "commercial_bar", which are the strings the build system
+                automatically generates for hypothetical recipes named
+                "foo" and "bar" assuming those recipes simply specify the
+                following:
+                <literallayout class='monospaced'>
+     LICENSE_FLAGS = "commercial"
+                </literallayout>
+                Thus, you can choose to exhaustively
+                enumerate each license flag in the whitelist and
+                allow only specific recipes into the image, or
+                you can use a string subset that causes a broader range of
+                matches to allow a range of recipes into the image.
+            </para>
+
+            <para>
+                This scheme works even if the
+                <filename>LICENSE_FLAG</filename> string already
+                has <filename>_${PN}</filename> appended.
+                For example, the build system turns the license flag
+                "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would
+                match both the general "commercial" and the specific
+                "commercial_1.2_foo" strings found in the whitelist, as
+                expected.
+            </para>
+
+            <para>
+                Here are some other scenarios:
+                <itemizedlist>
+                    <listitem><para>You can specify a versioned string in the
+                        recipe such as "commercial_foo_1.2" in a "foo" recipe.
+                        The build system expands this string to
+                        "commercial_foo_1.2_foo".
+                        Combine this license flag with a whitelist that has
+                        the string "commercial" and you match the flag along
+                        with any other flag that starts with the string
+                        "commercial".</para></listitem>
+                    <listitem><para>Under the same circumstances, you can
+                        use "commercial_foo" in the whitelist and the
+                        build system not only matches "commercial_foo_1.2" but
+                        also matches any license flag with the string
+                        "commercial_foo", regardless of the version.
+                        </para></listitem>
+                    <listitem><para>You can be very specific and use both the
+                        package and version parts in the whitelist (e.g.
+                        "commercial_foo_1.2") to specifically match a
+                        versioned recipe.</para></listitem>
+                </itemizedlist>
+            </para>
+        </section>
+
+        <section id="other-variables-related-to-commercial-licenses">
+            <title>Other Variables Related to Commercial Licenses</title>
+
+            <para>
+                Other helpful variables related to commercial
+                license handling exist and are defined in the
+                <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
+                <literallayout class='monospaced'>
+     COMMERCIAL_AUDIO_PLUGINS ?= ""
+     COMMERCIAL_VIDEO_PLUGINS ?= ""
+     COMMERCIAL_QT = ""
+                </literallayout>
+                If you want to enable these components, you can do so by making sure you have
+                statements similar to the following
+                in your <filename>local.conf</filename> configuration file:
+                <literallayout class='monospaced'>
+     COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
+        gst-plugins-ugly-mpegaudioparse"
+     COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
+        gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
+     COMMERCIAL_QT ?= "qmmp"
+     LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
+                </literallayout>
+                Of course, you could also create a matching whitelist
+                for those components using the more general "commercial"
+                in the whitelist, but that would also enable all the
+                other packages with <filename>LICENSE_FLAGS</filename> containing
+                "commercial", which you may or may not want:
+                <literallayout class='monospaced'>
+     LICENSE_FLAGS_WHITELIST = "commercial"
+                </literallayout>
+            </para>
+
+            <para>
+                Specifying audio and video plug-ins as part of the
+                <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
+                <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
+                or commercial Qt components as part of
+                the <filename>COMMERCIAL_QT</filename> statement (along
+                with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
+                plug-ins or components into built images, thus adding
+                support for media formats or components.
+            </para>
+        </section>
+    </section>
+</section>
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
new file mode 100644
index 0000000000..b00e7bc14e
--- /dev/null
+++ b/documentation/ref-manual/usingpoky.xml
@@ -0,0 +1,848 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<chapter id='usingpoky'>
+<title>Using the Yocto Project</title>
+
+    <para>
+        This chapter describes common usage for the Yocto Project.
+        The information is introductory in nature as other manuals in the Yocto Project
+        documentation set provide more details on how to use the Yocto Project.
+    </para>
+
+<section id='usingpoky-build'>
+    <title>Running a Build</title>
+
+    <para>
+        This section provides a summary of the build process and provides information
+        for less obvious aspects of the build process.
+        For general information on how to build an image using the OpenEmbedded build
+        system, see the
+        "<ulink url='&YOCTO_DOCS_QS_URL;#building-image'>Building an Image</ulink>"
+        section of the Yocto Project Quick Start.
+    </para>
+
+    <section id='build-overview'>
+        <title>Build Overview</title>
+
+        <para>
+            The first thing you need to do is set up the OpenEmbedded build
+            environment by sourcing an environment setup script
+            (i.e.
+            <link linkend='structure-core-script'><filename>&OE_INIT_FILE;</filename></link>
+            or
+            <link linkend='structure-memres-core-script'><filename>oe-init-build-env-memres</filename></link>).
+            Here is an example:
+            <literallayout class='monospaced'>
+     $ source &OE_INIT_FILE; [&lt;build_dir&gt;]
+            </literallayout>
+        </para>
+
+        <para>
+            The <filename>build_dir</filename> is optional and specifies the directory the
+            OpenEmbedded build system uses for the build -
+            the <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>.
+            If you do not specify a Build Directory, it defaults to a directory
+            named <filename>build</filename> in your current working directory.
+            A common practice is to use a different Build Directory for different targets.
+            For example, <filename>~/build/x86</filename> for a <filename>qemux86</filename>
+            target, and <filename>~/build/arm</filename> for a <filename>qemuarm</filename> target.
+            See the "<link linkend="structure-core-script"><filename>&OE_INIT_FILE;</filename></link>"
+            section for more information on this script.
+        </para>
+
+        <para>
+            Once the build environment is set up, you can build a target using:
+            <literallayout class='monospaced'>
+     $ bitbake &lt;target&gt;
+            </literallayout>
+        </para>
+
+        <para>
+            The <filename>target</filename> is the name of the recipe you want to build.
+            Common targets are the images in <filename>meta/recipes-core/images</filename>,
+            <filename>/meta/recipes-sato/images</filename>, etc. all found in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+            Or, the target can be the name of a recipe for a specific piece of software such as
+            BusyBox.
+            For more details about the images the OpenEmbedded build system supports, see the
+            "<link linkend="ref-images">Images</link>" chapter.
+        </para>
+
+        <note>
+            Building an image without GNU General Public License Version 3 (GPLv3) components
+            is only supported for minimal and base images.
+            See the "<link linkend='ref-images'>Images</link>" chapter for more information.
+        </note>
+    </section>
+
+    <section id='building-an-image-using-gpl-components'>
+        <title>Building an Image Using GPL Components</title>
+
+        <para>
+            When building an image using GPL components, you need to maintain your original
+            settings and not switch back and forth applying different versions of the GNU
+            General Public License.
+            If you rebuild using different versions of GPL, dependency errors might occur
+            due to some components not being rebuilt.
+        </para>
+    </section>
+</section>
+
+<section id='usingpoky-install'>
+    <title>Installing and Using the Result</title>
+
+    <para>
+        Once an image has been built, it often needs to be installed.
+        The images and kernels built by the OpenEmbedded build system are placed in the
+        <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink> in
+        <filename class="directory">tmp/deploy/images</filename>.
+        For information on how to run pre-built images such as <filename>qemux86</filename>
+        and <filename>qemuarm</filename>, see the
+        "<ulink url='&YOCTO_DOCS_QS_URL;#using-pre-built'>Using Pre-Built Binaries and QEMU</ulink>"
+        section in the Yocto Project Quick Start.
+        For information about how to install these images, see the documentation for your
+        particular board or machine.
+    </para>
+</section>
+
+<section id='usingpoky-debugging'>
+    <title>Debugging Build Failures</title>
+
+    <para>
+        The exact method for debugging build failures depends on the nature of the
+        problem and on the system's area from which the bug originates.
+        Standard debugging practices such as comparison against the last
+        known working version with examination of the changes and the re-application of steps
+        to identify the one causing the problem are
+        valid for the Yocto Project just as they are for any other system.
+        Even though it is impossible to detail every possible potential failure,
+        this section provides some general tips to aid in debugging.
+    </para>
+
+    <para>
+        For discussions on debugging, see the
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#platdev-gdb-remotedebug'>Debugging With the GNU Project Debugger (GDB) Remotely</ulink>"
+        and
+        "<ulink url='&YOCTO_DOCS_DEV_URL;#adt-eclipse'>Working within Eclipse</ulink>"
+        sections in the Yocto Project Development Manual.
+    </para>
+
+    <section id='usingpoky-debugging-taskfailures'>
+        <title>Task Failures</title>
+
+        <para>The log file for shell tasks is available in
+            <filename>${WORKDIR}/temp/log.do_taskname.pid</filename>.
+            For example, the <filename>compile</filename> task for the QEMU minimal image for the x86
+            machine (<filename>qemux86</filename>) might be
+            <filename>tmp/work/qemux86-poky-linux/core-image-minimal/1.0-r0/temp/log.do_compile.20830</filename>.
+            To see what BitBake runs to generate that log, look at the corresponding
+            <filename>run.do_taskname.pid</filename> file located in the same directory.
+        </para>
+
+        <para>
+            Presently, the output from Python tasks is sent directly to the console.
+        </para>
+    </section>
+
+    <section id='usingpoky-debugging-taskrunning'>
+        <title>Running Specific Tasks</title>
+
+        <para>
+            Any given package consists of a set of tasks.
+            The standard BitBake behavior in most cases is: <filename>fetch</filename>,
+            <filename>unpack</filename>,
+            <filename>patch</filename>, <filename>configure</filename>,
+            <filename>compile</filename>, <filename>install</filename>, <filename>package</filename>,
+            <filename>package_write</filename>, and <filename>build</filename>.
+            The default task is <filename>build</filename> and any tasks on which it depends
+            build first.
+            Some tasks exist, such as <filename>devshell</filename>, that are not part of the
+            default build chain.
+            If you wish to run a task that is not part of the default build chain, you can use the
+            <filename>-c</filename> option in BitBake.
+            Here is an example:
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c devshell
+            </literallayout>
+        </para>
+
+        <para>
+            If you wish to rerun a task, use the <filename>-f</filename> force option.
+            For example, the following sequence forces recompilation after changing files in the
+            working directory.
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop
+               .
+               .
+        [make some changes to the source code in the working directory]
+               .
+               .
+     $ bitbake matchbox-desktop -c compile -f
+     $ bitbake matchbox-desktop
+            </literallayout>
+        </para>
+
+        <para>
+            This sequence first builds and then recompiles
+            <filename>matchbox-desktop</filename>.
+            The last command reruns all tasks (basically the packaging tasks) after the compile.
+            BitBake recognizes that the <filename>compile</filename> task was rerun and therefore
+            understands that the other tasks also need to be run again.
+        </para>
+
+        <para>
+            You can view a list of tasks in a given package by running the
+            <filename>listtasks</filename> task as follows:
+            <literallayout class='monospaced'>
+     $ bitbake matchbox-desktop -c listtasks
+            </literallayout>
+            The results are in the file <filename>${WORKDIR}/temp/log.do_listtasks</filename>.
+        </para>
+    </section>
+
+    <section id='usingpoky-debugging-dependencies'>
+        <title>Dependency Graphs</title>
+
+        <para>
+            Sometimes it can be hard to see why BitBake wants to build some other packages before a given
+            package you have specified.
+            The <filename>bitbake -g targetname</filename> command creates the
+            <filename>depends.dot</filename>, <filename>package-depends.dot</filename>,
+            and <filename>task-depends.dot</filename> files in the current directory.
+            These files show the package and task dependencies and are useful for debugging problems.
+            You can use the <filename>bitbake -g -u depexp targetname</filename> command to
+            display the results in a more human-readable form.
+        </para>
+    </section>
+
+    <section id='usingpoky-debugging-bitbake'>
+        <title>General BitBake Problems</title>
+
+        <para>
+            You can see debug output from BitBake by using the <filename>-D</filename> option.
+            The debug output gives more information about what BitBake
+            is doing and the reason behind it.
+            Each <filename>-D</filename> option you use increases the logging level.
+            The most common usage is <filename>-DDD</filename>.
+        </para>
+
+        <para>
+            The output from <filename>bitbake -DDD -v targetname</filename> can reveal why
+            BitBake chose a certain version of a package or why BitBake
+            picked a certain provider.
+            This command could also help you in a situation where you think BitBake did something
+            unexpected.
+        </para>
+    </section>
+
+    <section id='development-host-system-issues'>
+        <title>Development Host System Issues</title>
+
+        <para>
+            Sometimes issues on the host development system can cause your
+            build to fail.
+            Following are known, host-specific problems.
+            Be sure to always consult the
+            <ulink url='&YOCTO_RELEASE_NOTES;'>Release Notes</ulink>
+            for a look at all release-related issues.
+            <itemizedlist>
+                <listitem><para><emphasis><filename>eglibc-initial</filename> fails to build</emphasis>:
+                    If your development host system has the unpatched
+                    <filename>GNU Make 3.82</filename>,
+                    the <filename>do_install</filename> task
+                    fails for <filename>eglibc-initial</filename> during the
+                    build.</para>
+                    <para>Typically, every distribution that ships
+                    <filename>GNU Make 3.82</filename> as
+                    the default already has the patched version.
+                    However, some distributions, such as Debian, have
+                    <filename>GNU Make 3.82</filename> as an option, which
+                    is unpatched.
+                    You will see this error on these types of distributions.
+                    Switch to <filename>GNU Make 3.81</filename> or patch
+                    your <filename>make</filename> to solve the problem.
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+
+    <section id='usingpoky-debugging-buildfile'>
+        <title>Building with No Dependencies</title>
+        <para>
+            If you really want to build a specific <filename>.bb</filename> file, you can use
+            the command form <filename>bitbake -b &lt;somepath/somefile.bb&gt;</filename>.
+            This command form does not check for dependencies so you should use it
+            only when you know its dependencies already exist.
+            You can also specify fragments of the filename.
+            In this case, BitBake checks for a unique match.
+        </para>
+    </section>
+
+    <section id='usingpoky-debugging-variables'>
+        <title>Variables</title>
+        <para>
+            You can use the <filename>-e</filename> BitBake option to
+            display the resulting environment for a configuration
+            when you do not specify a package or for a specific package when
+            you do specify the package.
+            If you want to show the environment resulting from parsing a single
+            recipe, use the <filename>-b recipename</filename> form.
+        </para>
+    </section>
+
+    <section id='recipe-logging-mechanisms'>
+        <title>Recipe Logging Mechanisms</title>
+        <para>
+            Best practices exist while writing recipes that both log build progress and
+            act on build conditions such as warnings and errors.
+            Both Python and Bash language bindings exist for the logging mechanism:
+            <itemizedlist>
+                <listitem><para><emphasis>Python:</emphasis> For Python functions, BitBake
+                    supports several loglevels: <filename>bb.fatal</filename>,
+                    <filename>bb.error</filename>, <filename>bb.warn</filename>,
+                    <filename>bb.note</filename>, <filename>bb.plain</filename>,
+                    and <filename>bb.debug</filename>.</para></listitem>
+                <listitem><para><emphasis>Bash:</emphasis> For Bash functions, the same set
+                    of loglevels exist and are accessed with a similar syntax:
+                    <filename>bbfatal</filename>, <filename>bberror</filename>,
+                    <filename>bbwarn</filename>, <filename>bbnote</filename>,
+                    <filename>bbplain</filename>, and <filename>bbdebug</filename>.</para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            For guidance on how logging is handled in both Python and Bash recipes, see the
+            <filename>logging.bbclass</filename> file in the
+            <filename>meta/classes</filename> folder of the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>.
+        </para>
+
+        <section id='logging-with-python'>
+            <title>Logging With Python</title>
+            <para>
+                When creating recipes using Python and inserting code that handles build logs,
+                keep in mind the goal is to have informative logs while keeping the console as
+                "silent" as possible.
+                Also, if you want status messages in the log, use the "debug" loglevel.
+            </para>
+
+            <para>
+                Following is an example written in Python.
+                The code handles logging for a function that determines the number of tasks
+                needed to be run:
+                <literallayout class='monospaced'>
+     python do_listtasks() {
+         bb.debug(2, "Starting to figure out the task list")
+         if noteworthy_condition:
+             bb.note("There are 47 tasks to run")
+         bb.debug(2, "Got to point xyz")
+         if warning_trigger:
+             bb.warn("Detected warning_trigger, this might be a problem later.")
+         if recoverable_error:
+             bb.error("Hit recoverable_error, you really need to fix this!")
+         if fatal_error:
+             bb.fatal("fatal_error detected, unable to print the task list")
+         bb.plain("The tasks present are abc")
+         bb.debug(2, "Finished figuring out the tasklist")
+     }
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='logging-with-bash'>
+            <title>Logging With Bash</title>
+            <para>
+                When creating recipes using Bash and inserting code that handles build
+                logs, you have the same goals - informative with minimal console output.
+                The syntax you use for recipes written in Bash is similar to that of
+                recipes written in Python described in the previous section.
+            </para>
+
+            <para>
+                Following is an example written in Bash.
+                The code logs the progress of the <filename>do_my_function</filename> function.
+                <literallayout class='monospaced'>
+     do_my_function() {
+         bbdebug 2 "Running do_my_function"
+         if [ exceptional_condition ]; then
+             bbnote "Hit exceptional_condition"
+         fi
+         bbdebug 2  "Got to point xyz"
+         if [ warning_trigger ]; then
+             bbwarn "Detected warning_trigger, this might cause a problem later."
+         fi
+         if [ recoverable_error ]; then
+             bberror "Hit recoverable_error, correcting"
+         fi
+         if [ fatal_error ]; then
+             bbfatal "fatal_error detected"
+         fi
+         bbdebug 2 "Completed do_my_function"
+     }
+                </literallayout>
+            </para>
+        </section>
+    </section>
+
+    <section id='usingpoky-debugging-others'>
+        <title>Other Tips</title>
+
+        <para>
+            Here are some other tips that you might find useful:
+            <itemizedlist>
+                <listitem><para>When adding new packages, it is worth watching for
+                    undesirable items making their way into compiler command lines.
+                    For example, you do not want references to local system files like
+                    <filename>/usr/lib/</filename> or <filename>/usr/include/</filename>.
+                    </para></listitem>
+                <listitem><para>If you want to remove the <filename>psplash</filename>
+                    boot splashscreen,
+                    add <filename>psplash=false</filename> to  the kernel command line.
+                    Doing so prevents <filename>psplash</filename> from loading
+                    and thus allows you to see the console.
+                    It is also possible to switch out of the splashscreen by
+                    switching the virtual console (e.g. Fn+Left or Fn+Right on a Zaurus).
+                    </para></listitem>
+            </itemizedlist>
+        </para>
+    </section>
+</section>
+
+<section id='maintaining-build-output-quality'>
+    <title>Maintaining Build Output Quality</title>
+
+    <para>
+        Many factors can influence the quality of a build.
+        For example, if you upgrade a recipe to use a new version of an upstream software
+        package or you experiment with some new configuration options, subtle changes
+        can occur that you might not detect until later.
+        Consider the case where your recipe is using a newer version of an upstream package.
+        In this case, a new version of a piece of software might introduce an optional
+        dependency on another library, which is auto-detected.
+        If that library has already been built when the software is building,
+        the software will link to the built library and that library will be pulled
+        into your image along with the new software even if you did not want the
+        library.
+    </para>
+
+    <para>
+        The <filename>buildhistory</filename> class exists to help you maintain
+        the quality of your build output.
+        You can use the class to highlight unexpected and possibly unwanted
+        changes in the build output.
+        When you enable build history, it records information about the contents of
+        each package and image and then commits that information to a local Git
+        repository where you can examine the information.
+    </para>
+
+    <para>
+        The remainder of this section describes the following:
+        <itemizedlist>
+           <listitem><para>How you can enable and disable
+               build history</para></listitem>
+           <listitem><para>How to understand what the build history contains
+               </para></listitem>
+           <listitem><para>How to limit the information used for build history
+               </para></listitem>
+           <listitem><para>How to examine the build history from both a
+               command-line and web interface</para></listitem>
+       </itemizedlist>
+    </para>
+
+    <section id='enabling-and-disabling-build-history'>
+        <title>Enabling and Disabling Build History</title>
+
+        <para>
+            Build history is disabled by default.
+            To enable it, add the following statements to the end of your
+            <filename>conf/local.conf</filename> file found in the
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+            <literallayout class='monospaced'>
+     INHERIT += "buildhistory"
+     BUILDHISTORY_COMMIT = "1"
+            </literallayout>
+            Enabling build history as previously described
+            causes the build process to collect build
+            output information and commit it to a local
+            <ulink url='&YOCTO_DOCS_DEV_URL;#git'>Git</ulink> repository.
+            <note>
+                Enabling build history increases your build times slightly,
+                particularly for images, and increases the amount of disk
+                space used during the build.
+            </note>
+        </para>
+
+        <para>
+            You can disable build history by removing the previous statements
+            from your <filename>conf/local.conf</filename> file.
+            However, you should realize that enabling and disabling
+            build history in this manner can change the
+            <filename>do_package</filename> task checksums, which if you
+            are using the OEBasicHash signature generator (the default
+            for many current distro configurations including
+            <filename>DISTRO = "poky"</filename> and
+            <filename>DISTRO = ""</filename>) and will result in the packaging
+            tasks being re-run during the subsequent build.
+        </para>
+
+        <para>
+            To disable the build history functionality without causing the
+            packaging tasks to be re-run, add this statement to your
+            <filename>conf/local.conf</filename> file:
+            <literallayout class='monospaced'>
+     BUILDHISTORY_FEATURES = ""
+            </literallayout>
+        </para>
+    </section>
+
+    <section id='understanding-what-the-build-history-contains'>
+        <title>Understanding What the Build History Contains</title>
+
+        <para>
+            Build history information is kept in
+            <filename>$</filename><link linkend='var-TMPDIR'><filename>TMPDIR</filename></link><filename>/buildhistory</filename>
+            in the Build Directory.
+            The following is an example abbreviated listing:
+            <imagedata fileref="figures/buildhistory.png" align="center" width="6in" depth="4in" />
+        </para>
+
+        <para>
+            At the top level, there is a <filename>metadata-revs</filename> file
+            that lists the revisions of the repositories for the layers enabled
+            when the build was produced.
+            The rest of the data splits into separate
+            <filename>packages</filename>, <filename>images</filename> and
+            <filename>sdk</filename> directories, the contents of which are
+            described below.
+        </para>
+
+        <section id='build-history-package-information'>
+            <title>Build History Package Information</title>
+
+            <para>
+                The history for each package contains a text file that has
+                name-value pairs with information about the package.
+                For example, <filename>buildhistory/packages/core2-poky-linux/busybox/busybox/latest</filename>
+                contains the following:
+                <literallayout class='monospaced'>
+     PV = 1.19.3
+     PR = r3
+     RDEPENDS = update-rc.d eglibc (>= 2.13)
+     RRECOMMENDS = busybox-syslog busybox-udhcpc
+     PKGSIZE = 564701
+     FILES = /usr/bin/* /usr/sbin/* /usr/libexec/* /usr/lib/lib*.so.* \
+        /etc /com /var /bin/* /sbin/* /lib/*.so.* /usr/share/busybox \
+        /usr/lib/busybox/* /usr/share/pixmaps /usr/share/applications \
+        /usr/share/idl /usr/share/omf /usr/share/sounds /usr/lib/bonobo/servers
+     FILELIST = /etc/busybox.links /etc/init.d/hwclock.sh /bin/busybox /bin/sh
+                </literallayout>
+                Most of these name-value pairs correspond to variables used
+                to produce the package.
+                The exceptions are <filename>FILELIST</filename>, which is the
+                actual list of files in the package, and
+                <filename>PKGSIZE</filename>, which is the total size of files
+                in the package in bytes.
+            </para>
+
+            <para>
+                There is also a file corresponding to the recipe from which the
+                package came (e.g.
+                <filename>buildhistory/packages/core2-poky-linux/busybox/latest</filename>):
+                <literallayout class='monospaced'>
+     PV = 1.19.3
+     PR = r3
+     DEPENDS = virtual/i586-poky-linux-gcc virtual/i586-poky-linux-compilerlibs \
+        virtual/libc update-rc.d-native
+     PACKAGES = busybox-httpd busybox-udhcpd busybox-udhcpc busybox-syslog \
+        busybox-mdev busybox-dbg busybox busybox-doc busybox-dev \
+        busybox-staticdev busybox-locale
+                </literallayout>
+            </para>
+
+            <para>
+                Finally, for those recipes fetched from a version control
+                system (e.g., Git), a file exists that lists source revisions
+                that are specified in the recipe and lists the actual revisions
+                used during the build.
+                Listed and actual revisions might differ when
+                <link linkend='var-SRCREV'><filename>SRCREV</filename></link>
+                is set to
+                <filename>${<link linkend='var-AUTOREV'>AUTOREV</link>}</filename>.
+                Here is an example assuming
+                <filename>buildhistory/packages/emenlow-poky-linux/linux-yocto/latest_srcrev</filename>):
+                <literallayout class='monospaced'>
+     # SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
+     SRCREV_machine = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
+     # SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
+     SRCREV_emgd = "caea08c988e0f41103bbe18eafca20348f95da02"
+     # SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
+     SRCREV_meta = "c2ed0f16fdec628242a682897d5d86df4547cf24"
+                </literallayout>
+                You can use the <filename>buildhistory-collect-srcrevs</filename>
+                command to collect the stored <filename>SRCREV</filename> values
+                from build history and report them in a format suitable for use in
+                global configuration (e.g., <filename>local.conf</filename>
+                or a distro include file) to override floating
+                <filename>AUTOREV</filename> values to a fixed set of revisions.
+                Here is some example output from this command:
+                <literallayout class='monospaced'>
+     # emenlow-poky-linux
+     SRCREV_machine_pn-linux-yocto = "b5c37fe6e24eec194bb29d22fdd55d73bcc709bf"
+     SRCREV_emgd_pn-linux-yocto = "caea08c988e0f41103bbe18eafca20348f95da02"
+     SRCREV_meta_pn-linux-yocto = "c2ed0f16fdec628242a682897d5d86df4547cf24"
+     # core2-poky-linux
+     SRCREV_pn-kmod = "62081c0f68905b22f375156d4532fd37fa5c8d33"
+     SRCREV_pn-blktrace = "d6918c8832793b4205ed3bfede78c2f915c23385"
+     SRCREV_pn-opkg = "649"
+                </literallayout>
+                <note>
+                    Here are some notes on using the
+                    <filename>buildhistory-collect-srcrevs</filename> command:
+                    <itemizedlist>
+                        <listitem><para>By default, only values where the
+                            <filename>SRCREV</filename> was
+                            not hardcoded (usually when <filename>AUTOREV</filename>
+                            was used) are reported.
+                            Use the <filename>-a</filename> option to see all
+                            <filename>SRCREV</filename> values.
+                            </para></listitem>
+                        <listitem><para>The output statements might not have any effect
+                            if overrides are applied elsewhere in the build system
+                            configuration.
+                            Use the <filename>-f</filename> option to add the
+                            <filename>forcevariable</filename> override to each output line
+                            if you need to work around this restriction.
+                            </para></listitem>
+                        <listitem><para>The script does apply special handling when
+                            building for multiple machines.
+                            However, the script does place a
+                            comment before each set of values that specifies
+                            which triplet to which they belong as shown above
+                            (e.g., <filename>emenlow-poky-linux</filename>).
+                            </para></listitem>
+                    </itemizedlist>
+                </note>
+            </para>
+        </section>
+
+        <section id='build-history-image-information'>
+            <title>Build History Image Information</title>
+
+            <para>
+                The files produced for each image are as follows:
+                <itemizedlist>
+                    <listitem><para><filename>image-files:</filename>
+                        A directory containing selected files from the root
+                        filesystem.
+                        The files are defined by
+                        <filename>BUILDHISTORY_IMAGE_FILES</filename>.
+                        </para></listitem>
+                    <listitem><para><filename>build-id:</filename>
+                        Human-readable information about the build configuration
+                        and metadata source revisions.</para></listitem>
+                    <listitem><para><filename>*.dot:</filename>
+                        Dependency graphs for the image that are
+                        compatible with <filename>graphviz</filename>.
+                        </para></listitem>
+                    <listitem><para><filename>files-in-image.txt:</filename>
+                            A list of files in the image with permissions,
+                        owner, group, size, and symlink information.
+                        </para></listitem>
+                    <listitem><para><filename>image-info.txt:</filename>
+                        A text file containing name-value pairs with information
+                        about the image.
+                        See the following listing example for more information.
+                        </para></listitem>
+                    <listitem><para><filename>installed-package-names.txt:</filename>
+                        A list of installed packages by name only.</para></listitem>
+                    <listitem><para><filename>installed-package-sizes.txt:</filename>
+                        A list of installed packages ordered by size.
+                        </para></listitem>
+                    <listitem><para><filename>installed-packages.txt:</filename>
+                        A list of installed packages with full package
+                        filenames.</para></listitem>
+                </itemizedlist>
+                <note>
+                    Installed package information is able to be gathered and
+                    produced even if package management is disabled for the final
+                    image.
+                </note>
+            </para>
+
+            <para>
+                Here is an example of <filename>image-info.txt</filename>:
+                <literallayout class='monospaced'>
+     DISTRO = poky
+     DISTRO_VERSION = 1.1+snapshot-20120207
+     USER_CLASSES = image-mklibs image-prelink
+     IMAGE_CLASSES = image_types
+     IMAGE_FEATURES = debug-tweaks x11-base apps-x11-core \
+        package-management ssh-server-dropbear package-management
+     IMAGE_LINGUAS = en-us en-gb
+     IMAGE_INSTALL = task-core-boot task-base-extended
+     BAD_RECOMMENDATIONS =
+     ROOTFS_POSTPROCESS_COMMAND = buildhistory_get_image_installed ;   rootfs_update_timestamp ;
+     IMAGE_POSTPROCESS_COMMAND = buildhistory_get_imageinfo ;
+     IMAGESIZE = 171816
+                </literallayout>
+                Other than <filename>IMAGESIZE</filename>, which is the
+                total size of the files in the image in Kbytes, the
+                name-value pairs are variables that may have influenced the
+                content of the image.
+                This information is often useful when you are trying to determine
+                why a change in the package or file listings has occurred.
+            </para>
+        </section>
+
+        <section id='using-build-history-to-gather-image-information-only'>
+            <title>Using Build History to Gather Image Information Only</title>
+
+            <para>
+                As you can see, build history produces image information,
+                including dependency graphs, so you can see why something
+                was pulled into the image.
+                If you are just interested in this information and not
+                interested in collecting history or any package information,
+                you can enable writing only image information without
+                any history by adding the following
+                to your <filename>conf/local.conf</filename> file found in the
+                <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
+                <literallayout class='monospaced'>
+     INHERIT += "buildhistory"
+     BUILDHISTORY_COMMIT = "0"
+     BUILDHISTORY_FEATURES = "image"
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='build-history-sdk-information'>
+            <title>Build History SDK Information</title>
+            <para>
+                Build history collects similar information on the contents
+                of SDKs (e.g., <filename>meta-toolchain</filename>
+                or <filename>bitbake -c populate_sdk imagename</filename>)
+                as compared to information it collects for images.
+                The following list shows the files produced for each SDK:
+                <itemizedlist>
+                    <listitem><para><filename>files-in-sdk.txt:</filename>
+                        A list of files in the SDK with permissions,
+                        owner, group, size, and symlink information.
+                        This list includes both the host and target parts
+                        of the SDK.
+                        </para></listitem>
+                    <listitem><para><filename>sdk-info.txt:</filename>
+                        A text file containing name-value pairs with information
+                        about the SDK.
+                        See the following listing example for more information.
+                        </para></listitem>
+                    <listitem><para>The following information appears under
+                        each of the <filename>host</filename>
+                        and <filename>target</filename> directories
+                        for the portions of the SDK that run on the host and
+                        on the target, respectively:
+                        <itemizedlist>
+                            <listitem><para><filename>depends.dot:</filename>
+                                Dependency graph for the SDK that is
+                                compatible with <filename>graphviz</filename>.
+                                </para></listitem>
+                            <listitem><para><filename>installed-package-names.txt:</filename>
+                                A list of installed packages by name only.
+                                </para></listitem>
+                            <listitem><para><filename>installed-package-sizes.txt:</filename>
+                                A list of installed packages ordered by size.
+                                </para></listitem>
+                            <listitem><para><filename>installed-packages.txt:</filename>
+                                A list of installed packages with full package
+                                filenames.</para></listitem>
+                            </itemizedlist>
+                        </para></listitem>
+                </itemizedlist>
+            </para>
+
+            <para>
+                Here is an example of <filename>sdk-info.txt</filename>:
+                <literallayout class='monospaced'>
+     DISTRO = poky
+     DISTRO_VERSION = 1.3+snapshot-20130327
+     SDK_NAME = poky-eglibc-i686-arm
+     SDK_VERSION = 1.3+snapshot
+     SDKMACHINE =
+     SDKIMAGE_FEATURES = dev-pkgs dbg-pkgs
+     BAD_RECOMMENDATIONS =
+     SDKSIZE = 352712
+                </literallayout>
+                Other than <filename>SDKSIZE</filename>, which is the
+                total size of the files in the SDK in Kbytes, the
+                name-value pairs are variables that might have influenced the
+                content of the SDK.
+                This information is often useful when you are trying to
+                determine why a change in the package or file listings
+                has occurred.
+            </para>
+        </section>
+
+        <section id='examining-build-history-information'>
+            <title>Examining Build History Information</title>
+
+            <para>
+                You can examine build history output from the command line or
+                from a web interface.
+            </para>
+
+            <para>
+                To see any changes that have occurred (assuming you have
+                <filename>BUILDHISTORY_COMMIT = "1"</filename>), you can simply
+                use any Git command that allows you to view the history of
+                a repository.
+                Here is one method:
+                <literallayout class='monospaced'>
+      $ git log -p
+                </literallayout>
+                You need to realize, however, that this method does show
+                changes that are not significant (e.g. a package's size
+                changing by a few bytes).
+            </para>
+
+            <para>
+                A command-line tool called <filename>buildhistory-diff</filename>
+                does exist, though, that queries the Git repository and prints just
+                the differences that might be significant in human-readable form.
+                Here is an example:
+                <literallayout class='monospaced'>
+     $ ~/poky/poky/scripts/buildhistory-diff . HEAD^
+     Changes to images/qemux86_64/eglibc/core-image-minimal (files-in-image.txt):
+        /etc/anotherpkg.conf was added
+        /sbin/anotherpkg was added
+        * (installed-package-names.txt):
+        *   anotherpkg was added
+     Changes to images/qemux86_64/eglibc/core-image-minimal (installed-package-names.txt):
+        anotherpkg was added
+     packages/qemux86_64-poky-linux/v86d: PACKAGES: added "v86d-extras"
+        * PR changed from "r0" to "r1"
+        * PV changed from "0.1.10" to "0.1.12"
+     packages/qemux86_64-poky-linux/v86d/v86d: PKGSIZE changed from 110579 to 144381 (+30%)
+        * PR changed from "r0" to "r1"
+        * PV changed from "0.1.10" to "0.1.12"
+                </literallayout>
+            </para>
+
+            <para>
+                To see changes to the build history using a web interface, follow
+                the instruction in the <filename>README</filename> file here.
+                <ulink url='http://git.yoctoproject.org/cgit/cgit.cgi/buildhistory-web/'></ulink>.
+            </para>
+
+            <para>
+                Here is a sample screenshot of the interface:
+                <imagedata fileref="figures/buildhistory-web.png" align="center" scalefit="1" width="130%" contentdepth="130%" />
+            </para>
+        </section>
+    </section>
+</section>
+
+</chapter>
+<!--
+vim: expandtab tw=80 ts=4
+-->
diff --git a/documentation/template/Vera.ttf b/documentation/template/Vera.ttf
new file mode 100644
index 0000000000..58cd6b5e61
--- /dev/null
+++ b/documentation/template/Vera.ttf
diff --git a/documentation/template/Vera.xml b/documentation/template/Vera.xml
new file mode 100644
index 0000000000..3c82043e35
--- /dev/null
+++ b/documentation/template/Vera.xml
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><font-metrics type="TYPE0"><font-name>BitstreamVeraSans</font-name><embed/><cap-height>729</cap-height><x-height>546</x-height><ascender>928</ascender><descender>-235</descender><bbox><left>-183</left><bottom>-235</bottom><right>1287</right><top>928</top></bbox><flags>32</flags><stemv>0</stemv><italicangle>0</italicangle><subtype>TYPE0</subtype><multibyte-extras><cid-type>CIDFontType2</cid-type><default-width>0</default-width><bfranges><bf gi="3" ue="126" us="32"/><bf gi="172" ue="160" us="160"/><bf gi="163" ue="161" us="161"/><bf gi="132" ue="163" us="162"/><bf gi="189" ue="164" us="164"/><bf gi="150" ue="165" us="165"/><bf gi="231" ue="166" us="166"/><bf gi="134" ue="167" us="167"/><bf gi="142" ue="168" us="168"/><bf gi="139" ue="169" us="169"/><bf gi="157" ue="170" us="170"/><bf gi="169" ue="171" us="171"/><bf gi="164" ue="172" us="172"/><bf gi="256" ue="173" us="173"/><bf gi="138" ue="174" us="174"/><bf gi="217" ue="175" us="175"/><bf gi="131" ue="176" us="176"/><bf gi="147" ue="177" us="177"/><bf gi="241" ue="179" us="178"/><bf gi="141" ue="180" us="180"/><bf gi="151" ue="181" us="181"/><bf gi="136" ue="182" us="182"/><bf gi="195" ue="183" us="183"/><bf gi="221" ue="184" us="184"/><bf gi="240" ue="185" us="185"/><bf gi="158" ue="186" us="186"/><bf gi="170" ue="187" us="187"/><bf gi="243" ue="190" us="188"/><bf gi="162" ue="191" us="191"/><bf gi="173" ue="192" us="192"/><bf gi="201" ue="193" us="193"/><bf gi="199" ue="194" us="194"/><bf gi="174" ue="195" us="195"/><bf gi="98" ue="197" us="196"/><bf gi="144" ue="198" us="198"/><bf gi="100" ue="199" us="199"/><bf gi="203" ue="200" us="200"/><bf gi="101" ue="201" us="201"/><bf gi="200" ue="202" us="202"/><bf gi="202" ue="203" us="203"/><bf gi="207" ue="204" us="204"/><bf gi="204" ue="207" us="205"/><bf gi="232" ue="208" us="208"/><bf gi="102" ue="209" us="209"/><bf gi="210" ue="210" us="210"/><bf gi="208" ue="212" us="211"/><bf gi="175" ue="213" us="213"/><bf gi="103" ue="214" us="214"/><bf gi="239" ue="215" us="215"/><bf gi="145" ue="216" us="216"/><bf gi="213" ue="217" us="217"/><bf gi="211" ue="219" us="218"/><bf gi="104" ue="220" us="220"/><bf gi="234" ue="221" us="221"/><bf gi="236" ue="222" us="222"/><bf gi="137" ue="223" us="223"/><bf gi="106" ue="224" us="224"/><bf gi="105" ue="225" us="225"/><bf gi="107" ue="226" us="226"/><bf gi="109" ue="227" us="227"/><bf gi="108" ue="228" us="228"/><bf gi="110" ue="229" us="229"/><bf gi="160" ue="230" us="230"/><bf gi="111" ue="231" us="231"/><bf gi="113" ue="232" us="232"/><bf gi="112" ue="233" us="233"/><bf gi="114" ue="235" us="234"/><bf gi="117" ue="236" us="236"/><bf gi="116" ue="237" us="237"/><bf gi="118" ue="239" us="238"/><bf gi="233" ue="240" us="240"/><bf gi="120" ue="241" us="241"/><bf gi="122" ue="242" us="242"/><bf gi="121" ue="243" us="243"/><bf gi="123" ue="244" us="244"/><bf gi="125" ue="245" us="245"/><bf gi="124" ue="246" us="246"/><bf gi="184" ue="247" us="247"/><bf gi="161" ue="248" us="248"/><bf gi="127" ue="249" us="249"/><bf gi="126" ue="250" us="250"/><bf gi="128" ue="252" us="251"/><bf gi="235" ue="253" us="253"/><bf gi="237" ue="254" us="254"/><bf gi="186" ue="255" us="255"/><bf gi="251" ue="263" us="262"/><bf gi="253" ue="269" us="268"/><bf gi="0" ue="270" us="270"/><bf gi="0" ue="271" us="271"/><bf gi="0" ue="272" us="272"/><bf gi="255" ue="273" us="273"/><bf gi="246" ue="287" us="286"/><bf gi="248" ue="304" us="304"/><bf gi="214" ue="305" us="305"/><bf gi="225" ue="322" us="321"/><bf gi="176" ue="339" us="338"/><bf gi="249" ue="351" us="350"/><bf gi="227" ue="353" us="352"/><bf gi="187" ue="376" us="376"/><bf gi="229" ue="382" us="381"/><bf gi="166" ue="402" us="402"/><bf gi="215" ue="710" us="710"/><bf gi="224" ue="711" us="711"/><bf gi="218" ue="730" us="728"/><bf gi="223" ue="731" us="731"/><bf gi="216" ue="732" us="732"/><bf gi="222" ue="733" us="733"/><bf gi="159" ue="937" us="937"/><bf gi="155" ue="960" us="960"/><bf gi="178" ue="8212" us="8211"/><bf gi="0" ue="8213" us="8213"/><bf gi="0" ue="8214" us="8214"/><bf gi="0" ue="8215" us="8215"/><bf gi="182" ue="8217" us="8216"/><bf gi="196" ue="8218" us="8218"/><bf gi="0" ue="8219" us="8219"/><bf gi="180" ue="8221" us="8220"/><bf gi="197" ue="8222" us="8222"/><bf gi="0" ue="8223" us="8223"/><bf gi="130" ue="8224" us="8224"/><bf gi="194" ue="8225" us="8225"/><bf gi="135" ue="8226" us="8226"/><bf gi="0" ue="8227" us="8227"/><bf gi="0" ue="8228" us="8228"/><bf gi="0" ue="8229" us="8229"/><bf gi="171" ue="8230" us="8230"/><bf gi="198" ue="8240" us="8240"/><bf gi="190" ue="8250" us="8249"/><bf gi="258" ue="8364" us="8364"/><bf gi="140" ue="8482" us="8482"/><bf gi="152" ue="8706" us="8706"/><bf gi="0" ue="8707" us="8707"/><bf gi="0" ue="8708" us="8708"/><bf gi="0" ue="8709" us="8709"/><bf gi="168" ue="8710" us="8710"/><bf gi="154" ue="8719" us="8719"/><bf gi="0" ue="8720" us="8720"/><bf gi="153" ue="8721" us="8721"/><bf gi="238" ue="8722" us="8722"/><bf gi="0" ue="8723" us="8723"/><bf gi="0" ue="8724" us="8724"/><bf gi="188" ue="8725" us="8725"/><bf gi="0" ue="8726" us="8726"/><bf gi="0" ue="8727" us="8727"/><bf gi="0" ue="8728" us="8728"/><bf gi="257" ue="8729" us="8729"/><bf gi="165" ue="8730" us="8730"/><bf gi="0" ue="8731" us="8731"/><bf gi="0" ue="8732" us="8732"/><bf gi="0" ue="8733" us="8733"/><bf gi="146" ue="8734" us="8734"/><bf gi="156" ue="8747" us="8747"/><bf gi="167" ue="8776" us="8776"/><bf gi="143" ue="8800" us="8800"/><bf gi="0" ue="8801" us="8801"/><bf gi="0" ue="8802" us="8802"/><bf gi="0" ue="8803" us="8803"/><bf gi="148" ue="8805" us="8804"/><bf gi="185" ue="9674" us="9674"/><bf gi="192" ue="64258" us="64257"/><bf gi="0" ue="65535" us="65535"/></bfranges><cid-widths start-index="0"><wx w="600"/><wx w="0"/><wx w="317"/><wx w="317"/><wx w="400"/><wx w="459"/><wx w="837"/><wx w="636"/><wx w="950"/><wx w="779"/><wx w="274"/><wx w="390"/><wx w="390"/><wx w="500"/><wx w="837"/><wx w="317"/><wx w="360"/><wx w="317"/><wx w="336"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="636"/><wx w="336"/><wx w="336"/><wx w="837"/><wx w="837"/><wx w="837"/><wx w="530"/><wx w="1000"/><wx w="684"/><wx w="686"/><wx w="698"/><wx w="770"/><wx w="631"/><wx w="575"/><wx w="774"/><wx w="751"/><wx w="294"/><wx w="294"/><wx w="655"/><wx w="557"/><wx w="862"/><wx w="748"/><wx w="787"/><wx w="603"/><wx w="787"/><wx w="694"/><wx w="634"/><wx w="610"/><wx w="731"/><wx w="684"/><wx w="988"/><wx w="685"/><wx w="610"/><wx w="685"/><wx w="390"/><wx w="336"/><wx w="390"/><wx w="837"/><wx w="500"/><wx w="500"/><wx w="612"/><wx w="634"/><wx w="549"/><wx w="634"/><wx w="615"/><wx w="352"/><wx w="634"/><wx w="633"/><wx w="277"/><wx w="277"/><wx w="579"/><wx w="277"/><wx w="974"/><wx w="633"/><wx w="611"/><wx w="634"/><wx w="634"/><wx w="411"/><wx w="520"/><wx w="392"/><wx w="633"/><wx w="591"/><wx w="817"/><wx w="591"/><wx w="591"/><wx w="524"/><wx w="636"/><wx w="336"/><wx w="636"/><wx w="837"/><wx w="684"/><wx w="684"/><wx w="698"/><wx w="631"/><wx w="748"/><wx w="787"/><wx w="731"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="612"/><wx w="549"/><wx w="615"/><wx w="615"/><wx w="615"/><wx w="615"/><wx w="277"/><wx w="277"/><wx w="277"/><wx w="277"/><wx w="633"/><wx w="611"/><wx w="611"/><wx w="611"/><wx w="611"/><wx w="611"/><wx w="633"/><wx w="633"/><wx w="633"/><wx w="633"/><wx w="500"/><wx w="500"/><wx w="636"/><wx w="636"/><wx w="500"/><wx w="589"/><wx w="636"/><wx w="629"/><wx w="1000"/><wx w="1000"/><wx w="1000"/><wx w="500"/><wx w="500"/><wx w="837"/><wx w="974"/><wx w="787"/><wx w="833"/><wx w="837"/><wx w="837"/><wx w="837"/><wx w="636"/><wx w="636"/><wx w="517"/><wx w="673"/><wx w="756"/><wx w="588"/><wx w="520"/><wx w="471"/><wx w="471"/><wx w="764"/><wx w="981"/><wx w="611"/><wx w="530"/><wx w="400"/><wx w="837"/><wx w="637"/><wx w="636"/><wx w="837"/><wx w="668"/><wx w="611"/><wx w="611"/><wx w="1000"/><wx w="636"/><wx w="684"/><wx w="684"/><wx w="787"/><wx w="1069"/><wx w="1022"/><wx w="500"/><wx w="1000"/><wx w="518"/><wx w="518"/><wx w="317"/><wx w="317"/><wx w="837"/><wx w="494"/><wx w="591"/><wx w="610"/><wx w="166"/><wx w="636"/><wx w="399"/><wx w="399"/><wx w="629"/><wx w="629"/><wx w="500"/><wx w="317"/><wx w="317"/><wx w="518"/><wx w="1341"/><wx w="684"/><wx w="631"/><wx w="684"/><wx w="631"/><wx w="631"/><wx w="294"/><wx w="294"/><wx w="294"/><wx w="294"/><wx w="787"/><wx w="787"/><wx w="787"/><wx w="731"/><wx w="731"/><wx w="731"/><wx w="277"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="562"/><wx w="284"/><wx w="634"/><wx w="520"/><wx w="685"/><wx w="524"/><wx w="336"/><wx w="774"/><wx w="611"/><wx w="610"/><wx w="591"/><wx w="604"/><wx w="634"/><wx w="837"/><wx w="837"/><wx w="400"/><wx w="400"/><wx w="400"/><wx w="969"/><wx w="969"/><wx w="969"/><wx w="774"/><wx w="634"/><wx w="294"/><wx w="634"/><wx w="520"/><wx w="698"/><wx w="549"/><wx w="698"/><wx w="549"/><wx w="634"/><wx w="360"/><wx w="317"/><wx w="636"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="500"/><wx w="400"/><wx w="500"/><wx w="500"/></cid-widths></multibyte-extras><kerning kpx1="246"><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="169"/><pair kern="-26" kpx2="197"/><pair kern="-35" kpx2="55"/><pair kern="-49" kpx2="60"/><pair kern="-49" kpx2="187"/><pair kern="-21" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-49" kpx2="234"/></kerning><kerning kpx1="235"><pair kern="-142" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-146" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-72" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="43"><pair kern="-35" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-35" kpx2="197"/><pair kern="-30" kpx2="181"/></kerning><kerning kpx1="16"><pair kern="36" kpx2="246"/><pair kern="-17" kpx2="235"/><pair kern="-21" kpx2="199"/><pair kern="18" kpx2="123"/><pair kern="27" kpx2="208"/><pair kern="-118" kpx2="187"/><pair kern="-49" kpx2="59"/><pair kern="18" kpx2="124"/><pair kern="-21" kpx2="201"/><pair kern="-118" kpx2="60"/><pair kern="36" kpx2="52"/><pair kern="18" kpx2="125"/><pair kern="36" kpx2="42"/><pair kern="-118" kpx2="234"/><pair kern="18" kpx2="122"/><pair kern="27" kpx2="210"/><pair kern="-21" kpx2="36"/><pair kern="18" kpx2="82"/><pair kern="-40" kpx2="58"/><pair kern="-91" kpx2="55"/><pair kern="-17" kpx2="186"/><pair kern="27" kpx2="175"/><pair kern="27" kpx2="50"/><pair kern="27" kpx2="209"/><pair kern="27" kpx2="103"/><pair kern="-21" kpx2="98"/><pair kern="55" kpx2="45"/><pair kern="-21" kpx2="173"/><pair kern="-17" kpx2="92"/><pair kern="-26" kpx2="89"/><pair kern="18" kpx2="121"/><pair kern="-58" kpx2="57"/><pair kern="-35" kpx2="37"/><pair kern="-21" kpx2="174"/></kerning><kerning kpx1="112"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="123"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="251"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="213"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="208"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="187"><pair kern="-114" kpx2="126"/><pair kern="-137" kpx2="107"/><pair kern="-132" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-118" kpx2="16"/><pair kern="-132" kpx2="123"/><pair kern="-132" kpx2="112"/><pair kern="-54" kpx2="251"/><pair kern="-54" kpx2="208"/><pair kern="-132" kpx2="113"/><pair kern="-54" kpx2="180"/><pair kern="-137" kpx2="105"/><pair kern="-114" kpx2="129"/><pair kern="-132" kpx2="124"/><pair kern="-109" kpx2="169"/><pair kern="-77" kpx2="201"/><pair kern="-54" kpx2="253"/><pair kern="-137" kpx2="106"/><pair kern="-132" kpx2="29"/><pair kern="-132" kpx2="125"/><pair kern="-72" kpx2="170"/><pair kern="-132" kpx2="115"/><pair kern="-114" kpx2="88"/><pair kern="-132" kpx2="122"/><pair kern="-54" kpx2="100"/><pair kern="-137" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-77" kpx2="36"/><pair kern="-132" kpx2="82"/><pair kern="-132" kpx2="114"/><pair kern="-54" kpx2="175"/><pair kern="-114" kpx2="127"/><pair kern="-54" kpx2="50"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-137" kpx2="108"/><pair kern="-77" kpx2="98"/><pair kern="-35" kpx2="76"/><pair kern="-17" kpx2="181"/><pair kern="-202" kpx2="17"/><pair kern="-114" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-137" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-54" kpx2="38"/><pair kern="-132" kpx2="121"/><pair kern="-137" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="113"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="144"><pair kern="-40" kpx2="180"/><pair kern="-54" kpx2="197"/><pair kern="-44" kpx2="181"/></kerning><kerning kpx1="59"><pair kern="-72" kpx2="100"/><pair kern="-63" kpx2="210"/><pair kern="-17" kpx2="55"/><pair kern="-44" kpx2="114"/><pair kern="-44" kpx2="72"/><pair kern="-63" kpx2="175"/><pair kern="-49" kpx2="16"/><pair kern="-63" kpx2="50"/><pair kern="-63" kpx2="209"/><pair kern="-44" kpx2="112"/><pair kern="-72" kpx2="251"/><pair kern="-63" kpx2="103"/><pair kern="-63" kpx2="208"/><pair kern="-44" kpx2="113"/><pair kern="-40" kpx2="181"/><pair kern="-77" kpx2="180"/><pair kern="-54" kpx2="169"/><pair kern="-21" kpx2="197"/><pair kern="-72" kpx2="38"/><pair kern="-72" kpx2="253"/><pair kern="-44" kpx2="115"/></kerning><kerning kpx1="73"><pair kern="31" kpx2="180"/><pair kern="-17" kpx2="90"/><pair kern="-72" kpx2="17"/><pair kern="-17" kpx2="235"/><pair kern="-35" kpx2="169"/><pair kern="-114" kpx2="197"/><pair kern="-17" kpx2="186"/><pair kern="-17" kpx2="92"/><pair kern="-17" kpx2="87"/><pair kern="-54" kpx2="16"/><pair kern="-35" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="41"><pair kern="-17" kpx2="227"/><pair kern="-54" kpx2="126"/><pair kern="-91" kpx2="107"/><pair kern="-91" kpx2="235"/><pair kern="-54" kpx2="72"/><pair kern="-91" kpx2="199"/><pair kern="-35" kpx2="123"/><pair kern="-54" kpx2="112"/><pair kern="-54" kpx2="113"/><pair kern="-17" kpx2="54"/><pair kern="-21" kpx2="180"/><pair kern="-91" kpx2="105"/><pair kern="-54" kpx2="129"/><pair kern="-35" kpx2="124"/><pair kern="-91" kpx2="201"/><pair kern="-72" kpx2="85"/><pair kern="-91" kpx2="106"/><pair kern="-77" kpx2="29"/><pair kern="-35" kpx2="125"/><pair kern="-54" kpx2="115"/><pair kern="-54" kpx2="88"/><pair kern="-35" kpx2="122"/><pair kern="-91" kpx2="68"/><pair kern="-91" kpx2="36"/><pair kern="-35" kpx2="82"/><pair kern="-91" kpx2="186"/><pair kern="-17" kpx2="55"/><pair kern="-54" kpx2="114"/><pair kern="-54" kpx2="127"/><pair kern="-91" kpx2="108"/><pair kern="-91" kpx2="98"/><pair kern="-72" kpx2="76"/><pair kern="-160" kpx2="17"/><pair kern="-54" kpx2="128"/><pair kern="-91" kpx2="173"/><pair kern="-91" kpx2="109"/><pair kern="-183" kpx2="197"/><pair kern="-91" kpx2="92"/><pair kern="-35" kpx2="121"/><pair kern="-91" kpx2="110"/><pair kern="-91" kpx2="174"/><pair kern="-17" kpx2="249"/></kerning><kerning kpx1="124"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="169"><pair kern="-17" kpx2="90"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="246"/><pair kern="-17" kpx2="235"/><pair kern="-17" kpx2="58"/><pair kern="-17" kpx2="186"/><pair kern="-54" kpx2="55"/><pair kern="-17" kpx2="251"/><pair kern="-72" kpx2="187"/><pair kern="-17" kpx2="39"/><pair kern="73" kpx2="144"/><pair kern="-17" kpx2="45"/><pair kern="-17" kpx2="92"/><pair kern="-17" kpx2="38"/><pair kern="-72" kpx2="60"/><pair kern="-17" kpx2="89"/><pair kern="-17" kpx2="253"/><pair kern="-54" kpx2="57"/><pair kern="-17" kpx2="37"/><pair kern="-17" kpx2="42"/><pair kern="-72" kpx2="234"/></kerning><kerning kpx1="201"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="60"><pair kern="-114" kpx2="126"/><pair kern="-137" kpx2="107"/><pair kern="-132" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-118" kpx2="16"/><pair kern="-132" kpx2="123"/><pair kern="-132" kpx2="112"/><pair kern="-54" kpx2="251"/><pair kern="-54" kpx2="208"/><pair kern="-132" kpx2="113"/><pair kern="-54" kpx2="180"/><pair kern="-137" kpx2="105"/><pair kern="-114" kpx2="129"/><pair kern="-132" kpx2="124"/><pair kern="-109" kpx2="169"/><pair kern="-77" kpx2="201"/><pair kern="-54" kpx2="253"/><pair kern="-137" kpx2="106"/><pair kern="-132" kpx2="29"/><pair kern="-132" kpx2="125"/><pair kern="-72" kpx2="170"/><pair kern="-132" kpx2="115"/><pair kern="-114" kpx2="88"/><pair kern="-132" kpx2="122"/><pair kern="-54" kpx2="100"/><pair kern="-137" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-77" kpx2="36"/><pair kern="-132" kpx2="82"/><pair kern="-132" kpx2="114"/><pair kern="-54" kpx2="175"/><pair kern="-114" kpx2="127"/><pair kern="-54" kpx2="50"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-137" kpx2="108"/><pair kern="-77" kpx2="98"/><pair kern="-35" kpx2="76"/><pair kern="-17" kpx2="181"/><pair kern="-202" kpx2="17"/><pair kern="-114" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-137" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-54" kpx2="38"/><pair kern="-132" kpx2="121"/><pair kern="-137" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="85"><pair kern="-21" kpx2="254"/><pair kern="-21" kpx2="72"/><pair kern="-63" kpx2="16"/><pair kern="-21" kpx2="112"/><pair kern="-21" kpx2="123"/><pair kern="-17" kpx2="80"/><pair kern="-21" kpx2="113"/><pair kern="-17" kpx2="71"/><pair kern="-21" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-21" kpx2="252"/><pair kern="-21" kpx2="70"/><pair kern="-17" kpx2="85"/><pair kern="-17" kpx2="29"/><pair kern="-21" kpx2="125"/><pair kern="-21" kpx2="115"/><pair kern="-21" kpx2="111"/><pair kern="-21" kpx2="122"/><pair kern="-21" kpx2="82"/><pair kern="-17" kpx2="75"/><pair kern="-21" kpx2="114"/><pair kern="-26" kpx2="91"/><pair kern="-17" kpx2="81"/><pair kern="41" kpx2="181"/><pair kern="-91" kpx2="17"/><pair kern="-151" kpx2="197"/><pair kern="-17" kpx2="74"/><pair kern="-17" kpx2="84"/><pair kern="-21" kpx2="121"/><pair kern="-17" kpx2="247"/><pair kern="-17" kpx2="120"/></kerning><kerning kpx1="61"><pair kern="-17" kpx2="180"/><pair kern="-17" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-17" kpx2="181"/></kerning><kerning kpx1="234"><pair kern="-114" kpx2="126"/><pair kern="-137" kpx2="107"/><pair kern="-132" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-118" kpx2="16"/><pair kern="-132" kpx2="123"/><pair kern="-132" kpx2="112"/><pair kern="-54" kpx2="251"/><pair kern="-54" kpx2="208"/><pair kern="-132" kpx2="113"/><pair kern="-54" kpx2="180"/><pair kern="-137" kpx2="105"/><pair kern="-114" kpx2="129"/><pair kern="-132" kpx2="124"/><pair kern="-109" kpx2="169"/><pair kern="-77" kpx2="201"/><pair kern="-54" kpx2="253"/><pair kern="-137" kpx2="106"/><pair kern="-132" kpx2="29"/><pair kern="-132" kpx2="125"/><pair kern="-72" kpx2="170"/><pair kern="-132" kpx2="115"/><pair kern="-114" kpx2="88"/><pair kern="-132" kpx2="122"/><pair kern="-54" kpx2="100"/><pair kern="-137" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-77" kpx2="36"/><pair kern="-132" kpx2="82"/><pair kern="-132" kpx2="114"/><pair kern="-54" kpx2="175"/><pair kern="-114" kpx2="127"/><pair kern="-54" kpx2="50"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-137" kpx2="108"/><pair kern="-77" kpx2="98"/><pair kern="-35" kpx2="76"/><pair kern="-17" kpx2="181"/><pair kern="-202" kpx2="17"/><pair kern="-114" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-137" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-54" kpx2="38"/><pair kern="-132" kpx2="121"/><pair kern="-137" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="100"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="122"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="47"><pair kern="-17" kpx2="126"/><pair kern="-91" kpx2="235"/><pair kern="-49" kpx2="104"/><pair kern="-17" kpx2="72"/><pair kern="22" kpx2="199"/><pair kern="-17" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-49" kpx2="213"/><pair kern="-35" kpx2="208"/><pair kern="-132" kpx2="187"/><pair kern="-17" kpx2="113"/><pair kern="-202" kpx2="180"/><pair kern="-17" kpx2="129"/><pair kern="-17" kpx2="124"/><pair kern="22" kpx2="201"/><pair kern="-132" kpx2="60"/><pair kern="-49" kpx2="211"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="115"/><pair kern="-132" kpx2="234"/><pair kern="-17" kpx2="88"/><pair kern="-17" kpx2="122"/><pair kern="-35" kpx2="210"/><pair kern="22" kpx2="36"/><pair kern="-17" kpx2="82"/><pair kern="-91" kpx2="58"/><pair kern="-91" kpx2="186"/><pair kern="-137" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-35" kpx2="175"/><pair kern="-17" kpx2="127"/><pair kern="-35" kpx2="50"/><pair kern="-35" kpx2="209"/><pair kern="-35" kpx2="103"/><pair kern="22" kpx2="98"/><pair kern="-262" kpx2="181"/><pair kern="-17" kpx2="128"/><pair kern="22" kpx2="173"/><pair kern="-49" kpx2="212"/><pair kern="-91" kpx2="92"/><pair kern="-17" kpx2="121"/><pair kern="-109" kpx2="57"/><pair kern="22" kpx2="174"/><pair kern="-49" kpx2="56"/></kerning><kerning kpx1="210"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="58"><pair kern="-35" kpx2="126"/><pair kern="-63" kpx2="107"/><pair kern="-17" kpx2="235"/><pair kern="-58" kpx2="72"/><pair kern="-54" kpx2="199"/><pair kern="-40" kpx2="16"/><pair kern="-58" kpx2="112"/><pair kern="-58" kpx2="123"/><pair kern="-58" kpx2="113"/><pair kern="-17" kpx2="180"/><pair kern="-63" kpx2="105"/><pair kern="-35" kpx2="129"/><pair kern="-58" kpx2="124"/><pair kern="-54" kpx2="169"/><pair kern="-54" kpx2="201"/><pair kern="-44" kpx2="85"/><pair kern="-63" kpx2="106"/><pair kern="-58" kpx2="29"/><pair kern="-58" kpx2="125"/><pair kern="-17" kpx2="170"/><pair kern="-58" kpx2="115"/><pair kern="-35" kpx2="88"/><pair kern="-58" kpx2="122"/><pair kern="-63" kpx2="68"/><pair kern="-54" kpx2="36"/><pair kern="-58" kpx2="82"/><pair kern="-17" kpx2="186"/><pair kern="-58" kpx2="114"/><pair kern="-35" kpx2="127"/><pair kern="-63" kpx2="108"/><pair kern="-54" kpx2="98"/><pair kern="-21" kpx2="76"/><pair kern="-114" kpx2="17"/><pair kern="-35" kpx2="128"/><pair kern="-54" kpx2="173"/><pair kern="-63" kpx2="109"/><pair kern="-128" kpx2="197"/><pair kern="-17" kpx2="92"/><pair kern="-58" kpx2="121"/><pair kern="-63" kpx2="110"/><pair kern="-54" kpx2="174"/></kerning><kerning kpx1="82"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="186"><pair kern="-142" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-146" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-72" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="175"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="209"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="103"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="81"><pair kern="-72" kpx2="180"/><pair kern="-44" kpx2="197"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="98"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="212"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="229"><pair kern="-17" kpx2="180"/><pair kern="-17" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-17" kpx2="181"/></kerning><kerning kpx1="38"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="121"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="57"><pair kern="-67" kpx2="126"/><pair kern="-77" kpx2="107"/><pair kern="-26" kpx2="235"/><pair kern="-77" kpx2="72"/><pair kern="-63" kpx2="199"/><pair kern="-58" kpx2="16"/><pair kern="-77" kpx2="123"/><pair kern="-77" kpx2="112"/><pair kern="-17" kpx2="208"/><pair kern="-77" kpx2="113"/><pair kern="-77" kpx2="105"/><pair kern="-67" kpx2="129"/><pair kern="-77" kpx2="124"/><pair kern="-86" kpx2="169"/><pair kern="-63" kpx2="201"/><pair kern="-77" kpx2="106"/><pair kern="-81" kpx2="29"/><pair kern="-77" kpx2="125"/><pair kern="-54" kpx2="170"/><pair kern="-77" kpx2="115"/><pair kern="-67" kpx2="88"/><pair kern="-77" kpx2="122"/><pair kern="-77" kpx2="68"/><pair kern="-17" kpx2="210"/><pair kern="-63" kpx2="36"/><pair kern="-77" kpx2="82"/><pair kern="-26" kpx2="186"/><pair kern="-77" kpx2="114"/><pair kern="-17" kpx2="175"/><pair kern="-67" kpx2="127"/><pair kern="-17" kpx2="50"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="-77" kpx2="108"/><pair kern="-63" kpx2="98"/><pair kern="-21" kpx2="76"/><pair kern="-128" kpx2="17"/><pair kern="-67" kpx2="128"/><pair kern="-63" kpx2="173"/><pair kern="-77" kpx2="109"/><pair kern="-137" kpx2="197"/><pair kern="-26" kpx2="92"/><pair kern="-77" kpx2="121"/><pair kern="-77" kpx2="110"/><pair kern="-63" kpx2="174"/></kerning><kerning kpx1="37"><pair kern="-17" kpx2="227"/><pair kern="-17" kpx2="246"/><pair kern="-17" kpx2="251"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-17" kpx2="54"/><pair kern="-54" kpx2="180"/><pair kern="-30" kpx2="169"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="170"/><pair kern="-54" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="210"/><pair kern="-35" kpx2="58"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="50"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="-54" kpx2="181"/><pair kern="-40" kpx2="197"/><pair kern="-17" kpx2="38"/><pair kern="-30" kpx2="57"/><pair kern="-17" kpx2="249"/></kerning><kerning kpx1="120"><pair kern="-72" kpx2="180"/><pair kern="-44" kpx2="197"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="249"><pair kern="18" kpx2="173"/><pair kern="18" kpx2="36"/><pair kern="18" kpx2="201"/><pair kern="18" kpx2="199"/><pair kern="18" kpx2="174"/><pair kern="18" kpx2="98"/></kerning><kerning kpx1="227"><pair kern="18" kpx2="173"/><pair kern="18" kpx2="36"/><pair kern="18" kpx2="201"/><pair kern="18" kpx2="199"/><pair kern="18" kpx2="174"/><pair kern="18" kpx2="98"/></kerning><kerning kpx1="51"><pair kern="-17" kpx2="126"/><pair kern="-44" kpx2="107"/><pair kern="-35" kpx2="72"/><pair kern="-63" kpx2="199"/><pair kern="-21" kpx2="16"/><pair kern="-35" kpx2="123"/><pair kern="-35" kpx2="112"/><pair kern="-21" kpx2="187"/><pair kern="-35" kpx2="113"/><pair kern="-17" kpx2="86"/><pair kern="18" kpx2="180"/><pair kern="-44" kpx2="105"/><pair kern="-17" kpx2="129"/><pair kern="-35" kpx2="124"/><pair kern="-17" kpx2="169"/><pair kern="-63" kpx2="201"/><pair kern="-17" kpx2="85"/><pair kern="-21" kpx2="60"/><pair kern="-44" kpx2="106"/><pair kern="-35" kpx2="125"/><pair kern="-35" kpx2="115"/><pair kern="-21" kpx2="234"/><pair kern="-17" kpx2="88"/><pair kern="-35" kpx2="122"/><pair kern="-44" kpx2="68"/><pair kern="-63" kpx2="36"/><pair kern="-35" kpx2="82"/><pair kern="-35" kpx2="114"/><pair kern="-17" kpx2="250"/><pair kern="-17" kpx2="127"/><pair kern="-44" kpx2="108"/><pair kern="-63" kpx2="98"/><pair kern="-17" kpx2="81"/><pair kern="-21" kpx2="76"/><pair kern="18" kpx2="181"/><pair kern="-155" kpx2="17"/><pair kern="-17" kpx2="128"/><pair kern="-63" kpx2="173"/><pair kern="-44" kpx2="109"/><pair kern="-160" kpx2="197"/><pair kern="-35" kpx2="121"/><pair kern="-17" kpx2="228"/><pair kern="-44" kpx2="110"/><pair kern="-63" kpx2="174"/><pair kern="-17" kpx2="120"/></kerning><kerning kpx1="104"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="72"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="199"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="54"><pair kern="18" kpx2="173"/><pair kern="18" kpx2="36"/><pair kern="18" kpx2="201"/><pair kern="18" kpx2="199"/><pair kern="18" kpx2="174"/><pair kern="18" kpx2="98"/></kerning><kerning kpx1="180"><pair kern="-35" kpx2="235"/><pair kern="-35" kpx2="246"/><pair kern="-30" kpx2="43"/><pair kern="-72" kpx2="123"/><pair kern="-35" kpx2="251"/><pair kern="-35" kpx2="208"/><pair kern="-188" kpx2="144"/><pair kern="-58" kpx2="59"/><pair kern="-35" kpx2="73"/><pair kern="-30" kpx2="41"/><pair kern="-72" kpx2="124"/><pair kern="-54" kpx2="85"/><pair kern="-128" kpx2="201"/><pair kern="-17" kpx2="61"/><pair kern="-35" kpx2="100"/><pair kern="-72" kpx2="122"/><pair kern="-30" kpx2="47"/><pair kern="-35" kpx2="210"/><pair kern="-72" kpx2="82"/><pair kern="-35" kpx2="186"/><pair kern="-35" kpx2="175"/><pair kern="-35" kpx2="209"/><pair kern="-35" kpx2="103"/><pair kern="-128" kpx2="98"/><pair kern="-54" kpx2="81"/><pair kern="-17" kpx2="229"/><pair kern="-35" kpx2="38"/><pair kern="-72" kpx2="121"/><pair kern="-30" kpx2="37"/><pair kern="-54" kpx2="120"/><pair kern="-30" kpx2="51"/><pair kern="-128" kpx2="199"/><pair kern="-30" kpx2="53"/><pair kern="-30" kpx2="137"/><pair kern="-35" kpx2="233"/><pair kern="-35" kpx2="253"/><pair kern="-35" kpx2="52"/><pair kern="-72" kpx2="125"/><pair kern="-35" kpx2="42"/><pair kern="-35" kpx2="90"/><pair kern="-128" kpx2="36"/><pair kern="-35" kpx2="50"/><pair kern="-30" kpx2="39"/><pair kern="-30" kpx2="236"/><pair kern="-30" kpx2="45"/><pair kern="-128" kpx2="173"/><pair kern="-35" kpx2="92"/><pair kern="-35" kpx2="89"/><pair kern="-30" kpx2="46"/><pair kern="-128" kpx2="174"/></kerning><kerning kpx1="53"><pair kern="-21" kpx2="107"/><pair kern="-54" kpx2="235"/><pair kern="-40" kpx2="16"/><pair kern="-44" kpx2="112"/><pair kern="-44" kpx2="123"/><pair kern="-49" kpx2="251"/><pair kern="-44" kpx2="113"/><pair kern="-63" kpx2="187"/><pair kern="-44" kpx2="129"/><pair kern="-44" kpx2="124"/><pair kern="-54" kpx2="169"/><pair kern="-63" kpx2="60"/><pair kern="-40" kpx2="201"/><pair kern="-21" kpx2="106"/><pair kern="-30" kpx2="29"/><pair kern="-63" kpx2="234"/><pair kern="-49" kpx2="100"/><pair kern="-44" kpx2="122"/><pair kern="-21" kpx2="68"/><pair kern="-40" kpx2="58"/><pair kern="-44" kpx2="82"/><pair kern="-54" kpx2="186"/><pair kern="-40" kpx2="98"/><pair kern="-63" kpx2="181"/><pair kern="-35" kpx2="17"/><pair kern="-49" kpx2="38"/><pair kern="-44" kpx2="121"/><pair kern="-54" kpx2="57"/><pair kern="-44" kpx2="126"/><pair kern="-44" kpx2="72"/><pair kern="-40" kpx2="199"/><pair kern="-72" kpx2="180"/><pair kern="-21" kpx2="105"/><pair kern="-49" kpx2="253"/><pair kern="-44" kpx2="125"/><pair kern="-44" kpx2="115"/><pair kern="-17" kpx2="170"/><pair kern="-44" kpx2="88"/><pair kern="-40" kpx2="36"/><pair kern="-44" kpx2="114"/><pair kern="-72" kpx2="55"/><pair kern="-44" kpx2="127"/><pair kern="-21" kpx2="108"/><pair kern="-44" kpx2="128"/><pair kern="-40" kpx2="173"/><pair kern="-21" kpx2="109"/><pair kern="-54" kpx2="92"/><pair kern="-17" kpx2="197"/><pair kern="-21" kpx2="110"/><pair kern="-40" kpx2="174"/></kerning><kerning kpx1="137"><pair kern="-54" kpx2="180"/><pair kern="-40" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="233"><pair kern="-44" kpx2="180"/><pair kern="-35" kpx2="197"/><pair kern="-54" kpx2="181"/></kerning><kerning kpx1="253"><pair kern="-17" kpx2="169"/><pair kern="-17" kpx2="60"/><pair kern="-17" kpx2="187"/><pair kern="18" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-17" kpx2="234"/></kerning><kerning kpx1="211"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning><kerning kpx1="78"><pair kern="-17" kpx2="107"/><pair kern="-30" kpx2="126"/><pair kern="-35" kpx2="235"/><pair kern="-35" kpx2="72"/><pair kern="-35" kpx2="112"/><pair kern="-35" kpx2="123"/><pair kern="-35" kpx2="113"/><pair kern="-17" kpx2="105"/><pair kern="-30" kpx2="129"/><pair kern="-35" kpx2="124"/><pair kern="-17" kpx2="106"/><pair kern="-35" kpx2="125"/><pair kern="-35" kpx2="115"/><pair kern="-30" kpx2="88"/><pair kern="-35" kpx2="122"/><pair kern="-17" kpx2="68"/><pair kern="-35" kpx2="82"/><pair kern="-35" kpx2="114"/><pair kern="-35" kpx2="186"/><pair kern="-30" kpx2="127"/><pair kern="-17" kpx2="108"/><pair kern="-30" kpx2="128"/><pair kern="-17" kpx2="109"/><pair kern="-35" kpx2="92"/><pair kern="-35" kpx2="121"/><pair kern="-17" kpx2="110"/></kerning><kerning kpx1="52"><pair kern="-21" kpx2="180"/><pair kern="-63" kpx2="197"/><pair kern="27" kpx2="16"/><pair kern="-17" kpx2="181"/></kerning><kerning kpx1="125"><pair kern="-72" kpx2="180"/><pair kern="-17" kpx2="17"/><pair kern="-63" kpx2="197"/><pair kern="18" kpx2="16"/><pair kern="-30" kpx2="91"/><pair kern="-35" kpx2="181"/></kerning><kerning kpx1="42"><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="169"/><pair kern="-26" kpx2="197"/><pair kern="-35" kpx2="55"/><pair kern="-49" kpx2="60"/><pair kern="-49" kpx2="187"/><pair kern="-21" kpx2="181"/><pair kern="-17" kpx2="170"/><pair kern="-49" kpx2="234"/></kerning><kerning kpx1="170"><pair kern="-17" kpx2="235"/><pair kern="-35" kpx2="199"/><pair kern="-17" kpx2="251"/><pair kern="-109" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-54" kpx2="59"/><pair kern="-109" kpx2="60"/><pair kern="-35" kpx2="201"/><pair kern="-17" kpx2="253"/><pair kern="-109" kpx2="234"/><pair kern="-17" kpx2="90"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="210"/><pair kern="-35" kpx2="36"/><pair kern="-54" kpx2="58"/><pair kern="-91" kpx2="55"/><pair kern="-17" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="50"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="-17" kpx2="39"/><pair kern="-35" kpx2="98"/><pair kern="-17" kpx2="45"/><pair kern="-35" kpx2="173"/><pair kern="-17" kpx2="92"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="89"/><pair kern="-86" kpx2="57"/><pair kern="-35" kpx2="37"/><pair kern="-35" kpx2="174"/></kerning><kerning kpx1="115"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="90"><pair kern="-91" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-104" kpx2="197"/><pair kern="-54" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="36"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="55"><pair kern="-165" kpx2="107"/><pair kern="-155" kpx2="235"/><pair kern="-91" kpx2="16"/><pair kern="-169" kpx2="112"/><pair kern="-169" kpx2="123"/><pair kern="-58" kpx2="251"/><pair kern="-169" kpx2="113"/><pair kern="-165" kpx2="86"/><pair kern="-151" kpx2="129"/><pair kern="-169" kpx2="124"/><pair kern="-91" kpx2="169"/><pair kern="-169" kpx2="252"/><pair kern="-169" kpx2="70"/><pair kern="-146" kpx2="85"/><pair kern="-77" kpx2="201"/><pair kern="-165" kpx2="106"/><pair kern="-109" kpx2="29"/><pair kern="-58" kpx2="100"/><pair kern="-169" kpx2="122"/><pair kern="-165" kpx2="68"/><pair kern="-169" kpx2="82"/><pair kern="-155" kpx2="186"/><pair kern="-165" kpx2="250"/><pair kern="-77" kpx2="98"/><pair kern="-21" kpx2="181"/><pair kern="-118" kpx2="17"/><pair kern="-58" kpx2="38"/><pair kern="-169" kpx2="121"/><pair kern="-165" kpx2="228"/><pair kern="-169" kpx2="254"/><pair kern="-151" kpx2="126"/><pair kern="-169" kpx2="72"/><pair kern="-77" kpx2="199"/><pair kern="-165" kpx2="105"/><pair kern="-58" kpx2="253"/><pair kern="-169" kpx2="125"/><pair kern="-169" kpx2="115"/><pair kern="-54" kpx2="170"/><pair kern="-151" kpx2="88"/><pair kern="-169" kpx2="111"/><pair kern="-165" kpx2="90"/><pair kern="-77" kpx2="36"/><pair kern="-17" kpx2="55"/><pair kern="-169" kpx2="114"/><pair kern="-151" kpx2="127"/><pair kern="-165" kpx2="108"/><pair kern="-30" kpx2="76"/><pair kern="-151" kpx2="128"/><pair kern="-77" kpx2="173"/><pair kern="-165" kpx2="109"/><pair kern="-155" kpx2="92"/><pair kern="-128" kpx2="197"/><pair kern="-165" kpx2="110"/><pair kern="-77" kpx2="174"/></kerning><kerning kpx1="114"><pair kern="-17" kpx2="91"/></kerning><kerning kpx1="50"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="27" kpx2="16"/><pair kern="-54" kpx2="187"/><pair kern="-17" kpx2="98"/><pair kern="-17" kpx2="181"/><pair kern="-63" kpx2="59"/><pair kern="-40" kpx2="17"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="29"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="91"><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="111"/><pair kern="-30" kpx2="122"/><pair kern="-30" kpx2="82"/><pair kern="-30" kpx2="114"/><pair kern="-30" kpx2="72"/><pair kern="-30" kpx2="112"/><pair kern="-30" kpx2="123"/><pair kern="-30" kpx2="113"/><pair kern="-30" kpx2="124"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-30" kpx2="121"/><pair kern="-30" kpx2="125"/><pair kern="-30" kpx2="115"/></kerning><kerning kpx1="39"><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="199"/><pair kern="-17" kpx2="98"/><pair kern="-54" kpx2="187"/><pair kern="-26" kpx2="181"/><pair kern="-21" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="169"/><pair kern="-91" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-54" kpx2="60"/><pair kern="-17" kpx2="57"/><pair kern="-17" kpx2="174"/><pair kern="-17" kpx2="170"/><pair kern="-54" kpx2="234"/></kerning><kerning kpx1="236"><pair kern="-17" kpx2="180"/><pair kern="-72" kpx2="17"/><pair kern="-91" kpx2="197"/><pair kern="-35" kpx2="29"/></kerning><kerning kpx1="45"><pair kern="-35" kpx2="180"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="36"/><pair kern="-17" kpx2="169"/><pair kern="-54" kpx2="197"/><pair kern="-17" kpx2="201"/><pair kern="-17" kpx2="199"/><pair kern="-35" kpx2="16"/><pair kern="-17" kpx2="174"/><pair kern="-17" kpx2="98"/><pair kern="-30" kpx2="181"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="173"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="197"><pair kern="-35" kpx2="246"/><pair kern="-54" kpx2="235"/><pair kern="-35" kpx2="43"/><pair kern="-35" kpx2="123"/><pair kern="-54" kpx2="251"/><pair kern="-183" kpx2="187"/><pair kern="-54" kpx2="208"/><pair kern="18" kpx2="144"/><pair kern="-35" kpx2="59"/><pair kern="-17" kpx2="73"/><pair kern="-35" kpx2="41"/><pair kern="-35" kpx2="124"/><pair kern="-35" kpx2="85"/><pair kern="-183" kpx2="60"/><pair kern="18" kpx2="201"/><pair kern="-183" kpx2="234"/><pair kern="-54" kpx2="100"/><pair kern="-35" kpx2="122"/><pair kern="-35" kpx2="47"/><pair kern="-54" kpx2="210"/><pair kern="-35" kpx2="82"/><pair kern="-123" kpx2="58"/><pair kern="-54" kpx2="186"/><pair kern="-54" kpx2="175"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-35" kpx2="81"/><pair kern="18" kpx2="98"/><pair kern="-54" kpx2="38"/><pair kern="-35" kpx2="121"/><pair kern="-183" kpx2="57"/><pair kern="-35" kpx2="37"/><pair kern="-35" kpx2="120"/><pair kern="-35" kpx2="51"/><pair kern="18" kpx2="199"/><pair kern="-35" kpx2="53"/><pair kern="-35" kpx2="137"/><pair kern="-35" kpx2="233"/><pair kern="-54" kpx2="253"/><pair kern="-54" kpx2="52"/><pair kern="-35" kpx2="125"/><pair kern="-35" kpx2="42"/><pair kern="-95" kpx2="90"/><pair kern="18" kpx2="36"/><pair kern="-137" kpx2="55"/><pair kern="-54" kpx2="50"/><pair kern="-35" kpx2="39"/><pair kern="-35" kpx2="236"/><pair kern="22" kpx2="45"/><pair kern="18" kpx2="173"/><pair kern="-54" kpx2="92"/><pair kern="-114" kpx2="89"/><pair kern="-35" kpx2="46"/><pair kern="18" kpx2="174"/></kerning><kerning kpx1="92"><pair kern="-142" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-146" kpx2="197"/><pair kern="-17" kpx2="16"/><pair kern="-72" kpx2="29"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="89"><pair kern="-77" kpx2="17"/><pair kern="-17" kpx2="169"/><pair kern="-132" kpx2="197"/><pair kern="-26" kpx2="16"/><pair kern="-54" kpx2="29"/><pair kern="-17" kpx2="181"/><pair kern="-17" kpx2="170"/></kerning><kerning kpx1="46"><pair kern="-17" kpx2="107"/><pair kern="-72" kpx2="235"/><pair kern="-104" kpx2="16"/><pair kern="-49" kpx2="112"/><pair kern="-49" kpx2="123"/><pair kern="-54" kpx2="251"/><pair kern="-26" kpx2="213"/><pair kern="-49" kpx2="113"/><pair kern="-35" kpx2="187"/><pair kern="-54" kpx2="208"/><pair kern="-49" kpx2="129"/><pair kern="-49" kpx2="124"/><pair kern="-63" kpx2="169"/><pair kern="-35" kpx2="60"/><pair kern="-17" kpx2="201"/><pair kern="-17" kpx2="106"/><pair kern="-35" kpx2="234"/><pair kern="-54" kpx2="100"/><pair kern="-49" kpx2="122"/><pair kern="-17" kpx2="68"/><pair kern="-54" kpx2="210"/><pair kern="-35" kpx2="58"/><pair kern="-49" kpx2="82"/><pair kern="-72" kpx2="186"/><pair kern="-54" kpx2="175"/><pair kern="-54" kpx2="209"/><pair kern="-54" kpx2="103"/><pair kern="-17" kpx2="98"/><pair kern="-30" kpx2="181"/><pair kern="-26" kpx2="212"/><pair kern="-54" kpx2="38"/><pair kern="-49" kpx2="121"/><pair kern="-49" kpx2="126"/><pair kern="-26" kpx2="104"/><pair kern="-49" kpx2="72"/><pair kern="-17" kpx2="199"/><pair kern="-30" kpx2="180"/><pair kern="-17" kpx2="105"/><pair kern="-54" kpx2="253"/><pair kern="-26" kpx2="211"/><pair kern="-49" kpx2="125"/><pair kern="-49" kpx2="115"/><pair kern="-49" kpx2="88"/><pair kern="-17" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-49" kpx2="114"/><pair kern="-54" kpx2="50"/><pair kern="-49" kpx2="127"/><pair kern="-17" kpx2="108"/><pair kern="-49" kpx2="128"/><pair kern="-17" kpx2="173"/><pair kern="-17" kpx2="109"/><pair kern="-72" kpx2="92"/><pair kern="-17" kpx2="110"/><pair kern="-17" kpx2="174"/><pair kern="-26" kpx2="56"/></kerning><kerning kpx1="174"><pair kern="-17" kpx2="246"/><pair kern="-67" kpx2="235"/><pair kern="-21" kpx2="16"/><pair kern="-17" kpx2="112"/><pair kern="-17" kpx2="123"/><pair kern="-17" kpx2="251"/><pair kern="-17" kpx2="113"/><pair kern="-77" kpx2="187"/><pair kern="-17" kpx2="208"/><pair kern="-35" kpx2="73"/><pair kern="-17" kpx2="124"/><pair kern="-35" kpx2="169"/><pair kern="-17" kpx2="252"/><pair kern="-17" kpx2="70"/><pair kern="-77" kpx2="60"/><pair kern="27" kpx2="201"/><pair kern="-17" kpx2="29"/><pair kern="-77" kpx2="234"/><pair kern="-17" kpx2="100"/><pair kern="-17" kpx2="122"/><pair kern="-17" kpx2="210"/><pair kern="-17" kpx2="82"/><pair kern="-54" kpx2="58"/><pair kern="-67" kpx2="186"/><pair kern="-17" kpx2="175"/><pair kern="-17" kpx2="209"/><pair kern="-17" kpx2="103"/><pair kern="27" kpx2="98"/><pair kern="-123" kpx2="181"/><pair kern="-17" kpx2="17"/><pair kern="-17" kpx2="38"/><pair kern="-17" kpx2="84"/><pair kern="-17" kpx2="121"/><pair kern="-63" kpx2="57"/><pair kern="-17" kpx2="254"/><pair kern="-17" kpx2="87"/><pair kern="-17" kpx2="72"/><pair kern="27" kpx2="199"/><pair kern="-17" kpx2="71"/><pair kern="-128" kpx2="180"/><pair kern="-17" kpx2="253"/><pair kern="-17" kpx2="52"/><pair kern="-17" kpx2="125"/><pair kern="-17" kpx2="42"/><pair kern="-17" kpx2="115"/><pair kern="-40" kpx2="90"/><pair kern="-17" kpx2="111"/><pair kern="27" kpx2="36"/><pair kern="-77" kpx2="55"/><pair kern="-17" kpx2="114"/><pair kern="-17" kpx2="50"/><pair kern="27" kpx2="173"/><pair kern="-67" kpx2="92"/><pair kern="22" kpx2="197"/><pair kern="-58" kpx2="89"/><pair kern="27" kpx2="174"/></kerning><kerning kpx1="56"><pair kern="-17" kpx2="229"/><pair kern="-17" kpx2="61"/></kerning></font-metrics>
\ No newline at end of file
diff --git a/documentation/template/VeraMoBd.ttf b/documentation/template/VeraMoBd.ttf
new file mode 100644
index 0000000000..9be6547ed6
--- /dev/null
+++ b/documentation/template/VeraMoBd.ttf
diff --git a/documentation/template/VeraMoBd.xml b/documentation/template/VeraMoBd.xml
new file mode 100644
index 0000000000..9b33107a44
--- /dev/null
+++ b/documentation/template/VeraMoBd.xml
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><font-metrics metrics-version="2" type="TYPE0"><font-name>BitstreamVeraSansMono-Bold</font-name><full-name>Bitstream Vera Sans Mono Bold</full-name><family-name>Bitstream Vera Sans Mono</family-name><embed/><cap-height>729</cap-height><x-height>546</x-height><ascender>759</ascender><descender>-240</descender><bbox><left>-19</left><bottom>-235</bottom><right>605</right><top>928</top></bbox><flags>34</flags><stemv>0</stemv><italicangle>0</italicangle><subtype>TYPE0</subtype><multibyte-extras><cid-type>CIDFontType2</cid-type><default-width>0</default-width><bfranges><bf gi="3" ue="126" us="32"/><bf gi="172" ue="160" us="160"/><bf gi="163" ue="161" us="161"/><bf gi="132" ue="163" us="162"/><bf gi="189" ue="164" us="164"/><bf gi="150" ue="165" us="165"/><bf gi="231" ue="166" us="166"/><bf gi="134" ue="167" us="167"/><bf gi="142" ue="168" us="168"/><bf gi="139" ue="169" us="169"/><bf gi="157" ue="170" us="170"/><bf gi="169" ue="171" us="171"/><bf gi="164" ue="172" us="172"/><bf gi="256" ue="173" us="173"/><bf gi="138" ue="174" us="174"/><bf gi="217" ue="175" us="175"/><bf gi="131" ue="176" us="176"/><bf gi="147" ue="177" us="177"/><bf gi="241" ue="179" us="178"/><bf gi="141" ue="180" us="180"/><bf gi="151" ue="181" us="181"/><bf gi="136" ue="182" us="182"/><bf gi="195" ue="183" us="183"/><bf gi="221" ue="184" us="184"/><bf gi="240" ue="185" us="185"/><bf gi="158" ue="186" us="186"/><bf gi="170" ue="187" us="187"/><bf gi="243" ue="190" us="188"/><bf gi="162" ue="191" us="191"/><bf gi="173" ue="192" us="192"/><bf gi="201" ue="193" us="193"/><bf gi="199" ue="194" us="194"/><bf gi="174" ue="195" us="195"/><bf gi="98" ue="197" us="196"/><bf gi="144" ue="198" us="198"/><bf gi="100" ue="199" us="199"/><bf gi="203" ue="200" us="200"/><bf gi="101" ue="201" us="201"/><bf gi="200" ue="202" us="202"/><bf gi="202" ue="203" us="203"/><bf gi="207" ue="204" us="204"/><bf gi="204" ue="207" us="205"/><bf gi="232" ue="208" us="208"/><bf gi="102" ue="209" us="209"/><bf gi="210" ue="210" us="210"/><bf gi="208" ue="212" us="211"/><bf gi="175" ue="213" us="213"/><bf gi="103" ue="214" us="214"/><bf gi="239" ue="215" us="215"/><bf gi="145" ue="216" us="216"/><bf gi="213" ue="217" us="217"/><bf gi="211" ue="219" us="218"/><bf gi="104" ue="220" us="220"/><bf gi="234" ue="221" us="221"/><bf gi="236" ue="222" us="222"/><bf gi="137" ue="223" us="223"/><bf gi="106" ue="224" us="224"/><bf gi="105" ue="225" us="225"/><bf gi="107" ue="226" us="226"/><bf gi="109" ue="227" us="227"/><bf gi="108" ue="228" us="228"/><bf gi="110" ue="229" us="229"/><bf gi="160" ue="230" us="230"/><bf gi="111" ue="231" us="231"/><bf gi="113" ue="232" us="232"/><bf gi="112" ue="233" us="233"/><bf gi="114" ue="235" us="234"/><bf gi="117" ue="236" us="236"/><bf gi="116" ue="237" us="237"/><bf gi="118" ue="239" us="238"/><bf gi="233" ue="240" us="240"/><bf gi="120" ue="241" us="241"/><bf gi="122" ue="242" us="242"/><bf gi="121" ue="243" us="243"/><bf gi="123" ue="244" us="244"/><bf gi="125" ue="245" us="245"/><bf gi="124" ue="246" us="246"/><bf gi="184" ue="247" us="247"/><bf gi="161" ue="248" us="248"/><bf gi="127" ue="249" us="249"/><bf gi="126" ue="250" us="250"/><bf gi="128" ue="252" us="251"/><bf gi="235" ue="253" us="253"/><bf gi="237" ue="254" us="254"/><bf gi="186" ue="255" us="255"/><bf gi="251" ue="263" us="262"/><bf gi="253" ue="269" us="268"/><bf gi="0" ue="270" us="270"/><bf gi="0" ue="271" us="271"/><bf gi="0" ue="272" us="272"/><bf gi="255" ue="273" us="273"/><bf gi="246" ue="287" us="286"/><bf gi="248" ue="304" us="304"/><bf gi="214" ue="305" us="305"/><bf gi="225" ue="322" us="321"/><bf gi="176" ue="339" us="338"/><bf gi="249" ue="351" us="350"/><bf gi="227" ue="353" us="352"/><bf gi="187" ue="376" us="376"/><bf gi="229" ue="382" us="381"/><bf gi="166" ue="402" us="402"/><bf gi="215" ue="710" us="710"/><bf gi="224" ue="711" us="711"/><bf gi="218" ue="730" us="728"/><bf gi="223" ue="731" us="731"/><bf gi="216" ue="732" us="732"/><bf gi="222" ue="733" us="733"/><bf gi="159" ue="937" us="937"/><bf gi="155" ue="960" us="960"/><bf gi="178" ue="8212" us="8211"/><bf gi="0" ue="8213" us="8213"/><bf gi="0" ue="8214" us="8214"/><bf gi="0" ue="8215" us="8215"/><bf gi="182" ue="8217" us="8216"/><bf gi="196" ue="8218" us="8218"/><bf gi="0" ue="8219" us="8219"/><bf gi="180" ue="8221" us="8220"/><bf gi="197" ue="8222" us="8222"/><bf gi="0" ue="8223" us="8223"/><bf gi="130" ue="8224" us="8224"/><bf gi="194" ue="8225" us="8225"/><bf gi="135" ue="8226" us="8226"/><bf gi="0" ue="8227" us="8227"/><bf gi="0" ue="8228" us="8228"/><bf gi="0" ue="8229" us="8229"/><bf gi="171" ue="8230" us="8230"/><bf gi="198" ue="8240" us="8240"/><bf gi="190" ue="8250" us="8249"/><bf gi="258" ue="8364" us="8364"/><bf gi="140" ue="8482" us="8482"/><bf gi="152" ue="8706" us="8706"/><bf gi="0" ue="8707" us="8707"/><bf gi="0" ue="8708" us="8708"/><bf gi="0" ue="8709" us="8709"/><bf gi="168" ue="8710" us="8710"/><bf gi="154" ue="8719" us="8719"/><bf gi="0" ue="8720" us="8720"/><bf gi="153" ue="8721" us="8721"/><bf gi="238" ue="8722" us="8722"/><bf gi="0" ue="8723" us="8723"/><bf gi="0" ue="8724" us="8724"/><bf gi="188" ue="8725" us="8725"/><bf gi="0" ue="8726" us="8726"/><bf gi="0" ue="8727" us="8727"/><bf gi="0" ue="8728" us="8728"/><bf gi="257" ue="8729" us="8729"/><bf gi="165" ue="8730" us="8730"/><bf gi="0" ue="8731" us="8731"/><bf gi="0" ue="8732" us="8732"/><bf gi="0" ue="8733" us="8733"/><bf gi="146" ue="8734" us="8734"/><bf gi="156" ue="8747" us="8747"/><bf gi="167" ue="8776" us="8776"/><bf gi="143" ue="8800" us="8800"/><bf gi="0" ue="8801" us="8801"/><bf gi="0" ue="8802" us="8802"/><bf gi="0" ue="8803" us="8803"/><bf gi="148" ue="8805" us="8804"/><bf gi="185" ue="9674" us="9674"/><bf gi="192" ue="64258" us="64257"/><bf gi="0" ue="65535" us="65535"/></bfranges><cid-widths start-index="0"><wx w="602"/><wx w="0"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/></cid-widths></multibyte-extras></font-metrics>
\ No newline at end of file
diff --git a/documentation/template/VeraMono.ttf b/documentation/template/VeraMono.ttf
new file mode 100644
index 0000000000..139f0b4311
--- /dev/null
+++ b/documentation/template/VeraMono.ttf
diff --git a/documentation/template/VeraMono.xml b/documentation/template/VeraMono.xml
new file mode 100644
index 0000000000..3a0a86659c
--- /dev/null
+++ b/documentation/template/VeraMono.xml
@@ -0,0 +1 @@
+<?xml version="1.0" encoding="UTF-8"?><font-metrics metrics-version="2" type="TYPE0"><font-name>BitstreamVeraSansMono-Roman</font-name><full-name>Bitstream Vera Sans Mono</full-name><family-name>Bitstream Vera Sans Mono</family-name><embed/><cap-height>729</cap-height><x-height>546</x-height><ascender>759</ascender><descender>-240</descender><bbox><left>-4</left><bottom>-235</bottom><right>605</right><top>928</top></bbox><flags>34</flags><stemv>0</stemv><italicangle>0</italicangle><subtype>TYPE0</subtype><multibyte-extras><cid-type>CIDFontType2</cid-type><default-width>0</default-width><bfranges><bf gi="3" ue="126" us="32"/><bf gi="172" ue="160" us="160"/><bf gi="163" ue="161" us="161"/><bf gi="132" ue="163" us="162"/><bf gi="189" ue="164" us="164"/><bf gi="150" ue="165" us="165"/><bf gi="231" ue="166" us="166"/><bf gi="134" ue="167" us="167"/><bf gi="142" ue="168" us="168"/><bf gi="139" ue="169" us="169"/><bf gi="157" ue="170" us="170"/><bf gi="169" ue="171" us="171"/><bf gi="164" ue="172" us="172"/><bf gi="256" ue="173" us="173"/><bf gi="138" ue="174" us="174"/><bf gi="217" ue="175" us="175"/><bf gi="131" ue="176" us="176"/><bf gi="147" ue="177" us="177"/><bf gi="241" ue="179" us="178"/><bf gi="141" ue="180" us="180"/><bf gi="151" ue="181" us="181"/><bf gi="136" ue="182" us="182"/><bf gi="195" ue="183" us="183"/><bf gi="221" ue="184" us="184"/><bf gi="240" ue="185" us="185"/><bf gi="158" ue="186" us="186"/><bf gi="170" ue="187" us="187"/><bf gi="243" ue="190" us="188"/><bf gi="162" ue="191" us="191"/><bf gi="173" ue="192" us="192"/><bf gi="201" ue="193" us="193"/><bf gi="199" ue="194" us="194"/><bf gi="174" ue="195" us="195"/><bf gi="98" ue="197" us="196"/><bf gi="144" ue="198" us="198"/><bf gi="100" ue="199" us="199"/><bf gi="203" ue="200" us="200"/><bf gi="101" ue="201" us="201"/><bf gi="200" ue="202" us="202"/><bf gi="202" ue="203" us="203"/><bf gi="207" ue="204" us="204"/><bf gi="204" ue="207" us="205"/><bf gi="232" ue="208" us="208"/><bf gi="102" ue="209" us="209"/><bf gi="210" ue="210" us="210"/><bf gi="208" ue="212" us="211"/><bf gi="175" ue="213" us="213"/><bf gi="103" ue="214" us="214"/><bf gi="239" ue="215" us="215"/><bf gi="145" ue="216" us="216"/><bf gi="213" ue="217" us="217"/><bf gi="211" ue="219" us="218"/><bf gi="104" ue="220" us="220"/><bf gi="234" ue="221" us="221"/><bf gi="236" ue="222" us="222"/><bf gi="137" ue="223" us="223"/><bf gi="106" ue="224" us="224"/><bf gi="105" ue="225" us="225"/><bf gi="107" ue="226" us="226"/><bf gi="109" ue="227" us="227"/><bf gi="108" ue="228" us="228"/><bf gi="110" ue="229" us="229"/><bf gi="160" ue="230" us="230"/><bf gi="111" ue="231" us="231"/><bf gi="113" ue="232" us="232"/><bf gi="112" ue="233" us="233"/><bf gi="114" ue="235" us="234"/><bf gi="117" ue="236" us="236"/><bf gi="116" ue="237" us="237"/><bf gi="118" ue="239" us="238"/><bf gi="233" ue="240" us="240"/><bf gi="120" ue="241" us="241"/><bf gi="122" ue="242" us="242"/><bf gi="121" ue="243" us="243"/><bf gi="123" ue="244" us="244"/><bf gi="125" ue="245" us="245"/><bf gi="124" ue="246" us="246"/><bf gi="184" ue="247" us="247"/><bf gi="161" ue="248" us="248"/><bf gi="127" ue="249" us="249"/><bf gi="126" ue="250" us="250"/><bf gi="128" ue="252" us="251"/><bf gi="235" ue="253" us="253"/><bf gi="237" ue="254" us="254"/><bf gi="186" ue="255" us="255"/><bf gi="251" ue="263" us="262"/><bf gi="253" ue="269" us="268"/><bf gi="0" ue="270" us="270"/><bf gi="0" ue="271" us="271"/><bf gi="0" ue="272" us="272"/><bf gi="255" ue="273" us="273"/><bf gi="246" ue="287" us="286"/><bf gi="248" ue="304" us="304"/><bf gi="214" ue="305" us="305"/><bf gi="225" ue="322" us="321"/><bf gi="176" ue="339" us="338"/><bf gi="249" ue="351" us="350"/><bf gi="227" ue="353" us="352"/><bf gi="187" ue="376" us="376"/><bf gi="229" ue="382" us="381"/><bf gi="166" ue="402" us="402"/><bf gi="215" ue="710" us="710"/><bf gi="224" ue="711" us="711"/><bf gi="218" ue="730" us="728"/><bf gi="223" ue="731" us="731"/><bf gi="216" ue="732" us="732"/><bf gi="222" ue="733" us="733"/><bf gi="159" ue="937" us="937"/><bf gi="155" ue="960" us="960"/><bf gi="178" ue="8212" us="8211"/><bf gi="0" ue="8213" us="8213"/><bf gi="0" ue="8214" us="8214"/><bf gi="0" ue="8215" us="8215"/><bf gi="182" ue="8217" us="8216"/><bf gi="196" ue="8218" us="8218"/><bf gi="0" ue="8219" us="8219"/><bf gi="180" ue="8221" us="8220"/><bf gi="197" ue="8222" us="8222"/><bf gi="0" ue="8223" us="8223"/><bf gi="130" ue="8224" us="8224"/><bf gi="194" ue="8225" us="8225"/><bf gi="135" ue="8226" us="8226"/><bf gi="0" ue="8227" us="8227"/><bf gi="0" ue="8228" us="8228"/><bf gi="0" ue="8229" us="8229"/><bf gi="171" ue="8230" us="8230"/><bf gi="198" ue="8240" us="8240"/><bf gi="190" ue="8250" us="8249"/><bf gi="258" ue="8364" us="8364"/><bf gi="140" ue="8482" us="8482"/><bf gi="152" ue="8706" us="8706"/><bf gi="0" ue="8707" us="8707"/><bf gi="0" ue="8708" us="8708"/><bf gi="0" ue="8709" us="8709"/><bf gi="168" ue="8710" us="8710"/><bf gi="154" ue="8719" us="8719"/><bf gi="0" ue="8720" us="8720"/><bf gi="153" ue="8721" us="8721"/><bf gi="238" ue="8722" us="8722"/><bf gi="0" ue="8723" us="8723"/><bf gi="0" ue="8724" us="8724"/><bf gi="188" ue="8725" us="8725"/><bf gi="0" ue="8726" us="8726"/><bf gi="0" ue="8727" us="8727"/><bf gi="0" ue="8728" us="8728"/><bf gi="257" ue="8729" us="8729"/><bf gi="165" ue="8730" us="8730"/><bf gi="0" ue="8731" us="8731"/><bf gi="0" ue="8732" us="8732"/><bf gi="0" ue="8733" us="8733"/><bf gi="146" ue="8734" us="8734"/><bf gi="156" ue="8747" us="8747"/><bf gi="167" ue="8776" us="8776"/><bf gi="143" ue="8800" us="8800"/><bf gi="0" ue="8801" us="8801"/><bf gi="0" ue="8802" us="8802"/><bf gi="0" ue="8803" us="8803"/><bf gi="148" ue="8805" us="8804"/><bf gi="185" ue="9674" us="9674"/><bf gi="192" ue="64258" us="64257"/><bf gi="0" ue="65535" us="65535"/></bfranges><cid-widths start-index="0"><wx w="602"/><wx w="0"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/><wx w="602"/></cid-widths></multibyte-extras></font-metrics>
\ No newline at end of file
diff --git a/documentation/template/draft.png b/documentation/template/draft.png
new file mode 100644
index 0000000000..53051a9ddd
--- /dev/null
+++ b/documentation/template/draft.png
diff --git a/documentation/template/fop-config.xml b/documentation/template/fop-config.xml
new file mode 100644
index 0000000000..09cc5ca0f5
--- /dev/null
+++ b/documentation/template/fop-config.xml
@@ -0,0 +1,58 @@
+<fop version="1.0">
+
+  <!-- Strict user configuration -->
+  <strict-configuration>true</strict-configuration>
+
+  <!-- Strict FO validation -->
+  <strict-validation>true</strict-validation>
+
+   <!--
+    Set the baseDir so common/openedhand.svg references in plans still
+    work ok. Note, relative file references to current dir should still work.
+    --> 
+  <base>../template</base>
+  <font-base>../template</font-base>
+ 
+  <!-- Source resolution in dpi (dots/pixels per inch) for determining the
+       size of pixels in SVG and bitmap images, default: 72dpi -->
+  <!-- <source-resolution>72</source-resolution> -->
+  <!-- Target resolution in dpi (dots/pixels per inch) for specifying the
+       target resolution for generated bitmaps, default: 72dpi -->
+  <!-- <target-resolution>72</target-resolution> -->
+ 
+  <!-- default page-height and page-width, in case
+       value is specified as auto -->
+  <default-page-settings height="11in" width="8.26in"/> 
+ 
+  <!-- <use-cache>false</use-cache> -->
+ 
+  <renderers>
+    <renderer mime="application/pdf">
+      <fonts>
+        <font  metrics-file="VeraMono.xml"
+               kerning="yes" 
+               embed-url="VeraMono.ttf">
+          <font-triplet name="veramono" style="normal" weight="normal"/>
+        </font>
+
+        <font  metrics-file="VeraMoBd.xml"
+               kerning="yes" 
+               embed-url="VeraMoBd.ttf">
+          <font-triplet name="veramono" style="normal" weight="bold"/>
+        </font>
+
+        <font  metrics-file="Vera.xml"
+               kerning="yes" 
+               embed-url="Vera.ttf">
+          <font-triplet name="verasans" style="normal" weight="normal"/>
+          <font-triplet name="verasans" style="normal" weight="bold"/>
+          <font-triplet name="verasans" style="italic" weight="normal"/>
+          <font-triplet name="verasans" style="italic" weight="bold"/>
+        </font>
+        
+        <auto-detect/>
+      </fonts>
+    </renderer>
+  </renderers>
+</fop>
+
diff --git a/documentation/template/ohand-color.svg b/documentation/template/ohand-color.svg
new file mode 100644
index 0000000000..e42ff9c6fc
--- /dev/null
+++ b/documentation/template/ohand-color.svg
@@ -0,0 +1,150 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://web.resource.org/cc/"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="141.17999"
+   height="55.34"
+   id="svg2207"
+   sodipodi:version="0.32"
+   inkscape:version="0.45"
+   version="1.0"
+   sodipodi:docname="ohand-color.svg"
+   inkscape:output_extension="org.inkscape.output.svg.inkscape"
+   sodipodi:docbase="/home/mallum/Projects/admin/oh-doc-tools/common"
+   sodipodi:modified="true">
+  <defs
+     id="defs3" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.2"
+     inkscape:cx="160"
+     inkscape:cy="146.21189"
+     inkscape:document-units="mm"
+     inkscape:current-layer="layer1"
+     height="55.34px"
+     width="141.18px"
+     inkscape:window-width="772"
+     inkscape:window-height="581"
+     inkscape:window-x="5"
+     inkscape:window-y="48" />
+  <metadata
+     id="metadata2211">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <g
+       id="g2094"
+       style="fill:#6d6d70;fill-opacity:1"
+       inkscape:export-filename="/home/mallum/Desktop/g2126.png"
+       inkscape:export-xdpi="312.71841"
+       inkscape:export-ydpi="312.71841"
+       transform="matrix(0.5954767,0,0,0.5954767,31.793058,-18.471052)">
+      <g
+         id="g19"
+         style="fill:#6d6d70;fill-opacity:1">
+        <path
+           style="fill:#6d6d70;fill-opacity:1"
+           id="path21"
+           d="M 48.693,50.633 C 40.282,50.633 33.439,57.477 33.439,65.888 L 33.439,81.142 L 41.066,81.142 L 41.066,65.888 C 41.066,61.684 44.486,58.261 48.692,58.261 C 52.897,58.261 56.32,61.684 56.32,65.888 C 56.32,70.093 52.897,73.516 48.692,73.516 C 45.677,73.516 43.065,71.756 41.828,69.211 L 41.828,79.504 C 43.892,80.549 46.224,81.142 48.692,81.142 C 57.103,81.142 63.947,74.3 63.947,65.888 C 63.948,57.477 57.104,50.633 48.693,50.633 z " />
+      </g>
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path23"
+         d="M 18.486,50.557 C 26.942,50.557 33.819,57.435 33.819,65.888 C 33.819,74.344 26.942,81.223 18.486,81.223 C 10.032,81.223 3.152,74.344 3.152,65.888 C 3.152,57.435 10.032,50.557 18.486,50.557 z M 18.486,73.556 C 22.713,73.556 26.153,70.118 26.153,65.888 C 26.153,61.661 22.713,58.222 18.486,58.222 C 14.258,58.222 10.819,61.661 10.819,65.888 C 10.82,70.117 14.259,73.556 18.486,73.556 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path25"
+         d="M 94.074,107.465 L 94.074,96.016 C 94.074,87.605 87.233,80.763 78.822,80.763 C 70.41,80.763 63.567,87.605 63.567,96.016 C 63.567,104.427 70.41,111.269 78.822,111.269 C 81.289,111.269 83.621,110.676 85.685,109.631 L 85.685,99.339 C 84.448,101.885 81.836,103.644 78.822,103.644 C 74.615,103.644 71.194,100.221 71.194,96.016 C 71.194,91.81 74.615,88.388 78.822,88.388 C 83.026,88.388 86.448,91.81 86.448,96.016 L 86.448,107.456 C 86.448,109.562 88.156,111.268 90.262,111.268 C 92.364,111.269 94.068,109.566 94.074,107.465 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path27"
+         d="M 124.197,95.814 C 124.088,87.496 117.293,80.762 108.949,80.762 C 100.59,80.762 93.783,87.52 93.697,95.856 L 93.693,95.856 L 93.695,107.456 C 93.695,109.562 95.402,111.268 97.509,111.268 C 99.611,111.268 101.316,109.566 101.321,107.464 L 101.321,95.994 L 101.321,95.994 C 101.333,91.798 104.747,88.388 108.948,88.388 C 113.147,88.388 116.563,91.798 116.575,95.994 L 116.575,107.456 C 116.575,109.562 118.282,111.268 120.387,111.268 C 122.492,111.268 124.201,109.562 124.201,107.456 L 124.201,95.814 L 124.197,95.814 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path29"
+         d="M 63.946,96.005 L 63.946,95.854 L 63.943,95.854 L 63.943,95.815 L 63.942,95.815 C 63.833,87.497 57.037,80.761 48.693,80.761 C 48.682,80.761 48.671,80.763 48.658,80.763 C 48.382,80.763 48.107,80.772 47.833,80.786 C 47.75,80.791 47.668,80.799 47.586,80.806 C 47.378,80.822 47.172,80.838 46.968,80.862 C 46.884,80.873 46.801,80.882 46.719,80.893 C 46.508,80.92 46.298,80.952 46.091,80.987 C 46.024,80.999 45.958,81.01 45.891,81.024 C 45.649,81.068 45.406,81.119 45.168,81.175 C 45.14,81.183 45.112,81.189 45.085,81.195 C 43.656,81.542 42.306,82.092 41.065,82.812 L 41.065,80.761 L 33.438,80.761 L 33.438,95.857 L 33.435,95.857 L 33.435,107.457 C 33.435,109.563 35.142,111.269 37.248,111.269 C 39.093,111.269 40.632,109.958 40.984,108.217 C 41.036,107.963 41.065,107.702 41.065,107.435 L 41.065,95.873 C 41.086,94.732 41.357,93.65 41.828,92.685 L 41.828,92.693 C 42.598,91.106 43.905,89.824 45.511,89.085 C 45.519,89.08 45.529,89.076 45.536,89.073 C 45.849,88.928 46.174,88.807 46.508,88.707 C 46.523,88.704 46.536,88.699 46.55,88.696 C 46.699,88.651 46.85,88.614 47.004,88.576 C 47.025,88.575 47.046,88.567 47.069,88.562 C 47.234,88.527 47.402,88.495 47.572,88.469 C 47.586,88.468 47.6,88.466 47.615,88.463 C 47.763,88.443 47.916,88.427 48.067,88.415 C 48.106,88.41 48.145,88.407 48.186,88.404 C 48.352,88.393 48.52,88.386 48.691,88.386 C 52.888,88.387 56.304,91.797 56.316,95.992 L 56.316,107.454 C 56.316,109.56 58.023,111.266 60.13,111.266 C 61.976,111.266 63.516,109.954 63.867,108.211 C 63.919,107.963 63.946,107.706 63.946,107.442 L 63.946,96.024 C 63.946,96.021 63.947,96.018 63.947,96.015 C 63.948,96.011 63.946,96.008 63.946,96.005 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path31"
+         d="M 180.644,50.633 C 178.539,50.633 176.832,52.341 176.832,54.447 L 176.832,65.887 C 176.832,70.092 173.41,73.513 169.203,73.513 C 164.998,73.513 161.576,70.092 161.576,65.887 C 161.576,61.683 164.998,58.26 169.203,58.26 C 172.219,58.26 174.83,60.019 176.068,62.565 L 176.068,52.271 C 174.004,51.225 171.673,50.632 169.203,50.632 C 160.793,50.632 153.951,57.476 153.951,65.887 C 153.951,74.298 160.793,81.141 169.203,81.141 C 177.615,81.141 184.459,74.298 184.459,65.887 L 184.459,54.447 C 184.458,52.341 182.751,50.633 180.644,50.633 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path33"
+         d="M 124.203,77.339 L 124.203,65.687 L 124.197,65.687 C 124.088,57.371 117.293,50.633 108.949,50.633 C 100.592,50.633 93.783,57.393 93.697,65.731 L 93.695,65.731 L 93.695,65.877 C 93.695,65.882 93.693,65.885 93.693,65.888 C 93.693,65.891 93.695,65.896 93.695,65.899 L 93.695,77.33 C 93.695,79.435 95.402,81.142 97.509,81.142 C 99.614,81.142 101.321,79.435 101.321,77.33 L 101.321,65.868 C 101.333,61.672 104.747,58.261 108.948,58.261 C 113.147,58.261 116.563,61.672 116.575,65.868 L 116.575,65.868 L 116.575,77.329 C 116.575,79.434 118.282,81.141 120.389,81.141 C 122.492,81.142 124.197,79.44 124.203,77.339 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path35"
+         d="M 150.517,80.761 C 148.41,80.761 146.703,82.469 146.703,84.575 L 146.703,96.015 C 146.703,100.22 143.283,103.643 139.076,103.643 C 134.871,103.643 131.449,100.22 131.449,96.015 C 131.449,91.808 134.871,88.387 139.076,88.387 C 142.092,88.387 144.703,90.145 145.941,92.692 L 145.941,82.397 C 143.875,81.353 141.545,80.76 139.076,80.76 C 130.666,80.76 123.822,87.604 123.822,96.015 C 123.822,104.426 130.666,111.268 139.076,111.268 C 147.486,111.268 154.33,104.426 154.33,96.015 L 154.33,84.575 C 154.33,82.469 152.623,80.761 150.517,80.761 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path37"
+         d="M 82.625,77.345 C 82.625,75.247 80.923,73.547 78.826,73.547 L 78.826,81.142 C 80.922,81.142 82.625,79.442 82.625,77.345 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path39"
+         d="M 90.252,69.685 C 92.35,69.685 94.048,67.987 94.048,65.888 L 86.453,65.888 C 86.453,67.986 88.154,69.685 90.252,69.685 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path41"
+         d="M 93.832,77.329 C 93.832,75.223 92.125,73.516 90.018,73.516 L 78.825,73.516 C 74.619,73.516 71.199,70.093 71.199,65.888 C 71.199,61.684 74.619,58.261 78.825,58.261 C 83.032,58.261 86.453,61.684 86.453,65.888 C 86.453,68.904 84.694,71.514 82.149,72.752 L 92.442,72.752 C 93.488,70.689 94.08,68.356 94.08,65.888 C 94.08,57.477 87.237,50.633 78.826,50.633 C 70.415,50.633 63.571,57.477 63.571,65.888 C 63.571,74.3 70.415,81.142 78.826,81.142 L 90.018,81.142 C 92.125,81.142 93.832,79.435 93.832,77.329 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path43"
+         d="M 142.869,77.345 C 142.869,75.247 141.168,73.547 139.07,73.547 L 139.07,81.142 C 141.167,81.142 142.869,79.442 142.869,77.345 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path45"
+         d="M 150.496,69.685 C 152.594,69.685 154.293,67.987 154.293,65.888 L 146.699,65.888 C 146.699,67.986 148.398,69.685 150.496,69.685 z " />
+      <path
+         style="fill:#6d6d70;fill-opacity:1"
+         id="path47"
+         d="M 154.076,77.329 C 154.076,75.223 152.367,73.516 150.262,73.516 L 139.07,73.516 C 134.865,73.516 131.443,70.093 131.443,65.888 C 131.443,61.684 134.865,58.261 139.07,58.261 C 143.275,58.261 146.699,61.684 146.699,65.888 C 146.699,68.904 144.939,71.514 142.392,72.752 L 152.687,72.752 C 153.73,70.689 154.324,68.356 154.324,65.888 C 154.324,57.477 147.48,50.633 139.07,50.633 C 130.66,50.633 123.816,57.477 123.816,65.888 C 123.816,74.3 130.66,81.142 139.07,81.142 L 150.261,81.142 C 152.367,81.142 154.076,79.435 154.076,77.329 z " />
+    </g>
+    <g
+       id="g2126"
+       transform="matrix(0.7679564,0,0,0.7679564,-66.520631,11.42903)"
+       inkscape:export-xdpi="312.71841"
+       inkscape:export-ydpi="312.71841"
+       style="fill:#35992a;fill-opacity:1">
+      <g
+         transform="translate(86.33975,4.23985e-2)"
+         style="fill:#35992a;fill-opacity:1"
+         id="g2114">
+        <g
+           style="fill:#35992a;fill-opacity:1"
+           id="g2116">
+          <path
+             id="path2118"
+             transform="translate(-86.33975,-4.239934e-2)"
+             d="M 89.96875,0.03125 C 87.962748,0.031250001 86.34375,1.6815001 86.34375,3.6875 L 86.34375,17.71875 L 86.34375,19.6875 L 86.34375,28.90625 C 86.343752,39.06825 94.61925,47.34375 104.78125,47.34375 L 113.375,47.34375 L 123.1875,47.34375 L 127.15625,47.34375 C 129.16325,47.343749 130.8125,45.72475 130.8125,43.71875 C 130.8125,41.71275 129.16325,40.09375 127.15625,40.09375 L 123.1875,40.09375 L 123.1875,19.6875 L 123.1875,14.65625 L 123.1875,3.6875 C 123.1875,1.6815 121.5675,0.03125 119.5625,0.03125 C 117.5555,0.031250001 115.9375,1.6815001 115.9375,3.6875 L 115.9375,14.28125 C 115.1185,13.65425 114.26275,13.109 113.34375,12.625 L 113.34375,3.6875 C 113.34475,1.6815 111.6925,0.03125 109.6875,0.03125 C 107.6825,0.031250001 106.0625,1.6815001 106.0625,3.6875 L 106.0625,10.5625 C 105.6305,10.5325 105.22025,10.5 104.78125,10.5 C 104.34125,10.5 103.90075,10.5325 103.46875,10.5625 L 103.46875,3.6875 C 103.46975,1.6815 101.84975,0.03125 99.84375,0.03125 C 97.837749,0.031250001 96.21875,1.6815001 96.21875,3.6875 L 96.21875,12.625 C 95.299754,13.109 94.41375,13.65425 93.59375,14.28125 L 93.59375,3.6875 C 93.59475,1.6815 91.97475,0.03125 89.96875,0.03125 z M 104.78125,14.34375 C 112.80825,14.34375 119.3125,20.87925 119.3125,28.90625 C 119.3125,36.93325 112.80825,43.46875 104.78125,43.46875 C 96.754254,43.46875 90.21875,36.93425 90.21875,28.90625 C 90.218752,20.87825 96.753253,14.34375 104.78125,14.34375 z "
+             style="fill:#35992a;fill-opacity:1" />
+        </g>
+      </g>
+      <path
+         style="fill:#35992a;fill-opacity:1"
+         id="path2122"
+         d="M 112.04875,28.913399 C 112.04875,24.899399 108.78275,21.634399 104.76975,21.634399 C 100.75675,21.634399 97.490753,24.900399 97.490753,28.913399 C 97.490753,32.926399 100.75675,36.192399 104.76975,36.192399 C 108.78275,36.192399 112.04875,32.927399 112.04875,28.913399 z " />
+    </g>
+  </g>
+</svg>
diff --git a/documentation/template/poky-db-pdf.xsl b/documentation/template/poky-db-pdf.xsl
new file mode 100644
index 0000000000..f8a3df103d
--- /dev/null
+++ b/documentation/template/poky-db-pdf.xsl
@@ -0,0 +1,64 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl" />
+
+  <!-- check project-plan.sh for how this is generated, needed to tweak
+       the cover page
+    -->
+  <xsl:include href="/tmp/titlepage.xsl"/>
+
+  <!-- To force a page break in document, i.e per section add a
+      <?hard-pagebreak?> tag.
+  -->
+ <xsl:template match="processing-instruction('hard-pagebreak')">
+   <fo:block break-before='page' />
+ </xsl:template>
+
+  <!--Fix for defualt indent getting TOC all wierd..
+      See http://sources.redhat.com/ml/docbook-apps/2005-q1/msg00455.html
+      FIXME: must be a better fix
+    -->
+  <xsl:param name="body.start.indent" select="'0'"/>
+  <!--<xsl:param name="title.margin.left" select="'0'"/>-->
+
+  <!-- stop long-ish header titles getting wrapped -->
+  <xsl:param name="header.column.widths">1 10 1</xsl:param>
+
+  <!-- customise headers and footers a little -->
+
+  <xsl:template name="head.sep.rule">
+   <xsl:if test="$header.rule != 0">
+     <xsl:attribute name="border-bottom-width">0.5pt</xsl:attribute>
+     <xsl:attribute name="border-bottom-style">solid</xsl:attribute>
+     <xsl:attribute name="border-bottom-color">#999999</xsl:attribute>
+   </xsl:if>
+  </xsl:template>
+
+  <xsl:template name="foot.sep.rule">
+    <xsl:if test="$footer.rule != 0">
+     <xsl:attribute name="border-top-width">0.5pt</xsl:attribute>
+     <xsl:attribute name="border-top-style">solid</xsl:attribute>
+     <xsl:attribute name="border-top-color">#999999</xsl:attribute>
+    </xsl:if>
+  </xsl:template>
+
+  <xsl:attribute-set name="header.content.properties">
+    <xsl:attribute name="color">#999999</xsl:attribute>
+  </xsl:attribute-set>
+
+  <xsl:attribute-set name="footer.content.properties">
+    <xsl:attribute name="color">#999999</xsl:attribute>
+  </xsl:attribute-set>
+
+
+  <!-- general settings -->
+
+  <xsl:param name="fop1.extensions" select="1"></xsl:param>
+  <xsl:param name="paper.type" select="'A4'"></xsl:param>
+  <xsl:param name="section.autolabel" select="1"></xsl:param>
+  <xsl:param name="body.font.family" select="'verasans'"></xsl:param>
+  <xsl:param name="title.font.family" select="'verasans'"></xsl:param>
+  <xsl:param name="monospace.font.family" select="'veramono'"></xsl:param>
+
+</xsl:stylesheet>
diff --git a/documentation/template/poky-ref-manual.png b/documentation/template/poky-ref-manual.png
new file mode 100644
index 0000000000..2085edb467
--- /dev/null
+++ b/documentation/template/poky-ref-manual.png
diff --git a/documentation/template/poky.svg b/documentation/template/poky.svg
new file mode 100644
index 0000000000..a4ea5e2f45
--- /dev/null
+++ b/documentation/template/poky.svg
@@ -0,0 +1,163 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+<svg
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   version="1.0"
+   width="158.56076"
+   height="79.284424"
+   viewBox="-40.981 -92.592 300 300"
+   id="svg2"
+   xml:space="preserve">
+<defs
+   id="defs4">
+</defs>
+<path
+   d="M -36.585379,54.412576 L -36.585379,54.421305 L -36.582469,54.421305 L -36.582469,54.243829 C -36.57956,54.302018 -36.585379,54.357297 -36.585379,54.412576 z "
+   style="fill:#6ac7bd"
+   id="path6" />
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g8">
+        <g
+   id="g10">
+                <path
+   d="M 24.482,23.998 L 24.482,23.995 C 10.961,23.994 0,34.955 0,48.476 L 0.001,48.479 L 0.001,48.482 C 0.003,62.001 10.962,72.96 24.482,72.96 L 24.482,72.96 L 0,72.96 L 0,97.442 L 0.003,97.442 C 13.523,97.44 24.482,86.48 24.482,72.961 L 24.485,72.961 C 38.005,72.959 48.963,62 48.963,48.479 L 48.963,48.476 C 48.962,34.957 38.001,23.998 24.482,23.998 z M 24.482,50.928 C 23.13,50.928 22.034,49.832 22.034,48.48 C 22.034,47.128 23.13,46.032 24.482,46.032 C 25.834,46.032 26.93,47.128 26.93,48.48 C 26.93,49.832 25.834,50.928 24.482,50.928 z "
+   style="fill:#ef412a"
+   id="path12" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g14">
+        <g
+   id="g16">
+                <path
+   d="M 119.96,48.842 C 120.024,47.548 121.086,46.516 122.397,46.516 C 123.707,46.516 124.768,47.548 124.833,48.843 C 137.211,47.62 146.879,37.181 146.879,24.483 L 122.397,24.483 C 122.396,10.961 111.435,0 97.915,0 L 97.915,24.485 C 97.917,37.183 107.584,47.619 119.96,48.842 z M 124.833,49.084 C 124.769,50.379 123.707,51.411 122.397,51.411 L 122.396,51.411 L 122.396,73.444 L 146.878,73.444 L 146.878,73.441 C 146.876,60.745 137.208,50.308 124.833,49.084 z M 119.949,48.963 L 97.915,48.963 L 97.915,73.442 L 97.915,73.442 C 110.613,73.442 121.052,63.774 122.275,51.399 C 120.981,51.334 119.949,50.274 119.949,48.963 z "
+   style="fill:#a9c542"
+   id="path18" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g20">
+        <g
+   id="g22">
+                <path
+   d="M 168.912,48.967 C 168.912,47.656 169.945,46.596 171.24,46.531 C 170.018,34.152 159.579,24.482 146.879,24.482 L 146.879,48.963 C 146.879,62.484 157.84,73.444 171.361,73.444 L 171.361,51.414 C 170.007,51.415 168.912,50.319 168.912,48.967 z M 195.841,48.978 C 195.841,48.973 195.842,48.969 195.842,48.964 L 195.842,24.482 L 195.838,24.482 C 183.14,24.484 172.702,34.154 171.482,46.531 C 172.776,46.595 173.808,47.656 173.808,48.967 C 173.808,50.278 172.776,51.339 171.481,51.403 C 172.679,63.59 182.814,73.146 195.244,73.445 L 171.361,73.445 L 171.361,97.927 L 171.364,97.927 C 184.879,97.925 195.834,86.973 195.842,73.46 L 195.844,73.46 L 195.844,48.979 L 195.841,48.978 z M 195.832,48.964 L 195.842,48.964 L 195.842,48.978 L 195.832,48.964 z "
+   style="fill:#f9c759"
+   id="path24" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g26">
+        <g
+   id="g28">
+                <path
+   d="M 70.994,48.479 L 48.962,48.479 L 48.962,48.481 L 70.995,48.481 C 70.995,48.481 70.994,48.48 70.994,48.479 z M 73.44,24.001 L 73.437,24.001 L 73.437,46.032 C 73.439,46.032 73.44,46.032 73.442,46.032 C 74.794,46.032 75.89,47.128 75.89,48.48 C 75.89,49.832 74.794,50.928 73.442,50.928 C 72.091,50.928 70.996,49.834 70.994,48.483 L 48.958,48.483 L 48.958,48.486 C 48.96,62.005 59.919,72.964 73.437,72.964 C 86.955,72.964 97.914,62.005 97.916,48.486 L 97.916,48.483 C 97.916,34.963 86.958,24.003 73.44,24.001 z "
+   style="fill:#6ac7bd"
+   id="path30" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g32">
+        <g
+   id="g34">
+                <path
+   d="M 24.482,23.998 L 24.482,23.995 C 10.961,23.994 0,34.955 0,48.476 L 22.034,48.476 C 22.036,47.125 23.131,46.031 24.482,46.031 C 25.834,46.031 26.93,47.127 26.93,48.479 C 26.93,49.831 25.834,50.927 24.482,50.927 L 24.482,72.937 C 24.469,59.427 13.514,48.479 0,48.479 L 0,72.96 L 24.481,72.96 L 24.481,72.96 L 0,72.96 L 0,97.442 L 0.003,97.442 C 13.523,97.44 24.482,86.48 24.482,72.961 L 24.485,72.961 C 38.005,72.959 48.963,62 48.963,48.479 L 48.963,48.476 C 48.962,34.957 38.001,23.998 24.482,23.998 z "
+   style="fill:#ef412a"
+   id="path36" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g38">
+        <g
+   id="g40">
+                <path
+   d="M 122.397,46.516 C 123.707,46.516 124.768,47.548 124.833,48.843 C 137.211,47.62 146.879,37.181 146.879,24.483 L 122.397,24.483 L 122.397,46.516 L 122.397,46.516 z M 97.915,0 L 97.915,24.482 L 122.396,24.482 C 122.396,10.961 111.435,0 97.915,0 z M 122.275,46.528 C 121.052,34.151 110.613,24.482 97.914,24.482 L 97.914,48.964 L 97.914,48.964 L 97.914,73.443 L 97.914,73.443 C 110.612,73.443 121.051,63.775 122.274,51.4 C 120.98,51.335 119.948,50.275 119.948,48.964 C 119.949,47.653 120.98,46.593 122.275,46.528 z M 124.833,49.084 C 124.769,50.379 123.707,51.411 122.397,51.411 L 122.396,51.411 L 122.396,73.444 L 146.878,73.444 L 146.878,73.441 C 146.876,60.745 137.208,50.308 124.833,49.084 z "
+   style="fill:#a9c542"
+   id="path42" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g44">
+        <g
+   id="g46">
+                <path
+   d="M 173.795,49.1 C 173.724,50.389 172.666,51.415 171.36,51.415 C 170.006,51.415 168.911,50.319 168.911,48.967 C 168.911,47.656 169.944,46.596 171.239,46.531 C 170.017,34.152 159.578,24.482 146.878,24.482 L 146.878,48.963 C 146.878,62.484 157.839,73.444 171.36,73.444 L 171.36,97.926 L 171.363,97.926 C 184.878,97.924 195.833,86.972 195.841,73.459 L 195.842,73.459 L 195.842,73.443 L 195.841,73.443 C 195.833,60.753 186.167,50.322 173.795,49.1 z M 195.838,24.482 C 183.14,24.484 172.702,34.154 171.482,46.531 C 172.775,46.595 173.806,47.655 173.808,48.964 L 195.841,48.964 L 195.841,48.979 C 195.841,48.974 195.842,48.969 195.842,48.964 L 195.842,24.482 L 195.838,24.482 z "
+   style="fill:#f9c759"
+   id="path48" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g50">
+        <g
+   id="g52">
+                <path
+   d="M 71.007,48.347 C 71.075,47.105 72.062,46.117 73.304,46.046 C 72.509,38.02 67.85,31.133 61.201,27.284 C 57.601,25.2 53.424,24 48.965,24 L 48.962,24 C 48.962,28.46 50.161,32.638 52.245,36.24 C 56.093,42.891 62.98,47.552 71.007,48.347 z M 48.962,48.418 C 48.962,48.438 48.961,48.456 48.961,48.476 L 48.961,48.479 L 48.962,48.479 L 48.962,48.418 z M 70.995,48.482 C 70.995,48.481 70.995,48.481 70.995,48.48 L 48.962,48.48 L 48.962,48.482 L 70.995,48.482 z M 73.44,24.001 L 73.437,24.001 L 73.437,46.032 C 73.439,46.032 73.44,46.032 73.442,46.032 C 74.794,46.032 75.89,47.128 75.89,48.48 C 75.89,49.832 74.794,50.928 73.442,50.928 C 72.091,50.928 70.996,49.834 70.994,48.483 L 48.958,48.483 L 48.958,48.486 C 48.96,62.005 59.919,72.964 73.437,72.964 C 86.955,72.964 97.914,62.005 97.916,48.486 L 97.916,48.483 C 97.916,34.963 86.958,24.003 73.44,24.001 z "
+   style="fill:#6ac7bd"
+   id="path54" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g56">
+        <g
+   id="g58">
+                <path
+   d="M 24.482,23.998 L 24.482,23.995 C 10.961,23.994 0,34.955 0,48.476 L 22.034,48.476 C 22.036,47.125 23.131,46.031 24.482,46.031 C 25.834,46.031 26.93,47.127 26.93,48.479 C 26.93,49.831 25.834,50.927 24.482,50.927 C 23.171,50.927 22.11,49.894 22.046,48.6 C 9.669,49.824 0.001,60.262 0.001,72.96 L 0,72.96 L 0,97.442 L 0.003,97.442 C 13.523,97.44 24.482,86.48 24.482,72.961 L 24.485,72.961 C 38.005,72.959 48.963,62 48.963,48.479 L 48.963,48.476 C 48.962,34.957 38.001,23.998 24.482,23.998 z "
+   style="fill:#ef412a"
+   id="path60" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g62">
+        <g
+   id="g64">
+                <path
+   d="M 119.949,48.963 C 119.949,47.611 121.045,46.515 122.397,46.515 C 123.707,46.515 124.768,47.547 124.833,48.842 C 137.211,47.619 146.879,37.18 146.879,24.482 L 122.397,24.482 C 122.396,10.961 111.435,0 97.915,0 L 97.915,24.482 L 122.394,24.482 C 108.874,24.484 97.916,35.444 97.916,48.963 L 97.916,48.963 L 97.916,73.442 L 97.916,73.442 C 110.614,73.442 121.053,63.774 122.276,51.399 C 120.981,51.334 119.949,50.274 119.949,48.963 z M 124.833,49.084 C 124.769,50.379 123.707,51.411 122.397,51.411 L 122.396,51.411 L 122.396,73.444 L 146.878,73.444 L 146.878,73.441 C 146.876,60.745 137.208,50.308 124.833,49.084 z "
+   style="fill:#a9c542"
+   id="path66" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g68">
+        <g
+   id="g70">
+                <path
+   d="M 195.841,48.979 L 195.835,48.964 L 195.841,48.964 L 195.841,48.979 C 195.841,48.974 195.842,48.969 195.842,48.964 L 195.842,24.482 L 195.838,24.482 C 183.14,24.484 172.702,34.154 171.482,46.531 C 172.776,46.595 173.808,47.656 173.808,48.967 C 173.808,50.319 172.712,51.415 171.361,51.415 C 170.007,51.415 168.912,50.319 168.912,48.967 C 168.912,47.656 169.945,46.596 171.24,46.531 C 170.018,34.152 159.579,24.482 146.879,24.482 L 146.879,48.963 C 146.879,62.484 157.84,73.444 171.361,73.444 L 171.361,97.926 L 171.364,97.926 C 184.883,97.924 195.843,86.963 195.843,73.444 L 171.959,73.444 C 185.203,73.126 195.841,62.299 195.841,48.979 z "
+   style="fill:#f9c759"
+   id="path72" />
+        </g>
+</g>
+<g
+   transform="matrix(2.9094193,0,0,2.9094193,-179.03055,-86.624435)"
+   style="opacity:0.65"
+   id="g74">
+        <g
+   id="g76">
+                <path
+   d="M 73.44,24.001 L 73.437,24.001 C 59.919,24.003 48.96,34.959 48.958,48.476 L 48.958,48.479 L 48.961,48.479 L 48.961,48.481 L 48.957,48.482 L 48.957,48.485 C 48.959,62.004 59.918,72.963 73.436,72.963 C 86.954,72.963 97.913,62.004 97.915,48.485 L 97.915,48.482 C 97.916,34.963 86.958,24.003 73.44,24.001 z M 73.442,50.928 C 72.09,50.928 70.994,49.832 70.994,48.48 C 70.994,47.128 72.09,46.032 73.442,46.032 C 74.794,46.032 75.89,47.128 75.89,48.48 C 75.89,49.832 74.794,50.928 73.442,50.928 z "
+   style="fill:#6ac7bd"
+   id="path78" />
+        </g>
+</g>
+</svg>
\ No newline at end of file
diff --git a/documentation/template/titlepage.templates.xml b/documentation/template/titlepage.templates.xml
new file mode 100644
index 0000000000..f53f147002
--- /dev/null
+++ b/documentation/template/titlepage.templates.xml
@@ -0,0 +1,1227 @@
+<!DOCTYPE t:templates [
+<!ENTITY hsize0 "10pt">
+<!ENTITY hsize1 "12pt">
+<!ENTITY hsize2 "14.4pt">
+<!ENTITY hsize3 "17.28pt">
+<!ENTITY hsize4 "20.736pt">
+<!ENTITY hsize5 "24.8832pt">
+<!ENTITY hsize0space "7.5pt"> <!-- 0.75 * hsize0 -->
+<!ENTITY hsize1space "9pt"> <!-- 0.75 * hsize1 -->
+<!ENTITY hsize2space "10.8pt"> <!-- 0.75 * hsize2 -->
+<!ENTITY hsize3space "12.96pt"> <!-- 0.75 * hsize3 -->
+<!ENTITY hsize4space "15.552pt"> <!-- 0.75 * hsize4 -->
+<!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
+]>
+<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
+             xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
+             xmlns:fo="http://www.w3.org/1999/XSL/Format"
+             xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!-- ********************************************************************
+     $Id: titlepage.templates.xml,v 1.23 2003/12/16 00:30:49 bobstayton Exp $
+     ********************************************************************
+
+     This file is part of the DocBook XSL Stylesheet distribution.
+     See ../README or http://docbook.sf.net/ for copyright
+     and other information.
+
+     ******************************************************************** -->
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="article" t:wrapper="fo:block"
+             font-family="{$title.fontset}">
+
+  <t:titlepage-content t:side="recto"
+             text-align="center">
+
+    <mediaobject/>           
+
+    <title t:named-template="component.title"
+           param:node="ancestor-or-self::article[1]"
+           keep-with-next="always"
+           font-size="&hsize5;"
+           font-weight="bold"/>
+
+    <subtitle param:node="ancestor-or-self::article[1]"
+           keep-with-next="always"
+           font-size="&hsize3;"
+           font-weight="bold"
+       space-after="0.8em"/>
+
+    <corpauthor space-before="0.5em"
+                font-size="&hsize3;"/>
+    <authorgroup space-before="0.5em"
+                 font-size="&hsize2;"/>
+    <author space-before="0.5em"
+            font-size="&hsize2;" 
+            space-after="0.8em"/>
+
+    <email font-size="&hsize2;"/>
+
+    <othercredit space-before="0.5em"/>
+    <releaseinfo space-before="0.5em"/>
+    <copyright space-before="0.5em"/>
+    <legalnotice text-align="start"
+                 margin-left="0.5in"
+                 margin-right="0.5in"
+                 font-family="{$body.fontset}"/>
+    <pubdate space-before="0.5em"/>
+        <para></para>
+    <revision space-before="0.5em"/>
+    <revhistory space-before="0.5em"/>
+    <abstract space-before="0.5em"
+              text-align="start"
+              margin-left="0.5in"
+              margin-right="0.5in"
+              font-family="{$body.fontset}"/>
+
+    <para></para>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="set" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+      <title
+             t:named-template="division.title"
+             param:node="ancestor-or-self::set[1]"
+             text-align="center"
+             font-size="&hsize5;"
+             space-before="&hsize5space;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"
+              text-align="center"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="book" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+
+      <mediaobject/>         
+
+      <subtitle
+                text-align="center"
+                font-size="&hsize4;"
+                space-before="&hsize4space;"
+                font-family="{$title.fontset}"/>
+      <corpauthor font-size="&hsize3;"
+                  keep-with-next="always"
+                  space-before="2in"/>
+      <authorgroup space-before="2in"/>
+      <author font-size="&hsize3;"
+              space-before="&hsize2space;"
+              keep-with-next="always"/>
+    </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+      <corpauthor/>
+      <authorgroup t:named-template="verso.authorgroup"/>
+      <author/>
+      <othercredit/>
+      <pubdate space-before="1em"/>
+      <copyright/>
+      <abstract/>
+      <legalnotice font-size="8pt"/>
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+      <fo:block break-after="page"/>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+      <fo:block break-after="page"/>
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="part" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+      <title
+             t:named-template="division.title"
+             param:node="ancestor-or-self::part[1]"
+             text-align="center"
+             font-size="&hsize5;"
+             space-before="&hsize5space;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    <subtitle
+              text-align="center"
+              font-size="&hsize4;"
+              space-before="&hsize4space;"
+              font-weight='bold'
+              font-style='italic'
+              font-family="{$title.fontset}"/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<t:titlepage t:element="partintro" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           text-align="center"
+           font-size="&hsize5;"
+           font-weight="bold"
+           space-before="1em"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              text-align="center"
+              font-size="&hsize2;"
+              font-weight="bold"
+              font-style="italic"
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="reference" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+      <title
+             t:named-template="division.title"
+             param:node="ancestor-or-self::reference[1]"
+             text-align="center"
+             font-size="&hsize5;"
+             space-before="&hsize5space;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"
+              text-align="center"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="refsynopsisdiv" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           font-family="{$title.fontset}"/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="refsection" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           font-family="{$title.fontset}"/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="refsect1" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           font-family="{$title.fontset}"/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="refsect2" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           font-family="{$title.fontset}"/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="refsect3" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           font-family="{$title.fontset}"/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="dedication" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="component.title"
+             param:node="ancestor-or-self::dedication[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize5;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="preface" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="component.title"
+             param:node="ancestor-or-self::preface[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize5;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+      <corpauthor/>
+      <authorgroup/>
+      <author/>
+      <othercredit/>
+      <releaseinfo/>
+      <copyright/>
+      <legalnotice/>
+      <pubdate/>
+      <revision/>
+      <revhistory/>
+      <abstract/>
+    </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="chapter" t:wrapper="fo:block"
+               font-family="{$title.fontset}">
+    <t:titlepage-content t:side="recto" margin-left="{$title.margin.left}">
+      <title t:named-template="component.title"
+             param:node="ancestor-or-self::chapter[1]"
+             font-size="&hsize5;"
+             font-weight="bold"/>
+
+      <subtitle space-before="0.5em"
+                font-style="italic"
+                font-size="&hsize2;"
+                font-weight="bold"/>
+
+      <corpauthor  space-before="0.5em"
+                   space-after="0.5em"
+                   font-size="&hsize2;"/>
+
+      <authorgroup space-before="0.5em"
+                   space-after="0.5em"
+                   font-size="&hsize2;"/>
+
+      <author      space-before="0.5em"
+                   space-after="0.5em"
+                   font-size="&hsize2;"/>
+
+      <othercredit/>
+      <releaseinfo/>
+      <copyright/>
+      <legalnotice/>
+      <pubdate/>
+      <revision/>
+      <revhistory/>
+      <abstract/>
+    </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="appendix" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:named-template="component.title"
+             param:node="ancestor-or-self::appendix[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize5;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+      <corpauthor/>
+      <authorgroup/>
+      <author/>
+      <othercredit/>
+      <releaseinfo/>
+      <copyright/>
+      <legalnotice/>
+      <pubdate/>
+      <revision/>
+      <revhistory/>
+      <abstract/>
+    </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="section" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           margin-left="{$title.margin.left}"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<t:titlepage t:element="sect1" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           margin-left="{$title.margin.left}"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<t:titlepage t:element="sect2" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           margin-left="{$title.margin.left}"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<t:titlepage t:element="sect3" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           margin-left="{$title.margin.left}"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<t:titlepage t:element="sect4" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           margin-left="{$title.margin.left}"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<t:titlepage t:element="sect5" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           margin-left="{$title.margin.left}"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<t:titlepage t:element="simplesect" t:wrapper="fo:block">
+  <t:titlepage-content t:side="recto">
+    <title
+           margin-left="{$title.margin.left}"
+           font-family="{$title.fontset}"/>
+    <subtitle
+              font-family="{$title.fontset}"/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <othercredit/>
+    <releaseinfo/>
+    <copyright/>
+    <legalnotice/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="bibliography" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="component.title"
+             param:node="ancestor-or-self::bibliography[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize5;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="bibliodiv" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title t:named-template="component.title"
+             param:node="ancestor-or-self::bibliodiv[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize4;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="glossary" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="component.title"
+             param:node="ancestor-or-self::glossary[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize5;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="glossdiv" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title t:named-template="component.title"
+             param:node="ancestor-or-self::glossdiv[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize4;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="index" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="component.title"
+             param:node="ancestor-or-self::index[1]"
+             param:pagewide="1"
+             margin-left="0pt"
+             font-size="&hsize5;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <!-- The indexdiv.title template is used so that manual and -->
+  <!-- automatically generated indexdiv titles get the same -->
+  <!-- formatting. -->
+
+  <t:titlepage t:element="indexdiv" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title t:force="1"
+             t:named-template="indexdiv.title"
+             param:title="title"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="setindex" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="component.title"
+             param:node="ancestor-or-self::setindex[1]"
+             param:pagewide="1"
+             margin-left="0pt"
+             font-size="&hsize5;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="colophon" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="component.title"
+             param:node="ancestor-or-self::colophon[1]"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize5;"
+             font-family="{$title.fontset}"
+             font-weight="bold"/>
+      <subtitle
+                font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+<!-- ==================================================================== -->
+
+  <t:titlepage t:element="table.of.contents" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="gentext"
+             param:key="'TableofContents'"
+             space-before.minimum="1em"
+             space-before.optimum="1.5em"
+             space-before.maximum="2em"
+             space-after="0.5em"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize3;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+  <t:titlepage t:element="list.of.tables" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="gentext"
+             param:key="'ListofTables'"
+             space-before.minimum="1em"
+             space-before.optimum="1.5em"
+             space-before.maximum="2em"
+             space-after="0.5em"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize3;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+  <t:titlepage t:element="list.of.figures" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="gentext"
+             param:key="'ListofFigures'"
+             space-before.minimum="1em"
+             space-before.optimum="1.5em"
+             space-before.maximum="2em"
+             space-after="0.5em"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize3;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+  <t:titlepage t:element="list.of.examples" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="gentext"
+             param:key="'ListofExamples'"
+             space-before.minimum="1em"
+             space-before.optimum="1.5em"
+             space-before.maximum="2em"
+             space-after="0.5em"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize3;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+  <t:titlepage t:element="list.of.equations" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="gentext"
+             param:key="'ListofEquations'"
+             space-before.minimum="1em"
+             space-before.optimum="1.5em"
+             space-before.maximum="2em"
+             space-after="0.5em"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize3;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+  <t:titlepage t:element="list.of.procedures" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="gentext"
+             param:key="'ListofProcedures'"
+             space-before.minimum="1em"
+             space-before.optimum="1.5em"
+             space-before.maximum="2em"
+             space-after="0.5em"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize3;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+  <t:titlepage t:element="list.of.unknowns" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+      <title
+             t:force="1"
+             t:named-template="gentext"
+             param:key="'ListofUnknown'"
+             space-before.minimum="1em"
+             space-before.optimum="1.5em"
+             space-before.maximum="2em"
+             space-after="0.5em"
+             margin-left="{$title.margin.left}"
+             font-size="&hsize3;"
+             font-weight="bold"
+             font-family="{$title.fontset}"/>
+    </t:titlepage-content>
+
+    <t:titlepage-content t:side="verso">
+    </t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+</t:templates>
diff --git a/documentation/template/yocto-project-qs.png b/documentation/template/yocto-project-qs.png
new file mode 100644
index 0000000000..333442e0d6
--- /dev/null
+++ b/documentation/template/yocto-project-qs.png
diff --git a/documentation/tools/eclipse-help.sed b/documentation/tools/eclipse-help.sed
new file mode 100644
index 0000000000..38690bc938
--- /dev/null
+++ b/documentation/tools/eclipse-help.sed
@@ -0,0 +1,18 @@
+# Processes poky-ref-manual and yocto-project-qs manual (<word>-<word>-<word> style)
+# For example:
+#   "ulink" href="http://www.yoctoproject.org/docs/1.3/poky-ref-manual/poky-ref-manual.html#faq"
+#   -> "link" href="../poky-ref-manual/faq.html"
+s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*-[a-z]*\)\/[a-z]*-[a-z]*-[a-z]*.html#\([^\"]*\)\"/\"link\" href=\"\.\.\/\1\/\2.html\"/g
+
+# Processes all other manuals (<word>-<word> style)
+# For example:
+#   "ulink" href="http://www.yoctoproject.org/docs/1.3/kernel-manual/kernel-manual.html#faq"
+#   -> "link" href="../kernel-manual/faq.html"
+s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*\)\/[a-z]*-[a-z]*.html#\([^\"]*\)\"/\"link\" href=\"\.\.\/\1\/\2.html\"/g
+
+# Process cases where just an external manual is referenced without an id anchor
+# For example:
+#   "ulink" href="http://www.yoctoproject.org/docs/1.3/kernel-manual/kernel-manual.html
+#   -> "link" href="../kernel-manual/index.html"
+s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*-[a-z]*\)\/[a-z]*-[a-z]*-[a-z]*.html\"/\"link\" href=\"\.\.\/\1\/index.html\"/g
+s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/[^\/]*\/\([a-z]*-[a-z]*\)\/[a-z]*-[a-z]*.html\"/\"link\" href=\"\.\.\/\1\/index.html\"/g
diff --git a/documentation/tools/mega-manual.sed b/documentation/tools/mega-manual.sed
new file mode 100644
index 0000000000..d3142ec60d
--- /dev/null
+++ b/documentation/tools/mega-manual.sed
@@ -0,0 +1,13 @@
+# Processes ref-manual and yocto-project-qs manual (<word>-<word>-<word> style)
+s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/[a-z]*-[a-z]*-[a-z]*\/[a-z]*-[a-z]*-[a-z]*.html#/\"link\" href=\"#/g
+
+# Processes all other manuals (<word>-<word> style)
+s/\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/[a-z]*-[a-z]*\/[a-z]*-[a-z]*.html#/\"link\" href=\"#/g
+
+# Process cases where just an external manual is referenced without an id anchor
+s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/yocto-project-qs\/yocto-project-qs.html\" target=\"_top\">Yocto Project Quick Start<\/a>/Yocto Project Quick Start/g
+s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/dev-manual\/dev-manual.html\" target=\"_top\">Yocto Project Development Manual<\/a>/Yocto Project Development Manual/g
+s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/adt-manual\/adt-manual.html\" target=\"_top\">Yocto Project Application Developer's Guide<\/a>/Yocto Project Application Developer's Guide/g
+s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/bsp-guide\/bsp-guide.html\" target=\"_top\">Yocto Project Board Support Package (BSP) Developer's Guide<\/a>/Yocto Project Board Support Package (BSP) Developer's Guide/g
+s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/kernel-dev\/kernel-dev.html\" target=\"_top\">Yocto Project Linux Kernel Development Manual<\/a>/Yocto Project Linux Kernel Development Manual/g
+s/<a class=\"ulink\" href=\"http:\/\/www.yoctoproject.org\/docs\/1.5.1\/ref-manual\/ref-manual.html\" target=\"_top\">Yocto Project Reference Manual<\/a>/Yocto Project Reference Manual/g
diff --git a/documentation/tools/poky-docbook-to-pdf b/documentation/tools/poky-docbook-to-pdf
new file mode 100755
index 0000000000..f55fd278af
--- /dev/null
+++ b/documentation/tools/poky-docbook-to-pdf
@@ -0,0 +1,51 @@
+#!/bin/sh
+        
+if [ -z "$1" -o -z "$2" ]; then
+   echo "usage: [-v] $0 <docbook file> <templatedir>"
+   echo
+   echo "*NOTE* you need xsltproc, fop and nwalsh docbook stylesheets" 
+   echo "       installed for this to work!"
+   echo
+   exit 0
+fi
+
+FO=`echo $1 | sed s/.xml/.fo/` || exit 1
+PDF=`echo $1 | sed s/.xml/.pdf/` || exit 1
+TEMPLATEDIR=$2
+
+##
+# These URI should be rewritten by your distribution's xml catalog to
+# match your localy installed XSL stylesheets.
+XSL_BASE_URI="http://docbook.sourceforge.net/release/xsl/current"
+
+# Creates a temporary XSL stylesheet based on titlepage.xsl
+xsltproc -o /tmp/titlepage.xsl                                           \
+         --xinclude                                                      \
+         $XSL_BASE_URI/template/titlepage.xsl \
+         $TEMPLATEDIR/titlepage.templates.xml || exit 1
+
+# Creates the file needed for FOP
+xsltproc --xinclude                    \
+         --stringparam hyphenate false \
+         --stringparam formal.title.placement "figure after" \
+         --stringparam ulink.show 1 \
+         --stringparam  body.font.master  9 \
+         --stringparam  title.font.master  11 \
+         --stringparam draft.watermark.image "$TEMPLATEDIR/draft.png" \
+         --stringparam  chapter.autolabel 1 \
+         --stringparam  appendix.autolabel A \
+         --stringparam  section.autolabel 1 \
+         --stringparam  section.label.includes.component.label 1 \
+         --output $FO               \
+         $TEMPLATEDIR/poky-db-pdf.xsl    \
+         $1                 || exit 1
+
+# Invokes the Java version of FOP.  Uses the additional configuration file common/fop-config.xml
+fop -c $TEMPLATEDIR/fop-config.xml -fo $FO -pdf $PDF       || exit 1
+
+rm -f $FO
+rm -f  /tmp/titlepage.xsl
+
+echo
+echo " #### Success! $PDF ready. ####"
+echo
diff --git a/documentation/yocto-project-qs/figures/building-an-image.png b/documentation/yocto-project-qs/figures/building-an-image.png
new file mode 100755
index 0000000000..1fbea5ab00
--- /dev/null
+++ b/documentation/yocto-project-qs/figures/building-an-image.png
diff --git a/documentation/yocto-project-qs/figures/using-a-pre-built-image.png b/documentation/yocto-project-qs/figures/using-a-pre-built-image.png
new file mode 100644
index 0000000000..b03130d123
--- /dev/null
+++ b/documentation/yocto-project-qs/figures/using-a-pre-built-image.png
diff --git a/documentation/yocto-project-qs/figures/yocto-environment.png b/documentation/yocto-project-qs/figures/yocto-environment.png
new file mode 100644
index 0000000000..82b7a55a35
--- /dev/null
+++ b/documentation/yocto-project-qs/figures/yocto-environment.png
diff --git a/documentation/yocto-project-qs/figures/yocto-project-transp.png b/documentation/yocto-project-qs/figures/yocto-project-transp.png
new file mode 100755
index 0000000000..31d2b147fd
--- /dev/null
+++ b/documentation/yocto-project-qs/figures/yocto-project-transp.png
diff --git a/documentation/yocto-project-qs/qs-style.css b/documentation/yocto-project-qs/qs-style.css
new file mode 100644
index 0000000000..234e432a74
--- /dev/null
+++ b/documentation/yocto-project-qs/qs-style.css
@@ -0,0 +1,979 @@
+/* 
+   Generic XHTML / DocBook XHTML CSS Stylesheet.
+   
+   Browser wrangling and typographic design by
+      Oyvind Kolas / pippin@gimp.org
+
+   Customised for Poky by
+      Matthew Allum / mallum@o-hand.com
+
+   Thanks to:
+     Liam R. E. Quin
+     William Skaggs
+     Jakub Steiner
+
+   Structure
+   ---------
+
+   The stylesheet is divided into the following sections:
+
+       Positioning
+          Margins, paddings, width, font-size, clearing.
+       Decorations
+          Borders, style
+       Colors
+          Colors
+       Graphics
+          Graphical backgrounds
+       Nasty IE tweaks
+          Workarounds needed to make it work in internet explorer,
+          currently makes the stylesheet non validating, but up until
+          this point it is validating.
+       Mozilla extensions
+          Transparency for footer
+          Rounded corners on boxes
+
+*/
+
+
+  /*************** /
+ /  Positioning   /
+/ ***************/
+
+body {
+  font-family: Verdana, Sans, sans-serif;
+ 
+  min-width: 640px;
+  width: 80%;
+  margin:  0em auto;
+  padding: 2em 5em 5em 5em;
+  color: #333;
+}
+
+h1,h2,h3,h4,h5,h6,h7 {
+  font-family: Arial, Sans;
+  color: #00557D;
+  clear: both;
+}
+
+h1 {
+  font-size: 2em;
+  text-align: left;
+  padding: 0em 0em 0em 0em;
+  margin: 2em 0em 0em 0em;
+}
+
+h2.subtitle {
+  margin: 0.10em 0em 3.0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 1.8em;
+  padding-left: 20%;
+  font-weight: normal;
+  font-style: italic;
+}
+
+h2 {
+  margin: 2em 0em 0.66em 0em;
+  padding: 0.5em 0em 0em 0em;
+  font-size: 1.5em;
+  font-weight: bold;
+}
+
+h3.subtitle {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+  font-size: 142.14%;
+  text-align: right;
+}
+
+h3 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 140%;
+  font-weight: bold;
+}
+
+h4 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 120%;
+  font-weight: bold;
+}
+
+h5 {
+  margin: 1em 0em 0.5em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+h6 {
+  margin: 1em 0em 0em 0em;
+  padding: 1em 0em 0em 0em;
+  font-size: 110%;
+  font-weight: bold;
+}
+
+.authorgroup {
+  background-color: transparent;
+  background-repeat: no-repeat;
+  padding-top: 256px;
+  background-image: url("../figures/yocto-project-bw.png");
+  background-position: top;
+  margin-top: -256px;
+  padding-right: 50px;
+  margin-left: 50px;
+  text-align: center;
+  width: 600px;
+}
+
+h3.author {
+  margin: 0em 0me 0em 0em;
+  padding: 0em 0em 0em 0em;
+  font-weight: normal;
+  font-size: 100%;
+  color: #333;
+  clear: both;
+}
+
+.author tt.email {
+  font-size: 66%;
+}
+
+.titlepage hr {
+  width: 0em;
+  clear: both;
+}
+
+.revhistory {
+  padding-top: 2em;
+  clear: both;
+}
+
+.toc,
+.list-of-tables,
+.list-of-examples,
+.list-of-figures {
+  padding: 1.33em 0em 2.5em 0em;
+  color: #00557D;
+}
+
+.toc p,
+.list-of-tables p,
+.list-of-figures p,
+.list-of-examples p {
+  padding: 0em 0em 0em 0em;
+  padding: 0em 0em 0.3em;
+  margin: 1.5em 0em 0em 0em;
+}
+
+.toc p b,
+.list-of-tables p b,
+.list-of-figures p b,
+.list-of-examples p b{
+  font-size: 100.0%;
+  font-weight: bold;
+}
+
+.toc dl,
+.list-of-tables dl,
+.list-of-figures dl,
+.list-of-examples dl {
+  margin: 0em 0em 0.5em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dt {
+  margin: 0em 0em 0em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.toc dd {
+  margin: 0em 0em 0em 2.6em;
+  padding: 0em 0em 0em 0em;
+}
+
+div.glossary dl,
+div.variablelist dl {
+}
+
+.glossary dl dt,
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  font-weight: normal;
+  width: 20em;
+  text-align: right;
+}
+
+.variablelist dl dt {
+  margin-top: 0.5em;
+}
+
+.glossary dl dd,
+.variablelist dl dd {
+  margin-top: -1em;
+  margin-left: 25.5em;
+}
+
+.glossary dd p,
+.variablelist dd p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+
+div.calloutlist table td {
+  padding: 0em 0em 0em 0em;
+  margin: 0em 0em 0em 0em;
+}
+
+div.calloutlist table td p {
+  margin-top: 0em;
+  margin-bottom: 1em;
+}
+
+div p.copyright {
+  text-align: left;
+}
+
+div.legalnotice p.legalnotice-title {
+  margin-bottom: 0em;
+}
+
+p {
+  line-height: 1.5em;
+  margin-top: 0em;
+  
+}
+
+dl {
+  padding-top: 0em;
+}
+
+hr {
+  border: solid 1px;
+}
+
+
+.mediaobject,
+.mediaobjectco {
+  text-align: center;
+}
+
+img {
+  border: none;
+}
+
+ul {
+  padding: 0em 0em 0em 1.5em;
+}
+
+ul li {
+  padding: 0em 0em 0em 0em;
+}
+
+ul li p {
+  text-align: left;
+}
+
+table {
+  width :100%;
+}
+
+th {
+  padding: 0.25em;
+  text-align: left;
+  font-weight: normal;
+  vertical-align: top;
+}
+
+td {
+  padding: 0.25em;
+  vertical-align: top;
+}
+
+p a[id] {
+  margin: 0px;
+  padding: 0px;
+  display: inline;
+  background-image: none;
+} 
+
+a {
+  text-decoration: underline;
+  color: #444;
+}
+
+pre {
+    overflow: auto;
+}
+
+a:hover {
+  text-decoration: underline;
+  /*font-weight: bold;*/
+}
+
+
+div.informalfigure,
+div.informalexample,
+div.informaltable,
+div.figure,
+div.table,
+div.example {
+  margin: 1em 0em;
+  padding: 1em;
+  page-break-inside: avoid;
+}
+
+
+div.informalfigure p.title b,
+div.informalexample p.title b,
+div.informaltable p.title b,
+div.figure p.title b,
+div.example p.title b,
+div.table p.title b{
+    padding-top: 0em;
+    margin-top: 0em;
+    font-size: 100%;
+    font-weight: normal;
+}
+
+.mediaobject .caption, 
+.mediaobject .caption p  {
+  text-align: center;
+  font-size: 80%;  
+  padding-top: 0.5em;
+  padding-bottom: 0.5em;
+}
+
+.epigraph {
+  padding-left: 55%;
+  margin-bottom: 1em;
+}
+
+.epigraph p {
+  text-align: left;
+}
+
+.epigraph .quote {
+  font-style: italic;
+}
+.epigraph .attribution {
+  font-style: normal;
+  text-align: right;
+}
+
+span.application {
+  font-style: italic;
+}
+
+.programlisting {
+  font-family: monospace;
+  font-size: 80%;
+  white-space: pre;
+  margin: 1.33em 0em;
+  padding: 1.33em;
+}
+
+.tip,
+.warning,
+.caution,
+.note {
+  margin-top: 1em;
+  margin-bottom: 1em;
+
+}
+
+/* force full width of table within div */
+.tip table,
+.warning table,
+.caution table,
+.note table {
+  border: none;
+  width: 100%;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  padding: 0.8em 0.0em 0.0em 0.0em;
+  margin : 0em 0em 0em 0em;
+}
+
+.tip p,
+.warning p,
+.caution p,
+.note p {
+  margin-top: 0.5em;
+  margin-bottom: 0.5em;
+  padding-right: 1em;
+  text-align: left;
+}
+
+.acronym {
+  text-transform: uppercase;
+}
+
+b.keycap,
+.keycap {
+  padding: 0.09em 0.3em;
+  margin: 0em;
+}
+
+.itemizedlist li {
+  clear: none;
+}
+
+.filename {
+  font-size: medium;
+  font-family: Courier, monospace;
+}
+
+
+div.navheader, div.heading{
+  position: absolute;
+  left: 0em;
+  top: 0em;
+  width: 100%;
+  background-color: #cdf;
+  width: 100%;
+}
+
+div.navfooter, div.footing{
+  position: fixed;
+  left: 0em;
+  bottom: 0em;
+  background-color: #eee;
+  width: 100%;
+}
+
+
+div.navheader td,
+div.navfooter td {
+  font-size: 66%;
+}
+
+div.navheader table th {
+  /*font-family: Georgia, Times, serif;*/
+  /*font-size: x-large;*/
+  font-size: 80%;
+}
+
+div.navheader table {
+  border-left: 0em;
+  border-right: 0em;
+  border-top: 0em;
+  width: 100%;
+}
+
+div.navfooter table {
+  border-left: 0em;
+  border-right: 0em;
+  border-bottom: 0em;
+  width: 100%;
+}
+
+div.navheader table td a,
+div.navfooter table td a {
+  color: #777;
+  text-decoration: none;
+}
+
+/* normal text in the footer */
+div.navfooter table td {
+  color: black;
+}
+
+div.navheader table td a:visited,
+div.navfooter table td a:visited {
+  color: #444;
+}
+
+
+/* links in header and footer */
+div.navheader table td a:hover,
+div.navfooter table td a:hover {
+  text-decoration: underline;
+  background-color: transparent;
+  color: #33a;
+}
+
+div.navheader hr,
+div.navfooter hr {
+  display: none;
+}
+
+
+.qandaset tr.question td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+
+.qandaset tr.answer td p {
+  margin: 0em 0em 1em 0em;
+  padding: 0em 0em 0em 0em;
+}
+.answer td {
+  padding-bottom: 1.5em;
+}
+
+.emphasis {
+  font-weight: bold;
+}
+
+
+  /************* /
+ / decorations  /
+/ *************/
+
+.titlepage {
+}
+
+.part .title {
+}
+
+.subtitle {
+    border: none;
+}
+
+/*
+h1 {
+  border: none;
+}
+
+h2 {
+  border-top: solid 0.2em;
+  border-bottom: solid 0.06em;
+}
+
+h3 {
+  border-top: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h4 {
+  border: 0em;
+  border-bottom: solid 0.06em;
+}
+
+h5 {
+  border: 0em;
+}
+*/
+
+.programlisting {
+  border: solid 1px;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example {
+  border: 1px solid;
+}
+
+
+
+.tip,
+.warning,
+.caution,
+.note {
+  border: 1px solid;
+}
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom: 1px solid;
+}
+
+.question td {
+  border-top: 1px solid black;
+}
+
+.answer {
+}
+
+
+b.keycap,
+.keycap {
+  border: 1px solid;
+}
+  
+
+div.navheader, div.heading{
+  border-bottom: 1px solid;
+}
+
+
+div.navfooter, div.footing{
+  border-top: 1px solid;
+}
+
+  /********* /
+ /  colors  /
+/ *********/
+
+body {
+  color: #333;
+  background: white;
+}
+
+a {
+  background: transparent;
+}
+
+a:hover {
+  background-color: #dedede;
+}
+
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7,
+h8 {
+  background-color: transparent;
+}
+
+hr {
+  border-color: #aaa;
+}
+
+
+.tip, .warning, .caution, .note {
+  border-color: #fff;
+}
+
+
+.tip table th,
+.warning table th,
+.caution table th,
+.note table th {
+  border-bottom-color: #fff;
+}
+
+
+.warning {
+  background-color: #f0f0f2;
+}
+
+.caution {
+  background-color: #f0f0f2;
+}
+
+.tip {
+  background-color: #f0f0f2;
+}
+
+.note {
+  background-color: #f0f0f2; 
+}
+
+.glossary dl dt, 
+.variablelist dl dt,
+.variablelist dl dt span.term {
+  color: #044;
+}
+
+div.figure,
+div.table,
+div.example,
+div.informalfigure,
+div.informaltable,
+div.informalexample {
+  border-color: #aaa;
+}
+
+pre.programlisting {
+  color: black;
+  background-color: #fff;
+  border-color: #aaa;
+  border-width: 2px;
+}
+
+.guimenu,
+.guilabel,
+.guimenuitem {
+  background-color: #eee;
+}
+
+
+b.keycap,
+.keycap {
+  background-color: #eee;
+  border-color: #999;
+}
+
+
+div.navheader {
+  border-color: black;
+}
+
+
+div.navfooter {
+  border-color: black;
+}
+
+
+  /*********** /
+ /  graphics  /
+/ ***********/
+
+/*
+body {
+  background-image: url("images/body_bg.jpg");
+  background-attachment: fixed;
+}
+
+.navheader,
+.note,
+.tip {
+  background-image: url("images/note_bg.jpg");
+  background-attachment: fixed;
+}
+
+.warning,
+.caution {
+  background-image: url("images/warning_bg.jpg");
+  background-attachment: fixed;
+}
+
+.figure,
+.informalfigure,
+.example,
+.informalexample,
+.table,
+.informaltable {
+  background-image: url("images/figure_bg.jpg");
+  background-attachment: fixed;
+}
+
+*/
+h1,
+h2,
+h3,
+h4,
+h5,
+h6,
+h7{
+}
+
+/*
+Example of how to stick an image as part of the title.
+
+div.article .titlepage .title
+{
+  background-image: url("figures/white-on-black.png");
+  background-position: center;
+  background-repeat: repeat-x;
+}
+*/
+
+div.preface .titlepage .title, 
+div.colophon .title, 
+div.chapter .titlepage .title,
+div.article .titlepage .title 
+{
+}
+
+div.section div.section .titlepage .title,
+div.sect2 .titlepage .title {
+    background: none;
+}
+
+
+h1.title {
+  background-color: transparent;
+  background-image: url("figures/yocto-project-bw.png");
+  background-repeat: no-repeat;
+  height: 256px;
+  text-indent: -9000px;
+  overflow:hidden;
+}
+
+h2.subtitle {
+  background-color: transparent;
+  text-indent: -9000px;
+  overflow:hidden;
+  width: 0px;
+  display: none;
+}
+
+  /*************************************** /
+ /  pippin.gimp.org specific alterations  /
+/ ***************************************/
+
+/*
+div.heading, div.navheader {
+  color: #777;
+  font-size: 80%;
+  padding: 0;
+  margin: 0;
+  text-align: left;
+  position: absolute;
+  top: 0px;
+  left: 0px;
+  width: 100%;
+  height: 50px;
+  background: url('/gfx/heading_bg.png') transparent;
+  background-repeat: repeat-x;
+  background-attachment: fixed;
+  border: none;
+}
+
+div.heading a {
+  color: #444;
+}
+
+div.footing, div.navfooter {
+  border: none;
+  color: #ddd;
+  font-size: 80%;
+  text-align:right;
+
+  width: 100%;
+  padding-top: 10px;
+  position: absolute;
+  bottom: 0px;
+  left: 0px;
+
+  background: url('/gfx/footing_bg.png') transparent;
+}
+*/
+
+
+
+  /****************** /
+ /  nasty ie tweaks  /
+/ ******************/
+
+/*
+div.heading, div.navheader {
+  width:expression(document.body.clientWidth + "px");
+}
+
+div.footing, div.navfooter {
+  width:expression(document.body.clientWidth + "px");
+  margin-left:expression("-5em");
+}
+body {
+  padding:expression("4em 5em 0em 5em");
+}
+*/
+
+  /**************************************** /
+ / mozilla vendor specific css extensions  /
+/ ****************************************/
+/*
+div.navfooter, div.footing{
+  -moz-opacity: 0.8em;
+}
+
+div.figure,
+div.table,
+div.informalfigure,
+div.informaltable,
+div.informalexample,
+div.example,
+.tip,
+.warning,
+.caution,
+.note {
+  -moz-border-radius: 0.5em;
+}
+
+b.keycap,
+.keycap {
+  -moz-border-radius: 0.3em;
+}
+*/
+
+table tr td table tr td {
+  display: none;
+}
+
+
+hr {
+  display: none;
+}
+
+table {
+  border: 0em;
+}
+
+ .photo {
+  float: right;
+  margin-left:   1.5em;
+  margin-bottom: 1.5em;
+  margin-top: 0em;
+  max-width:      17em;
+  border:     1px solid gray;
+  padding:    3px;
+  background: white;
+}
+ .seperator {
+   padding-top: 2em;
+   clear: both;
+  }
+
+  #validators {
+      margin-top: 5em;
+      text-align: right;
+      color: #777;
+  }
+  @media print {
+      body {
+          font-size: 8pt;
+      }
+      .noprint {
+          display: none;
+      }
+  }
+
+
+.tip,
+.note {
+   background: #f0f0f2; 
+   color: #333;   
+   padding: 20px;
+   margin: 20px;
+}
+
+.tip h3,
+.note h3 {
+   padding: 0em;
+   margin: 0em;
+   font-size: 2em;
+   font-weight: bold;
+   color: #333;   
+}
+
+.tip a,
+.note a {
+   color: #333;   
+   text-decoration: underline;
+}
+
+.footnote {
+   font-size: small;
+   color: #333;
+}
+
+/* Changes the announcement text */
+.tip h3,
+.warning h3,
+.caution h3,
+.note h3 {
+   font-size:large;
+   color: #00557D;
+}
+
diff --git a/documentation/yocto-project-qs/yocto-project-qs-customization.xsl b/documentation/yocto-project-qs/yocto-project-qs-customization.xsl
new file mode 100644
index 0000000000..bd53ecb0f6
--- /dev/null
+++ b/documentation/yocto-project-qs/yocto-project-qs-customization.xsl
@@ -0,0 +1,9 @@
+<?xml version='1.0'?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns="http://www.w3.org/1999/xhtml" xmlns:fo="http://www.w3.org/1999/XSL/Format" version="1.0">
+  
+  <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl" />
+  <xsl:import href="yocto-project-qs-titlepage.xsl"/>
+
+  <xsl:param name="generate.toc" select="'article nop'"></xsl:param>
+  <xsl:param name="html.stylesheet" select="'qs-style.css'" />
+</xsl:stylesheet>
diff --git a/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl b/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl
new file mode 100644
index 0000000000..f8f8930f27
--- /dev/null
+++ b/documentation/yocto-project-qs/yocto-project-qs-eclipse-customization.xsl
@@ -0,0 +1,25 @@
+<?xml version='1.0'?>
+<xsl:stylesheet
+        xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+        xmlns="http://www.w3.org/1999/xhtml"
+        xmlns:fo="http://www.w3.org/1999/XSL/Format"
+        version="1.0">
+
+  <xsl:import
+          href="http://docbook.sourceforge.net/release/xsl/current/eclipse/eclipse3.xsl" />
+  <xsl:import href="yocto-project-qs-titlepage.xsl"/>
+
+  <xsl:param name="chunker.output.indent" select="'yes'"/>
+  <xsl:param name="chunk.quietly" select="1"/>
+  <xsl:param name="use.id.as.filename" select="1"/>
+  <xsl:param name="ulink.target" select="'_self'" />
+  <xsl:param name="base.dir" select="'html/yocto-project-qs/'"/>
+  <xsl:param name="chunk.section.depth" select="0"/>
+  <xsl:param name="html.stylesheet" select="'../book.css'"/>
+  <xsl:param name="eclipse.manifest" select="0"/>
+  <xsl:param name="create.plugin.xml" select="0"/>
+  <xsl:param name="suppress.navigation" select="1"/>
+  <xsl:param name="generate.index" select="0"/>
+  <xsl:param name="generate.toc" select="'article nop'"></xsl:param>
+  <xsl:param name="html.stylesheet" select="'style.css'" />
+</xsl:stylesheet>
diff --git a/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl b/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl
new file mode 100644
index 0000000000..a435ac77ab
--- /dev/null
+++ b/documentation/yocto-project-qs/yocto-project-qs-titlepage.xsl
@@ -0,0 +1,3820 @@
+<?xml version="1.0"?>
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:exsl="http://exslt.org/common" version="1.0" exclude-result-prefixes="exsl">
+
+<!-- This stylesheet was created by template/titlepage.xsl-->
+
+<xsl:template name="article.titlepage.recto">
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/abstract"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/abstract"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/abstract"/>
+  <xsl:choose>
+    <xsl:when test="articleinfo/title">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/title"/>
+    </xsl:when>
+    <xsl:when test="artheader/title">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="articleinfo/subtitle">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="artheader/subtitle">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/corpauthor"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/corpauthor"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/authorgroup"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/authorgroup"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/author"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/author"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/othercredit"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/othercredit"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/releaseinfo"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/releaseinfo"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/copyright"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/copyright"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/legalnotice"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/legalnotice"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/pubdate"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/pubdate"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/revision"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/revision"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="articleinfo/revhistory"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="artheader/revhistory"/>
+  <xsl:apply-templates mode="article.titlepage.recto.auto.mode" select="info/revhistory"/>
+</xsl:template>
+
+<xsl:template name="article.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="article.titlepage.separator"><hr/>
+</xsl:template>
+
+<xsl:template name="article.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="article.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="article.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="article.titlepage.before.recto"/>
+      <xsl:call-template name="article.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="article.titlepage.before.verso"/>
+      <xsl:call-template name="article.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="article.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="article.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="article.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="abstract" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+  <xsl:call-template name="anchor"/>
+  <xsl:apply-templates/>
+<!-- orignally generated content -->
+<!-- <xsl:apply-templates select="." mode="article.titlepage.recto.mode"/> -->
+</div>
+</xsl:template>
+
+<xsl:template match="title" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="article.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="article.titlepage.recto.style">
+<xsl:apply-templates select="." mode="article.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="set.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="setinfo/title">
+      <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="setinfo/subtitle">
+      <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/corpauthor"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/authorgroup"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/author"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/othercredit"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/releaseinfo"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/copyright"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/legalnotice"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/pubdate"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/revision"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/revhistory"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="setinfo/abstract"/>
+  <xsl:apply-templates mode="set.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="set.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="set.titlepage.separator"><hr/>
+</xsl:template>
+
+<xsl:template name="set.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="set.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="set.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="set.titlepage.before.recto"/>
+      <xsl:call-template name="set.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="set.titlepage.before.verso"/>
+      <xsl:call-template name="set.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="set.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="set.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="set.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="set.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="set.titlepage.recto.style">
+<xsl:apply-templates select="." mode="set.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="book.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="bookinfo/title">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="bookinfo/subtitle">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/corpauthor"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/authorgroup"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/author"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/othercredit"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/releaseinfo"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/copyright"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/legalnotice"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/pubdate"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/revision"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/revhistory"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="bookinfo/abstract"/>
+  <xsl:apply-templates mode="book.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="book.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="book.titlepage.separator"><hr/>
+</xsl:template>
+
+<xsl:template name="book.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="book.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="book.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="book.titlepage.before.recto"/>
+      <xsl:call-template name="book.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="book.titlepage.before.verso"/>
+      <xsl:call-template name="book.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="book.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="book.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="book.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="book.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="book.titlepage.recto.style">
+<xsl:apply-templates select="." mode="book.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="part.titlepage.recto">
+  <div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:call-template name="division.title">
+<xsl:with-param name="node" select="ancestor-or-self::part[1]"/>
+</xsl:call-template></div>
+  <xsl:choose>
+    <xsl:when test="partinfo/subtitle">
+      <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/corpauthor"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/corpauthor"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/authorgroup"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/authorgroup"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/author"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/author"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/othercredit"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/othercredit"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/releaseinfo"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/copyright"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/copyright"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/legalnotice"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/legalnotice"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/pubdate"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/pubdate"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/revision"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/revision"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/revhistory"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/revhistory"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="partinfo/abstract"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="docinfo/abstract"/>
+  <xsl:apply-templates mode="part.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="part.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="part.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="part.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="part.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="part.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="part.titlepage.before.recto"/>
+      <xsl:call-template name="part.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="part.titlepage.before.verso"/>
+      <xsl:call-template name="part.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="part.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="part.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="part.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="part.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="part.titlepage.recto.style">
+<xsl:apply-templates select="." mode="part.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="partintro.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="partintroinfo/title">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/title"/>
+    </xsl:when>
+    <xsl:when test="docinfo/title">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="partintroinfo/subtitle">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/corpauthor"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/corpauthor"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/authorgroup"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/authorgroup"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/author"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/author"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/othercredit"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/othercredit"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/releaseinfo"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/copyright"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/copyright"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/legalnotice"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/legalnotice"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/pubdate"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/pubdate"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/revision"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/revision"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/revhistory"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/revhistory"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="partintroinfo/abstract"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="docinfo/abstract"/>
+  <xsl:apply-templates mode="partintro.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="partintro.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="partintro.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="partintro.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="partintro.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="partintro.titlepage">
+  <div>
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="partintro.titlepage.before.recto"/>
+      <xsl:call-template name="partintro.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="partintro.titlepage.before.verso"/>
+      <xsl:call-template name="partintro.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="partintro.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="partintro.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="partintro.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="partintro.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="partintro.titlepage.recto.style">
+<xsl:apply-templates select="." mode="partintro.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="reference.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="referenceinfo/title">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/title"/>
+    </xsl:when>
+    <xsl:when test="docinfo/title">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="referenceinfo/subtitle">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/corpauthor"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/corpauthor"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/authorgroup"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/authorgroup"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/author"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/author"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/othercredit"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/othercredit"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/releaseinfo"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/copyright"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/copyright"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/legalnotice"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/legalnotice"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/pubdate"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/pubdate"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/revision"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/revision"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/revhistory"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/revhistory"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="referenceinfo/abstract"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="docinfo/abstract"/>
+  <xsl:apply-templates mode="reference.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="reference.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="reference.titlepage.separator"><hr/>
+</xsl:template>
+
+<xsl:template name="reference.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="reference.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="reference.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="reference.titlepage.before.recto"/>
+      <xsl:call-template name="reference.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="reference.titlepage.before.verso"/>
+      <xsl:call-template name="reference.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="reference.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="reference.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="reference.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="reference.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="reference.titlepage.recto.style">
+<xsl:apply-templates select="." mode="reference.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="refentry.titlepage.recto">
+</xsl:template>
+
+<xsl:template name="refentry.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="refentry.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="refentry.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="refentry.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="refentry.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="refentry.titlepage.before.recto"/>
+      <xsl:call-template name="refentry.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="refentry.titlepage.before.verso"/>
+      <xsl:call-template name="refentry.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="refentry.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="refentry.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="refentry.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template name="dedication.titlepage.recto">
+  <div xsl:use-attribute-sets="dedication.titlepage.recto.style">
+<xsl:call-template name="component.title">
+<xsl:with-param name="node" select="ancestor-or-self::dedication[1]"/>
+</xsl:call-template></div>
+  <xsl:choose>
+    <xsl:when test="dedicationinfo/subtitle">
+      <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="dedicationinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="dedication.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="dedication.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="dedication.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="dedication.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="dedication.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="dedication.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="dedication.titlepage.before.recto"/>
+      <xsl:call-template name="dedication.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="dedication.titlepage.before.verso"/>
+      <xsl:call-template name="dedication.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="dedication.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="dedication.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="dedication.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="dedication.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="dedication.titlepage.recto.style">
+<xsl:apply-templates select="." mode="dedication.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="acknowledgements.titlepage.recto">
+  <div xsl:use-attribute-sets="acknowledgements.titlepage.recto.style">
+<xsl:call-template name="component.title">
+<xsl:with-param name="node" select="ancestor-or-self::acknowledgements[1]"/>
+</xsl:call-template></div>
+  <xsl:choose>
+    <xsl:when test="acknowledgementsinfo/subtitle">
+      <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="acknowledgementsinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="acknowledgements.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="acknowledgements.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="acknowledgements.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="acknowledgements.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="acknowledgements.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="acknowledgements.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="acknowledgements.titlepage.before.recto"/>
+      <xsl:call-template name="acknowledgements.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="acknowledgements.titlepage.before.verso"/>
+      <xsl:call-template name="acknowledgements.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="acknowledgements.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="acknowledgements.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="acknowledgements.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="acknowledgements.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="acknowledgements.titlepage.recto.style">
+<xsl:apply-templates select="." mode="acknowledgements.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="preface.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="prefaceinfo/title">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/title"/>
+    </xsl:when>
+    <xsl:when test="docinfo/title">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="prefaceinfo/subtitle">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/corpauthor"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/corpauthor"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/authorgroup"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/authorgroup"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/author"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/author"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/othercredit"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/othercredit"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/releaseinfo"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/copyright"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/copyright"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/legalnotice"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/legalnotice"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/pubdate"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/pubdate"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/revision"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/revision"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/revhistory"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/revhistory"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="prefaceinfo/abstract"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="docinfo/abstract"/>
+  <xsl:apply-templates mode="preface.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="preface.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="preface.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="preface.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="preface.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="preface.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="preface.titlepage.before.recto"/>
+      <xsl:call-template name="preface.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="preface.titlepage.before.verso"/>
+      <xsl:call-template name="preface.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="preface.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="preface.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="preface.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="preface.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="preface.titlepage.recto.style">
+<xsl:apply-templates select="." mode="preface.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="chapter.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="chapterinfo/title">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/title"/>
+    </xsl:when>
+    <xsl:when test="docinfo/title">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="chapterinfo/subtitle">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/corpauthor"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/corpauthor"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/authorgroup"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/authorgroup"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/author"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/author"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/othercredit"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/othercredit"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/releaseinfo"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/copyright"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/copyright"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/legalnotice"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/legalnotice"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/pubdate"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/pubdate"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/revision"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/revision"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/revhistory"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/revhistory"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="chapterinfo/abstract"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="docinfo/abstract"/>
+  <xsl:apply-templates mode="chapter.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="chapter.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="chapter.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="chapter.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="chapter.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="chapter.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="chapter.titlepage.before.recto"/>
+      <xsl:call-template name="chapter.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="chapter.titlepage.before.verso"/>
+      <xsl:call-template name="chapter.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="chapter.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="chapter.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="chapter.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="chapter.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="chapter.titlepage.recto.style">
+<xsl:apply-templates select="." mode="chapter.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="appendix.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="appendixinfo/title">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/title"/>
+    </xsl:when>
+    <xsl:when test="docinfo/title">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="appendixinfo/subtitle">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/corpauthor"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/corpauthor"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/authorgroup"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/authorgroup"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/author"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/author"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/othercredit"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/othercredit"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/releaseinfo"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/copyright"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/copyright"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/legalnotice"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/legalnotice"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/pubdate"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/pubdate"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/revision"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/revision"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/revhistory"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/revhistory"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="appendixinfo/abstract"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="docinfo/abstract"/>
+  <xsl:apply-templates mode="appendix.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="appendix.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="appendix.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="appendix.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="appendix.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="appendix.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="appendix.titlepage.before.recto"/>
+      <xsl:call-template name="appendix.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="appendix.titlepage.before.verso"/>
+      <xsl:call-template name="appendix.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="appendix.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="appendix.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="appendix.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="appendix.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="appendix.titlepage.recto.style">
+<xsl:apply-templates select="." mode="appendix.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="section.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="sectioninfo/title">
+      <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="sectioninfo/subtitle">
+      <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/corpauthor"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/authorgroup"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/author"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/othercredit"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/releaseinfo"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/copyright"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/legalnotice"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/pubdate"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/revision"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/revhistory"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="sectioninfo/abstract"/>
+  <xsl:apply-templates mode="section.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="section.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="section.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if>
+</xsl:template>
+
+<xsl:template name="section.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="section.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="section.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="section.titlepage.before.recto"/>
+      <xsl:call-template name="section.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="section.titlepage.before.verso"/>
+      <xsl:call-template name="section.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="section.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="section.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="section.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="section.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="section.titlepage.recto.style">
+<xsl:apply-templates select="." mode="section.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="sect1.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="sect1info/title">
+      <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="sect1info/subtitle">
+      <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/corpauthor"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/authorgroup"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/author"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/othercredit"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/releaseinfo"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/copyright"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/legalnotice"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/pubdate"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/revision"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/revhistory"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="sect1info/abstract"/>
+  <xsl:apply-templates mode="sect1.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="sect1.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="sect1.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if>
+</xsl:template>
+
+<xsl:template name="sect1.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="sect1.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="sect1.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="sect1.titlepage.before.recto"/>
+      <xsl:call-template name="sect1.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="sect1.titlepage.before.verso"/>
+      <xsl:call-template name="sect1.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="sect1.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="sect1.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="sect1.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="sect1.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect1.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect1.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="sect2.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="sect2info/title">
+      <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="sect2info/subtitle">
+      <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/corpauthor"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/authorgroup"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/author"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/othercredit"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/releaseinfo"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/copyright"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/legalnotice"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/pubdate"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/revision"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/revhistory"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="sect2info/abstract"/>
+  <xsl:apply-templates mode="sect2.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="sect2.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="sect2.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if>
+</xsl:template>
+
+<xsl:template name="sect2.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="sect2.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="sect2.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="sect2.titlepage.before.recto"/>
+      <xsl:call-template name="sect2.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="sect2.titlepage.before.verso"/>
+      <xsl:call-template name="sect2.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="sect2.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="sect2.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="sect2.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="sect2.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect2.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect2.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="sect3.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="sect3info/title">
+      <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="sect3info/subtitle">
+      <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/corpauthor"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/authorgroup"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/author"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/othercredit"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/releaseinfo"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/copyright"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/legalnotice"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/pubdate"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/revision"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/revhistory"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="sect3info/abstract"/>
+  <xsl:apply-templates mode="sect3.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="sect3.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="sect3.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if>
+</xsl:template>
+
+<xsl:template name="sect3.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="sect3.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="sect3.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="sect3.titlepage.before.recto"/>
+      <xsl:call-template name="sect3.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="sect3.titlepage.before.verso"/>
+      <xsl:call-template name="sect3.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="sect3.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="sect3.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="sect3.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="sect3.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect3.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect3.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="sect4.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="sect4info/title">
+      <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="sect4info/subtitle">
+      <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/corpauthor"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/authorgroup"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/author"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/othercredit"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/releaseinfo"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/copyright"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/legalnotice"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/pubdate"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/revision"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/revhistory"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="sect4info/abstract"/>
+  <xsl:apply-templates mode="sect4.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="sect4.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="sect4.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if>
+</xsl:template>
+
+<xsl:template name="sect4.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="sect4.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="sect4.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="sect4.titlepage.before.recto"/>
+      <xsl:call-template name="sect4.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="sect4.titlepage.before.verso"/>
+      <xsl:call-template name="sect4.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="sect4.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="sect4.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="sect4.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="sect4.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect4.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect4.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="sect5.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="sect5info/title">
+      <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="sect5info/subtitle">
+      <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/corpauthor"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/authorgroup"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/author"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/othercredit"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/releaseinfo"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/copyright"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/legalnotice"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/pubdate"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/revision"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/revhistory"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="sect5info/abstract"/>
+  <xsl:apply-templates mode="sect5.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="sect5.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="sect5.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if>
+</xsl:template>
+
+<xsl:template name="sect5.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="sect5.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="sect5.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="sect5.titlepage.before.recto"/>
+      <xsl:call-template name="sect5.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="sect5.titlepage.before.verso"/>
+      <xsl:call-template name="sect5.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="sect5.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="sect5.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="sect5.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="sect5.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sect5.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sect5.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="simplesect.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="simplesectinfo/title">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/title"/>
+    </xsl:when>
+    <xsl:when test="docinfo/title">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="simplesectinfo/subtitle">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/corpauthor"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/corpauthor"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/corpauthor"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/authorgroup"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/authorgroup"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/authorgroup"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/author"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/author"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/author"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/othercredit"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/othercredit"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/othercredit"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/releaseinfo"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/releaseinfo"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/releaseinfo"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/copyright"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/copyright"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/copyright"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/legalnotice"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/legalnotice"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/legalnotice"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/pubdate"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/pubdate"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/pubdate"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/revision"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/revision"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/revision"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/revhistory"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/revhistory"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/revhistory"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="simplesectinfo/abstract"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="docinfo/abstract"/>
+  <xsl:apply-templates mode="simplesect.titlepage.recto.auto.mode" select="info/abstract"/>
+</xsl:template>
+
+<xsl:template name="simplesect.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="simplesect.titlepage.separator"><xsl:if test="count(parent::*)='0'"><hr/></xsl:if>
+</xsl:template>
+
+<xsl:template name="simplesect.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="simplesect.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="simplesect.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="simplesect.titlepage.before.recto"/>
+      <xsl:call-template name="simplesect.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="simplesect.titlepage.before.verso"/>
+      <xsl:call-template name="simplesect.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="simplesect.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="simplesect.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="simplesect.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="corpauthor" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="authorgroup" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="author" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="othercredit" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="releaseinfo" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="copyright" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="legalnotice" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="pubdate" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revision" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="revhistory" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template match="abstract" mode="simplesect.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="simplesect.titlepage.recto.style">
+<xsl:apply-templates select="." mode="simplesect.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="bibliography.titlepage.recto">
+  <div xsl:use-attribute-sets="bibliography.titlepage.recto.style">
+<xsl:call-template name="component.title">
+<xsl:with-param name="node" select="ancestor-or-self::bibliography[1]"/>
+</xsl:call-template></div>
+  <xsl:choose>
+    <xsl:when test="bibliographyinfo/subtitle">
+      <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="bibliographyinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="bibliography.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="bibliography.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="bibliography.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="bibliography.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="bibliography.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="bibliography.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="bibliography.titlepage.before.recto"/>
+      <xsl:call-template name="bibliography.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="bibliography.titlepage.before.verso"/>
+      <xsl:call-template name="bibliography.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="bibliography.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="bibliography.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="bibliography.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="bibliography.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="bibliography.titlepage.recto.style">
+<xsl:apply-templates select="." mode="bibliography.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="glossary.titlepage.recto">
+  <div xsl:use-attribute-sets="glossary.titlepage.recto.style">
+<xsl:call-template name="component.title">
+<xsl:with-param name="node" select="ancestor-or-self::glossary[1]"/>
+</xsl:call-template></div>
+  <xsl:choose>
+    <xsl:when test="glossaryinfo/subtitle">
+      <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="glossaryinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="glossary.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="glossary.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="glossary.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="glossary.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="glossary.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="glossary.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="glossary.titlepage.before.recto"/>
+      <xsl:call-template name="glossary.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="glossary.titlepage.before.verso"/>
+      <xsl:call-template name="glossary.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="glossary.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="glossary.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="glossary.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="glossary.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="glossary.titlepage.recto.style">
+<xsl:apply-templates select="." mode="glossary.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="index.titlepage.recto">
+  <div xsl:use-attribute-sets="index.titlepage.recto.style">
+<xsl:call-template name="component.title">
+<xsl:with-param name="node" select="ancestor-or-self::index[1]"/>
+</xsl:call-template></div>
+  <xsl:choose>
+    <xsl:when test="indexinfo/subtitle">
+      <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="indexinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="index.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="index.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="index.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="index.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="index.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="index.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="index.titlepage.before.recto"/>
+      <xsl:call-template name="index.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="index.titlepage.before.verso"/>
+      <xsl:call-template name="index.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="index.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="index.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="index.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="index.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="index.titlepage.recto.style">
+<xsl:apply-templates select="." mode="index.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="setindex.titlepage.recto">
+  <div xsl:use-attribute-sets="setindex.titlepage.recto.style">
+<xsl:call-template name="component.title">
+<xsl:with-param name="node" select="ancestor-or-self::setindex[1]"/>
+</xsl:call-template></div>
+  <xsl:choose>
+    <xsl:when test="setindexinfo/subtitle">
+      <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="setindexinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="setindex.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="setindex.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="setindex.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="setindex.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="setindex.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="setindex.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="setindex.titlepage.before.recto"/>
+      <xsl:call-template name="setindex.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="setindex.titlepage.before.verso"/>
+      <xsl:call-template name="setindex.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="setindex.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="setindex.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="setindex.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="setindex.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="setindex.titlepage.recto.style">
+<xsl:apply-templates select="." mode="setindex.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+<xsl:template name="sidebar.titlepage.recto">
+  <xsl:choose>
+    <xsl:when test="sidebarinfo/title">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="sidebarinfo/title"/>
+    </xsl:when>
+    <xsl:when test="docinfo/title">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="docinfo/title"/>
+    </xsl:when>
+    <xsl:when test="info/title">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="info/title"/>
+    </xsl:when>
+    <xsl:when test="title">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="title"/>
+    </xsl:when>
+  </xsl:choose>
+
+  <xsl:choose>
+    <xsl:when test="sidebarinfo/subtitle">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="sidebarinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="docinfo/subtitle">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="docinfo/subtitle"/>
+    </xsl:when>
+    <xsl:when test="info/subtitle">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="info/subtitle"/>
+    </xsl:when>
+    <xsl:when test="subtitle">
+      <xsl:apply-templates mode="sidebar.titlepage.recto.auto.mode" select="subtitle"/>
+    </xsl:when>
+  </xsl:choose>
+
+</xsl:template>
+
+<xsl:template name="sidebar.titlepage.verso">
+</xsl:template>
+
+<xsl:template name="sidebar.titlepage.separator">
+</xsl:template>
+
+<xsl:template name="sidebar.titlepage.before.recto">
+</xsl:template>
+
+<xsl:template name="sidebar.titlepage.before.verso">
+</xsl:template>
+
+<xsl:template name="sidebar.titlepage">
+  <div class="titlepage">
+    <xsl:variable name="recto.content">
+      <xsl:call-template name="sidebar.titlepage.before.recto"/>
+      <xsl:call-template name="sidebar.titlepage.recto"/>
+    </xsl:variable>
+    <xsl:variable name="recto.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($recto.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($recto.content) != '') or ($recto.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$recto.content"/></div>
+    </xsl:if>
+    <xsl:variable name="verso.content">
+      <xsl:call-template name="sidebar.titlepage.before.verso"/>
+      <xsl:call-template name="sidebar.titlepage.verso"/>
+    </xsl:variable>
+    <xsl:variable name="verso.elements.count">
+      <xsl:choose>
+        <xsl:when test="function-available('exsl:node-set')"><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:when test="contains(system-property('xsl:vendor'), 'Apache Software Foundation')">
+          <!--Xalan quirk--><xsl:value-of select="count(exsl:node-set($verso.content)/*)"/></xsl:when>
+        <xsl:otherwise>1</xsl:otherwise>
+      </xsl:choose>
+    </xsl:variable>
+    <xsl:if test="(normalize-space($verso.content) != '') or ($verso.elements.count &gt; 0)">
+      <div><xsl:copy-of select="$verso.content"/></div>
+    </xsl:if>
+    <xsl:call-template name="sidebar.titlepage.separator"/>
+  </div>
+</xsl:template>
+
+<xsl:template match="*" mode="sidebar.titlepage.recto.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="*" mode="sidebar.titlepage.verso.mode">
+  <!-- if an element isn't found in this mode, -->
+  <!-- try the generic titlepage.mode -->
+  <xsl:apply-templates select="." mode="titlepage.mode"/>
+</xsl:template>
+
+<xsl:template match="title" mode="sidebar.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sidebar.titlepage.recto.style">
+<xsl:call-template name="formal.object.heading">
+<xsl:with-param name="object" select="ancestor-or-self::sidebar[1]"/>
+</xsl:call-template>
+</div>
+</xsl:template>
+
+<xsl:template match="subtitle" mode="sidebar.titlepage.recto.auto.mode">
+<div xsl:use-attribute-sets="sidebar.titlepage.recto.style">
+<xsl:apply-templates select="." mode="sidebar.titlepage.recto.mode"/>
+</div>
+</xsl:template>
+
+</xsl:stylesheet>
+
diff --git a/documentation/yocto-project-qs/yocto-project-qs.xml b/documentation/yocto-project-qs/yocto-project-qs.xml
new file mode 100644
index 0000000000..3d6f98d5d5
--- /dev/null
+++ b/documentation/yocto-project-qs/yocto-project-qs.xml
@@ -0,0 +1,963 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[<!ENTITY % poky SYSTEM "../poky.ent"> %poky; ] >
+
+<article id='intro'>
+    <articleinfo>
+        <title>Yocto Project Quick Start</title>
+
+        <copyright>
+            <year>&COPYRIGHT_YEAR;</year>
+            <holder>Linux Foundation</holder>
+        </copyright>
+
+        <legalnotice>
+            <para>
+                Permission is granted to copy, distribute and/or modify this document under
+                the terms of the <ulink type="http" url="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative Commons Attribution-Share Alike 2.0 UK: England &amp; Wales</ulink> as published by Creative Commons.
+            </para>
+            <note>
+                For the latest version of this manual associated with this
+                Yocto Project release, see the
+                <ulink url='&YOCTO_DOCS_QS_URL;'>Yocto Project Quick Start</ulink>
+                from the Yocto Project website.
+            </note>
+        </legalnotice>
+
+
+        <abstract>
+            <imagedata fileref="figures/yocto-project-transp.png"
+                        width="6in" depth="1in"
+                        align="right" scale="25" />
+        </abstract>
+    </articleinfo>
+
+<section id='welcome'>
+    <title>Welcome!</title>
+    <para>
+        Welcome to the Yocto Project!
+        The Yocto Project is an open-source collaboration project focused on embedded Linux
+        developers.
+        Among other things, the Yocto Project uses a build system based on the Poky project
+        to construct complete Linux images.
+        The Poky project, in turn, draws from and contributes back to the OpenEmbedded project.
+    </para>
+
+    <para>
+        If you don't have a system that runs Linux and you want to give the Yocto Project a test run,
+        you might consider using the Yocto Project Build Appliance.
+        The Build Appliance allows you to build and boot a custom embedded Linux image with the Yocto
+        Project using a non-Linux development system.
+        See the <ulink url='http://www.yoctoproject.org/documentation/build-appliance'>Yocto
+        Project Build Appliance</ulink> for more information.
+    </para>
+
+    <para>
+        On the other hand, if you know all about open-source development, Linux development environments,
+        Git source repositories and the like and you just want some quick information that lets you try out
+        the Yocto Project on your Linux system, skip right to the
+        "<link linkend='super-user'>Super User</link>" section at the end of this quick start.
+    </para>
+
+    <para>
+        For the rest of you, this short document will give you some basic information about the environment and
+        let you experience it in its simplest form.
+        After reading this document, you will have a basic understanding of what the Yocto Project is
+        and how to use some of its core components.
+        This document steps you through a simple example showing you how to build a small image
+        and run it using the Quick EMUlator (QEMU emulator).
+    </para>
+
+    <para>
+        For more detailed information on the Yocto Project, you should check out these resources:
+        <itemizedlist>
+            <listitem><para><emphasis>Website:</emphasis> The <ulink url='&YOCTO_HOME_URL;'>Yocto Project Website</ulink>
+                provides the latest builds, breaking news, full development documentation, and a rich Yocto
+                Project Development Community into which you can tap.
+                </para></listitem>
+            <listitem><para><emphasis>FAQs:</emphasis> Lists commonly asked Yocto Project questions and answers.
+                You can find two FAQs: <ulink url='&YOCTO_WIKI_URL;/wiki/FAQ'>Yocto Project FAQ</ulink> on
+                a wiki, and the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink>" chapter in
+                the Yocto Project Reference Manual.
+                </para></listitem>
+            <listitem><para><emphasis>Developer Screencast:</emphasis> The
+                <ulink url='http://vimeo.com/36450321'>Getting Started with the Yocto Project - New
+                Developer Screencast Tutorial</ulink> provides a 30-minute video for the user
+                new to the Yocto Project but familiar with Linux build systems.</para></listitem>
+        </itemizedlist>
+    </para>
+</section>
+
+<section id='yp-intro'>
+    <title>Introducing the Yocto Project Development Environment</title>
+    <para>
+        The Yocto Project through the OpenEmbedded build system provides an open source development
+        environment targeting the ARM, MIPS, PowerPC and x86 architectures for a variety of
+        platforms including x86-64 and emulated ones.
+        You can use components from the Yocto Project to design, develop, build, debug, simulate,
+        and test the complete software stack using Linux, the X Window System, GNOME Mobile-based
+        application frameworks, and Qt frameworks.
+    </para>
+
+    <mediaobject>
+        <imageobject>
+            <imagedata fileref="figures/yocto-environment.png"
+                format="PNG" align='center' scalefit='1' width="100%"/>
+        </imageobject>
+        <caption>
+            <para>The Yocto Project Development Environment</para>
+        </caption>
+     </mediaobject>
+
+    <para>
+        Here are some highlights for the Yocto Project:
+    </para>
+
+    <itemizedlist>
+        <listitem>
+            <para>Provides a recent Linux kernel along with a set of system commands and libraries suitable for the embedded environment.</para>
+        </listitem>
+        <listitem>
+            <para>Makes available system components such as X11, GTK+, Qt, Clutter, and SDL
+            (among others) so you can create a rich user experience on devices
+            that have display hardware.
+            For devices that don't have a display or where you wish to use alternative UI
+            frameworks, these components need not be installed.</para>
+        </listitem>
+        <listitem>
+            <para>Creates a focused and stable core compatible with the OpenEmbedded
+            project with which you can easily and reliably build and develop.</para>
+        </listitem>
+        <listitem>
+            <para>Fully supports a wide range of hardware and device emulation through the QEMU
+            Emulator.</para>
+        </listitem>
+    </itemizedlist>
+
+    <para>
+        The Yocto Project can generate images for many kinds of devices.
+        However, the standard example machines target QEMU full-system emulation for x86, x86-64, ARM, MIPS,
+        and PPC-based architectures as well as specific hardware such as the
+        <trademark class='registered'>Intel</trademark> Desktop Board DH55TC.
+        Because an image developed with the Yocto Project can boot inside a QEMU emulator, the
+        development environment works nicely as a test platform for developing embedded software.
+    </para>
+
+    <para>
+        Another important Yocto Project feature is the Sato reference User Interface.
+        This optional GNOME mobile-based UI, which is intended for devices with
+        restricted screen sizes, sits neatly on top of a device using the
+        GNOME Mobile Stack and provides a well-defined user experience.
+        Implemented in its own layer, it makes it clear to developers how they can implement
+        their own user interface on top of a Linux image created with the Yocto Project.
+    </para>
+</section>
+
+<section id='yp-resources'>
+    <title>What You Need and How You Get It</title>
+
+    <para>
+        You need these things to develop in the Yocto Project environment:
+    </para>
+
+    <itemizedlist>
+        <listitem>
+            <para>A host system running a supported Linux distribution
+                (i.e. recent releases of Fedora, openSUSE, CentOS, Debian,
+                and Ubuntu).
+                If the host system supports multiple cores and threads, you can configure the
+                Yocto Project build system to decrease the time needed to build images
+                significantly.
+            </para>
+        </listitem>
+        <listitem>
+            <para>The right packages.</para>
+        </listitem>
+        <listitem>
+            <para>A release of the Yocto Project.</para>
+        </listitem>
+    </itemizedlist>
+
+    <section id='the-linux-distro'>
+        <title>The Linux Distribution</title>
+
+        <para>
+            The Yocto Project team is continually verifying more and more Linux
+            distributions with each release.
+            In general, if you have the current release minus one of the following
+            distributions you should have no problems.
+            <itemizedlist>
+                <listitem><para>Ubuntu</para></listitem>
+                <listitem><para>Fedora</para></listitem>
+                <listitem><para>openSUSE</para></listitem>
+                <listitem><para>CentOS</para></listitem>
+                <listitem><para>Debian</para></listitem>
+            </itemizedlist>
+            For a more detailed list of distributions that support the Yocto Project,
+            see the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>" section
+            in the Yocto Project Reference Manual.
+            </para>
+        <para>
+            The OpenEmbedded build system should be able to run on any modern
+            distribution that has the following versions for Git, tar, and
+            Python.
+            <itemizedlist>
+                <listitem><para>Git 1.7.5 or greater</para></listitem>
+                <listitem><para>tar 1.24 or greater</para></listitem>
+                <listitem><para>Python 2.7.3 or greater excluding Python
+                   3.x, which is not supported.</para></listitem>
+            </itemizedlist>
+            Earlier releases of Python are known to not work and the system
+            does not support Python 3 at this time.
+            If your system does not meet any of these three listed
+            version requirements, you can
+            take steps to prepare the system so that you can still use the build
+            system.
+            See the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#required-git-tar-and-python-versions'>Required Git, tar, and Python Versions</ulink>"
+            section in the Yocto Project Reference Manual for information.
+        </para>
+        <para>
+            This document assumes you are running one of the previously noted
+            distributions on your Linux-based host systems.
+        </para>
+        <note>
+            <para>
+                If you attempt to use a distribution not in the above list,
+                you may or may not have success.
+                Yocto Project releases are tested against the stable Linux
+                distributions listed in the
+                "<ulink url='&YOCTO_DOCS_REF_URL;#detailed-supported-distros'>Supported Linux Distributions</ulink>"
+                section of the Yocto Project Reference Manual.
+                Refer to
+                <ulink url='&OE_HOME_URL;/index.php?title=OEandYourDistro'>OE and Your Distro</ulink> and
+                <ulink url='&OE_HOME_URL;/index.php?title=Required_software'>Required Software</ulink>
+                for information for information about dependencies and
+                requirements.
+                If you encounter problems, please go to
+                <ulink url='&YOCTO_BUGZILLA_URL;'>Yocto Project Bugzilla</ulink>
+                and submit a bug.
+                We are interested in hearing about your experience.
+            </para>
+        </note>
+    </section>
+
+    <section id='packages'>
+        <title>The Packages</title>
+
+        <para>
+            Packages and package installation vary depending on your development system
+            and on your intent.
+            For example, if you want to build an image that can run
+            on QEMU in graphical mode (a minimal, basic build
+            requirement), then the number of packages is different than if you want to
+            build an image on a headless system or build out the Yocto Project
+            documentation set.
+            Collectively, the number of required packages is large
+            if you want to be able to cover all cases.
+            <note>In general, you need to have root access and then install the
+                required packages.
+                Thus, the commands in the following section may or may not work
+                depending on whether or not your Linux distribution has
+                <filename>sudo</filename> installed.</note>
+        </para>
+
+        <para>
+            The next few sections list, by supported Linux Distributions, the required
+            packages needed to build an image that runs on QEMU in graphical mode
+            (e.g. essential plus graphics support).
+        </para>
+
+        <para>
+            For lists of required packages for other scenarios, see the
+            "<ulink url='&YOCTO_DOCS_REF_URL;#required-packages-for-the-host-development-system'>Required Packages for the Host Development System</ulink>"
+            section in the Yocto Project Reference Manual.
+        </para>
+
+        <section id='ubuntu'>
+            <title>Ubuntu and Debian</title>
+
+            <para>
+                The essential and graphical support packages you need for a
+                supported Ubuntu or Debian distribution are shown in the
+                following command:
+                <literallayout class='monospaced'>
+     $ sudo apt-get install &UBUNTU_HOST_PACKAGES_ESSENTIAL; libsdl1.2-dev xterm
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='fedora'>
+            <title>Fedora</title>
+
+            <para>
+                The essential and graphical packages you need for a supported
+                Fedora distribution are shown in the following command:
+                <literallayout class='monospaced'>
+     $ sudo yum install &FEDORA_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='opensuse'>
+            <title>OpenSUSE</title>
+
+            <para>
+                The essential and graphical packages you need for a supported
+                OpenSUSE distribution are shown in the following command:
+                <literallayout class='monospaced'>
+     $ sudo zypper install &OPENSUSE_HOST_PACKAGES_ESSENTIAL; libSDL-devel xterm
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='centos'>
+            <title>CentOS</title>
+
+            <para>
+                The essential and graphical packages you need for a supported
+                CentOS distribution are shown in the following command:
+                <literallayout class='monospaced'>
+     $ sudo yum install &CENTOS_HOST_PACKAGES_ESSENTIAL; SDL-devel xterm
+                </literallayout>
+                <note>Depending on the CentOS version you are using, other requirements
+                    and dependencies might exist.
+                    For details, you should look at the CentOS sections on the
+                    <ulink url='https://wiki.yoctoproject.org/wiki/Poky/GettingStarted/Dependencies'>Poky/GettingStarted/Dependencies</ulink>
+                    wiki page.</note>
+            </para>
+        </section>
+    </section>
+
+    <section id='releases'>
+        <title>Yocto Project Release</title>
+
+        <para>
+            You can download the latest Yocto Project release by going to the
+            <ulink url="&YOCTO_HOME_URL;">Yocto Project website</ulink>
+            clicking "Downloads" in the navigation pane to the left to view all
+            available Yocto Project releases.
+            Current and archived releases are available for download to the
+            right.
+            Nightly and developmental builds are also maintained at
+            <ulink url="&YOCTO_AB_NIGHTLY_URL;"></ulink>.
+            However, for this document a released version of Yocto Project is used.
+        </para>
+
+        <para>
+            You can also get the Yocto Project files you need by setting up (cloning in Git terms)
+            a local copy of the <filename>poky</filename> Git repository on your host development
+            system.
+            Doing so allows you to contribute back to the Yocto Project project.
+            For information on how to get set up using this method, see the
+            "<ulink url='&YOCTO_DOCS_DEV_URL;#local-yp-release'>Yocto
+            Project Release</ulink>" item in the Yocto Project Development Manual.
+        </para>
+    </section>
+</section>
+
+<section id='test-run'>
+    <title>A Quick Test Run</title>
+
+    <para>
+        Now that you have your system requirements in order, you can give the Yocto Project a try.
+        This section presents some steps that let you do the following:
+    </para>
+
+    <itemizedlist>
+        <listitem>
+            <para>Build an image and run it in the QEMU emulator</para>
+        </listitem>
+        <listitem>
+            <para>Use a pre-built image and run it in the QEMU emulator</para>
+        </listitem>
+    </itemizedlist>
+
+    <section id='building-image'>
+        <title>Building an Image</title>
+
+        <para>
+            In the development environment you will need to build an image whenever you change hardware
+            support, add or change system libraries, or add or change services that have dependencies.
+        </para>
+
+        <mediaobject>
+            <imageobject>
+                <imagedata fileref="figures/building-an-image.png" format="PNG" align='center' scalefit='1'/>
+            </imageobject>
+            <caption>
+                <para>Building an Image</para>
+            </caption>
+         </mediaobject>
+
+         <para>
+             Use the following commands to build your image.
+             The OpenEmbedded build process creates an entire Linux distribution, including the toolchain,
+             from source.
+         </para>
+
+         <note><para>
+             The build process using Sato currently consumes about 50GB of disk space.
+             To allow for variations in the build process and for future package expansion, we
+             recommend having at least 100GB of free disk space.
+         </para></note>
+
+         <note><para>
+             By default, the build process searches for source code using a pre-determined order
+             through a set of locations.
+             If you encounter problems with the build process finding and downloading source code, see the
+             "<ulink url='&YOCTO_DOCS_REF_URL;#how-does-the-yocto-project-obtain-source-code-and-will-it-work-behind-my-firewall-or-proxy-server'>How does the OpenEmbedded build system obtain source code and will it work behind my
+             firewall or proxy server?</ulink>" in the Yocto Project Reference Manual.
+         </para></note>
+
+         <para>
+             <literallayout class='monospaced'>
+     $ wget &YOCTO_POKY_DL_URL;
+     $ tar xjf &YOCTO_POKY;.tar.bz2
+     $ cd &YOCTO_POKY;
+     $ source &OE_INIT_FILE;
+             </literallayout>
+         </para>
+
+         <tip><para>
+             To help conserve disk space during builds, you can add the following statement
+             to your project's configuration file, which for this example
+             is <filename>&YOCTO_POKY;/build/conf/local.conf</filename>.
+             Adding this statement deletes the work directory used for building a package
+             once the package is built.
+             <literallayout class='monospaced'>
+     INHERIT += "rm_work"
+             </literallayout>
+         </para></tip>
+
+         <itemizedlist>
+             <listitem><para>In the previous example, the first command retrieves the Yocto Project
+                 release tarball from the source repositories using the
+                 <filename>wget</filename> command.
+                 Alternatively, you can go to the
+                 <ulink url='&YOCTO_HOME_URL;'>Yocto Project website's</ulink>
+                 "Downloads" page to retrieve the tarball.</para></listitem>
+             <listitem><para>The second command extracts the files from the tarball and places
+                 them into a directory named <filename>&YOCTO_POKY;</filename> in the current
+                 directory.</para></listitem>
+             <listitem><para>The third and fourth commands change the working directory to the
+                 <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+                 and run the Yocto Project
+                 <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>
+                 environment setup script.
+                 Running this script defines OpenEmbedded build environment settings needed to
+                 complete the build.
+                 The script also creates the
+                 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>,
+                 which is <filename>build</filename> in this case and is located in the
+                 Source Directory.
+                 After the script runs, your current working directory is set
+                 to the Build Directory.
+                 Later, when the build completes, the Build Directory contains all the files
+                 created during the build.
+                 <note>
+                     For information on running a memory-resident BitBake, see
+                     the
+                     <ulink url='&YOCTO_DOCS_REF_URL;#structure-memres-core-script'><filename>oe-init-build-env-memres</filename></ulink>
+                     setup script.
+                 </note></para></listitem>
+         </itemizedlist>
+         <para>
+             Take some time to examine your <filename>local.conf</filename> file
+             in your project's configuration directory, which is found in the Build Directory.
+             The defaults in that file should work fine.
+             However, there are some variables of interest at which you might look.
+         </para>
+
+         <para>
+             By default, the target architecture for the build is <filename>qemux86</filename>,
+             which produces an image that can be used in the QEMU emulator and is targeted at an
+             <trademark class='registered'>Intel</trademark> 32-bit based architecture.
+             To change this default, edit the value of the
+             <ulink url='&YOCTO_DOCS_REF_URL;#var-MACHINE'><filename>MACHINE</filename></ulink>
+             variable in the configuration file before launching the build.
+         </para>
+
+         <para>
+             Another couple of variables of interest are the
+             <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink> and the
+             <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> variables.
+             By default, these variables are commented out.
+             However, if you have a multi-core CPU you might want to uncomment
+             the lines and set both variables equal to twice the number of your
+             host's processor cores.
+             Setting these variables can significantly shorten your build time.
+         </para>
+
+        <para>
+            Another consideration before you build is the package manager used when creating
+            the image.
+            By default, the OpenEmbedded build system uses the RPM package manager.
+            You can control this configuration by using the
+            <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink></filename> variable.
+             For additional package manager selection information, see the
+             "<ulink url='&YOCTO_DOCS_REF_URL;#ref-classes-package'>Packaging - <filename>package*.bbclass</filename></ulink>"
+             section in the Yocto Project Reference Manual.
+        </para>
+
+         <para>
+             Continue with the following command to build an OS image for the target, which is
+             <filename>core-image-sato</filename> in this example.
+             For information on the <filename>-k</filename> option use the
+             <filename>bitbake --help</filename> command or see the
+             "<ulink url='&YOCTO_DOCS_REF_URL;#usingpoky-components-bitbake'>BitBake</ulink>" section in
+             the Yocto Project Reference Manual.
+             <literallayout class='monospaced'>
+     $ bitbake -k core-image-sato
+             </literallayout>
+             <note><para>
+                 BitBake requires Python 2.6 or 2.7.  For more information on this requirement,
+                 see the
+                 <ulink url='&YOCTO_DOCS_REF_URL;#faq'>FAQ</ulink> in the Yocto Project Reference
+                 Manual.
+             </para></note>
+             The final command runs the image:
+             <literallayout class='monospaced'>
+     $ runqemu qemux86
+             </literallayout>
+             <note><para>
+                 Depending on the number of processors and cores, the amount or RAM, the speed of your
+                 Internet connection and other factors, the build process could take several hours the first
+                 time you run it.
+                 Subsequent builds run much faster since parts of the build are cached.
+             </para></note>
+         </para>
+    </section>
+
+    <section id='using-pre-built'>
+        <title>Using Pre-Built Binaries and QEMU</title>
+
+        <para>
+            If hardware, libraries and services are stable, you can get started by using a pre-built binary
+            of the filesystem image, kernel, and toolchain and run it using the QEMU emulator.
+            This scenario is useful for developing application software.
+        </para>
+
+        <mediaobject>
+            <imageobject>
+            <imagedata fileref="figures/using-a-pre-built-image.png" format="PNG" align='center' scalefit='1'/>
+            </imageobject>
+            <caption>
+                <para>Using a Pre-Built Image</para>
+            </caption>
+        </mediaobject>
+
+        <para>
+            For this scenario, you need to do several things:
+        </para>
+
+        <itemizedlist>
+            <listitem><para>Install the appropriate stand-alone toolchain tarball.</para></listitem>
+            <listitem><para>Download the pre-built image that will boot with QEMU.
+                You need to be sure to get the QEMU image that matches your target machine’s
+                architecture (e.g. x86, ARM, etc.).</para></listitem>
+            <listitem><para>Download the filesystem image for your target machine's architecture.
+                </para></listitem>
+            <listitem><para>Set up the environment to emulate the hardware and then start the QEMU emulator.
+                </para></listitem>
+        </itemizedlist>
+
+        <section id='installing-the-toolchain'>
+            <title>Installing the Toolchain</title>
+
+            <para>
+                You can download a tarball installer, which includes the
+                pre-built toolchain, the <filename>runqemu</filename>
+                script, and support files from the appropriate directory under
+                <ulink url='&YOCTO_TOOLCHAIN_DL_URL;'></ulink>.
+                Toolchains are available for 32-bit and 64-bit x86 development
+                systems from the <filename>i686</filename> and
+                <filename>x86_64</filename> directories, respectively.
+                The toolchains the Yocto Project provides are based off the
+                <filename>core-image-sato</filename> image and contain
+                libraries appropriate for developing against that image.
+                Each type of development system supports five or more target
+                architectures.
+            </para>
+
+            <para>
+                The names of the tarball installer scripts are such that a
+                string representing the host system appears first in the
+                filename and then is immediately followed by a string
+                that represents the target architecture.
+            </para>
+
+            <literallayout class='monospaced'>
+     poky-eglibc-&lt;<emphasis>host_system</emphasis>&gt;-&lt;<emphasis>image_type</emphasis>&gt;-&lt;<emphasis>arch</emphasis>&gt;-toolchain-&lt;<emphasis>release_version</emphasis>&gt;.sh
+
+     Where:
+         &lt;<emphasis>host_system</emphasis>&gt; is a string representing your development system:
+
+                    i686 or x86_64.
+
+         &lt;<emphasis>image_type</emphasis>&gt; is a string representing the image you wish to
+                develop a Software Development Toolkit (SDK) for use against.
+                The Yocto Project builds toolchain installers using the
+                following BitBake command:
+
+                    bitbake core-image-sato -c do_populatesdk core-image-sato
+
+         &lt;<emphasis>arch</emphasis>&gt; is a string representing the tuned target architecture:
+
+                    i586, x86_64, powerpc, mips, armv7a or armv5te
+
+         &lt;<emphasis>release_version</emphasis>&gt; is a string representing the release number of the
+                Yocto Project:
+
+                    &DISTRO;, &DISTRO;+snapshot
+            </literallayout>
+
+            <para>
+                For example, the following toolchain installer is for a 64-bit
+                development host system and a i586-tuned target architecture
+                based off the SDK for <filename>core-image-sato</filename>:
+                <literallayout class='monospaced'>
+     poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+                </literallayout>
+            </para>
+
+            <para>
+                Toolchains are self-contained and by default are installed into
+                <filename>/opt/poky</filename>.
+                However, when you run the toolchain installer, you can choose an
+                installation directory.
+            </para>
+
+            <para>
+                The following command shows how to run the installer given a toolchain tarball
+                for a 64-bit x86 development host system and a 32-bit x86 target architecture.
+                You must change the permissions on the toolchain
+                installer script so that it is executable.
+            </para>
+
+            <para>
+                The example assumes the toolchain installer is located in <filename>~/Downloads/</filename>.
+                <note>
+                    If you do not have write permissions for the directory into which you are installing
+                    the toolchain, the toolchain installer notifies you and exits.
+                    Be sure you have write permissions in the directory and run the installer again.
+                </note>
+            </para>
+
+            <para>
+                <literallayout class='monospaced'>
+     $ ~/Downloads/poky-eglibc-x86_64-core-image-sato-i586-toolchain-&DISTRO;.sh
+                </literallayout>
+            </para>
+
+            <para>
+                For more information on how to install tarballs, see the
+                "<ulink url='&YOCTO_DOCS_ADT_URL;#using-an-existing-toolchain-tarball'>Using a Cross-Toolchain Tarball</ulink>" and
+                "<ulink url='&YOCTO_DOCS_ADT_URL;#using-the-toolchain-from-within-the-build-tree'>Using BitBake and the Build Directory</ulink>" sections in the Yocto Project Application Developer's Guide.
+            </para>
+        </section>
+
+        <section id='downloading-the-pre-built-linux-kernel'>
+            <title>Downloading the Pre-Built Linux Kernel</title>
+
+            <para>
+                You can download the pre-built Linux kernel suitable for running in the QEMU emulator from
+                <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
+                Be sure to use the kernel that matches the architecture you want to simulate.
+                Download areas exist for the five supported machine architectures:
+                <filename>qemuarm</filename>, <filename>qemumips</filename>, <filename>qemuppc</filename>,
+                <filename>qemux86</filename>, and <filename>qemux86-64</filename>.
+            </para>
+
+            <para>
+                Most kernel files have one of the following forms:
+                <literallayout class='monospaced'>
+     *zImage-qemu&lt;<emphasis>arch</emphasis>&gt;.bin
+     vmlinux-qemu&lt;<emphasis>arch</emphasis>&gt;.bin
+
+     Where:
+         &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
+                x86, x86-64, ppc, mips, or arm.
+                </literallayout>
+            </para>
+
+            <para>
+                You can learn more about downloading a Yocto Project kernel in the
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#local-kernel-files'>Yocto Project Kernel</ulink>"
+                bulleted item in the Yocto Project Development Manual.
+            </para>
+        </section>
+
+        <section id='downloading-the-filesystem'>
+            <title>Downloading the Filesystem</title>
+
+            <para>
+                You can also download the filesystem image suitable for your target architecture from
+                <ulink url='&YOCTO_QEMU_DL_URL;'></ulink>.
+                Again, be sure to use the filesystem that matches the architecture you want
+                to simulate.
+            </para>
+
+            <para>
+                The filesystem image has two tarball forms: <filename>ext3</filename> and
+                <filename>tar</filename>.
+                You must use the <filename>ext3</filename> form when booting an image using the
+                QEMU emulator.
+                The <filename>tar</filename> form can be flattened out in your host development system
+                and used for build purposes with the Yocto Project.
+                <literallayout class='monospaced'>
+     core-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.ext3
+     core-image-&lt;<emphasis>profile</emphasis>&gt;-qemu&lt;<emphasis>arch</emphasis>&gt;.tar.bz2
+
+     Where:
+         &lt;<emphasis>profile</emphasis>&gt; is the filesystem image's profile:
+                   lsb, lsb-dev, lsb-sdk, lsb-qt3, minimal, minimal-dev, sato,
+                   sato-dev, or sato-sdk. For information on these types of image
+                   profiles, see the "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" chapter in the Yocto Project
+                   Reference Manual.
+
+         &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
+                x86, x86-64, ppc, mips, or arm.
+                </literallayout>
+            </para>
+        </section>
+
+        <section id='setting-up-the-environment-and-starting-the-qemu-emulator'>
+            <title>Setting Up the Environment and Starting the QEMU Emulator</title>
+
+            <para>
+                Before you start the QEMU emulator, you need to set up the emulation environment.
+                The following command form sets up the emulation environment.
+                <literallayout class='monospaced'>
+     $ source &YOCTO_ADTPATH_DIR;/environment-setup-&lt;<emphasis>arch</emphasis>&gt;-poky-linux-&lt;<emphasis>if</emphasis>&gt;
+
+     Where:
+         &lt;<emphasis>arch</emphasis>&gt; is a string representing the target architecture:
+                i586, x86_64, ppc603e, mips, or armv5te.
+
+         &lt;<emphasis>if</emphasis>&gt; is a string representing an embedded application binary interface.
+              Not all setup scripts include this string.
+                </literallayout>
+            </para>
+
+            <para>
+                Finally, this command form invokes the QEMU emulator
+                <literallayout class='monospaced'>
+     $ runqemu &lt;<emphasis>qemuarch</emphasis>&gt; &lt;<emphasis>kernel-image</emphasis>&gt; &lt;<emphasis>filesystem-image</emphasis>&gt;
+
+     Where:
+         &lt;<emphasis>qemuarch</emphasis>&gt; is a string representing the target architecture: qemux86, qemux86-64,
+                    qemuppc, qemumips, or qemuarm.
+
+         &lt;<emphasis>kernel-image</emphasis>&gt; is the architecture-specific kernel image.
+
+         &lt;<emphasis>filesystem-image</emphasis>&gt; is the .ext3 filesystem image.
+
+                </literallayout>
+            </para>
+
+            <para>
+                Continuing with the example, the following two commands setup the emulation
+                environment and launch QEMU.
+                This example assumes the root filesystem (<filename>.ext3</filename> file) and
+                the pre-built kernel image file both reside in your home directory.
+                The kernel and filesystem are for a 32-bit target architecture.
+                <literallayout class='monospaced'>
+     $ cd $HOME
+     $ source &YOCTO_ADTPATH_DIR;/environment-setup-i586-poky-linux
+     $ runqemu qemux86 bzImage-qemux86.bin \
+     core-image-sato-qemux86.ext3
+                </literallayout>
+            </para>
+
+            <para>
+                The environment in which QEMU launches varies depending on the filesystem image and on the
+                target architecture.
+                For example, if you source the environment for the ARM target
+                architecture and then boot the minimal QEMU image, the emulator comes up in a new
+                shell in command-line mode.
+                However, if you boot the SDK image, QEMU comes up with a GUI.
+                <note>Booting the PPC image results in QEMU launching in the same shell in
+                command-line mode.</note>
+            </para>
+        </section>
+    </section>
+</section>
+
+<section id='super-user'>
+    <title>Super User
+</title>
+
+    <para>
+        This section
+        <footnote>
+            <para>
+                Kudos and thanks to Robert P. J. Day of
+                <ulink url='http://www.crashcourse.ca'>CrashCourse</ulink> for providing the basis
+                for this "expert" section with information from one of his
+                <ulink url='http://www.crashcourse.ca/wiki/index.php/Yocto_Project_Quick_Start'>wiki</ulink>
+                pages.
+            </para>
+        </footnote>
+        gives you a minimal description of how to use the Yocto Project to build images
+        for a BeagleBoard xM starting from scratch.
+        The steps were performed on a 64-bit Ubuntu 10.04 system.
+    </para>
+
+    <section id='getting-yocto'>
+        <title>Getting the Yocto Project</title>
+
+        <para>
+            Set up your <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>
+            one of two ways:
+            <itemizedlist>
+                <listitem><para><emphasis>Tarball:</emphasis>
+                    Use if you want the latest stable release:
+                    <literallayout class='monospaced'>
+     $ wget &YOCTO_RELEASE_DL_URL;/&YOCTO_POKY_TARBALL;
+     $ tar xvjf &YOCTO_POKY_TARBALL;
+                    </literallayout></para></listitem>
+                <listitem><para><emphasis>Git Repository:</emphasis>
+                    Use if you want to work with cutting edge development content:
+                    <literallayout class='monospaced'>
+     $ git clone git://git.yoctoproject.org/poky
+                    </literallayout></para></listitem>
+            </itemizedlist>
+            The remainder of the section assumes the Git repository method.
+        </para>
+    </section>
+
+    <section id='setting-up-your-host'>
+        <title>Setting Up Your Host</title>
+
+        <para>
+            You need some packages for everything to work.
+            Rather than duplicate them here, look at the "<link linkend='packages'>The Packages</link>"
+            section earlier in this quick start.
+        </para>
+    </section>
+
+    <section id='initializing-the-build-environment'>
+        <title>Initializing the Build Environment</title>
+
+        <para>
+            From the parent directory your
+            <ulink url='&YOCTO_DOCS_DEV_URL;#source-directory'>Source Directory</ulink>,
+            initialize your environment and provide a meaningful
+            <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
+            name:
+            <literallayout class='monospaced'>
+     $ source poky/&OE_INIT_FILE; mybuilds
+            </literallayout>
+            At this point, the <filename>mybuilds</filename> directory has been created for you
+            and it is now your current working directory.
+            If you don't provide your own directory name it defaults to <filename>build</filename>,
+            which is inside the Source Directory.
+        </para>
+    </section>
+
+    <section id='configuring-the-local.conf-file'>
+        <title>Configuring the local.conf File</title>
+
+        <para>
+            Initializing the build environment creates a <filename>conf/local.conf</filename> configuration file
+            in the Build Directory.
+            You need to manually edit this file to specify the machine you are building and to optimize
+            your build time.
+            Here are the minimal changes to make:
+            <literallayout class='monospaced'>
+     BB_NUMBER_THREADS = "8"
+     PARALLEL_MAKE = "-j 8"
+     MACHINE ?= "beagleboard"
+            </literallayout>
+            Briefly, set <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_NUMBER_THREADS'><filename>BB_NUMBER_THREADS</filename></ulink>
+            and <ulink url='&YOCTO_DOCS_REF_URL;#var-PARALLEL_MAKE'><filename>PARALLEL_MAKE</filename></ulink> to
+            twice your host processor's number of cores.
+        </para>
+
+        <para>
+            A good deal that goes into a Yocto Project build is simply
+            downloading all of the source tarballs.
+            Maybe you have been working with another build system
+            (OpenEmbedded or Angstrom) for which you have built up a sizable
+            directory of source tarballs.
+            Or, perhaps someone else has such a directory for which you have
+            read access.
+            If so, you can save time by adding statements to your
+            configuration file so that the build process checks local
+            directories first for existing tarballs before checking the
+            Internet.
+            Here is an efficient way to set it up in your
+            <filename>local.conf</filename> file:
+            <literallayout class='monospaced'>
+     SOURCE_MIRROR_URL ?= "file:///home/you/your-download-dir/"
+     INHERIT += "own-mirrors"
+     BB_GENERATE_MIRROR_TARBALLS = "1"
+     # BB_NO_NETWORK = "1"
+            </literallayout>
+        </para>
+
+        <para>
+            In the previous example, the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-BB_GENERATE_MIRROR_TARBALLS'><filename>BB_GENERATE_MIRROR_TARBALLS</filename></ulink>
+            variable causes the OpenEmbedded build system to generate tarballs
+            of the Git repositories and store them in the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink>
+            directory.
+            Due to performance reasons, generating and storing these tarballs
+            is not the build system's default behavior.
+        </para>
+
+        <para>
+            You can also use the
+            <ulink url='&YOCTO_DOCS_REF_URL;#var-PREMIRRORS'><filename>PREMIRRORS</filename></ulink>
+            variable.
+            For an example, see the variable's glossary entry in the
+            Yocto Project Reference Manual.
+        </para>
+    </section>
+
+    <section id='building-the-image'>
+        <title>Building the Image</title>
+
+        <para>
+            At this point, you need to select an image to build for the BeagleBoard xM.
+            If this is your first build using the Yocto Project, you should try the smallest and simplest
+            image:
+            <literallayout class='monospaced'>
+     $ bitbake core-image-minimal
+            </literallayout>
+            Now you just wait for the build to finish.
+        </para>
+
+        <para>
+            Here are some variations on the build process that could be helpful:
+            <itemizedlist>
+                <listitem><para>Fetch all the necessary sources without starting the build:
+                    <literallayout class='monospaced'>
+     $ bitbake -c fetchall core-image-minimal
+                    </literallayout>
+                    This variation guarantees that you have all the sources for that BitBake target
+                    should you disconnect from the net and want to do the build later offline.
+                    </para></listitem>
+                <listitem><para>Specify to continue the build even if BitBake encounters an error.
+                    By default, BitBake aborts the build when it encounters an error.
+                    This command keeps a faulty build going:
+                    <literallayout class='monospaced'>
+     $ bitbake -k core-image-minimal
+                    </literallayout></para></listitem>
+            </itemizedlist>
+        </para>
+
+        <para>
+            Once you have your image, you can take steps to load and boot it on the target hardware.
+        </para>
+    </section>
+</section>
+
+</article>
+<!--
+vim: expandtab tw=80 ts=4
+-->