docs/usermanual/reference/image_types.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <section id="image_types" xreflabel="image types">
   3   <title>Image types</title>
   4
   5   <para>One of the most commonly used outputs from a build is a filesystem
   6   image containing the root filesystem for the target device. There are
   7   several variables which can be used to control the type of output images and
   8   the settings for those images, such as endianess or compression ratios. This
   9   section details the available images and the variables that effect them. See
  10   the <xref linkend="image_class" /> section for details on how image
  11   generation is configured.</para>
  12
  13   <para>The final root file system will consist of all of the files located in
  14   image root filesystem directory, <command>${IMAGE_ROOTFS}</command>, which
  15   is usually <command>tmp/rootfs</command> in the build area. One important
  16   difference between the images and the root file system directory is that any
  17   files which can only be created by privileged users, such as device nodes,
  18   will not appear in the <command>${IMAGE_ROOTFS}</command> directory but they
  19   will be present in any images that are generated. This is due to
  20   <emphasis><xref linkend="fakeroot" /> </emphasis>system keeping track of
  21   these special files and making them available when generating the image -
  22   even though they do not appear in the root filesystem directory. For this
  23   reason it is important to always create an actual image to use for testing,
  24   even if it's just a <command>.tar</command> archive, to ensure you have the
  25   correct device nodes and any other special files.</para>
  26
  27   <section>
  28     <title>Defining images</title>
  29
  30     <para>Each supported image type is defined via a set of variables. Each
  31     variables has the name of the image type appended to indicate the settings
  32     for that particular image type. The behaviour of the built in image types
  33     can be changed by modifying these variables, and new types can be created
  34     by defining these variables for the new type.</para>
  35
  36     <para>The variables that define an image type are:</para>
  37
  38     <variablelist>
  39       <varlistentry>
  40         <term>IMAGE_CMD_&lt;type&gt;</term>
  41
  42         <listitem>
  43           <para>Specifies the actual command that is run to generate an image
  44           of the specified type.</para>
  45         </listitem>
  46       </varlistentry>
  47
  48       <varlistentry>
  49         <term>EXTRA_IMAGECMD_&lt;type&gt;</term>
  50
  51         <listitem>
  52           <para>Used to pass additional command line arguments to the
  53           <command>IMAGE_CMD</command> without the need to redefine the entire
  54           image command. This is often used to pass options such as endianess
  55           and compression rations. You need to look at the
  56           <command>IMAGE_CMD</command> definition to determine how these
  57           options are being used.</para>
  58         </listitem>
  59       </varlistentry>
  60
  61       <varlistentry>
  62         <term>IMAGE_ROOTFS_SIZE_&lt;type&gt;</term>
  63
  64         <listitem>
  65           <para>For those image types that generate a fixed size image this
  66           variable is used to specify the required image size.</para>
  67         </listitem>
  68       </varlistentry>
  69
  70       <varlistentry>
  71         <term>IMAGE_DEPENDS_&lt;type&gt;</term>
  72
  73         <listitem>
  74           <para>Lists the packages that the <command>IMAGE_CMD</command>
  75           depends on. As an example the jffs2 filesystem creation depends on
  76           <command>mkfs.jffs2</command> command which is part of the mtd
  77           utilities and therefore depends on mtd-utils-native.</para>
  78         </listitem>
  79       </varlistentry>
  80     </variablelist>
  81   </section>
  82
  83   <section>
  84     <title>Available image types</title>
  85
  86     <para>The following image types are built in to OpenEmbedded:</para>
  87
  88     <variablelist>
  89       <varlistentry>
  90         <term>jffs2</term>
  91
  92         <listitem>
  93           <para>Creates jffs2 <emphasis>"Journaling flash file system
  94           2"</emphasis> images. This is a read/write, compressed filesystem
  95           for mtd (flash) devices. It is not supported for block
  96           devices.<screen>IMAGE_CMD_jffs2 = "mkfs.jffs2 \
  97   -x lzo \
  98   --root=${IMAGE_ROOTFS} \
  99   --faketime \
 100   --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
 101   ${EXTRA_IMAGECMD}"</screen></para>
 102
 103           <para>The <command>EXTRA_IMAGECMD</command> variable for jffs2
 104           passed to <command>mkfs.jffs2</command> and is left empty by
 105           default:<screen>EXTRA_IMAGECMD_jffs2 = ""</screen></para>
 106
 107           <para>This was not always empty, prior to 2007/05/02 the
 108           <command>EXTRA_IMAGECMD</command> variable for jffs2 was set to
 109           enable padding, to define the endianess and to specify the block
 110           size:<screen><emphasis>EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000"</emphasis></screen></para>
 111         </listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term>cramfs</term>
 116
 117         <listitem>
 118           <para>Creates cramfs <emphasis>"Compression ROM file
 119           system"</emphasis> images. This is a read only compressed filesystem
 120           which is used directly by decompressing files into RAM as they are
 121           accessed. Files sizes are limited to 16MB, file system size is
 122           limited to 256MB, only 8-bit uids and gids are supported, no hard
 123           links are supported and no time stamps are supported.<screen>IMAGE_CMD_cramfs = "mkcramfs ${IMAGE_ROOTFS} \
 124   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cramfs \
 125   ${EXTRA_IMAGECMD}"</screen></para>
 126
 127           <para>The <command>EXTRA_IMAGECMD</command> variable for cramfs is
 128           passed to <command>mkcramfs</command> and is left empty by
 129           default:<screen>EXTRA_IMAGECMD_cramfs = ""</screen></para>
 130         </listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term>ext2</term>
 135
 136         <listitem>
 137           <para>Creates an <emphasis>"Extended Filesystem 2"</emphasis> image
 138           file. This is the standard Linux non-journaling file system.<screen>IMAGE_CMD_ext2 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \
 139   -d ${IMAGE_ROOTFS} \
 140   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2 \
 141   ${EXTRA_IMAGECMD}"</screen></para>
 142
 143           <para>The <command>EXTRA_IMAGECMD</command> variable for ext2 is
 144           passed to <command>genext2fs</command> and is left empty by
 145           default:<screen>EXTRA_IMAGECMD_ext2 = ""</screen></para>
 146
 147           <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
 148           specify the size of the ext2 image and is set to 64k by
 149           default:<screen>IMAGE_ROOTFS_SIZE_ext2 = "65536"</screen></para>
 150         </listitem>
 151       </varlistentry>
 152
 153       <varlistentry>
 154         <term>ext3</term>
 155
 156         <listitem>
 157           <para>Creates an <emphasis>"Extended Filesystem 3"</emphasis> image
 158           file. This is the standard Linux journaling file system.<screen>IMAGE_CMD_ext3 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \
 159   -d ${IMAGE_ROOTFS} \
 160   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3 \
 161   ${EXTRA_IMAGECMD}; \
 162 tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3"</screen></para>
 163
 164           <para>The <command>EXTRA_IMAGECMD</command> variable for ext3 is
 165           passed to <command>genext2fs</command> and is left empty by
 166           default:<screen>EXTRA_IMAGECMD_ext3 = ""</screen></para>
 167
 168           <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
 169           specify the size of the ext3 image and is set to 64k by
 170           default:<screen>IMAGE_ROOTFS_SIZE_ext3 = "65536"</screen></para>
 171         </listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term>ext2.gz</term>
 176
 177         <listitem>
 178           <para>Creates a version of the ext2 filesystem image compressed with
 179           <command>gzip</command>.</para>
 180
 181           <para><screen>IMAGE_CMD_ext2.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz &amp;&amp; \
 182 mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \
 183 genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \
 184   ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2 \
 185   ${EXTRA_IMAGECMD}; \
 186 gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2; \
 187 mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext2.gz \
 188   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2.gz; \
 189 rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para>
 190
 191           <para>The <command>EXTRA_IMAGECMD</command> variable for ext2.gz is
 192           passed to <command>genext2fs</command> and is left empty by
 193           default:<screen>EXTRA_IMAGECMD_ext2.gz = ""</screen></para>
 194
 195           <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
 196           specify the size of the ext2 image and is set to 64k by
 197           default:</para>
 198
 199           <para><screen>IMAGE_ROOTFS_SIZE_ext2.gz = "65536"</screen></para>
 200         </listitem>
 201       </varlistentry>
 202
 203       <varlistentry>
 204         <term>ext3.gz</term>
 205
 206         <listitem>
 207           <para>Creates a version of the ext3 filesystem image compressed with
 208           <command>gzip</command>.</para>
 209
 210           <para><screen>IMAGE_CMD_ext3.gz = "rm -rf ${DEPLOY_DIR_IMAGE}/tmp.gz &amp;&amp; \
 211 mkdir ${DEPLOY_DIR_IMAGE}/tmp.gz; \
 212 genext2fs -b ${IMAGE_ROOTFS_SIZE} -d ${IMAGE_ROOTFS} \
 213   ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3 \
 214   ${EXTRA_IMAGECMD}; \
 215 tune2fs -j ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \
 216 gzip -f -9 ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3; \
 217 mv ${DEPLOY_DIR_IMAGE}/tmp.gz/${IMAGE_NAME}.rootfs.ext3.gz \
 218   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext3.gz; \
 219 rmdir ${DEPLOY_DIR_IMAGE}/tmp.gz"</screen></para>
 220
 221           <para>The <command>EXTRA_IMAGECMD</command> variable for ext3.gz is
 222           passed to <command>genext2fs</command> and is left empty by
 223           default:<screen>EXTRA_IMAGECMD_ext3.gz = ""</screen></para>
 224
 225           <para>The <command>IMAGE_ROOTS_SIZE</command> variable is used to
 226           specify the size of the ext2 image and is set to 64k by
 227           default:</para>
 228
 229           <para><screen>IMAGE_ROOTFS_SIZE_ext3.gz = "65536"</screen></para>
 230         </listitem>
 231       </varlistentry>
 232
 233       <varlistentry>
 234         <term>squashfs</term>
 235
 236         <listitem>
 237           <para>Creates a squashfs image. This is a read only compressed
 238           filesystem which is used directly with files uncompressed into RAM
 239           as they are accessed. Files and filesystems may be up to 2^64 bytes
 240           in size, full 32-bit uids and gids are stored, it detects duplicate
 241           files and stores only a single copy, all meta-data is compressed and
 242           big and little endian filesystems can be mounted on any
 243           platform.</para>
 244
 245           <para>Squashfs uses gzip as its compression method.</para>
 246
 247           <para><screen>IMAGE_CMD_squashfs = "mksquashfs ${IMAGE_ROOTFS} \
 248   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \
 249   ${EXTRA_IMAGECMD} -noappend"</screen></para>
 250
 251           <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is
 252           passed to <command>mksquashfs</command> and is left empty by
 253           default:<screen>EXTRA_IMAGECMD_squashfs = ""</screen></para>
 254
 255           <para>This was not always empty, prior to 2007/05/02 the
 256           <command>EXTRA_IMAGECMD</command> variable for squashfs specified
 257           the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs = "-le -b 16384"</emphasis></screen></para>
 258         </listitem>
 259       </varlistentry>
 260
 261       <varlistentry>
 262         <term>squashfs-lzma</term>
 263
 264         <listitem>
 265           <para>Creates a squashfs image using lzma compression instead of
 266           gzip which is the standard squashfs compression type. This is a read
 267           only compressed filesystem which is used directly with files
 268           uncompressed into RAM as they are accessed. Files and filesystems
 269           may be up to 2^64 bytes in size, full 32-bit uids and gids are
 270           stored, it detects duplicate files and stores only a single copy,
 271           all meta-data is compressed and big and little endian filesystems
 272           can be mounted on any platform.</para>
 273
 274           <para>Squashfs-lzma uses lzma as its compression method.</para>
 275
 276           <para><screen>IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \
 277   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \
 278   ${EXTRA_IMAGECMD} -noappend"</screen></para>
 279
 280           <para>The <command>EXTRA_IMAGECMD</command> variable for squashfs is
 281           passed to <command>mksquashfs-lzma</command> and is left empty by
 282           default:<screen>EXTRA_IMAGECMD_squashfs-lzma = ""</screen></para>
 283
 284           <para>This was not always empty, prior to 2007/05/02 the
 285           <command>EXTRA_IMAGECMD</command> variable for squashfs specified
 286           the endianess and block size of the filesystem:<screen><emphasis>EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384"</emphasis></screen></para>
 287         </listitem>
 288       </varlistentry>
 289
 290       <varlistentry>
 291         <term>tar</term>
 292
 293         <listitem>
 294           <para>Creates a .tar archive.</para>
 295
 296           <para><screen>IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} &amp;&amp; \
 297   tar -cvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar ."</screen></para>
 298
 299           <para>The <command>EXTRA_IMAGECMD</command> variable in not
 300           supported for tar images.</para>
 301         </listitem>
 302       </varlistentry>
 303
 304       <varlistentry>
 305         <term>tar.gz</term>
 306
 307         <listitem>
 308           <para>Creates a <command>gzip</command> compressed .tar
 309           archive.</para>
 310
 311           <para><screen>IMAGE_CMD_tar.gz = "cd ${IMAGE_ROOTFS} &amp;&amp; \
 312   tar -zcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.gz ."</screen></para>
 313
 314           <para>The <command>EXTRA_IMAGECMD</command> variable in not
 315           supported for .tar.gz images.</para>
 316         </listitem>
 317       </varlistentry>
 318
 319       <varlistentry>
 320         <term>tar.bz2</term>
 321
 322         <listitem>
 323           <para>Creates a <command>bzip2</command> compressed .tar
 324           archive.</para>
 325
 326           <para><screen>IMAGE_CMD_tar.bz2 = "cd ${IMAGE_ROOTFS} &amp;&amp; \
 327   tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ."</screen></para>
 328
 329           <para>The <command>EXTRA_IMAGECMD</command> variable in not
 330           supported for tar.bz2 images.</para>
 331         </listitem>
 332       </varlistentry>
 333
 334       <varlistentry>
 335         <term>cpio</term>
 336
 337         <listitem>
 338           <para>Creates a .cpio archive:<screen>IMAGE_CMD_cpio = "cd ${IMAGE_ROOTFS} &amp;&amp; \
 339   (find . | cpio -o -H newc &gt;${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio)"</screen></para>
 340
 341           <para>The <command>EXTRA_IMAGECMD</command> variable in not
 342           supported for cpio images.</para>
 343         </listitem>
 344       </varlistentry>
 345
 346       <varlistentry>
 347         <term>cpio.gz</term>
 348
 349         <listitem>
 350           <para>Creates a <command>gzip</command> compressed .cpio
 351           archive.<screen>IMAGE_CMD_cpio.gz = cd ${IMAGE_ROOTFS} &amp;&amp; \
 352   (find . | cpio -o -H newc | gzip -c -9 &gt;${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio.gz)"</screen></para>
 353
 354           <para>The <command>EXTRA_IMAGECMD</command> variable in not
 355           supported for cpio.gz images.</para>
 356         </listitem>
 357       </varlistentry>
 358     </variablelist>
 359
 360     <para>The above built in list of image types is defined in the bitbake
 361     configuration file:
 362     <command>org.openembedded.dev/conf/bitbake.conf</command>.</para>
 363   </section>
 364
 365   <section>
 366     <title>Custom image types</title>
 367
 368     <para>Custom image types can be created by defining the
 369     <command>IMAGE_CMD</command> variable, and optionally the
 370     <command>EXTRA_IMAGECMD</command>, <command>IMAGE_ROOTFS_SIZE</command>
 371     and <command>IMAGE_DEPENDS</command> variables, for your new image
 372     type.</para>
 373
 374     <para>An example can be found in
 375     <command>conf/machine/wrt54.conf</command> where it defines a new image
 376     type, <emphasis>squashfs-lzma</emphasis>, for a squashfs filesystem using
 377     lzma compression instead of the standard gzip compression (squashfs-lzma
 378     is now a standard type, but the example still serves to show the
 379     concept):<screen>IMAGE_DEPENDS_squashfs-lzma = "squashfs-tools-native"
 380 IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \
 381   ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs-lzma \
 382   ${EXTRA_IMAGECMD} -noappend"
 383 EXTRA_IMAGECMD_squashfs-lzma = "-root-owned -le"</screen></para>
 384   </section>
 385 </section>