metaltile

Rust DSL for writing Apple Metal GPU kernels — write once, run fast on Apple Silicon. This is the user-facing facade crate: add metaltile to your Cargo.toml, import metaltile::prelude::*, annotate functions with #[kernel], and dispatch them on the GPU with a few lines of Rust.

The crate re-exports the compiler, runtime, and macro crates under one namespace so you never need to depend on metaltile-core, metaltile-codegen, or the others directly unless you are writing tooling or compiler extensions.

Position in the pipeline

        ┌──────────────────────────────┐
        │  metaltile (this crate)       │
        │  user-facing facade           │
        │                              │
        │  use metaltile::prelude::*;   │
        │  #[kernel]                    │
        │  kernel::launch(&ctx)         │
        └──────────┬───────────────────┘
                   │ re-exports
    ┌──────────────┼──────────────┬──────────────┐
    ▼              ▼              ▼              ▼
metaltile-core  metaltile-macros  metaltile-codegen  metaltile-runtime
   (IR types)    (#[kernel])      (MSL lowering)     (GPU dispatch)

metaltile is the only crate end users depend on. It re-exports the DSL macros, placeholder types, IR/codegen modules, and runtime entry points under flat paths like metaltile::kernel, metaltile::core, metaltile::codegen, and metaltile::Context.

Quick start

use metaltile::prelude::*;

#[kernel]
fn vector_add(a: Tensor<f32>, b: Tensor<f32>, c: Tensor<f32>) {
    let idx = program_id::<0>();
    store(c[idx], load(a[idx]) + load(b[idx]));
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let ctx = Context::new()?;
    let n = 256usize;
    let a: Vec<u8> = (0..n).flat_map(|i| (i as f32).to_le_bytes()).collect();
    let b: Vec<u8> = (0..n).flat_map(|_| (1.0f32).to_le_bytes()).collect();
    let c = vec![0u8; n * 4];

    let result = vector_add::launch(&ctx)
        .input("a", a)
        .input("b", b)
        .input("c", c)
        .dispatch()?;

    let out: Vec<f32> = result.outputs["c"]
        .chunks_exact(4)
        .map(|b| f32::from_le_bytes(b.try_into().unwrap()))
        .collect();
    println!("out[0] = {}", out[0]); // 1.0
    Ok(())
}

To inspect the generated MSL directly without dispatching:

use metaltile::codegen::msl::MslGenerator;

let msl = MslGenerator::default().generate(&vector_add::kernel_ir())?;
println!("{msl}");

Crate contents

API reference

Prelude

use metaltile::prelude::*; brings everything public from all sub-crates into scope:

Macros (from metaltile-macros):

IR types (from metaltile-core):

Runtime (from metaltile-runtime):

Codegen (from metaltile-codegen):

DSL function stubs (panic if called outside #[kernel]):

Unary math (recognized by the body parser): exp, log, sqrt, rsqrt, abs, silu, gelu, relu, tanh, sigmoid, sin, cos, ceil, floor, recip

Re-exports

Directly accessible from metaltile:::

Dependencies

Internal

External

None — all external dependencies come transitively through the internal crates.

MSRV / platform

The facade crate itself has no platform gating. The runtime (Context::new()) requires macOS + Metal; codegen and IR introspection work on any host.

Rust: nightly (workspace-wide, edition 2024).

Extending

• New re-export: src/lib.rs — add pub use metaltile_<crate>::<Item>; with a doc comment.
• New prelude item: src/prelude.rs — add the type stub, function stub, or re-export, with a doc comment.
• New DSL intrinsic: src/prelude.rs — add a pub fn stub that panics, then add recognition in metaltile-macros/src/body_parser.rs.
• Tests to update: Doc-tests in src/lib.rs.

Related documentation

• Root README — project overview and architecture
• CONTRIBUTING — dev setup, PR process, CI
• metaltile-core README — the IR types prelude re-exports
• metaltile-macros README — how #[kernel] transforms your function
• metaltile-codegen README — the MSL generator behind metaltile::codegen
• metaltile-runtime README — the Context and dispatch lifecycle
• Crate docs on docs.rs

License

Licensed under the Apache License, Version 2.0.