V / vulcan documentation

Start here

Set up your workspace

Use the repository toolchain to compile a program, run it on Vega, and build a Venus application.

Prerequisites

You need access to a source checkout, Node.js 23 or newer for the TypeScript CLI, and a Rust toolchain with the dependencies required by the compiler and engine. Browser bundles also need the wasm32-unknown-unknown target. Follow your environment's provisioning process if a toolchain is missing.

The commands below run from the checkout root. They use development builds. A repository checkout is currently a prerequisite for these guides; they do not assume a public installer exists.

Build the compiler and engine

cargo build --locked --manifest-path n1/vulcan/lang/rust/Cargo.toml --bin vulc
cargo build --locked --manifest-path n1/vulcan/vega/engine/Cargo.toml

The CLI resolves a runnable compiler and engine for your platform. To select supplied binaries explicitly, set VULC_RS to the compiler path and VULC_VEGA to the engine path. A binary built for another operating system cannot be used just because its filename matches.

Check your first file

Create hello.v with the program from First program, then check and run it:

node n1/vulcan/lang/bin/vulc.ts check hello.v
node n1/vulcan/lang/bin/vulc.ts run hello.v

Check reports diagnostics. Run compiles and executes. A successful check alone does not prove that every construct can be lowered or that the program behaves correctly.

Browser applications

Venus builds a static bundle containing the application image, Vega and Venus WebAssembly runtimes, and the browser host modules. Serve the bundle over HTTP or HTTPS; opening index.html as a local file is not a supported launch path.

When something fails

  • Compiler not found: build or select a runnable compiler with VULC_RS.
  • Engine not found: build or select a runnable engine with VULC_VEGA.
  • Browser stays on its loading screen: check failed asset requests and the browser console; keep the entire bundle together.
  • A check succeeds but build fails: use the build diagnostic as the authoritative result for code generation.