Using the SCons build system

Using the SCons build system

Starting right after build-9half, th Linux-developers of Widelands has switched from the well-known Makefiles to a build system based on SCons.

Why SCons?

SCons basically does the same job as make, so why the switch?

• SCons is written in Python. The configuration files are in Python too. So if you want, you have the full power of Python at your hands while setting up the build. Compare that to make's features and it's reason enough.
• SCons is platform independent. Make claims to be, too, but try writing a single Makefile that works on win32, Linux and MacOS X and you'll see the point.
• SCons supports functionality similar to autoconf/automake. But unlike autotools, normal people can understand it.
• SCons supports unit testing out of the box.

OK, so we switched. But how do we use it and are there any differences to using make?

Using SCons

Using SCons is very similar to make. It's just the additional things that make it a joy to work with The commands you will use most often are:

• scons

1. Build from current source files (make)

• scons -c

1. Remove old intermediate files (make clean)

• scons -jN

1. Build using N concurrent processes (make -jN)

• scons -h

1. Get help about build options (configure --help)

• scons -H

1. Get help about other command line options

Not a big difference, right? But there's more:

Build options

Similar to autotools' configure, SCons allows you to add configuration options to your build. It work's like you'd expect:

scons BUILD_OPTION=VALUE

To look up the available options, use scons -h

SCons will remember your choice and use it for future compiles! So if you need an additional include path, specifiy it once:

scons extra_include_path=/home/me/include

and from then on just use "scons". No Makefile editing, no shell aliasing, nothing.

Build types

In Makefile/Makefile.local you could specify a build type like profile. With SCons, build type is a normal command line option:

   scons build_type=profile

The available build types are:

• debug (default)

1. create debug info, normal optimizations (-O3, for gcc)

• debug-slow

1. create debug info, no optimization

• debug-no-parachute

1. like debug, but disable the SDL parachute

• profile

1. generate debug info and profiling instrumentation, heavy optimization

• release

1. no debug info, heavy optimization

Note that, unlike before, intermediate build files will not be stored in, e.g., src/native-debug but rather in build/native-debug. SCons does not touch source directories in any way.

Build IDs

Basically everybody uses some kind of versioning in their releases. For Widelands, those are numbered builds (such as build-10, build-11, etc.). Setting this build ID is essential when creating releases, but once you have it it's also easy to create e.g. weekly snapshots.

By default, the build ID is automatically determined based on the current SVN revision number. Repositories using svk or git-svn are also supported by this mechanism.

If you want something different, use the parameter build_id:

   scons build_id=build10 dist         (for "dist", see below)

will create

   widelands-build10.tar.gz

Distributing files is great, but wouldn't it be cool to use this ID in the program too? You can== Just #include "build_id.h". This file gets created on every compiler run and contains:

#define BUILD_ID the_id_you_wanted
const char* g_build_id="the_id_you_wanted"

Keep in mind that SCons will remember this setting, so after a release make sure you go back to build_id="" to reenable the automatic mechanism.

config.h

On each run, SCons will create the file src/config.h. It contains information that has been autodetected - if you need to know about the environment, just ask the config system (that's what it's there for ;) ). If there are changes from the last run, files #include-ing config.h will be recompiled accordingly.

config.h contents are created 'manually', so if you need more information in config.h, you have to modify the SConstruct file.

Other targets

Of course, SCons lets you do anything you could do with the old build system. Additionaly targets include:

• scons tags

1. Create source code information with the "tags" program. This is called automatically after every compile, too.

• scons doc

1. Create source code documentation with Doxygen. You only need doxygen installed if you actually want to use this.

• scons dist

1. Create a distribution tarball

• scons install, scons uninstall

1. Install/uninstall Widelands on a Unix-like system. This will use the command line settings "install_prefix", "bindir" and "datadir"

• scons shrink

1. Use pngrewrite and optipng (not included with Widelands) to make all PNGs as small as possible. Be warned that this takes a long time - over one hour on a Xeon-2.8GHz! You need pngrewrite and optipng only if you actually want to use this. It's a job typically done once before a release.

• scons buildcat

1. Rebuild locales from the source. Do this if you changed translatable strings.

• scons indent

1. Automatic indenting of source files, using astyle. Only select files are indented at the moment, look at src/SConscript. You only need astyle installed if you actually want to use this.

• scons longlines

1. Count lines that are OK / too long at 8-character tabs / too long at 3-character tabs

• scons precommit

1. Run buildcat, indent and longlines. Please run this before committing to CVS or creating a patch.

Caveats

SCons ignores all environment variables, including PATH, CPPPATH and LIBPATH!

This is done on purpose: SCons will detect your build environment and will adapt to it in a predictable manner. Environment variables can screw up this autodetection big time, which makes repeatable builds impossible and can cause very difficult bugs. So if you need external information, use SCons to detect it (best), create a command line option (good enough) or rather forget about it. That's not to say it can't be done. It's just not a very good idea.