Getting Started¶
Prerequisites¶
All non-optional build dependencies are installed automatically through Conan when running CMake.
Conan itself can be installed manually but we recommend using the provided scipp-developer.yml
for installing this and other dependencies in a conda
environment (see below).
Alternatively you can refer to this file for a full list of dependencies.
See Tooling for compilers and other required tools.
Getting the code, building, and installing¶
Note that this assumes you will end up with a directory structure similar to the following. If you want something different be sure to modify paths as appropriate.
|-- scipp (source code)
| |-- build (build directory)
| |-- install (Python library installation)
| |-- ...
|-- ...
To build and install the library:
# Update Git submodules
git submodule init
git submodule update
# Create build and library install directories
mkdir build
mkdir install
cd build
# Create Conda environment with dependencies and development tools
conda env create -f ../scipp-developer.yml # For Linux
conda activate scipp-developer
To build a debug version of the library:
cmake \
-GNinja \
-DCMAKE_BUILD_TYPE=Debug \
-DPython_EXECUTABLE=$(command -v python3) \
-DCMAKE_INSTALL_PREFIX=../install \
-DCMAKE_INTERPROCEDURAL_OPTIMIZATION=OFF \
-DDYNAMIC_LIB=ON \
..
# C++ unit tests
cmake --build . --target all-tests
# Benchmarks
cmake --build . --target all-benchmarks
# Install Python library
cmake --build . --target install
Alternatively, to build a release version with all optimizations enabled:
cmake \
-GNinja \
-DPython_EXECUTABLE=$(command -v python3) \
-DCMAKE_INSTALL_PREFIX=../install \
-DCMAKE_BUILD_TYPE=Release \
..
cmake --build . --target all-tests
cmake --build . --target all-benchmarks
cmake --build . --target install
To use the scipp
Python module:
cd ../python
PYTHONPATH=$PYTHONPATH:../install python3
In Python:
import scipp as sc
Additional build options¶
-DDYNAMIC_LIB
forces the shared libraries building, that also decreases link time.-DENABLE_THREAD_LIMIT
limits the maximum number of threads that TBB can use. This defaults to the maximum number of cores identified on your build system. You may then optionally apply an artificial limit via-DTHREAD_LIMIT
.-DDISABLE_MULTI_THREADING
disable multi-threading. By default, multi-threading is enabled if TBB was found. If this option is set toON
, it overrides that.-DPRECOMPILED_HEADERS
toggle usage of precompiled headers.ON
by default.
Running the unit tests¶
Executables for the unit tests can be found in the build directory as build/XYZ/test/scipp-XYZ-test
, where XYZ
is the Scipp component under test (e.g. core
).
all-tests
can be used to build all tests at the same time. Note that simply running ctest
also works, but currently it seems to have an issue with gathering templated tests, so calling the test binaries manually is recommended (and much faster).
To run the Python tests, run (in the python/
directory):
cd python
PYTHONPATH=$PYTHONPATH:./install python3 -m pytest
Building Documentation¶
run
cmake --build . --target docs
from your build directory.This will build the documentation and put it on
<build dir>/docs
.If rebuilding the documentation is slow it can be quicker to remove the docs build directory and start a fresh build.
Precommit Hooks¶
If you wish, you can install precommit hooks for flake8 and yapf. In the source directory run:
pre-commit install
pre-commit run --all-files
Using scipp as a C++ library¶
Using Scipp as a C++ library is not recommened at this point as the API (and ABI) is not stable and documentation is sparse.
Nonetheless, it can be used as a cmake
package as follows.
In your CMakeLists.txt
:
find_package(Scipp 0.5 REQUIRED) # replace with required version
target_link_libraries(mytarget PUBLIC scipp::dataset)
If scipp was install using conda
, cmake
should find it automatically.
If you build and installed scipp from source use, e.g.,:
cmake -DCMAKE_PREFIX_PATH=<your_scipp_install_dir>
where <your_scipp_install_dir>
should point to the CMAKE_INSTALL_PREFIX
that was used when building scipp
.
Alternative set the Scipp_DIR
or CMAKE_PREFIX_PATH
(environment) variables to this path.