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 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
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"