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.
- Pre-requisites
- Project's architecture
- Setting up the work environment
- Development guidelines & coding styles
- Writing and generating documentation
- Warning! For now, symbolist have been compiled, tested and executed only under the macOS platform (starting with version 10.10 Yosemite). Thus, all instructions and informations published here are worth only for this platform.
- Bravura font. symbolist uses the Bravura font to integrate traditional music notation symbols in its palette. Therefore, the Bravura font must be installed in your computer if you want to use these symbols. You can download the Bravura font at https://www.smufl.org/fonts/. To complete the installation of the Bravura font, copy the bravura_metadata.json file (you'll find it in the Bravura font zip file) into your /Library/Fonts/bravura folder (create this folder if it doesn't exist).
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.
- Documentation: contains the Doxygen directory to generate the doc in html format, and the Images directory where are stored the different images populating the Wiki.
- 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 than 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.The symbolist's software architecture follows the Model-View-Controller (MVC) pattern. As the JUCE framework doesn't provide generic classes to implement the MVC in its applications, an MVC API of our own "brew" is integrated in symbolist. The following figure describes the UML class diagram representing our MVC API.
The Observer and Observable classes provide an implementation of the Observer design pattern. This pattern is used in a MVC architecture to enable the communication between the model (here represented by the SymbolistModel class) and its related views and controllers. Each time a information is updated in the model, the views and controllers of the application are informed, leveraging the notification system (the method notify is executed by the model, asking all its observers to perform their update method). Views and controllers of the application are therefore subclasses of the Observer class, meaning that they are observing the model, which inherits from the Observable class.
Two abstract superclasses describing the concept of View and Controller are then inheriting from the Observer class. The View and Controller classes are abstract, considering that the update method received from the Observer class is still undefined at this level. Concrete views and controllers will determine their own update behavior.
SYMBOLIST uses the Doxygen tool to write and generate the code documentation. The next section 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);