%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                            INVOKING THE COMPILER                                             %
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


\chapter{Invoking the \faust compiler}
The \faust compiler is invoked using the \texttt{faust} command. It translate \faust programs into C++ code.
The generated code can be wrapped into an optional \emph{architecture file} allowing to directly produce a fully operational program.

\begin{rail}
compiler : "faust" (options) (file +);
\end{rail}

For example \lstinline'faust noise.dsp' will compile \lstinline'noise.dsp' and output the corresponding C++ code on the standard output.  The option \lstinline'-o' allows to choose the output file : \lstinline'faust noise.dsp -o noise.cpp'. The option \lstinline'-a' allows to choose the architecture file : \lstinline'faust -a alsa-gtk.cpp noise.dsp'. 

To compile a \faust program into an ALSA application on Linux you can use the following commands: 
\begin{lstlisting}
	faust -a alsa-gtk.cpp noise.dsp -o noise.cpp
	g++ -lpthread -lasound  
		`pkg-config --cflags --libs gtk+-2.0` 
		noise.cpp -o noise
\end{lstlisting} 

\section{Compilation options}
Compilation options are listed in the following table :

\bigskip

\small
%%\begin{tabularx}{\textwidth}[t]{|l|l|X|}

\tablefirsthead{
\hline
\textbf{Short} 				& \textbf{Long} 					& \textbf{Description}   \\
\hline
}
\tablehead{
\hline
\textbf{Short} 				& \textbf{Long} 					& \textbf{Description}   \\
\hline
}
\tabletail{
  \hline
  \multicolumn{3}{|r|}{\small\sl continued on next page}\\
  \hline
}
\tablelasttail{
  \hline
}


\begin{supertabular}{|p{1.5cm}|p{4cm}|p{5cm}|}  
\texttt{-h} 				& \texttt{--help} 					& print the help message  \\
\texttt{-v} 				& \texttt{--version} 				& print version information  \\
\texttt{-d} 				& \texttt{--details} 				& print compilation details  \\
\texttt{-tg} 				& \texttt{--task-graph} 			& draw a graph of all internal computation loops as a .dot (graphviz) file. \\
\texttt{-sg} 				& \texttt{--signal-graph} 			& draw a graph of all internal signal expressions as a .dot (graphviz) file.  \\

\texttt{-ps} 				& \texttt{--postscript} 			& generate block-diagram postscript files  \\
\texttt{-svg} 				& \texttt{--svg} 					& generate block-diagram svg files  \\
\texttt{-blur} 				& \texttt{--shadow-blur} 			& add a blur to boxes shadows  \\
\texttt{-sd} 				& \texttt{--simplify-diagrams} 		& simplify block-diagram before drawing them  \\
\texttt{-f \farg{n}} 		& \texttt{--fold \farg{n}}  		& max complexity of svg diagrams before splitting into several files (default 25 boxes)  \\
\texttt{-mns \farg{n}} 		& \texttt{--max-name-size \farg{n}} & max character size used in svg diagram labels\\
\texttt{-sn}             	& \texttt{--simple-names}			& use simple names (without arguments) for block-diagram (default max size : 40 chars) \\
\texttt{-xml} 				& \texttt{--xml} 					& generate an additional description file in xml format  \\
\texttt{-uim} 				& \texttt{--user-interface-macros} 	& add user interface macro definitions to the C++ code  \\
\texttt{-flist} 			& \texttt{--file-list} 				& list all the source files and libraries implied in a compilation  \\
\texttt{-norm} 				& \texttt{--normalized-form} 		& prints the internal signals in normalized form and exits  \\
\hline
\texttt{-lb}	 			& \texttt{--left-balanced} 			& generate left-balanced expressions  \\
\texttt{-mb} 				& \texttt{--mid-balanced} 			& generate mid-balanced expressions (default)  \\
\texttt{-rb} 				& \texttt{--right-balanced}			& generate right-balanced expressions  \\
\texttt{-lt} 				& \texttt{--less-temporaries}		& generate less temporaries in compiling delays  \\
\texttt{-mcd \farg{n}}		& \texttt{--max-copy-delay \farg{n}}& threshold between copy and ring buffer delays (default 16 samples)\\
\hline
\texttt{-vec} 				& \texttt{--vectorize}				& generate easier to vectorize code  \\
\texttt{-vs \farg{n}}		& \texttt{--vec-size \farg{n}}		& size of the vector (default 32 samples) when -vec \\
\texttt{-lv \farg{n}}		& \texttt{--loop-variant \farg{n}}	& loop variant [0:fastest (default), 1:simple] when -vec\\
\texttt{-dfs} 				& \texttt{--deepFirstScheduling}	& schedule vector loops in deep first order when -vec \\
\hline
\texttt{-omp} 				& \texttt{--openMP}					& generate parallel code using OpenMP (implies -vec)  \\
\texttt{-sch} 				& \texttt{--scheduler}				& generate parallel code using threads directly (implies -vec)  \\
\texttt{-g} 				& \texttt{--groupTasks}				& group sequential tasks together when -omp or -sch is used \\
\hline
\texttt{-single} 			& \texttt{--single-precision-floats} & use floats for internal computations (default)  \\
\texttt{-double} 			& \texttt{--double-precision-floats} & use doubles for internal computations  \\
\texttt{-quad} 				& \texttt{--quad-precision-floats}	&  use extended for internal computations  \\
\hline
\texttt{-mdoc} 				& \texttt{--mathdoc}				& generates the full mathematical description of a \faust program \\
\texttt{-mdlang \farg{l}}			& \texttt{--mathdoc-lang \farg{l}} 		& choose the language of the mathematical description (\farg{l} = en, fr, ...) \\
\texttt{-stripmdoc} 			& \texttt{--strip-mdoc-tags}		& remove documentation tags when printing \faust listings\\
\hline
\texttt{-cn \farg{name}} 	& \texttt{--class-name \farg{name}}	& name of the dsp class to be used instead of 'mydsp' \\
\texttt{-t \farg{time}} 	& \texttt{--timeout \farg{time}}	& time out of time seconds (default 600) for the compiler to abort \\
\texttt{-a \farg{file}} 	&  									& architecture file to use  \\
\texttt{-o \farg{file}} 	&  									& C++ output file\\
%%\end{tabularx} 
\end{supertabular} 
\normalsize

\bigskip

