This repository contains the official Python bindings of the LibQi, the qi
Python module.
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.
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
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 .
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.
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.
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.
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
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
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.
The build system uses the FindOpenSSL CMake module.
The build system uses the FindICU CMake module.
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
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 .
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.
When enabled, tests can be executed with CTest.
cd build
ctest . --output-on-failure