Zig Project Engineering and Package Management

This chapter introduces how to organize Zig projects, manage dependency packages, and best practices for building large applications.

Project Structure

Standard Project Layout

my-zig-project/
├── build.zig              # Build script
├── build.zig.zon          # Project configuration and dependencies
├── src/                   # Source code directory
│   ├── main.zig          # Main program entry
│   ├── lib.zig           # Library entry
│   ├── utils/            # Utility modules
│   │   ├── string.zig
│   │   └── math.zig
│   └── tests/            # Test files
│       ├── main_test.zig
│       └── utils_test.zig
├── examples/             # Example code
│   └── basic_usage.zig
├── docs/                 # Documentation
│   └── README.md
├── assets/               # Resource files
│   └── config.json
└── zig-out/             # Build output directory
    ├── bin/
    └── lib/

Creating a New Project

bash

# Create executable program project
zig init-exe

# Create library project
zig init-lib

# Manually create project structure
mkdir my-project
cd my-project
mkdir src examples tests docs assets
touch build.zig build.zig.zon src/main.zig

Module System

Basic Module Structure

Create src/utils/math.zig:

zig

const std = @import("std");

/// Calculate greatest common divisor of two numbers
pub fn gcd(a: u32, b: u32) u32 {
    if (b == 0) return a;
    return gcd(b, a % b);
}

/// Calculate least common multiple of two numbers
pub fn lcm(a: u32, b: u32) u32 {
    return (a * b) / gcd(a, b);
}

/// Check if a number is prime
pub fn isPrime(n: u32) bool {
    if (n < 2) return false;
    if (n == 2) return true;
    if (n % 2 == 0) return false;
    
    var i: u32 = 3;
    while (i * i <= n) : (i += 2) {
        if (n % i == 0) return false;
    }
    return true;
}

// Tests
test "math utilities" {
    const testing = std.testing;
    
    // Test GCD
    try testing.expect(gcd(12, 8) == 4);
    try testing.expect(gcd(17, 13) == 1);
    
    // Test LCM
    try testing.expect(lcm(4, 6) == 12);
    try testing.expect(lcm(3, 7) == 21);
    
    // Test prime check
    try testing.expect(isPrime(2) == true);
    try testing.expect(isPrime(17) == true);
    try testing.expect(isPrime(4) == false);
    try testing.expect(isPrime(1) == false);
}

Package Management

build.zig.zon Configuration

Create build.zig.zon:

zig

.{
    .name = "my-zig-project",
    .version = "0.1.0",
    .description = "An example Zig project",
    .author = "Your Name",
    .license = "MIT",
    
    .dependencies = .{
        // Example dependencies (use real packages in practice)
        .json = .{
            .url = "https://github.com/example/zig-json/archive/main.tar.gz",
            .hash = "1234567890abcdef...", // Package hash
        },
        .http = .{
            .url = "https://github.com/example/zig-http/archive/v1.0.0.tar.gz",
            .hash = "abcdef1234567890...",
        },
    },
    
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "examples",
        "docs/README.md",
    },
}

Summary

This chapter introduced Zig project engineering practices:

✅ Standard project structure and module organization
✅ Package management and dependency handling
✅ Test organization and configuration management
✅ Logging system and example programs
✅ Build scripts and continuous integration
✅ Engineering best practices

Good engineering practices are the foundation for building maintainable and scalable Zig projects. Through proper project organization, comprehensive test coverage, and automated build processes, development efficiency and code quality can be greatly improved.

In the next chapter, we'll learn about Zig's build system.

Zig Project Engineering and Package Management ​

Project Structure ​

Standard Project Layout ​

Creating a New Project ​

Module System ​

Basic Module Structure ​

Package Management ​

build.zig.zon Configuration ​

Summary ​