aboutsummaryrefslogtreecommitdiffstats
path: root/usermanual/reference/class_image.xml
diff options
context:
space:
mode:
authorJamie Lenehan <lenehan@twibble.org>2007-05-02 10:01:08 +0000
committerJamie Lenehan <lenehan@twibble.org>2007-05-02 10:01:08 +0000
commit8572b86970698184c4e1d51bd4f46437963b7bae (patch)
treea86ec45fb86c01c8905ee4686d7a925e4e7caf2f /usermanual/reference/class_image.xml
parenta35403110d02609e837e2c9835566825a5c75574 (diff)
downloadopenembedded-8572b86970698184c4e1d51bd4f46437963b7bae.tar.gz
openembedded-8572b86970698184c4e1d51bd4f46437963b7bae.tar.bz2
openembedded-8572b86970698184c4e1d51bd4f46437963b7bae.zip
usermanual: The image_ipkg class is now just the image class. Update
all references. Modify description to include details about how it can potentially support other packaging types now. Probably needs a more detailed check to see if anything else changed.
Diffstat (limited to 'usermanual/reference/class_image.xml')
-rw-r--r--usermanual/reference/class_image.xml291
1 files changed, 291 insertions, 0 deletions
diff --git a/usermanual/reference/class_image.xml b/usermanual/reference/class_image.xml
new file mode 100644
index 0000000000..7d203f888c
--- /dev/null
+++ b/usermanual/reference/class_image.xml
@@ -0,0 +1,291 @@
+<?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> \ No newline at end of file