--- /dev/null
+<?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
+ <table></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
projects / vuplus_openembedded / blobdiff