1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
|
# Development
The project uses git and [Gitlab](https://about.gitlab.com) to manage the source code, bug reports, and issues.
You are free to fork the project and are welcome to propose evolutions. The preferred way of submitting patches is through Gitlab's merge request mechanism.
Bugs can be reported via the [Issues](https://gitlab.com/sfcgal/SFCGAL/-/issues) section of the Gitlab 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 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 developed on its own temporary branch.
Version numbers follow the [Semantic Versioning 2.0.0](https://semver.org) policy and are tagged as **x.y.z**, where:
- **x** is the major version number. It changes in case of API breaks or major redesign.
- **y** is the minor version number. It changes when new functionalities are added without a major API break.
- **z** is the patch version number. It changes when bugs 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 (ccmake or cmake-gui) to configure the build:
```bash
mkdir build_debug
cd build_debug
ccmake -DCMAKE_BUILD_TYPE=Debug .. && make -j 2
```
Environment variables and build options are listed in the installation [section](./installation.md).
## Tests
SFCGAL comes with different layers of tests. The `SFCGAL_BUILD_TESTS` CMake option allows you to build these tests.
Note: Tests should run from within the build directory. If you have built in `Debug`, you must add `d` at the end of the binary name.
- **Unit tests**: Test each feature independently with hand-crafted datasets that must cover every possible case. Run it with `test/unit/unit-test-SFCGAL`.
- **Regression tests**: Consist of function calls with real or near-real datasets. Run it with `test/regress/standalone/standalone-regress-test-SFCGAL`.
- **Garden test**: Inspired by the eponymous PostGIS test, it ensures that all combinations of parameters are acceptable for each function (i.e., no crashes occur). Run it with `garden-test-SFCGAL`.
- **Style test**: Ensures the code is properly formatted before committing. Run the script `test-style-SFCGAL.sh`.
- **Benchmark tests**: Measure the processing speed of SFCGAL algorithms. Compilation is available through the `SFCGAL_BUILD_BENCH` CMake option.
To list all known test run add the option `--list_content` to test binary. For example, `test/unit/unit-test-SFCGALd --list_content`.
To run a specific test use the option `-t` with the test name retrieve above. For example, `test/unit/unit-test-SFCGALd -t 'SFCGAL_sfcgal_cTest/testEnvelope*'`.
## Valgrind
[Valgrind](https://valgrind.org/) 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 special option is needed (not for production!) at `cmake` time: `-DSFCGAL_VALGRIND=ON`. This enable a specific define for CGAL: `CGAL_DISABLE_ROUNDING_MATH_CHECK` (see <https://github.com/CGAL/cgal/issues/3180#issuecomment-947376584>).
Then you can run the tests with, for example, this command: `valgrind --leak-check=yes -- test/unit/unit-test-SFCGALd -t 'SFCGAL_sfcgal_cTest*'`
## Documentation
The SFCGAL documentation is primarily written in [Doxygen](https://www.doxygen.nl/). If Doxygen is available, you can run `make doc` to generate the code documentation.
## Releasing
To release 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 from Gitlab (Gitlab will create the tag for you).
- Update links to the new version in the gh-pages branch.
## Bindings
SFCGAL can be accessed from a variety of other languages via bindings to the library.
### Python (official)
[PySFCGAL](https://gitlab.com/sfcgal/pysfcgal) by the SFCGAL Team.
### Rust
[sfcgal-rs](https://github.com/mthh/sfcgal-rs) and [sfcgal-sys](https://github.com/mthh/sfcgal-sys) by Matthieu Viry.
### Nim
[sfcgal.nim](https://gitlab.com/lbartoletti/sfcgal.nim) by Loïc Bartoletti.
|
