Local development

We recommend uv for building the project. A C++23 compiler with OpenMP support is required on your system. Platform-specific setup is described below.

Once the prerequisites are in place, set up the development environment for the first time with:

uv sync --only-dev
uv pip install --no-build-isolation -ve . \
  --config-settings cmake.build-type=Debug

The first command creates the .venv and installs all dependencies. The second compiles and installs the fast_plscan package without build isolation. Running uv sync or uv run will revert the fast_plscan package to the default state (isolated build, Release mode).

Repeat only the second command whenever C++ source files change. Python-only changes are reflected immediately without any reinstall.

Linux

It may be necessary to tell cmake which compiler it should use. For example, using g++-14 when that is not the system default:

uv pip install --no-build-isolation -ve . \
  --config-settings cmake.args="-DCMAKE_CXX_COMPILER=g++-14"

MacOS

MacOS requires installing OpenMP using homebrew:

brew install libomp

Then either export OpenMP_ROOT in your shell profile:

export OpenMP_ROOT=$(brew --prefix)/opt/libomp

or pass it as a cmake argument:

uv pip install --no-build-isolation -ve . \
  --config-settings cmake.args="-DOpenMP_ROOT=$(brew --prefix)/opt/libomp"

Windows

The default powershell terminal on windows is not configured for cmake to find the correct OpenMP version. Instead, use a developer powershell configured for a 64-bit target architecture. To open such a terminal, run the following code in a normal Powershell terminal:

$vswhere = "${env:ProgramFiles(x86)}/Microsoft Visual Studio/Installer/vswhere.exe"
$iloc = & $vswhere -products * -latest -property installationpath
$devddl = "$iloc/Common7/Tools/Microsoft.VisualStudio.DevShell.dll"
Import-Module $devddl; Enter-VsDevShell -Arch amd64 -VsInstallPath $iloc -SkipAutomaticLocation

You may also need to install the visual studio build tools.

Testing

To enable C++ coverage instrumentation, build with:

# Linux / macOS
uv pip install --no-build-isolation -ve . \
  --config-settings cmake.args="-DPLSCAN_COVERAGE=ON;-DCMAKE_BUILD_TYPE=Debug"

# Windows — -T ClangCL selects the LLVM toolset in the Visual Studio generator
uv pip install --no-build-isolation -ve . \
  --config-settings cmake.args="-DPLSCAN_COVERAGE=ON;-DCMAKE_BUILD_TYPE=Debug;-T ClangCL"

Then collect coverage with:

# Linux / macOS
bash scripts/collect_coverage.sh

# Windows (PowerShell)
pwsh scripts\\collect_coverage.ps1

Run the normal tests with:

pytest .