docs.rs failed to build mathic-0.3.0-rc.1
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

🧮 Mathic

A programming language with built-in symbolic algebra, powered by LLVM/MLIR

Features

Symbolic algebra: declare symbolic variables, compose arithmetic expressions, and evaluate them with concrete values at runtime.
Statically typed: type-checked at compile time.

Example

df main() i32 {
    sym x: expr<i32>;
    sym y: expr<i32>;
    sym z: expr<i32>;

    let a: expr<i32> = x + 5;
    let b: expr<i32> = 3 * y;
    let c: expr<i32> = 2 * z + 1;

    return c[x=10] + b[y=10] + a[z=10];
}

Prerequisites

LLVM/MLIR 22 is required. After installing, set:

export LLVM_SYS_221_PREFIX=/path/to/llvm-22
export MLIR_SYS_220_PREFIX=/path/to/llvm-22
export TABLEGEN_220_PREFIX=/path/to/llvm-22

macOS (Homebrew)

brew install llvm@22
export LLVM_SYS_221_PREFIX=$(brew --prefix llvm@22)
export MLIR_SYS_220_PREFIX=$(brew --prefix llvm@22)
export TABLEGEN_220_PREFIX=$(brew --prefix llvm@22)

You may also need:

export LIBRARY_PATH=/opt/homebrew/lib

Building from source

Requires ~6 GB RAM and ~20 GB disk space.

git clone https://github.com/llvm/llvm-project.git
cd llvm-project
git checkout llvmorg-22.1.8
cmake -G Ninja ../llvm \
    -DLLVM_ENABLE_PROJECTS="mlir" \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLLVM_ENABLE_ASSERTIONS=On \
    -DLLVM_BUILD_LLVM_DYLIB=On \
    -DLLVM_LINK_LLVM_DYLIB=On \
    -DMLIR_BUILD_MLIR_C_DYLIB=On \
    -DLLVM_TARGETS_TO_BUILD=host \
    -DCMAKE_INSTALL_PREFIX=/opt/llvm-22 \
    -DLLVM_USE_LINKER=mold   # optional, faster with mold
ninja install

Installation

cargo install mathic

Usage

# Create a new project
euler new <name>
cd <name>
# Compile and run the project in the current directory (requires src/main.mth)
euler run

Options for euler run:

euler run --opt-lvl <O0|O1|O2|O3>   # optimization level (default O2)
euler run --dump-mathir            # dump MATHIR to mathir_dumps/
euler run --dump-mlir              # dump MLIR to mlir_dumps/
euler run --dump-llvmir            # dump LLVM IR

Project Docs

See docs/ for the full project structure and pipeline.

Contributing

See CONTRIBUTING.md.

Status

Early development. Features are added incrementally. The symbolic dialect and its lowering passes are functional but evolving.

Built with ❤️ and 🦀 Rust

mathic 0.3.0-rc.1