Installation

Python binding

Pre-compiled binding “Wheel”s are available for x64 Windows, x64 or ARM MacOS 10.15 or newer and x64 Linux systems with glibc version 2.17 or above. You can install the most recent stable release from the PyPi index using pip:

$ python -m pip install --upgrade pip
$ python -m pip install --upgrade reticula

The first command makes sure your pip installation is up-to-date, the second command installs the most recent version of Reticula from the repository.

The binding currently supports Python versions 3.10, 3.11, 3.12 and 3.13.

If you need to install the library on a system with no pre-compiled Wheels, you can also build and install the binding from scrach. Chack out the Development section for more information.

The C++ library

You can include the C++ library in your code using CMake FetchContent module. To do this, you need to specify how to fetch Reticula in your CMakeLists.txt file:

include(FetchContent)

FetchContent_Declare(
reticula
GIT_REPOSITORY https://github.com/reticula-network/reticula.git
GIT_TAG ${COMMIT_HASH})

FetchContent_MakeAvailable(reticula)

You can use a git tag or branch name or the hash of a specific commit. We recommand that you use the most recent release branch v#.# for a new project.

You can then link to the reticula target:

add_executable(my_program main.cpp)
target_link_libraries(my_program PRIVATE reticula)

Development

Building the Python binding from scratch

In order to build the Python binding on a development machine, you need to make sure Python development headers are installed and accessible, a modern version of GCC ( >= 10.2) is installed and accessible and that you have access to approximatly infinite memory (> 40GB) and about 20 minutes.

$ git clone https://github.com/reticula-network/reticula-python.git
$ cd reticula-python
$ mkdir dist
$ python -m pip install --upgrade pip
$ python -m pip wheel . -w dist/
$ python -m pip install dist/*.whl

If you actively developing the Python binding (perhaps to send a pull request? Thank you very much!) you might want to avoid re-building everything from scratch every single time. In this scenario, I recommand disabling build isolation of pip wheel by using this command instead:

$ python -m pip wheel -w dist/ --verbose --no-build-isolation -Cbuild-dir=build .

Or just directly re-install the package on your system, meaning that in every iteration you just need to run:

$ python -m pip install --verbose --force-reinstall --no-build-isolation -Cbuild-dir=build .

This requires you to have the required python packages manually installed. You can find a list of these packages and acceptable version in the pyproject.toml file under the [build-system] table.

When building a wheel you intend to distribute, you might want to copy the external shared libraries using the auditwheel tool to ensure compatibility across different Linux distributions. Refer to the auditwheel documentation for more details.

$  python -m auditwheel repair --plat manylinux_2_39_x86_64 dist/*.whl

You can use the most recent platform compatible with all the computers that will be using the wheel instead of manylinux_2_39_x86_64. A better option is to use cibuildwheel for building wheels across different platforms.

Building C++ library tests

To build the tests for the C++ library, make sure you have CMake version 3.14 or newer installed on your system. All you need to do then, is to clone the library, make a build directory and build the tests:

$ git clone https://github.com/reticula-network/reticula.git
$ cd reticula
$ mkdir build
$ cd build
$ cmake ..
$ cmake --build . --target reticula_tests -j 10

This creates an executable titled reticula_tests, which you can execute to run the runtime tests, including address, memory leak and undefined behaviour sanitizer by default.

$ ./reticula_tests

After you made some modifications to the code, to re-compile the tests just re-run the build command.

$ cmake --build . --target reticula_tests -j 10
$ ./reticula_tests