diff options
| author | swhite <swhite@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 2006-02-21 15:09:35 +0000 |
|---|---|---|
| committer | swhite <swhite@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 2006-02-21 15:09:35 +0000 |
| commit | f72b64be23aa13aa7c292e8a7bc1a5a6b069b084 (patch) | |
| tree | 60ec11d39bb791d0922e2fda6f748be7831457b9 /doc/UsersGuide/RunningCactus.tex | |
| parent | 00cff78eaf6430d8058c7cecb8418687c6b5cd4d (diff) | |
Correct URL for GetCactus
Mention of MakeThornList
Updated Latex, formatting
git-svn-id: http://svn.cactuscode.org/flesh/trunk@4258 17b73243-c579-4c4c-a9d2-2d5706c11dac
Diffstat (limited to 'doc/UsersGuide/RunningCactus.tex')
| -rw-r--r-- | doc/UsersGuide/RunningCactus.tex | 772 |
1 files changed, 404 insertions, 368 deletions
diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex index 35fb0c40..ef169237 100644 --- a/doc/UsersGuide/RunningCactus.tex +++ b/doc/UsersGuide/RunningCactus.tex @@ -33,14 +33,14 @@ in single processor mode. Please refer to the architecture section operating systems known to man and can be obtained at \url{http://www.perl.org} \item[GNU make] The make - process works with the GNU make utility (referred to as {\tt gmake} + process works with the GNU make utility (referred to as \texttt{gmake} henceforth). While other make utilities may also work, this is not guaranteed. Gmake can be obtained from your favorite GNU site or from \url{http://www.gnu.org} \item[C] C compiler. For example, the GNU compiler. This is available for most supported platforms. Platform specific compilers should also work. -\item[CPP] C Preprocessor. For example, the GNU {\tt cpp}. These are +\item[CPP] C Preprocessor. For example, the GNU \texttt{cpp}. These are normally provided on most platforms, and many C compilers have an option to just run as a preprocessor. \item[CVS] The \textit{Concurrent Versions System} is not needed @@ -51,7 +51,7 @@ in single processor mode. Please refer to the architecture section \end{Lentry} \noindent -To use Cactus, with the default driver\footnote{For help with unfamiliar terms, please consult the glossary, Appendix \ref{sec:glossary}.} ({\tt CactusPUGH/PUGH}) on multiple +To use Cactus, with the default driver\footnote{For help with unfamiliar terms, please consult the glossary, Appendix \ref{sec:glossary}.} (\texttt{CactusPUGH/PUGH}) on multiple processors you also need: \begin{Lentry} \item[MPI] The \textit{Message Passing Interface} @@ -70,7 +70,7 @@ written in C++ you also need \item[C++] C++ compiler. For example, the GNU compiler. This is available for most supported platforms. Platform specific compilers should also work. Note that if a C++ compiler is available then the - {\tt main} routine in the Flesh is compiled with C++ to allow static + \text{main()} routine in the Flesh is compiled with C++ to allow static class initialisations. \end{Lentry} @@ -88,10 +88,10 @@ written in Fortran you also need While not required for compiling or running Cactus, for thorn development it is useful to install \begin{Lentry} -\item[{\tt ctags/etags}] These programs enable you browse through the +\item[\texttt{ctags/etags}] These programs enable you browse through the calling structure of a program by help of a function call database. Navigating the Flesh and arrangements becomes very easy. Emacs and - {\tt vi} both support this method. See \ref{sec:Appendix.tags} for a short + \texttt{vi} both support this method. See \ref{sec:Appendix.tags} for a short guide to tags. \end{Lentry} @@ -119,7 +119,7 @@ be found at \item[\textbf{IA32}] running Linux, OpenBSD, FreeBSD, or Windows 2000/NT. Single processor mode and MPI (MPICH and LAM) supported.\\ On Windows Cactus compiles with Cygwin. MPI (WMPI, HPVM, and MPIPro) - supported. Please read {\tt doc/README.NT} for details. + supported. Please read \texttt{doc/README.NT} for details. \item[\textbf{IA64}] running Linux. \item[\textbf{Macintosh PowerPC}] (MacOS X and Linux PPC) \item[\textbf{IBM SP2,SP3,SP4}] 32 or 64 bit running AIX. @@ -155,10 +155,10 @@ we also summarize in this appendix basic CVS commands. The space required for an installation depends on the arrangements and thorns used. The Flesh on its own requires less than 5 MB. -The script for checking out the Flesh and thorns, {\tt GetCactus}, is available -from the web site at +The script for checking out the Flesh and distribution thorns, +\texttt{GetCactus}, is available from the web site at -\url{http://www.cactuscode.org/Download/GetCactus} +\url{http://www.cactuscode.org/download/GetCactus} The script takes as an argument the name of a file containing a \textit{ThornList}, @@ -176,46 +176,53 @@ ThornLists for example applications are provided on the Cactus web site. The same script can be used to checkout additional thorns. +Another script, \texttt{MakeThornList}, can be used to produce a minimal +ThornList from a given Cactus par file. It needs a \emph{master} ThornList +to be copied into your \texttt{~\.cactus} directory. + +See \url{http://www.cactuscode.org/toolkit/makeThornList/}. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Directory structure} \label{sec:dist} -A fresh checkout creates a directory {\tt Cactus} with the +A fresh checkout creates a directory \texttt{Cactus} with the following subdirectories: \begin{Lentry} -\item[{\tt CVS}] the CVS bookkeeping directory, present in every subdirectory +\item[\texttt{CVS}] the CVS bookkeeping directory, present in every subdirectory -\item[{\tt doc}] Cactus documentation +\item[\texttt{doc}] Cactus documentation -\item[{\tt lib}] contains libraries +\item[\texttt{lib}] contains libraries -\item[{\tt src}] contains the source code for Cactus +\item[\texttt{src}] contains the source code for Cactus -\item [{\tt arrangements}] contains the Cactus arrangements. The arrangements +\item [\texttt{arrangements}] contains the Cactus arrangements. The arrangements (the actual ``physics'') are not supplied by checking out just Cactus. If the arrangements you want to use are standard Cactus arrangements, or - reside on our CVS repository ({\tt cvs.cactuscode.org}), + reside on our CVS repository (\texttt{cvs.cactuscode.org}), they can be checked out in similar way to the Flesh. \end{Lentry} -When Cactus is first compiled it creates a new directory {\tt -Cactus/configs}, which will contain all the source code, object files and -libraries created during the build process. Disk space may be a problem +When Cactus is first compiled it creates a new directory +\texttt{Cactus/configs}, which will contain all the source code, object files +and libraries created during the build process. Disk space may be a problem on supercomputers where home directories are small. A workaround is to first create a -configs directory on scratch space, say {\tt scratch/cactus\_configs/} (where -{\tt scratch/} is your scratch directory), and then either +configs directory on scratch space, say \texttt{scratch/cactus\_configs/} (where +\texttt{scratch/} is your scratch directory), and then either \begin{itemize} -\item{} set the environment variable {\tt CACTUS\_CONFIGS\_DIR} to point to +\item{} set the environment variable \texttt{CACTUS\_CONFIGS\_DIR} to point to this directory \end{itemize} or \begin{itemize} -\item{} soft link this directory ({\tt ln -s +\item{} soft link this directory (\texttt{ln -s scratch/cactus\_configs Cactus/configs/}) to the Cactus directory, if your filesystem supports soft links. \end{itemize} @@ -241,8 +248,8 @@ A description of the GNATS categories which we use is provided in the appendix % BUT, we could distribute our own, either copy cvsbug, or write a perl % version. Tom % \begin{itemize} -% \item {\tt A web interface} -% \item {\tt SendPR} +% \item \texttt{A web interface} +% \item \texttt{SendPR} % {FIXME: Mention the emacs thing here too...} % \end{itemize} @@ -256,7 +263,7 @@ A description of the GNATS categories which we use is provided in the appendix Cactus can be built in different configurations from the same copy of the source files, and these different configurations coexist in the -{\tt Cactus/configs} directory. Here are several instances in which +\texttt{Cactus/configs} directory. Here are several instances in which this can be useful: \begin{enumerate} @@ -271,23 +278,24 @@ system. collections} compiled into your executable. \end{enumerate} -Once a configuration has been created, by {\tt gmake <config>} as described -in detail in the next section, a single call to {\tt gmake <config>} -will compile the code. The first time it generates a compile -{\tt ThornList}, and gives you the chance to edit it before continuing. +Once a configuration has been created, by \texttt{gmake <\var{config}>} as +described in detail in the next section, a single call to +\texttt{gmake <\var{config}>} will compile the code. The first time it +generates a compile \texttt{ThornList}, and gives you the chance to edit +it before continuing. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Creating a configuration} \label{sec:configurations} -At its simplest, this is done by {\tt gmake <config>}\footnote +At its simplest, this is done by \texttt{gmake <\var{config}>}\footnote % {A note on the Cactus make system --- if at any point it prompts you to enter something, the default value, which will be assumed if you simply press enter, is shown in parentheses.} % . This generates a -configuration with the name {\tt config}, doing its best to +configuration with the name \texttt{\var{config}}, doing its best to automatically determine the default compilers and compilation flags suitable for the current architecture. @@ -303,36 +311,38 @@ There are three ways to pass options to the configuration process. Either: create a default configuration file \texttt{\$\{HOME\}/.cactus/config}. All available configuration options may be set in a default options file - {\tt \$\{HOME\}/.cactus/config}, any which are not set will take a default - value. The file should contain lines of the form: + \texttt{\$\{HOME\}/.cactus/config}, any which are not set will take a + default value. The file should contain lines of the form: - {\tt <option> [=] ...} + \texttt{<\var{option}> [=] ...} The equals sign is optional. Spaces are allowed everywhere. - Text starting wit a {\tt '\#'} character will be ignored as a comment. + Text starting wit a \texttt{'\#'} character will be ignored as a comment. \item[1b]{} Or: list your Cactus configuration files in an environment variable - {\tt CACTUS\_CONFIG\_FILES}: + \texttt{CACTUS\_CONFIG\_FILES}: - {\tt gmake <config>-config CACTUS\_CONFIG\_FILES=$<$list of config files$>$} + \texttt{gmake <\var{config name}>-config + CACTUS\_CONFIG\_FILES=$<$\var{list of config files}$>$} - Multiple configuration files, with their file names separated by a {\tt ':'} - character, will be processed in order. + Multiple configuration files, with their file names separated by a + \texttt{':'} character, will be processed in order. Each file should be given by its full path. - The options file has the same format as {\tt \$\{HOME\}/.cactus/config}. + The options file has the same format as \texttt{\$\{HOME\}/.cactus/config}. \item[2]{} Add the options to a configuration file and use, - {\tt gmake <config>-config options=<filename>} + \texttt{gmake <\var{config name}>-config options=<\var{filename}>} - The options file has the same format as {\tt \$\{HOME\}/.cactus/config}. + The options file has the same format as \texttt{\$\{HOME\}/.cactus/config}. \item[3]{} Pass the options individually on the command line, - {\tt gmake <configuration name>-config <option name>=<chosen value>, ...} + \texttt{gmake <\var{config name}>-config + <\var{option name}>=<\var{chosen value}>, ...} Not all configuration options can be set on the command line. Those that can be set are indicated in the table below. @@ -343,10 +353,10 @@ set on the command line will take priority over (potentially conflicting) options set in \texttt{\$\{HOME\}/.cactus/config} or other Cactus configuration files. Default options from \texttt{\$\{HOME\}/.cactus/config} will only be read if the -environment variable {\tt CACTUS\_CONFIG\_FILES} is not set. +environment variable \texttt{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 {\tt CFLAGS}. Setting any variable in the +options to the default values for \texttt{CFLAGS}. Setting any variable in the configuration file or the command line will overwrite completely the default values. @@ -363,28 +373,27 @@ If you are compiling on an architecture other than the one you are producing an executable for, you will need to pass the \begin{Lentry} - -\item [{\tt HOST\_MACHINE=x-x-x}] - +\item [\texttt{HOST\_MACHINE=\var{x-x-x}}] \end{Lentry} - -option, where x-x-x is the canonical name of the architecture you are -compiling for, such as {\tt sx6-nec-superux}; the format is {\tt - processor-vendor-OS}. +option, where \texttt{\var{x-x-x}} is the canonical name of the architecture +you are compiling for, such as \texttt{sx6-nec-superux}; the format is +\texttt{\var{processor}-\var{vendor}-\var{OS}}. \item {Compiled Thorns} 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 {\tt arrangements} directory +during configuration, a list containing all thorns in the +\texttt{arrangements} directory is automatically created, and the users prompted for any changes. \begin{Lentry} -\item [{\tt THORNLIST}] Name of file containing a list of thorns with -the syntax {\tt <arrangement name>/<thorn name>}, lines beginning with -\verb|#| or {\tt !} are ignored. +\item [\texttt{THORNLIST}] Name of file containing a list of thorns with +the syntax \texttt{<\var{arrangement name}>/<\var{thorn name}>}, lines +beginning with \verb|#| or \texttt{!} are ignored. -\item [{\tt THORNLIST\_DIR}] Location of directory containing {\tt THORNLIST}. +\item [\texttt{THORNLIST\_DIR}] Location of directory containing +\texttt{THORNLIST}. This defaults to the current working directory. @@ -396,19 +405,19 @@ These are used to specify which compilers and other tools to use. Entries follow by * may be specified on the command line. \begin{Lentry} -\item [{\tt CC}] * The C compiler. -\item [{\tt CXX}] The C++ compiler. -\item [{\tt F90}] * The Fortran 90 compiler. -\item [{\tt F77}] * The Fortran 77 compiler. -\item [{\tt CPP}] The preprocessor used to generate dependencies +\item [\texttt{CC}] * The C compiler. +\item [\texttt{CXX}] The C++ compiler. +\item [\texttt{F90}] * The Fortran 90 compiler. +\item [\texttt{F77}] * The Fortran 77 compiler. +\item [\texttt{CPP}] The preprocessor used to generate dependencies for and to preprocess C and C++ code. -\item [{\tt FPP}] The preprocessor used to generate dependencies +\item [\texttt{FPP}] The preprocessor used to generate dependencies for and to preprocess Fortran code. -\item [{\tt LD}] * The linker. -\item [{\tt AR}] The archiver used for generating libraries. -\item [{\tt RANLIB}] The archive indexer to use. -\item [{\tt MKDIR}] The program to use to create a directory. -\item [{\tt PERL}] The name of the Perl executable. +\item [\texttt{LD}] * The linker. +\item [\texttt{AR}] The archiver used for generating libraries. +\item [\texttt{RANLIB}] The archive indexer to use. +\item [\texttt{MKDIR}] The program to use to create a directory. +\item [\texttt{PERL}] The name of the Perl executable. \end{Lentry} \item {Compilation and tool flags} @@ -416,102 +425,102 @@ for and to preprocess Fortran code. Flags which are passed to the compilers and the tools. \begin{Lentry} -\item [{\tt CFLAGS}] +\item [\texttt{CFLAGS}] Flags for the C compiler. -\item [{\tt CXXFLAGS}] +\item [\texttt{CXXFLAGS}] Flags for the C++ compiler. -\item [{\tt F90FLAGS}] +\item [\texttt{F90FLAGS}] * Flags for the Fortran 90 compiler. -\item [{\tt F77FLAGS}] +\item [\texttt{F77FLAGS}] * Flags for the Fortran 77 compiler. -\item [{\tt CPPFLAGS}] +\item [\texttt{CPPFLAGS}] Flags for the preprocessor (used to generate compilation dependencies for and preprocess C and C++ code). -\item [{\tt FPPFLAGS}] +\item [\texttt{FPPFLAGS}] Flags for the preprocessor (used to generate compilation dependencies for and preprocess Fortran code). -\item [{\tt MKDIRFLAGS}] - Flags for {\tt MKDIR} so that no error is given if the directory exists. +\item [\texttt{MKDIRFLAGS}] + Flags for \texttt{MKDIR} so that no error is given if the directory exists. -\item [{\tt LDFLAGS}] +\item [\texttt{LDFLAGS}] * Flags for the linker. \emph{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 \texttt{LD} instead. -\item [{\tt ARFLAGS}] +\item [\texttt{ARFLAGS}] Flags for the archiver. -\item [{\tt C\_LINE\_DIRECTIVES}] +\item [\texttt{C\_LINE\_DIRECTIVES}] 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 {\tt yes} and {\tt -no}, the default is {\tt yes}. Set this to {\tt no} if your compiler -reports error messages about unrecognised \verb|#| directives. +created by Cactus. The only options available are \texttt{yes} and +\texttt{no}, the default is \texttt{yes}. Set this to \texttt{no} if your +compiler reports error messages about unrecognised \verb|#| directives. -\item [{\tt F\_LINE\_DIRECTIVES}] +\item [\texttt{F\_LINE\_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 {\tt yes} and {\tt -no}, the default is {\tt yes}. Set this to {\tt no} if your compiler -reports error messages about unrecognised \verb|#| directives. +created by Cactus. The only options available are \texttt{yes} and +\texttt{no}, the default is \texttt{yes}. Set this to \texttt{no} if your +compiler reports error messages about unrecognised \verb|#| directives. -\item [{\tt DISABLE\_REAL16}] Disable support for the data type {\tt - CCTK\_REAL16}. The only options available are {\tt yes} and {\tt - no}, the default is {\tt no}. Cactus autodetects this data type +\item [\texttt{DISABLE\_REAL16}] Disable support for the data type +\texttt{CCTK\_REAL16}. The only options available are \texttt{yes} and +\texttt{no}, the default is \texttt{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 {\tt CCTK\_REAL16} + does not, it may be necessary to disable \texttt{CCTK\_REAL16} altogether, since Cactus assumes that data types are fully supported if they exist. -\item [{\tt DEBUG}] +\item [\texttt{DEBUG}] * Specifies what type of debug mode should be used, the default is no debugging. -Current options are {\tt yes}, {\tt no}, or {\tt memory}. The option -{\tt yes} switches on all debugging features, whereas {\tt memory} just +Current options are \texttt{yes}, \texttt{no}, or \texttt{memory}. The option +\texttt{yes} switches on all debugging features, whereas \texttt{memory} just employs memory tracing (\ref{sec:metr}). -\item [{\tt OPTIMISE, OPTIMIZE}] +\item [\texttt{OPTIMISE, OPTIMIZE}] * Specifies what type of optimisation should be used. The only options currently -available are {\tt yes} and {\tt no}. The default is to use optimisation.\\ -Note that the British spelling {\tt OPTIMISE} will be checked first and, if set, -will override any setting of the American-spelled {\tt OPTIMIZE}. +available are \texttt{yes} and \texttt{no}. The default is to use optimisation.\\ +Note that the British spelling \texttt{OPTIMISE} will be checked first and, if set, +will override any setting of the American-spelled \texttt{OPTIMIZE}. -\item [{\tt C\_OPTIMISE\_FLAGS}] +\item [\texttt{C\_OPTIMISE\_FLAGS}] Optimisation flags for the C compiler, their use depends on the type of optimisation being used. -\item [{\tt CXX\_OPTIMISE\_FLAGS}] +\item [\texttt{CXX\_OPTIMISE\_FLAGS}] Optimisation flags for the C++ compiler, their use depends on the type of optimisation being used. -\item [{\tt F90\_OPTIMISE\_FLAGS}] +\item [\texttt{F90\_OPTIMISE\_FLAGS}] Optimisation flags for the Fortran 90 compiler, their use depends on the type of optimisation being used. -\item [{\tt F77\_OPTIMISE\_FLAGS}] +\item [\texttt{F77\_OPTIMISE\_FLAGS}] Optimisation flags for the Fortran 77 compiler, their use depends on the type of optimisation being used. -\item [{\tt C\_WARN\_FLAGS}] +\item [\texttt{C\_WARN\_FLAGS}] Warning flags for the C compiler, their use depends on the type of warnings used during compilation (\ref{sec:gmopfobuco}). -\item [{\tt CXX\_WARN\_FLAGS}] +\item [\texttt{CXX\_WARN\_FLAGS}] Warning flags for the C++ compiler, their use depends on the type of warnings used during compilation (\ref{sec:gmopfobuco}). -\item [{\tt F90\_WARN\_FLAGS}] +\item [\texttt{F90\_WARN\_FLAGS}] Warning flags for the Fortran 90 compiler, their use depends on the type of warnings used during compilation (\ref{sec:gmopfobuco}). -\item [{\tt F77\_WARN\_FLAGS}] +\item [\texttt{F77\_WARN\_FLAGS}] Warning flags for the Fortran 77 compiler, their use depends on the type of warnings used during compilation (\ref{sec:gmopfobuco}). @@ -520,11 +529,11 @@ warnings used during compilation (\ref{sec:gmopfobuco}). \item {Architecture-specific flags} \begin{Lentry} -\item [{\tt IRIX\_BITS=32|64}] For Irix SGI systems: whether to build a 32- or 64-bit configuration. +\item [\texttt{IRIX\_BITS=32|64}] For Irix SGI systems: whether to build a 32- or 64-bit configuration. \end{Lentry} \begin{Lentry} -\item [{\tt AIX\_BITS=32|64}] For IBM SP systems: whether to build a 32- or 64-bit configuration. +\item [\texttt{AIX\_BITS=32|64}] For IBM SP systems: whether to build a 32- or 64-bit configuration. \end{Lentry} \item {Library flags} @@ -532,19 +541,19 @@ warnings used during compilation (\ref{sec:gmopfobuco}). Used to specify auxiliary libraries and directories to find them in. \begin{Lentry} -\item [{\tt LIBS}] +\item [\texttt{LIBS}] Additional libraries. \emph{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 \texttt{LD} instead. -\item [{\tt LIBDIRS}] Any other library directories. +\item [\texttt{LIBDIRS}] Any other library directories. \end{Lentry} \item {Extra include directories} \begin{Lentry} -\item [{\tt SYS\_INC\_DIRS}] +\item [\texttt{SYS\_INC\_DIRS}] Used to specify any additional directories for system include files. \end{Lentry} @@ -557,19 +566,19 @@ values will be valid on all architectures. \begin{Lentry} -\item [{\tt REAL\_PRECISION}] -* Allowed values are {\tt 16, 8, 4}. +\item [\texttt{REAL\_PRECISION}] +* Allowed values are \texttt{16, 8, 4}. -\item [{\tt INTEGER\_PRECISION}] -* Allowed values are {\tt 8, 4} and {\tt 2}. +\item [\texttt{INTEGER\_PRECISION}] +* Allowed values are \texttt{8, 4} and \texttt{2}. \end{Lentry} \item {Executable name} \begin{Lentry} -\item [{\tt EXEDIR}] The directory in which to place the executable. -\item [{\tt EXE}] The name of the executable. +\item [\texttt{EXEDIR}] The directory in which to place the executable. +\item [\texttt{EXE}] The name of the executable. \end{Lentry} \item{Extra packages} @@ -579,29 +588,29 @@ Section \ref{subsec:cowiexpa}, which should be consulted for the full range of configuration options. \begin{Lentry} -\item [{\tt MPI}] * The MPI package to use, if required. Supported values are - {\tt CUSTOM}, {\tt NATIVE}, {\tt MPICH} or {\tt LAM}. +\item [\texttt{MPI}] * The MPI package to use, if required. Supported values are + \texttt{CUSTOM}, \texttt{NATIVE}, \texttt{MPICH} or \texttt{LAM}. -\item [{\tt HDF5}] -Supported values are {\tt yes, no}. A blank value is taken as {\tt no}. +\item [\texttt{HDF5}] +Supported values are \texttt{yes, no}. A blank value is taken as \texttt{no}. -\item [{\tt LAPACK}] -Supported values are {\tt yes, no}. A blank value is taken as {\tt no}. +\item [\texttt{LAPACK}] +Supported values are \texttt{yes, no}. A blank value is taken as \texttt{no}. -\item [{\tt PETSC}] -Supported values are {\tt yes, no}. A blank value is taken as {\tt no}. +\item [\texttt{PETSC}] +Supported values are \texttt{yes, no}. A blank value is taken as \texttt{no}. -\item [{\tt PTHREADS}] -Supported values are {\tt yes}. +\item [\texttt{PTHREADS}] +Supported values are \texttt{yes}. \end{Lentry} \item{Miscellaneous} \begin{Lentry} -\item [{\tt PROMPT}] Setting this to {\tt no} turns off all prompts from the +\item [\texttt{PROMPT}] Setting this to \texttt{no} turns off all prompts from the make system. -\item [{\tt SILENT}] Setting this to {\tt no} instructs {\tt gmake} to print the +\item [\texttt{SILENT}] Setting this to \texttt{no} instructs \texttt{gmake} to print the commands that it is executing. \end{Lentry} @@ -625,104 +634,104 @@ such as MPICH, LAM, WMPI, or PACX. To compile with MPI, the configure option is -{\tt MPI = <MPI\_TYPE>} +\texttt{MPI = <\var{MPI\_TYPE}>} -where {\tt <MPI\_TYPE>} can take the values (entries followed by * +where \texttt{<\var{MPI\_TYPE}>} can take the values (entries followed by * may be specified on the configuration command line): \begin{Lentry} -\item[{\tt CUSTOM}] For a custom MPI configuration set the variables +\item[\texttt{CUSTOM}] For a custom MPI configuration set the variables \begin{Lentry} - \item [{\tt MPI\_LIBS}] * libraries. - \item [{\tt MPI\_LIB\_DIRS}] * library directories. - \item [{\tt MPI\_INC\_DIRS}] * include file directories. + \item [\texttt{MPI\_LIBS}] * libraries. + \item [\texttt{MPI\_LIB\_DIRS}] * library directories. + \item [\texttt{MPI\_INC\_DIRS}] * include file directories. \end{Lentry} -\item[{\tt NATIVE}] Use the native MPI for this machine, as indicated in - the {\tt known-architectures} directory - ({\tt lib/make/known-architectures}). +\item[\texttt{NATIVE}] Use the native MPI for this machine, as indicated in + the \texttt{known-architectures} directory + (\texttt{lib/make/known-architectures}). -\item[{\tt MPICH}] +\item[\texttt{MPICH}] Use MPICH (\url{http://www-unix.mcs.anl.gov/mpi/mpich}). This is controlled by the options \begin{Lentry} - \item [{\tt MPICH\_ARCH}] * machine architecture. - \item [{\tt MPICH\_DIR} ] * directory in which MPICH is installed. + \item [\texttt{MPICH\_ARCH}] * machine architecture. + \item [\texttt{MPICH\_DIR} ] * directory in which MPICH is installed. If this option is not defined it will be searched for. - \item [{\tt MPICH\_DEVICE}] * the device used by MPICH. If not + \item [\texttt{MPICH\_DEVICE}] * the device used by MPICH. If not defined, the configuration process will search for this in a few defined places. - Supported devices are currently {\tt ch\_p4}, {\tt ch\_shmem}, - {\tt globus} and {\tt myrinet}. + Supported devices are currently \texttt{ch\_p4}, \texttt{ch\_shmem}, + \texttt{globus} and \texttt{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 {\tt MPICH\_DEVICE}, + in this order, for 1.2.0 you may need to specify \texttt{MPICH\_DEVICE}, depending on the installation. \end{Lentry} -If {\tt MPICH\_DEVICE} is chosen to be {\tt globus} +If \texttt{MPICH\_DEVICE} is chosen to be \texttt{globus} (\url{http://www.globus.org}), an additional variable must be set \begin{Lentry} - \item[{\tt GLOBUS\_LOCATION}] * directory in which Globus is installed. + \item[\texttt{GLOBUS\_LOCATION}] * directory in which Globus is installed. \end{Lentry} The Globus flavor may be chosen optionally \begin{Lentry} - \item[{\tt GLOBUS\_FLAVOR}] * Globus flavor to build Cactus with + \item[\texttt{GLOBUS\_FLAVOR}] * Globus flavor to build Cactus with \end{Lentry} If it is not set, the first Globus flavor found will be used. -If {\tt MPICH\_DEVICE} is chosen to be {\tt ch\_gm}, +If \texttt{MPICH\_DEVICE} is chosen to be \texttt{ch\_gm}, (\url{http://www.myri.com}), an additional variable must be set \begin{Lentry} - \item[{\tt MYRINET\_DIR}] * directory in which Myrinet libraries are installed. + \item[\texttt{MYRINET\_DIR}] * directory in which Myrinet libraries are installed. \end{Lentry} -\item[{\tt LAM}] -Use {\tt LAM} (\textit{Local Area Multicomputer}, \url{http://www.lam-mpi.org/}). +\item[\texttt{LAM}] +Use \texttt{LAM} (\textit{Local Area Multicomputer}, \url{http://www.lam-mpi.org/}). This is controlled by the variables \begin{Lentry} - \item[{\tt LAM\_DIR} ] * directory in which LAM is installed. This + \item[\texttt{LAM\_DIR} ] * directory in which LAM is installed. This will be searched for in a few provided places if not given. \end{Lentry} -if the {\tt LAM} installation splits libraries and include files into different -directories, instead of setting {\tt LAM\_DIR} set the two variables +if the \texttt{LAM} installation splits libraries and include files into different +directories, instead of setting \texttt{LAM\_DIR} set the two variables \begin{Lentry} - \item[{\tt LAM\_LIB\_DIR}] * directory in which LAM libraries are installed. - \item[{\tt LAM\_INC\_DIR}] * directory in which LAM include files are installed. + \item[\texttt{LAM\_LIB\_DIR}] * directory in which LAM libraries are installed. + \item[\texttt{LAM\_INC\_DIR}] * directory in which LAM include files are installed. \end{Lentry} -\item[{\tt WMPI}] +\item[\texttt{WMPI}] Use WMPI (\textit{Win32 Message Passing Interface}, \url{http://dsg.dei.uc.pt/w32mpi/intro.html}). This is controlled by the variable \begin{Lentry} - \item[{\tt WMPI\_DIR}] * directory in which WMPI is installed. + \item[\texttt{WMPI\_DIR}] * directory in which WMPI is installed. \end{Lentry} -\item[{\tt HPVM}] +\item[\texttt{HPVM}] Use HPVM (\textit{High Performance Virtual Machine}, (\url{http://www-csag.ucsd.edu/projects/hpvm.html}). This is controlled by the variable \begin{Lentry} - \item[{\tt HPVM\_DIR}] * directory in which HPVM is installed. + \item[\texttt{HPVM\_DIR}] * directory in which HPVM is installed. \end{Lentry} -\item[{\tt MPIPro}] +\item[\texttt{MPIPro}] Use MPIPro (\url{http://www.mpi-softtech.com/}). -\item[{\tt PACX}] +\item[\texttt{PACX}] Use the PACX Metacomputing package (\textit{PArallel Computer eXtension},\\ \url{http://www.hlrs.de/structure/organisation/par/projects/pacx-mpi/}). This is controlled by the variables \begin{Lentry} - \item[{\tt PACX\_DIR}] * directory in which PACX is installed. + \item[\texttt{PACX\_DIR}] * directory in which PACX is installed. If this option is not defined it will be searched for. - \item[{\tt PACX\_MPI}] * the MPI package PACX uses for node-local + \item[\texttt{PACX\_MPI}] * the MPI package PACX uses for node-local communication. This can be any of the above MPI packages. \end{Lentry} \end{Lentry} Note that the searches for libraries etc. mentioned above use the -locations given in the files in {\tt lib/make/extras/MPI}. +locations given in the files in \texttt{lib/make/extras/MPI}. \subsubsection{HDF5: Hierarchical Data Format version 5} \label{subsec:hdf5} @@ -730,19 +739,19 @@ locations given in the files in {\tt lib/make/extras/MPI}. To compile with HDF5 (\url{http://hdf.ncsa.uiuc.edu/whatishdf5.html}), the configure options are -{\tt HDF5 = yes/no [HDF5\_DIR = <dir>] [LIBZ\_DIR = <dir>] [LIBSZ\_DIR = <dir>]} +\texttt{HDF5 = yes/no [HDF5\_DIR = <\var{dir}>] [LIBZ\_DIR = <\var{dir}>] [LIBSZ\_DIR = <\var{dir}>]} -If {\tt HDF5\_DIR} is not given the configuration process will search for an +If \texttt{HDF5\_DIR} is not given the configuration process will search for an installed HDF5 package in some standard places (defined in -{\tt lib/make/extras/HDF5}). +\texttt{lib/make/extras/HDF5}). If the found HDF5 library was built with the external deflate I/O filter, -the configuration process also searches for the {\tt libz} library and adds it -to the linker flags. You may also point directly to the location of -{\tt libz.a} by setting {\tt LIBZ\_DIR}. -If the found HDF5 library was built with the external {\tt szlib} I/O filter, -the configuration process also searches for the {\tt szlib} library and adds it -to the linker flags. You may also point directly to the location of -{\tt libsz.a} by setting {\tt LIBSZ\_DIR}. +the configuration process also searches for the \texttt{libz} library and adds +it to the linker flags. You may also point directly to the location of +\texttt{libz.a} by setting \texttt{LIBZ\_DIR}. +If the found HDF5 library was built with the external \texttt{szlib} I/O filter, +the configuration process also searches for the \texttt{szlib} library and adds +it to the linker flags. You may also point directly to the location of +\texttt{libsz.a} by setting \texttt{LIBSZ\_DIR}. \subsubsection{LAPACK: Linear Algebra PACKage} @@ -750,46 +759,47 @@ to the linker flags. You may also point directly to the location of To compile with LAPACK (\url{http://www.netlib.org/lapack/}), the configure options are -\begin{verbatim} +\begin{alltt} LAPACK = yes | no | <blank> -[ LAPACK_DIR = <dir> | none ] -[ LAPACK_EXTRA_LIBS_DIRS = <dir> ] -[ LAPACK_LIBS = <libs> ] -[ LAPACK_EXTRA_LIBS = <libs> ] -\end{verbatim} +[ LAPACK\_DIR = <\var{dir}> | none ] +[ LAPACK\_EXTRA\_LIBS\_DIRS = <\var{dir}> ] +[ LAPACK\_LIBS = <\var{libs}> ] +[ LAPACK\_EXTRA\_LIBS = <\var{libs}> ] +\end{alltt} -If {\t LAPACK\_DIR} is not given the configuration process will search for a -LAPACK library {\tt liblapack.[\{a,so\}]} in some standard places (defined in -{\tt lib/make/extras/LAPACK}). If {\t LAPACK\_DIR} is set to {\tt no} the -LAPACK library path is assumed to be installed in a standard system location -(e.g. {\tt /usr/lib/}) and thus the library path will not be added to the linker's -command line. +If \texttt{LAPACK\_DIR} is not given the configuration process will search for a +LAPACK library \texttt{liblapack.[\{a,so\}]} in some standard places (defined in +\texttt{lib/make/extras/LAPACK}). If \texttt{LAPACK\_DIR} is set to \texttt{no} +the LAPACK library path is assumed to be installed in a standard system location +(e.g. \texttt{/usr/lib/}) and thus the library path will not be added to the +linker's command line. Because LAPACK doesn't come as a standardized system installation, there are additional configuration variables to set the name of the lapack library -({\t LAPACK\_LIBS}) as well as the name ({\t LAPACK\_EXTRA\_LIBS}) and location -({\t LAPACK\_EXTRA\_LIBS\_DIRS}) of extra libraries that are required by -LAPACK itself. +(\texttt{LAPACK\_LIBS}) as well as the name (\texttt{LAPACK\_EXTRA\_LIBS}) and +location (\texttt{LAPACK\_EXTRA\_LIBS\_DIRS}) of extra libraries that are +required by LAPACK itself. \subsubsection{PETSc: Portable, Extensible Toolkit for Scientific Computation} -To compile with PETSc (\url{http://www-unix.mcs.anl.gov/petsc/petsc-2/index.html}), +To compile with PETSc +(\url{http://www-unix.mcs.anl.gov/petsc/petsc-2/index.html}), the configure options are -\begin{verbatim} +\begin{alltt} PETSC = yes | no | <blank> -[ PETSC_DIR = <dir> ] -[ PETSC_ARCH = <architecture> ] -[ PETSC_ARCH_LIBS = <architecture-specific libraries> ] -\end{verbatim} +[ PETSC\_DIR = <\var{dir}> ] +[ PETSC\_ARCH = <\var{architecture}> ] +[ PETSC\_ARCH\_LIBS = <\var{architecture-specific libraries}> ] +\end{alltt} -If {\t PETSC\_DIR} is not given the configuration process will search for an +If \texttt{PETSC\_DIR} is not given the configuration process will search for an installed PETSc package in some standard places (defined in -{\tt lib/make/extras/PETSC}). -If {\t PETSC\_ARCH} is not given the configuration process will choose the -first PETSc configuration found in {\tt \$PETSC\_DIR/lib/libO/}. -If {\t PETSC\_ARCH\_LIBS} is not given the configuration process will choose +\texttt{lib/make/extras/PETSC}). +If \texttt{PETSC\_ARCH} is not given the configuration process will choose the +first PETSc configuration found in \texttt{\$PETSC\_DIR/lib/libO/}. +If \texttt{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). @@ -799,40 +809,40 @@ PETSc needs the LAPACK library). To enable multithreading support within Cactus using POSIX threads the configure option is -{\tt PTHREADS = yes} +\texttt{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 {\tt libpthread} or {\tt libpthreads}) and set preprocessor -defines necessary for compiling multithreaded code. +library (either \texttt{libpthread} or \texttt{libpthreads}) and set +preprocessor defines necessary for compiling multithreaded code. \subsection{File layout} The configuration process sets up various subdirectories and files in the -{\tt configs} directory to contain the configuration specific files, these +\texttt{configs} directory to contain the configuration specific files, these are placed in a directory with the name of the configuration. \begin{Lentry} -\item [{\tt config-data}] contains the files created by the configure +\item [\texttt{config-data}] contains the files created by the configure script: The most important ones are \begin{Lentry} -\item [{\tt make.config.defn}] +\item [\texttt{make.config.defn}] contains compilers and compilation flags for a configuration. -\item [{\tt make.extra.defn}] +\item [\texttt{make.extra.defn}] contains details about extra packages used in the configuration. -\item [{\tt cctk\_Config.h}] +\item [\texttt{cctk\_Config.h}] The main configuration header file, containing architecture specific definitions. -\item [{\tt cctk\_Archdefs.h}] +\item [\texttt{cctk\_Archdefs.h}] An architecture specific header file containing things which cannot be automatically detected, and have thus been hand-coded for this architecture. \end{Lentry} @@ -843,49 +853,49 @@ peculiarities of this configuration. In addition the following files may be informative: \begin{Lentry} -\item [{\tt fortran\_name.pl}] +\item [\texttt{fortran\_name.pl}] 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. -\item [{\tt make.config.deps}] +\item [\texttt{make.config.deps}] Initially empty. Can be edited to add extra architecture specific dependencies needed to generate the executable. -\item [{\tt make.config.rule}] -The {\tt make} rules for generating object files from source files. +\item [\texttt{make.config.rule}] +The \texttt{make} rules for generating object files from source files. \end{Lentry} -Finally, {\tt autoconf} generates the following files. +Finally, \texttt{autoconf} generates the following files. \begin{Lentry} -\item [{\tt config.log}] -A log of the {\tt autoconf} process. +\item [\texttt{config.log}] +A log of the \texttt{autoconf} process. -\item [{\tt config.status}] +\item [\texttt{config.status}] A script which may be used to regenerate the configuration. -\item [{\tt config.cache}] -An internal file used by {\tt autoconf}. +\item [\texttt{config.cache}] +An internal file used by \texttt{autoconf}. \end{Lentry} -\item [{\tt lib}] +\item [\texttt{lib}] An empty directory which will contain the libraries created for each thorn. -\item [{\tt build}] +\item [\texttt{build}] An empty directory which will contain the object files generated for this configuration, and preprocessed source files. -\item [{\tt config-info}] +\item [\texttt{config-info}] A file containing information about the configuration (including the options used to configure the configuration). -\item [{\tt bindings}] A directory which contains all the files +\item [\texttt{bindings}] A directory which contains all the files generated by the CST from the \texttt{.ccl} files. -\item [{\tt scratch}] +\item [\texttt{scratch}] A scratch directory which is used to accommodate Fortran 90 modules. \end{Lentry} @@ -896,70 +906,82 @@ A scratch directory which is used to accommodate Fortran 90 modules. Once you have created a new configuration, the command \\ \\ -{\tt gmake <configuration name>} +\texttt{gmake <\var{configuration name}>} \\ \\ will build an executable, prompting you along the way for the -thorns which should be included. There is a range of {\tt gmake} +thorns which should be included. There is a range of \texttt{gmake} targets and options which are detailed in the following sections. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{gmake targets for building and administering configurations} \label{sec:gmtafobuanadco} -A target for {\tt gmake} can be naively thought of as an argument -that tells it which of several things listed in the {\tt Makefile} it -is to do. The command {\tt gmake help} lists all {\tt gmake} targets: +A target for \texttt{gmake} can be naively thought of as an argument +that tells it which of several things listed in the \texttt{Makefile} it +is to do. The command \texttt{gmake help} lists all \texttt{gmake} targets: % colon clarifies that all (config) targets are listed here \begin{Lentry} -\item [{\tt gmake <config>}] +\item [\texttt{gmake <\var{config}>}] builds a configuration. If the configuration doesn't exist it will create it. -\item [{\tt gmake <config>-clean}] removes all object and dependency files from - a configuration. +\item [\texttt{gmake <\var{config}>-clean}] removes all object and dependency +files from a configuration. -\item [{\tt gmake <config>-cleandeps}] removes all dependency files from - a configuration. +\item [\texttt{gmake <\var{config}>-cleandeps}] removes all dependency files +from a configuration. -\item [{\tt gmake <config>-cleanobjs}] removes all object files from +\item [\texttt{gmake <\var{config}>-cleanobjs}] removes all object files from a configuration. -\item [{\tt gmake <config>-config}] creates a new configuration or reconfigures an existing one overwriting any previous configuration options.\\ - The configuration options are stored in a file {\tt configs/<config>/config-info}. +\item [\texttt{gmake <\var{config}>-config}] creates a new configuration or +reconfigures an existing one overwriting any previous configuration options.\\ +The configuration options are stored in a file +\texttt{configs/<\var{config}>/config-info}. -\item [{\tt gmake <config>-configinfo}] displays the options used to configure a configuration ({\tt cat configs/<config>/config-info}). +\item [\texttt{gmake <\var{config}>-configinfo}] displays the options +of the configuration (\texttt{cat configs/<\var{config}>/config-info}). -\item[{\tt gmake <config>-cvsupdate}] updates the Flesh and this configuration's thorns from the CVS repositories. +\item[\texttt{gmake <\var{config}>-cvsupdate}] updates the Flesh and this +configuration's thorns from the CVS repositories. -\item [{\tt gmake <config>-delete}] deletes a configuration ({\tt rm -r configs/<config>}). +\item [\texttt{gmake <\var{config}>-delete}] deletes a configuration +(\texttt{rm -r configs/<\var{config}>}). -\item [{\tt gmake <config>-editthorns}] edits the ThornList. +\item [\texttt{gmake <config>-editthorns}] edits the ThornList. -\item [{\tt gmake <config>-examples}] copies all the example parameter files relevant for this configuration to the directory {\tt examples} in the Cactus home directory. If a file of the same name is already there, it will not overwrite it. +\item [\texttt{gmake <\var{config}>-examples}] copies all the example parameter files relevant for this configuration to the directory \texttt{examples} in the Cactus home directory. If a file of the same name is already there, it will not overwrite it. -\item [{\tt gmake <config>-realclean}] removes from a configuration +\item [\texttt{gmake <\var{config}>-realclean}] removes from a configuration all object and dependency files, as well as files generated from the CST (stands for \textit{Cactus Specification Tool}, which is the set of Perl scripts which parse the thorn configuration files). Only the files generated -by configure and the {\tt ThornList} file remain. +by configure and the \texttt{ThornList} file remain. -\item [{\tt gmake <config>-rebuild}] rebuilds a configuration (reruns the CST). +\item [\texttt{gmake <\var{config}>-rebuild}] rebuilds a configuration (reruns the CST). -\item [{\tt gmake <config>-reconfig}] reconfigures an existing configuration using its previous configuration options from the file {\tt configs/<config>/config-info}. +\item [\texttt{gmake <\var{config}>-reconfig}] reconfigures an existing +configuration using its previous configuration options from the file +\texttt{configs/<\var{config}>/config-info}. -\item [{\tt gmake <config>-testsuite}] runs the test programs associated with - each thorn in the configuration. See section \ref{sec:testing} for information - about the test suite mechanism. +\item [\texttt{gmake <\var{config}>-testsuite}] runs the test programs +associated with each thorn in the configuration. See section +\ref{sec:testing} for information about the test suite mechanism. -\item[{\tt gmake <config>-ThornGuide}] builds documentation for the thorns -in this configuration - (see section \ref{sec:OtherGmakeTargetsDoc} on page \pageref{sec:OtherGmakeTargetsDoc} for other targets to build documentation for thorns). +\item[\texttt{gmake <\var{config}>-ThornGuide}] builds documentation for the +thorns in this configuration + (see section \ref{sec:OtherGmakeTargetsDoc} on page + \pageref{sec:OtherGmakeTargetsDoc} for other targets to build documentation + for thorns). -\item [{\tt gmake <config>-thornlist}] regenerates the {\tt ThornList} for a configuration. +\item [\texttt{gmake <\var{config}>-thornlist}] regenerates the +\texttt{ThornList} for a configuration. -\item [{\tt gmake <config>-utils [UTILS$=$<list>]}] builds all utility programs provided by the thorns of a configuration. Individual utilities can be selected by giving their names in the {\tt UTILS} variable. +\item [\texttt{gmake <\var{config}>-utils [UTILS$=$<\var{list}>]}] builds all +utility programs provided by the thorns of a configuration. Individual +utilities can be selected by giving their names in the \texttt{UTILS} variable. \end{Lentry} @@ -969,10 +991,10 @@ in this configuration \label{sec:cointh} Cactus will try to compile all thorns listed in -{\tt configs/<config>/ThornList}. -The {\tt ThornList} file is simply a list of the form -{\tt <arrangement>/<thorn>}. All text after a pound sign `{\tt \#}' or -exclamation mark `{\tt !}' +\texttt{configs/<\var{config}>/ThornList}. +The \texttt{ThornList} file is simply a list of the form +\texttt{<\var{arrangement}>/<\var{thorn}>}. All text after a pound sign +`\texttt{\#}' or exclamation mark `\texttt{!}' on a line is treated as a comment and ignored. The first time that you compile a configuration, if you did not specify a ThornList already during configuration, @@ -991,43 +1013,47 @@ gmake <\var{config}>-editthorns \end{alltt} Instead of using the editor to specify the thorns you want to - have compiled, you can \emph{edit} the {\tt ThornList} outside - the make process. It is located in {\tt configs/<config>/ThornList}, - where {\tt <config>} refers to the name of your configuration. - The directory, {\tt ./configs}, exists \emph{ after} the very first + have compiled, you can \emph{edit} the \texttt{ThornList} outside + the make process. It is located in \texttt{configs/<\var{config}>/ThornList}, + where \texttt{<\var{config}>} refers to the name of your configuration. + The directory, \texttt{./configs}, exists \emph{ after} the very first make phase for the first configuration. \subsection{Notes and Caveats} \begin{itemize} -\item{} If during the build you see the error ``{\tt missing +\item{} If during the build you see the error ``\texttt{missing separator}'' you are probably not using GNU make. \item{} \textit{The EDITOR environment variable}. You may not be aware of this, but this thing very often exists and may be set by default to - something scary like {\tt vi}. If you don't know how to use {\tt vi} + something scary like \texttt{vi}. If you don't know how to use \texttt{vi} or wish to use your favorite editor instead, reset this environment variable. - (To exit {\tt vi} type {\tt <ESC> :q!}) + (To exit \texttt{vi} type \texttt{<ESC> :q!}) \end{itemize} -\subsection{{\tt gmake} options for building configurations} +\subsection{\texttt{gmake} options for building configurations} \label{sec:gmopfobuco} -An \textit{option} for {\tt gmake} can be thought of as an argument which tells +An \textit{option} for \texttt{gmake} can be thought of as an argument which tells it how it should make a \textit{target}. Note that the final result is always the same. \begin{Lentry} -\item [{\tt gmake <target> PROMPT=no}] turns off all prompts from the +\item [\texttt{gmake <\var{target}> PROMPT=no}] turns off all prompts from the make system. -\item [{\tt gmake <target> SILENT=no}] print the commands that gmake is executing. -\item [{\tt gmake <target> WARN=yes}] show compiler warnings during compilation. -\item [{\tt gmake <target> FJOBS=<number>}] compile in parallel, across files within each thorn. -\item [{\tt gmake <target> TJOBS=<number>}] compile in parallel, across thorns. +\item [\texttt{gmake <\var{target}> SILENT=no}] print the commands that gmake +is executing. +\item [\texttt{gmake <\var{target}> WARN=yes}] show compiler warnings during +compilation. +\item [\texttt{gmake <\var{target}> FJOBS=<\var{number}>}] compile in parallel, +across files within each thorn. +\item [\texttt{gmake <\var{target}> TJOBS=<\var{number}>}] compile in parallel, +across thorns. \end{Lentry} -Note that with more modern versions of gmake, it is sufficient to pass the normal - {\tt -j <number>} flag to gmake to get parallel compilation. +Note that with more modern versions of gmake, it is sufficient to pass the +normal \texttt{-j <\var{number}>} flag to gmake to get parallel compilation. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1039,36 +1065,36 @@ Note that with more modern versions of gmake, it is sufficient to pass the norma \begin{Lentry} -\item [{\tt gmake help}] lists all make options. +\item [\texttt{gmake help}] lists all make options. -\item [{\tt gmake checkout}] allows you to easily checkout Cactus +\item [\texttt{gmake checkout}] allows you to easily checkout Cactus arrangements and thorns. For example it can checkout all the thorns in any thornlist file found in the \texttt{thornlists} subdirectory of the Cactus root directory. % (usually \texttt{Cactus}). -\item [{\tt gmake cvsdiff}] shows differences between checked out version of Cactus and that in the CVS repositories. +\item [\texttt{gmake cvsdiff}] shows differences between checked out version of Cactus and that in the CVS repositories. -\item [{\tt gmake cvsstatus}] shows status of checked out version of Cactus, reporting which files have been modified or need updating. +\item [\texttt{gmake cvsstatus}] shows status of checked out version of Cactus, reporting which files have been modified or need updating. -\item [{\tt gmake cvsupdate}] updates Flesh and all thorns from CVS repositories. +\item [\texttt{gmake cvsupdate}] updates Flesh and all thorns from CVS repositories. -\item [{\tt gmake configinfo}] prints configuration options for every +\item [\texttt{gmake configinfo}] prints configuration options for every configuration found in user's \texttt{configs} subdirectory. -\item [{\tt gmake default}] creates a new configuration with a default name. +\item [\texttt{gmake default}] creates a new configuration with a default name. -\item [{\tt gmake distclean}] deletes your {\tt configs} directory and hence all your configurations. +\item [\texttt{gmake distclean}] deletes your \texttt{configs} directory and hence all your configurations. -\item [{\tt gmake downsize}] removes non-essential files as documents +\item [\texttt{gmake downsize}] removes non-essential files as documents and test suites to allow for minimal installation size. -\item [{\tt gmake newthorn}] creates a new thorn, prompting for the necessary +\item [\texttt{gmake newthorn}] creates a new thorn, prompting for the necessary information and creating template files. -\item [{\tt gmake TAGS}] creates an Emacs style TAGS file. See section +\item [\texttt{gmake TAGS}] creates an Emacs style TAGS file. See section \ref{sec:Appendix.tags} for using tags within Cactus. -\item [{\tt gmake tags}] creates a {\tt vi} style tags file. See section +\item [\texttt{gmake tags}] creates a \texttt{vi} style tags file. See section \ref{sec:Appendix.tags} for using tags within Cactus. \end{Lentry} @@ -1078,23 +1104,30 @@ configuration found in user's \texttt{configs} subdirectory. \begin{Lentry} -\item[{\tt gmake <arrangement>-ArrangementDoc}] builds the documentation for the arrangement. +\item[\texttt{gmake <\var{arrangement}>-ArrangementDoc}] builds the +documentation for the arrangement. -\item[{\tt gmake ArrangementDoc}] builds the documentation for all arrangements. +\item[\texttt{gmake ArrangementDoc}] builds the documentation for all +arrangements. -\item [{\tt gmake MaintGuide}] runs LaTeX to produce a copy of the Maintainers' Guide. +\item [\texttt{gmake MaintGuide}] runs LaTeX to produce a copy of the +Maintainers' Guide. -\item [{\tt gmake ReferenceManual}] runs LaTeX to produce a copy of the Reference Manual. +\item [\texttt{gmake ReferenceManual}] runs LaTeX to produce a copy of the +Reference Manual. -\item[{\tt gmake <thorn>-ThornDoc}] builds the documentation for the thorn. +\item[\texttt{gmake <\var{thorn}>-ThornDoc}] builds the documentation for the +thorn. -\item[{\tt gmake ThornDoc}] builds the documentation for all thorns. +\item[\texttt{gmake ThornDoc}] builds the documentation for all thorns. -\item [{\tt gmake ThornGuide}] runs LaTeX to produce a copy of the Thorn Guide, for all the thorns in the arrangements directory. +\item [\texttt{gmake ThornGuide}] runs LaTeX to produce a copy of the Thorn +Guide, for all the thorns in the arrangements directory. -\item [{\tt gmake UsersGuide}] runs LaTeX to produce a copy of the Users' Guide. +\item [\texttt{gmake UsersGuide}] runs LaTeX to produce a copy of the Users' +Guide. -\item [{\tt gmake AllDoc}] creates all of the above documentations. +\item [\texttt{gmake AllDoc}] creates all of the above documentations. \end{Lentry} @@ -1106,7 +1139,7 @@ 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 -{\tt gmake <configuration>-testsuite} +\texttt{gmake <\var{configuration}>-testsuite} These test suite serve the dual purpose of @@ -1130,16 +1163,17 @@ specifies which thorns to use and sets the values of any parameters which are different from the default values. There is no restriction on the name of the parameter file, although it is conventional to use the file -extension {\tt .par}. Optional command line arguments can be used +extension \texttt{.par}. Optional command line arguments can be used to customise runtime behaviour, and to provide information about the thorns used in the executable. The general syntax for running Cactus from a parameter file is then -{\tt ./cactus\_<config> <parameter file> [command line options]} +\texttt{./cactus\_<\var{config}> <\var{parameter file}> +[\var{command line options}]} or if the parameter file should be taken from standard input -{\tt ./cactus\_<config> [command line options] -} +\texttt{./cactus\_<\var{config}> [\var{command line options}] -} The remainder of this chapter covers all aspects for running your Cactus executable. These include: command line options, parameter @@ -1151,20 +1185,20 @@ creating thorn documentation. The Cactus executable accepts numerous command line arguments: -{\tt +\texttt{ \begin{tabular}{|l|l|} \hline Short Version & Long Version \\ \hline -O[v] & -describe-all-parameters \\ \hline - -o<param> & -describe-parameter=<param> \\ + -o<\var{param}> & -describe-parameter=<\var{param}> \\ \hline -S & -print-schedule\\ \hline -T & -list-thorns\\ \hline - -t<arrangement/thorn>& -test-thorn-compiled=<arrangement/thorn>\\ + -t<\var{arrangement/thorn}>& -test-thorn-compiled=<\var{arrangement/thorn}>\\ \hline -h,-? & -help\\ \hline @@ -1172,76 +1206,78 @@ Short Version & Long Version \\ \hline % -x [<nprocs>] & -test-parameters [<nprocs>] \\ %\hline - -L<level> & -logging-level=<level> \\ + -L<\var{level}> & -logging-level=<\var{level}> \\ \hline - -W<level> & -warning-level=<level> \\ + -W<\var{level}> & -warning-level=<\var{level}> \\ \hline - -E<level> & -error-level=<level> \\ + -E<\var{level}> & -error-level=<\var{level}> \\ \hline -r[o|e|oe|eo] & -redirect=[o|e|oe|eo]\\ \hline -i & -ignore-next \\ \hline - & -parameter-level=<level> \\ + & -parameter-level=<\var{level}> \\ \hline \end{tabular} } \begin{Lentry} -\item [{\tt -O} or {\tt -describe-all-parameters}] +\item [\texttt{-O} or \texttt{-describe-all-parameters}] Produces a full list of all parameters from all thorns which were compiled, along with descriptions and allowed values. This can take an optional extra -parameter {\tt v} (i.e. {\tt -Ov} to give verbose information about +parameter \texttt{v} (i.e. \texttt{-Ov} to give verbose information about all parameters). -\item [{\tt -o<param>} or {\tt -describe-parameter=<param>}] +\item [\texttt{-o<\var{param}>} or \texttt{-describe-parameter=<\var{param}>}] Produces the description and allowed values for a given parameter --- takes one argument. -\item [{\tt -S} or {\tt -print-schedule}] +\item [\texttt{-S} or \texttt{-print-schedule}] Print only the schedule tree. -\item [{\tt -T} or {\tt -list-thorns}] +\item [\texttt{-T} or \texttt{-list-thorns}] Produces a list of all the thorns which were compiled in. -\item [{\tt -t<arrangement or thorn>} or {\tt -test-thorn-compiled=<arrangement or thorn>} ] +\item [\texttt{-t<\var{arrangement or thorn}>} or \texttt{-test-thorn-compiled=<\var{arrangement or thorn>}} ] Checks if a given thorn was compiled in --- takes one argument. -\item [{\tt -h}, {\tt -?} or {\tt -help}] +\item [\texttt{-h}, \texttt{-?} or \texttt{-help}] Produces a help message. -\item [{\tt -v} or {\tt -version}] +\item [\texttt{-v} or \texttt{-version}] Produces version information of the code. -%\item [{\tt -x <nprocs>} or {\tt -test-parameters <nprocs>}] +%\item [\texttt{-x <nprocs>} or \texttt{-test-parameters <nprocs>}] %Runs the code far enough to check the consistency of the parameters. If %given a numeric argument it will attempt to simulate being on that number %of processors. [To be implemented.] -\item [{\tt -L<level>} or {\tt -logging-level=<level>}] +\item [\texttt{-L<\var{level}>} or \texttt{-logging-level=<\var{level}>}] Sets the logging level of the code. All warning messages are given a level --- the lower the level the greater the severity. This -parameter {\tt -L} controls the level of messages to be seen, with all -warnings of level $\le$ {\tt <level>} printed to standard output. The +parameter \texttt{-L} controls the level of messages to be seen, with all +warnings of level $\le$ \texttt{<\var{level}>} printed to standard output. The default is a logging level of~0, meaning that only level~0 messages should be printed to standard output. -\item [{\tt -W<level>} or {\tt -warning-level=<level>}] -This is similar to {\tt -W}, but for standard error instead of -standard output. All warnings of level $\le$ {\tt <level>} are +\item [\texttt{-W<\var{level}>} or \texttt{-warning-level=<\var{level}>}] +This is similar to \texttt{-W}, but for standard error instead of +standard output. All warnings of level $\le$ \texttt{<\var{level}>} are printed to standard error. The default is a warning level of~1, meaning that level~0 and level~1 messages should be printed to standard error. -\item [{\tt -E<level} or {\tt -error-level=<level>}] -This is similar to {\tt -W}, but for fatal errors: Cactus treats all -warnings with level $\le$ {\tt <level>} as fatal errors, and aborts +\item [\texttt{-E<\var{level}} or \texttt{-error-level=<\var{level}>}] +This is similar to \texttt{-W}, but for fatal errors: Cactus treats all +warnings with level $\le$ \texttt{<\var{level}>} as fatal errors, and aborts the Cactus run immediately (after printing the warning message%%% \footnote{%%% Cactus imposes the constraints that - $\hbox{the {\tt -W} level} \ge \hbox{the {\tt -E} level} \ge 0$, + $\hbox{the \texttt{-W} level} \ge \hbox{the \texttt{-E} level} \ge 0$, so any fatal-error message will always be printed (first). }%%% ). The default value is zero, \ie{} only level~0 warnings will abort the Cactus run. -\item [{\tt -r[o|e|oe|eo]} or {\tt -redirect=[o|e|oe|eo]}] +\item [\texttt{-r[o|e|oe|eo]} or \texttt{-redirect=[o|e|oe|eo]}] This redirects the standard output (`\texttt{o}') and/or standard error (`\texttt{e}') of each processor to a file. By default the standard outputs from processors other than processor 0 are discarded. -\item [{\tt -i} or {\tt -ignore-next}] +\item [\texttt{-i} or \texttt{-ignore-next}] Ignore the next argument on the command line. -\item [{\tt -parameter-level=<level>}] -Set the level of parameter checking to be used, either {\tt strict}, {\tt normal} (the default), or {\tt relaxed}. See Section~\ref{sec:Parameter_File}. +\item [\texttt{-parameter-level=<\var{level}>}] +Set the level of parameter checking to be used, one of \texttt{strict}, +\texttt{normal} (the default), or \texttt{relaxed}. +See Section~\ref{sec:Parameter_File}. \end{Lentry} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -1252,45 +1288,45 @@ Set the level of parameter checking to be used, either {\tt strict}, {\tt normal A \textit{parameter file} ( or \textit{par file}) is used to control the behaviour of a Cactus executable. It specifies initial values for parameters -as defined in the various thorns' {\tt param.ccl} files +as defined in the various thorns' \texttt{param.ccl} files (see Chapter~\ref{chap:Cactus_parameters}). -The name of a parameter file is often given the suffix {\tt .par}, but +The name of a parameter file is often given the suffix \texttt{.par}, but this is not mandatory. A parameter file is a text file whose lines are either comments or parameter statements. Comments are blank lines or lines that begin with either -`{\tt \#}' or `{\tt !}'. +`\texttt{\#}' or `\texttt{!}'. A parameter statement consists of one or more parameter names, followed by -an `{\tt =}', followed by the value(s) for this (these) parameter(s). +an `\texttt{=}', followed by the value(s) for this (these) parameter(s). Note that all string parameters are case insensitive. -The first parameter statement in any parameter file should set {\tt ActiveThorns}, +The first parameter statement in any parameter file should set \texttt{ActiveThorns}, which is a special parameter that tells the program which \textit{thorns} are to be activated. Only parameters from active thorns can be set (and only those routines \textit{scheduled} by active thorns are run). By default all thorns are inactive. For example, the first entry in a parameter file which is using just the two thorns -{\tt CactusPUGH/PUGH} and {\tt CactusBase/CartGrid3D} should be +\texttt{CactusPUGH/PUGH} and \texttt{CactusBase/CartGrid3D} should be -{\tt ActiveThorns = "PUGH CartGrid3D"} +\texttt{ActiveThorns = "PUGH CartGrid3D"} -Parameters following the {\tt ActiveThorns} parameter all have names +Parameters following the \texttt{ActiveThorns} parameter all have names whose syntax depends on the scope (see Section~\ref{sec:Cactus_parameters.scope}) of the parameter: \begin{Lentry} -\item [{\tt Global parameters}] +\item [\texttt{Global parameters}] Just the name of the parameter itself. Global parameters are to be avoided; there are none in the Flesh and Cactus Toolkits. -\item [{\tt Restricted parameters}] +\item [\texttt{Restricted parameters}] The name of the \textit{implementation} which defined the parameter, followed by two colons, -then the name of the parameter --- e.g. {\tt driver::global\_nx}. -\item [{\tt Private parameters}] +then the name of the parameter --- e.g. \texttt{driver::global\_nx}. +\item [\texttt{Private parameters}] The name of the \textit{thorn} which defined the parameter, two colons, -and the name of the parameter --- e.g. {\tt wavetoyF77::amplitude}. +and the name of the parameter --- e.g. \texttt{wavetoyF77::amplitude}. \end{Lentry} This notation is not currently strictly enforced in the code. It is @@ -1300,31 +1336,31 @@ that the above convention be followed. The Cactus Flesh performs checks for consistency and range of parameters. The severity of these checks is controlled by the command line argument -{\tt -parameter-level} which can take the following values +\texttt{-parameter-level} which can take the following values \begin{Lentry} -\item[{\tt relaxed}] Cactus will issue a level 0 warning (that is the +\item[\texttt{relaxed}] Cactus will issue a level 0 warning (that is the default behaviour will be to terminate) if \begin{itemize} \item{} The specified parameter value is outside of the allowed range. \end{itemize} -\item [{\tt normal}] +\item [\texttt{normal}] This is the default, and provides the same warnings as the -{\tt relaxed} level, with in addition a level 0 warning issued for +\texttt{relaxed} level, with in addition a level 0 warning issued for \begin{itemize} -\item{} An implementation and/or thorn {\tt foo} is active, but the - parameter {\tt foo::bar} was not defined. -\item{} The parameter {\tt foo::bar} was successfully set for both an - active implementation {\tt foo} not implemented by a thorn {\tt foo}, - and to a thorn {\tt foo}. +\item{} An implementation and/or thorn \texttt{foo} is active, but the + parameter \texttt{foo::bar} was not defined. +\item{} The parameter \texttt{foo::bar} was successfully set for both an + active implementation \texttt{foo} not implemented by a thorn \texttt{foo}, + and to a thorn \texttt{foo}. \end{itemize} -\item [{\tt strict}] -This provides the same warnings as the {\tt normal} level, with in +\item [\texttt{strict}] +This provides the same warnings as the \texttt{normal} level, with in addition a level 0 warning issued for \begin{itemize} -\item{} The parameter {\tt foo::bar} is specified in the parameter file, - but no implementation or thorn with the name {\tt bar} is active. +\item{} The parameter \texttt{foo::bar} is specified in the parameter file, + but no implementation or thorn with the name \texttt{bar} is active. \end{itemize} \end{Lentry} @@ -1333,20 +1369,20 @@ Notes: \begin{itemize} \item{} You can obtain lists of the parameters associated with -each thorn using the command line options {\tt -o} and {\tt -O} +each thorn using the command line options \texttt{-o} and \texttt{-O} (Section~\ref{sec:command_line_options}). \item{} The parameter file is read \emph{sequentially} from top to bottom, this means that if you set the value of a parameter twice in the parameter file, the second value will be used. (This is - why the {\tt ActiveThorns} parameter is always first in the file). + why the \texttt{ActiveThorns} parameter is always first in the file). \item{} Some parameters are \textit{steerable} and can be changed during the execution of a Cactus program using parameter steering interfaces - For example, thorn {\tt CactusConnect/HTTPD}, or using a + For example, thorn \texttt{CactusConnect/HTTPD}, or using a parameter file when recovering from a checkpoint file. -\item{} For examples of parameter files, look in the {\tt par} directory +\item{} For examples of parameter files, look in the \texttt{par} directory which can be found in most thorns. \end{itemize} @@ -1362,14 +1398,14 @@ but the Thorn Guide is a good place to first look for special instructions on how to run and interpret the output from a Thorn. Details about parameters, grid variables and scheduling are automatically included in from a thorns CCL files into the Thorn -Guide. To construct a Thorn Guide for the configuration {\tt -$<$config$>$} use +Guide. To construct a Thorn Guide for the configuration +\texttt{$<$\var{config}$>$} use -{\tt gmake $<$config$>$-ThornGuide} +\texttt{gmake $<$\var{config}$>$-ThornGuide} -or to make a Thorn Guide for all the thorns in the {\tt arrangements} directory +or to make a Thorn Guide for all the thorns in the \texttt{arrangements} directory -{\tt gmake $<$config$>$}. +\texttt{gmake $<$\var{config}$>$}. See Section~\ref{sec:Adding_documentation} for a guide to adding documentation to your own thorns. @@ -1394,7 +1430,7 @@ As the program runs, the normal output provides the following information: \begin{Lentry} \item [Active thorns] - A report is made as each of the thorns in the {\tt ActiveThorns} + A report is made as each of the thorns in the \texttt{ActiveThorns} parameters from the parameter file (see Section~\ref{sec:Parameter_File}) is attempted to be activated. This report shows whether the thorn activation was successful, and if successful gives the |