Modules, Testing & FFI
Splitting a program across files, writing tests, and calling C through extern.
Modules & Imports
import("name") returns a module value, a compile-time record of the symbols another
file exports. Bind it through const either whole or destructured.
// Whole-module binding.
const std = import("std");
fn show() {
std.fmt.println("Hello!");
}
// Destructured binding, pulls specific names into the current scope.
// Re-exports under `std` can be reached via chained access on the
// import expression: pick the names you need without binding the
// whole module.
const { Vec } = import("std").collections;
const { Option } = import("std").option;
const { assert } = import("test");
The path is resolved relative to the file (./collections.jam or std/string.jam) or
to a built-in name (std, test). Modules can re-export by binding to a local pub
name.
Testing
tfn declares a test. jam test <file-or-dir> compiles every tfn,
synthesizes a main that runs them, and reports each by name.
import("test") exports assert(actual, expected).
const { assert } = import("test");
fn double(x: u64) u64 { return x * 2; }
tfn doubling() {
assert(double(21) as i32, 42);
}
extern / FFI
extern declarations link to symbols defined in C (or any system providing the C ABI).
The compiler does not generate a body; it just emits a call. Most stdlib allocators use
this.
pub extern fn malloc(size: u64) *mut[] u8;
pub extern fn free(ptr: *mut[] u8);
pub extern fn realloc(ptr: *mut[] u8, size: u64) *mut[] u8;
fn allocOne() *mut[] u32 {
var raw: *mut[] u8 = malloc(@sizeOf(u32));
return raw as *mut[] u32;
}
Param types must match the C ABI. Slice arguments are passed as a {ptr, len} pair, and
struct arguments larger than two words use sret-style return ABI, these match the
platform’s C compiler.
Calling raw function addresses: @callC
When the callee is only known as an address (dlsym results,
objc_msgSend-style dispatchers), @callC(R, addr, args...) performs an
indirect call with the C calling convention. R is the return type (void
is accepted here), addr is a u64, and each argument’s static type
becomes the corresponding parameter type of the synthesized signature, with no
coercion happens at the boundary, so spell scalar types explicitly
(0 as i64, x as u64).
pub extern fn fabs(x: f64) f64;
fn callThroughAddress() f64 {
const addr: u64 = fabs as u64;
return @callC(f64, addr, -2.5); // fn(f64) f64, by address
}
By-value aggregates are allowed when they are homogeneous float aggregates
of at most 4 same-width floats ({f64,f64,f64,f64}, FP registers) or at
most two full 64-bit words ({u64,u64}, GP registers); other shapes are
rejected at compile time.
Variadic cfn: forwarding argument packs
A cfn method may declare one trailing argument pack, args: .... The
method is instantiated per call-site shape (each pack argument’s static
type becomes a real parameter), and the pack’s only use is forwarding:
args... at the end of a call-argument list, most usefully into @callC
or an extern C-variadic like printf:
const Caller = struct {
addr: u64,
cfn callThrough(self: Caller, R: type, args: ...) R {
return @callC(R, self.addr, args...);
}
};
const n: i32 = c.callThrough(i32, -7 as i32); // fn(i32) i32
const d: f64 = c.callThrough(f64, 1.5, 2.5); // fn(f64, f64) f64
The pack cannot be read, indexed, or stored, only spread. Packs are not
available on plain fn or on top-level (comptime) cfns.