Information for developers

Building the Manual with Sphinx

To build this manual using Sphinx, follow these steps:

Requirements: Install Sphinx together with the extensions used by Codac, if they are not already installed.
```
pip install sphinx sphinx_rtd_theme furo sphinx-math-dollar sphinx_tabs breathe
```
Building the manual: After configuring the CMake project, the manual can be build with:
```
make manual
```
The generated website will be locally available in ./build/doc/manual.

To contribute and extend this manual, please consult the Sphinx documentation: https://www.sphinx-doc.org

Building a local Python binding for Codac

You can compile Codac’s Python binding binaries locally on your machine to take advantage of the library’s latest features. If you simply want to use the latest Codac release in Python, you can download the binaries directly from PyPi or follow the standard installation procedure.

Ensure the following prerequisites are met:
- the prerequisites for the C++ installation of Codac. On Linux systems, you can simply:
```
sudo apt-get install -y g++ gcc cmake git flex bison
```
- a supported version of Python (>=3.6).
- a recent Doxygen version (for instance, release 1.13.0 or newest). On Linux systems, latest releases are not available as Debian packages, so we advice to install Doxygen from the sources:
```
cd $HOME
git clone https://github.com/doxygen/doxygen
cd doxygen
git checkout Release_1_13_0 # 1.13.0, or any newer release
mkdir build ; cd build
cmake -DCMAKE_INSTALL_PREFIX=$HOME/doxygen/build_install ..
make ; make install
```
About the use of Doxygen

Doxygen software extracts C++ documentation from header files into XML format. We then convert this data into docstring format before embedding it into the binding binaries. In this way, the writing of the documentation is centralized in a single location in the C++ header files.

Configure IBEX prior to compiling Codac:

We recall that IBEX sources can be obtained with:

git clone https://github.com/lebarsfa/ibex-lib.git $HOME/ibex-lib
cd $HOME/ibex-lib

You will need to compile both IBEX and Codac using the -fPIC options. This can be done with the following CMake configuration:

mkdir build ; cd build
cmake -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_C_FLAGS="-fPIC" -DCMAKE_INSTALL_PREFIX=$HOME/ibex-lib/build_install -DCMAKE_BUILD_TYPE=Release ..
make ; make install

Compile Codac with Python binding:

We recall that Codac sources can be obtained with:
```
git clone https://github.com/codac-team/codac $HOME/codac
cd $HOME/codac
```
Using Codac v2 simultaneously with Codac v1

In case you want to use the two versions of Codac in the same Python script, you will have to compile the binaries of Codac v2 under a different name in order to avoid import conflicts. Things are already prepared in the branch codac2_renamed, you can therefore:
```
git checkout codac2_renamed
```
Note that you will then have to import codac2 instead of import codac in your Python scripts.
In addition to the -fPIC options, you will have to configure WITH_PYTHON=ON and PYBIND11_FINDPYTHON=OFF. Note that the git submodule commands will automatically get the pybind11 files required for the binding.
```
# Get automatically pybind11 and eigen submodules:
git submodule init ; git submodule update
# Configure CMake
mkdir build ; cd build
cmake -DCMAKE_CXX_FLAGS="-fPIC" -DCMAKE_C_FLAGS="-fPIC" -DWITH_PYTHON=ON -DPYBIND11_FINDPYTHON=OFF -DCMAKE_INSTALL_PREFIX=$HOME/codac/build_install -DCMAKE_PREFIX_PATH="$HOME/ibex-lib/build_install;$HOME/doxygen/build_install" -DCMAKE_BUILD_TYPE=Release ..
make ; make install
```
Configure your Python environment:

Finally, you need to configure your system so that Python can find access to your Codac binding binaries:
```
cd $HOME/codac/build/python/python_package
python setup.py develop --user
```
And update your configuration file (for instance, $HOME/.bashrc on Linux systems) with:
```
export PYTHONPATH="${PYTHONPATH}:$HOME/codac/build/python/python_package/"
```
Verify the installation (optional):

To ensure that the installation has worked properly, the unit tests of the library can be run:
```
python -m unittest discover codac.tests
```
Try an example (optional):

You may want to try Codac in Python by running one of the proposed examples. After the installation, you can run the following commands:
```
cd $HOME/codac/examples/03_sivia
python main.py
```
Note that before executing the example, you will have to launch the VIBes viewer. You should obtain a graphical output corresponding to a set inversion.

For admins

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.

The command for uploading the generated wheels on PyPi is:

python -m twine upload --repository pypi *