diff options
author | jthorn <jthorn@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 2006-06-23 14:17:19 +0000 |
---|---|---|
committer | jthorn <jthorn@17b73243-c579-4c4c-a9d2-2d5706c11dac> | 2006-06-23 14:17:19 +0000 |
commit | 1e3e3903f32031c424a6136ae18f8c56fcad77bb (patch) | |
tree | 42c9c3d1ea9ba6b861667ac821b0ba72156418ba /doc | |
parent | a906d065d89bf7b2e74821b02fffca9a352b7347 (diff) |
description of command-line options:
* describe --foo as standard long-option syntax, with -foo deprecated
* also describe other syntax rules
git-svn-id: http://svn.cactuscode.org/flesh/trunk@4333 17b73243-c579-4c4c-a9d2-2d5706c11dac
Diffstat (limited to 'doc')
-rw-r--r-- | doc/UsersGuide/RunningCactus.tex | 96 |
1 files changed, 62 insertions, 34 deletions
diff --git a/doc/UsersGuide/RunningCactus.tex b/doc/UsersGuide/RunningCactus.tex index 3ce4f1bf..43205cc9 100644 --- a/doc/UsersGuide/RunningCactus.tex +++ b/doc/UsersGuide/RunningCactus.tex @@ -1017,7 +1017,7 @@ by configure and the \texttt{ThornList} file remain. configuration using its previous configuration options from the file \texttt{configs/<\var{config}>/config-info}. -\item [\texttt{gmake <\var{config}>-testsuite}] runs the test programs +\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. @@ -1190,7 +1190,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 -\texttt{gmake <\var{configuration}>-testsuite} +\texttt{gmake <\var{configuration}>--testsuite} These test suite serve the dual purpose of @@ -1235,83 +1235,111 @@ creating thorn documentation. \section{Command Line Options} \label{sec:command_line_options} -The Cactus executable accepts these command line arguments: +Cactus uses the standard GNU style of long-named command-line options; +many of these options also have traditional Unix single-letter short forms. +The options follow the usual GNU rules: +\begin{itemize} +\item A long-named option \verb|--foo| which takes an argument \verb|bar| + may be written as either \verb|--foo bar| or as \verb|--foo=bar|. +\item A long-named option may be abbreviated so long as the abbreviation + is unambiguous. +\item The preferred way of spelling a long-named option is \verb|--foo|, + but \verb|-foo| also accepted, though this is deprecated + (we plan to remove it after the next beta release). +\item A short option \verb|-X| which takes an argument \verb|bar| + may be written as either \verb|-Xbar| or as \verb|-X=bar|. +\item An option which can be interpreted as either a short option, + or as an abbreviated \verb|-foo|-style long option, is interpreted + as the former. In particularl, \verb|-re| is interpreted as + an abbreviation for \verb|-redirect|, rather than as \verb|-r=e|. +\end{itemize} +The Cactus command line options are specified in +table~\ref{tab:command-line-options}, and are as follows: + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +\begin{table} \texttt{ \begin{tabular}{|l|l|} \hline Short Version & Long Version \\ \hline - -O[v] & -describe-all-parameters \\ + -O[v] & --describe-all-parameters \\ \hline - -o<\var{param}> & -describe-parameter=<\var{param}> \\ + -o<\var{param}> & --describe-parameter=<\var{param}> \\ \hline - -S & -print-schedule\\ + -S & --print-schedule\\ \hline - -T & -list-thorns\\ + -T & --list-thorns\\ \hline - -t<\var{arrangement/thorn}>& -test-thorn-compiled=<\var{arrangement/thorn}>\\ + -t<\var{arrangement/thorn}>& --test-thorn-compiled=<\var{arrangement/thorn}>\\ \hline - -h,-? & -help\\ + -h,-? & --help\\ \hline - -v & -version \\ + -v & --version \\ \hline -% -x [<nprocs>] & -test-parameters [<nprocs>] \\ +% -x [<nprocs>] & --test-parameters [<nprocs>] \\ %\hline - -L<\var{level}> & -logging-level=<\var{level}> \\ + -L<\var{level}> & --logging-level=<\var{level}> \\ \hline - -W<\var{level}> & -warning-level=<\var{level}> \\ + -W<\var{level}> & --warning-level=<\var{level}> \\ \hline - -E<\var{level}> & -error-level=<\var{level}> \\ + -E<\var{level}> & --error-level=<\var{level}> \\ \hline - -r[o|e|oe|eo] & -redirect=[o|e|oe|eo]\\ + -r[o|e|oe|eo] & --redirect=[o|e|oe|eo]\\ \hline - -b <\var{mode}> & -buffering=<\var{mode}>\\ + -b <\var{mode}> & --buffering=<\var{mode}>\\ \hline - -i & -ignore-next \\ + -i & --ignore-next \\ \hline - & -parameter-level=<\var{level}> \\ + & --parameter-level=<\var{level}> \\ \hline \end{tabular} } +\caption[Command-Line Options] + {This table shows all the Cactus command-line options.} +\label{tab:command-line-options} +\end{table} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \begin{Lentry} -\item [\texttt{-O} or \texttt{-describe-all-parameters}] +\item [\texttt{-O} or \texttt{--describe-all-parameters}] Prints 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 \texttt{v} (i.e. \texttt{-Ov} to give verbose information about all parameters). -\item [\texttt{-o<\var{param}>} or \texttt{-describe-parameter=<\var{param}>}] +\item [\texttt{-o<\var{param}>} or \texttt{--describe-parameter=<\var{param}>}] Prints the description and allowed values for a given parameter --- takes one argument. -\item [\texttt{-S} or \texttt{-print-schedule}] +\item [\texttt{-S} or \texttt{--print-schedule}] Print only the schedule tree. -\item [\texttt{-T} or \texttt{-list-thorns}] +\item [\texttt{-T} or \texttt{--list-thorns}] Prints a list of all the thorns which were compiled in. -\item [\texttt{-t<\var{arrangement or thorn}>} or \texttt{-test-thorn-compiled=<\var{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 [\texttt{-h}, \texttt{-?} or \texttt{-help}] +\item [\texttt{-h}, \texttt{-?} or \texttt{--help}] Prints a help message. -\item [\texttt{-v} or \texttt{-version}] +\item [\texttt{-v} or \texttt{--version}] Prints version information of the code. -%\item [\texttt{-x <nprocs>} or \texttt{-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 [\texttt{-L<\var{level}>} or \texttt{-logging-level=<\var{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 \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 [\texttt{-W<\var{level}>} or \texttt{-warning-level=<\var{level}>}] +\item [\texttt{-W<\var{level}>} or \texttt{--warning-level=<\var{level}>}] 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 [\texttt{-E<\var{level}>} or \texttt{-error-level=<\var{level}>}] +\item [\texttt{-E<\var{level}>} or \texttt{--error-level=<\var{level}>}] 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%%% @@ -1322,12 +1350,12 @@ the Cactus run immediately (after printing the warning message%%% }%%% ). The default value is zero, \ie{} only level~0 warnings will abort the Cactus run. -\item [\texttt{-r[o|e|oe|eo]} or \texttt{-redirect=[o|e|oe|eo]}] +\item [\texttt{-r[o|e|oe|eo]} or \texttt{--redirect=[o|e|oe|eo]}] 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 [\texttt{-b <\var{mode}>} or \texttt{-buffering=<\var{mode}>}] +\item [\texttt{-b <\var{mode}>} or \texttt{--buffering=<\var{mode}>}] Set the \texttt{stdout} buffering mode. \var{mode} can be one of \texttt{no}, \texttt{line}, and \texttt{full}. Buffered I/O is a standard feature of C programmes. This delays writing the actual @@ -1342,9 +1370,9 @@ the standard outputs from processors other than processor 0 are discarded. messages, i.e.\ the \texttt{stderr} stream, is always unbuffered (and hence usually slower than \texttt{stdout}). -\item [\texttt{-i} or \texttt{-ignore-next}] +\item [\texttt{-i} or \texttt{--ignore-next}] Causes the next argument on the command line to be ignored. -\item [\texttt{-parameter-level=<\var{level}>}] +\item [\texttt{--parameter-level=<\var{level}>}] Sets 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}. @@ -1406,7 +1434,7 @@ 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 -\texttt{-parameter-level} which can take the following values +\texttt{--parameter-level} which can take the following values \begin{Lentry} \item[\texttt{relaxed}] Cactus will issue a level 0 warning (that is the default behaviour will be to terminate) if |