Zig 初始化与包元数据

默认模板：模块 + 可执行文件

在空目录中运行zig init会生成四个文件，展示了既需要可重用模块又需要CLI工具的项目的推荐模式：

$ mkdir myproject && cd myproject
$ zig init
info: created build.zig
info: created build.zig.zon
info: created src/main.zig
info: created src/root.zig
info: see `zig build --help` for a menu of options

生成的结构分离了关注点：

• src/root.zig: 可重用模块，暴露公共API（例如 bufferedPrint, add）
• src/main.zig: 可执行入口点，导入并使用模块
• build.zig: 构建图，连接模块和可执行产物
• build.zig.zon: 包元数据，包括名称、版本和指纹

这种布局使得外部包可以轻松依赖您的模块，而无需继承不必要的可执行代码，同时仍然为本地开发或分发提供方便的CLI。20

最小模板：为有经验的用户提供的存根

对于了解构建系统并希望最小化样板代码的用户，zig init --minimal 仅生成 build.zig.zon 和一个存根 build.zig：

$ mkdir minimal-project && cd minimal-project
$ zig init --minimal
info: successfully populated 'build.zig.zon' and 'build.zig'

生成的 build.zig.zon 很紧凑：

.{
    .name = .minimal_project,
    .version = "0.0.1",
    .minimum_zig_version = "0.15.2",
    .paths = .{""},
    .fingerprint = 0x52714d1b5f619765,
}

存根 build.zig 同样简洁：

const std = @import("std");

pub fn build(b: *std.Build) void {
    _ = b; // stub
}

此模式适用于您有明确的构建策略并希望避免删除样板注释和示例代码的情况。

ZON文件的解析方式

从解析器的角度来看，.zon清单只是Ast.parse()的另一种模式。分词器在.zig和.zon文件之间共享，但.zig被解析为声明容器，而.zon被解析为单个表达式——这正是build.zig.zon包含的内容。

• Zig模式（.zig文件）：将完整源文件解析为包含声明的容器
• ZON模式（.zon文件）：解析单个表达式（Zig对象表示法）

Sources: lib/std/zig/Parse.zig:192-205, lib/std/zig/Parse.zig:208-228

Required Fields

Every build.zig.zon must define these core fields:

.{
    .name = .myproject,
    .version = "0.1.0",
    .minimum_zig_version = "0.15.2",
    .paths = .{""},
    .fingerprint = 0xa1b2c3d4e5f60718,
}

• .name: A symbol literal (e.g., .myproject) used as the default dependency key; conventionally lowercase, omitting redundant "zig" prefixes since the package already lives in the Zig namespace.
• .version: A semantic version string ("MAJOR.MINOR.PATCH") that the package manager will eventually use for deduplication. SemanticVersion.zig
• .minimum_zig_version: The earliest Zig release that this package supports; older compilers will refuse to build it.
• .paths: An array of file/directory paths (relative to the build root) included in the package’s content hash; only these files are distributed and cached.
• .fingerprint: A 64-bit hexadecimal integer serving as the package’s globally unique identifier, generated once by the toolchain and never changed (except in hostile fork scenarios).

The following demo shows how these fields map to runtime introspection patterns (though in practice the build runner handles this automatically):

const std = @import("std");

pub fn main() !void {
    // Demonstrate parsing and introspecting build.zig.zon fields
    // In practice, the build runner handles this automatically
    const zon_example =
        \\.{
        \\    .name = .demo,
        \\    .version = "0.1.0",
        \\    .minimum_zig_version = "0.15.2",
        \\    .fingerprint = 0x1234567890abcdef,
        \\    .paths = .{"build.zig", "src"},
        \\    .dependencies = .{},
        \\}
    ;

    std.debug.print("--- build.zig.zon Field Demo ---\n", .{});
    std.debug.print("Sample ZON structure:\n{s}\n\n", .{zon_example});

    std.debug.print("Field explanations:\n", .{});
    std.debug.print("  .name: Package identifier (symbol literal)\n", .{});
    std.debug.print("  .version: Semantic version string\n", .{});
    std.debug.print("  .minimum_zig_version: Minimum supported Zig\n", .{});
    std.debug.print("  .fingerprint: Unique package ID (hex integer)\n", .{});
    std.debug.print("  .paths: Files included in package distribution\n", .{});
    std.debug.print("  .dependencies: External packages required\n", .{});

    std.debug.print("\nNote: Zig 0.15.2 uses .fingerprint for unique identity\n", .{});
    std.debug.print("      (Previously used UUID-style identifiers)\n", .{});
}

$ zig run zon_field_demo.zig

=== build.zig.zon Field Demo ===
Sample ZON structure:
.{
    .name = .demo,
    .version = "0.1.0",
    .minimum_zig_version = "0.15.2",
    .fingerprint = 0x1234567890abcdef,
    .paths = .{"build.zig", "src"},
    .dependencies = .{},
}

Field explanations:
  .name: Package identifier (symbol literal)
  .version: Semantic version string
  .minimum_zig_version: Minimum supported Zig
  .fingerprint: Unique package ID (hex integer)
  .paths: Files included in package distribution
  .dependencies: External packages required

Note: Zig 0.15.2 uses .fingerprint for unique identity
      (Previously used UUID-style identifiers)

Fingerprint: Global Identity and Fork Detection

The .fingerprint field is the linchpin of package identity: it is generated once when you first run zig init, and should never change for the lifetime of the package unless you are deliberately forking it into a new identity.

Changing the fingerprint of an actively maintained upstream project is considered a hostile fork—an attempt to hijack the package’s identity and redirect users to different code. Legitimate forks (where the upstream is abandoned) should regenerate the fingerprint to establish a new identity, while maintaining forks (backports, security patches) preserve the original fingerprint to signal continuity.

const std = @import("std");

pub fn main() !void {
    std.debug.print("--- Package Identity Validation ---\n\n", .{});

    // Simulate package metadata inspection
    const pkg_name = "mylib";
    const pkg_version = "1.0.0";
    const fingerprint: u64 = 0xabcdef1234567890;

    std.debug.print("Package: {s}\n", .{pkg_name});
    std.debug.print("Version: {s}\n", .{pkg_version});
    std.debug.print("Fingerprint: 0x{x}\n\n", .{fingerprint});

    // Validate semantic version format
    const version_valid = validateSemVer(pkg_version);
    std.debug.print("Version format valid: {}\n", .{version_valid});

    // Check fingerprint uniqueness
    std.debug.print("\nFingerprint ensures:\n", .{});
    std.debug.print("  - Globally unique package identity\n", .{});
    std.debug.print("  - Unambiguous version detection\n", .{});
    std.debug.print("  - Fork detection (hostile vs. legitimate)\n", .{});

    std.debug.print("\nWARNING: Changing fingerprint of a maintained project\n", .{});
    std.debug.print("         is considered a hostile fork attempt!\n", .{});
}

fn validateSemVer(version: []const u8) bool {
    // Simplified validation: check for X.Y.Z format
    var parts: u8 = 0;
    for (version) |c| {
        if (c == '.') parts += 1;
    }
    return parts == 2; // Must have exactly 2 dots
}

$ zig run fingerprint_demo.zig

=== Package Identity Validation ===

Package: mylib
Version: 1.0.0
Fingerprint: 0xabcdef1234567890

Version format valid: true

Fingerprint ensures:
  - Globally unique package identity
  - Unambiguous version detection
  - Fork detection (hostile vs. legitimate)

WARNING: Changing fingerprint of a maintained project
         is considered a hostile fork attempt!

Dependencies: Remote, Local, and Lazy

The .dependencies field is a struct literal mapping dependency names to fetch specifications; each entry is either a remote URL dependency, a local filesystem path dependency, or a lazily-fetched optional dependency.

.{
    // Package name: used as key in dependency tables
    // Convention: lowercase, no "zig" prefix (redundant in Zig namespace)
    .name = .mylib,

    // Semantic version for package deduplication
    .version = "1.2.3",

    // Globally unique package identifier
    // Generated once by toolchain, then never changes
    // Allows unambiguous detection of package updates
    .fingerprint = 0xa1b2c3d4e5f60718,

    // Minimum supported Zig version
    .minimum_zig_version = "0.15.2",

    // External dependencies
    .dependencies = .{
        // Remote dependency with URL and hash
        .example_remote = .{
            .url = "https://github.com/user/repo/archive/tag.tar.gz",
            // Multihash format: source of truth for package identity
            .hash = "1220abcdef1234567890abcdef1234567890abcdef1234567890abcdef12345678",
        },

        // Local path dependency (no hash needed)
        .example_local = .{
            .path = "../sibling-package",
        },

        // Lazy dependency: only fetched if actually used
        .example_lazy = .{
            .url = "https://example.com/optional.tar.gz",
            .hash = "1220fedcba0987654321fedcba0987654321fedcba0987654321fedcba098765",
            .lazy = true,
        },
    },

    // Files included in package hash
    // Only these files/directories are distributed
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
        "README.md",
    },
}

const std = @import("std");

pub fn main() !void {
    std.debug.print("--- Dependency Types Comparison ---\n\n", .{});

    // Demonstrate different dependency specification patterns
    const deps = [_]Dependency{
        .{
            .name = "remote_package",
            .kind = .{ .remote = .{
                .url = "https://example.com/pkg.tar.gz",
                .hash = "122012345678...",
            } },
            .lazy = false,
        },
        .{
            .name = "local_package",
            .kind = .{ .local = .{
                .path = "../local-lib",
            } },
            .lazy = false,
        },
        .{
            .name = "lazy_optional",
            .kind = .{ .remote = .{
                .url = "https://example.com/opt.tar.gz",
                .hash = "1220abcdef...",
            } },
            .lazy = true,
        },
    };

    for (deps, 0..) |dep, i| {
        std.debug.print("Dependency {d}: {s}\n", .{ i + 1, dep.name });
        std.debug.print("  Type: {s}\n", .{@tagName(dep.kind)});
        std.debug.print("  Lazy: {}\n", .{dep.lazy});

        switch (dep.kind) {
            .remote => |r| {
                std.debug.print("  URL: {s}\n", .{r.url});
                std.debug.print("  Hash: {s}\n", .{r.hash});
                std.debug.print("  (Fetched from network, cached locally)\n", .{});
            },
            .local => |l| {
                std.debug.print("  Path: {s}\n", .{l.path});
                std.debug.print("  (No hash needed, relative to build root)\n", .{});
            },
        }
        std.debug.print("\n", .{});
    }

    std.debug.print("Key differences:\n", .{});
    std.debug.print("  - Remote: Uses hash as source of truth\n", .{});
    std.debug.print("  - Local: Direct filesystem path\n", .{});
    std.debug.print("  - Lazy: Only fetched when actually imported\n", .{});
}

const Dependency = struct {
    name: []const u8,
    kind: union(enum) {
        remote: struct {
            url: []const u8,
            hash: []const u8,
        },
        local: struct {
            path: []const u8,
        },
    },
    lazy: bool,
};

$ zig run dependency_types.zig

=== Dependency Types Comparison ===

Dependency 1: remote_package
  Type: remote
  Lazy: false
  URL: https://example.com/pkg.tar.gz
  Hash: 122012345678...
  (Fetched from network, cached locally)

Dependency 2: local_package
  Type: local
  Lazy: false
  Path: ../local-lib
  (No hash needed, relative to build root)

Dependency 3: lazy_optional
  Type: remote
  Lazy: true
  URL: https://example.com/opt.tar.gz
  Hash: 1220abcdef...
  (Fetched from network, cached locally)

Key differences:
  - Remote: Uses hash as source of truth
  - Local: Direct filesystem path
  - Lazy: Only fetched when actually imported

Paths: Controlling Package Distribution

The .paths field specifies which files and directories are included when computing the package hash and distributing the package; everything not listed is excluded from the cached artifact.

Typical patterns:

.paths = .{
    "build.zig",        // Build script is always needed
    "build.zig.zon",    // Metadata file itself
    "src",              // Source code directory (recursive)
    "LICENSE",          // Legal requirement
    "README.md",        // Documentation
}

Listing a directory includes all files within it recursively; listing the empty string "" includes the build root itself (equivalent to listing every file individually, which is rarely desired).

Under the hood: ZON files in dependency tracking

The compiler’s incremental dependency tracker treats ZON files as a distinct dependee category alongside source hashes, embedded files, and declaration-based dependencies. The core storage is an InternPool that owns multiple maps into a shared dep_entries array:

The dependency tracking system uses multiple hash maps to look up dependencies by different dependee types. All maps point into a shared dep_entries array, which stores the actual DepEntry structures forming linked lists of dependencies.

Sources: src/InternPool.zig:34-85

Each category tracks a different kind of dependee:

Sources: src/InternPool.zig:34-71

Minimum Zig Version: Compatibility Bounds

The .minimum_zig_version field declares the earliest Zig release that the package can build with; older compilers will refuse to proceed, preventing silent miscompilations due to missing features or changed semantics.

When the language stabilizes at 1.0.0, this field will interact with semantic versioning to provide compatibility guarantees; before 1.0.0, it serves as a forward-looking compatibility declaration even though breaking changes happen every release.

Version: Semantic Versioning for Deduplication

The .version field currently documents the package’s semantic version but does not yet enforce compatibility ranges or automatic deduplication; that functionality is planned for post-1.0.0 when the language stabilizes.

Follow semantic versioning conventions:

• MAJOR: Increment for incompatible API changes
• MINOR: Increment for backward-compatible feature additions
• PATCH: Increment for backward-compatible bug fixes

This discipline will pay off once the package manager can auto-resolve compatible versions within dependency trees. 24