Sterling Language Documentation

Version: 0.1.0-alpha

Overview

Sterling is a low-level, strongly typed, systems programming language designed for performance, ABI stability, C interoperability, and full control over memory and hardware. It supports metaprogramming, hot-reloading, inline and raw assembly, and is built for multi-file compilation and dynamic linking.

This Document is a work in progress, features are not yet implemented and i use this as a design document to stay true to my vision

File Extensions

• Source files: .stg
• Header files: .sth (placeholder, subject to change)

Function Qualifiers

Every function must declare its linkage explicitly:

fn		// globally visible, default linkage
fn_static	// translation unit-local only
fn_export	// must be exported to dynlib/staticlib
fn_extern	// declared but defined elsewhere
fn_inline	// inline-only, no symbol emitted
fn_asm		// raw assembly function, globally visible
fn_static_asm	// raw assembly function, TU-local only

Function 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_extern i32 printf(const char* fmt, ...);

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

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

Assembly Functions

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
}

Syscalls

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
}

Types

Sterling supports explicitly sized, ABI-stable primitive types. Signed and unsigned integer types are defined as follows:

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)

Pointer types:

T*	// Pointer to type T
ptr*	// Special pointer with implicit coercion allowed (e.g., for GC, reflective systems)
void*	// Opaque pointer with explicit cast required

All types have explicitly defined size and alignment. Structs support default values and zero-initialization rules:

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 (default zero-init)

To opt out of default zero-initialization:

@raw u32 raw_val; // uninitialized

Memory Model

Sterling uses explicit, manual memory management by default. All variables are zero-initialized unless explicitly marked with @raw. Heap allocation is done via standard system or custom allocators.

• Stack: Local automatic variables
• Heap: malloc/free or custom allocators
• Zero-cost abstraction: structs and stack values are passed by value unless explicitly passed by pointer

Alignment and packing are controllable per type (TBD syntax). All layout is predictable and optimized for cache behavior. There are no hidden fields, vtables, or RTTI overhead.

Operating System Development Features

• Direct register access: reg.rax, reg.cr3, etc.
• Memory barriers: memory_fence_acquire(), memory_fence_release()
• Segment descriptor support: GDT, IDT, TSS descriptors definable via built-in types
• Interrupt handler definitions: fn_isr for IRQ, fn_trap for fault handlers
• Syscall traps: fn_syscall with ABI-safe handling
• No external ASM required: use fn_asm to write boot routines and context switches inline
• Inline port I/O: outb(port, val), inw(port), etc.
• MSR and control register access: readable and writable constants like CR0_PG, MSR_EFER
• Binary blob inclusion: embed_binary("boot.bin")
• Freestanding boot targets: no runtime required, bootloader/kernels fully supported

Metaprogramming

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

ABI and Interop

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

Threading

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

Graphics and Rendering

TODO: Describe native rendering interface, GPU abstraction layer, and access to OpenGL/DirectX backends.

Build and Compilation Model

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