173 lines
6.0 KiB
HTML
173 lines
6.0 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>Sterling Language Documentation</title>
|
|
<style>
|
|
body { font-family: monospace; background: #0f0f0f; color: #f0f0f0; padding: 2rem; }
|
|
h1, h2, h3 { color: #00ffe0; }
|
|
pre { background: #1a1a1a; padding: 1rem; overflow-x: auto; }
|
|
code { color: #d0d0ff; }
|
|
a { color: #00aaff; }
|
|
</style>
|
|
</head>
|
|
<body>
|
|
|
|
<h1>Sterling Language Documentation</h1>
|
|
<p>Version: <code>0.1.0-alpha</code></p>
|
|
|
|
<h2>Overview</h2>
|
|
<p>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.</p>
|
|
|
|
<h3>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</h3>
|
|
|
|
<h2>File Extensions</h2>
|
|
<ul>
|
|
<li>Source files: <code>.stg</code></li>
|
|
<li>Header files: <code>.sth</code> <em>(placeholder, subject to change)</em></li>
|
|
</ul>
|
|
|
|
<h2>Function Qualifiers</h2>
|
|
<p>Every function must declare its linkage explicitly:</p>
|
|
|
|
<pre><code>
|
|
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
|
|
</code></pre>
|
|
|
|
<h2>Function Syntax</h2>
|
|
<p>All functions must explicitly declare their return type. The only exception is <code>void</code>, which may be omitted for brevity when no return value is intended.</p>
|
|
|
|
<pre><code>
|
|
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()
|
|
}
|
|
</code></pre>
|
|
|
|
<h2>Assembly Functions</h2>
|
|
<p>Write raw x86_64 assembly using <code>fn_asm</code> or <code>fn_static_asm</code>. Symbol, section, and global declaration are implicit.</p>
|
|
|
|
<pre><code>
|
|
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
|
|
}
|
|
</code></pre>
|
|
|
|
<h2>Syscalls</h2>
|
|
<p>System calls are allowed via <code>fn_asm</code> or wrapped using concrete ABI-aware interfaces. Example:</p>
|
|
|
|
<pre><code>
|
|
fn_asm void exit() {
|
|
mov rax, 60 ; syscall: exit
|
|
mov rdi, 0 ; exit code
|
|
syscall
|
|
ret
|
|
}
|
|
</code></pre>
|
|
|
|
<h2>Types</h2>
|
|
<p>Sterling supports explicitly sized, ABI-stable primitive types. Signed and unsigned integer types are defined as follows:</p>
|
|
|
|
<pre><code>
|
|
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)
|
|
</code></pre>
|
|
|
|
<p>Pointer types:</p>
|
|
|
|
<pre><code>
|
|
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
|
|
</code></pre>
|
|
|
|
<p>All types have explicitly defined size and alignment. Structs support default values and zero-initialization rules:</p>
|
|
|
|
<pre><code>
|
|
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)
|
|
</code></pre>
|
|
|
|
<p>To opt out of default zero-initialization:</p>
|
|
|
|
<pre><code>
|
|
@raw u32 raw_val; // uninitialized
|
|
</code></pre>
|
|
|
|
<h2>Memory Model</h2>
|
|
<p>Sterling uses explicit, manual memory management by default. All variables are zero-initialized unless explicitly marked with <code>@raw</code>. Heap allocation is done via standard system or custom allocators.</p>
|
|
<ul>
|
|
<li><strong>Stack</strong>: Local automatic variables</li>
|
|
<li><strong>Heap</strong>: malloc/free or custom allocators</li>
|
|
<li><strong>Zero-cost abstraction</strong>: structs and stack values are passed by value unless explicitly passed by pointer</li>
|
|
</ul>
|
|
<p>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.</p>
|
|
|
|
<h2>Operating System Development Features</h2>
|
|
<ul>
|
|
<li>Direct register access: <code>reg.rax</code>, <code>reg.cr3</code>, etc.</li>
|
|
<li>Memory barriers: <code>memory_fence_acquire()</code>, <code>memory_fence_release()</code></li>
|
|
<li>Segment descriptor support: GDT, IDT, TSS descriptors definable via built-in types</li>
|
|
<li>Interrupt handler definitions: <code>fn_isr</code> for IRQ, <code>fn_trap</code> for fault handlers</li>
|
|
<li>Syscall traps: <code>fn_syscall</code> with ABI-safe handling</li>
|
|
<li>No external ASM required: use <code>fn_asm</code> to write boot routines and context switches inline</li>
|
|
<li>Inline port I/O: <code>outb(port, val)</code>, <code>inw(port)</code>, etc.</li>
|
|
<li>MSR and control register access: readable and writable constants like <code>CR0_PG</code>, <code>MSR_EFER</code></li>
|
|
<li>Binary blob inclusion: <code>embed_binary("boot.bin")</code></li>
|
|
<li>Freestanding boot targets: no runtime required, bootloader/kernels fully supported</li>
|
|
</ul>
|
|
|
|
<h2>Metaprogramming</h2>
|
|
<p><em>TODO: Describe 'meta' keyword, templating, compile-time codegen, restrictions on type inference.</em></p>
|
|
|
|
<h2>ABI and Interop</h2>
|
|
<p><em>TODO: Specify ABI model (System V AMD64), calling convention details, struct/pointer representation rules.</em></p>
|
|
|
|
<h2>Threading</h2>
|
|
<p><em>TODO: Describe standard threading model, scheduler integration, context switching, green threads API.</em></p>
|
|
|
|
<h2>Graphics and Rendering</h2>
|
|
<p><em>TODO: Describe native rendering interface, GPU abstraction layer, and access to OpenGL/DirectX backends.</em></p>
|
|
|
|
<h2>Build and Compilation Model</h2>
|
|
<p><em>TODO: AOT compilation, linker behavior, multi-file project structure, module system (if any).</em></p>
|
|
|
|
</body>
|
|
</html>
|