zig

---
name: zig
description: Use when writing low-level systems code that needs C interop, manual memory control, and compile-time metaprogramming without hidden control flow.
source: https://ziglang.org/documentation/master/
generated: 2026-07-02T18:43:56.575Z
category: language
audience: engineers
---

## When to use

- Building systems software, embedded firmware, or game engines needing manual memory control
- Cross-compiling C/C++ projects where Zig acts as a drop-in C compiler and build system
- Replacing C while keeping a tiny runtime and no hidden allocations
- Generating code at compile time with comptime instead of macros or codegen

## Key concepts

### comptime

Code marked comptime runs during compilation; used for generics, type reflection, and constant folding. Types are first-class comptime values, so generic functions take a type parameter.

### Allocators

Zig has no global allocator. Functions that allocate take a std.mem.Allocator parameter, making allocation explicit. Common ones: GeneralPurposeAllocator, ArenaAllocator, std.heap.page_allocator, FixedBufferAllocator.

### Error unions

Functions return error unions like !T. Use try to propagate, catch to handle, and errdefer to clean up on the error path. Errors are values from an inferred or named error set.

### Optionals

?T represents a maybe-null value. Unwrap with if (opt) |val| {} or orelse. No null pointers exist unless a type is explicitly optional, eliminating most null dereferences.

### defer / errdefer

defer runs a statement at scope exit; errdefer runs only when the scope returns an error. Together they give deterministic resource cleanup without RAII.

### build.zig

The build system is itself a Zig program. A build function receives a *std.Build and declares artifacts, steps, modules, and dependencies declaratively.

## API reference

```
zig build
```

Run the build graph defined in build.zig, producing the declared artifacts.

```
zig build
zig build run
zig build test
```

```
zig build-exe <file.zig>
```

Compile a single source file directly into an executable without a build.zig.

```
zig build-exe src/main.zig -O ReleaseFast
```

```
zig run <file.zig>
```

Compile and immediately run a source file, like a script.

```
zig run hello.zig
```

```
zig test <file.zig>
```

Compile and run all test {} blocks in the given file.

```
zig test src/lib.zig
```

```
zig build-exe -target <arch-os-abi>
```

Cross-compile to another target triple; Zig ships libc headers for many targets.

```
zig build-exe main.zig -target aarch64-linux-musl
```

```
zig cc / zig c++
```

Use Zig as a drop-in C/C++ cross-compiler that wraps clang and bundles headers.

```
zig cc -o app app.c -target x86_64-windows-gnu
```

```
const std = @import("std");
```

Import the standard library; @import is a builtin that returns a module's root struct.

```
const std = @import("std");
pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    const allocator = gpa.allocator();
    defer _ = gpa.deinit();
    const list = try allocator.alloc(u8, 16);
    defer allocator.free(list);
    std.debug.print("len={d}\n", .{list.len});
}
```

```
test "name" { ... }
```

Declare a unit test block; assert with std.testing.expect and expectEqual.

```
test "adds" {
    try std.testing.expectEqual(@as(i32, 3), add(1, 2));
}
```

## Gotchas

- There is no default allocator; any std API that allocates requires you to pass an Allocator explicitly.
- comptime-known integer literals are arbitrary precision; coerce with @as or @intCast before runtime use.
- Unused variables and unused function parameters are compile errors; discard with _ = x;.
- defer captures the statement, not values at defer time; the expression evaluates at scope exit.
- Release builds (ReleaseFast/ReleaseSmall) disable safety checks like bounds and overflow; only Debug and ReleaseSafe keep them.
- The language is pre-1.0; std and build.zig APIs change between minor versions, so pin your Zig toolchain.
- Integer overflow traps in safe builds; use wrapping operators like +% or saturating +| when you want wraparound.
- Slices ([]T) carry a length and are distinct from many-item pointers ([*]T); converting requires explicit syntax.

---
Generated by SkillMake from https://ziglang.org/documentation/master/ on 2026-07-02T18:43:56.575Z.
Verify against source before relying on details.

File: ~/.claude/skills/zig/SKILL.md