Skip to content

Building From Source

Jump to bottom
Eugene Palchukovsky edited this page Aug 1, 2026 · 1 revision

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)

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

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.

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.

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.

Related Pages

  • 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

Clone this wiki locally