There are four ways to pass options to the configuration process.
export <option name>=<chosen value> # for bash
setenv <option name> <chosen value> # for (t)csh
gmake <configuration name>-config
All available configuration options may be set in a default options file ${HOME}/.cactus/config, any option which are not set will take a default value. The file should contain lines of the form:
<option> [=] ...
The equals sign is optional. Spaces are allowed everywhere. Text starting wit a ’#’ character will be ignored as a comment.
gmake <config name>-config CACTUS_CONFIG_FILES=<list of config files>
Multiple configuration files, with their file names separated by a ’:’ character, will be processed in order. Each file should be given by its full path. The options file has the same format as ${HOME}/.cactus/config.
gmake <config name>-config options=<filename>
The options file has the same format as ${HOME}/.cactus/config. (Note that these options are added to those from the ${HOME}/.cactus/config file.)
gmake <config name>-config <option name>=<chosen value>, ...
Not all configuration options can be set on the command line. Those that can be set are indicated in the table below.
The options are listed here in order of increasing precedence, e.g. options set on the command line will take priority over (potentially conflicting) options set in ${HOME}/.cactus/config or other Cactus configuration files. Default options from ${HOME}/.cactus/config will only be read if the environment variable CACTUS_CONFIG_FILES is not set.
It is important to note that these methods cannot be used to, for example, add options to the default values for CFLAGS. Setting any variable in the configuration file or the command line will overwrite completely the default values.
There is a plethora of available options.
If you are compiling on an architecture other than the one you are producing an executable for, you will need to pass the
option, where x-x-x is the canonical name of the architecture you are compiling for, such as sx6-nec-superux; the format is processor-vendor-OS.
These specify the chosen set of thorns for compilation. If the thorn choice is not provided during configuration, a list containing all thorns in the arrangements directory is automatically created, and the user is prompted for any changes.
Name of file containing a list of thorns with the syntax <arrangement name>/<thorn name>. Lines beginning with # or ! are ignored.
Location of directory containing THORNLIST. This defaults to the current working directory.
These are used to specify which compilers and other tools to use. Entries followed by * may be specified on the command line.
* The C compiler.
* The CUDA compiler.
The C++ compiler.
* The Fortran 90 compiler.
* The Fortran 77 compiler.
The preprocessor used to generate dependencies for and to preprocess C and C++ code.
The preprocessor used to generate dependencies for and to preprocess Fortran code.
* The linker.
The archiver used for generating libraries.
The archive indexer to use.
The program to use to create a directory.
The name of the Perl executable.
Flags which are passed to the compilers and the tools.
Flags for the C compiler.
Flags for the CUDA compiler.
Flags for the C++ compiler.
* Flags for the Fortran 90 compiler.
* Flags for the Fortran 77 compiler.
Flags for the preprocessor (used to generate compilation dependencies for and preprocess C and C++ code).
Flags for the preprocessor (used to generate compilation dependencies for and preprocess Fortran code).
Flags for MKDIR, so that no error is given if the directory exists.
* Flags for the linker. Warning: This variable is ignored while the compilers and linkers are autodetected. This can lead to strange errors while configuring. You can pass the linker flags in the variable LD instead.
Flags for the archiver.
Whether error messages and debug information in the compiled C and C++ files should point to the original source file or to an internal file created by Cactus. The only options available are yes and no, the default is yes. Set this to no if your compiler reports error messages about unrecognised # directives.
Whether error messages and debug information in the compiled Fortran files should point to the original source file or to an internal file created by Cactus. The only options available are yes and no, the default is yes. Set this to no if your compiler reports error messages about unrecognised # directives.
Enables cross compilation. Available options are yes and no, the default is no. To create a cross-compiled configuration one must explicitly set this option to yes.
Disable support for the data type CCTK_REAL16. The only options available are yes and no, the default is no. Cactus autodetects this data type only for C. If the C compiler supports it, but the Fortran compiler does not, it may be necessary to disable CCTK_REAL16 altogether, since Cactus assumes that data types are fully supported if they exist.
* Specifies what type of debug mode should be used, the default is no debugging. Current options are yes, no, or memory. The option yes switches on all debugging features, whereas memory just employs memory tracing (Section C1.9.3).
Debug flags for the C compiler, their use depends on the type of debugging being used.
Debug flags for the CUDA compiler, their use depends on the type of debugging being used.
Debug flags for the C++ compiler, their use depends on the type of debugging being used.
Debug flags for the Fortran 90 compiler, their use depends on the type of debugging being used.
Debug flags for the Fortran 77 compiler, their use depends on the type of debugging being used.
* Specifies what type of optimisation should be used. The only options
currently available are yes and no. The default is to use optimisation.
Note that the British spelling OPTIMISE will be checked first and, if set, will
override any setting of the American-spelled OPTIMIZE.
Optimisation flags for the C compiler, their use depends on the type of optimisation being used.
Optimisation flags for the C compiler, their use depends on the type of optimisation being used.
Optimisation flags for the C++ compiler, their use depends on the type of optimisation being used.
Optimisation flags for the Fortran 90 compiler, their use depends on the type of optimisation being used.
Optimisation flags for the Fortran 77 compiler, their use depends on the type of optimisation being used.
Optimisation flags used to indicate that no optimisation should be performed. These are invoked when OPTIMISE=no is used.
* Specifies what type of profiling should be used. The only options currently available are yes and no. The default is to use no profiling.
Profile flags for the C compiler, their use depends on the type of profiling being used.
Profile flags for the CUDA compiler, their use depends on the type of profiling being used.
Profile flags for the C++ compiler, their use depends on the type of profiling being used.
Profile flags for the Fortran 90 compiler, their use depends on the type of profiling being used.
Profile flags for the Fortran 77 compiler, their use depends on the type of profiling being used.
* Specifies what type of build warnings should be used. The only options currently available are yes and no. The default is to produce no warnings.
Warning flags for the C compiler, their use depends on the type of warnings used during compilation (Section B2.4.4).
Warning flags for the CUCC compiler, their use depends on the type of warnings used during compilation (Section B2.4.4).
Warning flags for the C++ compiler, their use depends on the type of warnings used during compilation (Section B2.4.4).
Warning flags for the Fortran 90 compiler, their use depends on the type of warnings used during compilation (Section B2.4.4).
Warning flags for the Fortran 77 compiler, their use depends on the type of warnings used during compilation (Section B2.4.4).
For Irix SGI systems: whether to build a 32- or 64-bit configuration.
For IBM SP systems: whether to build a 32- or 64-bit configuration.
Used to specify auxiliary libraries and directories to find them in.
Additional libraries. This variable can also contain linker options, e.g. to switch between static and dynamic linking. (Cactus adds a -l prefix to library names, but does not modify linker options.) Warning: This variable is ignored while the compilers and linkers are autodetected. This can lead to strange errors while configuring. You can pass the additional libraries in the variable LD instead.
Any other library directories. This variable can also contain linker options. (Cactus adds an -L prefix to library directories, but does not modify linker options.)
Used to specify any additional directories for system include files.
Used to specify the precision of the default real and integer data types, by the number of bytes the data takes up. Note that not all values will be valid on all architectures.
* Allowed values are 16, 8, 4.
* Allowed values are 8, 4, 2.
The directory in which to place the executable.
The name of the executable.
Compiling with extra packages is described fully in Section B2.2, which should be consulted for the full range of configuration options.
* The MPI package to use, if required. Supported values are CUSTOM, NATIVE, MPICH, or LAM.
Used in connection with thorn ExternalLibraries/HDF5. Supported values are BUILD, or a path pointing to an existing installation. The option HDF5 is depreciated.
Used in connection with thorn ExternalLibraries/LAPACK. Supported values are BUILD, or a path pointing to an existing installation. The option LAPACK is depreciated.
Supported values are yes, and no. A blank value is taken as no.
Supported values are yes, and no. A blank value is taken as no.
Setting this to no turns off all prompts from the make system.
Setting this to yes instructs gmake to print the commands that it is executing.
Setting this to no is an depreciated way of using VERBOSE = yes.
The Message Passing Interface (MPI) provides inter-processor communication. It can either be implemented natively on a machine (this is usual on most supercomputers), or through a standard package such as MPICH, LAM, WMPI, or PACX.
To compile with MPI, the configure option is
MPI = <MPI_TYPE>,
where <MPI_TYPE> can take the values (entries followed by * may be specified on the configuration command line):
For a custom MPI configuration set the variables
* libraries.
* library directories.
* include file directories.
Use the native MPI for this machine, as indicated in the known-architectures directory (lib/make/known-architectures).
Use MPICH (http://www-unix.mcs.anl.gov/mpi/mpich). This is controlled by the options
* machine architecture.
* directory in which MPICH is installed. If this option is not defined, it will be searched for.
* the device used by MPICH. If not defined, the configuration process will search for this in a few defined places. Supported devices are currently ch_p4, ch_shmem, globus and myrinet. For versions of MPICH prior to 1.2.0, the devices are searched for in this order, for 1.2.0 you may need to specify MPICH_DEVICE, depending on the installation.
If MPICH_DEVICE is chosen to be globus (http://www.globus.org), an additional variable must be set
* directory in which Globus is installed.
The Globus flavor may be chosen optionally
* Globus flavor to build Cactus with.
If it is not set, the first Globus flavor found will be used.
If MPICH_DEVICE is chosen to be ch_gm, (http://www.myri.com), an additional variable must be set
* directory in which Myrinet libraries are installed.
Use LAM (Local Area Multicomputer, http://www.lam-mpi.org/). This is controlled by the variables
* directory in which LAM is installed. This will be searched for in a few provided places if not given.
If the LAM installation splits libraries and include files into different directories, instead of setting LAM_DIR set the two variables
* directory in which LAM libraries are installed.
* directory in which LAM include files are installed.
Use WMPI (Win32 Message Passing Interface, http://dsg.dei.uc.pt/w32mpi/intro.html). This is controlled by the variable
* directory in which WMPI is installed.
Use HPVM (High Performance Virtual Machine, (http://www-csag.ucsd.edu/projects/hpvm.html). This is controlled by the variable
* directory in which HPVM is installed.
Use MPIPro (http://www.mpi-softtech.com/).
Use the PACX Metacomputing package (PArallel Computer eXtension,
http://www.hlrs.de/structure/organisation/par/projects/pacx-mpi/). This is
controlled by the variables
* directory in which PACX is installed. If this option is not defined, it will be searched for.
* the MPI package PACX uses node-local communication. This can be any of the above MPI packages.
Note that the searches for libraries, etc. mentioned above use the locations given in the files in lib/make/extras/MPI.
To compile with HDF5 (http://hdf.ncsa.uiuc.edu/whatishdf5.html), include thorn ExternalLibraries/HDF5 in your thornlist, and use the configure option
HDF5_DIR = BUILD/<dir> [LIBZ_DIR = <dir>] [LIBSZ_DIR = <dir>]
If HDF5_DIR is not given, the configuration process will search for an installed HDF5 package in some standard places. If HDF5_DIR is set to BUILD an HDF5 installation will be build. If the found HDF5 library was built with the external deflate I/O filter, the configuration process also searches for the libz library and adds it to the linker flags. You may also point directly to the location of libz.a by setting LIBZ_DIR. If the found HDF5 library was built with the external szlib I/O filter, the configuration process also searches for the szlib library and adds it to the linker flags. You may also point directly to the location of libsz.a by setting LIBSZ_DIR. Note that the option HDF5 = yes/no is depreciated and does not work with thorn ExternalLibraries/HDF5.
To compile with LAPACK (http://www.netlib.org/lapack/), include thorn ExternalLibraries/LAPACK in your thornlist, and use the configure option
If LAPACK_DIR is not given, the configuration process will search for a LAPACK library liblapack.[{a,so}] in some standard places. If LAPACK_DIR is set to BUILD, a Lapack installation will be build.
To compile with PETSc (http://www-unix.mcs.anl.gov/petsc/petsc-2/index.html), the configure options are
If PETSC_DIR is not given, the configuration process will search for an installed PETSc package in some standard places (defined in lib/make/extras/PETSC). If PETSC_ARCH is not given, the configuration process will choose the first PETSc configuration found in $PETSC_DIR/lib/libO/. If PETSC_ARCH_LIBS is not given, the configuration process will choose architecture-specific libraries, as required by a PETSc configuration (usually PETSc needs the LAPACK library).
To enable multithreading support within Cactus using POSIX threads, the configure option is
PTHREADS = yes
The configuration process will check if a reentrant C library is available, and adds it to the linker flags. It will also search for the system’s Pthreads library (either libpthread or libpthreads), and set preprocessor defines necessary for compiling multithreaded code.
The configuration process sets up various subdirectories and files in the configs directory to contain the configuration specific files; these are placed in a directory with the name of the configuration.
contains the files created by the configure script:
The most important ones are
contains compilers and compilation flags for a configuration.
contains details about extra packages used in the configuration.
The main configuration header file, containing architecture specific definitions.
An architecture specific header file containing things which cannot be automatically detected, and have thus been hand-coded for this architecture.
These are the first files which should be checked or modified to suit any peculiarities of this configuration.
In addition, the following files may be informative:
A Perl script used to determine how the Fortran compiler names subroutines. This is used to make some C routines callable from Fortran, and Fortran routines callable from C.
Initially empty. It can be edited to add extra architecture specific dependencies needed to generate the executable.
The make rules for generating object files from source files.
Finally, autoconf generates the following files.
A log of the autoconf process.
A script which may be used to regenerate the configuration.
An internal file used by autoconf.
An empty directory which will contain the libraries created for each thorn.
An empty directory which will contain the object files generated for this configuration, and preprocessed source files.
A file containing information about the configuration (including the options used to configure the configuration).
A directory which contains all the files generated by the CST from the .ccl files.
A scratch directory which is used to accommodate Fortran 90 modules.
Once you have created a new configuration, the command
gmake <configuration name>
will build an executable, prompting you along the way for the thorns which should be included. There is a range
of gmake targets and options which are detailed in the following sections.
A target for gmake can be naively thought of as an argument that tells it which of several things listed in the Makefile it is to do. The command gmake help lists all gmake targets:
builds a configuration. If the configuration doesn’t exist, it will create it.
removes all object and dependency files from a configuration.
removes all dependency files from a configuration.
removes all object files from a configuration.
creates a new configuration or reconfigures an existing one overwriting any previous
configuration options.
The configuration options are stored in a file configs/<config>/config-info.
displays the options of the configuration (cat configs/<config>/config-info).
deletes a configuration (rm -r configs/<config>).
edits the ThornList.
copies all the example parameter files relevant for this configuration to the directory examples in the Cactus home directory. If a file of the same name is already there, it will not overwrite it.
removes from a configuration all object and dependency files, as well as files generated from the CST (stands for Cactus Specification Tool, which is the set of Perl scripts which parse the thorn configuration files). Only the files generated by configure and the ThornList file remain.
rebuilds a configuration (reruns the CST).
reconfigures an existing configuration using its previous configuration options from the file configs/<config>/config-info.
runs the test programs associated with each thorn in the configuration. See section B2.6 for information about the test suite mechanism.
builds documentation for the thorns in this configuration (see section B2.5, page B32, for other targets to build documentation for thorns).
regenerates the ThornList for a configuration.
builds all utility programs provided by the thorns of a configuration. Individual utilities can be selected by giving their names (ie. name of the source file without extension) in the UTILS variable.
Cactus will try to compile all thorns listed in configs/<config>/ThornList. The ThornList file is simply a list of the form <arrangement>/<thorn>. All text after a pound sign ‘#’ or exclamation mark ‘!’ on a line is treated as a comment and ignored. If you did not specify a ThornList already, the first time that you compile a configuration you will be shown a list of all the thorns in your arrangement directory, and asked if you with to edit them. You can regenerate this list at anytime by typing
or you can edit it using
Instead of using the editor to specify the thorns you want to have compiled, you can edit the ThornList outside the make process. It is located in configs/<config>/ThornList, where <config> refers to the name of your configuration. The directory ./configs exists after the very first make phase for the first configuration.
An option for gmake can be thought of as an argument which tells it how it should make a target. Note that the final result is always the same.
turns off all prompts from the make system.
prints the commands that gmake is executing.
shows compiler warnings during compilation.
compiles in parallel, across files within each thorn.
compiles in parallel, across thorns.
Note that with more modern versions of gmake, it is sufficient to pass the normal -j <number> flag to gmake to get parallel compilation.
lists all make options.
allows you to easily checkout Cactus arrangements and thorns. For example, it can checkout all the thorns in any thornlist file found in the thornlists subdirectory of the Cactus root directory.
prints configuration options for every configuration found in user’s configs subdirectory.
creates a new configuration with a default name.
deletes your configs directory, and hence all your configurations.
removes non-essential files as documents and test suites to allow for minimal installation size.
creates a new thorn, prompting for the necessary information and creating template files.
creates an Emacs style TAGS file. See section D8 for using tags within Cactus.
creates a vi style tags file. See section D8 for using tags within Cactus.
Targets to generate Cactus documentation:
builds the documentation for the arrangement.
builds the documentation for all arrangements.
runs LaTeX to produce a copy of the Maintainers’ Guide.
runs LaTeX to produce a copy of the Reference Manual.
builds the documentation for the thorn.
builds the documentation for all thorns.
runs LaTeX to produce a copy of the Thorn Guide, for all the thorns in the arrangements directory.
runs LaTeX to produce a copy of the Users’ Guide.
creates all of the above documentations.
Some thorns come with a test suite, consisting of example parameter files and the output files generated by running these. To run the test suite for the thorns you have compiled use
gmake <configuration>--testsuite
These test suite serve the dual purpose of
i.e. making sure that changes to the thorn or the flesh don’t affect the output from a known parameter file.
i.e. checking that the results are independent of the architecture—this is also of use when trying to get Cactus to work on a new architecture.