How to set up a development environment¶

To change sharedbox, you need your own copy that you can build and test. Setting it up takes one clone and one command, once you have the tools below.

Before you start¶

Clone and build¶

git clone https://github.com/jacopoabramo/sharedbox.git
cd sharedbox
uv sync --dev

uv sync --dev creates .venv, builds the extension with CMake and installs it. The build uses scikit-build-core and nanobind, which uv fetches by itself. Each Python version builds into a folder of its own named after its wheel, such as build/cp311-cp311-win_amd64.

uv sync builds the extension again when a C++ source, a header, a file in cmake/ or CMakeLists.txt has changed since the last build. Run it after each such change, before running the tests.

The version comes from the git tags, through setuptools-scm, and is written to src/sharedbox/_version.py, which git ignores.

Point VS Code at the headers¶

If you use VS Code's C/C++ extension, run this once after uv sync --dev, so it finds the CPython, nanobind and sharedbox headers the build uses:

uv run python scripts/vscode_setup.py

Run it again after changing the Python version or deleting build/.

Install the git hook¶

Once per clone, so formatting and lint run on every commit:

uv run prek install

See How to run the commit checks for what the hook does.

Check that it works¶

uv run tox

This runs the tests on every supported Python version, the type checks, the lint and the docs build, each in its own environment built from uv.lock. How to run the tests explains each environment.