image class

The image class is used to generate filesystem images containing a root filesystem, as generated by the rootfs class for the package type, such as rootfs_ipkg class, for use on the target device. This could be a jffs2 image which is to be written directly into the flash on the target device for example. In addition this class also configures the ipkg feeds (where to get updates from) and is able to generate multiple different image types.

Summary of the actions performed by the image_ipkg class:

  1. Inherits the rootfs class for the appropriate package type, typically rootfs_ipkg class, in order to bring in the functionality required to generate a root filesystem image. The root filesystem image is generate from a set of of packages (typically .ipkg packages), and then the required images are generated using the contents of the root filesystem;

  2. Sets BUILD_ALL_DEPS = "1" to force the dependency system to build all packages that are listed in the RDEPENDS and/or RRECOMENDS of the packages to be installed;

  3. Determines the name of the image device tables or table (IMAGE_DEVICE_TABLES/IMAGE_DEVICE_TABLE) which will be used to describe the device nodes to create in /dev directory in the root filesystem;

  4. Erases the contents of any existing root filesystem image, ${IMAGE_ROOTFS};

  5. If devfs is not being used then the /dev directory, ${IMAGE_ROOTFS}/dev, will be created and then populated with the device nodes described by the image device table or tables (using "makedevs -r ${IMAGE_ROOTFS} -D " for each device table);

  6. Calls into rootfs_ipkg class to install all of the required packages into the root filesystem;

  7. Configures the ipkg feed information in the root filesystem (using FEED_URIS and FEED_DEPLOYDIR_BASE_URI);

  8. Runs any image pre-processing commands as specified via ${IMAGE_PREPROCESS_COMMAND};

  9. Calls bbimage on the root filesystem for each required image type, as specified via ${IMAGE_FSTYPES}, to generate the actual filesystem images;

  10. Runs any image post-processing commands, as specified via ${IMAGE_POSTPROCESS_COMMAND}.

  11. The following variables may be used to control some of the behaviour of this class (remember we use rootfs_ipkg class to build the filesystem image, so look at the variables defined by that class as well):

    USE_DEVFS

    Indicates if the image will be using devfs, the device filesystem, or not. If devfs is being used then no /dev directory will be required in the image. Set to "1" to indicate that devfs is being used. Note that devfs has been removed from the Linux kernel in the 2.6 series and most platforms are moving towards the use of udev as a replacement for devfs.

    Default: "0"

    IMAGE_DEVICE_TABLES

    Specifies one, or more, files containing a list of the device nodes that should be created in the /dev directory of the image. Each file is searched for via the ${BBPATH} and therefore can be specified as a file relative to the top of the build. Device files are processed in the specified order. NOTE: If IMAGE_DEVICE_TABLE is set then this variable is ignored.

    Example: IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci.txt device_table_add-sm.txt"

    Default: "files/device_table-minimal.txt"

    IMAGE_DEVICE_TABLE

    Specifies the file that lists the device nodes that should be created in the /dev directory of the image. This needs to be an absolute filename and so should be specified relative to ${BBPATH}. Only a single device table is supported. Use IMAGE_DEVICE_TABLES instead if you want to use multiple device tables.

    Default: ""

    IMAGE_PREPROCESS_COMMAND

    Additional commands to run prior to processing the image. Note that these command run within the same fakeroot instance as the rest of this class.

    Default: ""

    IMAGE_POSTPROCESS_COMMAND

    Additional commands to run after processing the image. Note that these command run within the same fakeroot instance as the rest of this class.

    Default: ""

    IMAGE_FSTYPES

    Specifies the type of image files to create. The supported image types, and details on modifying existing types and on creating new types, are described in the image types section. This variable is set to a space seperated list of image types to generate.

    Example: "jffs2 tar.gz"

    Default: "jffs2"

    FEED_URIS

    The name of the feeds to be configured in the image by default. Each entry consists of the feed name, followed by two pound signs and then followed by the actual feed URI.

    Example: FEED_URIS = "example##http://dist.example.com/ipkg-titan-glibc/"

    Default: ""

    FEED_DEPLOYDIR_BASE_URI

    If set, configures local testing feeds using OE package deploy dir contents. The value is URL, corresponding to the ipk deploy dir.

    Example: FEED_DEPLOYDIR_BASE_URI = "http://192.168.2.200/bogofeed/"

    Default: ""

    Special node handling (fakeroot)

    Special nodes, such as /dev nodes, and files with special permissions, such as suid files, are handled via the fakeroot system. This means that when you view the contents of the root filesystem these device appear to be created incorrectly:

    The IMAGE_PREPROCESS_COMMAND and IMAGE_POSTPROCESS_COMMAND variables will be processed within the same fakeroot instance as the rest of the rest of this class.

    Device (/dev) nodes

    There are two variables that can be defined for creating device nodes. The new method supports multiple device node tables and supports searching for these tables via the ${BBPATH} so that relative file names may be used.

    The following example from machine/titan.conf shows the use of multiple device tables:

    # Add the SCI devices to minimal /dev
    IMAGE_DEVICE_TABLES = "files/device_table-minimal.txt files/device_table_add-sci.txt device_table_add-sm.txt"
    

    It uses the standard minimal device tables but adds some additional items which are not normally needed:

    files/device_table-minimal.txt

    This is the standard minimal set of device nodes.

    files/device_table_add-sci.txt

    This contains details for creating the /dev/SC{0,1,2} nodes which are required for the SH processors on board SCI and SCIF serial ports. On the titan hardware the serial console is provided via one of these ports and so we require the device node to be present.

    device_table_add-sm.txt

    This contains details for creating the /dev/sm0 and /dev/sm0p{0,1,2} devices nodes for the block driver, and the associated partitions, that are used to manage the on board flash on the titan hardware.

    Prior to support for multiple device tables this would have required the creation of a titan specific device table.

    Image types

    The type of filesystem images to create are specified via the IMAGE_FSTYPES variable. A full description of the available image types, options of the images and details on creating new image types is provided in the image types section.

    Package feeds

    "Package feed", or feed for short, is a term used by ipkg package manager, commonly used in embedded systems, to name a package repository holding packages. Structurally, a feed is a directory - local, or on HTTP of FTP server, - holding packages and package descriptor file, named Packages or Packages.gz if compressed. Multiple feeds are supported.

    OpenEmbedded has support to pre-configure feeds within generated images, so once image is installed on a device, user can immediately install new software, without the need to manually edit config files. There are several ways to pre-configure feed support, described below.

    Method 1: Using existing feed

    If you already have the feed(s) set up and available via specific URL, they can be added to the image using FEED_URIS variable:

    FEED_URIS = " \
            base##http://oe.example.com/releases/${DISTRO_VERSION}/feed/base \
            updates##http://oe.example.com/releases/${DISTRO_VERSION}/feed/updates"

    FEED_URIS contains list of feed descriptors, separated by spaces, per OE conventions. Each descriptor consists of feed name and feed URL, joined with "##". Feed name is an identifier used by ipkg to distinguish among the feeds. It can be arbitrary, just useful to the users to understood which feed is used for one or another action.

    Method 2: Using OE deploy directory as a feed (development only)

    OE internally maintains a feed-like collection of directories to create images from packages. This package deployment directory however has structure internal to OE and subject to change without notice. Thus, using it as feed directly is not recommended (distributions which ignored this recommendation are known to have their feeds broken when OE upgraded its internal mechanisms).

    However, using deploy directory as feed directly may be beneficial during development and testing, as it allows developers to easily install newly built packages without many manual actions. To facilitate this, OE offers a way to prepare feed configs for using deploy dir as such. To start with this, you first need to configure local HTTP server to export a package deployment directory via HTTP. Suppose you will export it via URL "http://192.168.2.200/bogofeed" (where 192.168.2.200 is the address which will be reachable from the device). Add the following to your local.conf:

    FEED_DEPLOYDIR_BASE_URI = "http://192.168.2.200/bogofeed"
    

    Now you need to setup local HTTP server to actually export that directory. For Apache it can be:

     
    Alias /bogofeed ${DEPLOY_DIR} 
     
    
        Options Indexes FollowSymLinks
        Order deny,allow
        Allow from 192.168.2.0/24
    
    
    

    Replace ${DEPLOY_DIR} with the full path of deploy directory (last components of its path will be deploy/ipk).

    Now, every image built will automatically contain feed configs for the deploy directory (as of time of writing, deploy directory is internally structured with per-arch subdirectories; so, there several feed configs are being generated, one for each subdirectory).

    Prev Up Next
    fakeroot (device node handling) HomeImage types