-
Notifications
You must be signed in to change notification settings - Fork 3
For Developers
This section intends to give people, who wants to contribute to the symbolist project, informations and advices about how to develop, compile or write documentation for the project.
- Project's architecture
- Setting up the developing environment
- Development guidelines & coding styles
- Writing and generating documentation
Here is described the architecture of the symbolist project.
- Builds: contains three subfolders, one for each OS: Linux, Windows and macOS. The symbolist's XCode project is to be found under the MacOSX subfolder.
- Source: symbolist source code.
- SymbolistTests: contains all files for unit tests and integration tests in symbolist.
- JuceLibraryCode: contains all headers generated by the Projucer app to include JUCE library's modules into the symbolist source code.
- Doxygen: contains the doxyfile to generate the Doxygen documentation in html format.
- OM: contains all files related to the integration of symbolist in the OpenMusic language.
- max: contains all files related to the integration of symbolist in the Max language.
- symbolist.jucer: the symbolist Projucer file, to manage and generate projects for specific IDE (XCode, Visual Studio…).
- symbolist-deploy: bash script to automate the deployment of symbolist as a Max and an OpenMusic object.
For now the development, and deployment of the symbolist software have been tested on the macOS platform only. Therefore, the following instructions about how to set up the working environment for symbolist are described only for macOS. However, in the future, instructions for the setting of symbolist in other platforms will be added.
The following configuration have been tested in macOS Sierra (v.10.12.6). Please, do follow each one of the steps described below in order to set the working environment for symbolist. The location of each folder, containing libraries and source code, is specified and must be respected, in order to match the relative pathes of the XCode project.
- Get JUCE. symbolist is developed using the JUCE C++ Library. In order to compile and run symbolist, you need to download the JUCE Library (https://shop.juce.com/get-juce/download) and place the downloaded JUCE folder at the same level of your symbolist repository. Currently, version 5.2 of the JUCE library is used. Trouble can be experienced when trying to compile symbolist with an earlier version of JUCE (5.3, for example).
- libo. The libo library (CNMAT, Berkeley) is used to handle the underlying OSC (Open Sound Control) structure of symbols in a symbolist score. In order to compile the symbolist project, download the libo git repository from its GitHub page (https://github.com/CNMAT/libo), and place it at the same level than your symbolist repository. Then, generate the libo.a static library file by following the instructions written in the GitHub page. Let libo.a in its original folder (libo.a in libo).
- Max SDK and libomax. In order to compile symbolist as a Max object, download and extract the Max SDK (https://cycling74.com/downloads/sdk), and clone the libomax git repository (https://github.com/CNMAT/libomax) both in the same location as your symbolist repository. Then, compile the libomax library as described in the libomax GitHub page, and let the produced libomax.a file in the libomax folder.
If the previous steps are correctly followed, the directory containing your symbolist repository should look like that:
.
+-- symbolist // your symbolist repo.
+-- JUCE // JUCE Library source code (version 5.2).
+-- libo // libo repo containing libo.a after compilation.
| +-- libo.a
| ...
+-- libomax // libomax repo containing libomax.a after compilation.
| +-- libomax.a
| ...
+-- max-sdk // containing the Max SDK source code.SYMBOLIST uses the Doxygen tool to write and generate the code documentation. The next sections presents how to install Doxygen and how to use it, and in addition, how to write block comments so they could be integrated in the docs.
The Doxygen program enables the automatic generation of documentation following the instructions contained in the configuration file (the Doxyfile). To generate the doc, download the Doxygen binary corresponding to your OS at http://www.stack.nl/~dimitri/doxygen/download.html. When the download is completed, add the binaries to your PATH variable :
export PATH=$PATH:/Applications/Doxygen.app/Resources
Go to the Doxygen directory under your local symbolist repository, then launch the doxygen command :
cd /path_to_your_local_repo/Doxygen
doxygen Doxyfile
This will create an html directory and with it generate all documentation files.
Doxygen supports the javadoc style for documentation's block comments. All block comments beginning strictly with /** will be considered as documentation comments. These blocks can precede all elements of a class definition : class name, fields, constructors, methods... Comments for documentation must be written in the header files. Here is an example of block comment for the documentation of a class method presented in the Oracle's website, on the page How to Write Doc Comments for the Javadoc Tool:
/**
* Draws as much of the specified image as is currently available
* with its northwest corner at the specified coordinate (x, y).
* This method will return immediately in all cases, even if the
* entire image has not yet been scaled, dithered and converted
* for the current output device.
*
* @param img the image to be drawn
* @param x the x-coordinate of the northwest corner
* of the destination rectangle in pixels
* @param y the y-coordinate of the northwest corner
* of the destination rectangle in pixels
* @param observer the image observer to be notified as more
* of the image is converted. May be
* <code>null</code>
* @return <code>true</code> if the image is completely
* loaded and was painted successfully;
* <code>false</code> otherwise.
* @see Image
* @see ImageObserver
* @since 1.0
*/
public abstract boolean drawImage(Image img, int x, int y,
ImageObserver observer);SYMBOLIST Wiki