Next: Instrumentation and Measurement Modules, Previous: Introduction, Up: Top
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
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
configure.ac (or in some older versions, configure.in).
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 Makefile.am 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.
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.
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 Bootstrap.sh 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 configure.ac and Makefile.am files should work with any relatively modern version of Automake (v1.8+) and Autoconf (v2.13+).
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 Makefile.am 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.
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 http://svn.hcs.ufl.edu/ppw/trunk 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 Bootstrap.sh
Setting up autoconf/automake...
aclocal...
autoheader...
automake...
... output truncated ...
Done.
$ ./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 (ant.apache.org) and run 'ant dist' from
within the javasrc directory.
PAPI support: No
$ make
At this point, the software will be compiled.
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.