Document the configuration.ccl file syntax and usage.

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

2 files changed, 45 insertions, 4 deletions

diff --git a/doc/UsersGuide/Appendices.tex b/doc/UsersGuide/Appendices.tex
index 4140a446..6f9def1e 100644
--- a/doc/UsersGuide/Appendices.tex
+++ b/doc/UsersGuide/Appendices.tex
@@ -217,12 +217,13 @@ int* ptr = i;     /* ptr is NOT guaranteed to be a NULL pointer! */
 \section{General Concepts}
 \label{sec:geco}
 
-Each thorn is configured by three compulsory files in the top level thorn
-directory:
+Each thorn is configured by three compulsory and one optional files in the
+top level thorn directory:
 \begin{itemize}
 \item{} {\tt interface.ccl}
 \item{} {\tt param.ccl}
 \item{} {\tt schedule.ccl}
+\item{} {\tt configuration.ccl} (optional)
 \end{itemize}
 These files are written in the {\it Cactus Configuration Language} which is
 case insensitive.
@@ -700,6 +701,21 @@ scheduling the SCHEDULE WHILE construction should be used.
 Conditional constructs cannot be used inside a schedule block.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\section{configuration.ccl}
+\label{sec:co}
+
+A configuration options file has the form:
+
+\begin{verbatim}
+Requires Thorns: <list of thorns>
+\end{verbatim}
+
+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 there are located in).
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
diff --git a/doc/UsersGuide/ThornWriters.tex b/doc/UsersGuide/ThornWriters.tex
index b1644985..e10e7e6c 100644
--- a/doc/UsersGuide/ThornWriters.tex
+++ b/doc/UsersGuide/ThornWriters.tex
@@ -120,8 +120,8 @@ the other thorns.
 \section{Thorns}
 \label{sec:th}
 
-A thorn consists of a subdirectory of an arrangement containing three
-administrative files
+A thorn consists of a subdirectory of an arrangement containing four
+administrative files:
 
 \begin{Lentry}
 \item[{\tt interface.ccl}] the cactus interface, which defines the grid
@@ -130,6 +130,8 @@ functions, variables, etc. See \ref{sec:in}.
 parameters needed from other thorns. See
 \ref{sec:pa}.
 \item[{\tt schedule.ccl}] scheduling information for routines called by
+\item[{\tt configuration.ccl}] configuration options for the thorn. See
+\ref{sec:co}.
 the flesh. See \ref{sec:sc}.
 \end{Lentry}
 
@@ -184,6 +186,9 @@ with their visibility to other implementations.
 This defines which functions from the thorn are called 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.
+
 \end{Lentry}
 
 \subsection{General syntax of CCL files}
@@ -610,6 +615,26 @@ this way at the start, a thorn could explicitly switch the storage off
 statement in schedule blocks, each group must also specify how many
 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:
+
+\begin{verbatim}
+Requires Thorns: <list of thorns>
+\end{verbatim}
+
+where {\tt <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.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{Naming Conventions for Source Files}