Build Configuration¶
CARMA v0.5 requires a compiler with support for C++14 and supports:
- Python 3.6 – 3.9
- Numpy >= 1.14
- Pybind11 >= v2.6.0
- Armadillo >= 10.5.2
CMake build¶
CARMA provides a CMake configuration that can be used to integrate into existing builds. You can either use it directly or install it first. To edit the configuration please see
It is advised to use the carma::carma
interface target that can be linked to your target.
This target pre-compiles the cnalloc.h
header containing wrappers around Numpy’s (de)allocator that are then picked up by Armadillo.
By pre-compiling the header we can ensure that the ARMA_ALIEN_MEM_ALLOC
and ARMA_ALIEN_MEM_FREE
definitions exist when including Armadillo
regardless of the include order.
Warning
if you are not using CARMA’s cmake target you have to ensure that you include CARMA before Armadillo. Not doing so results in a compile error.
Installation¶
Make sure to change the configuration if desired before installing CARMA.
CARMA can be installed using:
mkdir build
cd build
# optionally with -DCMAKE_INSTALL_PREFIX:PATH=
cmake -DCARMA_INSTALL_LIB=ON ..
cmake --build . --config Release --target install
You can than include it in a project using:
FIND_PACKAGE(carma CONFIG REQUIRED)
TARGET_LINK_LIBRARIES(<your_target> PRIVATE carma::carma)
The REQUIRED
state is propagated to the dependencies of CARMA.
Variables¶
The FIND_PACKAGE
call sets the following variables
carma_FOUND
– true if CARMA was foundcarma_INCLUDE_DIR
– the path to CARMA’s include directorycarma_INCLUDE_DIRS
– the paths to CARMA’s include directory and the paths to the include directories of the dependencies.
Components¶
When including carma using FIND_PACKAGE
two targets are created:
carma::carma
carma::carma
has been linked with Python, Numpy, Pybind11 and Armadillo and pre-compiles the cnalloc.h
header which means that there is no required order to includes or carma and armadillo. If you only want this component you can use FIND_PACKAGE(carma CONFIG REQUIRED COMPONENTS carma)
carma::headers
If you want to have a header-only target that is not linked with the dependencies and does not pre-compile cnalloc.h
. You must than make sure to link it to it’s dependencies and make sure to always include carma before armadillo.
If you only want this component you can use FIND_PACKAGE(carma CONFIG REQUIRED COMPONENTS headers)
Subdirectory¶
Alternatively, you can use CARMA without installing it by using:
ADD_SUBDIRECTORY(extern/carma)
TARGET_LINK_LIBRARIES(<your_target> PRIVATE carma::carma)
The same targets and conditions as for the installation hold, however, this build will obtain Armadillo and Pybind11 if they have not been provided.
Armadillo¶
Users can provide a specific Armadillo version by making sure the target armadillo
is set before including CARMA or by setting:
-DARMADILLO_ROOT_DIR=/path/to/armadillo/root/directory
When using the subdirectory build, if neither is set, CARMA will provide the armadillo
target at build time and store a clone of armadillo in carma/extern/armadillo-code
. The Armadillo version, by default 10.5.2
, can be set using:
-DUSE_ARMA_VERSION=10.5.x
Pybind11¶
Users can provide a specific Pybind11 version by making sure the target pybind11
is set before including CARMA or by setting:
-DPYBIND11_ROOT_DIR=/path/to/pybind11/root/directory
When using the subdirectory build, if neither is set, CARMA will provide the pybind11
target at build time and store a clone in carma/extern/pybind11
. The Pybind11 version, by default v2.6.2
can be set using:
-DUSE_PYBIND11_VERSION=v2.6.2
Python¶
CARMA needs to link against Python’s and Numpy’s headers and uses CMake’s FIND_PYTHON
to locate them.
FIND_PYTHON
doesn’t always find the right Python, e.g. when using pyenv
. When this happens you can set Python3_EXECUTABLE
, which is then also passed on to Pybind11 to ensure the same Python versions are found.
-DPython3_EXECUTABLE=$(which python3)
# or
-DPython3_EXECUTABLE=$(python3 -c 'import sys; print(sys.executable)')