briar-systems/mach

A small, explicit systems language for compilers, kernels, runtimes and games:
anywhere performance is a requirement and hidden behavior is a liability.

machlang.org · docs · releases · changelog · discord · ecosystem · awesome-mach

Principles

• No hidden control flow. No exceptions, no destructors, no overloaded operators. Execution goes where the code says and nowhere else.
• No hidden allocation. No garbage collector and no runtime quietly reaching for the heap. Memory moves when you move it.
• Types on the page. Nothing is inferred. Every binding states its type, so a reader never has to reconstruct what the compiler decided.
• One toolchain. A single binary builds, links, tests, formats, vendors dependencies and cross-compiles. The one outside tool it runs is Git, which mach dep uses to fetch and pin dependencies; a build never runs it. Nothing else to install. It cooks and cleans if you ask nicely.

Batteries are not included, there is rarely more than one way to do a thing, and the language will not stop you from doing something dangerous. Safety is a decision the programmer makes, not a restriction imposed on them.

Written in Mach

The compiler, code generators and linker are Mach all the way through, with no external dependencies. The standard library uses platform libraries only where it must, such as libSystem on Darwin and the system DLLs on Windows. The language is proven on the hardest program it will ever build: itself. Each generation compiles the next from the same source, and when two in a row come out the same, the compiler has reproduced itself.

Nothing happens off the page

Not even the runtime. It is an ordinary module in the standard library that a program opts into by importing std.runtime, and main is just the function that exports the symbol it calls. The compiler does not provide a runtime and does not know one exists.

use std.runtime;                  # the runtime is a std module you import
use std.types.error.err;
use std.types.result.res;
use std.types.size.usize;

use A:    std.allocator;
use page: std.allocator.page;

#[symbol("main")]                 # exported by name, for the runtime's _start to call
fun main(argc: i64, argv: **u8) i64 {
    val count: usize = 1024;      # every binding states its type

    var a: A.Allocator;           # the allocator is a value you hold
    page.make(?a);

    # each allocation names its allocator and its type
    val r: res[*u8, A.Error] = A.allocate[u8](?a, count);
    if (sel r.err) {              # failure is a value you check, never thrown
        ret 1;
    }
    val buf: *u8 = r.ok;          # reachable because the error branch returned

    # freed by the same allocator, on the page
    val released: err[A.Error] = A.deallocate[u8](?a, buf, count);
    if (sel released.err) {
        ret 1;
    }

    ret 0;
}

What it's for

Operating systems, firmware and bootloaders. Write the kernel, the bootloader and the build tools in one language. Freestanding targets and inline assembly live in the same source as everything else.

pub fun halt() {
    asm x86_64 {
        cli
        hlt
    }
}

Constant-time cryptography (experimental preview). Mark a value secret and the compiler refuses to let it steer a branch, an index or a timing. Constant-time code, checked instead of hoped for.

#[constant_time("hard")]
fun check(mac: ^u64, want: ^u64) bool {
    if (mac == want) {
        ret true;
    }
    ret false;
}

error[secret.branch]: secret value used as a branch condition
  --> ./src/mac.mach:3:5

GPU compute and shaders. Vertex, fragment and compute stages are Mach functions. A spirv target compiles them straight to a finished SPIR-V module a Vulkan driver loads, with no shading language on the side and no second toolchain. See shaders.

#[gpu.storage(0, 0)]
var particles: Particles;

#[gpu.builtin("global_invocation")]
var global_id: u32x3;

#[gpu.stage("compute")]
#[gpu.workgroup(64, 1, 1)]
fun step() {
    val i: u32 = global_id[0];
    particles.position[i] = particles.position[i] + particles.velocity[i];
}

Targets

A target is a fully spelled tuple of isa, os and abi, plus the extensions every host it runs on is promised to have. Declare them once in mach.toml and one command builds every one of them, from a desktop binary to a bare-metal image to a GPU module.

[target.linux]
arch = "x86_64"
sys  = "linux"
abi = "sysv64"
ext = ["x86-64-v3", "sha"]

[target.board]
arch      = "riscv32"
isa = "rv32imc"
sys       = "freestanding"
abi      = "ilp32"

[target.gpu]
arch = "spirv"
sys  = "vulkan"
abi = "spirv"
env = "vulkan1.3"

mach build . -t '*'

A target's extensions are comptime facts, so one module can carry a hardware path and a portable fallback. The branch a target does not select is dropped before it is type-checked.

$if ($mach.build.ext.sha) {
    use impl: app.sha.hw;
}
$or {
    use impl: app.sha.portable;
}

A target names an arch, an sys, an abi and optionally an object format of, and a spirv target an env. The values each axis accepts are listed in the manifest reference.

x86_64 linux is the primary host. aarch64 linux runs natively in CI, riscv64 linux self-hosts under qemu, darwin self-hosts on both architectures, and windows is a cross-compilation target. mach info targets lists every tuple your binary can build.

Documentation

doc/language/ is the language reference. doc/mach/ is the API reference for the compiler itself, generated by mach doc ..

Install

Linux and macOS:

curl -fsSL https://machlang.org/install.sh | sh

Windows, in PowerShell:

irm https://machlang.org/install.ps1 | iex

Both install the latest release. ~/.local/bin on Linux and macOS and %LOCALAPPDATA%\mach\bin on Windows. Precompiled binaries are also on the releases page.

Getting started

curl -fsSL https://machlang.org/install.sh | sh   # install
mach init hello && cd hello                       # create a project and step into it
mach build .                                      # build it
mach run .                                        # run it

mach init leaves a working program in src/main.mach:

use std.print;
use std.runtime;

#[symbol("main")]
fun main(argc: i64, argv: **u8) i64 {
    print.println("Hello, World!");
    ret 0;
}

[!NOTE] mach run . does not build first. Run mach build . after every change.

From here, read the documentation (a pamphlet, not a bible) or start from mach-sieve.

Contributing

Contributions are welcome. Read the contributing guidelines first.

Credit

Mach draws on more languages than can be counted, but a few shaped the language and its compiler most directly:

• C
• Go
• Zig
• Rust
• V

Mach stands on the shoulders of countless giants who contributed to these languages, directly or by proxy. It is out of respect for their work that Mach will always be fully open source. Thank you all.

Mach is licensed under the MIT License.