builtin - Compiler Built-ins

The builtin namespace contains types and values that are automatically provided by the Zig compiler. These types are used by the language code generation and must be kept in sync with the compiler implementation.

Overview

Import the builtin namespace:

const builtin = @import("builtin");

This namespace is part of the Zig language specification and provides information about the compilation environment, target platform, and compiler backend.

Core Types

Type System

Type

union(enum)

Represents type information at runtime. Used by @typeInfo() to inspect types.Variants:

type - The type type
void - The type void
bool - Boolean type
noreturn - The noreturn type
int: Int - Integer type
float: Float - Floating-point type
pointer: Pointer - Pointer type
array: Array - Array type
@"struct": Struct - Struct type
optional: Optional - Optional type
error_union: ErrorUnion - Error union type
error_set: ErrorSet - Error set type
@"enum": Enum - Enum type
@"union": Union - Union type
@"fn": Fn - Function type
@"opaque": Opaque - Opaque type
vector: Vector - Vector type
And more…

TypeId

type

Tag type for Type union, equivalent to std.meta.Tag(Type).

Stack Traces

StackTrace

struct

Data structure used by Zig language code generation for stack traces.

Show Fields

index

usize

Current index in the instruction_addresses array.

instruction_addresses

[]usize

Array of instruction addresses forming the stack trace.

SourceLocation

struct

Represents a location in source code.

Show Fields

module

[:0]const u8

The name chosen when compiling (not a file path).

file

[:0]const u8

Relative to the root directory of its module.

fn_name

[:0]const u8

Function name.

line

u32

Line number.

column

u32

Column number.

Enumerations

Compilation Modes

OptimizeMode

enum

Optimization level for compilation.Values:

Debug - No optimizations, safety checks enabled
ReleaseSafe - Optimizations enabled, safety checks enabled
ReleaseFast - Optimizations enabled, safety checks disabled
ReleaseSmall - Optimize for small binary size

OutputMode

enum

Output type of compilation.Values:

Exe - Executable
Lib - Library
Obj - Object file

LinkMode

enum

Library linkage mode.Values:

static - Static linking
dynamic - Dynamic linking

Code Model

CodeModel

enum

The code model puts constraints on the location of symbols and the size of code and data.Values:

default
tiny
small
kernel
medium
large
extreme
And more architecture-specific models…

Calling Conventions

CallingConvention

union(enum)

Defines how arguments and return values are passed in function calls.Common variants:

auto - Default Zig calling convention
async - Async function calling convention
naked - No prologue or epilogue
@"inline" - Semantically inlined
c - Default C calling convention (alias)
Platform-specific conventions (x86_64_sysv, aarch64_aapcs, etc.)

Example:

fn myFunction() callconv(.C) void {
    // Uses C calling convention
}

Atomic Operations

AtomicOrder

enum

Memory ordering for atomic operations.Values:

unordered - No ordering constraints
monotonic - Single total order exists
acquire - Acquire semantics
release - Release semantics
acq_rel - Acquire and release
seq_cst - Sequentially consistent

AtomicRmwOp

enum

Atomic read-modify-write operations.Values:

Xchg - Exchange (store operand unmodified)
Add - Add operand to existing value
Sub - Subtract operand from existing value
And - Bitwise AND
Nand - Bitwise NAND
Or - Bitwise OR
Xor - Bitwise XOR
Max - Store maximum
Min - Store minimum

Memory and Linking

AddressSpace

enum(u5)

Memory address spaces for pointers.CPU address spaces:

generic
gs, fs, ss (x86-specific)

GPU address spaces:

global, constant, shared, local
uniform, push_constant, storage_buffer

Architecture-specific:

flash, flash1, … (AVR)
cog, hub, lut (Propeller)

GlobalLinkage

enum(u2)

Symbol linkage type.Values:

internal - Internal linkage
strong - Strong symbol
weak - Weak symbol
link_once - Link once

SymbolVisibility

enum(u2)

Symbol visibility.Values:

default - Default visibility
hidden - Hidden symbol
protected - Protected symbol

Other Enumerations

Signedness

enum(u1)

Integer signedness.Values:

signed
unsigned

Endian

enum

Byte order.Values:

big - Big-endian
little - Little-endian

FloatMode

enum

Floating-point optimization mode.Values:

strict - Strict IEEE 754 compliance
optimized - Allow optimizations

ReduceOp

enum

Vector reduction operations.Values:

And, Or, Xor
Min, Max
Add, Mul

Compiler Information

CompilerBackend

enum(u64)

Identifies which compiler backend is being used.Values:

other (0) - Unknown/unidentified compiler
stage1 (1) - Original C++ compiler (deleted 2022)
stage2_llvm (2) - Self-hosted with LLVM backend
stage2_c (3) - Self-hosted with C backend
stage2_wasm (4) - Self-hosted with WebAssembly backend
stage2_arm (5) - Self-hosted with ARM backend
stage2_x86_64 (6) - Self-hosted with x86_64 backend
stage2_aarch64 (7) - Self-hosted with AArch64 backend
stage2_x86 (8) - Self-hosted with x86 backend
stage2_riscv64 (9) - Self-hosted with RISC-V 64 backend
And more…

This is nonexhaustive to allow alternate Zig implementations.

Options and Configuration

CallModifier

enum

Modifiers for function calls.Values:

auto - Equivalent to normal call syntax
never_tail - Prevent tail call optimization
never_inline - Prevent inlining
no_suspend - Assert function will not suspend
always_tail - Require tail call optimization
always_inline - Require inlining
compile_time - Evaluate at compile-time

BranchHint

enum(u3)

Hints for branch prediction.Values:

none - No hint
likely - Branch likely to be taken
unlikely - Branch unlikely to be taken
cold - Branch very unlikely (can be placed in different memory page)
unpredictable - Difficult to predict (avoid expensive mispredictions)

Example:

@branchHint(.unlikely);
if (rare_condition) {
    // ...
}

PrefetchOptions

struct

Options for @prefetch builtin.

Show Fields

default:".read"

Whether to prefetch for read or write.

.read - Prefetch for reading
.write - Prefetch for writing

locality

default:"3"

Data locality (0-3).

0 - No temporal locality (immediate drop)
3 - High temporal locality (keep in cache)

cache

Cache

default:".data"

Which cache to prefetch to.

.instruction - Instruction cache
.data - Data cache

ExportOptions

struct

Options for @export builtin.

Show Fields

name

[]const u8

required

Symbol name for export.

linkage

GlobalLinkage

default:".strong"

Symbol linkage type.

section

?[]const u8

default:"null"

Section to place symbol in.

visibility

SymbolVisibility

default:".default"

Symbol visibility.

ExternOptions

struct

Options for @extern builtin.

Show Fields

name

[]const u8

required

Symbol name.

library_name

?[]const u8

default:"null"

Library containing the symbol.

linkage

GlobalLinkage

default:".strong"

Symbol linkage.

is_thread_local

bool

default:"false"

Whether symbol is thread-local.

Platform-Specific Types

Variable Argument Lists

VaList

type

Platform-specific va_list type for variable arguments. The actual type varies by architecture:

On x86_64 (non-Windows): VaListX86_64
On AArch64: VaListAarch64
On ARM: VaListArm
On many architectures: *u8 or *anyopaque

Platform-specific structures include:

VaListX86_64
VaListAarch64
VaListArm
VaListPowerPc
VaListS390x
And more…

WASI

WasiExecModel

enum

WASI execution model.Values:

command - Command-line program
reactor - Library/service

UnwindTables

enum

Unwind table generation mode.Values:

none - No unwind tables
sync - Synchronous unwind tables
async - Asynchronous unwind tables

Testing

TestFn

struct

Represents a test function. Used by the Zig test runner.

Show Fields

name

[]const u8

Name of the test.

func

*const fn() anyerror!void

Test function pointer.

Panic Handling

panic

namespace

Namespace used by the Zig compiler to emit various kinds of safety panics.Can be overridden by making a public panic namespace in the root source file:

pub const panic = struct {
    pub fn sentinel_mismatch(ptr: [*:0]const u8, expected: u8, actual: u8) noreturn {
        // Custom panic handler
    }
    // ... other panic functions
};

Assembly

assembly

module

Architecture-specific assembly utilities and register definitions.Location: lib/std/builtin/assembly.zig

Core

Data Structures

Memory

System

Utilities

builtin - Compiler Built-ins

Overview

Core Types

Type System

Stack Traces

Enumerations

Compilation Modes

Code Model

Calling Conventions

Atomic Operations

Memory and Linking

Other Enumerations

Compiler Information

Options and Configuration

Platform-Specific Types

Variable Argument Lists

WASI

Testing

Panic Handling

Assembly

See Also

Build docs developers (and LLMs) love

Core

Data Structures

Memory

System

Utilities

​Overview

​Core Types

​Type System

​Stack Traces

​Enumerations

​Compilation Modes

​Code Model

​Calling Conventions

​Atomic Operations

​Memory and Linking

​Other Enumerations

​Compiler Information

​Options and Configuration

​Platform-Specific Types

​Variable Argument Lists

​WASI

​Testing

​Panic Handling

​Assembly

​See Also

Build docs developers (and LLMs) love

Overview

Core Types

Type System

Stack Traces

Enumerations

Compilation Modes

Code Model

Calling Conventions

Atomic Operations

Memory and Linking

Other Enumerations

Compiler Information

Options and Configuration

Platform-Specific Types

Variable Argument Lists

WASI

Testing

Panic Handling

Assembly

See Also