%MAN OFF
\section{Running \cmix}
\label{running}
\def\manIgnore#1{#1}

The command line syntax for \cmix{} is quite simple. Most of the turns
and knobs that control \cmix's operation are \emph{specializer
directives} which have their own section (\ref{directives}) of the
manual.

\subsection{The \cmix{} main system}
\label{manual page}
%
%
\example{cmix «option...» «filename...»}

\cmix{} accepts the following command line options:
%MAN ON
%MAN%.SH OPTIONS
\begin{description}
\item[»-I««path»] -- specifies where to look for »\#include«d files.
        Equivalent to the »-I« option usually found in C compilers.
\manIgnore{\item[»-D««symbol»] or »-D««symbol»»=««expansion» --}
%MAN%.lI \fB-D\fIsymbol\fR[\fB=\fIexpansion\fR]
	defines the
        given symbol as a preprocessor macro when reading in the
        C sources. Equivalent to the »define:« specializer directive
        and to the »-D« option usually found in C compilers.
\item[»-e««directive»] -- give an arbitrary specializer directive%
        \manIgnore{ (see section \ref{directives})}. Note that the
	shell will probably need the directive text to be quoted
        except in very simple cases.
\item[»-o««basename»] -- controls the naming of the \cmix{} output
        files, which will be called «basename-gen.c» and
        «basname.ann». Equivalent to the »outputbase:« specializer
        directive.
\item[»-q«] -- suppresses routine messages about reading and writing
        files.
\item[»-v«] -- be verbose about the progress of analysis phases.
\item[»-s«] -- output the ».ann« file in a format that resembles the
        data format uses internally by \cmix{}. The format is
        sufficiently close to C to be readable, but you may have
        trouble recognizing the structure of your program---or indeed
        to find your program amidst the definitions read from header
        files.
\item[»-S«] -- same as »-s« but turns off some shortcuts normally
	taken to keep the output readable. This makes the output
	quite unreadable indeed: what normally is represented as
	»t2p->t1.x« now gets rendered \verb+*&(&(*&t2p)->t1)->x+. This
	is primaily useful when debugging \cmix.
\item[»-b«] -- make a generating extension that tries very hard to
        share code internally in each residual function. This slows
        down the specialization process very noticeably, usually with
        no great benefit.
%\item[»-g«] -- make generating extension source that uses GCC language
%	extensions to gain a little extra performance. The residual
%	code produced does not change.
\item[»-E«] -- instead of parsing the C source and making a
	generating extension, just preprocess it (with the same
	include file search path and predefined symbols as \cmix{}
	would normally use) and write the preprocessed source to
	the standard output. This is sometimes useful for debugging
	if one suspects the program text is changed unexpectedly in
	the preprocessing step.
\item[»-h«] -- displays an option summary
\item[»-d«...] -- controls debugging output, which you normally
        don't want to see.
\end{description}

%MAN%.SH OTHER ARGUMENTS
Any command line argument to \cmix{} that is not an option is treated
as a file name. If the argument ends with ».c« then it is assumed to
be a C source file containing code to be specialized.

If you want a
file whose name does not have a ».c« suffix to be parsed as C code,
you need to use an explicit »source:« directive. E.g.:
\example{cmix -e 'source: plain-file-name'}

If a command line argument is not an option and does not look like
a C source file name, it is interpreted as the name of a
\emph{script file}. The script file consists of specializer directives
separated by semicolons or blank lines. Since most of \cmix{}'s
actions can be controlled by specializer directives, once you have
set up a script file, a useful \cmix{} command line can be as short as
\example{cmix myproject.cmx}

\manIgnore{\medskip}
%MAN%.SH OUTPUT FILES
\cmix{} names its output files by appending »-gen.c« and ».ann« to a
basename obtained in the following way:
\begin{itemize}
\item An »-o« option, if it exists, always takes precedence
\item If no »-o« option is found \cmix{} looks for an »outputbase:«
        specializer directive.
\item The name of the first script file named
        on the command line. By convention, script files have
        names ending in ».cmx«; this suffix is stripped from the
        file name before using it to derive output file names.
\item If there is no script file, the name of the first C source
        file named on the command line is used.
\item If everything else fails, the output files will be names
        »cmix-gen.c« and »cmix.ann«.
\end{itemize}
%MAN OFF

\input{cmixshow}

\subsection{Compiling the generating extension}
\label{compiling it}
%
%
\example{cc -lcmix «basename»-gen.c -o «binaryname»}
For the generating extension to work, you need to link it to a special
\cmix{} support libary. You might need to use an »-L« switch to locate
it if it has been installed in a nonstandard place.

\subsection{Running the generating extension}
%
%
If you use the »goal« directive, you can simply run the compiled generating
extension, giving as many command-line parameters as there were ``»\$«$n$''
specificers in the »goal« directive. It then output specialized C code to
standard output.

You can put a ``»-R«'' switch in front of those parameters. This disables
a restructuring phase that tries to express the control flow of the
specialized C code with high-level control constructs. Sometimes this
makes compilers generate better code for the residual program; sometimes
it has the opposite effect. The »-R« switch can also be use if you find
the residual program provokes an internal error in the restructuring phase.

\smallbreak

If you use »generator« directives, you have to supply a »main« function
yourself, as detailed in the description of that directive. Your »main()« can
disable the restructuring phase by doing
\example{extern int cmixRestruct ;}
\example{cmixRestruct = 0 ;}
