Next: , Previous: Introduction, Up: Top

2 Build System

To simplify things for end users, the PPW source tree uses GNU automake and GNU autoconf.

If you're not familiar with automake and/or autoconf, feel free to read the very brief introduction below, or refer to the GNU website for more information

2.1 A Brief Description of Automake and Autoconf

Autoconf is a collection of utilities that produces a portable script named configure that a user is supposed to run before they compile a piece of software. Autoconf can be thought of as a proactive approach to portability, where the software examines the current environment and machine configuration and makes appropriate changes to the source code to make it compile and run under a certain configuration.

The script that autoconf generates is prepared by examining a file named (or in some older versions, Autoconf provides a bunch of m4 macros related to portability that can do certain checks for you, such as find the full path of a certain executable, find out what C compiler the system has available, and determine if the current C compiler accepts the inline, volatile, and const keywords. There is also a special macro named AC_OUTPUT that takes files with an extension of .in, replaces keywords in them, and outputs a file without the .in extension.

Automake is another tool that provides a high-level way of writing Makefiles. Instead of writing a Makefile directly, you write a file that gives high-level information about how to compile your application such as what binaries and libraries to compile, where to install them, etc. Automake produces Makefiles compatible with most vendor-supplied make programs, in addition to GNU make which can be installed on just about anything.

Both Autoconf and Automake make it much easier to write and distribute software, but both are fairly complex and have some, shall we say, interesting syntax aspects and default behaviors. However, both are worth the initial learning curve and are de-facto standards used nearly all open source projects as of 2006, including Berkeley UPC.

2.2 Build directory, source directory, PREFIX, and DESTDIR

One interesting aspect of Automake is that it lets users build in separate directories from where the source code resides. For example, a user might do something like this:

     $ tar xvzf ppw-1.0.tar.gz
     $ cd ppw-1.0
     $ mkdir bldopt; cd bldopt
     $ ../configure CFLAGS=-O2
     $ cd ..
     $ mkdir bld; cd bld
     $ ../configure CFLAGS=-g -Wall

This can be really handy for testing different configurations of the tool on a single source tree.

In addition to separate build directories, Automake also allows you to specify a prefix on install that might be separate from the one chosen when the configure script was run, as in:

     $ ./configure prefix=/foo/bar
     $ make
     $ make prefix=/tmp/asdf install

Finally, Automake also allows appending an arbitrary prefix to your installation path, such as

     $ make DESTDIR=/tmp/blah install

This particular option is sometimes used by people packaging software up to be distributed in binary form.

It is very important that any updates to the build system do not break these features, as advanced users will expect them to “just work.” Luckily, Automake handles most of the details about this for us, but be sure to run make distcheck every once in a while to make sure you haven't inadvertently broken this functionality.

2.3 Getting a ./configure Script From the Subversion Tree

If Autoconf and Automake generate a configure script and a set of Makefiles, then a question arises: should we store the generated configure scripts and Makefiles inside the svn tree? Since end users won't be getting copies of PPW through svn, I decided that it wouldn't be worth the hassle of trying to store all of Automake and Autoconf's files in svn. Instead, in the toplevel PPW source tree, there is a script called that takes care of calling the appropriate automake and autoconf commands to generate everything needed to build the PPW source code.

This way, it is easier to experiment with different version of Automake and Autoconf. The and files should work with any relatively modern version of Automake (v1.8+) and Autoconf (v2.13+).

2.4 Java Source Code Distribution

Since Java-compiled bytecode is (nearly) platform-independent, I've opted to keep the Java build process separate from the rest of the software. Instead, the file in the javasrc directory contains references to the jar files that should be distributed when make dist or make distcheck is run.

For the Java source code, we use Apache Ant to build the source code and resulting JAR files. We use a pretty standard Java source tree setup, although one notable differences is that all third-party source code is stored in the javasrc/thirdparty directory; all source in the javasrc/src directory has been written by us for PPW.

Note: Make sure to follow any licensing requirements from third-party source code added to the source tree. For any LGPL-licensed source code, this usually means keeping a separate JAR file and “dynamically linking” to that via the main JAR's Class-Path attribute.

2.5 Example Developer Session

Listed below is the partial output taken from using svn to check out a clean copy of the PPW source tree, run the bootstrap script, configure the source tree, and compile it.

     $ svn co ppw
     ... output truncated ...
     A    ppw/examples/shmem/shtest.c
     A    ppw/examples/shmem/apsp_shmem.c
     A    ppw/examples/shmem/Makefile
     A    ppw/examples/sequential
     A    ppw/examples/sequential/pi.c
     A    ppw/examples/sequential/simple.c
     A    ppw/examples/sequential/Makefile
     $ cd ppw
     $ sh
     Setting up autoconf/automake...
     ... output truncated ...
     $ ./configure
     ... output truncated ...
     configure: creating ./config.status
     config.status: creating Makefile
     config.status: creating src/Makefile
     config.status: creating javasrc/Makefile
     config.status: creating src/ppw_config.h
     config.status: executing depfiles commands
     PPW has been configured with the following options:
       GASNet tools: use Berkeley UPC's version
       PThreads support: Yes
       Sequential C (via gaspref): Yes
       SHMEM (via gaspref): Yes, quadrics
       UPC (via GASP): Yes, berkeley
       Java: Yes
         If you'd like to recompile all of the Java source code,
         please install Apache Ant ( and run 'ant dist' from
         within the javasrc directory.
       PAPI support: No
     $ make

At this point, the software will be compiled.

2.6 Using Automake to Build a Tarball

Automake automatically builds a make distcheck target to run that produces a compressed tarball of the program's source code which should be used when preparing a new release of PPW.

Note: When preparing a new release, don't forget to run ant in the javasrc directory to rebuild the Java source code tree.