Building From Source¶

Contributor-facing page: how to build and test OpenPit from a checkout of the main repository.

Application developers do not need this page. Every SDK ships a prebuilt artifact, and Getting Started covers installation from the public package registries. Build from source only when working on the SDK itself, reproducing a defect against an unreleased tree, or linking an application against a locally built runtime.

The repository exposes its build and test steps as just recipes. Each recipe is a thin wrapper over the underlying toolchain command, and the manual equivalents are listed next to it so that a contributor without just can run the same steps.

Prerequisites¶

Install only the parts needed for the languages you touch.

POSIX (Linux, macOS, etc)

- [Rust toolchain](https://rustup.rs/) - [cargo-nextest](https://nexte.st/docs/installation/pre-built-binaries/) if you run Rust tests through `just` - [Python `>=3.10`](https://www.python.org/downloads/) for repository build and test recipes, generated API artifacts, and the Python binding - [Go `1.22`](https://go.dev/dl/) if you build or test the Go binding - [golangci-lint](https://golangci-lint.run/welcome/install/) if you lint Go - A C compiler from your OS package manager: the Go binding uses cgo - [Node.js `>=18`](https://nodejs.org/) if you build or test the JavaScript/WebAssembly binding - [CMake `>=3.21`](https://cmake.org/download/), a C++17 compiler, and [clang-format and clang-tidy](https://github.com/llvm/llvm-project/releases) if you build, test, format, or lint the C++ binding and examples - [Doxygen](https://www.doxygen.nl/download.html) and [Graphviz](https://graphviz.org/download/) if you generate the C++ reference documentation - Optional: [Just](https://just.systems/) for the recipe shortcuts Create the repository-local Python environment:

python3 -m venv .venv
.venv/bin/python -m pip install -r ./requirements.txt

The build recipes use this local environment for helper scripts, generated API artifacts, and Python tooling such as `maturin` and `pytest`.

Windows

- [rustup](https://rustup.rs/) with the `x86_64-pc-windows-msvc` target - [cargo-nextest](https://nexte.st/docs/installation/pre-built-binaries/) if you run Rust tests through `just` - [Python `>=3.10`](https://www.python.org/downloads/) available as `python` - [Go `1.22`](https://go.dev/dl/) if you build or test the Go binding - [golangci-lint](https://golangci-lint.run/welcome/install/) if you lint Go - [CMake `>=3.21`](https://cmake.org/download/) if you build or test the C++ binding and examples - [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) with the MSVC C++ tools if you build or test the C++ binding and examples - [LLVM](https://github.com/llvm/llvm-project/releases) if you build or test Go through cgo, format or lint C++, or use `clang`/`lld` - [Doxygen](https://www.doxygen.nl/download.html) and [Graphviz](https://graphviz.org/download/) if you generate the C++ reference documentation - Optional: [Just](https://just.systems/) for the recipe shortcuts Add the Rust target and create the repository-local Python environment:

rustup target add x86_64-pc-windows-msvc
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r .\requirements.txt

Toolchain Setup¶

just install provisions the full build toolchain in one shot: the wasm32-unknown-unknown Rust target, wasm-bindgen-cli pinned to the version the crate resolved to, the JavaScript development dependencies, and the Python development install.

just install

This installs a lot. If you do not need the full build, do not run it blindly: read the install recipe in the repository justfile and install or build only the parts you actually use.

Build¶

POSIX (Linux, macOS, etc)

### Core

just build-debug

Manual:

cargo build --workspace

### Go The Go SDK consumes the native runtime through cgo. Build the FFI library first:

cargo build -p openpit-ffi --locked

Go tests then expect the path to that library through `OPENPIT_RUNTIME_LIBRARY_PATH`. That variable is needed only for local development inside the repository - consumers installing the SDK with `go get` never set it, because the module carries an embedded runtime. See [Runtime Delivery](Runtime-Delivery.md). ### Python

just python-develop-debug

Manual:

.venv/bin/maturin develop --manifest-path bindings/python/Cargo.toml

Run `maturin develop` before `pytest`. That builds against the current checkout, including a dirty worktree. ### JavaScript The JavaScript/TypeScript binding is a WebAssembly build; there is no native add-on to compile.

just build-js

Manual:

cd bindings/js
npm install
npm run build

### C++ The C++ binding is a header-only C++17 SDK. In-repository builds link it against the locally built native runtime:

just build-cpp-debug
just build-examples-cpp-debug

Manual:

cargo build -p openpit-ffi --locked
cmake -S bindings/cpp -B bindings/cpp/build-debug \
  -DCMAKE_BUILD_TYPE=Debug \
  -DOPENPIT_RUNTIME_LIBRARY="$PWD/target/debug/libopenpit_ffi.dylib"
cmake --build bindings/cpp/build-debug --config Debug

The command above names the macOS library. On Linux use `libopenpit_ffi.so`; on Windows use `openpit_ffi.dll`. To produce an installable CMake package from the checkout, build the release runtime and install the package into a prefix of your choice:

cargo build -p openpit-ffi --release --locked
cmake -S bindings/cpp -B bindings/cpp/build \
  -DOPENPIT_RUNTIME_LIBRARY="$PWD/target/release/libopenpit_ffi.dylib"
cmake --build bindings/cpp/build
cmake --install bindings/cpp/build --prefix "$PWD/.openpit"

Windows

### Core

just build-debug

Manual:

cargo build --workspace --target x86_64-pc-windows-msvc

### Go

cargo build -p openpit-ffi --locked --target x86_64-pc-windows-msvc

Go tests then expect the path to that library through `OPENPIT_RUNTIME_LIBRARY_PATH`, and cgo needs `clang`/`lld` from LLVM on `PATH`. See [Runtime Delivery](Runtime-Delivery.md). ### Python

just python-develop-debug

Manual:

.\.venv\Scripts\python.exe -m maturin develop `
  --manifest-path bindings/python/Cargo.toml `
  --target x86_64-pc-windows-msvc

### C++

just build-cpp-debug
just build-examples-cpp-debug

Manual:

cargo build -p openpit-ffi --locked --target x86_64-pc-windows-msvc
cmake -S bindings/cpp -B bindings/cpp/build-debug `
  -DCMAKE_BUILD_TYPE=Debug `
  -DOPENPIT_RUNTIME_LIBRARY="$PWD\target\x86_64-pc-windows-msvc\debug\openpit_ffi.dll" `
  -DOPENPIT_RUNTIME_IMPORT_LIBRARY="$PWD\target\x86_64-pc-windows-msvc\debug\openpit_ffi.dll.lib"
cmake --build bindings/cpp/build-debug --config Debug

Windows needs both the runtime DLL and the matching MSVC import library. A release package is produced the same way with `--release`, the release target directory, and `cmake --install bindings/cpp/build --prefix "$PWD\.openpit"`. The `just build-cpp-release` and `just test-cpp-release` recipes wrap the release variant.

Test Matrix¶

POSIX (Linux, macOS, etc)

# Everything:
just test-all-debug

# Core:
just test-rust-debug

# Python:
just test-python-debug
just test-python-unit-debug
just test-python-integration-debug

# Go:
just test-go-debug
just test-go-race

# C++:
just test-cpp-debug
just test-examples-cpp-debug

# JavaScript:
just test-js-debug

Manual:

# Core:
cargo test --workspace

# Python:
.venv/bin/maturin develop --manifest-path bindings/python/Cargo.toml
.venv/bin/python -m pytest bindings/python/tests
.venv/bin/python -m pytest bindings/python/tests/unit
.venv/bin/python -m pytest bindings/python/tests/integration

# Go:
cargo build -p openpit-ffi --locked
cd bindings/go
export OPENPIT_RUNTIME_LIBRARY_PATH="$(pwd)/../../target/debug/libopenpit_ffi.so"
# macOS: use libopenpit_ffi.dylib instead.
go test ./...
go test -race ./...

# C++:
cargo build -p openpit-ffi --locked
cmake -S bindings/cpp -B bindings/cpp/build-debug \
  -DCMAKE_BUILD_TYPE=Debug \
  -DOPENPIT_RUNTIME_LIBRARY="$PWD/target/debug/libopenpit_ffi.dylib"
cmake --build bindings/cpp/build-debug --config Debug
ctest --test-dir bindings/cpp/build-debug --output-on-failure

# JavaScript:
cd bindings/js
npm install
npm run build
npm test

Windows

# Everything:
just test-all-debug

# Core:
just test-rust-debug

# Python:
just test-python-debug
just test-python-unit-debug
just test-python-integration-debug

# Go:
just test-go-debug
just test-go-race

# C++:
just test-cpp-debug
just test-examples-cpp-debug

Manual:

# Core:
cargo test --workspace --target x86_64-pc-windows-msvc

# Python:
.\.venv\Scripts\python.exe -m maturin develop `
  --manifest-path bindings/python/Cargo.toml `
  --target x86_64-pc-windows-msvc
.\.venv\Scripts\python.exe -m pytest bindings/python/tests

# Go:
cargo build -p openpit-ffi --locked --target x86_64-pc-windows-msvc
$env:OPENPIT_RUNTIME_LIBRARY_PATH = `
  (Resolve-Path target\x86_64-pc-windows-msvc\debug\openpit_ffi.dll)
$env:CGO_ENABLED = "1"
$env:CC = "clang -fuse-ld=lld"
$env:CXX = "clang++ -fuse-ld=lld"
Push-Location bindings\go
go test ./...
go test -race ./...
Pop-Location

# C++:
cargo build -p openpit-ffi --locked --target x86_64-pc-windows-msvc
cmake -S bindings/cpp -B bindings/cpp/build-debug `
  -DCMAKE_BUILD_TYPE=Debug `
  -DOPENPIT_RUNTIME_LIBRARY="$PWD\target\x86_64-pc-windows-msvc\debug\openpit_ffi.dll" `
  -DOPENPIT_RUNTIME_IMPORT_LIBRARY="$PWD\target\x86_64-pc-windows-msvc\debug\openpit_ffi.dll.lib"
cmake --build bindings/cpp/build-debug --config Debug
ctest --test-dir bindings/cpp/build-debug --output-on-failure --build-config Debug

Every recipe has -release and, for most languages, -full variants that run the debug and release suites in sequence.

Getting Started: Install a released SDK and run a first end-to-end flow
Runtime Delivery: How each SDK obtains and loads the native runtime, including the environment overrides used by local builds
Errors: What each SDK returns as a value and what it raises

Building From Source¶

Prerequisites¶

Toolchain Setup¶

Build¶

Test Matrix¶

Related Pages¶