Installation

Prerequisites

Walrus is built in Rust and requires the Rust toolchain to build from source.

Install Rust

If you don’t have Rust installed, download and install it from rust-lang.org:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, restart your terminal and verify the installation:

rustc --version
cargo --version

Walrus requires the latest stable version of Rust. Run rustup update to ensure you’re up to date.

Clone the repository

Clone the Walrus repository from GitHub:

git clone https://github.com/sb2bg/walrus.git
cd walrus

Build Walrus

Build Walrus in release mode for optimal performance:

cargo build --release

This will create the walrus binary at target/release/walrus.

The first build may take a few minutes as Cargo downloads and compiles dependencies.

Verify installation

Test that Walrus is working correctly:

cargo run -- --help

You should see the Walrus command-line help information.

Optional: JIT compilation support

Walrus includes an optional Just-In-Time (JIT) compiler powered by Cranelift that can dramatically speed up hot loops by compiling them to native machine code.

Building with JIT enabled

To build Walrus with JIT support, use the jit feature flag:

cargo build --release --features jit

Performance impact

The JIT compiler can provide significant speedups for computational workloads:

Benchmark	Interpreter	JIT	Speedup
10K iterations × sum(0..1000)	0.68s	0.01s	~68x

JIT compilation is most effective for hot integer range loops. See the JIT documentation for details on what code patterns can be JIT-compiled.

Running Walrus

Once built, you can run Walrus in several ways:

Using cargo run
Direct execution
Add to PATH

During development, you can run Walrus directly with cargo run:

# Execute a file
cargo run -- program.walrus

# Start REPL
cargo run

# Compile mode (explicit VM execution)
cargo run -- -c program.walrus

# Disassemble bytecode
cargo run -- -d program.walrus

Run the compiled binary directly:

# Execute a file
./target/release/walrus program.walrus

# Start REPL
./target/release/walrus

# With JIT enabled (if built with --features jit)
./target/release/walrus program.walrus --jit

# Show JIT statistics
./target/release/walrus program.walrus --jit --jit-stats

For convenience, add the Walrus binary to your PATH:

# Add to ~/.bashrc, ~/.zshrc, or equivalent
export PATH="$PATH:/path/to/walrus/target/release"

Then run Walrus from anywhere:

walrus program.walrus

Command-line options

Walrus supports several command-line flags:

Option	Description
`<file>`	Execute a Walrus source file
`-c, --compile`	Use bytecode compilation mode (VM execution)
`-d, --disassemble`	Disassemble and display bytecode
`--jit`	Enable JIT compilation (requires `jit` feature)
`--jit-stats`	Show JIT profiling statistics
`--no-jit-profile`	Disable JIT profiling (baseline comparison)
`--help`	Display help information

VS Code integration

Walrus includes a Language Server Protocol (LSP) implementation and VS Code extension for enhanced development experience.

Build the language server

cargo build --release --bin walrus-lsp

Install extension dependencies

cd vscode/walrus
npm install

Launch extension development host

Open vscode/walrus in VS Code and press F5 to launch the Extension Development Host.

Open a Walrus file

Open any .walrus file to get:

Parse diagnostics
Hover information for symbols, keywords, and builtins
Scoped completion
Signature help
Document symbols
Go-to-definition
Find references
Rename symbol
Document highlights
Syntax highlighting

The VS Code extension is currently in development and requires running the Extension Development Host. Full marketplace publication is planned for a future release.

Platform-specific builds

The Walrus repository includes optimized build scripts for different platforms:

./scripts/build-linux-optimized.sh

Development tools

Running tests

Walrus includes a comprehensive test suite:

./scripts/run-tests.sh

Benchmarks

Compare Walrus performance against Python:

cd benchmarks
./run_benchmarks.sh

Profiling

Memory profiling
CPU profiling (macOS)

Use dhat for memory profiling:

./scripts/dhat.sh

Use Instruments for CPU profiling:

./scripts/instruments.sh

Troubleshooting

Build fails with linker errors

Ensure you have the necessary system development tools installed:Ubuntu/Debian:

sudo apt-get install build-essential

macOS:

xcode-select --install

Rust version too old

Update Rust to the latest stable version:

rustup update stable

JIT feature not available

Make sure you built with the jit feature:

cargo build --release --features jit

The JIT feature requires Cranelift dependencies which are only compiled when explicitly enabled.

Next steps

Now that you have Walrus installed, proceed to the quickstart guide to write your first program:

Quickstart guide

Write your first Walrus program in minutes

Get Started

Language Guide

Standard Library

Advanced Topics

CLI Reference

Development

Prerequisites

Optional: JIT compilation support

Building with JIT enabled

Performance impact

Running Walrus

Command-line options

VS Code integration

Platform-specific builds

Development tools

Running tests

Benchmarks

Profiling

Troubleshooting

Next steps

Quickstart guide

Build docs developers (and LLMs) love

Get Started

Language Guide

Standard Library

Advanced Topics

CLI Reference

Development

​Prerequisites

​Optional: JIT compilation support

​Building with JIT enabled

​Performance impact

​Running Walrus

​Command-line options

​VS Code integration

​Platform-specific builds

​Development tools

​Running tests

​Benchmarks

​Profiling

​Troubleshooting

​Next steps

Quickstart guide

Build docs developers (and LLMs) love

Prerequisites

Optional: JIT compilation support

Building with JIT enabled

Performance impact

Running Walrus

Command-line options

VS Code integration

Platform-specific builds

Development tools

Running tests

Benchmarks

Profiling

Troubleshooting

Next steps