Next Previous Contents

6. The local overlay

So far we have been playing with OE as a user...now it is time to move to the role of a developer by making our own distribution. For this purpose there are two different approaches:

  1. To deal with OE Monotone database: working on the current working copy and making our own OE branch (overwriting files, adding files, and so on).
  2. To make a local overlay: with this approach we would leave untouched the current working copy.

In this guide we are going to use the local overlay technique. A local overlay is a place where you keep your local files, in an OE style setup, leaving untouched the original OE tree. Using a local overlay directory we will be able to add, modify, and to overwrite the original OE tree items, in a simple and clean manner.

6.1 Overlay directory layout

The first step is to recreate the OE tree structure under a local directory, as seen below:

my_OE/
   `-- local
       |-- classes
       |-- conf
       |   |-- distro
       |   |   `-- include
       |   `-- machine
       `-- packages
           |-- images
           `-- tasks

By making the appropriate files keeping the same directory structure, we will have preference over the original openembedded directory structure. Files placed in the local overlay will have preference over the ones in the openembbeded directory, even with identical name.

In order to keep everything under control, it is a good practice to maintain the Makefile front-end and our local overlay under control version (i.e. subversion). In the future, to build the system in a different machine all we will need is the Makefile front-end and the local overlay, hence its importance.

6.2 Our own distribution

It is now time to populate the local overlay with our distribution related files. Ir order to save some work and to avoid reinventing the wheel, it is a good idea to reuse any base files from openembedded metadata, in short:

cp my_OE/openembedded/conf/distro/generic.conf my_OE/local/conf/distro/my_distro.conf
cp my_OE/openembedded/conf/machine/epia.conf my_OE/local/conf/machine/my_distro_epia.conf

On the other side, we have to set up another local file in order OpenEmbedded to take into account this local overlay layout. The following file uses the named BitBake Collections:

my_OE/
   `-- local/
        `- conf/
             `- site.conf

                BBFILES += "${HOME}/my_OE/local/packages/*/*.bb"
                BBFILE_COLLECTIONS = "overlay"
                BBFILE_PATTERN_overlay = "${HOME}/my_OE/local"
                BBFILE_PRIORITY_overlay = 5

We also have to modify the BBPATH environment variable to add the new tree before the other two:

BBPATH="${HOME}/my_OE/local:${HOME}/my_OE/build:${HOME}/my_OE/openembedded"

The final step to complete the local overlay setup is to add our brand new distro and machine to the local.conf file:

MACHINE = "my_distro_epia"
DISTRO = "my_distro"

The global variables defined by all these .conf files are being used by the recipes (*.bb files) and bitbake. We just need a .bb file more, the special .bb file related with the final rootfs layout, in other words, the packages that will be included in the final image of our distribution.

my_OE/
   `-- local
       `-- packages
           `-- images
                `-- mydistro-image.bb


$ cat my_OE/local/packages/images/mydistro-image.bb

# Final filesystem image components definition for MyDistro Distribution.

# base sanity imagen.
require packages/images/bootstrap-image.bb

export IMAGE_INSTALL += " \
                ipkg \
                alsa-utils \
                ppp"

inherit image

export IMAGE_BASENAME = "mydistro-image"

The base set package is defined by openembedded bootstrap-image.bb recipe, what is a base image with minimal sanity set of packages. We will add new packages to this set by means of the mydistro-image.bb file.

To build our image:


$ cd build
$ . ../setup-env
$ bitbake mydistro-image

The output of this command will be:

my_OE/
 `-- build
     `-- tmp
         |-- rootfs/
         `-- deploy
             |- ipk   ==> all ipkg packages for the final image.
             `-- images
                 `-- images
                     `--  mydistro-image-my_distro-epia.cpio -> 
                                mydistro-image-my_distro-epia-20080414123329.rootfs.cpio

6.3 A new package example

The following is a typical example of an OE package, nevertheless we will try to make a useful package for our customization purposes.

The system V boot style of OE is splited into stages. One of these stages is the execution of /etc/init.d/rcS script, this script executes a pre-starting script /sbin/unconfigured.sh. Another stage is a post-starting script /sbin/setup.sh. Both scripts are not included by any OE embedded package.

We could also add ones with the following package:

my_OE/
   `-- local
       `-- packages
           `-- setup 
                |-- files
                |   |-- setup.sh
                |   `-- unconfigured.sh
                `-- setup_0.0.1.bb


$ cat ~/my_OE/local/packages/setup/setup_0.0.1.bb

DESCRIPTION = "Custom setup files unconfigured.sh, setup.sh"
LICENSE = "GPL"
PR = "r1"

SRC_URI =  "file://setup.sh \
            file://unconfigured.sh"

PACKAGES = "${PN}"

FILES_${PN} = "/sbin/* ${sysconfdir}"

do_install () {
        install -d ${D}/sbin
        install -d ${D}/etc
        install -m 0755 ${WORKDIR}/setup.sh ${D}/sbin/setup.sh
        install -m 0755 ${WORKDIR}/unconfigured.sh ${D}/sbin/unconfigured.sh
}

Do not forget to add this new package to our image definition: mydistro-image.bb

...
export IMAGE_INSTALL += " \
                ipkg \
                alsa-utils \
                ppp \
                setup"
...

6.4 Solving package problems

While we have been working with the my_OE example, it is easy to run into problems with packages, problems such as package source URLs obsoletes, packages with old software versions, and so on. When we need to change a package, all we have to do is to copy the openembedded original package into our local overlay and modify it. Bitbake uses the higher package version by default, but bitbake also will use our local overlay package even when it has the same name and version as the original.

6.5 So far ...

A quick look to the directory layout is a good manner to summarize:

my_OE/
 `-- local
        |-- classes
        |-- conf
        |   |-- distro
        |   |   |-- include
        |   |   `-- my_distro.conf
        |   |-- machine
        |   |   `-- my_distro_epia.conf
        |   `-- site.conf
        `-- packages
                |-- images
                |   `-- mydistro-image.bb
                |-- setup
                |   |-- files
                |   |   |-- setup.sh
                |   |   `-- unconfigured.sh
                |   `-- setup_0.0.1.bb
                `-- tasks


Next Previous Contents