# 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.