diff --git a/doc/documentation.tex b/doc/documentation.tex index feec262..184bd9a 100644 --- a/doc/documentation.tex +++ b/doc/documentation.tex @@ -1,3 +1,73 @@ +% *======================================================================* +% Cactus Thorn template for ThornGuide documentation +% Author: Ian Kelley +% Date: Sun Jun 02, 2002 +% $Header$ +% +% Thorn documentation in the latex file doc/documentation.tex +% will be included in ThornGuides built with the Cactus make system. +% The scripts employed by the make system automatically include +% pages about variables, parameters and scheduling parsed from the +% relevant thorn CCL files. +% +% This template contains guidelines which help to assure that your +% documentation will be correctly added to ThornGuides. More +% information is available in the Cactus UsersGuide. +% +% Guidelines: +% - Do not change anything before the line +% % START CACTUS THORNGUIDE", +% except for filling in the title, author, date, etc. fields. +% - Each of these fields should only be on ONE line. +% - Author names should be separated with a \\ or a comma. +% - You can define your own macros, but they must appear after +% the START CACTUS THORNGUIDE line, and must not redefine standard +% latex commands. +% - To avoid name clashes with other thorns, 'labels', 'citations', +% 'references', and 'image' names should conform to the following +% convention: +% ARRANGEMENT_THORN_LABEL +% For example, an image wave.eps in the arrangement CactusWave and +% thorn WaveToyC should be renamed to CactusWave_WaveToyC_wave.eps +% - Graphics should only be included using the graphicx package. +% More specifically, with the "\includegraphics" command. Do +% not specify any graphic file extensions in your .tex file. This +% will allow us to create a PDF version of the ThornGuide +% via pdflatex. +% - References should be included with the latex "\bibitem" command. +% - Use \begin{abstract}...\end{abstract} instead of \abstract{...} +% - Do not use \appendix, instead include any appendices you need as +% standard sections. +% - For the benefit of our Perl scripts, and for future extensions, +% please use simple latex. +% +% *======================================================================* +% +% Example of including a graphic image: +% \begin{figure}[ht] +% \begin{center} +% \includegraphics[width=6cm]{MyArrangement_MyThorn_MyFigure} +% \end{center} +% \caption{Illustration of this and that} +% \label{MyArrangement_MyThorn_MyLabel} +% \end{figure} +% +% Example of using a label: +% \label{MyArrangement_MyThorn_MyLabel} +% +% Example of a citation: +% \cite{MyArrangement_MyThorn_Author99} +% +% Example of including a reference +% \bibitem{MyArrangement_MyThorn_Author99} +% {J. Author, {\em The Title of the Book, Journal, or periodical}, 1 (1999), +% 1--16. {\tt http://www.nowhere.com/}} +% +% *======================================================================* + +% If you are using CVS use this line to give version information +% $Header$ + \documentclass{article} % Use the Cactus ThornGuide style file @@ -8,14 +78,62 @@ \begin{document} -\title{ExternalLibraries/MPI} +% The author of the documentation +\author{Federico Cipolletta, Roland Haas} + +% The title of the document (not necessarily the name of the Thorn) +\title{MPI} + +% the date your document was last changed, if your document is in CVS, +% please use: +% \date{$ $Date$ $} +% when using git instead record the commit ID: +% \date{$ $Id$ $} +% and add this line to your repos' .gitattributes file: +% **.tex ident +\date{2020-07-01} \maketitle % Do not delete next line % START CACTUS THORNGUIDE +% Add all definitions used in this documentation here +% \def\mydef etc + +% Add an abstract for this thorn's documentation +\begin{abstract} +This thorn provides access to the MPI library. +\end{abstract} + +% The following sections are suggestive only. +% Remove them or add your own. + +\section{Using This Thorn} + +Refer to the Cactus UserGuide, Sec. B2.2, in order to know how this thorn can be used in a compiled configuration and how to possibly linking another specific version, already installed steparately. + +\subsection*{Note on possible ExternalLibraries' location stripping} +\label{stripping} + +Each thorn contained in \texttt{Cactus/arrangements/ExternalLibraries} will automatically adopt the library version contained in the \texttt{Cactus/arrangements//dist} folder. In particular, the tarball in \texttt{Cactus/arrangements//dist} is only used if either \texttt{THORN\_DIR} is set to \texttt{BUILD} or is left empty and no precompiled copy of the library is found. If another location is specified via the \texttt{THORN\_DIR} variable in the \texttt{.cfg} file at compilation, then the \texttt{Cactus/lib/sbin/strip-incdirs.sh} script will automatically strip away (for safety reasons) the locations: +\begin{Lentry} +\item [\texttt{/include}] +\item [\texttt{/usr/include}] +\item [\texttt{/usr/local/include}] +\end{Lentry} +from \texttt{THORN\_INC\_DIRS} which default to \texttt{THORN\_DIR/include}. Therefore, if there is any need for using one already installed version of one external library, the aforementioned location should be avoided (e.g. indicating \texttt{/home} as the \texttt{THORN\_DIR} will work with no problems if the required library is installed there) or should be carefully checked, in order to avoid unwanted stripping. The same stripping happens to \texttt{THORN\_LIB\_DIRS} in \texttt{lib/sbin/strip-libdirs.sh} with a larger list of directories: +\begin{Lentry} +\item [\texttt{/lib}] +\item [\texttt{/usr/lib}] +\item [\texttt{/usr/local/lib}] +\item [\texttt{/lib64}] +\item [\texttt{/usr/lib64}] +\item [\texttt{/usr/local/lib64}] +\end{Lentry} + % Do not delete next line % END CACTUS THORNGUIDE \end{document} +