Build and configuration

Build

xtensor build supports the following options:

  • BUILD_TESTS: enables the xtest and xbenchmark targets (see below).

  • DOWNLOAD_GTEST: downloads gtest and builds it locally instead of using a binary installation.

  • GTEST_SRC_DIR: indicates where to find the gtest sources instead of downloading them.

  • XTENSOR_ENABLE_ASSERT: activates the assertions in xtensor.

  • XTENSOR_CHECK_DIMENSION: turns on XTENSOR_ENABLE_ASSERT and activates dimension checks in xtensor. Note that the dimensions check should not be activated if you expect operator() to perform broadcasting.

  • XTENSOR_USE_XSIMD: enables simd acceleration in xtensor. This requires that you have xsimd installed on your system.

  • XTENSOR_USE_TBB: enables parallel assignment loop. This requires that you have you have tbb installed on your system.

  • Optionally use XTENSOR_TBB_THRESHOLD to set a minimum size to trigger parallel assignment (default is 0)

  • XTENSOR_USE_OPENMP: enables parallel assignment loop using OpenMP. This requires that OpenMP is available on your system.

All these options are disabled by default. Enabling DOWNLOAD_GTEST or setting GTEST_SRC_DIR enables BUILD_TESTS.

If the BUILD_TESTS option is enabled, the following targets are available:

  • xtest: builds an run the test suite.

  • xbenchmark: builds and runs the benchmarks.

For instance, building the test suite of xtensor with assertions enabled:

mkdir build
cd build
cmake -DBUILD_TESTS=ON -DXTENSOR_ENABLE_ASSERT=ON ../
make xtest

Building the test suite of xtensor where the sources of gtest are located in e.g. /usr/share/gtest:

mkdir build
cd build
cmake -DGTEST_SRC_DIR=/usr/share/gtest ../
make xtest

Configuration

xtensor can be configured via macros, which must be defined before including any of its header. Here is a list of available macros:

  • XTENSOR_ENABLE_ASSERT: enables assertions in xtensor, such as bound check.

  • XTENSOR_ENABLE_CHECK_DIMENSION: enables the dimensions check in xtensor. Note that this option should not be turned on if you expect operator() to perform broadcasting.

  • XTENSOR_USE_XSIMD: enables SIMD acceleration in xtensor. This requires that you have xsimd installed on your system.

  • XTENSOR_USE_TBB: enables parallel assignment loop. This requires that you have you have tbb installed on your system.

  • XTENSOR_USE_OPENMP: enables parallel assignment loop using OpenMP. This requires that OpenMP is available on your system.

  • XTENSOR_DEFAULT_DATA_CONTAINER(T, A): defines the type used as the default data container for tensors and arrays. T is the value_type of the container and A its allocator_type.

  • XTENSOR_DEFAULT_SHAPE_CONTAINER(T, EA, SA): defines the type used as the default shape container for tensors and arrays. T is the value_type of the data container, EA its allocator_type, and SA is the allocator_type of the shape container.

  • XTENSOR_DEFAULT_LAYOUT: defines the default layout (row_major, column_major, dynamic) for tensors and arrays. We strongly discourage using this macro, which is provided for testing purpose. Prefer defining alias types on tensor and array containers instead.

  • XTENSOR_DEFAULT_TRAVERSAL: defines the default traversal order (row_major, column_major) for algorithms and iterators on tensors and arrays. We strongly discourage using this macro, which is provided for testing purpose.

Build the documentation

First install the tools required to build the documentation:

conda install breathe doxygen sphinx_rtd_theme -c conda-forge

You can then build the documentation:

cd docs
make html

Type make help to see the list of available documentation targets.