summaryrefslogtreecommitdiff
path: root/docs/usermanual/reference
diff options
context:
space:
mode:
authorMichael 'Mickey' Lauer <mickey@vanille-media.de>2009-02-25 01:47:30 +0100
committerMichael 'Mickey' Lauer <mickey@vanille-media.de>2009-02-25 01:47:30 +0100
commit25b51d32c982a6767f3d4a88dec12f70c8c8f875 (patch)
tree206e94d12d2fda511c5b383adfec3684829703a1 /docs/usermanual/reference
parent6d76191b2021518d2f1ea00c20a1ec3151d93069 (diff)
docs: import usermanual from org.openembedded.documentation.
org.openembedded.documentation is deprecated now; please do all updates here!
Diffstat (limited to 'docs/usermanual/reference')
-rw-r--r--docs/usermanual/reference/.mtn2git_empty0
-rw-r--r--docs/usermanual/reference/class_autotools.xml153
-rw-r--r--docs/usermanual/reference/class_binconfig.xml46
-rw-r--r--docs/usermanual/reference/class_distutils.xml48
-rw-r--r--docs/usermanual/reference/class_image.xml358
-rw-r--r--docs/usermanual/reference/class_pkgconfig.xml39
-rw-r--r--docs/usermanual/reference/class_rootfs_ipkg.xml215
-rw-r--r--docs/usermanual/reference/class_siteinfo.xml180
-rw-r--r--docs/usermanual/reference/class_update-alternatives.xml241
-rw-r--r--docs/usermanual/reference/class_update-rc.d.xml133
-rw-r--r--docs/usermanual/reference/dirs_install.xml198
-rw-r--r--docs/usermanual/reference/dirs_staging.xml169
-rw-r--r--docs/usermanual/reference/fakeroot.xml186
-rw-r--r--docs/usermanual/reference/image_types.xml385
-rw-r--r--docs/usermanual/reference/var_section.xml704
-rw-r--r--docs/usermanual/reference/var_src_uri.xml692
16 files changed, 3747 insertions, 0 deletions
diff --git a/docs/usermanual/reference/.mtn2git_empty b/docs/usermanual/reference/.mtn2git_empty
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/docs/usermanual/reference/.mtn2git_empty
diff --git a/docs/usermanual/reference/class_autotools.xml b/docs/usermanual/reference/class_autotools.xml
new file mode 100644
index 0000000000..a9e1a5721a
--- /dev/null
+++ b/docs/usermanual/reference/class_autotools.xml
@@ -0,0 +1,153 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="autotools_class" xreflabel="autotools class">
+ <title>autotools class</title>
+
+ <para>Autotools is one of the most commonly seen configuration methods for
+ applications. Anything that uses the standard <command>./configure; make;
+ make install</command> sequence is using autotools. Usually the configure
+ script will support a large number of options to specify various
+ installation directories, to disable and/or enable various features and
+ options to specify search paths for headers and libraries.</para>
+
+ <para>The autotools class takes care of all of the details for you. It
+ defines appropriate tasks for <emphasis>configure</emphasis>,
+ <emphasis>compile</emphasis>, <emphasis>stage</emphasis> and
+ <emphasis>install</emphasis>. At it's simplest adding an inherit for the
+ autotools class is all that is required. The netcat recipe for example
+ is:<screen>DESCRIPTION = "GNU Netcat"
+HOMEPAGE = "http://netcat.sourceforge.net"
+LICENSE = "GPLv2"
+MAINTAINER = "Your name &lt;yname@example.com&gt;"
+SECTION = "console/networking"
+PR = "r1"
+
+SRC_URI = "${SOURCEFORGE_MIRROR}/netcat/netcat-${PV}.tar.bz2"
+
+inherit autotools</screen>The header is defined, the location of the source
+ code and then the inherit. For the simplest cases this is all that is
+ required. If you need to pass additional parameters to the configure script,
+ such as for enabling and/or disabling options, then they can be specified
+ via the <command>EXTRA_OECONF</command> variable. This example from the lftp
+ recipe shows several extra options being passed to the configure
+ script:<screen>EXTRA_OECONF = "--disable-largefile --disable-rpath --with-included-readline=no"</screen>If
+ you define your own tasks for <emphasis>configure</emphasis>,
+ <emphasis>compile</emphasis>, <emphasis>stage</emphasis> or
+ <emphasis>install</emphasis> (via <command>do_&lt;taskname&gt;</command>)
+ then they will override the methods generated by the autotools class. If you
+ need to perform additional operations (rather than replacing the generated
+ operations) you can use the <command>do_&lt;task&gt;_append</command> or
+ <command>do_&lt;task&gt;_prepend</command> methods. The following example
+ from the conserver recipe shows some additional items being
+ installed:<screen># Include the init script and default settings in the package
+do_install_append () {
+ install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d
+ install -m 0644 ${WORKDIR}/conserver.default ${D}${sysconfdir}/default/conserver
+ install -m 0755 ${WORKDIR}/conserver.init ${D}${sysconfdir}/init.d/conserver
+}</screen></para>
+
+ <section>
+ <title>oe_runconf / autotools_do_configure</title>
+
+ <para>Autotools generates a configuration method called
+ <command>oe_runconf</command> which runs the actual configure script, and
+ a method called <command>autotools_do_configure</command> which generates
+ the configure file (runs automake and autoconf) and then calls
+ <command>oe_runconf</command>. The generated method for the
+ <emphasis>configure</emphasis> task, <command>do_configure</command>, just
+ calls the <command>autotools_do_configure</command> method.</para>
+
+ <para>It is sometimes desirable to implement your own
+ <command>do_configure</command> method, where additional configuration is
+ required or where you wish to inhibit the running of automake and
+ autoconf, and then manually call <command>oe_runconf</command>.</para>
+
+ <para>The following example from the ipacct recipe shows an example of
+ avoiding the use of automake/autoconf:<screen>do_configure() {
+ oe_runconf
+}</screen>Sometimes manual manipulations of the autotools files is required
+ prior to calling autoconf/automake. In this case you can defined your own
+ <command>do_configure</command> method which performs the required actions
+ and then calls <command>autotools_do_configure</command>.</para>
+ </section>
+
+ <section>
+ <title>Presetting autoconf variables (the site file)</title>
+
+ <para>The autotools configuration method has support for caching the
+ results of tests. In the cross-compilation case it is sometimes necessary
+ to prime the cache with per-calculated results (since tests designed to
+ run on the target cannot be run when cross-compiling). These are defined
+ via the site file(s) for the architecture you are using and may be
+ specific to the package you are building.</para>
+
+ <para>Autoconf uses site files as definied in the
+ <command>CONFIG_SITE</command> variable, which is a space seperate list of
+ files to load in the specified order. Details on how this variable is set
+ is provided in the <xref linkend="siteinfo_class" /> (the class
+ responsbile for setting the variable) section.</para>
+
+ <para>There are some things that you should keep in mind about the caching
+ of configure tests:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Check the other site files to see if there any entries for the
+ application you are attempting to build.</para>
+
+ <para>Sometimes entries are only updated for the target that the
+ developer has access to. If they exist for another target then it may
+ provide a good idea of what needs to be defined.</para>
+ </listitem>
+
+ <listitem>
+ <para>Sometimes the same cache value is used by multiple
+ applications.</para>
+
+ <para>This can have the side effect where a value added for one
+ application breaks the build of another. It is a very good idea to
+ empty the site file of all other values if you are having build
+ problems to ensure that none of the existing values are causing
+ problems.</para>
+ </listitem>
+
+ <listitem>
+ <para>Not all values can be stored in the cache</para>
+
+ <para>Caching of variables is defined by the author of the configure
+ script, so sometimes not all variables can be set via the cache. In
+ this case it often means resorting to patching the original configure
+ scripts to achieve the desired result.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>All site files are shell scripts which are run by autoconf and
+ therefore the syntax is the same as you would use in sh. There are two
+ current methods of settings variables that is used in the existing site
+ files. This include explicitly settings the value of the variable:<screen>ac_cv_sys_restartable_syscalls=yes</screen>and
+ conditionally setting the value of the variable:<screen>ac_cv_uchar=${ac_cv_uchar=no}</screen>The
+ conditional version is using shell syntax to say "<emphasis>only set this
+ to the specified value if it is not currently set</emphasis>". The
+ conditional version allows the variable to be set in the shell prior to
+ calling configure and it will then not be replaced by the value from the
+ site file.</para>
+
+ <note>
+ <para>Site files are applied in order, so the application specific site
+ files will be applied prior to the top level site file entries. The use
+ of conditional assignment means that the first definition found will
+ apply, while when not using conditionals the last definition found will
+ apply.</para>
+ </note>
+
+ <para>It is possible to disable the use of the cached values from the site
+ file by clearing the definition of <command>CONFIG_SITE</command> prior to
+ running the configure script. Doing this will disable the use of the site
+ file entirely. This however should be used as a last resort. The following
+ example from the db recipe shows an example of this:<screen># Cancel the site stuff - it's set for db3 and destroys the
+# configure.
+CONFIG_SITE = ""
+do_configure() {
+ oe_runconf
+}</screen></para>
+ </section>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_binconfig.xml b/docs/usermanual/reference/class_binconfig.xml
new file mode 100644
index 0000000000..049f85e1f0
--- /dev/null
+++ b/docs/usermanual/reference/class_binconfig.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="binconfig_class" xreflabel="binconfig class">
+ <title>binconfig class</title>
+
+ <para>The binconfig class is for packages that install
+ <command>&lt;pkg&gt;-config</command> scripts that provide information about
+ the build settings for the package. It is usually provided by libraries and
+ then used by other packages to determine various compiler options.</para>
+
+ <para>Since the script is used at build time it is required to be copied
+ into the staging area. All the actions performed by the class are appended
+ to the <emphasis>stage</emphasis> task.</para>
+
+ <para>The actions performed by the binconfig class are:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Copies the <command>&lt;x&gt;-config</command> script from the
+ package into <command>${STAGING_BINDIR} </command>directory;</para>
+ </listitem>
+
+ <listitem>
+ <para>If the package is not native then it modifies the contents of the
+ <command>&lt;x&gt;-config</command> script in the staging area to ensure
+ that all the paths in the script refer to the staging area;</para>
+ </listitem>
+
+ <listitem>
+ <para>If the package is native then
+ the<command>&lt;x&gt;-config</command> script is renamed to
+ <command>&lt;x&gt;-config-native</command> to ensure that the native and
+ non-native versions do not interfere with each other.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>A package is considered to be native if it also inherits the native
+ class.</para>
+
+ <para>The class will search in source directory, <command>${S}</command>,
+ and all it's subdirectories, for files that end in
+ <command>-config</command> and process them as described above. All that is
+ required to use the class is the addition of binconfig in an inherit
+ statement:</para>
+
+ <para><screen>inherit autotools binconfig</screen></para>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_distutils.xml b/docs/usermanual/reference/class_distutils.xml
new file mode 100644
index 0000000000..ddc9c721ab
--- /dev/null
+++ b/docs/usermanual/reference/class_distutils.xml
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="distutils_class" xreflabel="distutils class">
+ <title>distutils class</title>
+
+ <para>Distutils is a standard python system for building and installing
+ modules. The <emphasis>distutils</emphasis> class is used to automate the
+ building of python modules that use the distutils system.</para>
+
+ <para>Any python package that requires the standard python commands to build
+ and install is using the distutils system and should be able to use this
+ class:<screen>python setup.py build
+python setup.py install</screen></para>
+
+ <para>The <emphasis>distutils</emphasis> class will perform the build and
+ install actions on the <command>setup.py</command> provided by the package,
+ as required for building distutils packages, including setting all the
+ required parameters for cross compiling. It willl also perform the following
+ actions:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Adds python-native to <command>DEPENDS</command> to ensure that
+ python is built and installed on the build host. This also ensure that
+ the version of python that is used during package creation matches the
+ version of python that will be installed on the target.</para>
+ </listitem>
+
+ <listitem>
+ <para>Adds python-core to <command>RDEPENDS</command> to ensure that the
+ python-core is installed when this module is installed. Note that you
+ need to manually add any other python module dependencies to
+ <command>RDEPENDS</command>.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The following example from the <emphasis>moin</emphasis> recipe shows
+ how simple this can make a python package:<screen>DESCRIPTION = "A full fledged WikiWiki system written in Python"
+LICENSE = "GPL"
+SECTION = "base"
+PRIORITY = "optional"
+MAINTAINER = "Your name &lt;yname@example.com&gt;"
+PR = "r1"
+
+SRC_URI = "${SOURCEFORGE_MIRROR}/moin/moin-${PV}.tar.gz"
+
+inherit distutils</screen>The header, source location and the inherit are all
+ that is required.</para>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_image.xml b/docs/usermanual/reference/class_image.xml
new file mode 100644
index 0000000000..b591e9aae2
--- /dev/null
+++ b/docs/usermanual/reference/class_image.xml
@@ -0,0 +1,358 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="image_class" xreflabel="image class">
+ <title>image class</title>
+
+ <para>The image class is used to generate filesystem images containing a
+ root filesystem, as generated by the rootfs class for the package type, such
+ as <xref linkend="rootfs_ipkg_class" />, for use on the target device. This
+ could be a <emphasis>jffs2</emphasis> image which is to be written directly
+ into the flash on the target device for example. In addition this class also
+ configures the ipkg feeds (where to get updates from) and is able to
+ generate multiple different image types.</para>
+
+ <para>Summary of the actions performed by the
+ <emphasis>image_ipkg</emphasis> class:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Inherits the rootfs class for the appropriate package type,
+ typically <xref linkend="rootfs_ipkg_class" />, in order to bring in the
+ functionality required to generate a root filesystem image. The root
+ filesystem image is generate from a set of of packages (typically .ipkg
+ packages), and then the required images are generated using the contents
+ of the root filesystem;</para>
+ </listitem>
+
+ <listitem>
+ <para>Sets <command>BUILD_ALL_DEPS = "1"</command> to force the
+ dependency system to build all packages that are listed in the
+ <command>RDEPENDS</command> and/or <command>RRECOMENDS</command> of the
+ packages to be installed;</para>
+ </listitem>
+
+ <listitem>
+ <para>Determines the name of the image device tables or table
+ (<command>IMAGE_DEVICE_TABLES/IMAGE_DEVICE_TABLE</command>) which will
+ be used to describe the device nodes to create in
+ <command>/dev</command> directory in the root filesystem;</para>
+ </listitem>
+
+ <listitem>
+ <para>Erases the contents of any existing root filesystem image,
+ <command>${IMAGE_ROOTFS}</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>If devfs is not being used then the <command>/dev</command>
+ directory, <command>${IMAGE_ROOTFS}/dev</command>, will be created and
+ then populated with the device nodes described by the image device table
+ or tables (using "<command>makedevs -r ${IMAGE_ROOTFS} -D
+ &lt;table&gt;</command>" for each device table);</para>
+ </listitem>
+
+ <listitem>
+ <para>Calls into <xref linkend="rootfs_ipkg_class" /> to install all of
+ the required packages into the root filesystem;</para>
+ </listitem>
+
+ <listitem>
+ <para>Configures the ipkg feed information in the root filesystem
+ (using <command>FEED_URIS</command> and <command>FEED_DEPLOYDIR_BASE_URI</command>);</para>
+ </listitem>
+
+ <listitem>
+ <para>Runs any image pre-processing commands as specified via
+ <command>${IMAGE_PREPROCESS_COMMAND}</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Calls <command>bbimage</command> on the root filesystem for each
+ required image type, as specified via
+ <command>${IMAGE_FSTYPES}</command>, to generate the actual filesystem
+ images;</para>
+ </listitem>
+
+ <listitem>
+ <para>Runs any image post-processing commands, as specified via
+ <command>${IMAGE_POSTPROCESS_COMMAND}</command>.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The following variables may be used to control some of the behaviour
+ of this class (remember we use <xref linkend="rootfs_ipkg_class" /> to build
+ the filesystem image, so look at the variables defined by that class as
+ well):</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>USE_DEVFS</term>
+
+ <listitem>
+ <para>Indicates if the image will be using devfs, the device
+ filesystem, or not. If devfs is being used then no
+ <command>/dev</command> directory will be required in the image. Set
+ to <command>"1"</command> to indicate that devfs is being used. Note
+ that devfs has been removed from the Linux kernel in the 2.6 series
+ and most platforms are moving towards the use of udev as a replacement
+ for devfs.</para>
+
+ <para>Default: <command>"0"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_DEVICE_TABLES</term>
+
+ <listitem>
+ <para>Specifies one, or more, files containing a list of the device
+ nodes that should be created in the <command>/dev</command> directory
+ of the image. Each file is searched for via the
+ <command>${BBPATH}</command> and therefore can be specified as a file
+ relative to the top of the build. Device files are processed in the
+ specified order. NOTE: If <command>IMAGE_DEVICE_TABLE</command> is set
+ then this variable is ignored.</para>
+
+ <para>Example: <command>IMAGE_DEVICE_TABLES =
+ "files/device_table-minimal.txt files/device_table_add-sci.txt
+ device_table_add-sm.txt"</command></para>
+
+ <para>Default:
+ <command>"files/device_table-minimal.txt"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_DEVICE_TABLE</term>
+
+ <listitem>
+ <para>Specifies the file that lists the device nodes that should be
+ created in the <command>/dev </command>directory of the image. This
+ needs to be an absolute filename and so should be specified relative
+ to <command>${BBPATH}</command>. Only a single device table is
+ supported. Use <command>IMAGE_DEVICE_TABLES</command> instead if you
+ want to use multiple device tables.</para>
+
+ <para>Default: <command>""</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_PREPROCESS_COMMAND</term>
+
+ <listitem>
+ <para>Additional commands to run prior to processing the image. Note
+ that these command run within the same <xref linkend="fakeroot" />
+ instance as the rest of this class.</para>
+
+ <para>Default: <command>""</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_POSTPROCESS_COMMAND</term>
+
+ <listitem>
+ <para>Additional commands to run after processing the image. Note that
+ these command run within the same <xref linkend="fakeroot" /> instance
+ as the rest of this class.</para>
+
+ <para>Default: <command>""</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_FSTYPES</term>
+
+ <listitem>
+ <para>Specifies the type of image files to create. The supported image
+ types, and details on modifying existing types and on creating new
+ types, are described in the <xref linkend="image_types" /> section.
+ This variable is set to a space seperated list of image types to
+ generate.</para>
+
+ <para>Example: <command>"jffs2 tar.gz"</command></para>
+
+ <para>Default: <command>"jffs2"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FEED_URIS</term>
+
+ <listitem>
+ <para>The name of the feeds to be configured in the image by default.
+ Each entry consists of the feed name, followed by two pound signs and
+ then followed by the actual feed URI.</para>
+
+ <para>Example: <command>FEED_URIS =
+ "example##http://dist.example.com/ipkg-titan-glibc/"</command></para>
+
+ <para>Default: <command>""</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FEED_DEPLOYDIR_BASE_URI</term>
+
+ <listitem>
+ <para>If set, configures local testing feeds using OE package deploy dir
+ contents. The value is URL, corresponding to the ipk deploy dir.</para>
+
+ <para>Example: <command>FEED_DEPLOYDIR_BASE_URI =
+ "http://192.168.2.200/bogofeed/"</command></para>
+
+ <para>Default: <command>""</command></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <section>
+ <title>Special node handling (fakeroot)</title>
+
+ <para>Special nodes, such as <command>/dev</command> nodes, and files with
+ special permissions, such as suid files, are handled via the <xref
+ linkend="fakeroot" /> system. This means that when you view the contents
+ of the root filesystem these device appear to be created
+ incorrectly:</para>
+
+ <para>The <command>IMAGE_PREPROCESS_COMMAND</command> and
+ <command>IMAGE_POSTPROCESS_COMMAND</command> variables will be processed
+ within the same <xref linkend="fakeroot" /> instance as the rest of the
+ rest of this class.</para>
+ </section>
+
+ <section>
+ <title>Device (/dev) nodes</title>
+
+ <para>There are two variables that can be defined for creating device
+ nodes. The new method supports multiple device node tables and supports
+ searching for these tables via the <command>${BBPATH}</command> so that
+ relative file names may be used.</para>
+
+ <para>The following example from <command>machine/titan.conf</command>
+ shows the use of multiple device tables:</para>
+
+ <para><screen># Add the SCI devices to minimal /dev
+IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci.txt device_table_add-sm.txt"
+</screen></para>
+
+ <para>It uses the standard minimal device tables but adds some additional
+ items which are not normally needed:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>files/device_table-minimal.txt</term>
+
+ <listitem>
+ <para>This is the standard minimal set of device nodes.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>files/device_table_add-sci.txt</term>
+
+ <listitem>
+ <para>This contains details for creating the
+ <command>/dev/SC{0,1,2}</command> nodes which are required for the
+ SH processors on board SCI and SCIF serial ports. On the titan
+ hardware the serial console is provided via one of these ports and
+ so we require the device node to be present.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>device_table_add-sm.txt</term>
+
+ <listitem>
+ <para>This contains details for creating the
+ <command>/dev/sm0</command> and <command>/dev/sm0p{0,1,2}</command>
+ devices nodes for the block driver, and the associated partitions,
+ that are used to manage the on board flash on the titan
+ hardware.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Prior to support for multiple device tables this would have required
+ the creation of a titan specific device table.</para>
+ </section>
+
+ <section>
+ <title>Image types</title>
+
+ <para>The type of filesystem images to create are specified via the
+ <command>IMAGE_FSTYPES</command> variable. A full description of the
+ available image types, options of the images and details on creating new
+ image types is provided in the <xref linkend="image_types" />
+ section.</para>
+ </section>
+
+ <section>
+ <title>Package feeds</title>
+
+ <para>"Package feed", or feed for short, is a term used by <command>ipkg</command>
+ package manager, commonly used in embedded systems, to name a package repository
+ holding packages. Structurally, a feed is a directory - local, or on HTTP of FTP server, -
+ holding packages and package descriptor file, named <command>Packages</command> or
+ <command>Packages.gz</command> if compressed. Multiple feeds are supported.</para>
+
+ <para>OpenEmbedded has support to pre-configure feeds within generated images,
+ so once image is installed on a device, user can immediately install new software,
+ without the need to manually edit config files. There are several ways to pre-configure
+ feed support, described below.</para>
+
+ <section>
+ <title>Method 1: Using existing feed</title>
+ <para>If you already have the feed(s) set up and available via specific URL, they
+ can be added to the image using FEED_URIS variable:
+<screen>FEED_URIS = " \
+ base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \
+ updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen>
+
+ FEED_URIS contains list of feed descriptors, separated by spaces, per
+ OE conventions. Each descriptor consists of feed name and feed URL,
+ joined with "##". Feed name is an identifier used by ipkg to distinguish
+ among the feeds. It can be arbitrary, just useful to the users to understood
+ which feed is used for one or another action.</para>
+ </section>
+
+ <section>
+ <title>Method 2: Using OE deploy directory as a feed (development only)</title>
+ <para>OE internally maintains a feed-like collection of directories to create
+ images from packages. This package deployment directory however has structure internal to OE
+ and subject to change without notice. Thus, using it as feed directly is not recommended
+ (distributions which ignored this recommendation are known to have their feeds broken when
+ OE upgraded its internal mechanisms).</para>
+ <para>However, using deploy directory as feed directly may be beneficial during
+ development and testing, as it allows developers to easily install newly built packages
+ without many manual actions. To facilitate this, OE offers a way to prepare feed configs
+ for using deploy dir as such. To start with this, you first need to configure local
+ HTTP server to export a package deployment directory via HTTP.
+ Suppose you will export it via URL "http://192.168.2.200/bogofeed" (where 192.168.2.200 is the address
+ which will be reachable from the device). Add the following to your local.conf:
+<screen>
+FEED_DEPLOYDIR_BASE_URI = "http://192.168.2.200/bogofeed"
+</screen>
+ Now you need to setup local HTTP server to actually export that directory. For Apache it can be:
+<screen>
+<![CDATA[
+Alias /bogofeed ${DEPLOY_DIR}
+
+<Directory ${DEPLOY_DIR}>
+ Options Indexes FollowSymLinks
+ Order deny,allow
+ Allow from 192.168.2.0/24
+</Directory>
+]]>
+</screen>
+ Replace ${DEPLOY_DIR} with the full path of deploy directory (last components of its path will be
+ <command>deploy/ipk</command>).</para>
+ <para>Now, every image built will automatically contain feed configs
+ for the deploy directory (as of time of writing, deploy directory is internally structured with
+ per-arch subdirectories; so, there several feed configs are being generated, one for each subdirectory).
+ </para>
+
+ </section>
+
+ </section>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_pkgconfig.xml b/docs/usermanual/reference/class_pkgconfig.xml
new file mode 100644
index 0000000000..3cb5002df5
--- /dev/null
+++ b/docs/usermanual/reference/class_pkgconfig.xml
@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="pkgconfig_class" xreflabel="pkgconfig class">
+ <title>pkgconfig class</title>
+
+ <para>The pkgconfig class is for packages that install
+ <command>&lt;pkg&gt;.pc</command> files. These files provide information
+ about the build settings for the package vwhich are then made available by
+ the <command>pkg-config</command> command.</para>
+
+ <para>Since the contents of the <command>.pc</command> files are used at
+ build time they need to be installed into the staging area. All the actions
+ performed by this class are appended to the <emphasis>stage</emphasis>
+ task.</para>
+
+ <para>The actions performed by the pkgconfig class are:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Copies the <command>&lt;x&gt;.pc</command> files into the
+ <command>${PKG_CONFIG_PATH}</command> directory;</para>
+ </listitem>
+
+ <listitem>
+ <para>If the package is not native then it modifies the contents of the
+ <command>&lt;x&gt;.pc</command> file in the
+ <command>${PKG_CONFIG_PATH}</command> area to ensure that all the paths
+ in the script refer to the staging area;</para>
+ </listitem>
+ </orderedlist>
+
+ <para>A package is considered to be native if it also inherits the native
+ class.</para>
+
+ <para>The class will search the source directory, <command>${S}</command>,
+ and all it's subdirectories, for files that end in <command>.pc</command>
+ (it will ignore those that end in <command>-uninstalled.pc)</command> and
+ process them as described above. All that is required to use the class is
+ the addition of pkgconfig in an inherit statement:<screen>inherit autotools pkgconfig</screen></para>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_rootfs_ipkg.xml b/docs/usermanual/reference/class_rootfs_ipkg.xml
new file mode 100644
index 0000000000..b60adf8e70
--- /dev/null
+++ b/docs/usermanual/reference/class_rootfs_ipkg.xml
@@ -0,0 +1,215 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="rootfs_ipkg_class" xreflabel="rootfs_ipkg class">
+ <title>rootfs_ipkg class</title>
+
+ <para>The <emphasis>rootf_ipk</emphasis> class us used to create a root
+ filesystem for the target device from a set of .ipkg packages. The end
+ result is a directory containing all the files that need to be included in
+ the root filesystem of the target device.</para>
+
+ <para>This class is normally not used directly, but instead used from the
+ <xref linkend="image_class" /> which creates images from a set of package
+ (typically <command>.ipkg</command>) files.</para>
+
+ <para>Summary of actions performed by the <emphasis>rootfs_ipkg</emphasis>
+ class:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Erase any existing root filesystem image by deleting the entire
+ contents of <command>${IMAGE_ROOTFS}</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Creates the device node directory,
+ <command>${IMAGE_ROOTFS}/dev</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Determines which packages to install in order to provide the
+ locales that have been requested;</para>
+ </listitem>
+
+ <listitem>
+ <para>Configures ipkg to allow it to be used locally to install into the
+ root filesystem <command>${IMAGE_ROOTFS}</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Installs locale related .ipkg packages;</para>
+ </listitem>
+
+ <listitem>
+ <para>Installs the list of requested <command>.ipkg</command> packages,
+ <command>${IPKG_INSTALL}</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Creates ipkg's arch.conf as
+ <command>${IMAGE_ROOTFS}/etc/ipkg/arch.conf</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Runs any preinst and postinst scripts that were specified by the
+ installed .ipkg packages;</para>
+ </listitem>
+
+ <listitem>
+ <para>Creates the system configuration directory
+ <command>${IMAGE_ROOTFS}/${sysconfdir}</command> (that is the
+ <command>/etc</command> directory on the target);</para>
+ </listitem>
+
+ <listitem>
+ <para>Runs and custom post-processing commands, as described by
+ <command>${ROOTFS_POSTPROCESS_COMMAND}</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Verifies that all the ipkg's were installed correctly and reports
+ an error if they were not;</para>
+ </listitem>
+
+ <listitem>
+ <para>Makes available a set of functions which may be used by callers of
+ the class: <command>zap_root_password</command>,
+ <command>create_etc_timestamp</command> and
+ <command>remove_init_link</command>;</para>
+ </listitem>
+
+ <listitem>
+ <para>Adds the rootfs task to run after the <emphasis>install</emphasis>
+ task <command>"addtask rootfs before do_build and
+ do_install"</command>.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The following variables may be used to control some of the behaviour
+ of this class:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>IPKG_INSTALL</term>
+
+ <listitem>
+ <para>The list of packages which will be installed into the root
+ filesystem. This needs to be set in order for this class to perform
+ any useful work.</para>
+
+ <para>Default: empty</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ROOTFS_POSTPROCESS_COMMAND</term>
+
+ <listitem>
+ <para>Defines additional commands to run after processing of the root
+ filesystem. Could be used to change roots password, remove parts of
+ the install kernel such as the <command>zImage</command> kernel image
+ or to edit the ipkg configuration for example.</para>
+
+ <para>Default: empty</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>PACKAGE_ARCH</term>
+
+ <listitem>
+ <para>Defines the list of architectures that are support by the target
+ platform. This is used to configure the arch settings for ipkg on the
+ target system.</para>
+
+ <para>Default: <command>"all any noarch ${TARGET_ARCH}
+ ${PACKAGE_EXTRA_ARCHS} ${MACHINE}"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_LINGUAS</term>
+
+ <listitem>
+ <para>Specifies which locales should be installed. This is often set
+ to <command>""</command> to indicate that no locales will be
+ installed.</para>
+
+ <para>Default: <command>"de-de fr-fr en-gb"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>EXTRA_IMAGEDEPENDS</term>
+
+ <listitem>
+ <para>A list of dependencies, this is appended to
+ <command>DEPENDS</command>. This is typically used to ensure that any
+ commands that are called by
+ <command>ROOTFS_POSTPROCESS_COMMAND</command> are actually built by
+ the system prior to being called.</para>
+
+ <para>Default: empty</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>BUILDNAME</term>
+
+ <listitem>
+ <para>The name of the build. This is either set by the distro
+ configuration (for released versions) or set to a date stamp which is
+ autogenerated by bitbake.</para>
+
+ <para>Default: <command>'date +%Y%m%d%H%M'</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_ROOTFS</term>
+
+ <listitem>
+ <para>The path to the root of the filesystem image. You can use this
+ when you need to explicitly refer to the root filesystem
+ directory.</para>
+
+ <para>Default: <command>IMAGE_ROOTFS =
+ "${TMPDIR}/rootfs"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DEPLOY_DIR</term>
+
+ <listitem>
+ <para>The base deploy dir. Used to find the directory containing the
+ ipkg files.</para>
+
+ <para>Default: <command>DEPLOY_DIR =
+ "${TMPDIR}/deploy"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DEPLOY_DIR_IPK</term>
+
+ <listitem>
+ <para>The directory in which to search for the ipkg files that are to
+ be installed in the root filesystem.</para>
+
+ <para>Default: <command>DEPLOY_DIR_IPK =
+ "${DEPLOY_DIR}/ipk"</command></para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Note that the entire process is run under the control of <xref
+ linkend="fakeroot" /> in order to handle device files, uids and gids. The
+ <command>ROOTFS_POSTPROCESS_COMMAND</command> is useful due to the fact that
+ it runs within the same <xref linkend="fakeroot" /> instance as the rest of
+ this class.</para>
+
+ <para>The class also provides a function <command>real_do_rootfs</command>
+ which is executed without <xref linkend="fakeroot" /> and therefore can be
+ used from other classes, such as <xref linkend="image_class" />, that
+ are already running under the control of <xref linkend="fakeroot" />.</para>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_siteinfo.xml b/docs/usermanual/reference/class_siteinfo.xml
new file mode 100644
index 0000000000..4d66e85e7c
--- /dev/null
+++ b/docs/usermanual/reference/class_siteinfo.xml
@@ -0,0 +1,180 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="siteinfo_class" xreflabel="siteinfo class">
+ <title>siteinfo class</title>
+
+ <para>The siteinfo class provides information for a target with a particular
+ emphasis on determining the names of the site files to be passed to
+ autoconf, as described in the <xref linkend="autotools_class" />. Full site
+ information for your target can be determined by looking at the table in the
+ class implementation found in the
+ <command>classes/siteinfo.bbclass</command> file. A typical entry contains
+ the name of the target and a list of site information for the
+ target:<screen> "sh4-linux": "endian-little bit-32 common-glibc sh-common",</screen>In
+ the above example for sh4-linux target (that's a build for an sh4 processor
+ using glibc) we see that the endianess and bit-size of target are defined
+ and an additional set of site files that should be used are listed. These
+ include a common site file for glibc and a common site file for sh
+ processors (so sh3 and sh4 can share defines). A <command>"common"</command>
+ entry is automatically added to the end of each of the definitions during
+ processing.</para>
+
+ <para>The class makes available three variables based on the information
+ provided for a target:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>SITEINFO_ENDIANESS</term>
+
+ <listitem>
+ <para>Defines the endianess of the target as either
+ <command>"le"</command> (little endian) or <command>"be"</command>
+ (big endian). The target must list either
+ <command>endian-little</command> or <command>endian-big</command> in
+ it's site information.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SITEINFO_BITS</term>
+
+ <listitem>
+ <para>Defines the bitsize of the target as either
+ <command>"32"</command> or <command>"64"</command>. The target must
+ list either <command>bit-32</command> or <command>bit-64</command> in
+ it's site information.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>CONFIG_SITE</term>
+
+ <listitem>
+ <para>Defines the site files to be used by autoconf. This is a space
+ separated list of one or more site files for the target.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>A typical use for the <command>SITEINFO_ENDIANESS</command> and
+ <command>SITEINFO_BITS</command> variables is to provide configuration
+ within a recipe based on their values. The following example from the
+ <emphasis>openssl</emphasis> recipe showw the correct define for the
+ endiness of the target being passed to openssl via the compiler flags. The
+ define to add to the flags is set based on the value of the
+ <command>SITEINFO_ENDIANESS</command> variable. Note that use of the
+ <emphasis>base_conditional</emphasis> method (see the <xref
+ linkend="recipes_advanced_python" /> section) to select a value conditional
+ on the endianess setting:</para>
+
+ <para><screen> # Additional flag based on target endiness (see siteinfo.bbclass)
+ CFLAG="${CFLAG} ${@base_conditional('SITEINFO_ENDIANESS', 'le', '-DL_ENDIAN', '-DB_ENDIAN', d)}"</screen></para>
+
+ <section>
+ <title>CONFIG_SITE: The autoconf site files</title>
+
+ <para>The autotools configuration method has support for caching the
+ results of tests. In the cross-compilation case it is sometimes necessary
+ to prime the cache with per-calculated results (since tests designed to
+ run on the target cannot be run when cross-compiling). These are defined
+ via the site file(s) for the architecture you are using and may be
+ specific to the package you are building.</para>
+
+ <para>Which site files are used is determined via the
+ <command>CONFIG_SITE</command> definition which is calculated via the
+ siteinfo class. Typically the following site files will be checked for,
+ and used in the order found:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>endian-(big|little)</term>
+
+ <listitem>
+ <para>Either <command>endian-big</command> or
+ <command>endian-little</command> depending on the endianess of the
+ target. This site file would contain defines that only change based
+ on if the target is little endian or big endian.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>bit-(32|64)</term>
+
+ <listitem>
+ <para>Either <command>bit-32</command> or <command>bit-64</command>
+ depending on the bitsize of the target. This site file would contain
+ defines that only change based on if the target is a 32-bit or
+ 64-bit cpu.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>common-(libc|uclibc)</term>
+
+ <listitem>
+ <para>Either <command>common-libc</command> or
+ <command>common-uclibc</command> based on the C library being used
+ for the target. This site file would contain defines the are
+ specific to the C library being used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>&lt;arch&gt;-common</term>
+
+ <listitem>
+ <para>A common site file for the target architecture. For i386,
+ i485, i586 and i686 this would be <command>x86-common</command>, for
+ sh3 and sh4 this would be <command>sh-common</command> and for
+ various arm targets this would be
+ <command>arm-common</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>common</term>
+
+ <listitem>
+ <para>This is a site file which is common for all targets and
+ contains definitions which remain the same no matter what target is
+ being built.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Each of the supported site files for a target is will be checked for
+ in several different directories. Each time a file is found it as added to
+ the list of files in the <command>CONFIG_SITE</command> variable. The
+ following directories are checked:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>org.openembedded.dev/packages/&lt;packagename&gt;/site-&lt;version&gt;/</term>
+
+ <listitem>
+ <para>This directory is for site files which are specific to a
+ particular version (where version is the PV of the package) of a
+ package.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>org.openembedded.dev/packages/&lt;packagename&gt;/site/</term>
+
+ <listitem>
+ <para>This directory is for site files which are specific to a
+ particular package, but apply to all versions of the package.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>org.openembedded.dev/site/</term>
+
+ <listitem>
+ <para>This directory is for site files that are common to all
+ packages. Originally this was the only site file directory that was
+ supported.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_update-alternatives.xml b/docs/usermanual/reference/class_update-alternatives.xml
new file mode 100644
index 0000000000..cd86e3e6ab
--- /dev/null
+++ b/docs/usermanual/reference/class_update-alternatives.xml
@@ -0,0 +1,241 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="update-alternatives_class" xreflabel="update-alternatives class">
+ <title>update-alternatives class</title>
+
+ <para>Some commands are available from multiple sources. As an example we
+ have <command>/bin/sh</command> available from <emphasis>busybox</emphasis>
+ and from <emphasis>bash</emphasis>. The busybox version is better from a
+ size perspective, but limited in functionality, while the bash version is
+ much larger but also provides far more features. The alternatives system is
+ designed to handle the situation where two commands are provided by two, or
+ more, packages. It ensures that one of the alternatives is always the
+ currently selected one and ensures that there are no problems with
+ installing and/or removing the various alternatives.</para>
+
+ <para>The update-alternatives class is used to register a command provided
+ by a package that may have an alternative implementation in a some other
+ package.</para>
+
+ <para>In the following sections we'll use the <command>/bin/ping</command>
+ command as an example. This command is available as a basic version from
+ busybox and as a more advanced version from iputils.</para>
+
+ <section>
+ <title>Naming of the alternative commands</title>
+
+ <para>When supplying alternative commands the target command itself is not
+ installed directly by any of the available alternatives. This is to ensure
+ that no package will replace files that were installed by one of the other
+ available alternative packages. The alternatives system will create a
+ symlink for the target command that points to the required
+ alternative.</para>
+
+ <para>For the <command>/bin/ping</command> case this means that neither
+ busybox nor iputils should actually install a command called
+ <command>/bin/ping</command>. Instead we see that the iputils recipe
+ installs it's version of ping as
+ <command>/bin/ping.iputils</command>:<screen>do_install () {
+ install -m 0755 -d ${D}${base_bindir} ${D}${bindir} ${D}${mandir}/man8
+ # SUID root programs
+ install -m 4755 ping ${D}${base_bindir}/ping.${PN}
+ ...
+}</screen></para>
+
+ <para>If you were to look at the busybox recipe you would see that it also
+ doesn't install a command called <command>/bin/ping</command>, instead it
+ installs it's command as <command>/bin/busybox</command>.</para>
+
+ <para>The important point to note is that neither package is installing an
+ actual <command>/bin/ping</command> target command.</para>
+ </section>
+
+ <section>
+ <title>How alternatives work</title>
+
+ <para>Before proceeding lets take a look at how alternatives are handled.
+ If we have a base image that includes only busybox then look at
+ <command>/bin/ping</command> we see that it is a symlink to
+ busybox:</para>
+
+ <para><screen>root@titan:/etc# ls -l /bin/ping
+lrwxrwxrwx 1 root root 7 May 3 2006 /bin/ping -&gt; busybox</screen></para>
+
+ <para>This is what is expected since the busybox version of ping is the
+ only one installed on the system. Note again that it is only a symlink and
+ not an actual command.</para>
+
+ <para>If the iputils version of ping is now installed and we look at the
+ <command>/bin/ping</command> command again we see that it has been changed
+ to a symlink pointing at the iputils version of ping -
+ <command>/bin/ping.iptils</command>:</para>
+
+ <para><screen>root@titan:/etc# ipkg install iputils-ping
+Installing iputils-ping (20020927-r2) to root...
+Downloading http://nynaeve/ipkg-titan-glibc//iputils-ping_20020927-r2_sh4.ipk
+Configuring iputils-ping
+update-alternatives: Linking //bin/ping to ping.iputils
+root@titan:/etc# ls -l /bin/ping
+lrwxrwxrwx 1 root root 12 May 13 2006 /bin/ping -&gt; ping.iputils</screen></para>
+
+ <para>The iputils version is considered to be the more fully featured
+ version of ping and is therefore the default when both versions are
+ installed.</para>
+
+ <para>What happens if the iputils-ping package is removed now? The symlink
+ should be changed to point back at the busybox version:</para>
+
+ <para><screen>root@titan:/etc# ipkg remove iputils-ping
+Removing package iputils-ping from root...
+update-alternatives: Linking //bin/ping to busybox
+root@titan:/etc# ls -l /bin/ping
+lrwxrwxrwx 1 root root 7 May 13 2006 /bin/ping -&gt; busybox</screen></para>
+
+ <para>This simple example shows that the alternatives system is taking
+ care of ensuring the symlink is pointing to the correct version of the
+ command without any special interaction from the end users.</para>
+ </section>
+
+ <section>
+ <title>The update-alternatives command</title>
+
+ <para>Available alternatives need to be registered with the alternatives
+ system. This is handled by the <command>update-alternatives</command>
+ command. The help from the command shows it's usage options:<screen>root@titan:/etc# update-alternatives --help
+update-alternatives: help:
+
+Usage: update-alternatives --install &lt;link&gt; &lt;name&gt; &lt;path&gt; &lt;priority&gt;
+ update-alternatives --remove &lt;name&gt; &lt;path&gt;
+ update-alternatives --help
+&lt;link&gt; is the link pointing to the provided path (ie. /usr/bin/foo).
+&lt;name&gt; is the name in /usr/lib/ipkg/alternatives/alternatives (ie. foo)
+&lt;path&gt; is the name referred to (ie. /usr/bin/foo-extra-spiffy)
+&lt;priority&gt; is an integer; options with higher numbers are chosen.
+</screen></para>
+
+ <para>During postinst the update-alternatives command needs to be called
+ with the install option and during postrm it needs to be called with the
+ remove option.</para>
+
+ <para>The iputils recipe actual codes this directly (rather than using the
+ class) so we can see an example of the command being called:<screen>pkg_postinst_${PN}-ping () {
+ update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100
+}
+pkg_prerm_${PN}-ping () {
+ update-alternatives --remove ping ping.${PN}
+}</screen></para>
+
+ <para>In both cases the name that the alternatives are registered against,
+ <command>"ping"</command>, is passed in and the path to the iputils
+ version of the command, <command>"ping.${PN}"</command>. For the install
+ case the actual command name (where the symlink will be made from) and a
+ priority value are also supplied.</para>
+ </section>
+
+ <section>
+ <title>Priority of the alternatives</title>
+
+ <para>So why did the alternatives system prefer the iputils version of
+ ping over the busybox version? It's because of the relative priorities of
+ the available alternatives. When iputils calls update-alternatives the
+ last parameter passed is a priority:<screen> update-alternatives --install ${base_bindir}/ping ping ping.${PN} 100</screen></para>
+
+ <para>So iputils is specifying a priority of 100 and if you look at
+ busybox you'll see it specifies a priority of 50 for ping. The alternative
+ with the highest priority value is the one that update-alternatives will
+ select as the version to actual use. In this particular situation the
+ authors have selected a higher priority for iputils since it is the more
+ capable version of ping and would not normally be installed unless
+ explicitly requested.</para>
+ </section>
+
+ <section>
+ <title>Tracking of the installed alternatives</title>
+
+ <para>You can actually see which alternatives are available and what their
+ priority is on a target system. Here we have an example in which both
+ busybox and iptuils-ping packages are installed: <screen>root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping
+/bin/ping
+busybox 50
+ping.iputils 100</screen>If we remove iputils-ping, then we see that
+ alternatives file is updated to reflect this: <screen>root@titan:/etc# cat /usr/lib/ipkg/alternatives/ping
+/bin/ping
+busybox 50
+root@titan:/etc#</screen></para>
+
+ <para>The file lists the command first, and then each of the available
+ alternatives and their relative priorities.</para>
+ </section>
+
+ <section>
+ <title>Using the update-alternatives class</title>
+
+ <para>Neither busybox nor iputils actually use the update-alternatives
+ class - they call the update-alternatives functions directly. They need to
+ call the command directly since they need to register multiple
+ alternatives and the class does not support this. The class can only be
+ used when you have only a single alternative to register.</para>
+
+ <para>To use the class you need to inherent update-alternatives and then
+ define the name, path, link and priority as show in the following example
+ from the jamvm recipe:</para>
+
+ <para><screen>inherit autotools update-alternatives
+
+ALTERNATIVE_NAME = "java"
+ALTERNATIVE_PATH = "${bindir}/jamvm"
+ALTERNATIVE_LINK = "${bindir}/java"
+ALTERNATIVE_PRIORITY = "10"
+</screen></para>
+
+ <para>where the variables to be specified are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>ALTERNATIVE_NAME [Required]</term>
+
+ <listitem>
+ <para>The name that the alternative is registered against and needs
+ to be the same for all alternatives registering this command.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ALTERNATIVE_PATH [Required]</term>
+
+ <listitem>
+ <para>The path of the installed alternative. (This was iputils.ping
+ in the example used previously).</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ALTERNATIVE_LINK [Optional]</term>
+
+ <listitem>
+ <para>The name of the actual command. This is what the symlink will
+ be called and is the actual command that the use runs. The default
+ value is: <command>"${bindir}/${ALTERNATIVE_NAME}"</command></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ALTERNATIVE_PRIORITY [Optional]</term>
+
+ <listitem>
+ <para>The priority of this alternative. The alternative with the
+ highest valued priority will be selected as the default. The default
+ value is: <command>"10"</command>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The actual postinst and postrm commands that are registered by the
+ class are:<screen>update_alternatives_postinst() {
+ update-alternatives --install ${ALTERNATIVE_LINK} ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH} ${ALTERNATIVE_PRIORITY}
+}
+
+update_alternatives_postrm() {
+ update-alternatives --remove ${ALTERNATIVE_NAME} ${ALTERNATIVE_PATH}
+}</screen></para>
+ </section>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/class_update-rc.d.xml b/docs/usermanual/reference/class_update-rc.d.xml
new file mode 100644
index 0000000000..2da9b0bf86
--- /dev/null
+++ b/docs/usermanual/reference/class_update-rc.d.xml
@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="update-rc-d_class" xreflabel="update-rc.d class">
+ <title>update-rc.d class</title>
+
+ <para>Services which need to be started during boot need to be registered
+ using the update-rc.d command. These services are required to have an init
+ script which is installed into <command>/etc/init.d</command> that can be
+ used to start and stop the service.</para>
+
+ <para>The following examples show a service being manually stopped and
+ started using it's init script:<screen>root@titan:/etc# /etc/init.d/syslog stop
+Stopping syslogd/klogd: stopped syslogd (pid 1551).
+stopped klogd (pid 1553).
+done
+root@titan:/etc# /etc/init.d/syslog start
+Starting syslogd/klogd: done
+root@titan:/etc#</screen>The update-rc.d class takes care of the following
+ automatically:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Registers the service with the system during postinst so it will
+ be automatically started on boot;</para>
+ </listitem>
+
+ <listitem>
+ <para>Stops the service during prerm so it will no longer be running
+ after being removed;</para>
+ </listitem>
+
+ <listitem>
+ <para>Unregisters the service during prerm so there will be no attempts
+ to start the removed service during boot;</para>
+ </listitem>
+
+ <listitem>
+ <para>Adds a build and run time dependency on the update-rc.d package
+ which it uses to register and unregister the services.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>Usage is very simple, as shown by this example from dropbear:<screen>INITSCRIPT_NAME = "dropbear"
+INITSCRIPT_PARAMS = "defaults 10"
+
+inherit autotools update-rc.d</screen></para>
+
+ <para>where the variables are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>INITSCRIPT_NAME</term>
+
+ <listitem>
+ <para>The name of the init script, which the package will have
+ installed into /etc/init.d</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>INITSCRIPT_PARAMS</term>
+
+ <listitem>
+ <para>The parameters to pass to the update-rc.d call during
+ installation. Typically this will be the work default followed by
+ either single number or a pair of numbers representing the start/stop
+ sequence number (both are set to the same if only one number is
+ supplied.)</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The help from update-rc.d shows show the required parameters:<screen>root@titan:/etc# update-rc.d -h
+usage: update-rc.d [-n] [-f] [-r &lt;root&gt;] &lt;basename&gt; remove
+ update-rc.d [-n] [-r &lt;root&gt;] [-s] &lt;basename&gt; defaults [NN | sNN kNN]
+ update-rc.d [-n] [-r &lt;root&gt;] [-s] &lt;basename&gt; start|stop NN runlvl [runlvl] [...] .
+ -n: not really
+ -f: force
+ -r: alternate root path (default is /)
+ -s: invoke start methods if appropriate to current runlevel
+root@titan:/etc#</screen>The start and stop sequence numbers need to ensure
+ that the the service is started at the appropriate time relative to other
+ services, such as waiting for any service that it depends on before starting
+ (networking for example). Unless the service is a system or security related
+ service it's better to be started as late as possible.</para>
+
+ <section>
+ <title>Multiple update-rc.d packages</title>
+
+ <para>Defining multiple init scripts within the one recipe is also
+ supported. Note that each init script must be in it's own package. The
+ following example is from the quagga recipe:<screen># Main init script starts all deamons
+# Seperate init script for watchquagga
+INITSCRIPT_PACKAGES = "${PN} ${PN}-watchquagga"
+INITSCRIPT_NAME_${PN} = "quagga"
+INITSCRIPT_PARAMS_${PN} = "defaults 15 85"
+INITSCRIPT_NAME_${PN}-watchquagga = "watchquagga"
+INITSCRIPT_PARAMS_${PN}-watchquagga = "defaults 90 10"
+
+inherit autotools update-rc.d</screen> The variables that need to be declared
+ are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>INITSCRIPT_PACKAGES</term>
+
+ <listitem>
+ <para>The names of each package which includes an init
+ script.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>INITSCRIPT_NAME_x</term>
+
+ <listitem>
+ <para>The same meaning as INITSCRIPT_NAME, but for the package x.
+ This would be repeated for each package that includes an init
+ script.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>INITSCRIPT_PARAMS_x</term>
+
+ <listitem>
+ <para>The same meaning as INITSCRIPT_PARAMS, but for the package x.
+ This would be repeated for each package that includes an init
+ script.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/dirs_install.xml b/docs/usermanual/reference/dirs_install.xml
new file mode 100644
index 0000000000..75f85ac930
--- /dev/null
+++ b/docs/usermanual/reference/dirs_install.xml
@@ -0,0 +1,198 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="directories_installation" xreflabel="Installation directories">
+ <title>Directories: Installation variables</title>
+
+ <para>The following table provides a list of the variables that are used to
+ control the directories into which files are installed.</para>
+
+ <para>These variables can be used directly by the recipe to refer to paths
+ that will be used after the package is installed. For example, when specify
+ the location of configuration files you need to specify the location on the
+ target as show in the following example from quagga:<screen># Indicate that the default files are configuration files
+CONFFILES_${PN} = "${sysconfdir}/default/quagga"
+CONFFILES_${PN}-watchquagga = "${sysconfdir}/default/watchquagga"</screen></para>
+
+ <para>When using these variables to actually install the components of a
+ package from within a bitbake recipe they should used relative to the
+ destination directory, <emphasis role="bold">D</emphasis>. The following
+ example from the quagga recipe shows some addition files being manually
+ installed from within the recipe itself:<screen>do_install () {
+ # Install init script and default settings
+ install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
+ install -m 0644 ${WORKDIR}/quagga.default ${D}${sysconfdir}/default/quagga</screen></para>
+
+ <informaltable>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Variable name</entry>
+
+ <entry>Definition</entry>
+
+ <entry>Typical value</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>prefix</entry>
+
+ <entry>/usr</entry>
+
+ <entry>/usr</entry>
+ </row>
+
+ <row>
+ <entry>base_prefix</entry>
+
+ <entry align="right"><emphasis>(empty)</emphasis></entry>
+
+ <entry align="right"><emphasis>(empty)</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>exec_prefix</entry>
+
+ <entry>${base_prefix}</entry>
+
+ <entry align="right"><emphasis>(empty)</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>base_bindir</entry>
+
+ <entry>${base_prefix}/bin</entry>
+
+ <entry>/bin</entry>
+ </row>
+
+ <row>
+ <entry>base_sbindir</entry>
+
+ <entry>${base_prefix}/sbin</entry>
+
+ <entry>/sbin</entry>
+ </row>
+
+ <row>
+ <entry>base_libdir</entry>
+
+ <entry>${base_prefix}/lib</entry>
+
+ <entry>/lib</entry>
+ </row>
+
+ <row>
+ <entry>datadir</entry>
+
+ <entry>${prefix}/share</entry>
+
+ <entry>/usr/share</entry>
+ </row>
+
+ <row>
+ <entry>sysconfdir</entry>
+
+ <entry>/etc</entry>
+
+ <entry>/etc</entry>
+ </row>
+
+ <row>
+ <entry>localstatedir</entry>
+
+ <entry>/var</entry>
+
+ <entry>/var</entry>
+ </row>
+
+ <row>
+ <entry>infodir</entry>
+
+ <entry>${datadir}/info</entry>
+
+ <entry>/usr/share/info</entry>
+ </row>
+
+ <row>
+ <entry>mandir</entry>
+
+ <entry>${datadir}/man</entry>
+
+ <entry>/usr/share/man</entry>
+ </row>
+
+ <row>
+ <entry>docdir</entry>
+
+ <entry>${datadir}/doc</entry>
+
+ <entry>/usr/share/doc</entry>
+ </row>
+
+ <row>
+ <entry>servicedir</entry>
+
+ <entry>/srv</entry>
+
+ <entry>/srv</entry>
+ </row>
+
+ <row>
+ <entry>bindir</entry>
+
+ <entry>${exec_prefix}/bin</entry>
+
+ <entry>/usr/bin</entry>
+ </row>
+
+ <row>
+ <entry>sbindir</entry>
+
+ <entry>${exec_prefix}/sbin</entry>
+
+ <entry>/usr/sbin</entry>
+ </row>
+
+ <row>
+ <entry>libexecdir</entry>
+
+ <entry>${exec_prefix}/libexec</entry>
+
+ <entry>/usr/libexec</entry>
+ </row>
+
+ <row>
+ <entry>libdir</entry>
+
+ <entry>${exec_prefix}/lib</entry>
+
+ <entry>/usr/lib</entry>
+ </row>
+
+ <row>
+ <entry>includedir</entry>
+
+ <entry>${exec_prefix}/include</entry>
+
+ <entry>/usr/include</entry>
+ </row>
+
+ <row>
+ <entry>palmtopdir</entry>
+ <entry>${libdir}/opie</entry>
+ <entry>/usr/lib/opie</entry>
+ </row>
+
+ <row>
+ <entry>palmqtdir</entry>
+ <entry>${palmtopdir}</entry>
+ <entry>/usr/lib/opie</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para></para>
+</section>
diff --git a/docs/usermanual/reference/dirs_staging.xml b/docs/usermanual/reference/dirs_staging.xml
new file mode 100644
index 0000000000..25f3685aad
--- /dev/null
+++ b/docs/usermanual/reference/dirs_staging.xml
@@ -0,0 +1,169 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="directories_staging" xreflabel="Staging directories">
+ <title>Directories: Staging variables</title>
+
+ <para>The following table provides a list of the variables that are used to
+ control the directories into which files are staged.</para>
+
+ <para>Staging is used for headers, libraries and binaries that are generated
+ by packages and are to be used in the generation of other packages. For
+ example the libpcre recipe needs to make the include files and libraries for
+ the target available on the host for other applications that depend on
+ libpcre. So in addition to packaging these files up for use in the binary
+ package they are need to be installed in the staging are for use by other
+ packages.</para>
+
+ <para>There are two common situations in which you will need to directly
+ refer to the staging directories:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>To specify where headers and libraries are to be found for
+ libraries that your package depends on. In some cases these will be
+ found automatically due to the default compiler settings used by OE, but
+ in other cases you will need to explicitly tell your package to look in
+ the staging area. This is more commonly needed with autoconf based
+ packages that check for the presence of a specific package during the
+ <emphasis>configure</emphasis> task.</para>
+ </listitem>
+
+ <listitem>
+ <para>In the <emphasis>stage</emphasis> task for libraries to specify
+ where to install the headers and libraries.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>The following example from libpcre shows the installation of the
+ libraries and headers from the package into the staging area. Note the use
+ of the <emphasis>oe_libinstall</emphasis> helper function for installation
+ of the libraries:<screen>do_stage () {
+ oe_libinstall -a -so libpcre ${STAGING_LIBDIR}
+ oe_libinstall -a -so libpcreposix ${STAGING_LIBDIR}
+ install -m 0644 pcre.h ${STAGING_INCDIR}/
+ install -m 0644 pcreposix.h ${STAGING_INCDIR}/
+}</screen></para>
+
+ <para>The following example from the flac recipe shows the location of the
+ ogg libraries and included before explicitly passed to the configured script
+ via EXTRA_OECONF so that it will correctly find ogg and enable support for
+ it:<screen>EXTRA_OECONF = "--disable-oggtest --disable-id3libtest \
+ --with-ogg-libraries=${STAGING_LIBDIR} \
+ --with-ogg-includes=${STAGING_INCDIR} \
+ --without-xmms-prefix \
+ --without-xmms-exec-prefix \
+ --without-libiconv-prefix \
+ --without-id3lib"</screen>The following table lists the available
+ variables for referring to the staging area:</para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="0" colwidth="1*" />
+
+ <colspec colnum="1" colwidth="1*" />
+
+ <thead>
+ <row>
+ <entry>Directory</entry>
+
+ <entry>Definition</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>STAGING_DIR</entry>
+
+ <entry>${TMPDIR}/staging</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_BINDIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/bin</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_BINDIR_CROSS</entry>
+
+ <entry>${STAGING_DIR}/${BUILD_SYS}/bin/${HOST_SYS}</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_BINDIR_NATIVE</entry>
+
+ <entry>${STAGING_DIR}/${BUILD_SYS}/bin</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_LIBDIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/lib</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_INCDIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/include</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_DATADIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/share</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_LOADER_DIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/loader</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_FIRMWARE_DIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/firmware</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_PYDIR</entry>
+
+ <entry>${STAGING_DIR}/lib/python2.4</entry>
+ </row>
+
+ <row>
+ <entry>STAGING_KERNEL_DIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/kernel</entry>
+ </row>
+
+ <row>
+ <entry>PKG_CONFIG_PATH</entry>
+
+ <entry>${STAGING_LIBDIR}/pkgconfig</entry>
+ </row>
+
+ <row>
+ <entry>QTDIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}/qt2</entry>
+ </row>
+
+ <row>
+ <entry>QPEDIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}</entry>
+ </row>
+
+ <row>
+ <entry>OPIEDIR</entry>
+
+ <entry>${STAGING_DIR}/${HOST_SYS}</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para></para>
+
+ <para></para>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/fakeroot.xml b/docs/usermanual/reference/fakeroot.xml
new file mode 100644
index 0000000000..5eb6a48eb0
--- /dev/null
+++ b/docs/usermanual/reference/fakeroot.xml
@@ -0,0 +1,186 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="fakeroot" xreflabel="fakeroot">
+ <title>fakeroot (device node handling)</title>
+
+ <para>The fakeroot program is designed to allow non-root users to perform
+ actions that would normally require root privileges as part of the package
+ generation process. It is used by the <xref linkend="rootfs_ipkg_class" />
+ for root filesystem creation and by the <xref linkend="image_class" />
+ for the creation of filesystem images. Some recipes also use fakeroot to
+ assist with parts of the package installation (usually) or building where
+ root privligeses are expected by the package.</para>
+
+ <para>In particular fakeroot deals with:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Device nodes; and</para>
+ </listitem>
+
+ <listitem>
+ <para>Ownership and group (uid &amp; gid) management.</para>
+ </listitem>
+ </itemizedlist>
+
+ <section>
+ <title>How fakeroot works</title>
+
+ <para>First of all we'll look at an example of how the fakeroot process
+ works when used manually.</para>
+
+ <para>If we attempt to create a device node as a normal non-root user then
+ the command will fail, telling is that we do not have permission to create
+ device nodes:<screen>~%&gt; mknod hdc b 22 0
+mknod: `hdc': Operation not permitted</screen>Yet the <xref
+ linkend="image_class" /> is able to create device nodes and include
+ them in the final images, all without the need to have root
+ privileges.</para>
+
+ <para>Let's try and create that node again, this time we'll run the
+ commands from within a fakeroot process:<screen>~%&gt; ./tmp/staging/x86_64-linux/bin/fakeroot
+~#&gt; mknod hdc b 22 0
+~#&gt; ls -l hdc
+brw------- 1 root root 22, 0 Aug 18 13:20 hdc
+~#&gt;</screen>So it looks like we have successfully managed to create a
+ device node, even though we did not have to give a password for the root
+ user. In reality this device node still doesn't exist, it just looks like
+ it exits. Fakeroot is lying to the shell process and telling it that
+ <emphasis>"yes, this file exists and these are it's
+ properties"</emphasis>. We'll talk more about how fakeroot actually works
+ in a minute.</para>
+
+ <para>In this case <command>hdc</command> is the cd-rom drive, so let's
+ try and actually mount the cd-rom:<screen>~#&gt; mkdir disk
+~#&gt; mount hdc disk
+ERROR: ld.so: object 'libfakeroot.so.0' from LD_PRELOAD cannot be preloaded: ignored.
+mount: only root can do that
+~#&gt;</screen>So even though it appears we have root permissions, and that we
+ created a device node, you see that the system gives an error about
+ libfakeroot and about not being able to run mount because we are not
+ root.</para>
+
+ <para>If we exit the fakeroot process and then look at the device node
+ this is what we see:<screen>~#&gt; exit
+~%&gt; ls -l hdc
+brw------- 1 user user 22, 0 Aug 18 13:20 hdc
+~#&gt;</screen></para>
+
+ <para>Note that it isn't a device node at all, just an empty file owned by
+ the current user!</para>
+
+ <para>So what exactly is fakeroot doing? It's using
+ <command>LD_PRELOAD</command> to load a shared library into program which
+ replaces calls into libc, such as open and stat, and then returns
+ information to make it look like certain commands succeeded without
+ actually performing those commands. So when creating a device node
+ fakeroot will:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Intercept the mknod system call and instead of creating a device
+ node it'll just create an empty file, owned by the user who run
+ fakeroot;</para>
+ </listitem>
+
+ <listitem>
+ <para>It remembers the fact that mknod was called by root and it
+ remembers the properties of the device node;</para>
+ </listitem>
+
+ <listitem>
+ <para>When a program, such as ls, calls stat on the file fakeroot
+ remembers that it was device node, owned by root, and modifies that
+ stat information to return this to ls. So ls sees a device node even
+ though one doesn't exist.</para>
+ </listitem>
+ </orderedlist>
+
+ <para>When we tried to run mount we received the error <command>"ERROR:
+ ld.so: object 'libfakeroot.so.0' from LD_PRELOAD cannot be preloaded:
+ ignored."</command>. This is due to the fact that mount is an suid root
+ binary, and for security reasons <command>LD_PRELOAD</command> is disabled
+ on suid binaries.</para>
+
+ <para>There are some very important points to remember when dealing with
+ fakeroot:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>All information regarding devices nodes, uid and gids will be
+ lost when fakeroot exists;</para>
+ </listitem>
+
+ <listitem>
+ <para>None of the device nodes, uids or gids will appear on disk.
+ However if you tar up a directory from within fakeroot (for example),
+ all of these device, uids and gids will appear correctly in the tar
+ archive;</para>
+ </listitem>
+
+ <listitem>
+ <para>Any suid binaries will not interact with fakeroot;</para>
+ </listitem>
+
+ <listitem>
+ <para>Any static binaries will not interact with fakeroot;</para>
+ </listitem>
+ </orderedlist>
+ </section>
+
+ <section>
+ <title>Root filesystem, images and fakeroot</title>
+
+ <para>Many people have been confused by the generated root filesystem not
+ containing any valid device nodes. This is in fact the expected
+ behaviour.</para>
+
+ <para>When you look at a generated root filesystem you'll notice that the
+ device nodes all appear to be incorrectly created:<screen>~%&gt; ls -l tmp/rootfs/dev | grep ttySC
+-rw-r--r-- 1 root root 0 Aug 16 13:07 ttySC0
+-rw-r--r-- 1 root root 0 Aug 16 13:07 ttySC1
+-rw-r--r-- 1 root root 0 Aug 16 13:07 ttySC2
+~%&gt;</screen>These are empty files and not device nodes at all.</para>
+
+ <para>If we look in the image files generated from that root filesystem
+ then everything is actually ok:<screen>~%&gt; tar -ztvf tmp/deploy/images/titan-titan-20060816030639.rootfs.tar.gz | grep " ./dev/ttySC"
+crw-r----- root/root 204,8 2006-08-16 13:07:12 ./dev/ttySC0
+crw-r----- root/root 204,9 2006-08-16 13:07:12 ./dev/ttySC1
+crw-r----- root/root 204,10 2006-08-16 13:07:12 ./dev/ttySC2
+~%&gt;</screen>The images are created from within the same fakeroot process as
+ the creation of the root filesystem and therefore it correctly picks up
+ all of the special files and permissions from fakeroot.</para>
+
+ <para><emphasis role="bold">NOTE: This means that you cannot use the root
+ filesystem in tmp/rootfs directly on your target device. You need to use
+ the .tar.gz image and uncompress it, as root, in order to generate a root
+ filesystem which is suitable for use directly on the target (or as an NFS
+ root).</emphasis></para>
+ </section>
+
+ <section>
+ <title>Recipes and fakeroot</title>
+
+ <para>Some applications require that you have root permissions to run
+ their installation routine, and this is another area where fakeroot can
+ help. In a recipe the method for a standard task, such as the
+ <command>do_install</command> method for the <emphasis>install</emphasis>
+ task:<screen>do_install() {
+ install -d ${D}${bindir} ${D}${sbindir} ${D}${mandir}/man8 \
+ ${D}${sysconfdir}/default \
+ ${D}${sysconfdir}/init.d \
+ ${D}${datadir}/arpwatch
+
+ oe_runmake install DESTDIR=${D}
+ oe_runmake install-man DESTDIR=${D}
+ ...</screen>can be modified to run within a fakeroot environment by
+ prefixing the method name with fakeroot:<screen><emphasis role="bold">fakeroot</emphasis> do_install() {
+ install -d ${D}${bindir} ${D}${sbindir} ${D}${mandir}/man8 \
+ ${D}${sysconfdir}/default \
+ ${D}${sysconfdir}/init.d \
+ ${D}${datadir}/arpwatch
+
+ oe_runmake install DESTDIR=${D}
+ oe_runmake install-man DESTDIR=${D}
+ ...</screen></para>
+ </section>
+</section> \ No newline at end of file
diff --git a/docs/usermanual/reference/image_types.xml b/docs/usermanual/reference/image_types.xml
new file mode 100644
index 0000000000..4ea174fd46
--- /dev/null
+++ b/docs/usermanual/reference/image_types.xml
@@ -0,0 +1,385 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="image_types" xreflabel="image types">
+ <title>Image types</title>
+
+ <para>One of the most commonly used outputs from a build is a filesystem
+ image containing the root filesystem for the target device. There are
+ several variables which can be used to control the type of output images and
+ the settings for those images, such as endianess or compression ratios. This
+ section details the available images and the variables that effect them. See
+ the <xref linkend="image_class" /> section for details on how image
+ generation is configured.</para>
+
+ <para>The final root file system will consist of all of the files located in
+ image root filesystem directory, <command>${IMAGE_ROOTFS}</command>, which
+ is usually <command>tmp/rootfs</command> in the build area. One important
+ difference between the images and the root file system directory is that any
+ files which can only be created by privileged users, such as device nodes,
+ will not appear in the <command>${IMAGE_ROOTFS}</command> directory but they
+ will be present in any images that are generated. This is due to
+ <emphasis><xref linkend="fakeroot" /> </emphasis>system keeping track of
+ these special files and making them available when generating the image -
+ even though they do not appear in the root filesystem directory. For this
+ reason it is important to always create an actual image to use for testing,
+ even if it's just a <command>.tar</command> archive, to ensure you have the
+ correct device nodes and any other special files.</para>
+
+ <section>
+ <title>Defining images</title>
+
+ <para>Each supported image type is defined via a set of variables. Each
+ variables has the name of the image type appended to indicate the settings
+ for that particular image type. The behaviour of the built in image types
+ can be changed by modifying these variables, and new types can be created
+ by defining these variables for the new type.</para>
+
+ <para>The variables that define an image type are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>IMAGE_CMD_&lt;type&gt;</term>
+
+ <listitem>
+ <para>Specifies the actual command that is run to generate an image
+ of the specified type.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>EXTRA_IMAGECMD_&lt;type&gt;</term>
+
+ <listitem>
+ <para>Used to pass additional command line arguments to the
+ <command>IMAGE_CMD</command> without the need to redefine the entire
+ image command. This is often used to pass options such as endianess
+ and compression rations. You need to look at the
+ <command>IMAGE_CMD</command> definition to determine how these
+ options are being used.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_ROOTFS_SIZE_&lt;type&gt;</term>
+
+ <listitem>
+ <para>For those image types that generate a fixed size image this
+ variable is used to specify the required image size.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>IMAGE_DEPENDS_&lt;type&gt;</term>
+
+ <listitem>
+ <para>Lists the packages that the <command>IMAGE_CMD</command>
+ depends on. As an example the jffs2 filesystem creation depends on
+ <command>mkfs.jffs2</command> command which is part of the mtd
+ utilities and therefore depends on mtd-utils-native.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Available image types</title>
+
+ <para>The following image types are built in to OpenEmbedded:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>jffs2</term>
+
+ <listitem>
+ <para>Creates jffs2 <emphasis>"Journaling flash file system
+ 2"</emphasis> images. This is a read/write, compressed filesystem
+ for mtd (flash) devices. It is not supported for block
+ devices.<screen>IMAGE_CMD_jffs2 = "mkfs.jffs2 \
+ -x lzo \
+ --root=${IMAGE_ROOTFS} \
+ --faketime \
+ --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
+ ${EXTRA_IMAGECMD}"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for jffs2
+ passed to <command>mkfs.jffs2</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_jffs2 = ""</screen></para>
+
+ <para>This was not always empty, prior to 2007/05/02 the
+ <command>EXTRA_IMAGECMD</command> variable for jffs2 was set to
+ enable padding, to define the endianess and to specify the block
+ size:<screen><emphasis>EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000"</emphasis></screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cramfs</term>
+
+ <listitem>
+ <para>Creates cramfs <emphasis>"Compression ROM file
+ system"</emphasis> images. This is a read only compressed filesystem
+ which is used directly by decompressing files into RAM as they are
+ accessed. Files sizes are limited to 16MB, file system size is
+ limited to 256MB, only 8-bit uids and gids are supported, no hard
+ links are supported and no time stamps are supported.<screen>IMAGE_CMD_cramfs = "mkcramfs ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cramfs \
+ ${EXTRA_IMAGECMD}"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for cramfs is
+ passed to <command>mkcramfs</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_cramfs = ""</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ext2</term>
+
+ <listitem>
+ <para>Creates an <emphasis>"Extended Filesystem 2"</emphasis> image
+ file. This is the standard Linux non-journaling file system.<screen>IMAGE_CMD_ext2 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \
+ -d ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2 \
+ ${EXTRA_IMAGECMD}"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for ext2 is
+ passed to <command>genext2fs</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_ext2 = ""</screen></para>
+
+ <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
+ specify the size of the ext2 image and is set to 64k by
+ default:<screen>IMAGE_ROOTFS_SIZE_ext2 = "65536"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ext3</term>
+
+ <listitem>
+ <para>Creates an <emphasis>"Extended Filesystem 3"</emphasis> image
+ file. This is the standard Linux journaling file system.<screen>IMAGE_CMD_ext3 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \
+ -d ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3 \
+ ${EXTRA_IMAGECMD}; \
+tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for ext3 is
+ passed to <command>genext2fs</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_ext3 = ""</screen></para>
+
+ <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
+ specify the size of the ext3 image and is set to 64k by
+ default:<screen>IMAGE_ROOTFS_SIZE_ext3 = "65536"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ext2.gz</term>
+
+ <listitem>
+ <para>Creates a version of the ext2 filesystem image compressed with
+ <command>gzip</command>.</para>
+
+ <para><screen>IMAGE_CMD_ext2.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz &amp;&amp; \
+mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \
+genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2 \
+ ${EXTRA_IMAGECMD}; \
+gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2; \
+mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2.gz \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2.gz; \
+rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for ext2.gz is
+ passed to <command>genext2fs</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_ext2.gz = ""</screen></para>
+
+ <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
+ specify the size of the ext2 image and is set to 64k by
+ default:</para>
+
+ <para><screen>IMAGE_ROOTFS_SIZE_ext2.gz = "65536"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>ext3.gz</term>
+
+ <listitem>
+ <para>Creates a version of the ext3 filesystem image compressed with
+ <command>gzip</command>.</para>
+
+ <para><screen>IMAGE_CMD_ext3.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz &amp;&amp; \
+mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \
+genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3 \
+ ${EXTRA_IMAGECMD}; \
+tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \
+gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \
+mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3.gz \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3.gz; \
+rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for ext3.gz is
+ passed to <command>genext2fs</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_ext3.gz = ""</screen></para>
+
+ <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
+ specify the size of the ext2 image and is set to 64k by
+ default:</para>
+
+ <para><screen>IMAGE_ROOTFS_SIZE_ext3.gz = "65536"</screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>squashfs</term>
+
+ <listitem>
+ <para>Creates a squashfs image. This is a read only compressed
+ filesystem which is used directly with files uncompressed into RAM
+ as they are accessed. Files and filesystems may be up to 2^64 bytes
+ in size, full 32-bit uids and gids are stored, it detects duplicate
+ files and stores only a single copy, all meta-data is compressed and
+ big and little endian filesystems can be mounted on any
+ platform.</para>
+
+ <para>Squashfs uses gzip as its compression method.</para>
+
+ <para><screen>IMAGE_CMD_squashfs = "mksquashfs ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \
+ ${EXTRA_IMAGECMD} -noappend"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is
+ passed to <command>mksquashfs</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_squashfs = ""</screen></para>
+
+ <para>This was not always empty, prior to 2007/05/02 the
+ <command>EXTRA_IMAGECMD</command> variable for squashfs specified
+ the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs = "-le -b 16384"</emphasis></screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>squashfs-lzma</term>
+
+ <listitem>
+ <para>Creates a squashfs image using lzma compression instead of
+ gzip which is the standard squashfs compression type. This is a read
+ only compressed filesystem which is used directly with files
+ uncompressed into RAM as they are accessed. Files and filesystems
+ may be up to 2^64 bytes in size, full 32-bit uids and gids are
+ stored, it detects duplicate files and stores only a single copy,
+ all meta-data is compressed and big and little endian filesystems
+ can be mounted on any platform.</para>
+
+ <para>Squashfs-lzma uses lzma as its compression method.</para>
+
+ <para><screen>IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \
+ ${EXTRA_IMAGECMD} -noappend"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is
+ passed to <command>mksquashfs-lzma</command> and is left empty by
+ default:<screen>EXTRA_IMAGECMD_squashfs-lzma = ""</screen></para>
+
+ <para>This was not always empty, prior to 2007/05/02 the
+ <command>EXTRA_IMAGECMD</command> variable for squashfs specified
+ the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384"</emphasis></screen></para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>tar</term>
+
+ <listitem>
+ <para>Creates a .tar archive.</para>
+
+ <para><screen>IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} &amp;&amp; \
+ tar -cvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar ."</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable in not
+ supported for tar images.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>tar.gz</term>
+
+ <listitem>
+ <para>Creates a <command>gzip</command> compressed .tar
+ archive.</para>
+
+ <para><screen>IMAGE_CMD_tar.gz = "cd ${IMAGE_ROOTFS} &amp;&amp; \
+ tar -zcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.gz ."</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable in not
+ supported for .tar.gz images.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>tar.bz2</term>
+
+ <listitem>
+ <para>Creates a <command>bzip2</command> compressed .tar
+ archive.</para>
+
+ <para><screen>IMAGE_CMD_tar.bz2 = "cd ${IMAGE_ROOTFS} &amp;&amp; \
+ tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ."</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable in not
+ supported for tar.bz2 images.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cpio</term>
+
+ <listitem>
+ <para>Creates a .cpio archive:<screen>IMAGE_CMD_cpio = "cd ${IMAGE_ROOTFS} &amp;&amp; \
+ (find . | cpio -o -H newc &gt;${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio)"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable in not
+ supported for cpio images.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cpio.gz</term>
+
+ <listitem>
+ <para>Creates a <command>gzip</command> compressed .cpio
+ archive.<screen>IMAGE_CMD_cpio.gz = cd ${IMAGE_ROOTFS} &amp;&amp; \
+ (find . | cpio -o -H newc | gzip -c -9 &gt;${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio.gz)"</screen></para>
+
+ <para>The <command>EXTRA_IMAGECMD</command> variable in not
+ supported for cpio.gz images.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The above built in list of image types is defined in the bitbake
+ configuration file:
+ <command>org.openembedded.dev/conf/bitbake.conf</command>.</para>
+ </section>
+
+ <section>
+ <title>Custom image types</title>
+
+ <para>Custom image types can be created by defining the
+ <command>IMAGE_CMD</command> variable, and optionally the
+ <command>EXTRA_IMAGECMD</command>, <command>IMAGE_ROOTFS_SIZE</command>
+ and <command>IMAGE_DEPENDS</command> variables, for your new image
+ type.</para>
+
+ <para>An example can be found in
+ <command>conf/machine/wrt54.conf</command> where it defines a new image
+ type, <emphasis>squashfs-lzma</emphasis>, for a squashfs filesystem using
+ lzma compression instead of the standard gzip compression (squashfs-lzma
+ is now a standard type, but the example still serves to show the
+ concept):<screen>IMAGE_DEPENDS_squashfs-lzma = "squashfs-tools-native"
+IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \
+ ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs-lzma \
+ ${EXTRA_IMAGECMD} -noappend"
+EXTRA_IMAGECMD_squashfs-lzma = "-root-owned -le"</screen></para>
+ </section>
+</section>
diff --git a/docs/usermanual/reference/var_section.xml b/docs/usermanual/reference/var_section.xml
new file mode 100644
index 0000000000..96b746e56c
--- /dev/null
+++ b/docs/usermanual/reference/var_section.xml
@@ -0,0 +1,704 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="section_variable" xreflabel="SECTION variable">
+ <title>SECTION variable: Package category</title>
+
+ <para>Sections are a means for categorising packages into related groups to
+ enable users to find packages easier. The <command>SECTION</command>
+ variable is used to declare which section a package belongs to. The most
+ common use of the section information is in GUI based package management
+ applications.</para>
+
+ <para>The default values for the section variables are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><command>SECTION = "base"</command></para>
+ </listitem>
+
+ <listitem>
+ <para><command>SECTION_${PN}-doc = "doc"</command></para>
+ </listitem>
+
+ <listitem>
+ <para><command>SECTION_${PN}-dev = "devel"</command></para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note that each package generated by a recipe can have it's own section
+ and that by default documentation and development files are seperated out to
+ their own sections.</para>
+
+ <para>The table of sections show the current usage of section information.
+ This is a recomendation only, althought it is recomended that any additions
+ or modifications be discusssed via the open embedded developer mailing list
+ first.</para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="1*" />
+
+ <colspec colwidth="3*" />
+
+ <tbody>
+ <row>
+ <entry>Section</entry>
+
+ <entry>Description</entry>
+ </row>
+
+ <row>
+ <entry>admin</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>base</entry>
+
+ <entry>Base system files. These are applications which are expected
+ to be included as part of a base system and include things such as
+ init scripts, core utilities, standard system daemons etc.</entry>
+ </row>
+
+ <row>
+ <entry>base/shell</entry>
+
+ <entry>Shells such as bash, tcsh, ksh etc.</entry>
+ </row>
+
+ <row>
+ <entry>bootloaders</entry>
+
+ <entry>Bootloaders, which are the applications responsible for
+ loading the kernel from the appropriate location (disk, flash,
+ network, etc.) and starting it running.</entry>
+ </row>
+
+ <row>
+ <entry>console</entry>
+
+ <entry>Applications which run on the console. These require no GUI
+ related libraries or interfaces to run.</entry>
+ </row>
+
+ <row>
+ <entry>console/editors</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>console/games</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>console/multimedia</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>console/network</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>console/scientific</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>console/telephony</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>console/tools</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>console/utils</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>devel</entry>
+
+ <entry>Development related files. These include compilers,
+ libraries, headers, debuggers etc.</entry>
+ </row>
+
+ <row>
+ <entry>devel/libs</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>devel/perl</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>devel/python</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>devel/rexx</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>devel/ruby</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>devel/scheme</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>devel/tcltk</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>doc</entry>
+
+ <entry>Documentation, including man pages and sample configuration
+ files.</entry>
+ </row>
+
+ <row>
+ <entry>e/apps</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>e/libs</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>e/utils</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>fonts</entry>
+
+ <entry>Fonts that are not X11 or OPIE specific such as truetype
+ fonts.</entry>
+ </row>
+
+ <row>
+ <entry>games</entry>
+
+ <entry>Games.</entry>
+ </row>
+
+ <row>
+ <entry>games/arcade</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>gpe</entry>
+
+ <entry>GPE GUI enviroment. For the anything that provides or uses
+ the GPE UI. Note that development and documentation related files
+ should be in the appropriate devel and doc section, not under
+ GPE.</entry>
+ </row>
+
+ <row>
+ <entry>gpe/applications</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>gpe/base</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>gpe/games</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>gpe/libs</entry>
+
+ <entry>GPE runtime libraries. This does not include libraries used
+ for development - they should be included in the appropriate devel
+ section.</entry>
+ </row>
+
+ <row>
+ <entry>gpe/multimedia</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>inputmethods</entry>
+
+ <entry>inputmethods that are neither libs, nor solely for GPE/Opie or the console</entry>
+ </row>
+
+ <row>
+ <entry>interpreters</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>kde</entry>
+
+ <entry>KDE related applications.</entry>
+ </row>
+
+ <row>
+ <entry>kde/devel</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>kernel</entry>
+
+ <entry>Linux kernels.</entry>
+ </row>
+
+ <row>
+ <entry>kernel/modules</entry>
+
+ <entry>Linux kernel modules. This include out-of-tree kernel
+ modules.</entry>
+ </row>
+
+ <row>
+ <entry>kernel/userland</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>libs</entry>
+
+ <entry>Runtime libraries. This does not include libraries used for
+ development - they should be included in the appropriate devel
+ section.</entry>
+ </row>
+
+ <row>
+ <entry>libs/inputmethods</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>libs/multimedia</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>libs/network</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>network</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>network/cms</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>network/misc</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>openmoko</entry>
+
+ <entry>Anything related to openmoko.org</entry>
+ </row>
+
+ <row>
+ <entry>openmoko/applications</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>openmoko/base</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>openmoko/examples</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>openmoko/libs</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>openmoko/pim</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>openmoko/tools</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie</entry>
+
+ <entry>OPIE GUI enviroment. For the anything that provides or uses
+ the OPIE UI. Note that development and documentation related files
+ should be in the appropriate devel and doc section, not under
+ OPIE.</entry>
+ </row>
+
+ <row>
+ <entry>opie/applets</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/applications</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/base</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/codecs</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/datebook</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/decorations</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/fontfactories</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/fonts</entry>
+
+ <entry>OPIE specific fonts. General fonts, such as truetype fonts,
+ should be in the fonts section.</entry>
+ </row>
+
+ <row>
+ <entry>opie/games</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/help</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/inputmethods</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/libs</entry>
+
+ <entry>OPIE runtime libraries. This does not include libraries used
+ for development - they should be included in the appropriate devel
+ section.</entry>
+ </row>
+
+ <row>
+ <entry>opie/multimedia</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/network</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/pim</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/security</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/settings</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/shell</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/styles</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>opie/today</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>utils</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>x11</entry>
+
+ <entry>X11 GUI platform. For anything that provides or uses the X11
+ UI and is not GPE. Note that development and documentation related
+ files should be in the appropriate devel and doc section, not under
+ X11.</entry>
+ </row>
+
+ <row>
+ <entry>x11/applications</entry>
+
+ <entry>General applications.</entry>
+ </row>
+
+ <row>
+ <entry>x11/base</entry>
+
+ <entry>Core X11 applications.</entry>
+ </row>
+
+ <row>
+ <entry>x11/data</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>x11/fonts</entry>
+
+ <entry>X11 specific fonts. General fonts, such as truetype fonts,
+ should be in the fonts section.</entry>
+ </row>
+
+ <row>
+ <entry>x11/games</entry>
+
+ <entry>Games.</entry>
+ </row>
+
+ <row>
+ <entry>x11/gnome</entry>
+
+ <entry>Core gnome applications.</entry>
+ </row>
+
+ <row>
+ <entry>x11/gnome/libs</entry>
+
+ <entry>Gnome runtime libraries. This does not include libraries used
+ for development - they should be included in the appropriate devel
+ section.</entry>
+ </row>
+
+ <row>
+ <entry>x11/graphics</entry>
+
+ <entry>Applications which manipulate, display, edit, print etc.
+ images, photos, diagrams etc.</entry>
+ </row>
+
+ <row>
+ <entry>x11/libs</entry>
+
+ <entry>X11 runtime libraries. This does not include libraries used
+ for development - they should be included in the appropriate devel
+ section.</entry>
+ </row>
+
+ <row>
+ <entry>x11/multimedia</entry>
+
+ <entry>Multimedia applications.</entry>
+ </row>
+
+ <row>
+ <entry>x11/network</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>x11/office</entry>
+
+ <entry>Office and productivity applications.</entry>
+ </row>
+
+ <row>
+ <entry>x11/scientific</entry>
+
+ <entry>Scientific applications.</entry>
+ </row>
+
+ <row>
+ <entry>x11/utils</entry>
+
+ <entry></entry>
+ </row>
+
+ <row>
+ <entry>x11/wm</entry>
+
+ <entry>Window managers.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para>The following tables lists some sections which may be in existing
+ recipes. These should not be used in new recipes and should be renamed when
+ updated existing recipes that use the specified sections.</para>
+
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colwidth="1*" />
+
+ <colspec colwidth="3*" />
+
+ <tbody>
+ <row>
+ <entry>Section</entry>
+
+ <entry>Action</entry>
+ </row>
+
+ <row>
+ <entry>apps</entry>
+
+ <entry>Replace with appropriate section</entry>
+ </row>
+
+ <row>
+ <entry>gui</entry>
+
+ <entry>Replace with appropriate section</entry>
+ </row>
+
+ <row>
+ <entry>media-gfx</entry>
+
+ <entry>Replace with appropriate section</entry>
+ </row>
+
+ <row>
+ <entry>multimedia</entry>
+
+ <entry>Replace with appropriate section</entry>
+ </row>
+
+ <row>
+ <entry>net</entry>
+
+ <entry>Replace with network</entry>
+ </row>
+
+ <row>
+ <entry>unknown</entry>
+
+ <entry>Replace with appropriate section</entry>
+ </row>
+
+ <row>
+ <entry>x11-misc</entry>
+
+ <entry>Replace with appropriate section</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <para></para>
+</section>
diff --git a/docs/usermanual/reference/var_src_uri.xml b/docs/usermanual/reference/var_src_uri.xml
new file mode 100644
index 0000000000..a9a2985a70
--- /dev/null
+++ b/docs/usermanual/reference/var_src_uri.xml
@@ -0,0 +1,692 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="src_uri_variable" xreflabel="SRC_URI variable">
+ <title>SRC_URI variable: Source code and patches</title>
+
+ <para>All recipies need to contain a definition of
+ <command>SRC_URI</command>. It determines what files and source code is
+ needed and where that source code should be obtained from. This includes
+ patches to be applied and basic files that are shipped as part of the
+ meta-data for the package.</para>
+
+ <para>A typical <command>SRC_URI</command> contains a list of URL's, patches
+ and files as shown in this example from quagga:<screen>SRC_URI = "http://www.quagga.net/download/quagga-${PV}.tar.gz \
+ file://ospfd-no-opaque-lsa-fix.patch;patch=1 \
+ file://fix-for-lib-inpath.patch;patch=1 \
+ file://quagga.init \
+ file://quagga.default \
+ file://watchquagga.init \
+ file://watchquagga.default"</screen>All source code and files will
+ be placed into the work directory, <command>${WORKDIR}</command>, for the
+ package. All patches will be placed into a <command>patches</command>
+ subdirectory of the package source directory, <command>${S}</command>, and
+ then automatically applied to the source.</para>
+
+ <para>Before downloading from a remote URI a check will be made to see if
+ what is to be retrieved is already present in the download source directory,
+ <command>${DL_DIR}</command>, along with an associated md5 sum. If the
+ source is present in the downloaded sources directory and the md5 sum
+ matches that listed in the associated md5 sum file, then that version will
+ be used in preference to retrieving a new version . Any source that is
+ retrieved from a remote URI will be stored in the download source directory
+ and an appropriate md5 sum generated and stored alongside it.</para>
+
+ <para>Each URI supports a set of additional options. These options are
+ tag/value pairs of the form <command>"a=b"</command> and are semi-colon
+ separated from each other and from the URI. The follow examples shows two
+ options being included, the patch and pnum options:<screen>file://ospfd-no-opaque-lsa-fix.patch;patch=1;pnum=2</screen>The
+ supported methods for fetching source and files are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>http, https, ftps</term>
+
+ <listitem>
+ <para>Used to download files and source code via the specified URL.
+ These are fetched from the specified location using wget.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>file</term>
+
+ <listitem>
+ <para>Used for files that are included locally in the meta-data. These
+ may be plain files, such as init scripts to be added to the final
+ package, or they may be patch files to be applied to other
+ source.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>cvs</term>
+
+ <listitem>
+ <para>Used to download from a CVS repository.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>svn</term>
+
+ <listitem>
+ <para>Used to download from a subversion repository.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>git</term>
+
+ <listitem>
+ <para>Used to download from a git repository.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>When source code is specified as a part of <command>SRC_URI</command>
+ it is unpacked into the work directory, <command>${WORKDIR}</command>. The
+ unpacker recognises several archive and compression types and for these it
+ will decompress any compressed files and extract all of the files from
+ archives into the work directory. The supported types are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>.tar</term>
+
+ <listitem>
+ <para>Tar archives which will be extracted with <command>"tar x
+ --no-same-owner -f &lt;srcfile&gt;"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>.tgz, .tar.gz, tar.Z</term>
+
+ <listitem>
+ <para>Gzip compressed tar archives which will be extracted with
+ <command>"tar xz --no-same-owner -f &lt;srcfile&gt;"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>.tbz, .tar.bz2</term>
+
+ <listitem>
+ <para>Bzip2 compressed tar archives which will be extracted with
+ <command>"bzip2 -dc &lt;srcfile&gt; | tar x --no-same-owner -f
+ -"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>.gz, .Z, .z</term>
+
+ <listitem>
+ <para>Gzip compressed files which will be decompressed with
+ <command>"gzip -dc &lt;srcfile&gt; &gt;
+ &lt;dstfile&gt;"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>.bz2</term>
+
+ <listitem>
+ <para>Bzip2 compressed files which will be decompressed with
+ <command>"bzip2 -dc &lt;srcfile&gt; &gt;
+ &lt;dstfile&gt;"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>.zip</term>
+
+ <listitem>
+ <para>Zip archives which will be extracted with <command>"unzip -q
+ &lt;srcfile&gt;"</command>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The downloading of the source files occurs in the
+ <emphasis>fetch</emphasis> task, the unpacking and copying to the work
+ directory occurs in the <emphasis>unpack</emphasis> task and the applying of
+ patches occurs in the <emphasis>patch</emphasis> task.</para>
+
+ <section>
+ <title>http/https/ftp (wget)</title>
+
+ <para>The wget fetcher handles http, https and ftp URLs.<screen>http://www.quagga.net/download/quagga-${PV}.tar.gz</screen></para>
+
+ <para>Supported options:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>md5sum</term>
+
+ <listitem>
+ <para>If an md5sum is provided then the downloaded files will only
+ be considered valid if the md5sum of the downloaded file matches the
+ md5sum option provided.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Related variables:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>MIRRORS</term>
+
+ <listitem>
+ <para>Mirrors define alternative locations to download source files
+ from. See the mirror section below for more information.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DL_DIR</term>
+
+ <listitem>
+ <para>The downloaded files will be placed in this directory with the
+ name exactly as supplied via the URI.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>file: for patches and additional files</title>
+
+ <para>The file URI's are used to copy files, included as part of the
+ package meta data, into the work directory to be used when building the
+ package. Typical use of the file URI's is to specify patches that be
+ applied to the source and to provide additional files, such as init
+ scripts, to be included in the final package.</para>
+
+ <para>The following example shows the specification of a patch
+ file:<screen>file://ospfd-no-opaque-lsa-fix.patch;patch=1</screen></para>
+
+ <para>Patch files are be copied to the patches subdirectory of the source
+ directory, <command>${S}/patches</command>, and then applied from the
+ source directory. The patches are searched for along the path specified
+ via the file path variable, <command>${FILESPATH},</command> and if not
+ found the directory specified by the file directory variable,
+ <command>${FILEDIR}</command>, is also checked.</para>
+
+ <para>The following example shows the specification of a non-patch file.
+ In this case it's an init script:<screen>file://quagga.init</screen>Non-patch
+ files are copied to the work directory, <command>${WORKDIR}</command>. You
+ can access these files from within a recipe by referring to them relative
+ to the work directory. The following example, from the quagga recipe,
+ shows the above init script being included in the package by copying it
+ during the <emphasis>install</emphasis> task:<screen>do_install () {
+ # Install init script and default settings
+ install -m 0755 -d ${D}${sysconfdir}/default ${D}${sysconfdir}/init.d ${D}${sysconfdir}/quagga
+ install -m 0644 <emphasis role="bold">${WORKDIR}/quagga.init</emphasis> ${D}${sysconfdir}/init.d/quagga
+...</screen></para>
+
+ <para>Supported options:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>patch</term>
+
+ <listitem>
+ <para>Used as <command>"patch=1"</command> to define this file as a
+ patch file. Patch files will be copied to
+ <command>${S}/patches</command> and then applied to source from
+ within the source directory, <command>${S}</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>pnum</term>
+
+ <listitem>
+ <para>By default patches are applied with the <command>"-p
+ 1"</command> parameter, which strips off the first directory of the
+ pathname in the patches. This option is used to explicitly control
+ the value passed to <command>"-p"</command>. The most typical use is
+ when the patches are relative to the source directory already and
+ need to be applied using <command>"-p 0"</command>, in which case
+ the <command>"pnum=0"</command> option is supplied.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>cvs</title>
+
+ <para>The cvs fetcher is used to retrieve files from a CVS repository.
+ <screen> cvs://anonymous@cvs.sourceforge.net/cvsroot/linuxsh;module=linux;date=20051111</screen>A
+ cvs URI will retrieve the source from a cvs repository. Note that use of
+ the <emphasis>date=</emphasis> to specify a checkout for specified date.
+ It is preferable to use either a <emphasis>date=</emphasis> or a
+ <emphasis>tag=</emphasis> option to select a specific date and/or tag from
+ cvs rather than leave the checkout floating at the head revision.</para>
+
+ <para>Supported options:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>module</term>
+
+ <listitem>
+ <para>The name of a module to retrieve. This is a required parameter
+ and there is no default value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>tag</term>
+
+ <listitem>
+ <para>The name of a cvs tag to retrieve. Releases are often tagged
+ with a specific name to allow easy access. Either a tag or a date
+ can be specified, but not both.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>date</term>
+
+ <listitem>
+ <para>The date to retrieve. This requests that files as of the
+ specified date, rather then the current code or a tagged release. If
+ no date or tag options are specified, then the date is set to the
+ current date. The date is of any form accepted by cvs with the most
+ common format being <command>"YYYYMMDD"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>method</term>
+
+ <listitem>
+ <para>The method used to access the repository. Common options are
+ <command>"pserver"</command> and <command>"ext"</command> (for cvs
+ over rsh or ssh). The default is
+ <command>"pserver"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>rsh</term>
+
+ <listitem>
+ <para>The rsh command to use with the <command>"ext"</command>
+ method. Common options are <command>"rsh"</command> or
+ <command>"ssh"</command>. The default is
+ <command>"rsh"</command>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Related variables:<variablelist>
+ <varlistentry>
+ <term>CVS_TARBALL_STASH</term>
+
+ <listitem>
+ <para>Used to specifies a location to search for pre-generated tar
+ archives to use instead of accessing cvs directly.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>CVSDIR</term>
+
+ <listitem>
+ <para>The directory in which the cvs checkouts will be performed.
+ The default is <command>${DL_DIR}/cvs</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DL_DIR</term>
+
+ <listitem>
+ <para>A compressed tar archive of the retrieved files will be
+ placed in this directory. The archive name will be of the form:
+ <command>"&lt;module&gt;_&lt;host&gt;_&lt;tag&gt;_&lt;date&gt;.tar.gz"</command>.
+ Path separators in <command>module</command> will be replaced with
+ full stops.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>svn</title>
+
+ <para>The svn fetcher is used to retrieve files from a subversion
+ repository.</para>
+
+ <para><screen> svn://svn.xiph.org/trunk;module=Tremor;rev=4573;proto=http</screen></para>
+
+ <para>Supported options:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>module</term>
+
+ <listitem>
+ <para>The name of a module to retrieve. This is a required parameter
+ and there is no default value.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>rev</term>
+
+ <listitem>
+ <para>The revision to retrieve. Revisions in subversion are integer
+ values.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>proto</term>
+
+ <listitem>
+ <para>The method to use to access the repository. Common options are
+ <command>"svn"</command>, <command>"svn+ssh"</command>,
+ <command>"http"</command> and <command>"https"</command>. The
+ default is <command>"svn"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>rsh</term>
+
+ <listitem>
+ <para>The rsh command to use with using the
+ <command>"svn+ssh"</command> method. Common options are
+ <command>"rsh"</command> or <command>"ssh"</command>. The default is
+ <command>"ssh"</command>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Related variables:<variablelist>
+ <varlistentry>
+ <term>SVNDIR</term>
+
+ <listitem>
+ <para>The directory in which the svn checkouts will be performed..
+ The default is <command>${DL_DIR}/svn</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DL_DIR</term>
+
+ <listitem>
+ <para>A compressed tar archive of the retrieved files will be
+ placed in this directory. The archive name will be of the form:
+ <command>"&lt;module&gt;_&lt;host&gt;_&lt;path&gt;_&lt;revn&gt;_&lt;date&gt;.tar.gz"</command>.
+ Path separators in <command>path</command> and
+ <command>module</command> will be replaced with full stops.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>git</title>
+
+ <para>The git fetcher is used to retrieve files from a git repository.
+ <screen> SRC_URI = "git://www.denx.de/git/u-boot.git;protocol=git;tag=${TAG}"</screen></para>
+
+ <para>Supported options:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>tag</term>
+
+ <listitem>
+ <para>The tag to retrieve. The default is
+ <command>"master"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>protocol</term>
+
+ <listitem>
+ <para>The method to use to access the repository. Common options are
+ <command>"git"</command> and <command>"rsync"</command>. The default
+ is <command>"rsync"</command>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>Related variables</para>
+
+ <para><variablelist>
+ <varlistentry>
+ <term>GITDIR</term>
+
+ <listitem>
+ <para>The directory in which the git checkouts will be performed.
+ The default is <command>${DL_DIR}/git</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DL_DIR</term>
+
+ <listitem>
+ <para>A compressed tar archive of the retrieved files will be
+ placed in this directory. The archive name will be of the form:
+ <command>"git_&lt;host&gt;&lt;mpath&gt;_&lt;tag&gt;.tar.gz"</command>.
+ Path separators in <command>host</command> will be replaced with
+ full stops.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist></para>
+ </section>
+
+ <section>
+ <title>Mirrors</title>
+
+ <para>The support for mirror sites enables spreading the load over sites
+ and allows for downloads to occur even when one of the mirror sites are
+ unavailable.</para>
+
+ <para>Default mirrors, along with their primary URL, include:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>GNU_MIRROR</term>
+
+ <listitem>
+ <para>ftp://ftp.gnu.org/gnu</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>DEBIAN_MIRROR</term>
+
+ <listitem>
+ <para>ftp://ftp.debian.org/debian/pool</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SOURCEFORGE_MIRROR</term>
+
+ <listitem>
+ <para>http://heanet.dl.sourceforge.net/sourceforge</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GPE_MIRROR</term>
+
+ <listitem>
+ <para>http://handhelds.org/pub/projects/gpe/source</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>XLIBS_MIRROR</term>
+
+ <listitem>
+ <para>http://xlibs.freedesktop.org/release</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>XORG_MIRROR</term>
+
+ <listitem>
+ <para>http://xorg.freedesktop.org/releases</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GNOME_MIRROR</term>
+
+ <listitem>
+ <para>http://ftp.gnome.org/pub/GNOME/sources</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>FREEBSD_MIRROR</term>
+
+ <listitem>
+ <para>ftp://ftp.freebsd.org/pub/FreeBSD</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>GENTOO_MIRROR</term>
+
+ <listitem>
+ <para>http://distro.ibiblio.org/pub/linux/distributions/gentoo/distfiles</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>APACHE_MIRROR</term>
+
+ <listitem>
+ <para>http://www.apache.org/dist</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>When creating new recipes this mirrors should be used when you wish
+ to use one of the above sites by referring to the name of the mirror in
+ the URI, as show in this example from flex:<screen>SRC_URI = "${SOURCEFORGE_MIRROR}/lex/flex-2.5.31.tar.bz2</screen></para>
+
+ <para>You can manually define your mirrors if you wish to force the use of
+ a specific mirror by exporting the appropriate mirrors in
+ <command>local.conf</command> with them set to the local mirror:<screen>export GNU_MIRROR = "http://www.planetmirror.com/pub/gnu"
+export DEBIAN_MIRROR = "http://mirror.optusnet.com.au/debian/pool"
+export SOURCEFORGE_MIRROR = "http://optusnet.dl.sourceforge.net/sourceforge"</screen></para>
+
+ <para>Mirrors can be extended in individual recipes via the use of
+ <command>MIRRORS_prepend</command> or <command>MIRRORS_append</command>.
+ Each entry in the list contains the mirror name on the left-hand side and
+ the URI of the mirror on the right-hand side. The following example from
+ libffi shows the addition of two URI for the
+ <command>"${GNU_MIRROR}/gcc/"</command> URI:<screen>MIRRORS_prepend () {
+ ${GNU_MIRROR}/gcc/ http://gcc.get-software.com/releases/
+ ${GNU_MIRROR}/gcc/ http://mirrors.rcn.net/pub/sourceware/gcc/releases/
+}</screen></para>
+ </section>
+
+ <section>
+ <title>Manipulating SRC_URI</title>
+
+ <para>Sometimes it is desirable to only include patches for a specific
+ architecture and/or to include different files based on the architecture.
+ This can be done via the <command>SRC_URI_append</command> and/or
+ <command>SRC_URI_prepend</command> methods for adding additional URI's
+ based on the architecture or machine name.</para>
+
+ <para>In this example from glibc, the patch creates a configuration file
+ for glibc, which should only be used or the sh4 architecture. Therefore
+ this patch is appended to the <command>SRC_URI</command>, but only for the
+ sh4 architecture. For other architectures it is ignored:<screen># Build fails on sh4 unless no-z-defs is defined
+SRC_URI_append_sh4 = " file://no-z-defs.patch;patch=1"</screen></para>
+ </section>
+
+ <section>
+ <title>Source distribution (src_distribute_local)</title>
+
+ <para>In order to obtain a set of source files for a build you can use the
+ <emphasis>src_distribute_local</emphasis> class. This will result in all
+ the files that were actually used during a build being made available in a
+ seperate directory and therefore they can be distributed with the
+ binaries.</para>
+
+ <para>Enabling this option is as simple as activating the functionality by
+ including the required class in one of your configuration files:<screen>SRC_DIST_LOCAL = "copy"
+INHERIT += "src_distribute_local"</screen></para>
+
+ <para>Now during a build each recipe which has a LICENSE that mandates
+ source availability, like the GPL, will be placed into the source
+ distribution directory, <command>${SRC_DISTRIBUTEDIR}</command>, after
+ building.</para>
+
+ <para>There are some options available to effect the option</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>SRC_DIST_LOCAL</term>
+
+ <listitem>
+ <para>Specifies if the source files should be copied, symlinked or
+ moved and symlinked back. The default is
+ <command>"move+symlink"</command>.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>SRC_DISTRIBUTEDIR</term>
+
+ <listitem>
+ <para>Specifies the source distribution directory - this is why the
+ source files that was used for the build are placed. The default is
+ <command>"${DEPLOY_DIR}/sources"</command>.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>The valid values for <command>SRC_DIST_LOCAL</command> are:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>copy</term>
+
+ <listitem>
+ <para>Copies the files to the downloaded sources directory into the
+ distribution directory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>symlink</term>
+
+ <listitem>
+ <para>Symlinks the files from the downloaded sources directory into
+ the distribution directory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>move+symlink</term>
+
+ <listitem>
+ <para>Moves the files from the downloaded sources directory into the
+ distribution directory. Then creates a symlink in the download
+ sources directory to the moved files.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+</section> \ No newline at end of file