Building from Source

Building from Source

This page is for working on ctrlvim itself, or building it without the install script. See Installation if you just want the cvi binary on your system.

Requirements

Rust 1.80 or newer, and a C compiler, since ctrlvim vendors Lua 5.4 and tree sitter. See the Requirements section of Installation for platform specific notes.

Layout

ctrlvim is a Cargo workspace of twelve library crates plus the ctrlvim binary crate that produces cvi. Each crate handles one concern; see Architecture for what each one owns.

Everyday development

cargo run -p ctrlvim           # launch the editor
cargo run -p ctrlvim-core      # headless demo, exercises the engine with no UI
cargo test --workspace         # run every crate's test suite
cargo clippy --workspace --all-targets

cargo run -p ctrlvim is a debug build, which is the right choice while iterating: the dev profile keeps ctrlvim's own crates unoptimized so breakpoints and backtraces still work, but raises the optimization level for dependencies. Ropey and the tree sitter grammars are the two places nearly all the per keystroke cost lives, and an unoptimized build of those is three to four times slower for no debugging benefit, which is why the workspace overrides [profile.dev.package."*"] rather than leaving the whole dev profile unoptimized.

Release builds

make            # cargo build --release --package ctrlvim, produces target/release/cvi
make test        # cargo test --workspace
make lint        # cargo clippy --workspace --all-targets

The Makefile exists mainly to wire up installation on top of the plain cargo build; see Installation for make install and the macOS universal binary targets.

Testing notes

The ctrlvim-tui crate's render tests draw the UI into an in memory Ratatui TestBackend and assert against the resulting text grid, rather than mocking the renderer. That means a rendering regression, not just a logic regression, gets caught by cargo test --workspace.

Rendering the documentation site

The project site's docs page is a rendered copy of this wiki, generated at build time rather than served live, since GitHub Pages runs no server side code and the wiki is a separate repository:

git clone https://github.com/CtrlUserKnown/ctrlvim.wiki.git ~/development/wikis/ctrlvim.wiki
make site-docs WIKI=~/development/wikis/ctrlvim.wiki

make site-docs needs Node installed and writes into site/, which is what the deploy-site GitHub Actions workflow publishes.