usermanual: Add details on the image_ipk and rootfs_ipk to the

reference section of the document. Add id and xreflabel to all
sections in the reference documentation so we can refer to the
individual sections (which is used here to refer to the image types).

10 files changed, 507 insertions, 7 deletions

diff --git a/usermanual/reference/class_autotools.xml b/usermanual/reference/class_autotools.xml
index fd6c36da8e..a14b6d6ee8 100644
--- a/usermanual/reference/class_autotools.xml
+++ b/usermanual/reference/class_autotools.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<section>
+<section id="autotools_class" xreflabel="autotools class">
   <title>autotools class</title>
 
   <para>Autotools is one of the most commonly seen configuration methods for
diff --git a/usermanual/reference/class_binconfig.xml b/usermanual/reference/class_binconfig.xml
index 27eafa16f9..bf6290039d 100644
--- a/usermanual/reference/class_binconfig.xml
+++ b/usermanual/reference/class_binconfig.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<section>
+<section id="binconfig_class" xreflabel="binconfig class">
   <title>binconfig class</title>
 
   <para>The binconfig class is for packages that install
diff --git a/usermanual/reference/class_distutils.xml b/usermanual/reference/class_distutils.xml
index 96be6f6884..f2a2ec8957 100644
--- a/usermanual/reference/class_distutils.xml
+++ b/usermanual/reference/class_distutils.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<section>
+<section id="distutils_class" xreflabel="distutils class">
   <title>distutils class</title>
 
   <para>Distutils is a standard python system for building and installing
diff --git a/usermanual/reference/class_image_ipkg.xml b/usermanual/reference/class_image_ipkg.xml
new file mode 100644
index 0000000000..c81a76da2f
--- /dev/null
+++ b/usermanual/reference/class_image_ipkg.xml
@@ -0,0 +1,280 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section id="image_ipkg_class" xreflabel="image_ipkg class">
+  <title>image_ipkg class</title>
+
+  <para>The image_ipkg class is used to generate images containing a root
+  filesystem, as generate by the <xref linkend="rootfs_ipkg_class" /> class,
+  for use on the target device. This could be a <emphasis>jffs2</emphasis>
+  image to be written into flash on the target device for example. In addition
+  it also configures the ipkg feeds (where to get updates from) in the root
+  filesystem and is able to generate multiple different image types.</para>
+
+  <para>Summary of actions performed by the <emphasis>image_ipkg</emphasis>
+  class:</para>
+
+  <orderedlist>
+    <listitem>
+      <para>Inherits the <xref linkend="rootfs_ipkg_class" /> in order to
+      bring in the functionality required to generate a root filesystem image
+      from a set of ipkg's that will be suitable for included in the
+      image(s);</para>
+    </listitem>
+
+    <listitem>
+      <para>Sets <command>BUILD_ALL_DEPS = "1"</command> to force 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 determine 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>Call into <xref linkend="rootfs_ipkg_class" /> to install all of
+      the required components into the root filesystem;</para>
+    </listitem>
+
+    <listitem>
+      <para>Configures the ipkg feed information in the root filesystem for
+      the <command>FEED_URIS</command>;</para>
+    </listitem>
+
+    <listitem>
+      <para>Run any image per-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>Run 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 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 /dev 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.</para>
+
+        <para>Default: <command>""</command></para>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term>IMAGE_POSTPROCESS_COMMAND</term>
+
+      <listitem>
+        <para>Additional commands to run after processing the image.</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 modify existing types and creating new types is
+        provided in the <xref linkend="image_types" /> section.</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>
+  </variablelist>
+
+  <section>
+    <title>Special node handling (fakeroot)</title>
+
+    <para>Special nodes, such as /dev nodes, and files with special
+    permissions, such as suid files, are handled via the fakeroot system. This
+    means that when you view the contents of the root filesystem these device
+    appear to be created incorrectly:</para>
+
+    <para>While these devices do not appear correctly on disk, fakeroot keeps
+    track of what they should be and when generating images it will provide
+    the proper files to the commands (such as tar) which are processing the
+    root filesystem. Note that for this to work all of the commands related to
+    generating the image must be run under fakeroot. This is the remove for
+    the IMAGE_PREPROCESS_COMMAND and IMAGE_POSTPROCESS_COMMAND variables -
+    these variables are processed while still under the fakeroot
+    process.</para>
+  </section>
+
+  <section>
+    <title>Device (/dev) nodes</title>
+
+    <para>There are two variables that can be defined for creating device
+    nodes. The newer version supports multiple device node tables and searches
+    for the specified files along ${BBPATH} so that relative file names may be
+    used.</para>
+
+    <para>The following example from machine/titan.conf 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 /dev/SC{0,1,2} nodes
+          which are required for the SH processors on board SCI and SCIF
+          serial ports. On the titan 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 fro creating the /dev/sm0 and
+          /dev/sm0p{0,1,2} devices nodes for the block driver and associated
+          partitions that is used to managed the flash on the titan board.
+          </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
+    IMAGE_FSTYPES 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 (feed_uris)</title>
+
+    <para>Package feeds are used by the ipkg command to determine where to
+    retrieve updates and new packages from.</para>
+
+    <para>Multiple feeds are support. Each is provided with a feed name and
+    the URL which will contain the packages. The following example shows the
+    addition of two feeds, one called <emphasis>base</emphasis> and one called
+    <emphasis>updates</emphasis>:</para>
+
+    <para><screen>FEED_URIS += " \
+        base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \
+        updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"</screen></para>
+  </section>
+</section>
\ No newline at end of file
diff --git a/usermanual/reference/class_pkgconfig.xml b/usermanual/reference/class_pkgconfig.xml
index 9040bc5c44..08df975b84 100644
--- a/usermanual/reference/class_pkgconfig.xml
+++ b/usermanual/reference/class_pkgconfig.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<section>
+<section id="pkgconfig_class" xreflabel="pkgconfig class">
   <title>pkgconfig class</title>
 
   <para>The pkgconfig class is for packages that install
diff --git a/usermanual/reference/class_rootfs_ipkg.xml b/usermanual/reference/class_rootfs_ipkg.xml
new file mode 100644
index 0000000000..095c3278be
--- /dev/null
+++ b/usermanual/reference/class_rootfs_ipkg.xml
@@ -0,0 +1,216 @@
+<?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 packages that
+  would need to be included in the root filesystem of the target
+  device.</para>
+
+  <para>This class is normally not useddirectly, but instead used from
+  the<xref linkend="image_ipkg_class" /> which creates disk images from a set
+  of <command>.ipkg</command> files.</para>
+
+  <para>Summary of actions performed by the <emphasis>rootfs_ipkg</emphasis>
+  class:</para>
+
+  <orderedlist>
+    <listitem>
+      <para>Erase an existing root filesyste 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>Install locale related .ipkg packages;</para>
+    </listitem>
+
+    <listitem>
+      <para>Install 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>remote_init_link</command>;</para>
+    </listitem>
+
+    <listitem>
+      <para>Adds the rootfs task to run after the do_install 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>IPKG_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}
+        ${IPKG_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 fakeroot, so
+  any permissions, special devices files etc will be remember by fakeroot by
+  lost once the class has completed. This is why the
+  <command>ROOTFS_POSTPROCESS_COMMAND</command> is useful - it performs it's
+  actions while under the control of fakeroot. The class also provides a
+  function real_do_rootfs which is executed without fakeroot - this is used
+  from other classes, such as <xref linkend="image_ipkg_class" />, to perform
+  the functionality of this class under the control of it's own fakeroot
+  process so that it can perform additional actions under the control of
+  fakeroot in addition to that performed by the rootfs_ipkg class.</para>
+</section>
\ No newline at end of file
diff --git a/usermanual/reference/class_update-alternatives.xml b/usermanual/reference/class_update-alternatives.xml
index 21d2c9c2ca..4e8f64a32d 100644
--- a/usermanual/reference/class_update-alternatives.xml
+++ b/usermanual/reference/class_update-alternatives.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<section>
+<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
diff --git a/usermanual/reference/class_update-rc.d.xml b/usermanual/reference/class_update-rc.d.xml
index 11eed9ae4a..c29501fe59 100644
--- a/usermanual/reference/class_update-rc.d.xml
+++ b/usermanual/reference/class_update-rc.d.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<section>
+<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
diff --git a/usermanual/reference/image_types.xml b/usermanual/reference/image_types.xml
index 2f6b29849a..3ccfe9c4e0 100644
--- a/usermanual/reference/image_types.xml
+++ b/usermanual/reference/image_types.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<section>
+<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
diff --git a/usermanual/usermanual.xml b/usermanual/usermanual.xml
index b6c60da966..4995144045 100644
--- a/usermanual/usermanual.xml
+++ b/usermanual/usermanual.xml
@@ -8,8 +8,10 @@
 <!ENTITY class-autotools           SYSTEM "reference/class_autotools.xml">
 <!ENTITY class-binconfig           SYSTEM "reference/class_binconfig.xml">
 <!ENTITY class-distutils           SYSTEM "reference/class_distutils.xml">
+<!ENTITY class-image_ipkg          SYSTEM "reference/class_image_ipkg.xml">
 <!ENTITY image-types               SYSTEM "reference/image_types.xml">
 <!ENTITY class-pkgconfig           SYSTEM "reference/class_pkgconfig.xml">
+<!ENTITY class-rootfs_ipkg         SYSTEM "reference/class_rootfs_ipkg.xml">
 <!ENTITY class-update-alternatives SYSTEM "reference/class_update-alternatives.xml">
 <!ENTITY class-update-rcd          SYSTEM "reference/class_update-rc.d.xml">
 ]>
@@ -507,8 +509,10 @@ When utilizing OpenEmbedded you avoid searching for patches at many different pl
         &class-autotools;
         &class-binconfig;
         &class-distutils;
+        &class-image_ipkg;
         &image-types;
         &class-pkgconfig;
+        &class-rootfs_ipkg;
         &class-update-alternatives;
         &class-update-rcd;
     </chapter>