Contributing
In general, libraries are organised in a stacked manner: the base ones define functions or constants without any dependancies, and additional ones are gradually built on top of simpler ones, layer by layer. Dependency loops must be avoided as much as possible. The resources folder contains tools to build and visualise the libraries dependencies graphs.
If you wish to add a function to any of these libraries or if you plan to add a new library, make sure that you follow the following conventions:
New Functions
- All functions must be preceded by a markdown documentation header respecting the following format (open the source code of any of the libraries for an example):
//-----------------functionName--------------------
// Description
//
// #### Usage
//
// ```
// Usage Example
// ```
//
// Where:
//
// * argument1: argument 1 description
//-------------------------------------------------
- Every time a new function is added, the documentation should be updated simply by running
make doclib
. - The environment system (e.g.
os.osc
) should be used when calling a function declared in another library (see the section on Using the Faust Libraries). - Try to reuse existing functions as much as possible.
- If you have any question, send an e-mail to rmichon_at_ccrma_dot_stanford_dot_edu.
New Libraries
- Any new "standard" library should be declared in
stdfaust.lib
with its own environment (2 letters - seestdfaust.lib
). - Any new "standard" library must be added to
generateDoc
. - Functions must be organized by sections.
- Any new library should at least
declare
aname
and aversion
. - The comment based markdown documentation of each library must respect the following format (open the source code of any of the libraries for an example):
//############### libraryName ##################
// Description
//
// * Section Name 1
// * Section Name 2
// * ...
//
// It should be used using the `[...]` environment:
//
// ```
// [...] = library("libraryName");
// process = [...].functionCall;
// ```
//
// Another option is to import `stdfaust.lib` which already contains the `[...]`
// environment:
//
// ```
// import("stdfaust.lib");
// process = [...].functionCall;
// ```
//##############################################
//================= Section Name ===============
// Description
//==============================================
- If you have any question, send an e-mail to rmichon_at_ccrma_dot_stanford_dot_edu.
Coding Conventions
In order to have a uniformized library system, we established the following conventions (that hopefully will be followed by others when making modifications to them :-) ).
Documentation
- All the functions that we want to be "public" are documented.
- We used the
faust2md
"standards" for each library://###
for main title (library name - equivalent to#
in markdown),//===
for section declarations (equivalent to##
in markdown) and//---
for function declarations (equivalent to####
in markdown - seebasics.lib
for an example). - Sections in function documentation should be declared as
####
markdown title. - Each function documentation provides a "Usage" section (see
basics.lib
).
Library Import
To prevent cross-references between libraries we generalized the use of the library("")
system for function calls in all the libraries. This means that everytime a function declared in another library is called, the environment corresponding to this library needs to be called too. To make things easier, a stdfaust.lib
library was created and is imported by all the libraries:
an = library("analyzers.lib");
ba = library("basics.lib");
co = library("compressors.lib");
de = library("delays.lib");
dm = library("demos.lib");
dx = library("dx7.lib");
en = library("envelopes.lib");
fd = library("fds.lib");
fi = library("filters.lib");
ho = library("hoa.lib");
it = library("interpolators.lib");
ma = library("maths.lib");
mi = library("mi.lib");
ef = library("misceffects.lib");
os = library("oscillators.lib");
no = library("noises.lib");
pf = library("phaflangers.lib");
pm = library("physmodels.lib");
rm = library("reducemaps.lib");
re = library("reverbs.lib");
ro = library("routes.lib");
sp = library("spats.lib");
si = library("signals.lib");
so = library("soundfiles.lib");
sy = library("synths.lib");
ve = library("vaeffects.lib");
wa = library("webaudio.lib");
vl = library("version.lib");
wd = library("wavedigitalfilters.lib");
For example, if we wanted to use the smooth
function which is now declared in signals.lib
, we would do the following:
import("stdfaust.lib");
process = si.smooth(0.999);
This standard is only used within the libraries: nothing prevents coders to still import signals.lib
directly and call smooth
without ro.
, etc. It means symbols and function names defined within a library have to be unique to not collide with symbols of any other libraries.
"Demo" Functions
"Demo" functions are placed in demos.lib
and have a built-in user interface (UI). Their name ends with the _demo
suffix. Each of these function have a .dsp
file associated to them in the /examples
folder.
Any function containing UI elements should be placed in this library and respect these standards.
"Standard" Functions
"Standard" functions are here to simplify the life of new (or not so new) Faust coders. They are declared in /libraries/doc/standardFunctions.md
and allow to point programmers to preferred functions to carry out a specific task. For example, there are many different types of lowpass filters declared in filters.lib
and only one of them is considered to be standard, etc.