Building¶
Prerequisites - Caribou¶
At the moment, the only way to install Caribou is by compiling it. The following table states packages dependencies required before starting the compilation.
Package |
Type |
Ubuntu |
Mac OSX |
Description |
---|---|---|---|---|
Required |
|
|
Used everywhere inside Caribou has the main linear algebra library. |
|
Python 3 libs |
Optional |
|
|
Used for the python bindings of Caribou objects. |
Optional |
|
|
Used for the python bindings of Caribou objects. |
|
OpenMP |
Optional |
|
|
Used to parallelize the computation of some components. |
Intel MKL |
Optional |
|
Used by Eigen for optimization of some math operations. |
|
Google test suite |
Optional |
|
Used for the unit tests of Caribou. |
|
Optional |
See below for more information |
|||
Optional |
See below for more information |
Prerequisites - SofaCaribou (optional)¶
If you want to compile the Caribou’s SOFA plugin (alias SofaCaribou), you will need to either:
[Method 1] Install the SOFA binaries and headers somewhere on your computer and note its installation directory. Or,
[Method 2] Compile it following the SOFA build documentation. Once it is built, execute the installation by going into the build directory of SOFA (for example, /home/user/sofa/build/master/), and using the command
cmake --install .
Once done, export the installation path of SOFA inside the SOFA_INSTALL
environment variable. For example,
$ export SOFA_ROOT="/home/user/sofa/build/master/install"
Note
To make sure your SOFA_ROOT
is well defined, you can verify that the following file path exists:
$SOFA_ROOT/lib/cmake/SofaFramework/SofaFrameworkTargets.cmake
Prerequisites - SofaPython3 bindings (optional)¶
If you want the SofaCaribou python bindings, you will also need to compile the SofaPython3 plugin. This plugin allows you to compile it using two different methods.
“in-tree” build type, which is, building the plugin along with the compilation of SOFA using the
CMAKE_EXTERNAL_DIRECTORIES
CMake variable of SOFA. This means that when you compile SOFA, you also compile the SofaPython3 plugin at the same time, using the same build directory. The plugin binaries will be found at the same place as the SOFA ones.“out-of-tree” build type, which is, building the plugin in its own build directory, outside of SOFA.
If you used “in-tree” build type, nothing more has to be done. The installation files of the SofaPython3 plugin have been installed alongside the SOFA ones.
If instead you used the “out-of-tree” build type,
you will need to install the built files by using the command cmake --install .
in the build directory of the plugin (similarly to what you have done with SOFA in the last section).
Once done, export the installation path of SofaPython3 inside the SP3_ROOT
environment variable. For example, for
an out-of-tree build in the /home/user/plugin.SofaPython3 directory:
$ export SP3_ROOT="/home/user/plugin.SofaPython3/build/master/install"
For an “in-tree” build type, the SP3_ROOT
environment variable will be $SOFA_ROOT/plugins/SofaPython3
exactly the same as the SOFA_ROOT
environment variable defined earlier.
Note
To make sure your SP3_ROOT
is well defined, you can verify that the following file path exists:
$SP3_ROOT/lib/cmake/SofaPython3/PluginTargets.cmake
Compiling¶
All right, at this point you should have everything needed to compile Caribou. If you are also building SofaCaribou and
its python bindings, you also have defined the SOFA_ROOT
and SP3_ROOT
environment variables.
Start by cloning the Caribou source code and create a build directory inside of it.
$ git clone https://github.com/jnbrunet/caribou.git
$ cd caribou
$ mkdir build
$ cd build
Next, cmake will be use to configure the build option. It is used with the following format: cmake -DVAR=VALUE ..
where VAR is the name of a configuration variable and VALUE is the value assigned to the variable. Caribou provides
the following configuration variables:
Var |
Value |
Default |
Description |
---|---|---|---|
CARIBOU_USE_FLOAT |
ON/OFF |
OFF |
Specify if the floating point type should be float (OFF) or double(ON). |
CARIBOU_BUILD_TESTS |
ON/OFF |
OFF |
Whether or not the test suite of Caribou should be build. |
CARIBOU_WITH_SOFA |
ON/OFF |
ON |
Compile the Caribou’s SOFA plugin (SofaCaribou). |
CARIBOU_OPTIMIZE_FOR_NATIVE |
ON/OFF |
ON |
Tell the compiler to optimize Caribou following the architecture of your computer. |
CARIBOU_WITH_PYTHON_3 |
ON/OFF |
ON |
Compile Caribou’s python bindings. |
CARIBOU_WITH_MKL |
ON/OFF |
ON |
Compile Caribou with Intel® Math Kernel Library (MKL) support. |
CARIBOU_WITH_OPENMP |
ON/OFF |
ON |
Compile Caribou with OpenMP support. |
CMAKE_INSTALL_PREFIX |
Path |
install/ |
Specify where the built files (following the make install command) should be installed. |
If you are compiling the Caribou’s SOFA plugin, you will also need to tell cmake where it should find it. Caribou will automatically
find it by looking inside the SOFA_ROOT
environment variable. Otherwise, if the SOFA_ROOT
environment variable cannot be used,
setting the cmake variable CMAKE_PREFIX_PATH
to $SOFA_ROOT/lib/install/cmake
should also work. The same
thing needs to be done with SofaPython3 if you are also compiling Caribou’s python bindings and if SofaPython3 was compiled
out-of-tree. In this case, you can set CMAKE_PREFIX_PATH
to $SP3_INSTALL/lib/install/cmake
.
For example, if you want to compile Caribou with MKL support and python bindings:
$ cmake -DCARIBOU_WITH_MKL=ON -DCARIBOU_WITH_PYTHON_3=ON ..
If you want to compile Caribou with SOFA and python bindings:
$ export SOFA_ROOT=/opt/sofa/build/install
$ export SP3_ROOT=/opt/SofaPython3/build/install
$ cmake -DCARIBOU_WITH_PYTHON_3=ON -DCMAKE_PREFIX_PATH="$SP3_ROOT/lib/cmake" ..
You can now start the compilation.
$ cmake --build . -j4
$ cmake --install .
The last command (cmake --install .
) installed all the built files inside the directory install
(or the directory
specified by the cmake variable CMAKE_INSTALL_PREFIX
if you changed it). Export this path to the environment variable
CARIBOU_ROOT
:
$ export CARIBOU_ROOT="${PWD}/install"
Note
To make sure your CARIBOU_ROOT
is well defined, you can verify that the following file path exists:
$CARIBOU_ROOT/lib/cmake/Caribou/CaribouTargets.cmake
Installing python bindings¶
If you compiled the Caribou’s python bindings, and you want them to be found automatically by your python scripts, you can create a symbolic link to the binding directories inside Python’s site-package path:
For linux, this can be done with the following command:
$ ln -sFfv $(find $CARIBOU_ROOT/lib/python3/site-packages -maxdepth 1 -mindepth 1) $(python3 -m site --user-site)
And for Mac OSX:
$ ln -sFfv $(find $CARIBOU_ROOT/lib/python3/site-packages -d 1) $(python3 -m site --user-site)
You can test that the bindings have been correctly installed by starting a python shell and import Caribou:
import Caribou
# Do the following only if you compiled the Caribou's SOFA plugin
import SofaRuntime
import SofaCaribou