Sterling Documentation

Qualifiers

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
fn_inline_asm	//inline-only asm, no symbol emitted
fn_async	//for fiber (coroutine) ??

Syntax

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()
}

Assembly

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

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: (placeholder)

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//maybe but not a fan of them
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; // raw_val = ? can be poopoo data

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

Loop

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;
	}
}

loop {
	i32 i;//default init at 0

	while() {
		do
	}
}

loop {
	i32 i;
	while() {
		do
	}
}

for_each (tmp : array(T)) {
}?

This allows control without stack-nesting or excessive flags.

Branching

fn u32 test(u32 x, u32 y) {
	if (x == y) {

	}
	if (x == 0) {

	}
	if (y == 0) {

	}

	switch (data) {
		(a) {
			break;
		}
		(b) {
			break;
		}
		default: {
			break;
		}
	}

	block search {
		loop delta {
			i32 i;
			while() {

			}
		}
	}
}

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 in the future.

also i am not thinking of having something as close as what jai have, if you want solid meta programming look out for when jai become open beta

Metaprogramming

Sterling supports compile-time metaprogramming via the meta keyword. Meta constructs are evaluated at compile time and allow structured code generation, reflection, and type introspection.

Capabilities

• Generate code at compile-time (functions, structs, constants)
• Inspect type properties: size, alignment, fields
• Enumerate over struct fields, enum variants, function parameters
• Branch compile-time logic via meta if, meta match
• Define metafunctions using meta fn (not emitted at runtime)
• Support platform/target-specific compilation logic

Restrictions

• Meta code must be side-effect free (pure, deterministic)
• No runtime reflection or dynamic codegen
• No access to I/O, filesystem, or arbitrary memory
• All meta-expansions must type-check
• Expansion depth and iteration count are bounded

Example

meta fn print_fields_of(T) {
	for (field : fields(T)) {
		print("Field: ", field.name, " of type ", field.type);
	}
}

meta if sizeof(T) > 64 {
	fn_inline void fast_copy(T* dst, T* src) { ... }
}

Compiler Meta API (proposed)

meta_typeof(expr)
meta_sizeof(T)
meta_alignof(T)
meta_fields_of(T)
meta_fn_params(fn)
meta_platform() // e.g., "linux", "windows"
meta_codegen(name, ast_block) // gated for advanced use

TODO: Specify ABI model (System V AMD64), calling convention details, struct/pointer representation rules. C interaction, emiting ELF/COFF/Mach-O symbol tables .o

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

Fiber (Coroutine)

Using user managed stack that is allocated (usefull for userland threading)

• Each fiber as:
• Its own manually allocated stack
• Registers saved/restored on yield and resume
• Tracked by a runtime scheduler (or user managed)
• fiber_yield() triggers context switch, calling back into a fiber scheduler
• Can be pooled, migrated between threads, or used for deterministic execution (e.g., game loops, scripting)

Internal Scheduler Model

• A circular queue or priority queue of fiber_ids
• fiber_yield() pushes current fiber to back of queue
• fiber_resume() pulls next and switches context

This allows async, non-blocking logic to be modeled without system threads.

Safety and ABI Guarantees

• define the fiber stack layout, allowing for precise control (great for embedded targets)
• fiber_spawn can return errors if stack is misaligned or exhausted
• ABI guarantees for fiber functions: must follow a calling convention you define (e.g., preserved registers)

Thread

• Created via OS APIs (e.g., pthread, CreateThread, or syscall wrappers)
• Each thread runs independently; shares global heap and data structures
• You wrap OS threads and assign them entry points via thread_spawn

Thread Primitives

fn thread_spawn(void fn() entry_fn) -> thread_id;
fn thread_join(thread_id tid);
fn thread_exit();

Fiber Primitives

typedef struct fiber {
	void*	stack;
	u64	stack_size;
	void*	ip;//instruction pointer
	u8	flag;
}	fiber;

fn fiber_spawn(void fn() entry_fn) -> fiber_id;
fn fiber_yield();
fn fiber_resume(fiber_id id);
fn fiber_self() -> fiber_id;//could also be used instead of fork ex main process fibe_self = 0;

Optional stack control:

fn fiber_spawn_stack(void fn(), void* stack_ptr, u64 size);

TODO: Describe native rendering interfaceI have been thinking about supporting amd gpu acceleration with very few set of actual call, very fewer than opengl or other, but i will focus only on one hardware at first

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