Compiling Underworld With SCons

Some Notes About SCons
Compiling Underworld from source
Why SCons and not VMake?

Some Notes About SCons

Environment variables are used when configuring
All configuration steps are logged in 'config.log'
Can only build from the project root, which guarantees consistent builds.

Compiling Underworld from source

These instructions apply to compiling Underworld, version greater than 1.4, on local linux and mac machines, and broadly apply to compiling on clusters as well. For specific instruction on clusters Underworld is currently used on see Cluster page.

Underworld uses a mixture of python scripts and the SCons software construction tool to compile the code. ( Underworld versions greater than 1.2 come with a copy of SCons, so there is no need to download and install your own copy of SCons separately. )

Step 1: Configure

The configuration step checks that the dependency packages are compatible with the version of Underworld source code.

To configure run

./configure.py

from the top level directory of the source code.

The configure command can take options as arguments to override default behavior of the configuration script. The complete set of arguments can be seen by running

./configure.py -h

Common Command Arguments
--with-debugging={0,1}	Boolean: default is 1	1: will compile the code with debugging symbols, 0: compiles the code without debugging symbols in optimised mode (quick)
--with-x11={0,1}	Boolean: default is 1	1: will compile with visualisation support via x11, 0: no x11 support
--with-osmesa={0,1}	Boolean: default is 1	1: will compile with visualisation support via osmesa, 0: no osmesa support
--prefix=	string	path to install code to

example

   ./configure.py --with-debugging=0 --petsc-dir=/over/here --with-osmesa=1

this configures a optimised compilation to use the petsc package install at /over/here/ and for visualisation via the osmesa windowing.

For Macs using Mac OSX <10.6 will need to add the following flag (because Carbon is supported) to the end of their configuration command:

--with-x11=0

For supported computer clusters follow the links on the Cluster page.

Step 2: Build

In the same directory, then to build the package type:

./scons.py

or to build to the --prefix directory (as an equivalent to "make install"):

./scons.py ; ./scons.py install

or for code developers who want to rebuild as fast as possible (note that this is not garaunteed to produce a consistent build):

./fast-scons.py

Step 3: Check Build

To run tests, type one of the following (note: 1) we redirect the output to analyse it; 2) on some clusters tests may have to be run as a queue job ).

1. runs unit-tests & low resolution integration tests

./scons.py check > results

2. runs only convergence tests

./scons.py check-convergence > results

3. runs all tests (recommended for cluster installs, however can take a long time and backfire on machines with a complex mpi environment)

./scons.py check-complete > results

To analyse the results run

   $ grep Total results
   [PCU] Total Passes: (225/225)
   [PCU] Total Passes: (149/149)
   [PCU] Total Passes: (26/26)
   [PCU] Total Passes: (53/53)
   [PCU] Total Passes: (15/15)
   [PCU] Total Passes: (2/2)
   [PCU] Total Passes: (5/5)
   ALL Projects Total:  31 tests, 31/0/0 passes/fails/errors

Why SCons and not VMake?

SCons must be used to compile releases Underworld-1.2.0 and later. Underworld-1.1.0 and earlier releases were compiled using VMake.

-- Julian Giordani - 10 February 2011
-- Wendy Mason - 01 November 2010
-- John Spencer - 13 Aug 2008
-- Luke Hodkinson - 13 Aug 2008

users@underworldproject.org