diff options
author | Michael 'Mickey' Lauer <mickey@vanille-media.de> | 2009-02-25 01:47:30 +0100 |
---|---|---|
committer | Michael 'Mickey' Lauer <mickey@vanille-media.de> | 2009-02-25 01:47:30 +0100 |
commit | 25b51d32c982a6767f3d4a88dec12f70c8c8f875 (patch) | |
tree | 206e94d12d2fda511c5b383adfec3684829703a1 /docs/usermanual/reference/class_image.xml | |
parent | 6d76191b2021518d2f1ea00c20a1ec3151d93069 (diff) | |
download | openembedded-25b51d32c982a6767f3d4a88dec12f70c8c8f875.tar.gz |
docs: import usermanual from org.openembedded.documentation.
org.openembedded.documentation is deprecated now; please do all updates here!
Diffstat (limited to 'docs/usermanual/reference/class_image.xml')
-rw-r--r-- | docs/usermanual/reference/class_image.xml | 358 |
1 files changed, 358 insertions, 0 deletions
diff --git a/docs/usermanual/reference/class_image.xml b/docs/usermanual/reference/class_image.xml new file mode 100644 index 0000000000..b591e9aae2 --- /dev/null +++ b/docs/usermanual/reference/class_image.xml @@ -0,0 +1,358 @@ +<?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 |