Appendix F. Build Modes Reference

When Zig compiles a program, it can build the program in different modes.

A build mode changes things like:

• optimization level
• runtime safety checks
• debug information
• binary size
• execution speed

You choose the mode depending on what you are doing.

During development, you usually want safety and debugging support.

For production releases, you usually want speed or smaller binaries.

F.1 The Four Main Build Modes

Zig has four standard optimization modes:

These modes affect both performance and safety behavior.

F.2 Debug Mode

Debug mode is the default during development.

Example:

zig build-exe main.zig

Or explicitly:

zig build-exe main.zig -ODebug

Characteristics:

Debug mode catches many mistakes:

• integer overflow
• out-of-bounds indexing
• invalid unwraps
• some undefined behavior
• unreachable code reached

Example:

const x: u8 = 255;
const y = x + 1;

In Debug mode, this triggers overflow checking.

Debug mode is the best choice while learning Zig.

F.3 ReleaseSafe Mode

ReleaseSafe keeps safety checks but adds optimization.

Example:

zig build-exe main.zig -OReleaseSafe

Characteristics:

This mode is useful when:

• correctness matters
• performance matters
• you still want runtime checks

ReleaseSafe is often a good production default for many applications.

F.4 ReleaseFast Mode

ReleaseFast prioritizes speed.

Example:

zig build-exe main.zig -OReleaseFast

Characteristics:

This mode is dangerous if the program still contains bugs.

Example:

const x: u8 = 255;
const y = x + 1;

In ReleaseFast, overflow checking may be removed.

If the program has memory bugs or invalid assumptions, behavior may become unpredictable.

Use ReleaseFast only after testing carefully.

F.5 ReleaseSmall Mode

ReleaseSmall optimizes for binary size.

Example:

zig build-exe main.zig -OReleaseSmall

Characteristics:

Useful for:

• embedded systems
• tiny utilities
• WebAssembly
• distribution-sensitive software

F.6 Safety Checks

Different modes enable different runtime checks.

Common checks include:

Debug and ReleaseSafe keep most checks enabled.

ReleaseFast and ReleaseSmall disable many checks for performance.

F.7 Example: Bounds Checking

Example:

const nums = [_]i32{ 1, 2, 3 };

pub fn main() void {
    const x = nums[10];
    _ = x;
}

In Debug mode:

• Zig detects invalid indexing
• program stops safely

In ReleaseFast:

• check may disappear
• behavior may become undefined

This is why development should happen in safe modes.

F.8 Optimization Levels

Optimization changes generated machine code.

The compiler may:

• inline functions
• remove unused code
• reorder instructions
• eliminate allocations
• vectorize loops
• simplify calculations

Optimized code runs faster but becomes harder to debug.

Example problem:

var x = compute();

In optimized builds, x may disappear entirely if unused.

Debuggers may show confusing behavior because the optimizer changed the program layout.

F.9 Debug Symbols

Debug symbols help debuggers understand the program.

They contain information about:

• variable names
• source locations
• stack traces
• function boundaries

Debug mode includes more symbol information.

Release builds usually reduce or strip it.

F.10 Stack Traces

Safe modes produce better stack traces.

Example:

fn crash() void {
    unreachable;
}

pub fn main() void {
    crash();
}

Debug output may show:

• function names
• file names
• line numbers

This makes debugging much easier.

F.11 Undefined Behavior

Undefined behavior means the language no longer guarantees correct behavior.

Examples:

In safe modes, Zig often detects these problems.

In fast modes, they may silently corrupt the program.

F.12 Build Modes in build.zig

Most real Zig projects use build.zig.

Example:

const optimize = b.standardOptimizeOption(.{});

Then:

.root_module.optimize = optimize;

Users choose the mode:

zig build -Doptimize=ReleaseFast

Common values:

F.13 Common Development Workflow

Typical workflow:

F.14 Debugging Optimized Code

Optimized code is harder to debug.

Problems include:

• variables disappear
• stack frames change
• functions inline automatically
• instruction order changes

If debugging becomes confusing:

1. switch back to Debug mode
2. reproduce the problem
3. fix the bug
4. return to optimized builds later

F.15 Assertions and Build Modes

Assertions are checks inside your code.

Example:

std.debug.assert(x > 0);

In safe modes:

• failed assertion stops the program

In fast modes:

• some assertions may disappear

Do not rely on assertions for critical runtime validation in release builds unless you understand the mode behavior.

F.16 Safety vs Performance

This is one of Zig’s core tradeoffs.

Debug mode favors correctness.

ReleaseFast favors performance.

Zig lets you choose explicitly.

The language does not assume:

• safety always matters more
• performance always matters more

Instead, you control the balance.

F.17 Why ReleaseSafe Exists

Many languages force a difficult choice:

Zig’s ReleaseSafe mode is a middle ground.

You get:

• optimization
• many safety checks
• reasonable speed

This is valuable for servers, tooling, and infrastructure software where correctness matters.

F.18 Measuring Performance Correctly

Never benchmark Debug builds.

Debug mode intentionally disables many optimizations.

Bad benchmark:

zig run benchmark.zig

Better:

zig build-exe benchmark.zig -OReleaseFast
./benchmark

Benchmark optimized builds only.

F.19 Binary Size Differences

Different modes affect executable size.

Typical pattern:

Exact results depend on:

• platform
• linker
• libraries
• debug info
• optimization opportunities

F.20 Safety Checks Are Not Garbage Collection

A beginner confusion:

Runtime safety checks are not the same as garbage collection.

Zig safe modes detect invalid operations.

They do not automatically manage memory.

You still must:

• free memory
• manage ownership
• avoid dangling pointers

F.21 Build Modes and Panics

When safety checks fail, Zig usually panics.

Examples:

• overflow
• invalid unwrap
• unreachable reached
• out-of-bounds access

Debug builds provide better panic diagnostics.

Release builds may produce less information.

F.22 Cross Compilation and Modes

Build modes work with cross compilation too.

Example:

zig build-exe main.zig -target x86_64-windows -OReleaseSmall

This builds:

• Windows executable
• optimized for small size

Cross-compilation and optimization are independent settings.

F.23 LTO and Advanced Optimization

Some advanced optimization features include:

Zig and LLVM perform many optimizations automatically in release modes.

F.24 Which Mode Should Beginners Use?

Use Debug mode almost all the time at first.

zig run main.zig

Or:

zig build

Only switch to release modes when:

• benchmarking
• packaging
• testing production behavior
• reducing binary size

Correctness first. Optimization later.

F.25 Quick Reference Table

F.26 Practical Rule

A useful rule for Zig projects:

Build modes are not just compiler switches. They are part of how Zig balances performance, safety, and control.