Skip to main content

Quick Start

Get up and running with Mux in just a few minutes.

Prerequisites​

Before you begin, make sure you have the following installed:

  • For prebuilt install: any recent clang or gcc (Mux calls it to link your compiled program; the version does not need to match). No Rust and no LLVM development libraries needed.
  • For source install: Rust is required; use the bootstrap script to install LLVM 22 and clang 22

See Setup for the install command on your platform. The installer also runs mux doctor at the end and reports anything missing.

Installation​

Mux provides multiple installation methods to suit different needs.

Install with the official script:

curl -fsSL https://raw.githubusercontent.com/muxlang/mux-compiler/main/scripts/install.sh | sh

Windows PowerShell:

iwr -useb https://raw.githubusercontent.com/muxlang/mux-compiler/main/scripts/install.ps1 | iex

Custom Installation Directory (Optional)​

By default, the installer places the binary in ~/.local/bin and libraries in ~/.local/lib. You can customize this with environment variables if needed:

# Custom installation directory (bash)
MUX_INSTALL_DIR=/usr/local/bin MUX_LIB_DIR=/usr/local/lib sh install.sh
# Custom installation directory (PowerShell)
$env:MUX_INSTALL_DIR = "C:\Program Files\mux"
$env:MUX_LIB_DIR = "C:\Program Files\mux\lib"
iwr -useb https://raw.githubusercontent.com/muxlang/mux-compiler/main/scripts/install.ps1 | iex

Verifying Your Installation​

After installation, verify everything is working:

mux version

This prints the compiler version and the runtime it resolved, including the locked commit. Quote that line in bug reports.

Use the built-in doctor command to check your setup:

mux doctor       # Validate runtime dependencies
mux doctor --dev  # Validate LLVM 22 and clang for development
  • mux doctor - For end users to verify runtime dependencies
  • mux doctor --dev - For contributors to verify LLVM 22 and clang

Option 2: crates.io (frozen)​

mux-lang was published to crates.io through 0.6.0, but that channel is no longer updated. cargo install mux-lang requires a Rust toolchain and the exact LLVM 22 development libraries, then compiles the LLVM bindings from scratch, which makes it by far the slowest way to get a working compiler.

Use the prebuilt installer above instead. Build from source (below) if you want to work on the compiler itself.

Option 3: Build from Source (Contributors)​

If you prefer to build from source, maybe to even help contribute to the project:

  1. Clone the repository:

    git clone https://github.com/muxlang/mux-compiler
cd mux-compiler

    You only need this one repository. The runtime is a git dependency, so cargo fetches it for you.

  2. Run the bootstrap script to install LLVM 22 automatically:

    ./scripts/bootstrap-dev.sh

    This script detects your OS and installs LLVM 22, clang, and lld. It supports:

    • Arch Linux (via yay)
    • Debian/Ubuntu (via apt)
    • macOS (via Homebrew)

  3. Build using the dev wrapper:

    ./scripts/dev-cargo.sh build -p mux-runtime -p mux-lang

    The dev-cargo.sh script wraps cargo calls with the correct LLVM environment variables set automatically.

    Build both packages. Compiled Mux programs link libmux_runtime.a, and cargo emits a dependency's rlib but never its staticlib, so building only the compiler leaves every program failing to link.

The binary is called mux. dev-cargo.sh builds into target/dev-cargo/, so a default build lands at target/dev-cargo/debug/mux; add --release for target/dev-cargo/release/mux.

Option 4: Install via Bootstrap Scripts​

For contributors who want the easiest setup:

./scripts/bootstrap-dev.sh
./scripts/dev-cargo.sh build -p mux-runtime
./scripts/dev-cargo.sh install --path mux-compiler
mkdir -p ~/.cargo/lib
cp target/dev-cargo/debug/libmux_runtime.a ~/.cargo/lib/

This installs the mux binary to your cargo bin directory. cargo install copies only the binary, so the runtime archive has to be placed where the compiler looks for it: ~/.cargo/lib/, next to ~/.cargo/bin/mux. Setting MUX_RUNTIME_LIB to the archive works too.

Your First Mux Program​

1. Create a File​

Create a new file called hello.mux:

hello.mux
Loading...
Ctrl + Enter to run

2. Run the Program​

mux run hello.mux

You should see:

Hello, Mux!

Next Steps​

Try More Examples​

Create a file called numbers.mux:

numbers.mux
Loading...
Ctrl + Enter to run

Run it:

mux run numbers.mux

Explore the Language​

Commands and Options​

Usage: mux [OPTIONS] <COMMAND>

Commands:
  build    Compile a Mux file without running it
  run      Compile and run a Mux file
  format   Format a Mux file
  doctor   Check system dependencies for the Mux compiler
  version  Print the Mux version
  help     Print this message or the help of the given subcommand(s)

Options:
  -o, --output <OUTPUT>  Name of the output executable
  -i, --intermediate     Emit intermediate LLVM IR (.ll)
  -h, --help             Print help

Getting Help​

Current Limitations​

Mux is actively being developed. Here are some things to be aware of:

  • No LSP (Language Server Protocol) - Editor support is limited to basic syntax highlighting
  • No Code Formatter - There is currently no automated code formatting tool
  • Standard Library Available - Core stdlib modules are published; APIs may evolve as new modules are added
  • Breaking Changes Expected - The language is evolving, so expect syntax and semantic changes

These limitations are current; check the compiler issue tracker for implementation status and contribution opportunities.

What's Next?​

Now that you have Mux installed, explore the documentation: