Getting started with OE-Classic
Contents
Note for OpenMoko Developers
Openmoko has its own version of BitBake. Openmoko provides their own setup instructions.
Introduction
This page tells you how to get started with Openembedded, i.e. how to install OE and start building packages. Before you proceed, please look at the important bits of RequiredSoftware that must be installed on your system.
IMPORTANT NOTES: this guide assumes that:
- the base directory of your Openembedded environment is /stuff/
(As a normal user, you probably want to substitute this with /home/myuser/oe/stuff)
- you selected the org.openembedded.dev development branch
You do not have to be root to build packages or distributions with Openembedded. It is even recommended to always work as user, not as root.
org.openembedded.dev is a development branch, therefore your build will be based on the contents of this development branch which may not be what you intended. See DevelopmentBranches for other available branches including versioned branches. You might want to use the stable branch, which is called org.openembedded.stable. One general-purpose distro is Angstrom, well mantained in both stable and development branches. More information about the angstrom project can be found on Angstrom homepage
Again, for the rest of these notes, replace /stuff/ with the base directory of your Openembedded environment and org.openembedded.dev with the name of the branch that you selected.
Setting up the toolchain and doing a build
Directory Structure
The base directory of your Openembedded environment (/stuff/) is the location where sources will be checked out (or unpacked).
- You must choose a location with no symlinks above it
- If you work in a chrooted environment it is highly recommended to 'su - <username>' after you have chrooted. Otherwise compilation may fail because ccache needs a valid $HOME - which is set when using a user account.
To create the directory structure:
$ mkdir -p /stuff/build/conf $ cd /stuff/
Obtaining BitBake
To start using OE, you must first obtain the build tool it needs: bitbake
It is recommended to run bitbake without installing it, as a sibling directory of org.openembedded.dev/ and build/ directories. Indeed, as bitbake is written in python it does not need compilation for being used. You'll just have to set the PATH variable so that the BitBake tools are accessible (see Setup the environment section).
Using packages
There is a BitBake package available for more and more distros - see OEandYourDistro.
Using releases
Visit BitBake homepage and download tarball with latest release. For normal usage we suggest using 1.8.x (stable branch) versions. Unpack it to /stuff/bitbake/.
Using Subversion
Go to the base directory of your Openembedded environment and checkout bitbake:
$ cd /stuff/ $ svn co svn://svn.berlios.de/bitbake/branches/bitbake-1.8/ bitbake
NOTE: for proxy handling, see SVN FAQ
Updating bitbake
Bitbake is being revised fairly often. Periodically it's a good idea to check the repository of bitbake stable branches to see if a new stable branch is available or if the current branch has been revised. Compare your existing bitbake directory with the latest bitbake branch in the repository. Your existing bitbake branch and its 'last changed revision' number can be found as follows:
$ cd /stuff/bitbake; svn info
If there is a new stable branch, you will want to move or delete your existing bitbake directory and repeat the process listed above under "To obtain bitbake". If there is no new branch, it is easy to update bitbake:
$ cd /stuff/bitbake; svn update
Obtaining OpenEmbedded using Monotone
Note: OpenEmbedded is in the process of moving to git. This section will soon be obsolete and should be replaced. The git repository is at git://git.openembedded.net/org.openembedded.dev.git
Next, you'll need to obtain the actual Openembedded database. The OE database store all the OE metadata: build classes, configuration files, and packages. Then you can extract from this database the development branch(es) you want.
The Openembedded database is a Monotone database, which is the current SCM (Source Code Management) system for Openembedded. You can find monotone binaries and documentation at Monotone official site.
To obtain Openembedded:
- Install Monotone 0.3x (if you have to use an older version of Monotone because of libboost problems, then refer to the Manual for additional hints).
- Go to the base directory of your Openembedded environment
$ cd /stuff/
- Download and bunzip2 the OE database snapshot. Note: Unfortunately some monotone versions differ in database format. Check Snapshots and download the one matching your monotone version.
$ wget http://www.openembedded.org/snapshots/OE.mtn.bz2 $ bunzip2 -d OE.mtn.bz2
This is the database you'll be using for all the work.
If you run into a problem at this stage, check to make sure you have version 0.32 (or newer) of monotone installed.
If you get further troubles in using monotone, there are two ways out:
- use the latest OE snapshot
- use a static monotone image
Then you can checkout your local copy of the Openembedded tree.
$ cd /stuff $ mtn --db=/stuff/OE.mtn checkout --branch=org.openembedded.dev
This extracts directories and files relating to the selected branch from the OE.mtn database and places them under /stuff/branchname (i.e. in /stuff/org.openembedded.dev in this guide)
If at this stage you get an error that the branch you want to check out has multiple heads, you should do a mtn pull to update it, and if it isn't fixed after pulling, notify one of the developers to merge it. You should select one head and continue with this howto.
Note: As stated in the introduction, you can of course checkout other branches instead of org.openembedded.dev. See DevelopmentBranches for more details about existing branches.
Updating OE
The .dev branch of OE is updated very frequently (as much as several times an hour). The distro branches are not updated as much but still fairly often. It seems good practice to update your OE tree at least daily. To do this, first update your repository's local database (for .dev branch in this example):
$ mtn --db=/stuff/OE.mtn pull monotone.openembedded.org org.openembedded.dev
Then update the branch(es) you are using. This will update the contents of the files in the local database. For example:
$ cd /stuff/org.openembedded.dev && mtn update $ cd /stuff/org.openembedded.dreambox && mtn update
You may find the Monotone PhraseBook handy for further information on how to use Monotone.
If monotone.openembedded.net is down you can use the following backup monotone servers:
- monotone.nslu2-linux.org
- opensource.wolfsonmicro.com
These mirrors are synchronized at least twice per hour.
Create local configuration
It's now time to create your local configuration. While you could copy the default local.conf.sample like that:
$ cd /stuff/ $ cp org.openembedded.dev/conf/local.conf.sample build/conf/local.conf $ vi build/conf/local.conf
It is actually recommended to start smaller and keep local.conf.sample in the background and add entries from there step-by-step as you understand and need them. Please, do not just edit build/conf/local.conf.sample but actually READ it.
For building a .dev branch, in your local.conf file, you should have at least the following three entries. Example for the Angstrom distribution and the Openmoko gta01 machine:
BBFILES = "/stuff/org.openembedded.dev/packages/*/*.bb" DISTRO = "angstrom-2008.1" MACHINE = "om-gta01"
Setup the environment
One of the four command sets below will need to be run every time you open a terminal for development. (You can automate this in ~/.profile, /etc/profile, or perhaps use a script to set the necessary variables for using BitBake.)
If you followed the recommendation above to use an uninstalled BitBake:
$ export BBPATH=/stuff/build:/stuff/org.openembedded.dev $ export PATH=/stuff/bitbake/bin:$PATH
If you installed BitBake:
$ export BBPATH=/stuff/build:/stuff/org.openembedded.dev
Alternative syntax for those using the tcsh shell (e.g FreeBSD):
$ setenv PATH "/stuff/bitbake/bin:"$PATH $ setenv BBPATH "/stuff/build:/stuff/org.openembedded.dev:"$BBPATH
Start building
The primary interface to the build system is the bitbake command (see the bitbake users manual). bitbake will download and patch stuff from the network, so it helps if you are on a well connected machine.
Note that you should issue all bitbake commands from inside of the build/ directory, or you should override TMPDIR to point elsewhere (by default it goes to tmp/ relative to the directory you run the tools in).
Here are some example invocations:
Building a single package (e.g. nano):
$ bitbake nano
Building package sets (e.g. task-base):
$ bitbake task-base
Special note for task-base: you may need additional setup for building this very one task. More details in ZaurusKernels
Building a group of packages and deploying them into a rootfs image:
GPE:
$ bitbake gpe-image
OPIE:
$ bitbake opie-image
(NOTE: kergoth says it will take about 4GB of disk space to build an opie or gpe image for one architecture)
See the /stuff/org.openembedded.dev/packages/meta/ directory if you're curious about what meta/task and image targets exist.
Building every package in the repository (NOTE: This will take a very long time and needs approx. 35 GB disk space):
$ bitbake world
Building a single package, bypassing the long parse step (and therefore its dependencies--use with care):
$ bitbake -b /stuff/org.openembedded.dev/packages/blah/blah.bb
See UsefulTargets for a description of some of the more useful meta-packages. You will typically need at least one of the base images (bootstrap-image, opie-image or gpe-image), and if and only if you're building for an OpenZaurus target requiring an installer image (such as C3000), an additional pivotboot-image.
Output of the build process (temporary files, log files and the binaries) all ends up in the tmp directory. Most interesting is probably the tmp/work/ directory. Just have a look around the DirectoryStructure.
Images generated by building package groups like opie-im.mtnage or pivotboot-image are placed in the tmp/deploy/images/ directory. Individual ipkg packages are put in tmp/deploy/ipk.
Adding Packages
- Create bbfile.
- Try building it locally.
- Fix eventual problems.
- Send .bbfile or an OePatch to the openembedded mailing list.
Problems
Try to solve problems first by checking that you have done everything right, that nothing has changed from this description and that you have the latest code (see MonotonePhraseBook). Look also in the log file (referenced in any error message you will receive). If you still have problems, try checking PossibleFailures and common build errors. Above links are dead, you can try the Category:FAQ. If problems persist, ask on IRC or in the openembedded mailing list.
The Openembedded metadata is changing constantly. This implies several things:
- Once you have a "known good" version that works well on your system, keep it! To update, clone a new copy; don't overwrite that working version until it's known to be safe.
- To resolve build problems, "mtn pull ; mtn update" is your good friend. Many times, the issues will already be fixed in the current tree.
- Not all metadata updates cause the local caches to update correctly. Sometimes you'll need to remove the ".../tmp" work directory and rebuild from scratch.
- Similar issues apply to the package sources you download.
Portability issues
Make sure to set TARGET_OS to something other than linux in local.conf if your host isn't linux.
GNU extensions to tools are often required. Symlink GNU patch, make, and cp (from fileutils), chmod, sed, find, tar, awk into your OE development path.
FreeBSD 4 users: Perl 5.0 is too old. A more recent perl must be available as /usr/bin/perl. Unfortunately just having more recent perl in the path isn't good enough. Some scripts are hard-coded for /usr/bin/perl. You can test for which perl you're using by typing perl -v. see /usr/ports/UPDATING for instructions on updating perl. Don't forget to do a use.perl port as instructed in /usr/ports/UPDATING
FreeBSD users: Set BUILD_OS in local.conf to freebsdN where N is your major version number. At least the cross gcc wants this.
FreeBSD users: The build process of glibc uses a very long command line at some places. Increase ARG_MAX to at least 131072, by editing /usr/sys/sys/syslimits.h and recompile your kernel (and reboot).
Productivity notes
Use the interactive bitbake mode ("bitbake -i") to speed up work when debugging or developing .bb files. Remember to run "parse" at the prompt first. Go!
If you want to save some compile time or are interested in additional tweaks to local.conf take a look at the AdvancedConfiguration page.
