qi 3.0.0

LibQi Python bindings

This repository contains the official Python bindings of the LibQi, the qi Python module.

Building

This project supports the building of a standalone package (for instance as a wheel that can be uploaded on PyPi) or of a “system” archive.

Standalone (wheel)

This build mode is also referred to as the standalone mode. It is enabled by passing -DQIPYTHON_STANDALONE=ON to the CMake call. The Python setup script also sets this mode automatically when used.

In this mode, the project will build libqi and install all its dependencies as part of the project.

The package can be built from the setup.py script:

python3 ./setup.py bdist_wheel

or

pip3 wheel . --no-use-pep517

The use of PEP517 is not yet supported and still problematic with our setup script, so we have to disable it.

The setup script uses scikit-build which is itself based on setuptools. It handles any option the latter can handle. Additionally, it can take CMake arguments, which means that you can almost entirely customize how the native part is built.

In particular, you can use the CMAKE_TOOLCHAIN_FILE variable to specify a toolchain to build the native part of the wheel (e.g. if you are using qi toolchains):

python3 ./setup.py bdist_wheel -DCMAKE_TOOLCHAIN_FILE=$HOME/.local/share/qi/toolchains/my_toolchain/toolchain-my_toolchain.cmake

System archive

This build mode is also referred to as the “system” mode. This is the default mode.

In this mode, CMake will expect libqi to be available as a binary package. The simplest way to build the package in this mode is to use qibuild, which will first build libqi then libqi-python.

qibuild configure
qibuild make

You can also set the QI_DIR variable at the CMake call to let it know it of the location of the libqi package.

mkdir build && cd build
cmake .. -DQI_DIR=/path/to/libqi/install/dir
cmake --build .

Technical details

The compiled/native part of this project is based on CMake. It can be built as any other project of the sort and also through qibuild, although it requires at least CMake v3.17.

Our CMake scripts may take a few parameters:

• QIPYTHON_STANDALONE, when set, builds the library in standalone mode. Refer to the standalone section for details.

• QIPYTHON_FORCE_STRIP, when set, forces the build system to strip the libqi-python native module library at install, resulting in a smaller binary.

• QI_WITH_TESTS, when set, enables building of tests. This option is ignored when cross-compiling.

Dependencies

The project has a few dependencies and the build system might report errors if it fails to find them. It uses either FindXXX CMake modules through the find_package command or the FetchContent module for subprojects. Either way, any parameter that these modules and the find_package command accept can be used to customize how the build system finds the libraries or fetches the subprojects.

Most of the variables described here are defined in the cmake/set_dependencies.cmake file. You may refer to this file for more details on these variables and their values.

LibQi

The project’s dependencies on LibQi depends on the building mode:

• In system mode, it will expect to find it as a binary package. The location of the binary package installation can be specified through the QI_DIR variable.

• In standalone mode, it will download and compile it as a subproject through the FetchContent CMake module. How it is downloaded can be customized through the following variables:

  • LIBQI_VERSION

  • LIBQI_GIT_REPOSITORY

  • LIBQI_GIT_TAG

It is possible to skip the download step and use an existing source directory by setting its path as the FETCHCONTENT_SOURCE_DIR_LIBQI CMake variable. The build system will still check that the version of the sources matches the LIBQI_VERSION value if it is set.

Python

The build system uses the FindPython CMake module. It will try to honor the following variables if they are set:

• PYTHON_VERSION_STRING

• PYTHON_LIBRARY

• PYTHON_INCLUDE_DIR

pybind11

The build system will by default download and compile pybind11 as a subproject through the FetchContent CMake module. How it is downloaded can be customized through the following variables:

• PYBIND11_VERSION

• PYBIND11_GIT_REPOSITORY

• PYBIND11_GIT_TAG

Boost

The build system will look for the Boost libraries on the system or in the toolchain if one is set. The expected version of the libraries is specified as the BOOST_VERSION variable.

The build system uses the FindBoost CMake module.

OpenSSL

The build system uses the FindOpenSSL CMake module.

ICU

The build system uses the FindICU CMake module.

GoogleTest

The build system will by default download and compile GoogleTest as a subproject through the FetchContent CMake module. How it is downloaded can be customized through the following variables:

• GOOGLETEST_VERSION

• GOOGLETEST_GIT_REPOSITORY

• GOOGLETEST_GIT_TAG

Install

Once the project is configured, it can be built and installed as any CMake project:

mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/myinstallpath
cmake --install .

Crosscompiling

The project supports cross-compiling as explained in the CMake manual about toolchains. You may simply set the CMAKE_TOOLCHAIN_FILE variable to the path of the CMake file in your toolchain.

Testing

When enabled, tests can be executed with CTest.

cd build
ctest . --output-on-failure