Understanding Angstrom Bitbake Recipes

First, some information on my understanding of bitbake so far. Bitbake:

• Maintains the entire cross-compilation toolchain for you
• Enables reproducable open-source. When you bitbake systemd-image, it builds everything, from gcc and eglibc and upwards and you end up with a full filesystem and ipks. You really do have the source and you really can prove that you've built it all.
• Maintains a clean and and up-to-date ipk repository (making sure to clean old and obsolete packages)
• Handles building of dependencies -- if you say you need libreadline, just declare it as depends and it will make sure readline is built before your package builds. This is possible via the BBFILES path which scans and understands all recipes it can compile and forms a dependency tree. This tree can also be exported to graphviz
• Enforces a consistent build pattern for all of the OE projects, which gives you a lot of things for "free" like building ipk files, cleaning and fetching sources, etc.

The first page you will likely find on your searching is a very minimal and out-of-date (6 years old) bitbake manual. It explains a little bit about the syntax but not a lot about how to do recipes or how it's used within OpenEmbedded. There is some information also on the OpenEmbedded wiki but also nearly non-existant. After a LOT of searching, I've come across some more useful resources:

A "hello world' C program tutorial. This is useful but it doesn't work verbatim. However bitbake/Angstrom is now, the LICENSE and LIC_FILES_CHKSUM are required. This sounds like a great QA check for them, you have to say what the license is of the software and point to an actual file with that license and confirm it with a checksum. To just do my "hello" example I created an empty LICENSE file.

LICENSE = "TEST LICENSE"
LIC_FILES_CHKSUM = "file://LICENSE;md5=d41d8cd98f00b204e9800998ecf8427e"

SRC_URI = "file://hello.c\
           file://LICENSE"

I calculated the checksum simply with the "md5sums" command line tool. Now my package built and I got an ipk in the build/tmp-angstrom_2010_x-eglibc/deploy/ipk/armv7a directory. You can copy that ipk to the BeagleBone and install it "opkg install", then run hello.

This is as far as I've gone in practice so far, I want to start building real things soon, but this shows how easy it is. Just recently I finally found some real documentation that will let me take the next step. This documentation is a little old but still seems relevant to how things appear now. I found an OpenEmbedded manual linked from the beagleboard Google Group. There are three useful parts:

• All of chapter 8 is the most useful thing I've found yet.
• Chapter 3 contains something similar to the "hello world" tutorial I linked above but with more details (although harder to follow)
• The tasks section of chapter 7 describes the states bitbake goes through while building software. If you are are familar with the Java build tool Maven, this sounds a lot like the Maven lifecycle. Note you can also run bitbake <PACKAGE> -c listtasks to see what tasks can be run on a certain project.

One of the first things you will notice is that bitbake recipes are more declarative than imperative. If you're a Java developer familar with Ant and Maven, bitbake seems more like Maven, although the tasks are defined via imperative functions similar to make or Ant. Because of this, recipes seem very magical, for example they just set SRC_URI and then not bitbake not only knows how to obtain the source, but if patch files are included in SRC_URI then bitbake knows they should be patches applied before building, automagically. This is why documentation is very important for such a system so I hope to find a better resource for this. However, a lot of the magic variables have a default definition which you can find in the bitbake .conf files. There are 3 places you should look at when trying to figure things out:

• setup-scripts/conf/
• setup-scripts/sources/bitbake/conf/
• setup-scripts/sources/openembedded-core/meta/conf/

For example, from the openembedded conf file you can see the default definition of FILES_${PN}, which shows you the standard places that bitbake searches for files to go into your main package. That's how the hello world example automagically figured out that /usr/bin/hello should be packaged up.

And finally, of course the other good place to look is by example and the multitude of .bb files in the Angstrom layers. Once some of the magical variables are deceiphered, they should become more understandable.

I hope this helps you get started on your way, as it has for me. I'm still learning this so if I'm missing things, please leave a comment.