See also

This manual refers to Codac v1, but a new v2 implementation is currently in progress… an update of this manual will be available soon. See more.

Information for developers

In case you are willing to contribute to Codac, here are some information that may be useful.

Definition

CMake supports the following options for development:

Option

Description

CMAKE_INSTALL_PREFIX

See more

CMAKE_BUILD_TYPE

See more

CMAKE_PREFIX_PATH

See more

WITH_CAPD=ON

See more (not fully supported yet)

BUILD_TESTS
By default, the tests are not built.
To enable the compilation of tests:
cmake <other_cmake_options> -DBUILD_TESTS=ON ..

TEST_EXAMPLES

This will add the execution of the examples in the tests list.

cmake <other_cmake_options> -DTEST_EXAMPLES=ON ..

WITH_PYTHON

Note: you need to have doxygen and Python3 installed on your computer.

To enable the compilation of Python binding:

cmake <other_cmake_options> -DWITH_PYTHON=ON -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_C_FLAGS="-fPIC" ..

This configuration generates header files containing docstrings for Python, based on the content of XML files made by Doxygen. The documentation of any C++/Python function is then located in the C++ header files of the /src directory.

PYTHON_EXECUTABLE

(optional) Specifies the executable (and version) of Python. For instance:

cmake <other_cmake_options> -DPYTHON_EXECUTABLE=/usr/bin/python3.10 ..

Tips

To speed up the compilation with make and take benefit of, for example, 4 cores of your processor, use the -j option:

cd build
make -j4

Tests

Launch the tests:

cd build
make test

User manual

Build this user manual using Sphinx:

# Install Sphinx with
pip3 install -U sphinx breathe sphinx_rtd_theme sphinx-tabs sphinx-issues sphinx-reredirects

# Build the doc
cd build
make doc

The website will be generated in build/doc/.

API technical documentation

For building the API technical documentation using Doxygen:

# Install Doxygen with
sudo apt install doxygen graphviz

The API pages will be generated in build/doc/api/html/.

Script make.sh

One shortcut to build all the examples (including 3rd parties) is given by:

# From Codac root
./make.sh examples

Note that the build folders of each example is removed before the build.

One shortcut to build the tests is given by:

# From Codac root
./make.sh tests

One shortcut to build both the examples and tests is:

# From Codac root
./make.sh all

Visualization of graphs of CN

sudo apt install dot2tex

Install IBEX for Python binding (example of local install)

cmake -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_C_FLAGS="-fPIC" -DCMAKE_BUILD_TYPE=Debug -DCMAKE_INSTALL_PREFIX=$HOME/ibex-lib/build_install ..

IBEX uses the GAOL library by default, but Filib++ is also supported. Use -DINTERVAL_LIB=filib during the CMake configuration to use it.

Installing local Python binding

Warning

The binding is not working with G++7 for the moment.

Get Pybind11 as submodule:

git submodule init
git submodule update

Then, configure cmake with your custom options <...> and -DWITH_PYTHON=ON:

cmake <...> -DWITH_PYTHON=ON -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_C_FLAGS="-fPIC" ..

This configuration generates header files containing docstrings for Python, based on the content of XML files made by Doxygen. The documentation of any C++/Python function is then located in the C++ header files of the /src directory.

Note that you also have to configure IBEX with the -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_C_FLAGS="-fPIC" flag.

Finally, after the compilation of Codac (and IBEX):

# from codac repository
cd build/python/python_package
python3 setup.py develop --user

Script to create a first draft of binding

Copy the pybind11gen.py script in the sources folder. Then, for instance:

python3 pybind11gen.py module_name=RandTrajectory codac_RandTrajectory.h
# get the files in /tmp

[For admins] Upload Python binding on PyPi (see Codac repo)

Tag the current version:

git tag -a v3.0.0-beta1
git push origin v3.0.0-beta1

Warning

-beta1 part in the version might not be always supported.

Get all the wheels generated by GitHub Actions (the generated release needs to be explicitely set as latest):

sudo apt install curl wget sed
cd scripts/wheels
chmod a+x *.sh
./getlatestcodacwhl.sh
rm lk_codac_whl.ver # Optional, contain the version number that was last downloaded.

Note

For another version than the latest release, use ./gencodacwhl.sh instead of ./getlatestcodacwhl.sh and enter the desired version when asked.

Upload the wheels on PyPi:

python3 -m twine upload --repository pypi *

Testing the Linux wheels with Docker

In the codac directory, test the x86_64 Linux configuration locally using Docker:

chmod a+x scripts/docker/build_pybinding.sh
docker pull lebarsfa/manylinux_2_28_x86_64-for-codac
docker run --rm -v `pwd`:/io lebarsfa/manylinux_2_28_x86_64-for-codac /io/scripts/docker/build_pybinding.sh

The same can be done for the ARM Linux configurations (preferably from a powerful ARM computer, such as a Mac with Apple Silicon).

[For admins] Upload Ubuntu packages

Get access to https://packages.ensta-bretagne.fr/ server as a network drive from an Ubuntu computer. If not already done, run sudo apt install dpkg-dev curl to install some prerequisites. Then, run sudo ./getlatestcodacrelease.sh to download automatically the .deb files from the latest GitHub release for all the supported configurations and update the repository database (or just sudo ./gencodac.sh to download automatically a specific version without updating the database). If you downloaded manually the .deb files, you can update the repository database with sudo ./scanpackages.sh.

[For admins] Upload Windows packages

Get access to https://packages.ensta-bretagne.fr/ server as a network drive from a Windows computer. If not already done, install Chocolatey and then run choco install -y wget curl 7z checksum to install some prerequisites. Then, in choco folder, run from the Command Prompt getlatestcodacrelease.bat to generate a .nupkg from the latest GitHub release (or just gencodacpackages.bat to be able to test a specific version), then choco push codac.X.Y.Z.nupkg (need logged in Chocolatey maintainer) when the version is considered as OK to upload to the Chocolatey repository.

MATLAB compatibility

Some operators or special functions need special attention: