FS3D uses several tools to achieve different software engineering tasks.

Git

Git is used for versionning, with three goals:

ensure there will be no code loss,
keep track of changes,
keeping a stable version even while working on experimental features.

This page gives a few git commands to get started with git usage.

Git is a versionning tool working with a local repository and one (or several) remote ones. The local repository is the one located on the user's machine.

Getting a new version (from the remote to the local)

git pull

Getting information about the current repository

git status

Saving changes in the local repository

git add file1 file2 ... filen

git commit -m "commit message"

where file1 to filen are the files to be saved and "commit message" is the message that will be saved with the commit (used later to find which modification correspond to which feature).

Saving changes in the remote (so other users can see these)

If the changes are already in the local repository:

git push

if they are not:

git add file1 file2 ... filen
git commit -m "commit message"
git push

Continuous integration

Continuous integration is a system used to track functional regressions in the development process (the project FS3D makes use of the Jenkins platform provided at ci.inria.fr).

As illustrated below, the build process requires three steps:

building the libraries files from *.m files,
copying the libraries to the new build,
building the C++ code, linking on the libraries generated previously.

This process is designed to allow seamless integration of modifications made in matlab code in the C++ software.

Automatic integration process

Several jobs are used to automatically integrate the modifications done in the matlab code in the C++ software:

First matlab libraries are built by a script (libs-fedora-23).
The success of the step above triggers a downstream project, copying the libraries generated in pre-built, compiling the C++ software, and running the tests (full-build-fedora-23).
Once a week, a specific job builds the C++ software, runs the tests and, if successful, pushes the new libraries to the main repository (update_libs).

These three steps are detailed below.

First step:

CI polls the matlab repository to track changes in the matlab code. Such a change triggers a new compilation of the *.so files, using the following script (from a terminal, assuming the access to matlab licence is already configured):

matlab -nojvm -r engine.generateLibs

This script internally uses the matlab's mcc tool to build the %module%_invoker.m files, where %module% is the module name, for example corticalmap_invoker.m, that are wrappers around the true matlab module contained in +engine.

These invoker files are responsible for reshaping the matrices, and to do whatever pre-/post-processing is required in order to adapt the files. These invoker files wrap the call of the processing methods contained in +engine.

Even though this process is designed to be as user-friendly as possible, it nevertheless comes with some limitations. Indeed, to ensure mcc (the tool used by matlab to generate *.so files) will be able to generate librairies, the matlab code should respect the following constraints:

contain processing only, no display (this of course applies only to the code of the +engine folder);
the defined functions should rely only on their inputs, not on global variables;
do not use classes' methods (this can be seen as very limiting, however a method can be easily wrapped in a functional interface);
the functions signatures (i.e. the function name and its input parameters types) should contain only simple types: real, array, matrix.
do not use nested classes or cell arrays.

The signature of the functions defined in +engine and the files suffixed by _invoker has to remain constant over time.

Second step:

Building the C++ software is handled automatically by CI, along with running the tests, after the first step has been successfully completed, or a change in the C++ repository (is-dev) is detected. It is actually the step that will fail, should the matlab code break the rules above, as the mcc does not report errors.

Third step:

This step is asynchronous, unlike the previous one. It runs every week, if a change in the matlab code is detected. It uses the libraries generated by the step 1, rebuild the software, run the tests, and then, if everything succeded pushes the new librairies to the code repository.

CMake

CMake is a build system used in FS3D for cross-platform build.