zircon: Zirco's toolchain installer

Zircon is a toolchain installer for the Zirco programming language. It allows you to easily install and manage different versions of the Zirco compiler, libraries, and tools on your system.

Windows Support

Zircon does NOT support Windows. You must use WSL (Windows Subsystem for Linux) to run Zircon on Windows.

Installation

Prerequisites

Zircon requires the following dependencies to build and run Zirco:

• Rust (install from rustup.rs)
• LLVM 20 (REQUIRED - Zirco only works with LLVM 20.x)
• clang (usually included with LLVM)
• Git
• zstd, libssl, pkg-config (for building on Linux)

Installing LLVM 20 and clang

On macOS (Homebrew):

brew install llvm@20

On macOS (MacPorts):

sudo port install llvm-20

On Ubuntu/Debian:

sudo apt install llvm-20 llvm-20-dev libpolly-20-dev clang-20 build-essential libssl-dev pkg-config libzstd-dev

Note: Zirco requires LLVM 20 specifically. Other versions will not work.

Bootstrap Installation (Linux/macOS/WSL)

Run the bootstrap script to install Zircon (latest main branch):

curl -sSf https://raw.githubusercontent.com/zirco-lang/zircon/main/bootstrap.sh | bash

Or install a specific version:

curl -sSf https://raw.githubusercontent.com/zirco-lang/zircon/main/bootstrap.sh | bash -s v0.1.0

Manual Installation

Or manually:

# Clone and build Zircon
mkdir -p ~/.zircon/sources/zirco-lang
git clone https://github.com/zirco-lang/zircon.git ~/.zircon/sources/zirco-lang/zircon
cd ~/.zircon/sources/zirco-lang/zircon

# Optionally checkout a specific version
# git checkout v0.1.0

cargo build --release

# Create symlinks
ln -sf ~/.zircon/sources/zirco-lang/zircon ~/.zircon/self
mkdir -p ~/.zircon/bin
ln -sf ~/.zircon/sources/zirco-lang/zircon/target/release/zircon ~/.zircon/bin/zircon

# Add to PATH
export PATH="$HOME/.zircon/bin:$PATH"

# Run bootstrap
zircon _ bootstrap

Add to Shell Profile

Important: You must add Zircon's bin directory to your PATH before using the env command.

Linux/macOS (Bash/Zsh)

Add this to your ~/.bashrc, ~/.zshrc, or equivalent:

export PATH="$HOME/.zircon/bin:$PATH"

Then, load the full environment (including ZIRCO_INCLUDE_PATH) by running:

source <(zircon env)

Usage

Build a Zirco Toolchain

Build the latest version from the main branch:

zircon build main

Build a specific version (tag):

zircon build v0.1.0

Build from a specific branch:

zircon build feat-145

Build from a custom repository:

zircon build --zrc-repo https://github.com/SomeFork/zrc main

Switch Between Toolchains

zircon switch v0.1.0

List Installed Toolchains

zircon list

Delete a Toolchain

zircon delete v0.1.0

Prune Unused Toolchains

Remove all toolchains except the currently active one:

zircon prune

Or skip the confirmation prompt:

zircon prune -y

Manage Zircon Itself

Build Zircon from Source

Build Zircon from the latest main branch:

zircon self build

Or build from a specific version:

zircon self build v0.1.0
zircon self build my-feature-branch

Install Pre-built Zircon Release

Install the latest nightly release:

zircon self install

Or install a specific version:

zircon self install v0.1.0

Import Zircon from Archive

If you have a pre-built archive (e.g., from CI artifacts):

zircon self import ./zircon-linux-x64.tar.gz

Environment Configuration

Output shell environment variables:

zircon env

Or load them directly:

source <(zircon env)

This sets:

• PATH to include ~/.zircon/bin
• ZIRCO_INCLUDE_PATH to point to the current toolchain's include directory

Directory Structure

Zircon manages files in ~/.zircon (or %USERPROFILE%\.zircon on Windows):

~/.zircon
├── sources/
│   └── zirco-lang/
│       ├── zrc/          # Zirco compiler source
│       └── zircon/       # Zircon source (for self-updates)
├── toolchains/
│   ├── v0.1.0/
│   │   ├── bin/
│   │   │   └── zrc
│   │   └── include/
│   │       └── *.zh
│   └── current -> v0.1.0  # Symlink to active toolchain
├── self -> sources/zirco-lang/zircon  # Symlink to zircon source
└── bin/
    ├── zrc -> ../toolchains/current/bin/zrc
    └── zircon -> ../sources/zirco-lang/zircon/target/release/zircon

You can override the installation directory with the ZIRCON_PREFIX environment variable:

ZIRCON_PREFIX=/opt/zircon zircon build v0.1.0

Platform Support

Zircon is designed to work on:

• Linux ✓
• macOS ✓
• Windows via WSL ✓

A Note on Stability

So that Zirco can continue to evolve at a rapid pace, there are NO STABILITY GUARENTEES on the current version of Zirco, zrc, and zircon.