Installation Guide

This guide covers installation of IlluLang on Windows, Linux, and macOS.

Table of Contents

• Windows Installer (Easiest)
• Prerequisites
• Windows
• Linux
• macOS
• Installation Methods
• Quick Install (Using Scripts)
• Manual Install (Using CMake)
• VS Code Extension
• Verification
• Optional Configuration
• Troubleshooting

Windows Installer (Easiest)

The simplest way to install IlluLang on Windows is via the NSIS installer published with each GitHub Release.

Download

1. Go to the Releases page.
2. Download illulang-X.Y.Z-setup.exe (where X.Y.Z is the release version).

What the Installer Does

• Copies illulang.exe, the VS Code extension (.vsix), example files, and documentation to C:\Program Files\IlluLang (configurable).
• Adds C:\Program Files\IlluLang\bin to the system PATH so you can run illulang from any terminal.
• Registers .ilu files for double-click execution.
• Creates Start Menu shortcuts.
• Provides a standard Add/Remove Programs uninstaller.

Usage After Installing

Open any terminal (PowerShell, CMD, Windows Terminal) and run:

illulang                          ## Start the REPL
illulang program.ilu              ## Execute a file
illulang --lsp                    ## Start the language server

To install the bundled VS Code extension:

code --install-extension "C:\Program Files\IlluLang\illulang.vsix"

Uninstalling

Use Settings → Apps → Installed Apps → IlluLang → Uninstall, or run the uninstaller from the Start Menu.

Prerequisites

Windows

Required: - CMake (3.10 or higher): Download from cmake.org - C Compiler (one of): - MSYS2 UCRT64 (recommended): Download from msys2.org -- install mingw-w64-ucrt-x86_64-gcc and mingw-w64-ucrt-x86_64-cmake via pacman - MinGW-w64/GCC: Download from winlibs.com or use Chocolatey: choco install mingw - MSVC: Install Visual Studio 2019+ with "Desktop development with C++" workload

MSYS2 setup (recommended for Windows):

## After installing MSYS2, open "MSYS2 UCRT64" terminal:
pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-make

## Add to your system PATH: C:\msys64\ucrt64\bin

Optional: - Ninja (faster builds): choco install ninja or download from ninja-build.org

Linux

Required: - CMake (3.10+) - GCC or Clang - Make or Ninja

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y cmake gcc make

Fedora/RHEL:

sudo dnf install -y cmake gcc make

Arch Linux:

sudo pacman -S cmake gcc make

Optional (for memory testing):

sudo apt-get install -y valgrind  # or equivalent for your distro

macOS

Required: - CMake (3.10+) - Xcode Command Line Tools (provides clang)

Installation:

# Install Xcode Command Line Tools
xcode-select --install

# Install CMake via Homebrew
brew install cmake

Installation Methods

Quick Install (Using Scripts)

IlluLang provides convenience scripts for each platform.

Windows

Clean + build (recommended):

scripts\bat\illulang.bat -c -b

Incremental build (faster, reuses existing build):

scripts\bat\illulang.bat -b

Build core + VS Code extension (.vsix):

scripts\bat\illulang.bat --build-all

Build only VS Code extension (.vsix):

scripts\bat\illulang.bat -l

Build location: build/illulang

Linux / macOS

Clean + build (recommended):

chmod +x scripts/sh/illulang.sh
./scripts/sh/illulang.sh -c -b

Incremental build:

chmod +x scripts/sh/illulang.sh
./scripts/sh/illulang.sh -b

Build core + VS Code extension (.vsix):

./scripts/sh/illulang.sh --build-all

Build only VS Code extension (.vsix):

./scripts/sh/illulang.sh -l

Build location: build/illulang

Manual Install (Using CMake)

If you prefer explicit control or the scripts don't work for your environment:

Step 1: Configure

All platforms:

cmake -S . -B build/cmake

With specific generator (optional):

# Unix Makefiles (default on Linux/macOS)
cmake -S . -B build/cmake -G "Unix Makefiles"

# Ninja (faster, if installed)
cmake -S . -B build/cmake -G "Ninja"

# MinGW Makefiles (Windows with GCC)
cmake -S . -B build/cmake -G "MinGW Makefiles"

# Visual Studio (Windows with MSVC)
cmake -S . -B build/cmake -G "Visual Studio 17 2022"

Step 2: Build

All platforms:

cmake --build build/cmake --config Release

With parallelism:

cmake --build build/cmake --config Release -j4

Step 3: Locate the Executable

Linux/macOS:

build/illulang

Windows:

build\illulang.exe

WebAssembly Playground

To build the WebAssembly playground module with Emscripten, run (from repository root):

cmake -S . -B build-wasm -DBUILD_WASM=ON -DCMAKE_TOOLCHAIN_FILE="C:/path/to/emsdk/upstream/emscripten/cmake/Modules/Platform/Emscripten.cmake" -DCMAKE_BUILD_TYPE=Release
cmake --build build-wasm --target illulang_wasm --config Release

Or if you're already configured with emcmake:

emcmake cmake -S . -B build-wasm -DBUILD_WASM=ON -DCMAKE_BUILD_TYPE=Release
cmake --build build-wasm --target illulang_wasm --config Release

Output artifacts are written to docs/wasm/:

• docs/wasm/illulang.js
• docs/wasm/illulang.wasm

VS Code Extension

IlluLang ships a VS Code extension providing syntax highlighting, real-time diagnostics, hover documentation, auto-completion, and code snippets for .ilu files.

Prerequisites

• Node.js (v18 or later): nodejs.org
• The illulang binary must be installed and on your PATH (or configure illulang.serverPath in VS Code settings).

Option A -- Install from a GitHub Release (recommended)

Download illulang-X.Y.Z.vsix from the Releases page and install it:

code --install-extension illulang-X.Y.Z.vsix

Option B -- Build and package from source

This produces a self-contained .vsix file you can install on any machine.

Fast path (recommended)

From the repository root:

Windows:

scripts\bat\illulang.bat -l

Linux/macOS:

./scripts/sh/illulang.sh -l

To build both the language binary and extension in one command:

Windows:

scripts\bat\illulang.bat --build-all

Linux/macOS:

./scripts/sh/illulang.sh --build-all

Prerequisites

Note: The illulang binary must be on your PATH (or you can set illulang.serverPath in VS Code settings after installation).

Step 1 -- Enter the extension directory

cd plugin/vscode

Step 2 -- Install dependencies

npm install

This downloads vscode-languageclient, typescript, @vscode/vsce, and type definitions into node_modules/.

Step 3 -- Compile the TypeScript source

npm run compile

This runs tsc -p ./ and writes JavaScript output to out/.

Step 4 -- Package into a .vsix archive

npm run package

Which internally runs:

npx vsce package --no-dependencies --allow-missing-repository

After this step you will have a file named illulang-X.Y.Z.vsix inside plugin/vscode/.

Step 5 -- Install in VS Code

code --install-extension illulang-X.Y.Z.vsix

Or via the VS Code UI: Extensions → … menu → Install from VSIX… and select the file.

Full one-liner (all platforms)

cd plugin/vscode && npm install && npm run compile && npm run package && code --install-extension illulang-*.vsix

Windows (PowerShell):

cd plugin\vscode; npm install; npm run compile; npm run package; code --install-extension (Get-Item illulang-*.vsix).Name

Using the Build Scripts (Alternative)

Convenience scripts are provided to automate the build process:

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -File plugin/vscode/scripts/build-vsix.ps1

Linux/macOS:

chmod +x plugin/vscode/scripts/build-vsix.sh
./plugin/vscode/scripts/build-vsix.sh

These scripts automatically install dependencies and package the extension into a .vsix file.

Troubleshooting the VSIX build

Configuration

Features

Verification

Run the Test Suite

Windows:

build\tests\run_tests.exe

Linux/macOS:

./build/tests/run_tests

Expected output:

=== IlluLang 1.2.0 Test Suite ===
...
--- Test Summary ---
Passed: 800+, Failed: 0

Start the REPL

Windows:

build\illulang.exe

Linux/macOS:

./build/illulang

Expected output:

IlluLang <VERSION_FROM_VERSION_FILE>
Type 'exit' or press Ctrl+D to quit.

>

Run an Example

Windows:

build\illulang.exe examples\hello_world.ilu

Linux/macOS:

./build/illulang examples/hello_world.ilu

Optional Configuration

Add to PATH

To run illulang from anywhere:

Windows (PowerShell):

# Temporary (current session only)
$env:PATH += ";C:\path\to\illulang\build"

# Permanent (add to User Environment Variables via System Settings)
[System.Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\path\to\illulang\build", [System.EnvironmentVariableTarget]::User)

Linux/macOS (bash/zsh):

# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:/path/to/illulang/build"

# Or create a symlink
sudo ln -s /path/to/illulang/build/illulang /usr/local/bin/illulang

Environment Variables

IlluLang supports several optional environment variables:

ILLULANG_LOG -- Control logging verbosity:

export ILLULANG_LOG=debug   # Verbose output (error, warn, info, debug)
export ILLULANG_LOG=info    # Standard output (error, warn, info)
export ILLULANG_LOG=warn    # Warnings and errors only
export ILLULANG_LOG=error   # Errors only (default)

ILLULANG_ARENA -- Enable arena allocator for values:

export ILLULANG_ARENA=1     # Use arena allocator (faster, experimental)

ILLULANG_PROFILE -- Enable profiling counters:

export ILLULANG_PROFILE=1   # Track parse/eval/VM/allocation stats

Troubleshooting

Windows: "cmake: command not found"

Solution: Add CMake to your PATH: 1. Find CMake installation (usually C:\Program Files\CMake\bin) 2. Add to System Environment Variables via Settings → System → About → Advanced system settings → Environment Variables 3. Restart terminal

Windows: "gcc: command not found" or "cl: command not found"

Solution: Install a compiler (see Prerequisites): - MinGW: Download from winlibs.com and add bin/ to PATH - MSVC: Run build scripts from "Developer Command Prompt for VS 2019/2022"

Linux/macOS: "Permission denied" when running scripts

Solution: Make scripts executable:

chmod +x scripts/sh/illulang.sh

Linux: AddressSanitizer build fails

Solution: Install ASan development libraries:

# Ubuntu/Debian
sudo apt-get install -y libasan6 gcc

# Fedora
sudo dnf install -y libasan

Build errors: "Ninja not found" or generator issues

Solution 1: Install Ninja:

# Linux
sudo apt-get install ninja-build

# macOS
brew install ninja

# Windows
choco install ninja

Solution 2: Use default generator:

# Remove existing build and reconfigure without specifying generator
rm -rf build/cmake
cmake -S . -B build/cmake
cmake --build build/cmake

Tests fail on Windows with Unicode errors

Solution: Ensure terminal supports UTF-8:

# PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
chcp 65001

macOS: "xcrun: error: invalid active developer path"

Solution: Install Xcode Command Line Tools:

xcode-select --install

Advanced Build Options

Debug Build (with symbols)

cmake -S . -B build/debug -DCMAKE_BUILD_TYPE=Debug
cmake --build build/debug

AddressSanitizer Build (Linux only)

For memory leak detection:

Using script:

chmod +x scripts/sh/illulang.sh
./scripts/sh/illulang.sh -a
./build_asan/run_tests

Manual:

mkdir -p build_asan
cd build_asan
cmake -DCMAKE_BUILD_TYPE=Debug \
      -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
      -DCMAKE_RUNTIME_OUTPUT_DIRECTORY="$(cd .. && pwd)/build_asan" \
      -DCMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG="$(cd .. && pwd)/build_asan" \
      ..
cmake --build .
cd ..
./build_asan/run_tests

Valgrind Memory Testing (Linux)

chmod +x scripts/sh/illulang.sh
./scripts/sh/illulang.sh -v

CI/CD Integration

The project uses GitHub Actions for automated testing and releases. Workflow sources in the repository:

• .github/workflows/ci.yml
• .github/workflows/release.yml

What the CI does:

• Linux/macOS/Windows: builds on all platforms, runs the full test suite, validates the diagnostics contract
• Release: creates tagged releases with binaries, installer, and VS Code extension

To reproduce CI builds locally:

# Linux/macOS
./scripts/sh/illulang.sh -c -b
./build/run_tests

# Windows
scripts\bat\illulang.bat -c -b
build\run_tests.exe

The CI workflow validates all changes on every push and pull request to ensure cross-platform compatibility.

Next Steps

• Learn the language: SYNTAX
• Explore intent-oriented programming: INTENT_ORIENTED
• Try examples: Run scripts in the examples/ directory
• Contribute: See CONTRIBUTING.md

Version: See VERSION
Last Updated: March 20, 2026