Introduction to Zig: a project-based book

This project is the official repository for the book "Introduction to Zig: a project-based book" by Pedro Duarte Faria. The book is an open-source, technical introduction to the Zig programming language, designed for both beginners and experienced developers.

It uses a project-based approach (e.g., building a Base64 encoder/decoder, an HTTP Server, and an image filter) to teach:

• Zig syntax and comparisons to C, C++, and Rust.
• Data structures, memory allocators, filesystem, and I/O.
• Optionals and nullability.
• Testing and debugging.
• Error handling as values.
• The Zig build system and C interoperability.
• Parallelism (threads and SIMD).

To build the book manually, you must first install the following dependencies on your machine:

1. Zig compiler
2. R programming language (including knitr and rmarkdown)
3. Quarto publishing system (which uses Pandoc)

Once these are installed, follow these steps:

1. Install R packages

Run the provided R script to install the necessary R packages used throughout the book. Note that on Linux or macOS, this may take time as dependencies are often built from source.

2. Render the book

Use the Quarto CLI to compile the book content into HTML.

# Install R dependencies
Rscript dependencies.R

# Render the book
quarto render

If you prefer a reproducible environment, you can use the Nix Flake declared in the repository. This automatically handles the installation of Zig, R, and Quarto.

1. Run nix develop in the project root to enter a new bash session containing the required environment.
2. Run quarto render within that session to build the book.

nix develop
# Inside the new shell:
quarto render

Zig's testing framework allows you to write tests using the test keyword. When using allocators within tests, use std.testing.allocator. This allocator is designed to detect memory leaks; if you fail to call deinit() on an allocated resource (like an ArrayList), the test will fail, notifying you of the leak.

test "simple test" {
    var list = std.ArrayList(i32).init(std.testing.allocator);
    defer list.deinit(); // Ensures memory is freed and leaks are detected
    try list.append(42);
    try std.testing.expectEqual(@as(i32, 42), list.pop());
}

This example demonstrates how to perform matrix multiplication using Zig's @Vector type to leverage SIMD (Single Instruction, Multiple Data) capabilities. By casting slices of data into @Vector(nv, u64), you can perform arithmetic operations like multiplication on entire vectors at once, followed by @reduce(.Add, result) to sum the elements of the vector.

const nv: usize = 10;
// ... setup data ...

// Inside loops:
@memcpy(&Aar, A[i][k..(k + nv)]);
for (0..nv) |l| {
    Bar[l] = B[k + l][j];
}

const Av: @Vector(nv, u64) = Aar;
const Bv: @Vector(nv, u64) = Bar;
const result = Av * Bv;
C[i][j] += @reduce(.Add, result);

Zig supports fuzz testing via std.testing.fuzz. You provide a test function that accepts a *std.testing.Smith object. The Smith object is used to generate and manipulate data to find edge cases or crashes.

To run fuzz tests, use the command: zig build test --fuzz.

In Zig, the entry point main can accept a std.process.Init argument. This object provides access to essential runtime resources:

• init.arena: An allocator that lives for the duration of the process.
• init.minimal.args: Command line arguments. Use .toSlice(allocator) to convert them into a slice.
• init.io: An Io instance required for performing I/O operations.

Note that for application output, you should use a dedicated writer (like stdout) rather than std.debug.print, which is intended for debugging and prints to stderr.

pub fn main(init: std.process.Init) !void {
    const arena: std.mem.Allocator = init.arena.allocator();
    const args = try init.minimal.args.toSlice(arena);
    const io = init.io;
    // ...
}

To perform efficient I/O, you can wrap stdout in a buffered writer using std.Io.File.Writer. This requires an Io instance and a buffer.

Important: Always call .flush() on the writer before the program exits to ensure all buffered data is written to the output stream.

var stdout_buffer: [1024]u8 = undefined;
var stdout_file_writer: Io.File.Writer = .init(.stdout(), io, &stdout_buffer);
const stdout_writer = &stdout_file_writer.interface;

try stdout_writer.write("Hello World\n");
try stdout_writer.flush();

The print_matrix function provides a way to format and print a 2D matrix (represented as an array of slices) to standard output. It accepts a matrix of size [100][]u64 and a name string for labeling.

fn print_matrix(matrix: [100][]u64, name: []const u8) !void {
    try stdout.print("Matrix {s}\n\n", .{name});
    for (0..matrix.len) |i| {
        const row = matrix[i];
        _ = try stdout.write("| ");
        for (0..row.len) |j| {
            try stdout.print("{d} | ", .{row[j]});
        }
        _ = try stdout.write("\n-----------------------------------------------------------------------------------\n");
    }
}