Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 37 ยท Getting Started

Compiler Commands and Build Modes

Learn the everyday zig commands (run, build-exe, test, fmt, init, build, cc), the four build modes Debug, ReleaseSafe, ReleaseFast and ReleaseSmall, and what each one checks.

The zig program is more than a compiler. It is a build system, a test runner, a code formatter, a C compiler and a cross-compiler in one binary. You do not need make, CMake or a separate package manager. This lesson tours the commands you will type every day and explains the build modes, which decide whether your program is fast, small, or full of safety checks.

The everyday commands

Command What it does
zig run main.zig Compile and run immediately (output goes to the cache)
zig build-exe main.zig Produce an executable file named main (main.exe on Windows)
zig build-lib / zig build-obj Produce a library or an object file
zig test main.zig Compile and run all test blocks
zig fmt src/ Format files or folders in place
zig fmt --check src/ Fail if files are not formatted (good for CI)
zig init Create a starter project with build.zig
zig build Run the project's build.zig
zig build run / zig build test Run the steps the project defines
zig cc / zig c++ Use Zig as a drop-in C or C++ compiler
zig translate-c Turn a C file into Zig source
zig env, zig targets, zig version Information about the toolchain

You can pass program arguments after --:

TEXT
zig run main.zig -- first second

A program can read them with std.process.args, which later lessons use.

Build modes

Zig has four optimize modes. You choose one with -O:

Mode Flag Runtime safety checks Speed Binary size Use it for
Debug (default) on slowest large development, tests
ReleaseSafe -O ReleaseSafe on fast medium production when correctness matters
ReleaseFast -O ReleaseFast off fastest medium performance-critical code
ReleaseSmall -O ReleaseSmall off fast smallest embedded, WebAssembly
TEXT
zig build-exe main.zig -O ReleaseSafe
zig run main.zig -O ReleaseFast

What are runtime safety checks?

In Debug and ReleaseSafe, Zig inserts checks that turn silent bugs into panics, which are immediate crashes with a message and a stack trace. The checks include:

  • integer overflow (255 + 1 for a u8)
  • array and slice index out of bounds
  • unwrapping null with .?
  • invalid enum or union access
  • reaching unreachable
  • division by zero
  • unaligned or null pointer casts

In ReleaseFast and ReleaseSmall these checks are removed and the same mistakes become undefined behavior, exactly like in C: the program may crash, produce wrong results or appear to work. That is why many teams ship ReleaseSafe by default, and only switch hot code to ReleaseFast after measuring.

Always develop and test in Debug. A program that "works" in ReleaseFast may be hiding an overflow or out-of-bounds access that Debug would have caught in the first test run.

A panic looks like this (the exact text varies by version):

TEXT
thread 1234 panic: integer overflow
main.zig:6:15: 0x1043e5 in main (main)
    count += 1;
              ^

Choosing a build mode

Debug Safe and slow. Develop here
ReleaseSafe Fast, keeps checks. Safe default to ship
ReleaseFast Fastest. Checks removed
ReleaseSmall Tiny binaries for embedded and wasm

Same source code, four trade-offs.

1 / 2

Targets and cross-compilation

-target picks the CPU, OS and ABI to build for. The default is your own machine.

TEXT
zig build-exe main.zig -target x86_64-linux-gnu
zig build-exe main.zig -target aarch64-macos
zig build-exe main.zig -target wasm32-wasi
zig build-exe main.zig -target x86_64-windows -O ReleaseSmall

Your code can ask which target it is compiled for through @import("builtin"):

ZIG
const std = @import("std");
const builtin = @import("builtin");

pub fn main() void {
    std.debug.print("os: {s}, cpu: {s}\n", .{
        @tagName(builtin.os.tag),
        @tagName(builtin.cpu.arch),
    });
}

On a 64-bit Linux PC this prints os: linux, cpu: x86_64. Because builtin.os.tag is known at compile time, an if on it removes the dead branch from the binary entirely.

The cache

Zig stores compiled artifacts in .zig-cache inside your project and a global cache in your home directory. Compilation is incremental: unchanged code is not rebuilt. Add .zig-cache/ and zig-out/ to .gitignore. In projects, zig build writes results to zig-out/.

Reading a compile error

Zig errors point at the exact line and often show a note about how to fix it:

TEXT
main.zig:4:20: error: expected type 'u8', found 'comptime_int'
    const x: u8 = 300;
                  ^~~
note: type 'u8' cannot represent integer value '300'

Read the first line, then the caret, then the notes. Because analysis is lazy, fixing one error can reveal the next one.

A stand-in you can run

Safety checks are the main difference between Debug and ReleaseFast. This Rust stand-in shows the same trade-off in software: checked arithmetic reports overflow, wrapping arithmetic hides it.

Rust Stand-in (Rust): overflow detected or ignored

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

And the C side of the same story: C does no checking at all, so an out-of-bounds read is simply undefined behavior, which is why Zig's checked modes are valuable.

C Stand-in (C): doing the check yourself

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command compiles and runs a Zig file in one step?

    zig run builds into the cache and runs the program.
  2. 2. Which build mode removes runtime safety checks and aims for maximum speed?

    ReleaseFast removes the checks; ReleaseSmall also removes them but optimizes for size.
  3. 3. What happens on integer overflow in a Debug build?

    Debug and ReleaseSafe check overflow and panic; in release-fast modes it is undefined behavior.
  4. 4. How do you cross-compile for 64-bit Windows?

    Zig bundles what it needs to build for many targets without extra installs.
  5. 5. Which command checks formatting without changing files?

    zig fmt --check exits with an error if files would change, which suits CI.

Summary

  • zig run, build-exe, test, fmt, init and build cover daily work; zig cc makes Zig a C compiler.
  • Four build modes: Debug, ReleaseSafe, ReleaseFast, ReleaseSmall.
  • Safe modes panic on overflow, bounds errors and null unwraps; fast modes make them undefined behavior.
  • -target cross-compiles, and @import("builtin") reveals the target at compile time.
  • Add .zig-cache/ and zig-out/ to .gitignore.

Next: Variables and Constants