view · edit · print · history

Warning; this is unreviewed material from someone who learned things the hard way; pending review use care to rely onthe info in this page

Development 101

This page describes some essential do's and don't that you need to know if you are granted write access to the development database. It is by no means complete. Feel free to update.

Getting Started

It is essential that you have a good overview of the directory structure. A description can be found in MasterMakefile.
It is also assumed that you have some knowledgement about version control management system.
Also check the manual page for monotone.

The master makefile

The master makefile has targets for developers. Using these targets is the highly preferred way of working as this minimizes the risk of making errors.

  • make update
    This updates your working copy, fetching all changes since the last time you did this. If you only want to update openembbed you can use make update-openembedded
  • make push-openembedded
    This pushes all changes back to the central repository.

The monotone description below is useful to give you a better understanding on how things work. In most cases these are not needed (although I have found monotone revert to come in handy at a few times).


http://oe.handhelds.org/cgi-bin/moin.cgi/MonotonePhraseBook gives an overview of monotone commands. However for nslu2-linux things follow the same structure, but work out a little bit differently.

The nslu2-linux tree consists of five branches:

  • org.nslu2-linux.bitbake
  • org.nslu2-linux.dev
    This is the default branch that is used when you give monotone commands in the top level directory of your tree (where the master makefile resides). If you are starting with this you most likely won't have to do anything in this branch.
  • org.openembedded.dev
    This is where all openembedded packages reside. Typically developers make changes in the packages/<package>/ directories (and/or create a new directory in packages if a new package is added). The only other interesting place is conf/distro/*-packages.conf, which contains the list of packages. mt commands issued in the openembedded directory use this branch by default.
  • org.openembedded.dreambox

An overview of the most inportant monotone commands:

monotone pull

This updates your monotone database to the latest version of the source. It is a good habit when you changed things, before committing your changes you do a monotone build, then rebuild and test your changes, then check them in. That way the risk of multiple heads is reduced (since another developer could have changed something at the same time).

monotone update


monotone add <filename>

This adds the file to your local working copy. Upon committing and pushing this file will added to the database and central repository.
Be careful where you issue this command!. If you want to add a file to org.openembedded.dev you need to be in the openembedded directory.
It is not needed to add every file individually. You can also add a complete directory in one command. This is useful if you added a new package.

monotone commit

This actually commits your changes to the database. Be sure to add a good description to your changes. It is customary to start with the name of the package or file that you changed. Also check that you do not accidently drag in additional files (e.g. because you touched/modified something when debugging).
It is a good habit to have different commits for different changes/problems. So if you fix two problems, make two commits.\\ During the commit you will be asked for your password.

monotone push

This pushes your changes back to the repository. You will be asked for your password. It is good practice do to a monotone merge after pushing your changes.

monotone merge

Sometimes it happens that someone else makes a change in the database while you were working on it. monotone merge will merge the changes. If two people changed the same file manual intervention is needed to create the merged file. Otherwse the mechanism is automatic.

monotone revert

This command is not listed on the man page. However it is hightly useful. monotone revert is the command to use when you accidently modified a file (or modified it in a way you did not intend beyond recovery). It will restore the file to the version that is in your working copy of the database.


Bitbake is the tool to build individual packages. It operates on .bb files. These files contain a description of actions to be performed during a build. More on the contents of a .bb file in the next section.

In order to use bitbake you'll need to do the following (assuming you are in your top level directory:
cd openslug (or unslung or another distro, but I have only used this on openslug)
. setup-env

Invokation of bitbake can be done in two ways. The first one is to say:
bitbake <package>
The second one is to use:
bitbake -b <bbfile>

The package name is often (but not always!) the name of the directory in openembedded/packages. The name of the .bb file in the openembedded/packages/<package> directory reveals the right name. It is the part preceding the underscore ('_') in the filename. If a package dir contains multiple related packages you'll find multiple .bb files with different parts before the _. E.g. if you go to openembedded/packages/ixp4xx you'll see two sets of bb files. There is ixp-osal and ixp4xx-csr. Both pacakges have different versions.

As of the time of writing ixp-osal had three versions: (ixp-osal_1.5.bb, ixp-osal_2.0.bb, ixp-osal_2.1.bb) whereas ixp4xx-csr has four versions: (ixp4xx-csr_1.4.bb, ixp4xx-csr_1.5.bb, ixp4xx-csr_2.0.bb, ixp4xx-csr_2.1.bb).
bitbake <package> always takes the latest version (which is the bb file where the part after the _ is the biggest (according to the strcmp rules).

bitbake <package> only works if the package is listed in conf/distro/openslug-packages.conf. If you want to build a package not in the conf file (e.g. because you are porting it, or because it is only available on other platforms) you need to use bitbake -b to build the package. bitbake -b can also be used to build older versions of a package (should you desire/need to).

bitbake has one option that is highly useful for developers: -cclean This will remove your working copy of the package from tmp/work. That way you can easily test things (e.g. if you changed something in your .bb file).

Anatomy of a .bb file.

This section will give an overview of the most important parts of a .bb file.

should this be done using a live example (e.g. annotating an existing bb file)


inherit autotools


do_fetch do_unpack do_patch do_configure do_compile do_populate_staging do_stage do_package do_build

do_populate_staging _prepend _append

also covers patches directory naming etc

would this be the right place to tell about packages (dev, doc, locale) etc. Or should there be a separate section on packages?

Modifying an existing package.

Adding a release of a package.

This is often the simplest case. When there is a new release of a package, most often it suffices to copy and rename the existing bb file and the patch directory, modify the SRC_URI to the location of the latest and the greatest version of the package, reset PR to r0, and build and test the package. If the resulting pacakge does not work additional effort as described in "Modifying an existing package" is needed.

Adding a new package.

For further reading

Additional information can be found on the following web pages: .....

Also when in doubt you can always ask your questions on irc (e.g. in #nslu2-linux or #openslug on freenode)

Fixing changes to a package.

If you have made changes to a package and you want to revert them back to the original use this procedure

You must be in the ~slug/openembedded directory.

Check for the out of date packages.

 monotone update

You'll see output like this...

monotone: warning: missing packages/vlc/vlc-gpe-0.8.1/fix-pda.patch monotone: warning: missing packages/vlc/vlc-gpe-0.8.1/vlc-tremor.patch monotone: warning: missing packages/vlc/vlc-gpe_0.7.2.bb monotone: warning: missing packages/vlc/vlc-gpe_0.8.1.bb

The you can add each package back or all of them at once.

 monotone revert packages/vlc/vlc-gpe_0.7.2.bb

Will bring back a single file.

 monotone revert packages/vlc

Will bring back the entire directory.

 monotone revert --missing

Will bring all the missing package files back.

view · edit · print · history · Last edited by mrkzander.
Based on work by eFfeM and Koen.
Originally by eFfeM.
Page last modified on April 11, 2006, at 12:02 PM