Bug fixed for unix error "readlink /proc/self/fd/0" on MacOS.
[Faustine.git] / 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}