Tutorial: Building a C++ package#

This example shows how to build a C++ project with CMake and use it together with pixi-build. To read more about how building packages work with pixi see the Getting Started guide.

We'll start off by creating a project that use nanobind to build Python bindings. That we can also test using pixi. We'll later combine this example together with a Python package.

Warning

pixi-build is a preview feature, and will change until it is stabilized. Please keep that in mind when you use it for your projects.

Creating a new project#

To get started, create a new project with pixi:

pixi init python_bindings

This should give you the basic pixi.toml to get started.

We'll now create the following source directory structure:

python_bindings/
├── CMakeLists.txt
├── pixi.toml
├── .gitignore
└── src
    └── bindings.cpp

Creating the project files#

Next up we'll create the:

pixi.toml file that will be used to configure pixi.
CMakeLists.txt file that will be used to build the bindings.
src/bindings.cpp file that will contain the bindings.

The `pixi.toml` file#

Use the following pixi.toml file, you can hover over the annotations to see why each step was added.

[workspace]
channels = [
  "https://prefix.dev/pixi-build-backends",
  "https://prefix.dev/conda-forge",
]
platforms = ["osx-arm64", "osx-64", "linux-64", "win-64"]
preview = ["pixi-build"] Add the preview feature pixi-build that enables pixi to build the package.


[dependencies] These are the workspace dependencies. We add our own package as well as Python so that we can later run our package.

python = "3.12.*"
python_bindings = { path = "." }

[tasks]
start = "python -c 'import python_bindings as b; print(b.add(1, 2))'" Let's add a task that will run our test


[package] This is where we specify the package name and version.
   This section denotes that there is both a workspace and a package defined by this pixi.toml file.

name = "python_bindings"
version = "0.1.0"

[package.build]
backend = { name = "pixi-build-cmake", version = "0.1.*" } We use pixi-build-cmake as the build-system, so that we get the backend to build cmake packages.

[package.build.configuration]
extra-args = ["-DCMAKE_BUILD_TYPE=Release"] Optionally, we can add extra arguments to the CMake invocation (e.g. -DCMAKE_BUILD_TYPE=Release or -DUSE_FOOBAR=True). This totally depends on the specific project / CMakeLists.txt file.


[package.host-dependencies]
cmake = "3.20.*"   We override the cmake version to ensure it matches our CMakeLists.txt file.

nanobind = "2.4.*" We use the nanobind package to build our bindings.

python = "3.12.*"  We need python to build the bindings, so we add a host dependency on the python package.

The `CMakeLists.txt` file#

Next lets add the CMakeList.txt file:

cmake_minimum_required(VERSION 3.20...3.27)
project(python_bindings)

find_package(Python 3.8 COMPONENTS Interpreter Development.Module REQUIRED) Find python, this actually finds anything above 3.8, but we are using 3.8 as a minimum version.


execute_process(
  COMMAND "${Python_EXECUTABLE}" -m nanobind --cmake_dir
  OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE nanobind_ROOT
) Because we are using python in a conda environment we need to query the python interpreter to find the nanobind package.


execute_process(
    COMMAND ${Python_EXECUTABLE} -c "import sysconfig; print(sysconfig.get_path('purelib'))"
    OUTPUT_VARIABLE PYTHON_SITE_PACKAGES
    OUTPUT_STRIP_TRAILING_WHITESPACE
) Because we want to make the installation directory independent of the python version, we query the python site-packages directory.


find_package(nanobind CONFIG REQUIRED) Find the installed nanobind package.


nanobind_add_module(${PROJECT_NAME} src/bindings.cpp) Use our bindings file as the source file.


install( Install the bindings into the designated prefix.

    TARGETS ${PROJECT_NAME}
    EXPORT ${PROJECT_NAME}Targets
    LIBRARY DESTINATION ${PYTHON_SITE_PACKAGES}
    ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
    RUNTIME DESTINATION ${BINDIR}
)

The `src/bindings.cpp` file#

Next lets add the src/bindings.cpp file, this one is quite simple:

#include <nanobind/nanobind.h>

int add(int a, int b) { return a + b; } We define a function that will be used to add two numbers together.


NB_MODULE(python_bindings, m)
{
    m.def("add", &add); We bind this function to the python module using the nanobind package.

}

Testing if everything works#

Now that we have created the files we can test if everything works:

$ pixi run start
3

This command builds the bindings, installs them and then runs the test task.

Conclusion#

In this tutorial, we created a pixi package using C++. It can be used as-is, to upload to a conda channel. In another tutorial we will learn how to add multiple pixi packages to the same workspace and let one pixi package use another.

Thanks for reading! Happy Coding 🚀

Any questions? Feel free to reach out or share this tutorial on X, join our Discord, e-mail us or follow our GitHub.