Merge branch 'master' of https://scm.cri.ensmp.fr/git/Faustine
[Faustine.git] / interpretor / preprocessor / faust-0.9.47mr3 / documentation / faust-quick-reference-src / chapters / compiler.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 % INVOKING THE COMPILER %
3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4
5
6 \chapter{Invoking the \faust compiler}
7 The \faust compiler is invoked using the \texttt{faust} command. It translate \faust programs into C++ code.
8 The generated code can be wrapped into an optional \emph{architecture file} allowing to directly produce a fully operational program.
9
10 \begin{rail}
11 compiler : "faust" (options) (file +);
12 \end{rail}
13
14 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'.
15
16 To compile a \faust program into an ALSA application on Linux you can use the following commands:
17 \begin{lstlisting}
18 faust -a alsa-gtk.cpp noise.dsp -o noise.cpp
19 g++ -lpthread -lasound
20 `pkg-config --cflags --libs gtk+-2.0`
21 noise.cpp -o noise
22 \end{lstlisting}
23
24 \section{Compilation options}
25 Compilation options are listed in the following table :
26
27 \bigskip
28
29 \small
30 %%\begin{tabularx}{\textwidth}[t]{|l|l|X|}
31
32 \tablefirsthead{
33 \hline
34 \textbf{Short} & \textbf{Long} & \textbf{Description} \\
35 \hline
36 }
37 \tablehead{
38 \hline
39 \textbf{Short} & \textbf{Long} & \textbf{Description} \\
40 \hline
41 }
42 \tabletail{
43 \hline
44 \multicolumn{3}{|r|}{\small\sl continued on next page}\\
45 \hline
46 }
47 \tablelasttail{
48 \hline
49 }
50
51
52 \begin{supertabular}{|p{1.5cm}|p{4cm}|p{5cm}|}
53 \texttt{-h} & \texttt{--help} & print the help message \\
54 \texttt{-v} & \texttt{--version} & print version information \\
55 \texttt{-d} & \texttt{--details} & print compilation details \\
56 \texttt{-tg} & \texttt{--task-graph} & draw a graph of all internal computation loops as a .dot (graphviz) file. \\
57 \texttt{-sg} & \texttt{--signal-graph} & draw a graph of all internal signal expressions as a .dot (graphviz) file. \\
58
59 \texttt{-ps} & \texttt{--postscript} & generate block-diagram postscript files \\
60 \texttt{-svg} & \texttt{--svg} & generate block-diagram svg files \\
61 \texttt{-blur} & \texttt{--shadow-blur} & add a blur to boxes shadows \\
62 \texttt{-sd} & \texttt{--simplify-diagrams} & simplify block-diagram before drawing them \\
63 \texttt{-f \farg{n}} & \texttt{--fold \farg{n}} & max complexity of svg diagrams before splitting into several files (default 25 boxes) \\
64 \texttt{-mns \farg{n}} & \texttt{--max-name-size \farg{n}} & max character size used in svg diagram labels\\
65 \texttt{-sn} & \texttt{--simple-names} & use simple names (without arguments) for block-diagram (default max size : 40 chars) \\
66 \texttt{-xml} & \texttt{--xml} & generate an additional description file in xml format \\
67 \texttt{-uim} & \texttt{--user-interface-macros} & add user interface macro definitions to the C++ code \\
68 \texttt{-flist} & \texttt{--file-list} & list all the source files and libraries implied in a compilation \\
69 \texttt{-norm} & \texttt{--normalized-form} & prints the internal signals in normalized form and exits \\
70 \hline
71 \texttt{-lb} & \texttt{--left-balanced} & generate left-balanced expressions \\
72 \texttt{-mb} & \texttt{--mid-balanced} & generate mid-balanced expressions (default) \\
73 \texttt{-rb} & \texttt{--right-balanced} & generate right-balanced expressions \\
74 \texttt{-lt} & \texttt{--less-temporaries} & generate less temporaries in compiling delays \\
75 \texttt{-mcd \farg{n}} & \texttt{--max-copy-delay \farg{n}}& threshold between copy and ring buffer delays (default 16 samples)\\
76 \hline
77 \texttt{-vec} & \texttt{--vectorize} & generate easier to vectorize code \\
78 \texttt{-vs \farg{n}} & \texttt{--vec-size \farg{n}} & size of the vector (default 32 samples) when -vec \\
79 \texttt{-lv \farg{n}} & \texttt{--loop-variant \farg{n}} & loop variant [0:fastest (default), 1:simple] when -vec\\
80 \texttt{-dfs} & \texttt{--deepFirstScheduling} & schedule vector loops in deep first order when -vec \\
81 \hline
82 \texttt{-omp} & \texttt{--openMP} & generate parallel code using OpenMP (implies -vec) \\
83 \texttt{-sch} & \texttt{--scheduler} & generate parallel code using threads directly (implies -vec) \\
84 \texttt{-g} & \texttt{--groupTasks} & group sequential tasks together when -omp or -sch is used \\
85 \hline
86 \texttt{-single} & \texttt{--single-precision-floats} & use floats for internal computations (default) \\
87 \texttt{-double} & \texttt{--double-precision-floats} & use doubles for internal computations \\
88 \texttt{-quad} & \texttt{--quad-precision-floats} & use extended for internal computations \\
89 \hline
90 \texttt{-mdoc} & \texttt{--mathdoc} & generates the full mathematical description of a \faust program \\
91 \texttt{-mdlang \farg{l}} & \texttt{--mathdoc-lang \farg{l}} & choose the language of the mathematical description (\farg{l} = en, fr, ...) \\
92 \texttt{-stripmdoc} & \texttt{--strip-mdoc-tags} & remove documentation tags when printing \faust listings\\
93 \hline
94 \texttt{-cn \farg{name}} & \texttt{--class-name \farg{name}} & name of the dsp class to be used instead of 'mydsp' \\
95 \texttt{-t \farg{time}} & \texttt{--timeout \farg{time}} & time out of time seconds (default 600) for the compiler to abort \\
96 \texttt{-a \farg{file}} & & architecture file to use \\
97 \texttt{-o \farg{file}} & & C++ output file\\
98 %%\end{tabularx}
99 \end{supertabular}
100 \normalsize
101
102 \bigskip
103