Install with dotnet

With the .NET SDK, you can build zero-mode programs without cloning this repository. Three NuGet packages do it: a project SDK (ZeroCSharp.Sdk), the bflat compiler for your machine (ZeroCSharp.Bflat.linux-x64 or linux-arm64, downloaded by the SDK), and the project templates (ZeroCSharp.Templates). dotnet build then makes a native program, and your editor understands the code.

What you need

  • The .NET 10 SDK. Nothing else: the packages bring the compiler and the linker.
  • Linux, x64 or arm64, to build programs. The packages are tested on Ubuntu 22.04 and 24.04, Debian 12 and Fedora 41, each with nothing but the .NET SDK installed.
  • On macOS, everything except the last step works: the editor, compiling, libraries and dotnet pack. Building a program stops with an error that says so. Build programs on a Linux machine or in a container, or install from the repository, which also covers macOS, WebAssembly and DOS. Windows as a build machine comes in the next version.

Make a program

dotnet new install ZeroCSharp.Templates
dotnet new zero -o Hello
cd Hello
dotnet build

dotnet new zero makes a project and this program, which reads a name into a buffer on the stack and greets it:

// A zero-mode program: no .NET runtime and no garbage collector. Out and In
// write and read without allocating; the name is read into a stack buffer.
using System;

Out.Write("What's your name? ");
Span<char> buffer = stackalloc char[64];
int length = In.ReadLine(buffer);
// length is -1 at the end of input, and more than the buffer holds when
// the line didn't fit: then keep what did.
ReadOnlySpan<char> name = length switch
{
    <= 0 => "world",
    _ when length > buffer.Length => buffer,
    _ => buffer.Slice(0, length),
};
Out.Write("Hello, ");
Out.Write(name);
Out.Line("!");

dotnet build puts the native program in bin/Debug/zero01/; dotnet run builds and runs it:

echo Ann | bin/Debug/zero01/Hello
echo Ann | dotnet run
What's your name? Hello, Ann!

zero01 is the project's target framework: zero mode, version 0.1 of the SDK. It keeps ordinary .NET packages out, because they need .NET's libraries, which a zero program doesn't have.

Build for another target

The ZeroTarget property picks what to build for; by default it's the machine you build on. A program for a chosen target goes in a folder named after it, as dotnet build -r does for .NET, so programs for several targets sit side by side:

dotnet build -p:ZeroTarget=win-x64        # bin/Debug/zero01/win-x64/Hello.exe
dotnet build -p:ZeroTarget=linux-arm64    # bin/Debug/zero01/linux-arm64/Hello

dotnet clean removes all of them.

Property Values Default
ZeroTarget linux-x64, linux-arm64, win-x64 the build machine's
ZeroOptimizeFor Speed, or Size (bflat's -Os) Speed
ZeroInstructionSet passed to bflat as -m, e.g. x86-64-v3 or dotprod (see Use SIMD) none
ZeroDllImports more libraries whose [DllImport]s are bound when linking, besides libc and libm.so.6, which always are none

Set them on the command line with -p:, or in the project file. The native program is optimized in Debug and Release alike. dotnet publish copies it, and only it, to the publish folder: it needs nothing next to it.

What dotnet build does

It compiles your code twice. First the C# compiler compiles it against zerocore and lib/, the way your editor sees it, into an IL .dll: this is where C# errors come from, and Console or any other .NET API that zero mode doesn't have is an error here. Then bflat compiles the same sources into the native program, with zerocore, lib/ and any zero libraries the project references. Both compile with the project's LangVersion, Features and DefineConstants. bflat runs again only when a source, a referenced library or a property changed.

The target framework is always the SDK's: a project that sets TargetFramework gets error ZERO001.

The compiler is pinned to the one bflat uses (Roslyn 5.12), so C# 15's unions and the memory safety rules work in dotnet build whatever your SDK's own compiler is.

Editors

Editors check code with the compiler they bundle, not the pinned one, so an editor whose compiler is older than Roslyn 5.12 can mark C# 15 features as errors that dotnet build accepts, and a newer one may treat preview features a little differently. For example, the C# extension for VS Code, version 11.9.41, bundles Roslyn 5.14. How editors handle these projects hasn't been checked yet: if yours disagrees with dotnet build, dotnet build is right.

Next