Build

Pixi-managed build environment, tasks, CI, and release workflow.

Environment

All tooling flows through pixi:

pixi install          # sync environment from pixi.lock
pixi run <task>       # run a defined task
pixi run cargo build  # ad-hoc command in the env

The workspace supports linux-64, osx-arm64, osx-64, and win-64 so release CI can install the same environment on every runner.

Add dependencies with the CLI (do not hand-edit versions):

pixi add rust=1.96
pixi add nodejs=22       # when VS Code extension work starts
pixi add mdbook          # already in pixi.toml
pixi add --pypi pytest   # example PyPI package

Planned pixi tasks

Add these to [tasks] in pixi.toml as the workspace grows:

Task	Command	Purpose
`build`	`cargo build --release`	Production binary
`build-dev`	`cargo build`	Fast debug builds
`test`	`cargo test --workspace`	All unit + integration tests
`test-parser`	`cargo test -p spice-parser`	Parser fixtures only
`test-lsp`	`cargo test -p spice-lsp`	LSP integration tests
`spice-lsp`	`cargo run -p spice-lsp`	Run language server (stdio)
`fmt`	`cargo fmt --all`	Rust formatting
`clippy`	`cargo clippy --workspace -- -D warnings`	Lint
`mdbook-build`	`mdbook build docs`	Static doc site
`mdbook-serve`	`mdbook serve docs -n 127.0.0.1 -p 3000`	Live doc preview
`ext-install`	`npm install` in `editors/vscode`	Extension deps
`ext-compile`	`npm run compile`	Build extension TS
`ext-package`	`./scripts/package-vscode-extension.sh`	Bundle local binary + `.vsix`
`reference-validate`	`cargo test -p spice-reference --lib`	Validate embedded corpus
`reference-docs`	`spice-reference-catalog write`	Regenerate `docs/reference/` from corpus
`reference-docs-check`	`spice-reference-catalog check`	Fail if catalog docs drift

Example pixi.toml fragment:

[tasks]
build = "cargo build --release"
test = "cargo test --workspace"
spice-lsp = "cargo run -p spice-lsp"
mdbook-serve = "mdbook serve docs -n 127.0.0.1 -p 3000"

Rust workspace layout

Root Cargo.toml:

[workspace]
members = ["crates/spice-parser", "crates/spice-lsp"]
resolver = "2"

Release profile (recommended once benchmarks exist):

[profile.release]
lto = true
codegen-units = 1

Building the Tree-sitter grammar

Grammar crate under tree-sitter-spice/ is built via build.rs in spice-parser:

pixi run cargo build -p spice-parser

After grammar edits, run Tree-sitter’s test harness (once added):

pixi run cargo test -p tree-sitter-spice
# or: tree-sitter test (if CLI added via pixi)

CI (recommended)

GitHub Actions workflow stages:

pixi install
pixi run fmt -- --check
pixi run clippy
pixi run test
pixi run mdbook-build (optional, docs PRs)

Cache ~/.pixi and target/ between runs.

Release builds

Ship a single static binary per platform:

pixi run cargo build --release -p spice-lsp
# artifact: target/release/spice-lsp

Cross-compile with cross or platform matrix in CI. The Release VS Code extension workflow runs on every push to main: it patch-bumps the extension version, builds all platform binaries, packages a bundled .vsix, creates a GitHub Release, and publishes to the VS Code Marketplace (requires VSCE_PAT). See VS Code integration.

Documentation site

Build locally:

pixi run reference-docs   # regenerate dialect catalog from reference/
pixi run mdbook-build
# output: docs/book/

Preview:

pixi run mdbook-serve

After editing JSON under reference/, run pixi run reference-docs so the Dialect reference catalog stays in sync. CI runs pixi run reference-docs-check.

CI and GitHub Pages

The Deploy docs workflow runs on pushes to main when docs/, reference/, crates/spice-reference/, pixi.toml, or pixi.lock change. It:

Runs pixi run mdbook-build
Pushes the output to the gh-pages branch

GITHUB_TOKEN cannot enable GitHub Pages or set the repository Website field on this repo (API returns 403). Run the one-time setup script locally as a repository admin after the first successful deploy:

./scripts/setup-github-pages.sh

That script uses the gh CLI to:

Point Pages at the gh-pages branch (/ root)
Set the repository Website field to the published URL

Published URL: https://amirhosseindavoody.github.io/spice-lsp/

Trigger a manual deploy from the Actions tab via workflow_dispatch if needed.

Troubleshooting

Problem	Fix
`cargo: command not found`	Run `pixi install`; use `pixi run cargo`
Tree-sitter `build.rs` fails	Ensure C compiler available in pixi env (`pixi add gcc` on Linux)
Extension can’t find binary	Set `spiceLsp.serverPath` in VS Code settings to absolute path
LSP hangs on start	Normal for stdio servers waiting for JSON-RPC input

Keyboard shortcuts

spice-lsp