Source
Design: stage 0 and the S0 subset, including its amendment comment of 2026-11-16, which applies the file-extension decision and the ownership design. Status: draft. The formal grammar is in the specification: S0 Grammar.
S0 is the deliberately tiny subset of Cesium that stage 0 compiles. Stage 0 has one job, which is to compile stage 1 (cesium1), and stage 1 is written in S0. See Bootstrap Chain.
S0 is designed together with core MIR so that it is essentially a readable notation for it: almost every S0 construct maps one-to-one onto a core MIR construct.
Rules
- S0 is a strict subset of Cesium. Every S0 program is a valid Cesium program with the same meaning. Later compilers must still be able to compile the frozen stage 1.
- Features are added to S0 only when stage 1’s code genuinely needs them and implementing them in stage 0 is cheaper than writing around them.
- S0 maps (nearly) one-to-one onto core MIR. A feature that needs a nontrivial rewrite belongs in S1.
- Stage 0’s output may be naive.
Contents
| Area | S0 |
|---|---|
| Types | u8, i32, u32, i64, u64, uword; pointers #T (~T is parsed and treated the same: no borrow checking); pointer-to-pointer (##T); fixed arrays T name[N] |
| Data | struct with fields only: no methods, no struct literals (assign fields one at a time) |
| Control flow | if / else, while, break, continue, return |
| Functions | T = name(params) { ... }, single return value, void, recursion |
| Expressions | + - * / %, comparisons, && || !, bitwise & | and >< (XOR), shifts << >>, indexing p[i], address-of #x, field access a.b (auto-dereferences pointers), casts as, sizeof |
| Literals | integers, characters ('A'), strings as NUL-terminated #u8 |
| Memory | alloc(count) only: a bump arena that never frees. The element type comes from the declared target |
| Globals | global variables and const globals (constants also stand in for enums) |
| Outside world | extern name = import('lib') { ... } blocks declaring C ABI functions: a few libc functions (open, read, write, close, exit) and the coarse libcsmir API |
| Compilation unit | multiple files compiled as one unit with shared globals; no import of Cesium modules |
| Entry point | hosted main: i32 = main(i32 argc, ##u8 argv) |
| Source files | .csm |
i32 and u32 are required for C ABI correctness: passing an i64 where C expects an int happens to work on x86-64 but breaks on 32-bit targets.
S0’s arithmetic follows core MIR’s defined semantics (wrapping integers, defined shifts and division by zero), so stage 0’s output means the same thing on both backends.
Pointers in S0
Because S0 must be a strict subset of Cesium, S0 source follows the ownership syntax even though stage 0 does not enforce ownership:
-
A pointer is never initialized or re-pointed with plain
=. Plain=on a pointer assigns through it. A pointer gets its address with:=(ownership, as for the result ofalloc) or with#=(borrow):#Token t := alloc(1); // not: #Token t = alloc(1); t.start #= "hello"; // setting a pointer field: address-context assignment -
Dereference-by-default is confirmed. There is no dereference operator.
p[i]reads or writes an element, andp.fieldreaches through a pointer to a struct. -
#Tin a declaration is a pointer (to data that cannot be modified through it) everywhere. -
Stage 0 parses
~Tand treats it the same as#T.
Open
The design record does not yet say how the rest of the ownership rules apply to S0 source. S0 has no
free, while in full Cesium an owner that is never released is a compile error; and the record’s sample program writes through#Tpointers (t.kind = ...,buf[i] = ...), which the ownership design allows only through~T. Rule 1 above (strict subset) means these have to be reconciled before stage 1 is frozen. Track in cesiumlang/cesium#9.
S0 to Core MIR
| S0 | Core MIR |
|---|---|
T name = e; (local) | local %name: T = e |
x = e; (local) | set %x = e |
p[i] = e;, p.f = e; | store index(p, i), e, store field(p, f), e |
p[i], p.f (read) | load(index(p, i)), load(field(p, f)) |
#x | addr(%x) |
if / else, while, break, continue, return | the same structured statements |
a + b, a < b, a >< b, … | add(a, b), lt(a, b), xor(a, b), … |
a && b, a || b, !a | land(a, b), lor(a, b), lnot(a) |
e as T | as(T, e) |
sizeof(T) | sizeof(T) (resolved by the backend) |
f(args) | call @f(args) |
"text" | const @str.N: [len+1 x u8] = "text\00" and its address |
alloc(n) (target #T) | as(ptr<T>, call @cs_arena_alloc(mul(n, sizeof(T)), alignof(T))) |
struct S { ... } | struct S { ... } |
extern ... import(...) { ... } | extern func @name(...) -> T callconv(c) |
Every statement also carries its source location, so the backends can emit debug line information.
Not in S0
for, ranges, switch / case, enum, unions and typeof, slice / list / dict / str, multiple return values, defer, error types and catch / throw, modules and import of Cesium code, floating point, free / realloc, methods and this, generics, traits, inheritance, operator overloading, the math operators (^, ::, @, context-aware *, postfix ~), SIMD, comptime, string interpolation, with, inline asm, volatile / atomic.
Stage 1’s source simulates what it needs by hand: tag fields plus casts for AST nodes, hand-written hash tables over pointers, error codes as return values, NUL-terminated strings with explicit lengths where needed.
Sample Program
This is the sample from the design record with its amendment applied: pointers are initialized with := and the pointer field is set with #=. It is illustrative; the exact syntax still depends on the open questions below.
extern libc = import('c') {
i64 = write(i32 fd, #u8 buf, uword len);
}
const i64 TOK_IDENT = 1;
const i64 TOK_NUMBER = 2;
struct Token {
i64 kind;
#u8 start;
uword len;
}
uword = cstr_len(#u8 s) {
uword n = 0;
while (s[n] != 0) {
n = n + 1;
}
return n;
}
void = print(#u8 s) {
write(1, s, cstr_len(s));
}
// Write an unsigned integer as decimal text into buf; returns the length.
uword = fmt_u64(u64 v, #u8 buf) {
u8 tmp[20];
uword n = 0;
if (v == 0) {
buf[0] = '0';
return 1;
}
while (v != 0) {
tmp[n] = ('0' + (v % 10)) as u8;
v = v / 10;
n = n + 1;
}
uword i = 0;
while (i < n) {
buf[i] = tmp[n - 1 - i];
i = i + 1;
}
return n;
}
i32 = main(i32 argc, ##u8 argv) {
#Token t := alloc(1);
t.kind = TOK_IDENT;
t.start #= "hello";
t.len = cstr_len(t.start);
#u8 buf := alloc(32);
uword n = fmt_u64(t.len as u64, buf);
buf[n] = '\n';
buf[n + 1] = 0;
print("token length: ");
print(buf);
return 0;
}Provisional — not decided (cesiumlang/cesium#9)
If S0 source is to pass the full compiler’s borrow checker later, the pointers this sample writes through would be declared
~Tinstead of#T(~Token t := alloc(1);,~u8 buf := alloc(32);, and thebufparameter offmt_u64as~u8). Stage 0 treats the two sigils the same, so this costs nothing now and avoids rewriting frozen stage 1 source. This is a recommendation, not part of the design record.
Stage 0 as Implemented
Source
The first implementation of stage 0, cesiumlang/cesium#60 (under review). Its
bootstrap/README.mdis the reference for what follows. This section describes what the compilercesium0does; it decides nothing about the language.
cesium0 compiles the sample above, with the pointers it writes through declared ~T, and its cstr_len lowers to exactly the core MIR shown on the MIR page.
Stage 0 checks only what keeps S0 source meaningful:
- There are no implicit conversions. Both operands of a binary operator have one type;
asconverts. - An integer literal takes the type its context gives it: the declared type, a parameter type, or the type of the other operand.
- A pointer is used as a pointer only where one is expected: an argument for a pointer parameter, the right side of
:=,#=or~=, a returned pointer, or the operand of a cast to a pointer type. Everywhere else it is read through. :=,#=and~=are accepted only with a pointer on the left; a pointer declaration with plain=is an error.alloc(count)appears only on the right of:=.
It does not check ownership or borrowing, and it does not check that writes go through ~T.
What Stage 0 Rejects Because the Design Is Open
S0 source is frozen once stage 1 works, and every later compiler must accept it with the same meaning. Where the design has no recorded answer, cesium0 rejects the program instead of choosing one:
| Rejected | Open in |
|---|---|
A literal whose type no context gives, such as if (1) or 1 == 1 | cesiumlang/cesium#9, open question 2 |
Unary minus (write 0 - x) | cesiumlang/cesium#15 |
| Literal forms other than decimal | cesiumlang/cesium#56 |
| A local that reuses a name already in scope | not recorded in any issue |
null. S0 has no way to test or compare a pointer: p == q compares what the pointers point at | cesiumlang/cesium#26, cesiumlang/cesium#43 |
| A name that is a keyword of full Cesium | cesiumlang/cesium#50 |
| Assigning a struct or array as a whole | cesiumlang/cesium#22 |
Provisional — not decided
To be writable at all,
cesium0had to settle a few points that no issue decides. They are implementation choices listed for review in cesiumlang/cesium#60, not rules of S0:
~=, prefix~xand the owned forms:#T/:~Tare accepted and treated as#=,#xand the plain pointer type.!is a prefix operator andasbinds more tightly than every binary operator (cesiumlang/cesium#15).- The escapes
\n,\t,\r,\0,\\,\'and\"are accepted (cesiumlang/cesium#39).- Functions of an
externblock are called by their bare name (cesiumlang/cesium#19).- Array lengths are integer literals; constants are integers; a global is initialized by a literal, a constant, or a string for a
#u8.- Division by zero and signed
MIN / -1trap, and a local without an initializer starts as zero (cesiumlang/cesium#8).
Stage 1 Goals (S1)
Stage 1 is written in S0 and compiles S1. Each S1 feature is defined as a rewrite into core MIR. These are candidates, to be confirmed when stage 1 is designed:
forwith ranges and collection iteration;switch/casewith values, ranges andelseenum(including backed enums); type unions withswitch (typeof(x))strandslice[T]; built-inlist[T]anddict[K,V]- multiple return values;
defer errortypes,T|Errorreturns,catch (err) { case (...) }(return-based only)namespaceandimportof Cesium modules;privatef32/f64, including exact decimal-to-IEEE conversion for literals- a real allocator (
free,realloc) - possibly methods with
this
Testing
- A corpus of S0 programs with expected outputs.
- Golden MIR tests: S0 source to expected MIR text, and MIR text to expected behavior.
- Differential testing through QBE, LLVM
-O0and LLVM-O2once the LLVM lowering exists. cesium1built by stage 0 must compile the S1 test corpus and the real compiler.- Every later compiler must still compile the frozen stage 1.
Open Questions
From the design record, after its amendment:
File extension.Decided:.csm(cesiumlang/cesium#14).- Declaration and pointer syntax. Dereference-by-default and the meaning of
#Tare confirmed. Still open: the result type of comparisons (u8in core MIR, since Cesium has nobool) and the default type of an integer literal when context does not determine it. - Core MIR text syntax (cesiumlang/cesium#8).
- Which QBE version to vendor, and confirming its line-debug support and Windows output.
Cesium