Image types

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 image class section for details on how image generation is configured.

The final root file system will consist of all of the files located in image root filesystem directory, ${IMAGE_ROOTFS}, which is usually tmp/rootfs 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 ${IMAGE_ROOTFS} directory but they will be present in any images that are generated. This is due to fakeroot 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 .tar archive, to ensure you have the correct device nodes and any other special files.

Defining images

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.

The variables that define an image type are:

IMAGE_CMD_<type>

Specifies the actual command that is run to generate an image of the specified type.

EXTRA_IMAGECMD_<type>

Used to pass additional command line arguments to the IMAGE_CMD 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 IMAGE_CMD definition to determine how these options are being used.

IMAGE_ROOTFS_SIZE_<type>

For those image types that generate a fixed size image this variable is used to specify the required image size.

IMAGE_DEPENDS_<type>

Lists the packages that the IMAGE_CMD depends on. As an example the jffs2 filesystem creation depends on mkfs.jffs2 command which is part of the mtd utilities and therefore depends on mtd-utils-native.

Available image types

The following image types are built in to OpenEmbedded:

jffs2

Creates jffs2 "Journaling flash file system 2" images. This is a read/write, compressed filesystem for mtd (flash) devices. It is not supported for block devices.

IMAGE_CMD_jffs2 = "mkfs.jffs2 \
  -x lzo \
  --root=${IMAGE_ROOTFS} \
  --faketime \
  --output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
  ${EXTRA_IMAGECMD}"

The EXTRA_IMAGECMD variable for jffs2 passed to mkfs.jffs2 and is left empty by default:

EXTRA_IMAGECMD_jffs2 = ""

This was not always empty, prior to 2007/05/02 the EXTRA_IMAGECMD variable for jffs2 was set to enable padding, to define the endianess and to specify the block size:

EXTRA_IMAGECMD_jffs2 = "--pad --little-endian --eraseblock=0x40000"
cramfs

Creates cramfs "Compression ROM file system" 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.

IMAGE_CMD_cramfs = "mkcramfs ${IMAGE_ROOTFS} \
  ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cramfs \
  ${EXTRA_IMAGECMD}"

The EXTRA_IMAGECMD variable for cramfs is passed to mkcramfs and is left empty by default:

EXTRA_IMAGECMD_cramfs = ""
ext2

Creates an "Extended Filesystem 2" image file. This is the standard Linux non-journaling file system.

IMAGE_CMD_ext2 = "genext2fs -b ${IMAGE_ROOTFS_SIZE} \
  -d ${IMAGE_ROOTFS} \
  ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.ext2 \
  ${EXTRA_IMAGECMD}"

The EXTRA_IMAGECMD variable for ext2 is passed to genext2fs and is left empty by default:

EXTRA_IMAGECMD_ext2 = ""

The IMAGE_ROOTS_SIZE variable is used to specify the size of the ext2 image and is set to 64k by default:

IMAGE_ROOTFS_SIZE_ext2 = "65536"
ext3

Creates an "Extended Filesystem 3" image file. This is the standard Linux journaling file system.

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"

The EXTRA_IMAGECMD variable for ext3 is passed to genext2fs and is left empty by default:

EXTRA_IMAGECMD_ext3 = ""

The IMAGE_ROOTS_SIZE variable is used to specify the size of the ext3 image and is set to 64k by default:

IMAGE_ROOTFS_SIZE_ext3 = "65536"
ext2.gz

Creates a version of the ext2 filesystem image compressed with gzip.

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"

The EXTRA_IMAGECMD variable for ext2.gz is passed to genext2fs and is left empty by default:

EXTRA_IMAGECMD_ext2.gz = ""

The IMAGE_ROOTS_SIZE variable is used to specify the size of the ext2 image and is set to 64k by default:

IMAGE_ROOTFS_SIZE_ext2.gz = "65536"
ext3.gz

Creates a version of the ext3 filesystem image compressed with gzip.

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"

The EXTRA_IMAGECMD variable for ext3.gz is passed to genext2fs and is left empty by default:

EXTRA_IMAGECMD_ext3.gz = ""

The IMAGE_ROOTS_SIZE variable is used to specify the size of the ext2 image and is set to 64k by default:

IMAGE_ROOTFS_SIZE_ext3.gz = "65536"
squashfs

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.

Squashfs uses gzip as its compression method.

IMAGE_CMD_squashfs = "mksquashfs ${IMAGE_ROOTFS} \
  ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \
  ${EXTRA_IMAGECMD} -noappend"

The EXTRA_IMAGECMD variable for squashfs is passed to mksquashfs and is left empty by default:

EXTRA_IMAGECMD_squashfs = ""

This was not always empty, prior to 2007/05/02 the EXTRA_IMAGECMD variable for squashfs specified the endianess and block size of the filesystem:

EXTRA_IMAGECMD_squashfs = "-le -b 16384"
squashfs-lzma

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.

Squashfs-lzma uses lzma as its compression method.

IMAGE_CMD_squashfs-lzma = "mksquashfs-lzma ${IMAGE_ROOTFS} \
  ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.squashfs \
  ${EXTRA_IMAGECMD} -noappend"

The EXTRA_IMAGECMD variable for squashfs is passed to mksquashfs-lzma and is left empty by default:

EXTRA_IMAGECMD_squashfs-lzma = ""

This was not always empty, prior to 2007/05/02 the EXTRA_IMAGECMD variable for squashfs specified the endianess and block size of the filesystem:

EXTRA_IMAGECMD_squashfs-lzma = "-le -b 16384"
tar

Creates a .tar archive.

IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} && \
  tar -cvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar ."

The EXTRA_IMAGECMD variable in not supported for tar images.

tar.gz

Creates a gzip compressed .tar archive.

IMAGE_CMD_tar.gz = "cd ${IMAGE_ROOTFS} && \
  tar -zcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.gz ."

The EXTRA_IMAGECMD variable in not supported for .tar.gz images.

tar.bz2

Creates a bzip2 compressed .tar archive.

IMAGE_CMD_tar.bz2 = "cd ${IMAGE_ROOTFS} && \
  tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ."

The EXTRA_IMAGECMD variable in not supported for tar.bz2 images.

cpio

Creates a .cpio archive:

IMAGE_CMD_cpio = "cd ${IMAGE_ROOTFS} && \
  (find . | cpio -o -H newc >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio)"

The EXTRA_IMAGECMD variable in not supported for cpio images.

cpio.gz

Creates a gzip compressed .cpio archive.

IMAGE_CMD_cpio.gz = cd ${IMAGE_ROOTFS} && \
  (find . | cpio -o -H newc | gzip -c -9 >${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.cpio.gz)"

The EXTRA_IMAGECMD variable in not supported for cpio.gz images.

The above built in list of image types is defined in the bitbake configuration file: org.openembedded.dev/conf/bitbake.conf.

Custom image types

Custom image types can be created by defining the IMAGE_CMD variable, and optionally the EXTRA_IMAGECMD, IMAGE_ROOTFS_SIZE and IMAGE_DEPENDS variables, for your new image type.

An example can be found in conf/machine/wrt54.conf where it defines a new image type, squashfs-lzma, 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):

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"