SFCGAL

Development

The project uses git and GitHub to manage the source code, bug reports and issues.

You are free to fork the project and welcome to propose evolutions. The prefered way of submitting patches is through the pull request mechanism of GitHub.

Bugs can be reported via the Issues section of the GitHub project.

Branches

The master branch of the repository represents the current development version of SFCGAL. Each commit on this branch is enforced not to break the compilation and unit / regression tests.

For each public release, a new tag is created on this branch.

When different major versions are to be maintained, the most recent major version is hosted on the master branch and the older versions have their own branch where fixes can be backported if needed.

In conformance with the git way of development, each new feature is made on its own temporary branch.

Version numbers follow the Semantic Versioning 2.0.0 policy and are tagged as x.y.z where :

x is the major version number. It changes in case of API break or major redesign,
y is the minor version number. It changes when new functionalities are added, without majour API break,
z is the patch version number. It changes when bug or packaging issues are resolved.

Building

The classic way of building with cmake is to first create a build directory and use a CMake client to configure the build (ccmake or cmake-gui).

mkdir build_debug
cd build_debug
ccmake -DCMAKE_BUILD_TYPE=Debug .. && make -j 2

Environment variables and build options are listed in the instalation section.

Tests

SFCGAL comes with different layers of tests. The SFCGAL_BUILD_TESTS CMake option allows to build these tests.

Unit tests are used to test each feature independently with hand-crafted dataset that must cover every possible case. Run it with unit-test-SFCGAL

Regression tests consist of call to functions with real or near-real datasets. Run it with standalone-regress-test-SFCGAL

A garden test (inspired by the eponym PostGIS test) is used to ensure every combination of parameters are acceptable parameters for each function, i.e. that no function crashes on a specific parameter combination that would not be part of the unit tests. Run it with garden-test-SFCGAL

A style test is used to ensure that code is properly formatted before committing. Run the script test-style-SFCGAL.sh.

Benchmark tests allow to test processing speed of SFCGAL algorithms. Compilation available through the SFCGAL_BUILD_BENCH CMake option.

Valgrind

Valgrind can automatically detect many memory management and threading bugs, and profile programs in detail. Since SFCGAL uses a CGAL Kernel that depends on floating point rounding modes that are not supported by the current version of valgrind, a patched version is necessary:

git clone https://github.com/trast/valgrind.git
cd valgrind/
git clone https://github.com/trast/valgrind-VEX.git VEX
./autogen.sh
./configure && make -j 8 && sudo make install

Documentation

The SFCGAL documentation is primarilly written in doxygen. If doxygen is available, you may run make doc to generate the code documentation.

Releasing

To release of a new SFCGAL version:

update the file NEWS in the master branch
change the version number in the root CMakeLists.txt in the master branch
release form github (github will create the tag for you)
udate links to the new version in gh-pages branch.