diff options
Diffstat (limited to 'usermanual/reference/image_types.xml')
| -rw-r--r-- | usermanual/reference/image_types.xml | 385 |
1 files changed, 385 insertions, 0 deletions
diff --git a/usermanual/reference/image_types.xml b/usermanual/reference/image_types.xml new file mode 100644 index 0000000000..4ea174fd46 --- /dev/null +++ b/usermanual/reference/image_types.xml @@ -0,0 +1,385 @@ +<?xml version="1.0" encoding="UTF-8"?> +<section id="image_types" xreflabel="image types"> + <title>Image types</title> + + <para>One of the most commonly used outputs from a build is a filesystem + image containing the root filesystem for the target device. There are + several variables which can be used to control the type of output images and + the settings for those images, such as endianess or compression ratios. This + section details the available images and the variables that effect them. See + the <xref linkend="image_class" /> section for details on how image + generation is configured.</para> + + <para>The final root file system will consist of all of the files located in + image root filesystem directory, <command>${IMAGE_ROOTFS}</command>, which + is usually <command>tmp/rootfs</command> in the build area. One important + difference between the images and the root file system directory is that any + files which can only be created by privileged users, such as device nodes, + will not appear in the <command>${IMAGE_ROOTFS}</command> directory but they + will be present in any images that are generated. This is due to + <emphasis><xref linkend="fakeroot" /> </emphasis>system keeping track of + these special files and making them available when generating the image - + even though they do not appear in the root filesystem directory. For this + reason it is important to always create an actual image to use for testing, + even if it's just a <command>.tar</command> archive, to ensure you have the + correct device nodes and any other special files.</para> + + <section> + <title>Defining images</title> + + <para>Each supported image type is defined via a set of variables. Each + variables has the name of the image type appended to indicate the settings + for that particular image type. The behaviour of the built in image types + can be changed by modifying these variables, and new types can be created + by defining these variables for the new type.</para> + + <para>The variables that define an image type are:</para> + + <variablelist> + <varlistentry> + <term>IMAGE_CMD_<type></term> + + <listitem> + <para>Specifies the actual command that is run to generate an image + of the specified type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>EXTRA_IMAGECMD_<type></term> + + <listitem> + <para>Used to pass additional command line arguments to the + <command>IMAGE_CMD</command> without the need to redefine the entire + image command. This is often used to pass options such as endianess + and compression rations. You need to look at the + <command>IMAGE_CMD</command> definition to determine how these + options are being used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_ROOTFS_SIZE_<type></term> + + <listitem> + <para>For those image types that generate a fixed size image this + variable is used to specify the required image size.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IMAGE_DEPENDS_<type></term> + + <listitem> + <para>Lists the packages that the <command>IMAGE_CMD</command> + depends on. As an example the jffs2 filesystem creation depends on + <command>mkfs.jffs2</command> command which is part of the mtd + utilities and therefore depends on mtd-utils-native.</para> + </listitem> + </varlistentry> + </variablelist> + </section> + + <section> + <title>Available image types</title> + + <para>The following image types are built in to OpenEmbedded:</para> + + <variablelist> + <varlistentry> + <term>jffs2</term> + + <listitem> + <para>Creates jffs2 <emphasis>"Journaling flash file system + 2"</emphasis> images. This is a read/write, compressed filesystem + for mtd (flash) devices. It is not supported for block + devices.<screen>IMAGE_CMD_jffs2 = "mkfs.jffs2 \ + -x lzo \ + --root=${IMAGE_ROOTFS} \ + --faketime \ + --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \ + ${EXTRA_IMAGECMD}"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for jffs2 + passed to <command>mkfs.jffs2</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_jffs2 = ""</screen></para> + + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for jffs2 was set to + enable padding, to define the endianess and to specify the block + size:<screen><emphasis>EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000"</emphasis></screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cramfs</term> + + <listitem> + <para>Creates cramfs <emphasis>"Compression ROM file + system"</emphasis> images. This is a read only compressed filesystem + which is used directly by decompressing files into RAM as they are + accessed. Files sizes are limited to 16MB, file system size is + limited to 256MB, only 8-bit uids and gids are supported, no hard + links are supported and no time stamps are supported.<screen>IMAGE_CMD_cramfs = "mkcramfs ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cramfs \ + ${EXTRA_IMAGECMD}"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for cramfs is + passed to <command>mkcramfs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_cramfs = ""</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext2</term> + + <listitem> + <para>Creates an <emphasis>"Extended Filesystem 2"</emphasis> image + file. This is the standard Linux non-journaling file system.<screen>IMAGE_CMD_ext2 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \ + -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2 \ + ${EXTRA_IMAGECMD}"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext2 is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext2 = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext2 image and is set to 64k by + default:<screen>IMAGE_ROOTFS_SIZE_ext2 = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext3</term> + + <listitem> + <para>Creates an <emphasis>"Extended Filesystem 3"</emphasis> image + file. This is the standard Linux journaling file system.<screen>IMAGE_CMD_ext3 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \ + -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3 \ + ${EXTRA_IMAGECMD}; \ +tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext3 is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext3 = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext3 image and is set to 64k by + default:<screen>IMAGE_ROOTFS_SIZE_ext3 = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext2.gz</term> + + <listitem> + <para>Creates a version of the ext2 filesystem image compressed with + <command>gzip</command>.</para> + + <para><screen>IMAGE_CMD_ext2.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz && \ +mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ +genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2 \ + ${EXTRA_IMAGECMD}; \ +gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2; \ +mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2.gz \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2.gz; \ +rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext2.gz is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext2.gz = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext2 image and is set to 64k by + default:</para> + + <para><screen>IMAGE_ROOTFS_SIZE_ext2.gz = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>ext3.gz</term> + + <listitem> + <para>Creates a version of the ext3 filesystem image compressed with + <command>gzip</command>.</para> + + <para><screen>IMAGE_CMD_ext3.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz && \ +mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \ +genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3 \ + ${EXTRA_IMAGECMD}; \ +tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \ +gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \ +mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3.gz \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3.gz; \ +rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for ext3.gz is + passed to <command>genext2fs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_ext3.gz = ""</screen></para> + + <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to + specify the size of the ext2 image and is set to 64k by + default:</para> + + <para><screen>IMAGE_ROOTFS_SIZE_ext3.gz = "65536"</screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>squashfs</term> + + <listitem> + <para>Creates a squashfs image. This is a read only compressed + filesystem which is used directly with files uncompressed into RAM + as they are accessed. Files and filesystems may be up to 2^64 bytes + in size, full 32-bit uids and gids are stored, it detects duplicate + files and stores only a single copy, all meta-data is compressed and + big and little endian filesystems can be mounted on any + platform.</para> + + <para>Squashfs uses gzip as its compression method.</para> + + <para><screen>IMAGE_CMD_squashfs = "mksquashfs ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \ + ${EXTRA_IMAGECMD} -noappend"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is + passed to <command>mksquashfs</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_squashfs = ""</screen></para> + + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for squashfs specified + the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs = "-le -b 16384"</emphasis></screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>squashfs-lzma</term> + + <listitem> + <para>Creates a squashfs image using lzma compression instead of + gzip which is the standard squashfs compression type. This is a read + only compressed filesystem which is used directly with files + uncompressed into RAM as they are accessed. Files and filesystems + may be up to 2^64 bytes in size, full 32-bit uids and gids are + stored, it detects duplicate files and stores only a single copy, + all meta-data is compressed and big and little endian filesystems + can be mounted on any platform.</para> + + <para>Squashfs-lzma uses lzma as its compression method.</para> + + <para><screen>IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \ + ${EXTRA_IMAGECMD} -noappend"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is + passed to <command>mksquashfs-lzma</command> and is left empty by + default:<screen>EXTRA_IMAGECMD_squashfs-lzma = ""</screen></para> + + <para>This was not always empty, prior to 2007/05/02 the + <command>EXTRA_IMAGECMD</command> variable for squashfs specified + the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384"</emphasis></screen></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tar</term> + + <listitem> + <para>Creates a .tar archive.</para> + + <para><screen>IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} && \ + tar -cvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar ."</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for tar images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tar.gz</term> + + <listitem> + <para>Creates a <command>gzip</command> compressed .tar + archive.</para> + + <para><screen>IMAGE_CMD_tar.gz = "cd ${IMAGE_ROOTFS} && \ + tar -zcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.gz ."</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for .tar.gz images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>tar.bz2</term> + + <listitem> + <para>Creates a <command>bzip2</command> compressed .tar + archive.</para> + + <para><screen>IMAGE_CMD_tar.bz2 = "cd ${IMAGE_ROOTFS} && \ + tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ."</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for tar.bz2 images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cpio</term> + + <listitem> + <para>Creates a .cpio archive:<screen>IMAGE_CMD_cpio = "cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio)"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for cpio images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>cpio.gz</term> + + <listitem> + <para>Creates a <command>gzip</command> compressed .cpio + archive.<screen>IMAGE_CMD_cpio.gz = cd ${IMAGE_ROOTFS} && \ + (find . | cpio -o -H newc | gzip -c -9 >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio.gz)"</screen></para> + + <para>The <command>EXTRA_IMAGECMD</command> variable in not + supported for cpio.gz images.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The above built in list of image types is defined in the bitbake + configuration file: + <command>org.openembedded.dev/conf/bitbake.conf</command>.</para> + </section> + + <section> + <title>Custom image types</title> + + <para>Custom image types can be created by defining the + <command>IMAGE_CMD</command> variable, and optionally the + <command>EXTRA_IMAGECMD</command>, <command>IMAGE_ROOTFS_SIZE</command> + and <command>IMAGE_DEPENDS</command> variables, for your new image + type.</para> + + <para>An example can be found in + <command>conf/machine/wrt54.conf</command> where it defines a new image + type, <emphasis>squashfs-lzma</emphasis>, for a squashfs filesystem using + lzma compression instead of the standard gzip compression (squashfs-lzma + is now a standard type, but the example still serves to show the + concept):<screen>IMAGE_DEPENDS_squashfs-lzma = "squashfs-tools-native" +IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \ + ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs-lzma \ + ${EXTRA_IMAGECMD} -noappend" +EXTRA_IMAGECMD_squashfs-lzma = "-root-owned -le"</screen></para> + </section> +</section> |