Development Setup

How to set up a development environment for working on TeaLeaf. See also the comprehensive CONTRIBUTING.md in the repository root for project architecture, version management, and PR guidelines.

Prerequisites

Tool	Version	Purpose
Rust	1.70+	Core library, CLI, FFI
.NET SDK	8.0+	.NET bindings and tests
Git	Any	Version control

Optional:

Protobuf compiler (for benchmark suite)
mdBook (for documentation)

Clone and Build

git clone https://github.com/krishjag/tealeaf.git
cd tealeaf

# Build everything
cargo build --workspace

# Build release
cargo build --workspace --release

Project Layout

tealeaf/
├── tealeaf-core/          # Core library + CLI binary
├── tealeaf-derive/        # Proc-macro (derive macros)
├── tealeaf-ffi/           # C FFI layer
├── bindings/dotnet/       # .NET bindings
├── canonical/             # Shared test fixtures
├── spec/                  # Format specification
├── examples/              # Example files
├── docs-site/             # Documentation site (mdBook)
└── accuracy-benchmark/    # Accuracy benchmark tool

Running Tests

Rust

# All tests
cargo test --workspace

# Specific package
cargo test --package tealeaf-core
cargo test --package tealeaf-derive
cargo test --package tealeaf-ffi

# Specific test file
cargo test --package tealeaf-core --test canonical
cargo test --package tealeaf-core --test derive

# With output
cargo test --workspace -- --nocapture

.NET

cd bindings/dotnet
dotnet build
dotnet test

Lint

cargo clippy --workspace
cargo fmt --check

Development Workflows

Modifying the Parser

Edit tealeaf-core/src/lib.rs (lexer and parser live here)
Run cargo test --package tealeaf-core
Check canonical fixtures still pass
Add new test cases for the change

Modifying the Binary Format

Edit tealeaf-core/src/writer.rs (encoder) and tealeaf-core/src/reader.rs (decoder)
Run canonical round-trip tests: cargo test --package tealeaf-core --test canonical
Regenerate binary fixtures if the format changed

Modifying Derive Macros

Edit files in tealeaf-derive/src/
Run: cargo test --package tealeaf-core --test derive
Check that derive tests cover your change

Modifying FFI

Edit tealeaf-ffi/src/lib.rs
Run: cargo test --package tealeaf-ffi
The C header is auto-regenerated by cbindgen during build

Modifying .NET Bindings

Edit files in bindings/dotnet/
Build: cd bindings/dotnet && dotnet build
Test: dotnet test
The native library must be built first: cargo build --package tealeaf-ffi

Documentation

Building the Documentation Site

# Install mdBook
cargo install mdbook

# Build
cd docs-site
mdbook build

# Serve locally with live reload
mdbook serve --open

Rust API Docs

cargo doc --workspace --no-deps --open

CI/CD

The project uses GitHub Actions for CI:

Workflow	Purpose
`rust-cli.yml`	Build and test Rust on all platforms
`dotnet-package.yml`	Build .NET package with native libraries
`accuracy-benchmark.yml`	Benchmark accuracy tests

All CI runs are triggered on push to main/develop and on pull requests.

Debugging

Rust

# Run with debug output
RUST_LOG=debug cargo run --package tealeaf-core -- info test.tl

# Run with backtrace
RUST_BACKTRACE=1 cargo test --package tealeaf-core

.NET

Use Visual Studio or VS Code with the C# extension for debugging the source generator and managed code.

For native library issues, attach a native debugger to the .NET test process.

Keyboard shortcuts

TeaLeaf Documentation