path: root/usermanual/reference/class_image.xml

<?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 for
      the <command>FEED_URIS</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>
  </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 (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 supported. Each feed provides 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>