For Developers

Building wheels

Linux

Start by installing the build dependencies, if not already installed (check Installation section):

sudo apt-get update
sudo apt-get install -y build-essential cmake ninja-build

Then create a virtual environment and install the build tools:

python3 -m venv buildenv
source buildenv/bin/activate
pip install --upgrade pip
pip install build

And if you want to be explicit:

python -m pip install "scikit-build-core" "pybind11" "wheel"

Finally build the wheel:

python -m build --wheel

This will create the wheel file in the dist/ folder.

MacOS

For MacOS we recommend using homebrew and uv. Start by installing homebrew if not already installed (see Installation section). Then install the c++ toolchain and buiild tools if not already installed:

brew install gcc cmake ninja

Then install uv if not already installed:

brew install uv

Then build the wheel with uv:

uv build --wheel

This will create the wheel file in the dist/ folder.

Windows

Start by creating a virtual environment and upgrading pip:

python -m venv myenv
myenv\Scripts\activate
python -m pip install --upgrade pip

Then install the build tools:

python -m pip install build

And if you want to be explicit:

python -m pip install "scikit-build-core" "pybind11" "wheel"

Finally build the wheel:

python -m build --wheel

This will create the wheel file in the dist/ folder.

Debugging Python and C++ code

VSCode

To debug both Python and C++ code in VSCode you need to install the Python extension and the C++ extension by Microsoft. After you create your python environment, you also need to set up a launch configuration. Below is an example launch.json configuration that you can use as a starting point:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Launch (frontend)",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}", // your current file
            "console": "integratedTerminal",
            "justMyCode": true
        },
        {
            "name": "C++: Attach to python (lldb)",
            "type": "cppdbg",
            "request": "attach",
            "MIMode": "lldb",
            "program": "${command:python.interpreterPath}", // selected env's python
            "processId": "${command:pickProcess}"
        }
    ]
}

This will allow for a two-step debugging process that is the most portable and works on most platforms. To install SERVAL in debug mode you need to satisfy all the requirements listed in the Installation section depending on your platfrom. Then run:

pip install -v --no-build-isolation -e . --config-setting=cmake.build-type=Debug

or if you are using uv:

uv pip install -v --no-build-isolation -e . --config-setting=cmake.build-type=Debug

Once the code is installed the Debugging process is as follows:

Start by selecting the correct interpreter that matches your virtual environment:

Ctrl+Shift+P -> Python: Select Interpreter -> select your env

Create breakpoints in both Python and C++ code as needed. It is recommended to set breakpoints in the binding functions in the C++ code. If a breakpoint is not set in the C++ code the debugger will not access the C++ source.
Start the Python debugger by selecting the "Python: Launch (frontend)" configuration and pressing F5. This will start the Python code execution and stop at any Python breakpoints.
When a breakpoint is hit in Python, select from the RUN AND DEBUG pane the "C++: Attach to python (lldb)" configuration and hit F5. This will try to attach the C++ debugger by asking you to select the correct running process. You can search for "python" in the list of processes to find the correct one. It should be the newest one (last one). If uncertain you can print the process id in the Python code with:

import os, sys
print(f"PYTHON PID: {os.getpid()}", file=sys.stderr)

Wait to see the C++ debugger attach in your CALL STACK pane. If successful you should be able to hit C++ breakpoints now. If your code stops but the VSCode interface does not update, go to the CALL STACK pane and click on the breakpoint on the C++ debugger. This should update the interface and show you the current line of code.
In case all works out but your C++ breakpoints are not hit include SIGTRAP somewhere in the C++ function:

#include <csignal>
void some_function() {
    // some code
    std::raise(SIGTRAP); // this will trigger a breakpoint if the debugger is attached
    // some more code
}

This will force the debugger to stop at that line if it is attached. If you cannot move forward after this point. Remove the SIGTRAP line and try to set a breakpoint on the next line. This should allow you to continue debugging without the SIGTRAP line.'

Debugging unit tests

If you would like to do debugging during unit tests, from the VScode test explorer, then add the following configuration to your launch.json:

{
    "name": "Python: Debug Tests",
    "type": "debugpy",
    "request": "launch",
    "program": "${file}",
    "purpose": [
        "debug-test"
    ],
    "console": "integratedTerminal",
    "justMyCode": true
},

The remainder of the steps are the same as above. Just make sure to start the "Python: Debug Tests" configuration first.

NOTE: 1) The selected Debug flags in CMakeLists.txt can change numerical results for very tight comparison (1E-9). If you would still want some Debug information with optimization closer to release use the RelWithDebInfo flag instead of Debug.