Document the new configuration.ccl stuff. Made note of the it not being

fully implemented yet.


git-svn-id: http://svn.cactuscode.org/flesh/trunk@3621 17b73243-c579-4c4c-a9d2-2d5706c11dac

2 files changed, 228 insertions, 38 deletions

diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index c1741e2d..aa15b2f5 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -206,14 +206,14 @@ Cactus Users' Guide and the Cactus Reference Manual.
   You get a null pointer by converting the integer constant 0 to a
   pointer type, e.g.\ \verb|int* ptr = 0;|.%%%
 \footnote{%%%
-	 Note that if you have an expression which
-	 has the value zero, but which isn't an
-  	 integer constant, converting this to a
-	 pointer type is \emph{not} guaranteed to
-	 give a NULL pointer, e.g.:\\
-	 {\tt int i = 0;}\\
-	 {\tt int* ptr = i;     /* ptr is NOT guaranteed to be a NULL pointer! */}\\
-	 }%%%
+       Note that if you have an expression which
+       has the value zero, but which isn't an
+       integer constant, converting this to a
+       pointer type is \emph{not} guaranteed to
+       give a NULL pointer, e.g.:\\
+       {\tt int i = 0;}\\
+       {\tt int* ptr = i;     /* ptr is NOT guaranteed to be a NULL pointer! */}\\
+       }%%%
 
   Many programmers prefer to use the predefined macro \verb|NULL|
   (defined in \verb|<stdlib.h>|, \verb|<stdio.h>|, and possibly other
@@ -608,7 +608,7 @@ instead.
         parameter file has been read, or on restarting from
         checkpoint.  This option relaxes this restricting, specifying that
         the parameter may be changed at recovery time from a parameter file
-	or at any time using the Flesh routine {\tt CCTK\_ParameterSet} ---
+        or at any time using the Flesh routine {\tt CCTK\_ParameterSet} ---
         see the Reference Guide.
 
 \item{} {\t ACCUMULATOR} specifies that this is an \textit{accumulator}
@@ -670,7 +670,7 @@ block).
 
 \subsection{Schedule Blocks}
 
-Each \textit{schedule block} in the file {\t schedule.ccl} must have the syntax:
+Each \textit{schedule block} in the file {\t schedule.ccl} must have the syntax
 
 \begin{alltt}
 schedule [GROUP] <\var{function name}|\var{group name}> AT|IN <\var{time}> \verb|\|
@@ -788,29 +788,143 @@ Conditional constructs cannot be used inside a schedule block.
 \section{configuration.ccl}
 \label{sec:Appendix.configuration.ccl}
 
-A configuration options file has the form:
+[{\bf NOTE:} The configuration.ccl is still relatively new, and not
+all features listed below may be fully implemented or functional.]
+
+A configuration.ccl file defines {\bf capabilities} which a thorn
+either provides or requires, or may use if available.  Unlike {\bf
+implementations}, only one thorn providing a particular capability may
+be compiled into a configuration at one time.  Thus this mechanism may
+be used to, for example: provide access to external libraries; provide
+access to functions which other thorns must call, but are too complex
+for function aliasing; or to split a thorn into several thorns, all of
+which require some common (not aliased) functions.
+
+A configuration options file can contain any number of the following
+sections:
+
+\begin{itemize}
+
+\item
+
+\begin{alltt}
+PROVIDES <\var{Capability}>
+\{
+  SCRIPT <\var{Configuration script}>
+  LANG <\var{Language}>
+\}
+\end{alltt}
+
+Informs the CST that this thorn provides a given capability, and that
+this capability has a given detection script which may be used to
+configure it (e.g. running an autoconf script or detecting an external
+library's location).  The script should output configuration
+information on its standard output --- the syntax is described below
+in sectio \ref{sec:Appendix.configuration.ccl.configscript}.  The
+script may also indicate the failure to detect a capability by
+returning a non-zero exit code;  this will stop the build after the
+CST stage.
+
+Scripts can be in any language.  If an interpreter is needed to run
+the script, for example \verb|Perl|, this should be indicated by the
+\verb|LANG| option.
+
+\item
+
+\begin{alltt}
+REQUIRES  <\var{Capability}>
+\end{alltt}
+
+Informs the CST that this thorn requires a certain capability to be
+present.  If no thorn providing the capability is in the ThornList,
+the build will stop after the CST stage.
+
+\begin{alltt}
+OPTIONAL <\var{Capability}>
+\{
+  DEFINE <\var{macro}>
+\}
+\end{alltt}
+
+Informs the CST that this thorn may use a certain capability if a
+thorn providing it is in the ThornList.  If present, the preprocessor
+macro \verb|macro| will be defined and given the value ``1''.
+
+\end{itemize}
+
+\subsection{Configuration Scripts}
+\label{sec:Appendix.configuration.ccl.configscript}
+
+The configuration script may tell the CST to add certain features to
+the Cactus environment --- either to the make system or to header
+files included by thorns.  It does this by outputing lines to its
+standard output:
+
+\begin{itemize}
+
+\item
+
+\begin{alltt}
+BEGIN DEFINE 
+<text>
+END DEFINE
+\end{alltt}
+
+Places a set of definitions in a header file which will be included by
+all thorns using this capability (either through an OPTIONAL or
+REQUIRES entry in their configuration.ccl files).
+
+\item
 
 \begin{alltt}
-Requires Thorns: <\var{list of thorns}>
+INCLUDE_DIRECTORY  <directory>
 \end{alltt}
 
-The \verb|Requires Thorns| configuration option has as its argument a
-case sensitive, space-separated list of thorn names (without the name
-of the arrangement they are located in).  This option allows this
-thorn to access global variables or call routines from the listed
-thorns.
-
-This option has the following results: The listed thorns must be
-present in the \verb|ThornList| when the thorn is compiled, and they
-must be activated whenever the requiring thorn is activated.  They are
-also guaranteed to be listed after this thorn when the linker is
-called, so that variable references and function calls can be
-resolved.
-
-Note: This option is reserved for special cases, such as when a third
-party library is incorporated into Cactus.  In order to share
-variables, you should rather declare corresponding grid variables, and
-in order to call routines, you should use rather function aliasing.
+Adds a directory to the include path used for compiling files in
+thorns using this capability.
+
+\item
+
+\begin{alltt}
+BEGIN MAKE DEFINITION 
+<text>
+END MAKE DEFINITION
+\end{alltt}
+
+Adds a makefile definition into the compilation of all thorns using
+this capability.
+
+\item
+
+\begin{alltt}
+MAKE DEPENDENCY 
+<text>
+END MAKE DEPENDENCY 
+\end{alltt}
+
+Adds makefile dependency information into the compilation of all
+thorns using this capability.
+
+\item
+
+\begin{alltt}
+LIBRARY <library>
+\end{alltt}
+
+Adds a library to the final cactus link.
+
+\item
+
+\begin{alltt}
+LIBRARY_DIRECTORY <library>
+\end{alltt}
+
+Adds a directory to the list of directories searched for libraries at
+link time.
+
+\end{itemize}
+
+No other lines should be output by the script.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index 28fa95ba..076203a1 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -188,7 +188,8 @@ This defines which functions are called from the thorn and when they are
 called. It also handles memory and communication assignment for grid variables.
 
 \item [{\tt configuration.ccl}]
-This file is optional for a thorn. If it exists it contains configuration options of this thorn such as what other thorns it requires to be compiled and activated.
+This file is optional for a thorn. If it exists it contains extra
+configuration options of this thorn.
 
 \end{Lentry}
 
@@ -630,19 +631,94 @@ timelevels to activate storage for.
 
 \subsection{The {\tt configuration.ccl}}
 \label{subsec:configuration_ccl}
-The {\tt configuration.ccl} file is optional. If it exists Cactus will obtain
-from it specific configuration options for a thorn as well as what capabilities
-it provides to or requires from other thorns.
 
-Currently there is only one option evaluated from a thorn's {\tt configuration.ccl} file:
+[{\bf NOTE:} the configuration.ccl is a new feature, and not all the
+features described in this section have been fully implemented yet.
+PROVIDES and REQUIRES should work, but script support and OPTIONAL are still
+being developed.]
+
+The {\tt configuration.ccl} file is optional.  It can be used for two
+purposes: to detect certain features of the host system, such as the
+presence or absence of libraries, variables types, etc, or the
+location of libraries; or to provide access to certain functions too
+complex or otherwise not suitable for function aliasing.
+
+The basic concept here is that a thorn can either provide or use a
+{\bf capability}.  A thorn providing a capability can specify a script
+which is run by the CST to detect features and write any configuration
+files;  the script may output lines to its standard output to inform
+the CST of features to: add to the header files included by thorns
+using this capability; add to the make files used to build thorns
+using this capability; or to the main Cactus link line.  The script
+may also indicate that this capability is not present by returning a
+non-zero exit code --- e.g., if the thorn is providing access to an
+external library, it should return an error if the library is not
+installed on the system.
+
+A thorn may either require a capability to be present, in which case
+it is an error if there is no thorn providing that capability in the
+configuration's ThornList, or it may optionally use a capability, in
+which case a macro is defined in the thorn's header file if a thorn
+providing the capability is present.
+
+A configuration.ccl file has the form:
 
 \begin{alltt}
-Requires Thorns: <\var{list of thorns}>
+PROVIDES <\var{My_Capability}>
+\{
+  SCRIPT <\var{My_ConfigScript}>
+  LANG <\var{My_Language}>
+\}
+
+REQUIRES  <\var{Another_Capability}>
+
+OPTIONAL <\var{Yet_Another_Capability}>
+\{
+  DEFINE <\var{macro}>
+\}
+
 \end{alltt}
 
-where {\tt <\var{list of thorns}>} is a space-separated list of thorns which
-this thorn requires in order to be compiled and to be activated at runtime.
-Thorns must be given by their exact names, without the arrangement name.
+which states that this thorn provides the capability
+\verb|My_Capability|, and a script \verb|MyConfigScript| should be run
+to detect features of this capability; the script is in language
+\verb|My_Language| --- the CST will use the appropriate environment or
+interpreter to invoke the script.
+
+The example requires a thorn providing \verb|Another_Capability| to be
+in the ThornList, and, if a thorn providing
+\verb|Yet_Another_Capability| is in the ThornList, the preprocessor
+macro \verb|macro| will be defined, and set to 1.  
+
+As and example a thorn A may be able to use PVM for parallelism if it is
+present, but can still work in the absence of it.  There could be a
+thorn providing PVM, and thorn A would then have
+
+\begin{alltt}
+OPTIONAL PVM
+\{
+  DEFINE HAVE_PVM
+\}
+
+\end{alltt}
+
+The code in thorn A could then have
+
+\begin{alltt}
+
+#ifdef HAVE_PVM
+  do something
+#else
+  do something else
+#endif
+
+\end{alltt}
+
+to pick the appropriate mode.
+
+The syntax of the output of the configure script is described in
+Appendix \ref{sec:Appendix.configuration.ccl.configscript}.
+
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%