Package: example-python-extension-cpp
Python C++ extensionA template for a standalone C++ library with dependencies managed byvcpkgaccessible through Python usingpybind11.Why should I use this template?You want to write a C++ library that can be accessed through Python.You want to usecmaketo build your C++ code.You want to usepybind11to expose your C++ library as a Python module.You want to use some C++ dependencies and manage them withvcpkg. Otherwise
you should check otherscikit-build sample
projects.You are not specially concerned about build and install optimizations, it is
not a problem if they are long running.If you want to distribute your extension usingpiporcondaand you mind
that your users take a long time to install it, then it might be better to
distribute some built binaries instead of optimizing the build process. This
template might still be useful for you as it has aCDworkflow for building python wheels
withcibuildwheeland uploading them toPyPI.Example usageCreate a clean Python virtual environmentpython -m venv venvActivate it on Windows.\venv\Scripts\activateotherwisesource ./venv/bin/activateInstall this projectpip install git+https://github.com/esdandreu/python-extension-cppIt will take a while to build as it will build the C++ dependencies as well,
but it will work. It is definitely not the most optimal way of installing a
package as we are installing as well thevcpkgpackage manager and building
from source dependencies that might as well be installed on the system. But
this allows a fast development environment where adding or removing C++
dependencies should be easy.Alternatively, you can install the package from the binaries distributed inPyPIusing thecontinuous deploymentworkflow.pip install example-python-extension-cppTest that the C++ code is working in the Python packageOur simple project contains aaddfunction that adds two numbers together.python -c "import my_python_api; print(my_python_api.add(1, 2))"It also makes use of the C++ libraryfftw3that is available throughvcpkgin order to perform a Fast Fourier Transform over a generated signal, printing
its results.python -c "import my_python_api; my_python_api.hello_fft()"SetupInstall the requirementsInstallvcpkgrequirements with the
addition ofcmakeand Python. It could be summarized as:gitBuild tools (Visual
Studioon Windows orgccon Linux for example)cmakePython. Make sure to have development tools installed (python3.X-devon
Linux, beingXyour version of Python).If running on a clean linux environment (like a container or Windows Subsystem
for Linux) you will need to install some additional tools as it is stated invcpkg.sudo apt-get install build-essential curl zip unzip tar pkg-config libssl-dev python3-devCMakeFollow theofficial instructions.The requiredcmakeversion is quite high, if you are using a Linux
distribution and installingcmakefrom the repositories take into account
that they might not be updated to the latest version. However there are options
toinstall the latest version ofcmakefrom the command
line.Make sure that when you runcmake --versionthe output is3.21or higher.
The reason for this is that we are using some of the3.21features to install
runtime dependencies (managed withvcpkg) together with our project so they
are available to Python when using its API.FormattersThis project usesclang-formatto format the C++ code. There is a.clang-formatfile with options that I personally like. Downloadclang-formatas part ofLLVMfrom the officialrelease
page.I als recommend usingyapfto format python code.Clone this repository withvcpkgCone this repository withvcpkgas a submodule and navigate into it.git clone --recursive git@github.com:esdandreu/python-extension-cpp.git
cd python-extension-cppBootstrapvcpkgin Windows. Make sure you haveinstalled the
prerequisites..\vcpkg\bootstrap-vcpkg.batOr in Linux/MacOS. Make sure you haveinstalled developer
tools./vcpkg/bootstrap-vcpkg.shBuildingBuild locally with CMakeNavigate to the root of the repository and create a build directory.mkdir buildConfigurecmaketo usevcpkg.cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE="$pwd/vcpkg/scripts/buildsystems/vcpkg.cmake"Build the project.cmake --build buildBuild locally with PythonIt is recommended to use aclean virtual
environment.scikit-buildis required before running the installer, as it is the package
that takes care of the installation. The rest of dependencies will be installed
automatically.pip install scikit-build gitInstall the repository. By adding[test]to our install command we can
install additionally the test dependencies.pip install .[test]TestingTest the C++ library with Google Testctest --test-dir buildTest the python extensionpytestCI/CDThis template contains a continuous integration workflow that builds and tests
the C++ library and the python extensionci.yml.It also contains a continuous deployment workflow that builds wheels and source
distributions for the python extension, then creates a github release with it
and uploads it toPyPI:cd.yml. That workflow requires a repository secret
namedPYPI_TOKENwith a PyPI API token. is activated when pushing a version
tag to the repository:git tag -a v0.0.1 -m "First release"
git push origin --tags