OpenEmbedded is a flexible, capable build tool. There is, however, a lot to know in order to fully exploit its power. A good way to learn how it works is to explore its directory layout.

After setting up your build environment, your directory structure should look like this:

gumstix-oe
|-bitbake
|-build
|-org.openembedded.snapshot
|-com.gumstix.collection
|-user.collection
|-extras
`-tmp

bitbake

OpenEmbedded is based upon bitbake, a tool for executing tasks and managing metadata. This directory contains the bitbake tool and its associated configuration files.

build

The build directory contains configuration data for the build system. The configuration is split between three files, all of them in build/conf: auto.conf, local.conf, and site.conf.

auto.conf is used primarily to specify what machine configuration the build is targeted toward.

local.conf is used to specify build policy (uclibc vs glibc, debug vs release, etc)

site.conf is used for general configuration (location of source code cache, location of temporary file directory, environment set up, parallel make, etc)

org.openembedded.snapshot

This directory contains a snapshot of the OpenEmbedded development branch. It contains the "recipes" to build many hundreds of software packages.

NOTE: You should never edit files in this directory. You should use the bitbake collection feature and place your overrides in user.collection

com.gumstix.collection

This directory contains overrides to the standard OpenEmbedded recipes. This is where all of the gumstix specific customizations reside. Bitbake will give preference to recipes that it finds here over recipes contained in org.openembedded.snapshot.

NOTE: You should never edit files in this directory. You should use the bitbake collection feature and place your overrides in user.collection

user.collection

This directory is yours to use! You should place your custom recipes here and also any overrides to recipes contained in com.gumstix.collection or org.openembedded.snapshot. Bitbake gives highest preference to the recipes in this directory, making it possible for you to override any functionality without having to touch directories under Gumstix source code control.

It is highly recommended that you place this directory under your own source code control.

extras

The contents of this directory are not really part of the OpenEmbedded build system. It contains a variety of useful, related material: a kermit init script, suggested environment setup, autobuilder scripts, and setup files for jtag tools.

 

tmp

This is where the build system keeps its working files and also where it places the output of the build. There's a lot going on here, so let's look at the top layer of th edirectory structure under tmp:

tmp
|-cache
|-stamps
|-cross
|-staging
|-work
|-rootfs
`-deploy

cache

This is where bitbake caches information it obtains from parsing all available .bb files. You will normally not need to look in this directory.

stamps

This directory contains zero length files that are used to track each phase of the build as it is completed. You will normally not need to look in this directory.

cross

This directory contains the cross development tools for generating code for the gumstix procesor (compliers, linkers, etc.)

staging

Header files, libraries, and other items needed by the build system are stored in this directory.

work

This appropriately named directory is where the real work gets done! You won't normally need to look here, but knowing about its contents will give you better insight into how OpenEmedded works. It is also *the* place to look when you are trying to figure out why your new recipe isn't quite working as you intended.

A subdirectory is created for each package that is built. Let's look at the cron package as an example (the following assumes a uclibc build). Since cron is not a machine dependent package (I.e. it will run on any arm based uclibc system) the cron working directory is created in the armv5te-angstrom-linux-uclibcgnueabi/ subdirectory, and with it's version information appended will be named cron-3.0pl1-r8.

There will typically be several subdirectories in each package working directory, let's look at each of them:

cron-3.0pl1

This is where the downloaded source code is expanded and patched. It will typically contain the source code for the package as well as any associated make files and documentation.

install

This is where the build system places the files which will be packaged into ipkg files. There will typically be several subdirectories here, one for each ipkg that the recipe creates.

The contents of each of these subdirectories is a root based tree of files exactly as they are to be installed in the target system. For the cron package you will find etc, usr, and var subdirectories containing all of the cron binaries and configuration files. When debugging a recipe, this is the place to look to verify that the right files are getting installed in the right places.

tmp

This directory contains the scripts used to build the package and also the log files generated during the build process for the package. This is an extremely valuable debugging resource when you need to see exactly what the build system is doing.

image

There is normally no reason to look in this directory. It will contain the directory structure for the package installation, but without the actual files.

rootfs

After an image recipe build this directory will contain the complete root file system for the image. This directory is suitable for nfs mounting.

deploy

This directory contains the final output of the build process: a set of images and ipkg files. The files are organized intuitively:

For uclibc builds, images are under uclib/images, ipkg files are under uclibc/ipk

For glibc builds, images are under glib/images, ipkg files are under glibc/ipk