Zig

Zig book notes exported from ChatGPT, organized into 24 chapters.

Appendix

Zig is a programming language for writing fast, small, reliable programs.

Part 24. Reading and Contributing to Zig

The Zig compiler is not only a compiler for the Zig language. It is also the center of the Zig toolchain.

Part 23. Real Projects

In this project, we will build a small command-line calculator.

Part 22. Cross-Platform Development

Windows is one of Zig’s main supported platforms. You can write Zig programs on Windows, build Windows executables, call Windows system APIs, link with C libraries, and...

Part 21. Advanced Zig

Zig has a formatting system built into the standard library. You have already used it many times through std.debug.print.

Part 20. Performance and Optimization

Performance is one of the main reasons people choose Zig.

Part 19. Systems Programming

A memory mapped file is a file that the operating system places into your program's address space.

Part 18. Concurrency and Async

A thread is a separate path of execution inside one program.

Part 17. Interfacing with C

Zig works unusually well with C because it treats C as a first-class part of systems programming.

Important Builtins in Zig 1.16

This chapter covered the builtins you will see most often as a beginner.

Part 16. Testing and Debugging

Zig has a built-in test system. You do not need a separate testing library to start writing tests.

`@embedFile`

@embedFile reads a file at compile time and embeds its bytes into the final program.

Logging

Logging means recording what a program is doing.

Part 15. Build System and Tooling

Zig has a built-in build system.

`@compileError`

@compileError stops compilation with a custom error message.

Networking APIs

Networking means communicating with another program through a network.

Part 14. The Standard Library

std is Zig’s standard library.

`@panic`

@panic stops the program immediately with a message.

HTTP Client

An HTTP client is code that sends a request to a web server and reads the response.

Part 13. Collections and Data Structures

An ArrayList is one of the most important data structures in Zig.

`@floatCast`

@floatCast converts one floating-point value to another floating-point type.

JSON Support

JSON is a text format for storing structured data.

Conclusion

You now know the core ideas behind Zig.

Part 12. Allocators and Memory Management

Memory is one of the most important ideas in Zig.

`@truncate`

@truncate converts an integer to a smaller integer type by keeping only the low bits.

Compression

Compression means making data smaller.

Build System Changes in Zig 0.16

Zig changes quickly before 1.0. That includes the build system.

Appendix J. Migrating Between Zig Versions

Zig is still before 1.0, so the language and standard library can change between releases. Code written for one Zig version may not compile on another version without edits.

Appendix A. Zig 1.16 New Features

Zig has not reached 1.0 yet. The current release line discussed in this book is Zig 0.16, not Zig 1.16.

Part 11. Zig Builtins

Zig has special built-in functions whose names start with @.

Appendix A. Zig 1.16 New Features

As of the current public Zig release line, the version is Zig 0.16, not Zig 1.16. Zig has not reached 1.0 yet. In this appendix, read “Zig 1.16” as “Zig 0.16” unless...

When Not to Use `comptime`

comptime is one of Zig’s strongest features, but it should not be used everywhere.

`@intCast`

@intCast converts one integer value to another integer type.

Building Allocation-Friendly APIs

An allocation-friendly API makes memory behavior clear to the caller.

Appendix I. Zig Coding Style Guide

Zig code should be explicit, simple, and easy to inspect. The goal is not cleverness. The goal is code that another programmer can read, verify, and maintain.

Start with the Operations

A data structure is never just a container.

Process Management

A process is a running program.

Packaging Applications

Packaging means preparing your program so another person can download it, install it, and run it.

Benchmarking Code

Benchmarking measures how fast code runs.

Wrapping Existing Libraries

Wrapping a C library means building a Zig layer around it.

Writing a Small Shell

A shell is a program that reads commands and runs other programs.

High Performance Concurrent Design

High performance concurrent design means using several threads or tasks without making the program slower, more fragile, or harder to reason about.

Case Study 1: Reusing a Temporary Buffer

Performance ideas become clearer when you see them inside real code.

Following Zig Development

Zig changes quickly because it is still moving toward 1.0.

Understanding Zig IR

IR means intermediate representation.

Build a Mini Git Clone

Git stores snapshots of files.

Part 10. Compile-Time Programming

comptime means “compile time.”

Metaprogramming Patterns

Metaprogramming means writing code that helps create, inspect, or specialize other code.

`@memcpy`

@memcpy copies bytes from one memory region to another.

Lifetime Management

Memory lifetime means:

Appendix H. Useful Open Source Zig Projects

This appendix lists useful Zig projects to read after you know the basics.

Memory Debugging

Memory debugging means finding mistakes in how a program uses memory.

Contributing to Zig

Contributing to Zig means helping the language, compiler, standard library, documentation, tests, or tooling improve.

Start with the Rule

A collection is a type that stores many values.

Environment Variables

An environment variable is a named value provided to a program by the operating system.

Installing Binaries

A build does not only compile files. It can also install the results into a predictable output directory.

Working with Headers

C headers are the bridge between Zig and C.

Writing a CLI Tool

A CLI tool is a command-line program.

The Basic Idea

An abstraction is a way to hide detail behind a simpler interface.

Self-Hosted Zig Compiler

A self-hosted compiler is a compiler written in the language it compiles.

Packaging Cross-Platform Apps

Packaging means preparing your program so other people can download it, install it, run it, and trust what they are running.

Data Races

A data race happens when two threads access the same memory at the same time, at least one access writes, and there is no proper synchronization.

Build a Simple Game Engine

A game engine is a program structure for running interactive simulations.

Memory Leak Detection

A memory leak happens when a program allocates memory and then loses the ability to free it.

Appendix G. C Interop Reference

Zig is designed to work closely with C. You can call C from Zig, call Zig from C, compile C code with Zig, and link Zig programs against existing C libraries.

Why Trees Matter

A tree is a collection made of nodes.

Using GDB and LLDB

GDB and LLDB are debuggers.

Open Issues and RFCs

A programming language is never only its syntax.

Running Tests

Zig has built-in support for tests.

ABI Compatibility

ABI means Application Binary Interface.

Writing a TCP Server

A TCP server is a program that waits for clients to connect.

Benchmark the Right Thing

Benchmarking means measuring how fast code runs.

Writing a Compiler in Zig

A compiler translates one form of code into another form.

Handling Platform Differences

A cross-platform Zig program should not pretend that every operating system behaves the same way. Windows, Linux, macOS, WebAssembly, and embedded targets have different...

Random Number Generation

Random numbers are used when a program needs variation.

Channels and Queues

A queue is a data structure for passing work from one part of a program to another.

Build a Bytecode VM

A bytecode VM is a small machine inside your program.

Appendix F. Build Modes Reference

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

The Core Idea

A ring buffer is a fixed-size queue that reuses its storage.

Assertions

An assertion is a check that must be true while the program runs.

LLVM Integration

LLVM is a compiler infrastructure project.

Release Modes

Zig can build the same program in different optimization modes.

Exporting Zig to C

Zig can call C, but C can also call Zig.

Network Protocols

A network protocol is a rulebook for how programs talk over a network.

Why Branch Prediction Exists

Branch prediction is a CPU optimization.

Writing a Virtual Machine

A virtual machine is a program that runs another program.

Portable APIs

A portable API is an interface that works across more than one platform.

Time and Timers

Programs often need to work with time.

Event Loops

An event loop is code that waits for events, then runs the right piece of work for each event.

Build a Programming Language Lexer

A lexer is the first stage of many programming language tools.

Why Bit Sets Matter

A bit set is a compact collection of yes-or-no values.

Stack Traces

A stack trace shows how your program reached a failure.

Code Generation

Code generation is the compiler stage that turns analyzed program meaning into target code.

Static and Dynamic Linking

Linking is the step where the compiler connects your program with the code it depends on.

Building Mixed Zig and C Projects

A mixed Zig and C project contains source files from both languages.

Endianness

Endianness means the order used to store the bytes of a multi-byte value.

Small Values Are Fine to Copy

Copying data is sometimes necessary, but unnecessary copying is one of the easiest ways to waste time and memory.

Writing a Parser

A parser reads text and turns it into structure.

Cross-Target Debugging

Cross-target debugging means debugging a program built for a different machine, operating system, or CPU architecture than the one you are sitting at.

Parsing Numbers and Text

Parsing means turning text into data.

Await and Suspension

await means: wait until an asynchronous operation has finished, then continue with its result.

Build a Small Database

A database stores data so it can be saved, searched, updated, and loaded again later.

Cross Compilation

Cross compilation means building a program for a different machine than the one you are using.

Linking C Libraries

Importing a C header lets Zig understand a C API. Linking gives the final program the actual compiled code.

Binary File Formats

A binary file format stores data as bytes with a specific structure.

Why Allocations Cost Time

Allocations are one of the most common causes of slow programs.

Writing a Game Engine Core

A game engine core is the small central layer that runs the game.

ARM and Embedded Targets

ARM is a CPU architecture family used in phones, tablets, laptops, routers, Raspberry Pi boards, microcontrollers, servers, and many embedded devices. When you write Zig for...

Formatting and Printing

Formatting means turning values into text.

Async Functions

Async code lets a program start an operation now and receive the result later.

Build a Memory Allocator

A memory allocator is code that gives memory to the rest of a program.

Directories and Paths

A file lives inside a directory.

Condition Variables

A condition variable lets one thread sleep until another thread says that something has changed.

Build a Thread Pool

A thread pool is a group of worker threads that wait for jobs.

Volatile and Atomic Memory

Most memory in Zig is ordinary memory.

Part 6. Pointers and Memory

Memory is where a program keeps its data while it runs.

Memory Safety in Zig

Memory safety means using memory only while it is valid, only through the right type, and only inside the allowed range.

Dangling Pointers

A dangling pointer is a pointer that refers to memory that is no longer valid.

Efficient Text Processing

Efficient text processing means working with text without doing unnecessary allocation, copying, or decoding.

Data-Oriented Design

Data-oriented design means you organize a program around the data it processes.

Stack vs Heap

Zig programs use memory in different places. The two most important places are the stack and the heap.

Building Dynamic Strings

A dynamic string is text whose length is not fixed ahead of time.

Modeling State Machines

A state machine is a simple way to describe a program that moves between fixed states.

Type Reflection Basics

Type reflection means asking questions about a type while Zig is compiling the program.

Part 9. Optionals and Advanced Types

An optional type is a type that can hold either a value or no value.

Sentinel-Terminated Arrays

A sentinel-terminated array is an array with a special value at the end.

UTF-8 Processing

Zig string data is usually stored as UTF-8 bytes.

Union Safety

A union stores one active field at a time.

Type Coercion

Type coercion means Zig converts a value from one type to another when the conversion is safe and well-defined.

Static Dispatch

Static dispatch means the compiler decides which code to call before the program runs.

`@bitCast`

@bitCast reinterprets the bits of one value as another type.

Part 8. Structs, Enums, and Unions

A struct is a type that groups several values together.

Alignment

Alignment is a rule about where a value may be placed in memory.

Mutable Strings

Zig does not have a separate built-in mutable String type.

Tagged Unions

A tagged union is a type that can store one value from several possible shapes.

Error Union Internals

An error union is a value that can contain either:

Building Generic Data Structures

A generic data structure is a data structure that works with more than one element type.

`@ptrCast`

@ptrCast converts one pointer type into another pointer type.

Allocation Failure Handling

Allocation can fail.

Part 7. Arrays, Slices, and Strings

An array is a group of values stored next to each other.

Pointer Arithmetic

Pointer arithmetic means moving a pointer forward or backward through memory.

String Literals

A string literal is text written directly in your source code.

Enums

An enum is a type whose value must be one item from a fixed list.

`anytype`

anytype means the function parameter can accept many different types.

Reflection with `@typeInfo`

Reflection means inspecting a type as data.

`@typeInfo`

@typeInfo asks the compiler for structured information about a type.

Custom Allocators

A custom allocator is an allocator you design for a specific memory policy.

Appendix E. Memory Safety Checklist

Zig gives you direct control over memory. That control is useful, but it also means you must follow clear rules.

Slice Lifetimes

A slice is a view into memory.

Optional Pointers

An optional pointer is a pointer that may have no value.

Anonymous Structs

An anonymous struct is a struct type without a name.

Opaque Types

An opaque type is a type whose internal structure is hidden.

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.

`@Type`

@Type builds a type from compile-time type information.

Page Allocator

The page allocator asks the operating system for memory directly.

The Basic Difference

Queues and stacks are two simple ways to organize a collection of items.

Appendix D. Important Standard Library APIs

Zig’s standard library is imported with:

Debug Builds

A debug build is a build made for finding mistakes.

Semantic Analysis

Semantic analysis is the compiler stage that checks what a program means.

Part 5. Error Handling

Most programming languages need a way to handle failure.

Slices in Detail

A slice is a view into a sequence of values.

Slices

A slice is a view into a sequence of values.

Packed Structs

A normal Zig struct is designed for ordinary data modeling.

Vectors

A vector is a fixed-size group of values of the same type.

How Parsing Works

Parsing is the part of the compiler that reads source code and turns it into structure.

Compile-Time Loops

A compile-time loop is a loop that runs while Zig is compiling your program.

`@alignOf`

@alignOf asks the Zig compiler for the required memory alignment of a type.

Fixed Buffer Allocator

A fixed buffer allocator gives memory from a buffer you already own.

Fuzz Testing

Fuzz testing means testing a program with many generated inputs.

Using C Structs

A C struct groups several fields into one value.

Why Linked Lists Exist

A linked list is a collection where each item points to the next item.

Appendix C. Common Compiler Errors

One of Zig’s strengths is compiler diagnostics. Zig tries to explain problems precisely instead of silently accepting dangerous behavior.

Terminal Programming

Terminal programming means writing programs that interact with the command line as more than simple text output.

Build Options

A build option is a value passed from the command line into build.zig.

Embedded Development

Embedded development means writing software for small computers inside devices.

Why SIMD Matters

SIMD means Single Instruction, Multiple Data.

WebAssembly

WebAssembly, often shortened to Wasm, is a portable binary instruction format. It lets you compile code once and run it inside different hosts, such as web browsers, servers,...

Part 4. Functions

Functions are reusable blocks of code.

Many Item Pointers

A many item pointer is a pointer that can move across several values of the same type.

Multidimensional Arrays

A multidimensional array is an array whose elements are also arrays.

Default Field Values

A struct field can have a default value.

Understanding Stage2

When people talk about Zig compiler internals, they often mention stage2.

Nullable Pointers

A pointer stores the address of a value in memory.

Inline Branching

Inline branching means Zig chooses a branch during compilation, not during runtime.

`@sizeOf`

@sizeOf asks the Zig compiler how many bytes a type needs in memory.

Table-Driven Tests

A table-driven test checks many input cases with one test loop.

Why StringHashMap Exists

A StringHashMap is a hash map where the key is a string.

Arena Allocator

An arena allocator is an allocator that frees many allocations at once.

Calling C Functions

Calling a C function from Zig has three parts.

Appendix B. Zig Cheat Sheet

const std = @import"std";

Working with the OS

Systems programming means working directly with the operating system.

The Basic Idea

Modern CPUs are fast, but memory is much slower.

Plugin Architectures

A plugin architecture lets a program be extended without rewriting the whole program.

Atomics

An atomic operation is a small operation that can safely happen while several threads are running.

Writing Files

Writing a file means sending bytes from your program to the operating system so they can be stored on disk.

macOS Support

macOS is one of Zig’s main desktop targets. You can use Zig on macOS to write command-line tools, development utilities, servers, libraries, and cross-platform applications.

Adding Dependencies

A Zig project can depend on other Zig packages.

Build a Static File Server

A static file server is a program that reads files from a directory and sends them to a browser over HTTP.

Part 3. Control Flow

Programs need to make choices.

Single Item Pointers

A pointer is a value that stores the address of another value.

Array Literals

An array literal is the syntax you use to write array values directly in source code.

Struct Methods

A struct method is a function that belongs to a struct.

Appendix A. Zig 0.16 New Features

Zig 0.16.0 was released on April 14, 2026. The release contains 8 months of work, with changes from 244 contributors across 1,183 commits. The largest themes are the new I/O...

Optional Unwrapping

Optional unwrapping means taking the value out of an optional.

Compile-Time Variables

In the previous section, you learned that Zig can execute code during compilation.

`@import`

One of the first Zig builtins you will learn is @import.

General Purpose Allocator

The general purpose allocator is Zig’s standard allocator for ordinary heap allocation.

The Basic Idea

A HashMap is a data structure for storing values by key.

Creating Build Steps

A Zig build is made from steps.

Writing Unit Tests

A unit test checks one small piece of code in isolation.

Reading Files

Reading a file means asking the operating system for bytes stored on disk.

`@cImport`

@cImport is Zig’s built-in way to import C declarations from header files.

Mutexes

A mutex is a lock for shared data.

System Calls

A system call is a request from your program to the operating system.

Why Profiling Matters

When a program feels slow, your first job is not optimization.

Reflection Systems

Reflection means a program can inspect information about types while the program is being compiled or running.

Linux Support

Linux is one of the most natural platforms for Zig. Many Zig programs are built, tested, and deployed on Linux because Linux is common in servers, containers, embedded...

Zig Source Tree

When you first open the Zig source code repository, it can feel overwhelming.

Build a JSON Parser

A JSON parser reads JSON text and turns it into data your program can use.

Part 2. Zig Language Fundamentals

A program stores values so it can use them later. In Zig, you store values with two main keywords:

What Is Zig

Zig is a programming language for writing fast, small, reliable programs.

What Is Zig

Zig is a programming language for writing fast, small, reliable programs.

Variables and Constants

A program stores values so it can use them later. In Zig, you store values with two main keywords:

`if` Expressions

Programs need to make choices.

The Structure of a Function

Functions are reusable blocks of code.

Why Zig Has No Exceptions

Most programming languages need a way to handle failure.

Memory Model Basics

Memory is where a program keeps its data while it runs.

Fixed Arrays

An array is a group of values stored next to each other.

Struct Definitions

A struct is a type that groups several values together.

Optional Types

An optional type is a type that can hold either a value or no value.

What Is `comptime`

comptime means “compile time.”

Understanding `@` Builtins

Zig has special built-in functions whose names start with @.

Why Zig Uses Allocators

Memory is one of the most important ideas in Zig.

Importing ArrayList

An ArrayList is one of the most important data structures in Zig.

Tour of `std`

std is Zig’s standard library.

Introduction to `build.zig`

Zig has a built-in build system.

Zig Test Framework

Zig has a built-in test system. You do not need a separate testing library to start writing tests.

Why Zig Works Well with C

Zig works unusually well with C because it treats C as a first-class part of systems programming.

Threads in Zig

A thread is a separate path of execution inside one program.

Memory Mapped Files

A memory mapped file is a file that the operating system places into your program's address space.

What Actually Makes Programs Slow?

Performance is one of the main reasons people choose Zig.

Custom Formatting

Zig has a formatting system built into the standard library. You have already used it many times through std.debug.print.

Windows Support

Windows is one of Zig’s main supported platforms. You can write Zig programs on Windows, build Windows executables, call Windows system APIs, link with C libraries, and...

Build a CLI Calculator

In this project, we will build a small command-line calculator.

Zig Compiler Architecture

The Zig compiler is not only a compiler for the Zig language. It is also the center of the Zig toolchain.

Part 1. Introduction and Setup

Zig is a programming language for writing fast, small, reliable programs.

Reserved Keywords

A keyword is a word that has special meaning in Zig.

Reading Zig Error Messages

Sooner or later, every Zig beginner meets the compiler.

Naming Conventions

Names are part of the program.

Zig Generics Use `comptime`

A generic function is a function that works with many types instead of only one type.

Editors, LSP, and Debuggers

You can write Zig code in any text editor.

Comments and Documentation

Comments are notes for humans who read the code.

Compile Errors as Safety Checks

A compile error means Zig refused to build your program.

What “Exported” Means

An exported function is a function made visible outside the current Zig program.

Panic and Crash Behavior

Errors are for expected failures.

Project Structure

So far, we have used single-file programs.

Strings and UTF-8

A string is text.

Unreachable Code

Some parts of a program should never run.

A Mental Model

A calling convention defines how functions communicate at the machine level.

Custom Error Types

Most Zig programs start with small error sets:

Zig Compiler as a Toolchain

When beginners hear the word “compiler,” they often think of one job:

Zero Values and Initialization

Initialization means giving a value to something when it is created.

Defer and Cleanup

Many programs need to clean something up after using it.

A Simple Function

An inline function is a function where the compiler may place the function’s code directly at the call site instead of performing a normal function call.