path: root/docs/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 
      (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>