Generating Static Data with Zig's Compile‑Time Function Execution

Why CTFE matters

Zig's comptime keyword lets you run ordinary functions while the program is being compiled. The result becomes a compile‑time constant that the compiler inlines directly into the generated binary. This eliminates runtime work for data that never changes — lookup tables, configuration constants, or generated code — and catches errors early because the same type‑checking and error‑union logic applies at compile time.

How CTFE works

When a function is marked comptime, the compiler evaluates it during the compilation phase. The function must be pure: no I/O, no access to runtime globals, and no calls to functions that are not themselves comptime-safe. The compiler tracks a recursion depth limit (default 1000) and a memory budget; exceeding either produces a compilation error rather than a runtime crash.

Worked example: prime lookup table

The following program builds an array of all prime numbers up to a given limit at compile time and then prints the table at runtime.

// primes.zig
const std = @import("std");

// Compute primes up to `max` at compile time.
comptime fn genPrimes(max: u32) [max]u32 {
    var primes: [max]u32 = undefined;
    var count: usize = 0;
    var candidate: u32 = 2;
    while (candidate <= max) : (candidate += 1) {
        var isPrime = true;
        for (primes[0..count]) |p| {
            if (candidate % p == 0) {
                isPrime = false;
                break;
            }
        }
        if (isPrime) {
            primes[count] = candidate;
            count += 1;
        }
    }
    // Trim the array to the actual number of primes.
    return primes[0..count];
}

pub fn main() !void {
    // The table is a compile‑time constant; its length is known to the compiler.
    const primeTable = genPrimes(100);
    const stdout = std.io.getStdOut().writer();
    for (primeTable) |p| {
        try stdout.print("{d} ", .{p});
    }
    try stdout.print("\n", .{});
}

Save the file as primes.zig and compile it:

$ zig build-exe primes.zig
$ ./primes
2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71 73 79 83 89 97 

Where to run: any terminal with Zig 0.12+ installed. No special permissions are required beyond write access to the current directory for the executable. Expected check: the program prints the primes up to 100. Risk: increasing max to a very large value (e.g., 10⁶) can exceed the compiler's memory budget and cause the build to fail.

Limits and common mistakes

• Recursion depth: The default limit is 1000 calls. Deeply recursive algorithms (e.g., naive Fibonacci) will hit this ceiling. Use iterative loops or increase the limit with -fcomptime-recursion-limit=N if necessary.
• Memory consumption: Generating huge arrays (hundreds of megabytes) can exhaust the compiler's heap, leading to an out‑of‑memory error during compilation. Profile with zig build-exe --verbose to see memory usage.
• Error unions: Using anyerror in a comptime function hides the concrete error at compile time. Handle errors explicitly (e.g., !u32) so the compiler can report the exact failure.
• Runtime‑only APIs: Calls to std.fs, std.net, or any function that performs I/O are rejected. Keep comptime functions pure.

Verifying the result

After a successful build, run the executable and confirm the output matches the expected static data. For the prime example, the printed list should end with 97. If you change max and recompile, the new table appears without any runtime computation. This confirms that the data was embedded at compile time.

Quick checklist for CTFE usage

1. Mark the function comptime and ensure it only calls other comptime-safe functions.
2. Keep the generated data size reasonable for the target binary.
3. Test with a small limit first, then scale up while watching compiler diagnostics.
4. Run the resulting binary to verify the embedded constants are correct.