3. Setting up the working environment

3.1 Downloading

The first step consists of downloading the two key pieces in a working directory. Nevertheless, before that, it is a good moment to get our host environment ready. In order to use OE there are some tools that must be installed in your system. A comprehensive list can be found at the OE site required software.

Setting up Bitbake

At the time of this writing the current stable version is pointed out by the subversion tag bitbake-1.8.10. As Bitbake is written in Python, we just need to to download it to have it ready to use (as long as we have properly set the system PATH that makes bitbake accessible), see section 'Setting up the final environment' to learn how to do it properly.

$ mkdir my_OE; cd my_OE
$ svn co http://svn.berlios.de/svnroot/repos/bitbake/tags/bitbake-1.8.10 bitbake

Setting up OE

Setting up OpenEmbedded is a little less straightforward. The OpenEmbedded team maintains the OE metadata database in a Monotone repository. Note: Monotone is a version control system cataloged as distributed version control, such as Git, Mercurial or GNU arch.

Distributed revision control systems take a peer-to-peer approach, unlike the client-server approach of centralized systems. Rather than having a single, central repository, each user takes a copy of the whole repository, creating a distributed set of repositories. These repositories must be synchronized in order to share and merge elements.

3.2 Monotone versioning

We have to download an OE database snapshot from the OpenEmbedded site and uncompress it, but before that we have to deal with the monotone version installed in our host system. Some monotone versions differ in their database format, therefore we have to check the available snapshots and download the one that matches our monotone software version.

First of all we have to identify the mtn version. Secondly, we have to download the right OE database, and finally we will uncompress the database:

(always within of working directory)
$ mtn --version
monotone 0.36 (base revision: c1757f6cde49bddd77c82580059105bc470145b2) 
$ wget -c -O OE.mtn.bz2 http://www.openembedded.org/snapshots/OE-this-is-for-mtn-0.36.mtn.bz2
$ bunzip2 -d OE.mtn.bz2

Note: if the mtn tool installed in our system does not match with any of the OE databases, we will use the following one: http://www.openembedded.org/snapshots/OE.mtn.bz2

All the previous steps have been done within the working directory. Therefore the directory contents are (so far):

my_OE/
|-- OE.mtn
`-- bitbake/

3.3 Minimal contact with Monotone

We are ready to face the OE database, but before that, it will be necessary to learn some Monotone commands and concepts. Note: Monotone is out of the scope of this document, therefore we will learn the minimal set of commands necessary to extract the metadata.

As almost every other version control repositories, the database contains different branches of development, being some of them:

The full list of branches can be reached at OE branches.

The OE database downloaded is just a snapshot, so the content will be out of date. For this reason we must update out the repository's local database for some branch (in this example we will work with the org.openemebedded.stable branch). In order to accomplish this we will use the "pull" command (see below). The second step will be to extract the real openembedded workspace (metadata information) for the branch pulled, to do this we will use the "checkout" command. Like other version control systems the checkout must be done against a revision of code, in this example we will checkout against the HEAD revision.

(always within of working directory)

$ mtn --db=OE.mtn pull monotone.openembedded.org org.openembedded.stable
$ mtn --db=OE.mtn checkout --branch=org.openembedded.stable openembedded

3.4 Basic directory layout

At this point let's take a look at the directory layout of our working space:

my_OE/
|-- bitbake
|   |-- bin
|   `-- ...
|-- OE.mtn
`-- openembedded
    |-- _MTN
    |-- classes
    |-- conf
    |-- contrib
    |-- files
    |-- packages
    `-- site

my_OE/
 `-- openembedded/
        |- _MTN/ ==> special Monotone directory, this file defines this directory as 
        |            monotone workspace.
        |- packages/     ==> package rule files, bitbake recipes
                |- tasks/ ==> base tasks, useful tasks groups in file recipes
                |- conf
                    |- machine/ ==> machine rule files
                    |- distro/ ==> distro rule files

3.5 Setting up the final environment

Only remains some final details for the begining of the real work. This details are related with the environment setup. We have to do accessible the bitbake tool, with our execution path. Also we have to set the special variable BBPATH, and BBFILES, for OE uses. In short:

$ export PATH=$PATH:${HOME}/my_OE/bitbake/bin/
$ export BBPATH=${HOME}/my_OE/build:${HOME}/my_OE/openembedded
$ export BBFILES=${HOME}/my_OE/openembedded/packages/*/*.bb

3.6 local.conf special file

The final step is to create a build directory where the "build work" will be made. Build is a special directory which holds a local configuration file. We have to create the following folder structure:

my_OE/
 `-- build/
        `- conf/
             `-- local.conf

The special file local.conf is a basic configuration file which contains any OE variable. The most important ones are:

OE will use this information as a starting point, making cross compilers for the target architecture and building a distro based on it. For practical purposes we will use the following configuration file:

$ cat my_OE/build/conf/local.conf
MACHINE = "epia"
DISTRO = "generic"

"epia" is one of the available OE architectures, some others would be alix, efika, shark, x86, fic-gta01, etc. Epia is an architecture definition ready for VIA chipsets. As base distribution we will use a "generic" distro available in OE. This distribution configuration serves as a starting point for new target platforms, or distributions. It is based on conservative settings.