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:

SKBUILD_CMAKE_BUILD_TYPE=Debug pip install -e .[all]

or if you are using uv:

SKBUILD_CMAKE_BUILD_TYPE=Debug uv sync --extra all

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

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

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

1. 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.

2. 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.

3. 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)

1. Wait to see the C++ debugger attach in your CALL STACK pane. If successful you should be able to hit C++ breakpoints now.

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.