Generating Code at Compile Time

Generating code at compile time means using Zig code to create specialized program behavior before the final executable is built.

This does not mean Zig writes a new .zig file for you.

It means the compiler executes compile-time logic and uses the result to build the final program.

In Zig, compile-time code generation usually comes from:

The important point is simple: Zig uses normal Zig code for this.

Code Generation Without Text Generation

Some languages generate code by producing text.

For example, a tool might write a file containing source code, then compile that file.

Zig usually avoids that pattern.

Instead of generating text, Zig generates program structure directly.

Example:

fn makePair(comptime T: type) type {
    return struct {
        first: T,
        second: T,
    };
}

This function returns a type.

Use it like this:

const IntPair = makePair(i32);

const value = IntPair{
    .first = 10,
    .second = 20,
};

The compiler builds a struct type whose fields both use i32.

If you call:

const BoolPair = makePair(bool);

The compiler builds a different struct type whose fields both use bool.

There is no string manipulation. There is no separate template file. Zig creates the type directly.

Returning a Type from a Function

This is one of the first major ideas to understand.

In Zig, a function can return a type if the function runs at compile time.

fn Buffer(comptime size: usize) type {
    return struct {
        data: [size]u8,
    };
}

This function takes a compile-time size and returns a new struct type.

const SmallBuffer = Buffer(16);
const LargeBuffer = Buffer(4096);

Now SmallBuffer and LargeBuffer are different types.

SmallBuffer contains:

data: [16]u8

LargeBuffer contains:

data: [4096]u8

The size is baked into the type.

Why This Is Useful

This pattern is useful when the structure of the program depends on compile-time information.

For example, a fixed-size buffer should know its size at compile time:

fn FixedBuffer(comptime size: usize) type {
    return struct {
        data: [size]u8 = undefined,
        len: usize = 0,

        pub fn append(self: *@This(), byte: u8) !void {
            if (self.len >= size) {
                return error.NoSpaceLeft;
            }

            self.data[self.len] = byte;
            self.len += 1;
        }
    };
}

Usage:

const Buffer32 = FixedBuffer(32);

pub fn main() !void {
    var buffer = Buffer32{};

    try buffer.append('A');
    try buffer.append('B');
}

The compiler knows the buffer size. The type itself carries the size.

This gives you reusable code without runtime overhead for storing or checking a dynamic capacity field beyond what you choose to include.

@This()

Inside an anonymous struct, @This() refers to the current type.

In this method:

pub fn append(self: *@This(), byte: u8) !void {
    if (self.len >= size) {
        return error.NoSpaceLeft;
    }

    self.data[self.len] = byte;
    self.len += 1;
}

@This() means “the struct type being created.”

For FixedBuffer(32), @This() means that specific buffer type.

For FixedBuffer(1024), it means a different buffer type.

This is why the same source code can produce different specialized types.

Generating Repeated Code with inline for

inline for can generate repeated code paths.

Suppose you want to check whether a type is one of several allowed integer types:

fn isAllowedInteger(comptime T: type) bool {
    inline for (.{ u8, u16, u32, u64 }) |Allowed| {
        if (T == Allowed) {
            return true;
        }
    }

    return false;
}

The compiler expands the loop for each type.

Conceptually, it becomes:

if (T == u8) return true;
if (T == u16) return true;
if (T == u32) return true;
if (T == u64) return true;
return false;

The loop is source-level convenience. The compiler turns it into direct checks.

Generating Specialized Functions

You can generate a type that contains functions.

fn Counter(comptime T: type) type {
    return struct {
        value: T = 0,

        pub fn increment(self: *@This()) void {
            self.value += 1;
        }

        pub fn get(self: @This()) T {
            return self.value;
        }
    };
}

Usage:

const U8Counter = Counter(u8);
const U64Counter = Counter(u64);

pub fn main() void {
    var small = U8Counter{};
    var large = U64Counter{};

    small.increment();
    large.increment();
}

The compiler creates counter types specialized for u8 and u64.

Each generated type has its own value field and methods.

Generating Code Based on a Flag

Compile-time flags can choose code shape.

fn Logger(comptime enabled: bool) type {
    return struct {
        pub fn log(message: []const u8) void {
            if (enabled) {
                @import("std").debug.print("{s}\n", .{message});
            }
        }
    };
}

Usage:

const DebugLogger = Logger(true);
const SilentLogger = Logger(false);

For Logger(false), the compiler sees that enabled is false. The log body has no runtime work.

This is a common pattern for debug features, optional checks, and static configuration.

Generating APIs from Fields

A more advanced use is inspecting fields of a struct.

For that, Zig uses @typeInfo.

Here is the idea:

fn printFieldNames(comptime T: type) void {
    const info = @typeInfo(T);

    inline for (info.@"struct".fields) |field| {
        @compileLog(field.name);
    }
}

Given a struct type, Zig can inspect its fields during compilation.

Example:

const User = struct {
    id: u64,
    name: []const u8,
};

comptime {
    printFieldNames(User);
}

The compiler can see:

id
name

This is the beginning of reflection-based code generation.

You can use this idea to build serializers, command-line parsers, database mappers, validation systems, and formatters.

Rejecting Invalid Generated Code

When generating code, you should reject bad inputs early.

fn RequireStruct(comptime T: type) void {
    const info = @typeInfo(T);

    if (info != .@"struct") {
        @compileError("expected a struct type");
    }
}

Usage:

const User = struct {
    id: u64,
};

comptime {
    RequireStruct(User);
}

This is accepted.

But this fails:

comptime {
    RequireStruct(u32);
}

The compiler stops with your error message.

This gives library authors a way to produce clear failures instead of confusing type errors.

Code Generation and Runtime Cost

Compile-time generation can remove runtime cost.

For example, this function specializes on a type:

fn zero(comptime T: type) T {
    return switch (T) {
        bool => false,
        u8 => 0,
        u32 => 0,
        else => @compileError("unsupported type"),
    };
}

When you call:

const x = zero(u8);

The compiler knows the branch. The final code does not need to check the type at runtime.

There is no runtime type object, no reflection lookup, and no dynamic dispatch.

The decision happened during compilation.

Code Generation Can Increase Binary Size

Specialization has a cost.

If you generate many versions of the same logic for many types, the final program may become larger.

For example:

const A = Counter(u8);
const B = Counter(u16);
const C = Counter(u32);
const D = Counter(u64);

Each type may produce specialized code.

That can be good for performance, but it can also increase the binary size.

So compile-time generation should be used deliberately.

Do Not Overuse It

Code generation is powerful, but it can make code harder to read if every small decision happens at compile time.

Prefer ordinary runtime code when the decision depends on runtime data.

Use compile-time code generation when the structure of the program depends on information known before the program starts.

Good uses:

Poor uses:

Mental Model

Compile-time code generation in Zig means:

write ordinary Zig code

run part of it during compilation

use the result to shape types, functions, checks, or constants

emit a normal executable

The compiler is not just translating your code. It is also allowed to execute the parts of your code that are marked or required to run at compile time.

That is why Zig’s generic programming feels different from many languages.

You are not using a separate macro system.

You are programming the compiler with Zig itself.