Build and Configuration

Include Fastscapelib in a CMake Project

After installing Fastscapelib C++ headers (in a default location), you should be able to use CMake’s find_package to ensure these will be found when building your CMake project:

find_package(fastscapelib REQUIRED)

Don’t forget to link your target library or application with Fastscapelib:

target_link_libraries(your_target INTERFACE fastscapelib)

Build Options

Fastscapelib provides the following CMake build options (all disabled by default). See below for more explanations.

FS_BUILD_TESTS	Enables building the C++ tests
FS_DOWNLOAD_GTEST	Downloads google-test and builds it locally instead of using a binary installation
FS_GTEST_SRC_DIR	Indicates where to find the google-test sources instead of downloading them
FS_BUILD_BENCHMARKS	Enables building the micro-benchmarks
FS_DOWNLOAD_GBENCHMARK	Downloads google-benchmark and builds it locally instead of using a binary installation
FS_GBENCHMARK_SRC_DIR	Indicates where to find the google-benchmark sources instead of downloading them
FS_DOWNLOAD_XTENSOR	Downloads xtensor development version (master branch on GitHub) and uses it to build fastscapelib (useful for testing)

Pixi Configuration

Fastscapelib provides everything needed to manage its dependencies and run common tasks via pixi.

If you have pixi installed, you can install a development environment for your platform simply by executing the following command from Fastscapelib’s project root directory:

$ pixi install --environment dev

The following environments are defined:

build	All tools and dependencies needed to build and install Fastscapelib’s core (C++) library.
cpp	For running C++ tests and benchmarks.
python	All tools and dependencies needed to build Fastscapelib’s Python bindings
doc	For building Fastscapelib’s documentation.
dev	For contributing to Fastscapelib’s code (including test and lint tools).

Those environments are used to run Fastscapelib’s pixi tasks, e.g.,

$ pixi run build-python

Here is a subset of the available tasks:

run-tests	Run the C++ tests (build them if needed).
run-benchmarks	Run the benchmarks (build them if needed).
build-python	Build the Python bindings (note the python bindings are built and installed in the pixi environments during the pixi install steps)
run-tests-python	Run the Python bindings tests.
run-mypy	Run the Python static type checker.
build-doc	Build the documentation.
pre-commit-install	Run pre-commit install (a set of git hooks that will automatically check and format the source code prior to each commit)
update-compile-commands	Create of update the compile commands database (useful for C++ LSP servers)

For more details, check the pixi documentation. The full pixi configuration for Fastscapelib can be found in the pixi.toml file located in the project root directory.

Build and Run the C++ Tests

Fastscapelib has a test suite based on google-test.

You can install google-test, e.g., using conda:

$ conda install gtest -c conda-forge

Alternatively, google-test may be downloaded automatically by enabling FS_DOWNLOAD_GTEST, or a custom install path may be given by setting FS_GTEST_SRC_DIR (setting FS_DOWNLOAD_GTEST=ON or FS_GTEST_SRC_DIR=/path/to/gtest automatically sets FS_BUILD_TESTS=ON).

Tip

Download and build google-test from source as part of the Fastscapelib build process may prevent possible issues with reusing a pre-installed version of google-test that has been built with different options or flags.

To build the tests, run the following commands from the source root directory:

$ cmake -S . -B build/tests -DFS_BUILD_TESTS=ON
$ cmake --build build/tests

Then to run all the tests:

$ ctest -T test --output-on-failure build/tests

Run the Python Tests

Running the Python tests requires pytest. You can install it using, e.g., conda:

$ conda install pytest -c conda-forge

After (re)installing the Fastscapelib Python library, you can run the tests using the following command (from the repository root directory):

$ pytest -v .

Build and Run the Benchmarks

Fastscapelib has also a micro-benchmark suite based on google-benchmark.

You can install google-benchmark, e.g., using conda:

$ conda install benchmark -c conda-forge

Alternatively, google-benchmark may be downloaded automatically by enabling FS_DOWNLOAD_GBENCHMARK, or a custom install path may be given by setting FS_GBENCHMARK_SRC_DIR (setting FS_DOWNLOAD_GBENCHMARK=ON or FS_GBENCHMARK_SRC_DIR=/path/to/gbenchmark automatically sets FS_BUILD_BENCHMARKS=ON).

To build the benchmarks, run the following commands from the source root directory:

$ cmake -S . -B build/benchmarks -DFS_BUILD_BENCHMARKS=ON
$ cmake --build build/benchmarks

Then to run all the benchmarks:

$ build/benchmarks/./benchmark_fastscapelib