However, we haven’t yet really documented properly all the different build options and how it works. So here it is – your primer to the new Bongo build system.

Once you’ve checked out Bongo, you’ll see a source tree which looks something like this:

$ ls
ABOUT-NLS  cmake           COPYING  import   INSTALL  po      TODO
AUTHORS    CMakeLists.txt  doxygen  include  man      README  zoneinfo
ChangeLog  config.h.cmake  HACKING  init     NEWS     src

The first thing we should do is create a new directory to do our build in: this stops all our build files from littering the source tree.

$ mkdir build
$ cd build/

Now we need to configure the build. There are two ways of doing this, and I use both! One way is good to start off, the other way is good for tweaking. You’ll see what I mean, but let’s start with the initial configuration. This is how I usually start:

$ cmake ../ -DCMAKE_INSTALL_PREFIX=/tmp/build -DBONGO_USER=alex -DCMAKE_BUILD_TYPE=Debug -DDEBUG=On

The first argument points to the Bongo source directory. Because I made a ‘build’ directory in the source tree and went into it, we’re just pointing at our parent directory. Then come some other options. Every option is prefixed with “-D”, and some of them are CMake options and others are Bongo options. In full:

• CMAKE_INSTALL_PREFIX: where we want to install to. I use /tmp/build for testing, and /usr/local/bongo when I want to run it in production.
• BONGO_USER: which user you want Bongo to run as. I use my user account for testing, “bongo” for production. You can also run as “root” if brave (not recommended!)
• CMAKE_BUILD_TYPE: set this to Debug to generate information for gdb, otherwise leave this option out.
• DEBUG: enable code paths which generate debugging messages. Both this option and the previous are for either advanced users or developers, really.

There are other options to the Bongo build, but these are the main ones. However, once you’ve configured Bongo, you may want to tweak something: perhaps turn on debugging, or change one of the file paths, or something different. The easiest way to do that is simply:

$ ccmake ./

Note that it’s “ccmake”, not “cmake”. This starts an interactive application where you can change each configuration item. You point it at the build directory, not the source, and it gives you all the various tweakable options. You’ll see that they are the same options that we pass to cmake – and indeed, you can pass them to cmake! There’s even an advanced mode with even more knobs (press ‘t’). When you’re done, press ‘c’ to configure the build and then ‘q’ to quit.

Once you have configured the build, you have access to the usual make commands:

$ make
$ make install
$ make clean

The first builds Bongo, the second installs it to your prefix, the last removes the built files.

Since the project was initially released, the autotools build system was what you needed to create Bongo. There are a variety of benefits to using autotools, and it’s an extremely well-tested and mature system. However, it’s also relatively difficult to understand and not particularly quick. Over time we accreted more and more things into our build which no-one understood fully and that would occasionally blow up in our face.

Now, a little while ago I started a new branch of Bongo, called “memmgr-glib”. This was mainly to replace the memory allocator – maybe Pat can blog a bit more about this, but the short story is that this change has highlighted a variety of bugs in Bongo. The branch version of Bongo therefore seems extremely unstable – actually, it’s just a lot less bug-tolerant, which is overall a good thing – but we used that as a cue to make some other changes.

One of which was a switch from autotools to CMake as our build system. Just to give one really obvious stat:

Clearly, there is a big difference in each category: it must be said that the build systems aren’t doing quite the same things at this point, and I haven’t done these tests properly as benchmarks, but fundamentally the times are extremely different. I expect eventually that the compile time will even out – the difference will become minimal, and is already of the same order. Configure and install are clearly quicker though, and there aren’t any amazing short-cuts being taken on the cmake side.

The huge difference this makes for developers is the compile-test cycle. A re-compile with either system is basically pretty quick – something like a few seconds each. However, “make install” with both systems is quite different. To do a proper update, it’s much quicker with cmake, which means the testing cycle is really quick.

One other thing that is also big, for me at least: with CMake, we can finally do out-of-source builds. It’s possible with autotools, but our system never quite got it right. With CMake, you can check out Bongo from svn and then do something like ‘mkdir build/; cd build/; cmake ../; make’. The source we checked out isn’t touched, and nothing gets built in the source tree – it all happens in another directory. Not only does it feel cleaner, but it means that you’re not likely to commit any files which shouldn’t be there and if something goes wrong you can just nuke the build directory and start again easily.

I’ve yet to teach the bongo-build bot on IRC about this new system, but I expect that it will make building there a lot quicker too – mainly because it goes through the cycle above more than once (it configures twice, for example). It will be interesting to see what a difference it makes!