%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%                            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{Structure of the generated code}

A \faust DSP C++ class derives from the base \emph{dsp} class defined as below:
\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
class dsp {

    public:

        dsp() {}
        virtual ~dsp() {}

        virtual int getNumInputs() = 0;
        virtual int getNumOutputs() = 0
        virtual void buildUserInterface(UI* ui_interface) = 0;
        
        virtual int getSampleRate() = 0;
        
        virtual void init(int samplingRate) = 0;
        virtual void instanceInit(int samplingRate) = 0;
        virtual void instanceConstants(int samplingRate) = 0;
        virtual void instanceResetUserInterface() = 0;
        virtual void instanceClear() = 0;
    
        virtual dsp* clone() = 0;
    
        virtual void metadata(Meta* m) = 0;
    
        virtual void compute(int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) = 0;
        virtual void compute(double date_usec, int count, FAUSTFLOAT** inputs, FAUSTFLOAT** outputs) 
        { 
            compute(count, inputs, outputs); 
        }     
};
\end{lstlisting} 

Here is the class generated with the command \lstinline'faust noise.dsp'. Methods are filled by the compiler with the actual code. 

Several fine-grained initialization methods are available. The \lstinline'instanceInit' method calls several additional initialization methods. The \lstinline'instanceConstants' method sets the instance constant state. The \lstinline'instanceClear' method resets the instance dynamic state (delay lines...).  The \lstinline'instanceResetUserInterface' method resets all control value to their default state. All of those methods can be used individually on an allocated instance to reset part of its state. 

The \lstinline'classInit' static method will initialize static tables that are shared between all instances of the class, and is typically supposed to be called once. 

Finally the \lstinline'init' method combines class static state and instance initialization.

When using a single instance, then calling  \lstinline'init'  is the simplest way to do what is needed. When using several instances, then all of them can be initialized using  \lstinline'instanceInit' , whith a single call to \lstinline'classInit' to initialize the static shared state.  

\begin{lstlisting}[basicstyle=\ttfamily\footnotesize\color{yotxt}]
class mydsp : public dsp {

  private:
	FAUSTFLOAT 	fslider0;
	int 	iRec0[2];
	int fSamplingFreq;

  public:
	virtual void metadata(Meta* m) { 
		m->declare("name", "Noise");
		m->declare("version", "1.1");
		m->declare("author", "Grame");
		m->declare("license", "BSD");
		m->declare("copyright", "(c)GRAME 2009");
	}

	virtual int getNumInputs() { return 0; }
	virtual int getNumOutputs() { return 1; }
	static void classInit(int samplingFreq) {
	}
	virtual void instanceConstants(int samplingFreq) {
		fSamplingFreq = samplingFreq;
	}
	virtual void instanceResetUserInterface() {
		fslider0 = 0.5f;
	}
	virtual void instanceClear() {
		for (int i=0; i<2; i++) iRec0[i] = 0;
	}
	virtual void init(int samplingFreq) {
		classInit(samplingFreq);
		instanceInit(samplingFreq);
	}
	virtual void instanceInit(int samplingFreq) {
		instanceConstants(samplingFreq);
		instanceResetUserInterface();
		instanceClear();
	}
	virtual mydsp* clone() {
		return new mydsp();
	}
	virtual int getSampleRate() {
		return fSamplingFreq;
	}
	virtual void buildUserInterface(UI* ui_interface) {
		ui_interface->openVerticalBox("Noise");
		ui_interface->declare(&fslider0, "style", "knob");
		ui_interface->addVerticalSlider("Volume", &fslider0, 0.5f, 0.0f, 1.0f, 0.1f);
		ui_interface->closeBox();
	}
	virtual void compute (int count, FAUSTFLOAT** input, FAUSTFLOAT** output) {
		float 	fSlow0 = (4.656613e-10f * float(fslider0));
		FAUSTFLOAT* output0 = output[0];
		for (int i=0; i<count; i++) {
			iRec0[0] = ((1103515245 * iRec0[1]) + 12345);
			output0[i] = (FAUSTFLOAT)(fSlow0 * iRec0[0]);
			// post processing
			iRec0[1] = iRec0[0];
		}
	}
};
\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

