Sterling Documentation

Every function must declare its linkage explicitly:

		
fn globally visible, default linkage
		
fn_static translation unit-local only
		
fn_inline inline-only, no symbol emitted
		
fn_asm raw assembly function, globally visible
		
fn_static_asm raw assembly function, TU-local only
	

All functions must explicitly declare their return type. The only exception is void, which may be omitted for brevity when no return value is intended.

fn u32 add(u32 a, u32 b) {
	return (a + b);
}

fn_inline u32 max(u32 a, u32 b) {
	return ((a > b) ? a : b);
}

fn exit() {
	// equivalent to fn void exit()
}

Write raw x86_64 assembly using fn_asm or fn_static_asm. Symbol, section, and global declaration are implicit.

fn_asm void* memset(void* dst, u8 value, u64 size) {
	test rdx, rdx
	je .done

	mov rax, rsi
	mov rdi, rdi
	mov rcx, rdx

	rep stosb

.done:
	mov rax, rdi
	ret
}

System calls are allowed via fn_asm or wrapped using concrete ABI-aware interfaces. Example:

fn_asm void exit() {
	mov rax, 60   ; syscall: exit
	mov rdi, 0    ; exit code
	syscall
	ret
}

Sterling exposes raw CPU registers as language-level primitives. This is intended for kernel, embedded, and runtime-critical tasks.

fn u64 get_rbp() {
	return rbp;
}

fn void set_rsp(u64 val) {
	rsp = val;
}

Supported registers: rax, rbx, rcx, rdx, rsi, rdi, rsp, rbp, r8..r15.

i8, i16, i32, i64	// signed integers
u8, u16, u32, u64	// unsigned integers
f32, f64		// 32-bit and 64-bit IEEE floats
bool			// 1-byte boolean, 0 or 1 only
char			// 1-byte character (UTF-8)

T*	// Pointer to type T
ptr*	// Special pointer with implicit coercion allowed
void*	// Opaque pointer with explicit cast required

typedef struct {
	u32 x = 5;
	u32 y;
} vec2u;

vec2u a = {};      // x = 5, y = 0
vec2u b = {0};     // x = 0, y = 0
vec2u c;           // x = 0, y = 0

u32 raw_val @raw;

Manual memory management by default. Variables are zero-initialized unless marked @raw. All layout is predictable and cache-friendly. Custom allocators are encouraged.

• Stack: locals
• Heap: explicit alloc/free
• Inline: structs passed by value

typedef struct(bitfield) {
	u8 field0 : 3;
	u8 field1 : 5;
} Flags8;

Sterling introduces tagged loops and escape blocks for structured yet flat nested loop behavior:

loop_outer: loop {
	loop_inner: loop {
		if (should_exit_inner()) break loop_inner;
		if (should_exit_outer()) break loop_outer;
	}
}

This allows control without stack-nesting or excessive flags.

In place of traditional if-else trees for dual-tiling, prefer using precomputed lookup tables, or bitwise masks with packed branchless evaluation. Consider encoding tile states as compact u16 index and dereferencing behavior.

Runtime-initialized aligned linear arrays can be used to simulate array-of-array structures, where all memory layout is controlled explicitly with offsets:

struct ArrayView {
	u8* data;
	u32 stride;
	u32 count;
};

Insertions and deletions move memory explicitly, re-aligning if needed.

Sterling does not rely on dynamic linking by default. Static linking is favored for OS and runtime simplicity. Dynamic linking may be optionally implemented via host-defined facilities.

TODO: Describe 'meta' keyword, templating, compile-time codegen, restrictions on type inference.

TODO: Specify ABI model (System V AMD64), calling convention details, struct/pointer representation rules.

TODO: Describe standard threading model, scheduler integration, context switching, green threads API.

TODO: Describe native rendering interface

TODO: AOT compilation, linker behavior, multi-file project structure, module system (if any).