diff options
Diffstat (limited to 'usermanual/reference/class_image.xml')
| -rw-r--r-- | usermanual/reference/class_image.xml | 291 |
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 + <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 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 |