When you build OpenSlug or Unslung from the OpenEmbedded/bitbake/BitKeeper build system you are actually building a system to build a system. bitbake is not make. It isn't cvs either (BitKeeper is!)

bitbake takes a set of instructions, .bb files, some configuration, .conf files, and a set of OpenEmbedded specific programming, .bbclass files. From this it constructs a set of directories - ${TMPDIR}/work/* - in which it executes conventional make (or configure) style build operations.

Therefore most of the time you do not want to debug bitbake, you want to debug what bitbake assembled in the work directory.

Any such debugging and bug fixing is very temporary, the next bk pull and subsequent bitbake operations will almost certainly destroy any changes. Nevertheless this is just about the only way to debug something which already exists in the bitbake build.

Find your package

First locate the problem package. Find the openembedded source first, the quickest way is:

Add more * characters until you find it. This is the base package name. For some packages the .bb file, which you will find in the package directory, will result in a different name because it has a different base name. It is the file name base of the .bb file which determines the standard working directory base name. You may need to search all the package directories (this is what bitbake does with the BBFILES variable):

Typically, however, the package directory name is used.

Now find the working directory. To do this cd to the temporary directory then use another echo:

Most of the time you can skip the first step, but it is often helpful to know where the bitbake source for the package is. For the kernel the package is in packages/linux but the working directory will be based on the name of the kernel, for example work/openslug-kernel-2.6.11.2-r0. There is a corresponding .bb file in packages/linux.

Change the package

cd to the sub-directory of work and make whatever changes seem necessary. The source will almost always be in a sub-directory, the name will be obvious - it repeats the package name.

When you make changes, copy the original file before editing it. Copy it to a file called something like original-name-of-file.orig, i.e. just append .orig to the file name. You need to do this because if you do not it is much more difficult to GenerateANewPatchForTheOEBuild.

Rebuild the package

Because this is a temporary change you can't simply use bitbake to rebuild. Try it - nothing will happen! That's because bitbake believes that the package is up-to-date. To persuade it that it isn't carefully remove the stamp files corresponding to the steps after the configure step. The stamp files are in the stamp directory in the temporary directory - the same one as contains work. cd to that directory then:

This lists the stamp files in order of creation. Make sure you don't get stamp files for more than one package. Make sure you don't remove the do_unpack stamp - that would cause bitbake to overwrite your changes! The ls command relies on the bitbake steps taking at least 1 second each. If you have a very fast machine then you will have to learn the order of the steps...

Notice that output of the ls command includes a stamp called name-of-package.do_configure. If you need to redo the configure step remove this and all later stamps, otherwise just remove the later stamps (starting with the do_compile stamp). Here's a list for busybox, but it will be the same list for everything:

stamps/busybox-1.00-r17.do_unpack

unpacks the source from the URIS given by SRC_URIS

stamps/busybox-1.00-r17.do_patch

applies the patches given by entries in SRC_URIS which end in ;patch=1

stamps/busybox-1.00-r17.do_configure

runs the package configure script. This may also hack the source directory - for example with the kernel and busybox do_configure copies defconfig over the sub-directory .config file. This is tricky because rerunning this step can, as a result, kill your local changes.

stamps/busybox-1.00-r17.do_compile

compiles the package.

stamps/busybox-1.00-r17.do_populate_staging

installs the package this might only be doing something for locally used packages

stamps/busybox-1.00-r17.do_package

packages the package! If you look in the install sub-directory in the project you should see the result, the image sub-directory is a temporary directory.

stamps/busybox-1.00-r17.do_build

jbowler: I believe this is just a wrapper for the previous two steps

Typically you do always want to do the steps after do_compile. However it is often necessary to compile several times (sometimes code doesn't compile correctly the first time.) This makes it useful to be able to repeat the do_compile step!

Repeating the compile step

Look in the package temp directory, notice that there is at least one file called run.do_compile.some-number. If you execute this file (it is just a shell script) the compile will be repeated. I simply copy the file out of the temp directory:

After this I can just type ./dcomp every time I need to recompile the package. You do need to do one of these two things - simply typing make in the source directory is unlikely to do the right thing.

When everything compiles fine remove the stamp files and execute a bitbake build. Without this the installation steps will not be performed - the package must be installed then the image (openslug-image or unslung-image) must be built.

This trick also works for the do_configure step - see below, but it does not work for other steps because they use Python programming rather than the pure shell (bash) programming used for do_configure and do_compile.

A trick for busybox and the kernel

Busybox and the kernel are both extensively configurable. It's useful to be able to change the configuration. For this you must rerun the do_configure step. The configuration is also complex! For this reason both packages provide a menuconfig make target to simplify configuration.

To use this do the following:

(Ok, you don't have to use vi, any text editor is fine.) Search for oldconfig. You should find one or maybe two lines which say something like:

Change the lines to say:

Execute ./dconf, after the menuconfig code has been compiled and you will have the standard ncurses menu configuration interface.

You must remove the yes from the kernel file - if you don't the screen will flash madly and, after a ^C, be left in a weird state. To reset it type reset<Enter>.

When you exit you write a new .config. If you re-run ./dconf it will overwrite the new .config with defconfig from the working directory. So copy the new .config on top of the working directory defconfig first!

The defconfig file comes from a sub-directory of the package directory. For busybox and linux the sub-directory has a name which matches that of the .bb file. You can bk edit the original defconfig and copy your new version back on top of it - then subsequent bitbake builds will preserve your changes!