Zero mode
Zero mode is C# without .NET's runtime. The compiler turns the program into native code ahead of time and links it into one self-contained executable that needs only the C library, and that program carries no garbage collector, no exception handling, no reflection and almost no base class library. What is left is C#'s syntax, type safety and generics, with binaries the size of a C program's. The repository's README puts it as "C with proper generics".
Why give up the runtime
A normal .NET program brings System.Private.CoreLib and a native runtime with it: megabytes of code
before your own. Zero mode drops both. The smallest sample, samples/Tiny.cs, is about 16 KB once it
is stripped, and a hello world through puts is about 39 KB on Linux arm64.
// Example: Smallest possible bflat binary (~16 KB stripped).
// Build: ./build.sh Tiny (build.sh adds -Os --no-pie and strips)
using System.Runtime.InteropServices;
namespace TinySample;
public static class Program
{
[DllImport("libc")]
static unsafe extern int puts(byte* s);
public static int Main()
{
byte* msg = stackalloc byte[] { (byte)'H', (byte)'i', 0 };
unsafe { puts(msg); } // SAFETY: msg is NUL-terminated.
return 0;
}
}
The price is what the runtime used to do. Nothing collects garbage, so memory is your job (see
Memory without a GC). Nothing catches exceptions, so a throw, a failed cast or an
index out of range prints a message and ends the program. And most library types you know from .NET
are not there; lib/ supplies the ones these programs need. The same program also builds as a
WebAssembly module and as a DOS program for a 386 (see Targets).
bflat and the fork
bflat is a C# compiler that produces native programs directly. It has a zero mode of its own, --stdlib:zero, with a small core library
called zerolib.
This repository needs a fork of it, OnurGumus/bflat. The fork matters here mostly as a compiler:
- It compiles C# 15. Its Roslyn is the one shipped with the .NET 11 SDK, and a
--compiler-featureoption turns on the updated memory safety rules that every sample is written under. - Instruction sets come only from
-m. Zero mode has no run-time CPU detection, so a check such asDp.IsSupportedisfalseunless the build names that instruction set with-m. - It ships the .NET 10 GA JIT, which fixes static-field stores that the RC1 JIT in upstream bflat miscompiles on x64.
The fork also fixes and extends zerolib (strings, arrays, static fields, casts, SIMD). Those changes
only matter if you build with --stdlib:zero. The repository's build.sh doesn't: it uses its own core
library instead. Install shows how to get and build the fork.
Two libraries: zerocore and lib
Every C# program needs a core library: the assembly that defines object, int and string, and that
holds the code the compiler calls to allocate objects, check casts and set up static fields. In zero
mode that code is all the "runtime" there is.
zerocore/ is the core library. It replaces zerolib, under the MIT license, in about 2,400 lines
of C# and three short assembly routines per architecture. build.sh compiles it from source and
passes it to bflat with --stdlib:none, so nothing AGPL-licensed ends up in the binaries. It contains:
- the types the C# compiler requires: primitives,
object, arrays, delegates,Span<T>andReadOnlySpan<T>; string, withLength, an indexer,==,!=,Equals,IsNullOrEmptyand concatenation, soa + bandswitchon strings work;- allocation: every
new, boxing and string concatenation callscalloc, which zeroes memory as C# requires, and nothing is ever freed; - casts:
is,asand(T)xto classes and interfaces, and interface calls the compiler can't resolve at build time; - startup: storage for static fields that hold references, static constructors and
Main(string[] args); Math,MathF,Interlocked,Volatile, and the SIMD typeslib/Kernels.csuses.
Much of it is a contract with the compiler, which looks types, methods and fields up by name. Those
names can't be changed. Compared with zerolib, zerocore adds casts to interfaces, interface calls the
compiler can't resolve at build time, boxing and Main(string[] args), and leaves out Console and
Half.
lib/ is the library programs use. It is ordinary C# built on top of zerocore, and it is where
zero mode gets what .NET's base class library would otherwise provide:
Arena, the allocator for everything short-lived (see Memory without a GC);- collections that live in an arena:
List,Dict,RefList,StrDict,RefDict; Str,StrBuilder,OutandInfor text, input and output (see Strings without a GC);Kernels, SIMD math, andDos, the PC's screen, keyboard and speaker on DOS.
The split follows one rule: zerocore holds what the compiler requires, and lib/ holds what programs
choose to use. Each is compiled once into an IL assembly, and each program references both with -r.
Because the assembly holds IL, not native code, every program's build compiles only the parts it uses,
instantiates generics for its own types, and generates code for its own -m flags.
Where to go next
- Memory without a GC explains the biggest change from .NET.
- Limits lists what zero mode supports and what it doesn't.
- Your first program builds and runs one.