path: root/docs/usermanual/reference/image_types.xml

<?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/${PN}</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_&lt;type&gt;</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_&lt;type&gt;</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_&lt;type&gt;</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_&lt;type&gt;</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 &amp;&amp; \
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 &amp;&amp; \
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} &amp;&amp; \
  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} &amp;&amp; \
  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} &amp;&amp; \
  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} &amp;&amp; \
  (find . | cpio -o -H newc &gt;${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} &amp;&amp; \
  (find . | cpio -o -H newc | gzip -c -9 &gt;${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>