Rust, Zig and Go

Runnable examples: Volt calls Rust and Zig, and Rust, Zig and Go calling Volt.

One line imports a crate, as one imports a C header, and its public API is Volt functions and types:

use std::io;
use { "../geom" } as geom;          // the crate's directory (it has a Cargo.toml), from this file

fn main() -> !void {
    val d = geom::dist(geom::Point::new(0.0, 0.0), geom::Point::new(3.0, 4.0));
    std::println("{} {}", d, geom::greet("volt"));          // 5 hello, volt

    var s = geom::shapes::Shape::new("tri");                // a Rust value, owned by s
    s.add_side(3.0);
    std::println("{}", try s.side(0));                      // a Result: Err is an error
}

The crate is plain Rust: pub fn, pub struct, impl blocks, String, Vec, Option, Result. Nothing in it is written for Volt, with no extern "C", #[no_mangle] or #[repr(C)]. voltc runs bolt import, which reads the crate’s public API as rustdoc sees it, builds a small shim crate with cargo, and gives voltc the Volt declarations. Being rustdoc’s view, it has what macros make, the side of each #[cfg] that holds for the build, what pub use re-exports, by its public path (pub use inner::helper as renamed; is renamed; pub use extra::*; brings extra’s items in), and each const’s value as rustc works it out. An item under #[cfg(doc)], which only documentation sees, is kept when the build has one of its name (rustc’s expanded source of the crate says), so a documented stand-in brings in the item it documents. rustdoc writes this as JSON, which stable’s rustdoc does with RUSTC_BOOTSTRAP=1 (bolt sets it); with a toolchain whose rustdoc can’t, bolt reads rustc’s expanded source of the crate instead, which has what macros make and the side of each #[cfg] that holds but not what pub use re-exports (and, when rustc can’t write that either, the source as written, which has none of those), and says so. It caches the result and redoes it when the crate changes. It works the same with voltc run main.volt and in a bolt package.

The import names a directory with a Cargo.toml, or a single .rs file: use { "stats.rs" } as stats; makes that file a crate of its own (the files its mod x; lines name sit next to it), for code that has no Cargo project around it. use rust { "geom" } as geom; says the language outright (use zig and use go too). bolt reads $CARGO for cargo, else cargo on the PATH. Each Volt fn has the declaration it calls in a comment above it (// Rust: pub fn mean(xs: &[f64]) -> f64), which an editor’s hover shows; Zig’s and Go’s do too.

A generic is built per instance: when a check calls geom::largest with i32 and f64, voltc asks bolt for those two, which it builds into the shim as largest::<i32> and largest::<f64>, and checks the program again (only when the instances it needs change). rustc checks each instance’s bounds: types that don’t meet them are an error at the call, with rustc’s reason.

Closures and traits cross both ways. Their methods’ and closures’ types are numbers, bool, char, and text: &str and String in as str, String out as std::string, and a trait method’s &str result as str (lent, as in Rust). A Rust type’s own impl of a method with a body (Square’s describe) runs on its dyn_T and on the type; a Volt type that writes an @optional one has it called by Rust, while a value of the trait union passes with Rust’s body for it (a union can’t say which of its members wrote one). Rust may hand a Volt value it was given to another thread, as C code could: Volt has no Send.

use std::io;
use std::string;
use { "geom" } as geom;

struct tri { b: f64; h: f64; }

// pub trait Shape { fn area(&self) -> f64; fn name(&self) -> String; }
attach geom::Shape -> tri {
    fn area(this) -> f64 { return this.b * this.h / 2.0; }
    fn name(this) -> std::string { return std::string::from("tri"); }
}

fn main() -> void {
    val t: tri = { b: 4.0, h: 3.0 };
    std::println("{}", geom::area_of(&t));              // pub fn area_of(s: &dyn Shape) -> f64
    val u = geom::unit_square();                        // -> Box<dyn Shape>: a geom::dyn_Shape
    std::println("{} {}", u.area(), u.name());
    val add2 = geom::adder(2);                          // -> impl Fn(i32) -> i32
    std::println("{}", geom::apply(|| (x: i32) -> i32 { return x * 10; }, add2.call(1)));
}

Volt’s own types attach a trait that’s generic, has associated types or consts, or has a supertrait of the crate’s only once Volt can give Rust a value of one; until then such a trait is the crate’s types’ alone (its parameters a Rust function takes aren’t Volt’s to pass). A generic trait whose methods take a value of one of its type parameters, one with a generic supertrait or a supertrait from another crate (beyond Send, Sync and Sized), a function with a type the table doesn’t have, and a type generic over a const (Buf<const N: usize>) are left out, listed in a comment of the generated declarations (VOLT_SHOW_IMPORT=1 voltc check main.volt prints them).

A panic through a function stops the program with Rust’s message, as it would in Rust. Every function and method also has a try_ form (geom::try_at(xs, 9), and a closure’s try_call) that returns the panic as rust_error::PANIC with its message instead, the way C++’s try_ forms return exceptions; a Result function’s try_ form gives its own errors or PANIC. A crate built with panic = "abort" aborts instead, as Rust does. cargo builds the shim from the crate’s directory, so its rust-toolchain.toml and dependencies apply.

A .zig file is imported the same way, with zig build-lib building its shim:

use std::io;
use { "fastmath.zig" } as fm;        // the file, from this one; what it imports comes along

fn main() -> !void {
    var p = fm::Point::init(3.0, 4.0);
    std::println("{} {}", p.norm(), fm::add(2, 40));        // 5 42
    std::println("{}", try fm::upper("quiet"));             // QUIET: Zig allocated it, Volt freed it

    var s = try fm::shapes::Shape::init("tri");             // owns memory: delete calls its deinit
    try s.addSide(3.0);

    val xs: i32[3] = { 4, 9, 2 };
    std::println("{}", fm::largest(xs[..]));                // 9: zig built largest(i32, ..)
    var st = try fm::Stack<u8>::init(2);                    // fn Stack(comptime T: type) type
    st.push(1);
}

Generic functions and types get an instance per one a program uses: a call to fm::largest(xs[..]), fm::times<3>(7) or a use of fm::Stack<u8> has bolt add that instance and zig build it, as with Rust’s generics above. One zig rejects is an error at the call, with zig’s reason (fm::biggerOf("a", "b"): operator > not allowed for type ‘[]const u8’). bolt reads $ZIG for the compiler, else zig on the PATH. An extern fn with a calling convention other than C’s or a type C doesn’t have (a slice, an error union), a pointer to a pointer, a slice of an opaque type’s pointers, and a function with a type the table doesn’t have are left out, listed with the reason in a comment of the generated declarations (a variadic extern fn too). c_long and c_ulong are 64 bits, or 32 on Windows, as C’s are; bolt builds the shim for the system it runs on. A file with export fns is best imported under one name: two use lines naming it, both used, are two libraries that each define its C symbols, and the link fails.

A .go file imports its package (the files of its directory), and a directory with a go.mod imports that module’s package. Nothing in the Go code is written for Volt: no //export, no cgo. bolt asks Go’s own type checker what the package exports and writes a cgo shim for it:

use std::io;
use { "geom.go" } as geom;       // package geom, from this file's directory
use { "../shapes" } as sh;       // a module's directory: its root package

fn main() -> !void {
    var b: geom::Point = { X: 3.0, Y: 4.0 };    // a plain struct, by value
    b.Scale(2.0);                                // func (p *Point) Scale(k float64)
    std::println("{} {}", b.Norm(), geom::Upper("quiet"));      // 10 QUIET
    std::println("{}", try geom::Parse("42"));                  // (int, error)

    val sides: f64[3] = { 3.0, 4.0, 5.0 };
    var s = geom::NewShape("tri", sides[..]);   // *Shape: a handle; Go keeps it while Volt holds it
    s.Add(1.0);
    std::println("{} {}", s.Perimeter(), sh::Area(2.0, 3.0));
}

The newer forms in use (kinds.go is ordinary Go, as in the table):

use std::io;
use { "kinds.go" } as k;

struct tri { b: f64; h: f64; }

// type Figure interface { Area() float64; Name() string }
attach k::Figure -> tri {
    fn Area(this) -> f64 { return this.b * this.h / 2.0; }
    fn Name(this) -> std::string { return std::string::from("tri"); }
}

fn main() -> k::go_error!void {
    val xs: isize[3] = { 3, 9, 4 };
    std::println("{}", k::Max(xs[..]));                         // func Max[T cmp.Ordered](xs ...T) T
    std::println("{}", k::Apply(|| (x: isize) -> isize { return x * 3; }, 5));   // f func(int) int
    val (lo, hi) = k::MinMax(xs[..]);                           // (lo, hi int)
    val words: str[3] = { "a", "b", "a" };
    var counts = k::Count(words[..]);                           // map[string]int
    std::println("{} {} {}", lo, hi, counts.get("a") ?? 0);
    val r = k::Range(3);                                        // <-chan int, filled by a goroutine
    while (true) {
        val x = r.recv() ?? break;
        std::println("{}", x);
    }
    std::println("{}", k::Tell({ b: 4.0, h: 3.0 } as tri));     // func Tell(f Figure) string
    // func Spread(f func(int) (int, string)) string: a closure giving several results
    std::println("{}", k::Spread(|| (n: isize) -> (isize, std::string) { return (n, std::string::from("ab")); }));
    val chunks = k::Chunk(xs[..], 2);                           // [][]T: a slice<std::vec<isize>>
    val bad = k::try_At(xs[..], 5);                             // a panic, as go_error::PANIC
}

A main package works too (its main isn’t run). The program links every use go import into one library, so it has one Go runtime, started when the program starts. A panic stops the program with Go’s message, as it does in Go; each function’s try_ form (and a Go func value’s try_call) returns it as go_error::PANIC instead. The shim recovers it, so it never unwinds through C, and the same goes for a panic while a Volt closure’s slice result is handed to Go (it stops the program with Go’s message). Errors cross as their text: an error a Volt function gives Go is a new Go error with that text. Calls are safe from any Volt thread, and Go may call a Volt closure from any goroutine, as C code could. bolt reads $GO for the go command, else go on the PATH; cgo needs a C compiler.

What Go’s own rules keep out, listed in a comment of the generated declarations (VOLT_SHOW_IMPORT=1 voltc check main.volt prints them): an unexported type, or an internal package’s, which no other package can name; an interface with unexported methods, which only its own package’s types can have (Go’s values of it are still dyn_I handles); a constraint, which only a type parameter can have; and an untyped constant no Go number holds (1 << 100).

Libraries with a C API of their own, Go modules built as one (//export), and Rust crates or Zig files that export one (#[no_mangle] pub extern "C" fn, export fn), can be named under [foreign] in bolt.toml:

[foreign]
geom = { rust = "../geom" }        # a Cargo crate's directory
fastmath = { zig = "fastmath.zig" }
gomath = { go = "../gomath" }      # a Go module's directory

bolt builds each one into a static library in target/<profile>/foreign/: a crate with cargo rustc --crate-type staticlib (so any library crate works, with --release in an optimized profile), a Zig file with zig build-lib (ReleaseSafe or Debug), a Go module with go build -buildmode=c-archive. It also writes NAME.h (in foreign/include/), the library’s C API: read from the source for Rust and Zig, and the header cgo writes for Go (below). It links them, and the system libraries rustc says a Rust library needs, into the package’s programs. The code imports the header like any C header, by its name (foreign/include/ is on the include path):

#[repr(C)]
pub struct Point {
    pub x: f64,
    pub y: f64,
}

#[no_mangle]
pub extern "C" fn geom_dist(a: Point, b: Point) -> f64 {
    ((a.x - b.x).powi(2) + (a.y - b.y).powi(2)).sqrt()
}

pub const Range = extern struct { lo: i32, hi: i32 };

export fn fm_clamp(x: i32, r: Range) i32 {
    return @max(r.lo, @min(r.hi, x));
}

use std::io;
use { "geom.h" } as geom;
use { "fastmath.h" } as fm;

fn main() -> void {
    val a: geom::Point = { x: 0.0, y: 0.0 };
    val b: geom::Point = { x: 3.0, y: 4.0 };
    val r: fm::Range = { lo: 0, hi: 10 };
    std::println("{}", geom::geom_dist(a, b)); // 5
    std::println("{}", fm::fm_clamp(42, r));   // 10
}

What goes into the header:

An enum’s values become constants named Enum_Variant (Quadrant_First). A function whose types aren’t in that table isn’t declared, and the header says so in a comment. bolt reads $CARGO, $ZIG and $GO for the tools, else cargo, zig and go on the PATH.

A Go library is a main package whose API is its //export funcs; cgo writes their C declarations, with GoString (a pointer and a length), GoInt and the other Go types, into the header:

package main

import "C"

import "strings"

//export gm_add
func gm_add(a, b C.int) C.int { return a + b }

//export gm_upper
func gm_upper(s *C.char) *C.char { return C.CString(strings.ToUpper(C.GoString(s))) }

func main() {}

use std::io;
use { "gomath.h" } as go;

extern "C" fn free(p: void*) -> void;

fn main() -> void {
    std::println("{}", go::gm_add(2, 40));                         // 42
    val up = go::gm_upper(@cast<cstr>("volt\0".ptr)) ?? return;   // C.CString: the C heap's
    free(@cast<void*>(up));
}

The program links the Go runtime with it, which starts its threads when the program does. The other way round, voltc bindings --lang go writes a cgo package for a Volt library, see They call Volt.

A Cargo project builds a Volt package from its build script with volt-build (in interop/rust/volt-build in the repository):

[build-dependencies]
volt-build = { path = "../volt/interop/rust/volt-build" }

fn main() {
    volt_build::Package::new("mathlib", "volt/mathlib").build();
}

include!(concat!(env!("OUT_DIR"), "/mathlib.rs")); // pub mod mathlib, the Rust bindings

fn main() {
    println!("{}", mathlib::ml_add(2, 3));
}

build runs voltc lib NAME --static and voltc bindings NAME --lang rust into OUT_DIR and tells Cargo what to link; a failure stops the build script with voltc’s message (try_build() returns it as an Err instead). A Zig project does the same with interop/zig/volt.zig:

const volt = @import("volt.zig");
// ...after making exe:
volt.addPackage(b, exe, "mathlib", "volt/mathlib");

const mathlib = @import("mathlib");

Both take voltc from $VOLTC, else the PATH, and std from $VOLT_STD, else voltc’s own (volt_build::Package::new(...).std(dir) names it in Rust). Python and Node projects get the same from pip and npm: see pip install and npm install. The bindings’ types are in They call Volt: Result for errors, String and &str for text, a type that frees itself when dropped for an export struct (with its methods), and the same in Zig with error unions, slices and deinit(). Rust takes every shape, as C and C++ do: a generic’s instances (biggest_i32), owned values as parameters, a Volt trait as a Rust trait to implement (or one Volt made, as a Box<dyn T>), any closure (impl FnMut) taking and giving text and handles, and closures given back as Box<dyn FnMut>. So does Zig: a Volt trait takes any Zig value with its methods (lent as a pointer or given), callbacks are a context and a function, and closures come back as a struct with call and deinit().