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 variable 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_ROOTFS}, which is usually
tmp/rootfs in your build area. One important difference
between the image 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 are 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 with the
name of the image type appended. The behaviour of the built in image types
can be changed by modifying these variables, and new types created by
defining these variables for the new type.
The variables that define an image type are:
IMAGE_CMD_<type>
Specifies the 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 needing 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 to determine which command these
options are being passed to.
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 --root=${IMAGE_ROOTFS} \
--faketime \
--output=${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.jffs2 \
${EXTRA_IMAGECMD}"
The EXTRA_IMAGECMD variable for jffs2 is
passed to mkfs.jffs2 and by default is used to
enabled pad, 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 uid and guids are support, 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 not used by
default.
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 not used by
default.
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"
ext2.gz
Creates a version of the ext2 filesystem image compressed with
gzip.
IMAGE_CMD_ext2.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 not used by
default.
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"
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 uid 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.
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 by default is used
specify the endianess and block size of the filesystem:
EXTRA_IMAGECMD_squashfs = "-le -b 16384"
tar
Creates a bzip2 compressed .tar
archive.
IMAGE_CMD_tar = "cd ${IMAGE_ROOTFS} && \
tar -jcvf ${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.rootfs.tar.bz2 ."
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.
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: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"