Zig Comptime: Compile-Time Execution Instead of Separate Macros

You want a lookup table computed once, a constant validated before the program ever runs, or one function that works for every numeric type — without maintaining a separate macro language. Zig's answer is comptime: a single execution mode that runs ordinary Zig code during compilation and bakes the results into the binary as constants or specialized functions.

The practical consequence is that there is no preprocessor, no template syntax, and no macro crate. There is just Zig code the compiler is allowed to run early.

Comptime is an execution mode, not a preprocessor

Functions and blocks marked comptime execute while the compiler builds your program. They can loop, build fixed-size buffers, call other comptime functions, and inspect types through reflection. Their results become compile-time constants, types, or per-type specializations. Nothing is textually substituted, so errors point at real expressions rather than at an expanded macro.

Marking a function parameter comptime is a contract: the argument must be known at compile time. Passing a runtime value where a comptime parameter is required is a compile error, which is exactly what you want for configuration validation and format-string parsing.

Generics are just comptime type parameters

Generic programming in Zig is a function whose first parameter is a type.

fn max(comptime T: type, a: T, b: T) T {
    return if (a > b) a else b;
}

pub fn main() void {
    _ = max(i32, 1, 2);
    _ = max(f32, 1.5, 2.5);
}

The compiler specializes max for each concrete T at the call site — monomorphization, the same idea as C++ templates but without a separate template grammar. The standard library leans on this everywhere: std.ArrayList is generic over element type and allocator, and std.fmt.format parses its format string at compile time.

A worked example: a table computed at compile time

The following file computes a Fibonacci table during compilation and asserts a known value. Save it as fib.zig in a writable directory and run zig build-exe fib.zig from that directory. No special permissions are needed beyond write access to the output directory.

const std = @import("std");

fn fibTable(comptime n: usize) [n]u64 {
    var t: [n]u64 = undefined;
    if (n > 0) t[0] = 0;
    if (n > 1) t[1] = 1;
    var i: usize = 2;
    while (i < n) : (i += 1) t[i] = t[i - 1] + t[i - 2];
    return t;
}

const table = comptime fibTable(20);

comptime {
    std.debug.assert(table[10] == 55);
}

pub fn main() void {
    var sum: u64 = 0;
    for (table) |v| sum += v;
    std.debug.print("{d}\n", .{sum});
}

comptime fibTable(20) forces the call into compile-time evaluation; the resulting array is a constant. The comptime block is a compile-time assertion: if the table were wrong, the build would fail instead of the program misbehaving at runtime. Summing the array in main gives the compiler a reason to materialize the data rather than folding a single element into an immediate.

To check the result, run zig version first so you know which release you are testing, then inspect the binary. zig objdump -d fib (or objdump -s -j .rodata fib with a system binutils) shows emitted code and read-only data. Look for the table or for folded constants. Caveat: an optimizing backend is free to inline and eliminate symbols, so not finding a named table is not proof that comptime did not run — the compile-time assertion and the printed sum are the stronger checks.

Limits, version drift, and when to stop

• Evaluation quota. The compiler caps compile-time work to prevent hangs. Exceeding the cap produces an error naming @setEvalBranchQuota. The exact default has changed across releases, so read the number from the error message in your installed version rather than trusting a memorized figure. Raising the quota permanently usually means the computation should be simplified or moved to build time.
• No runtime state. Comptime code cannot capture runtime variables, so you cannot lift arbitrary runtime logic into compilation.
• Verbose errors. Failures deep inside generic instantiation produce long traces. Narrow the failing call before reading the whole message.
• Reflection is version-sensitive. @typeInfo tag names have changed between Zig releases; std.meta offers more stable helpers. Check the language reference for your version before relying on raw tags.
• C interop needs a C toolchain. @cImport and @cInclude evaluate C headers at compile time, so cross-compiling to a bare-metal target without a matching C compiler can fail.

Actionable summary: use comptime for per-type specialization, format-string parsing, and validating constants that must be correct before the program starts. Keep comptime functions pure and side-effect free, prefer std.meta over raw reflection, and treat a quota error as a design signal. Verify behavior on your own toolchain with zig version plus a small compile-time assertion, since these details move between releases.