interpreter/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