Development Setup

Prerequisites

Rootbeer uses mise to manage toolchain versions. Install mise, then run:

mise install

This installs the pinned versions of:

• Rust (with rustfmt, clippy, and rust-analyzer)
• Node + pnpm (for the docs site)
• lua-language-server (for Lua type checking and doc generation)
• lefthook (git hooks)

Alternatively, if you have Nix installed, you can use the provided flake to get a development shell with all dependencies:

nix develop

Or with direnv, the .envrc will automatically load the shell when you enter the project directory.

Building

With Cargo

# Debug build (binary lands in target/debug/rb)
cargo build

# Release build
cargo build --release

The debug binary is automatically on your PATH via the mise.toml env config, so you can run rb directly after building.

With Nix

# Build the package
nix build

# Run checks (clippy + fmt)
nix flake check

The binary is built to ./result/bin/rb.

Running Tests

cargo test --workspace

The test fixture lives in test/ — rootbeer.lua is a sample manifest and dotfiles/ contains files used for symlink tests.

Docs Site

The documentation site is built with VitePress. API reference pages are auto-generated from Lua doc comments via scripts/lua2md.ts.

# Install dependencies
pnpm install

# Start the dev server (auto-runs lua2md first)
pnpm dev

# Production build
pnpm build

Git Hooks

Install the pre-commit and pre-push hooks with:

lefthook install

This runs automatically on commit:

Hook	Action
pre-commit	cargo fmt, cargo clippy --fix, pnpm oxfmt

All fixers auto-stage corrected files so commits are always clean.

Editor Setup

For the best experience working on Lua modules, configure your editor to use lua-language-server with the lua/ directory. The @meta file at lua/rootbeer/core.lua provides type information for all native bindings, giving you autocomplete and diagnostics in the high-level modules.