454 lines
12 KiB
HTML
454 lines
12 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<link href="../assets/IosevkaSS15-Regular.ttf" rel="stylesheet">
|
|
<link rel="stylesheet" href="../css/sterling.css">
|
|
<link rel="stylesheet" href="../css/global.css">
|
|
<title>Sterling Documentation</title>
|
|
<script src="../js/sterling.js"></script>
|
|
</head>
|
|
<body>
|
|
<div style="width:100%">
|
|
<header>
|
|
<h1>Sterling Documentation</h1>
|
|
<input type="text" id="searchInput" placeholder="Search..." oninput="filterContent()">
|
|
<div class="controls">
|
|
<!--<button onclick="toggleTheme()">Toggle Theme</button>-->
|
|
<button onclick="window.print()">Export to PDF</button>
|
|
<button onclick="downloadOfflineVersion()">Download Offline</button>
|
|
</div>
|
|
</header>
|
|
|
|
|
|
<main id="doc-content">
|
|
|
|
<p>Version: <code>0.1.0-alpha</code></p>
|
|
|
|
<h2>Preface</h2>
|
|
<p>"An Idiot admire complexity, a genius admire simplicity" <em>Terry A. Davis</em></p>
|
|
<p>"Master All, Ace One" <em>Boykisser</em></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. It also introduces memory safety primitives and modern low-abstraction control flow enhancements.</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 <em>(subject to change)</em></h2>
|
|
<ul>
|
|
<li>Source files: <code>.stg</code></li>
|
|
<li>Header files: <code>.sth</code></li>
|
|
</ul>
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Function</h2>
|
|
<div class="section-content">
|
|
|
|
<h3>Qualifiers</h3>
|
|
<p>Every function must declare its linkage explicitly:</p>
|
|
|
|
<pre><code>
|
|
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) ??
|
|
</code></pre>
|
|
|
|
<h3>Syntax</h3>
|
|
<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_inline u32 max(u32 a, u32 b) {
|
|
return ((a > b) ? a : b);
|
|
}
|
|
|
|
fn exit() {
|
|
// equivalent to fn void exit()
|
|
}
|
|
</code></pre>
|
|
|
|
<h3>Assembly</h3>
|
|
<p>Write raw x86_64 assembly using <code>fn_asm</code> or <code>fn_static_asm</code>. Symbol, section, and global declaration are implicit.(placeholder)</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>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Syscalls</h2>
|
|
<div class="section-content">
|
|
<p>System calls are allowed via <code>fn_asm</code> or wrapped using concrete ABI-aware interfaces. Example: (placeholder)</p>
|
|
<pre><code>
|
|
fn_asm void exit() {
|
|
mov rax, 60 ; syscall: exit
|
|
mov rdi, 0 ; exit code
|
|
syscall
|
|
ret
|
|
}
|
|
</code></pre>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Register Access</h2>
|
|
<div class="section-content">
|
|
<p>Sterling exposes raw CPU registers as language-level primitives. This is intended for kernel, embedded, and runtime-critical tasks.</p>
|
|
<pre><code>
|
|
fn u64 get_rbp() {
|
|
return rbp;
|
|
}
|
|
|
|
fn void set_rsp(u64 val) {
|
|
rsp = val;
|
|
}
|
|
</code></pre>
|
|
<p>Supported registers: <code>rax, rbx, rcx, rdx, rsi, rdi, rsp, rbp, r8..r15</code>.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Types</h2>
|
|
<div class="section-content">
|
|
|
|
<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//maybe but not a fan of them
|
|
char // 1-byte character (UTF-8)
|
|
</code></pre>
|
|
<pre><code>
|
|
T* // Pointer to type T
|
|
ptr* // Special pointer with implicit coercion allowed
|
|
void* // Opaque pointer with explicit cast required
|
|
</code></pre>
|
|
|
|
<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
|
|
</code></pre>
|
|
<pre><code>
|
|
u32 raw_val @raw; // raw_val = ? can be poopoo data
|
|
</code></pre>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Memory Model</h2>
|
|
<div class="section-content">
|
|
<p>Manual memory management by default. Variables are zero-initialized unless marked <code>@raw</code>. All layout is predictable and cache-friendly. Custom allocators are encouraged.</p>
|
|
<ul>
|
|
<li><strong>Stack</strong>: locals</li>
|
|
<li><strong>Heap</strong>: explicit alloc/free</li>
|
|
<li><strong>Inline</strong>: structs passed by value</li>
|
|
</ul>
|
|
</div>
|
|
</section>
|
|
|
|
<!--<section class="section">
|
|
<h2 onclick="toggleSection(this)">Bitfields</h2>
|
|
<div class="section-content">
|
|
<pre><code>
|
|
typedef struct(bitfield) {
|
|
u8 field0 : 3;
|
|
u8 field1 : 5;
|
|
} Flags8;
|
|
</code></pre>
|
|
</div>
|
|
</section>-->
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Control Flow</h2>
|
|
<div class="section-content">
|
|
|
|
<h3>Loop</h3>
|
|
<p>Sterling introduces tagged loops and escape blocks for structured yet flat nested loop
|
|
behavior:</p>
|
|
|
|
<pre><code>
|
|
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)) {
|
|
}?
|
|
</code></pre>
|
|
<p>This allows control without stack-nesting or excessive flags.</p>
|
|
|
|
<h3>Branching</h3>
|
|
<p></p>
|
|
|
|
<pre><code>
|
|
|
|
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() {
|
|
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
</code></pre>
|
|
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Dynamic Arrays with Aligned Layout</h2>
|
|
<div class="section-content">
|
|
<p>Runtime-initialized aligned linear arrays can be used to simulate array-of-array structures, where all memory layout is controlled explicitly with offsets:</p>
|
|
<pre><code>
|
|
struct ArrayView {
|
|
u8* data;
|
|
u32 stride;
|
|
u32 count;
|
|
};
|
|
</code></pre>
|
|
<p>Insertions and deletions move memory explicitly, re-aligning if needed.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Dynamic Linking</h2>
|
|
<div class="section-content">
|
|
<p>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.</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Metaprogramming</h2>
|
|
<div class="section-content">
|
|
<p><em>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</em></p>
|
|
|
|
<h2>Metaprogramming</h2>
|
|
<p>Sterling supports compile-time metaprogramming via the <code>meta</code> keyword. Meta constructs are evaluated at compile time and allow structured code generation, reflection, and type introspection.</p>
|
|
|
|
<h3>Capabilities</h3>
|
|
<ul>
|
|
<li>Generate code at compile-time (functions, structs, constants)</li>
|
|
<li>Inspect type properties: size, alignment, fields</li>
|
|
<li>Enumerate over struct fields, enum variants, function parameters</li>
|
|
<li>Branch compile-time logic via <code>meta if</code>, <code>meta match</code></li>
|
|
<li>Define metafunctions using <code>meta fn</code> (not emitted at runtime)</li>
|
|
<li>Support platform/target-specific compilation logic</li>
|
|
</ul>
|
|
|
|
<h3>Restrictions</h3>
|
|
<ul>
|
|
<li>Meta code must be side-effect free (pure, deterministic)</li>
|
|
<li>No runtime reflection or dynamic codegen</li>
|
|
<li>No access to I/O, filesystem, or arbitrary memory</li>
|
|
<li>All meta-expansions must type-check</li>
|
|
<li>Expansion depth and iteration count are bounded</li>
|
|
</ul>
|
|
|
|
<h3>Example</h3>
|
|
<pre><code>
|
|
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) { ... }
|
|
}
|
|
</code></pre>
|
|
|
|
<h3>Compiler Meta API (proposed)</h3>
|
|
<pre><code>
|
|
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
|
|
</code></pre>
|
|
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">ABI and Interop</h2>
|
|
<div class="section-content">
|
|
<p><em>TODO: Specify ABI model (System V AMD64), calling convention details, struct/pointer representation rules. C interaction, emiting ELF/COFF/Mach-O symbol tables .o</em></p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Threading</h2>
|
|
<div class="section-content">
|
|
<p><em>TODO: Describe standard threading model, scheduler integration, context switching, green threads API.</em></p>
|
|
|
|
<h3>Fiber (Coroutine)</h3>
|
|
<p>Using user managed stack that is allocated (usefull for userland threading)</p>
|
|
|
|
<ul>
|
|
<li>Each <code>fiber</code> as:</li>
|
|
<ul>
|
|
<li>Its own manually allocated stack</li>
|
|
<li>Registers saved/restored on yield and resume</li>
|
|
<li>Tracked by a runtime scheduler (or user managed)</li>
|
|
</ul>
|
|
<li><code>fiber_yield()</code> triggers context switch, calling back into a fiber scheduler</li>
|
|
<li>Can be pooled, migrated between threads, or used for deterministic execution (e.g., game loops, scripting)</li>
|
|
</ul>
|
|
|
|
<h4>Internal Scheduler Model</h4>
|
|
<ul>
|
|
<li>A circular queue or priority queue of fiber_ids</li>
|
|
<li><code>fiber_yield()</code> pushes current fiber to back of queue</li>
|
|
<li><code>fiber_resume()</code> pulls next and switches context</li>
|
|
</ul>
|
|
<p>This allows async, non-blocking logic to be modeled without system threads.<p>
|
|
|
|
<h4>Safety and ABI Guarantees</h4>
|
|
|
|
<ul>
|
|
<li>define the fiber stack layout, allowing for precise control (great for embedded targets)</li>
|
|
<li><code>fiber_spawn</code> can return errors if stack is misaligned or exhausted</li>
|
|
<li>ABI guarantees for fiber functions: must follow a calling convention you define (e.g., preserved registers)</li>
|
|
|
|
<h3>Thread</h3>
|
|
<p></p>
|
|
<ul>
|
|
<li>Created via OS APIs (e.g., pthread, CreateThread, or syscall wrappers)</li>
|
|
<li>Each thread runs independently; shares global heap and data structures</li>
|
|
<li>You wrap OS threads and assign them entry points via thread_spawn</li>
|
|
</ul>
|
|
|
|
<h4>Thread Primitives</h4>
|
|
|
|
<pre><code>
|
|
fn thread_spawn(void fn() entry_fn) -> thread_id;
|
|
fn thread_join(thread_id tid);
|
|
fn thread_exit();
|
|
</code></pre>
|
|
|
|
<h4>Fiber Primitives</h4>
|
|
|
|
<pre><code>
|
|
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;
|
|
</code></pre>
|
|
|
|
<h4>Optional stack control:</h4>
|
|
|
|
<pre><code>
|
|
fn fiber_spawn_stack(void fn(), void* stack_ptr, u64 size);
|
|
</code></pre>
|
|
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Graphics and Rendering</h2>
|
|
<div class="section-content">
|
|
<p><em>TODO: Describe native rendering interface</em>I 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</p>
|
|
</div>
|
|
</section>
|
|
|
|
<section class="section">
|
|
<h2 onclick="toggleSection(this)">Build and Compilation Model</h2>
|
|
<div class="section-content">
|
|
<p><em>TODO: AOT compilation, linker behavior, multi-file project structure, module system (if any).</em></p>
|
|
</div>
|
|
</section>
|
|
|
|
<footer>
|
|
<section>
|
|
|
|
<a href="mailto:dev@sleepeesoftware.fr"><h4>email</h4></a>
|
|
</section>
|
|
<section>
|
|
|
|
<a href="https://sleepeesoftware.fr"><h4>website</h4></a>
|
|
</section>
|
|
</footer>
|
|
<p style="text-align: center;">Copyright @ 2025 Carle-Margueritte Alexandre<br>Verbatim copying and redistribution of this entire page are permitted provided this notice is preserved.<br>
|
|
Verbatim copying and redistribution of any of the photos in the photos subdirectory is permitted under the <a href="https://opensource.org/license/mit">MIT License</a></p>
|
|
</div>
|
|
</body>
|
|
</html>
|