Development

This page covers the tested local development flow. The commands below create a local development installation; they do not produce a wheel suitable for upload to a package index.

Build from source

Build from source when you are developing Vane Data, testing unreleased changes, or using a platform without a matching wheel. Vane supports Python 3.10, 3.11, and 3.12. Python 3.12 is recommended, is the primary development version, and is used by the Ubuntu 24.04 x86-64 CI development path. Other native toolchains and distributions may require additional setup.

Clone the repository with submodules:

shell

git clone --recursive https://github.com/AstroVela/vane.git
cd vane

If the checkout already exists and submodules are missing:

shell

git submodule update --init --recursive

On Ubuntu 24.04, install the native build tools used by CI:

shell

sudo apt-get update
sudo apt-get install -y \
  autoconf automake bison build-essential ccache curl flex git libtool \
  ninja-build pkg-config tar unzip zip

Install uv, then create and activate a Python 3.12 virtual environment and install the build dependency group declared by the repository:

shell

uv venv --python 3.12
source .venv/bin/activate
uv pip install --group build

Bootstrap the pinned C++ dependencies from the repository root:

shell

bash scripts/bootstrap_vcpkg.sh

The helper reads the exact baseline from vcpkg.json, installs packages into vcpkg_installed, reuses the repository's vcpkg binary cache, and verifies the committed native-dependency license bundle. Vane's CMake configuration discovers vcpkg_installed automatically, so do not set CMAKE_TOOLCHAIN_FILE.

Build and install a local, non-editable Release-mode package:

shell

export SKBUILD_BUILD_DIR="$PWD/build/python-release"
export SKBUILD_CMAKE_BUILD_TYPE=Release


uv pip install . --no-build-isolation

Using uv pip install instead of uv sync is intentional: the default Ray runner imports Vane in worker processes, while an editable installation can invoke CMake again during each worker import. Rerun the install command after changing source code; Python-only changes do not require a native recompile, while native changes reuse the incremental build directory. Rerun scripts/bootstrap_vcpkg.sh after changing vcpkg.json. If CMake options change, select a fresh SKBUILD_BUILD_DIR or remove the old build directory before rebuilding.

Formatting

The source CONTRIBUTING.md describes formatting through scripts/format. Install the root formatting hooks first:

shell

uv pip install pre-commit

Examples:

shell

scripts/format root --changed
scripts/format submodule --changed
scripts/format workspace --changed

The root formatter avoids scanning external/duckdb by default. Use the submodule command when changing DuckDB internals.

Tests

Install the test dependency group, then run the same base-installation gate as CI:

shell

uv pip install --group test
scripts/run_release_tests.sh

The broader compatibility suite and a focused local test can be run separately:

shell

python -m pytest tests/fast
python -m pytest tests/fast/test_udf_process.py

Some compatibility tests require optional services, credentials, model weights, or GPUs and should skip with a clear reason when that environment is absent.