Information for developers

Building the Manual with Sphinx

To build this manual using Sphinx, follow these steps:

  1. 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
    
  2. 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.

  1. Ensure the following prerequisites are met:

    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.

  2. 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
    
  3. 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. 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 -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
    
  4. 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/"
    
  5. 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
    
  6. 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

The command for uploading the generated wheels on PyPi is:

python -m twine upload --repository pypi *