doc/user-manual-src/faustine-user-manual.tex

   1 \documentclass[a4paper,12pt]{book}
   2
   3 %\usepackage{latexsym, amssymb}
   4 \usepackage{latexsym}
   5 \usepackage{graphicx}
   6 %\usepackage{longtable}
   7 %\usepackage{supertabular}
   8 %\usepackage{tabularx}
   9 %\usepackage{tabulary}
  10 \usepackage{xspace}
  11 \usepackage{pdfpages}
  12 %\usepackage[rounded]{syntax}
  13 \usepackage{hyperref}
  14 \usepackage{listings}
  15 %\usepackage[usenames,dvipsnames]{color}
  16
  17 %\usepackage[cc]{titlepic}
  18 \usepackage{sectsty}
  19 % \usepackage{times}
  20 %\usepackage[urw-garamond]{mathdesign}
  21 \usepackage{fncychap}
  22 \usepackage{fancyhdr}
  23
  24 \usepackage{rail}
  25 \railoptions{-t -h}
  26
  27 \fancyhead{} % clear all header fields
  28 \fancyheadoffset[LE,RO]{\marginparsep+\marginparwidth}
  29 \fancyhead[RO,LE]{\thepage}
  30 \fancyhead[LO]{\rightmark}
  31 \fancyhead[RE]{\leftmark}
  32 \renewcommand{\headrulewidth}{0.1pt}
  33
  34 \fancyfoot{}
  35
  36
  37 \hypersetup{%
  38             colorlinks = true, %true, false
  39             linkcolor = black,
  40             citecolor = blue,
  41             urlcolor = blue,
  42 }
  43 \urlstyle{sf} %rm
  44 \newcommand{\myurl}[1]{\textcolor{blue}{\underbar{\url{#1}}}}
  45
  46 %%% MY COLORS
  47 \definecolor{yoheader}{rgb}{0.71,0.01,0.0}
  48
  49 %%%% margin par
  50 \definecolor{margincolor}{rgb}{0.52,0.02,0.02} % grey red.
  51 \definecolor{yobg}{rgb}{0.9,0.9,1}
  52 \definecolor{yotxt}{rgb}{0.01,0.01,0.52}
  53 \definecolor{mylstcmt}{rgb}{0.01,0.52,0.01} % a dark green.
  54 %\definecolor{mylstdoc}{rgb}{0.60,0.60,0.60} % a medium grey.
  55 \definecolor{mylstdoc}{rgb}{0.80,0.30,0.80} % a medium pink.
  56 %\definecolor{mylsteqn}{rgb}{0.80,0.80,0.30} % a medium pink.
  57 \definecolor{mylstkey}{rgb}{0.52,0.01,0.01} % a dark red.
  58 %%\newcommand{\farg}[1]{\textrm{\textit{#1}}}
  59
  60 \setlength{\marginparwidth}{1.2in}
  61 \let\oldmarginpar\marginpar
  62 \renewcommand\marginpar[1]{\-\oldmarginpar[\raggedleft\color{margincolor}\footnotesize #1]%
  63 {\raggedright\color{margincolor}\footnotesize #1}}
  64
  65
  66
  67 % \relax
  68
  69 \begin{document}
  70 \ChRuleWidth{1pt}
  71 % \ChNumVar{\raggedleft\fontsize{80}{82}\sffamily\bfseries\color{yoheader}}
  72 \ChNumVar{\raggedleft\Huge\color{yoheader}}
  73 %\ChTitleVar{\raggedleft\fontsize{60}{62}\sffamily\it\color{yoheader}}
  74 \ChTitleVar{\raggedleft\sffamily\fontsize{30}{32}\bf\color{yoheader}}
  75
  76 %\chapterfont{\sffamily\color{yoheader}}
  77 %\sectionfont{\sffamily\color{yoheader}}
  78 %\subsectionfont{\sffamily\color{yoheader}}
  79 %\subsubsectionfont{\sffamily\color{yoheader}}
  80
  81 \chapterfont{\color{yoheader}}
  82 \sectionfont{\color{yoheader}}
  83 \subsectionfont{\color{yoheader}}
  84 \subsubsectionfont{\color{yoheader}}
  85
  86
  87 % parameters for listings
  88 \lstset{
  89   tabsize=4,
  90   showspaces=false,
  91   showstringspaces=false,
  92   language=C++,
  93   basicstyle=\ttfamily\color{yotxt},
  94   numbers=none,
  95   stepnumber=2,
  96   commentstyle=\slshape\color{mylstcmt},
  97   breaklines=true,
  98   emph={component, declare, environment, import, library, process},
  99   emph={[2]ffunction, fconstant, fvariable},
 100   emph={[3]button, checkbox, vslider, hslider, nentry, vgroup, hgroup, tgroup, vbargraph, hbargraph, attach},
 101   emphstyle=\color{mylstkey},
 102 %  morecomment=[s][\color{mylsteqn}]{<equation>}{</equation>},
 103   morecomment=[s][\color{mylstdoc}]{<mdoc>}{</mdoc>},
 104   %% frame=single,
 105   backgroundcolor=\color{yobg},
 106   captionpos=b
 107 }
 108
 109 \lstloadlanguages{C++,[LaTeX]TeX}
 110
 111 % \titlepic{
 112 %   \includegraphics[width=15cm]{images/bandeau-faust}
 113 % }
 114 \title{\Huge\color{yoheader}\faustine User Manual%\\\Large(version 0.9.29)
 115 }
 116 \author{CRI -- \textsc{Mines} ParisTech\\Centre de Recherche en Informatique}
 117 \date{September 2013}
 118
 119
 120 \railalias{recur}{$\sim$}
 121 \railalias{lbrace}{\{}
 122 \railalias{rbrace}{\}}
 123 \railalias{dollar}{\$}
 124 \railalias{mod}{\%}
 125 \railalias{arobase}{@}
 126 \railalias{ampersand}{\&}
 127 \railalias{hat}{$\land$}
 128 \railalias{kot}{'}
 129 \railalias{pipe}{$|$}
 130 \railalias{fdelay}{}
 131 \railalias{backslash}{\char"5C}
 132 \railterm{recur,lbrace,rbrace,dollar,mod,kot,arobase,ampersand,backslash,fdelay, pipe, hat}
 133
 134 \newcommand{\farg}[1]{\textrm{\textit{#1}}}
 135 \newcommand{\ldbrack}{[\![ \,}
 136 \newcommand{\rdbrack}{\, ]\!] }
 137 \newcommand{\rdbrackC}{\rdbrack_{\mathrm{C}}\,}
 138 \newcommand{\dbrack}[1]{\ldbrack #1 \rdbrack}
 139 \newcommand{\semantic}[1]{\ldbrack #1 \rdbrack}
 140 \newcommand{\dbrackC}[1]{\ldbrack #1 \rdbrackC}
 141
 142 \newcommand{\faust}{\textsc{Faust}\xspace}
 143 \newcommand{\faustine}{\textsc{Faustine}\xspace}
 144 \newcommand{\latex}{\LaTeX\xspace}
 145 \newcommand{\ircam}{\textsc{Ircam}\xspace}
 146 \newcommand{\astree}{\textsc{Astree}\xspace}
 147 \newcommand{\svg}{\textsc{Svg}\xspace}
 148
 149
 150 \setlength{\parindent}{0pt}
 151 \setlength{\parskip}{1ex plus 0.5ex minus 0.2ex}
 152
 153 \maketitle
 154
 155 \tableofcontents
 156
 157 \chapter{Introduction}
 158
 159 \faustine is an interpreter for multi-rate and vector exented \faust programs testing, written in OCaml, at CRI of MINES ParisTech, and covered by the GNU Public License V3 (see LICENSE.txt).
 160
 161 \faust (\textit{Functional Audio Stream}) is a functional programming language specifically designed for real-time signal processing and synthesis.  \faust targets high-performance signal processing applications and audio plug-ins for a variety of platforms and standards.
 162
 163 \section{Design Principles}
 164
 165 Various principles have guided the design of \faustine:
 166
 167 \begin{itemize}
 168
 169 \item \faustine is a \textit{test bed} interpreter for faust programs, especially for vector extension. It aims at providing a framework to test \textit{vector} and \textit{multi-rate} ideas quite easily, without having to deal with the burdens of the compiler. \faustine is written in OCaml.
 170
 171 \item \faustine programs are interpreted upon \faust language and extensions, onto input files (wav or csv), and producing output files (also wav or csv). The interpreter relies on a \faust preprocessor to translate \faust programs into equivalent flatten programs containing only core \faust functions except GUI ones.
 172
 173 \item In most cases, \faustine is inefficient but, still, it often allows to get a idea of time consumption location.
 174
 175 \item \faustine depends on g++ and ocamlopt compilers. It embeds libsndfile and a slighlty modified version of libsndfile-ocaml.
 176
 177 \item For the moment, \faustine only handles dynamic type-checking but future work should address static type-checking.
 178
 179 \item \faustine current extension supports four multirate and vector functions: \lstinline'vectorize', \lstinline'serialize', \lstinline'[ ]' (pick vector element), and \lstinline'#' (concatenate two vector elements).
 180
 181 \item So far, several vector libraries have been developed: complex.lib, fft.lib, fft2d.lib and morpho.lib.
 182
 183 \end{itemize}
 184
 185 \chapter{Compiling and installing \faustine}
 186
 187 \faustine's git repository can be cloned calling:
 188
 189 \begin{lstlisting}
 190         git clone https://scm.cri.ensmp.fr/git/Faustine.git
 191 \end{lstlisting}
 192
 193
 194 \section{Organization of the distribution}
 195
 196 \faustine directory should contain the following elements:
 197
 198 \begin{tabular}{ll}
 199   benchmarks/ &          benchmark result files\\
 200   Changes.txt &          what's new with each release\\
 201   configure       &      compilation configuration script\\
 202   examples/      &       vector examples (fft, image processing...)\\
 203   INSTALL.txt    &       Faustine installation instructions\\
 204   interpreter/    &      Faustine's interpreter source code\\
 205   lib/               &   library files in Faustine (fft.lib, morpho.lib...)\\
 206   LICENSE.txt  &         license and copyright notice\\
 207   Makefile           &   main Makefile to compile and install\\
 208   README.txt      &      this file\\
 209 \end{tabular}
 210
 211 \section{Compiling and Installing}
 212 \faustine has no dependencies outside standard libraries, except OCaml and g++ compilers and 'make'-like standard commands. Therefore the compilation should be straightforward. Configure is necessary for libsndfile embedded library. To compile the \faustine interpreter do:
 213 \begin{lstlisting}
 214         cd Faustine/
 215         ./configure
 216         make
 217         sudo make install
 218 \end{lstlisting}
 219
 220 If the compilation was successful you can test the interpreter before installing it:
 221 \begin{lstlisting}
 222         make test
 223 \end{lstlisting}
 224
 225
 226 \chapter{How to use \faustine}
 227
 228
 229
 230 \chapter{How to maintain and extend \faustine}
 231
 232
 233
 234 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 235 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 236 %                                       END                                              %
 237 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 238 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 239
 240
 241 \end{document}