Zig包管理器与（深入）

.{
    .name = "myproject",
    .version = "0.1.0",
    .minimum_zig_version = "0.15.2",
    .fingerprint = 0x1234567890abcdef,
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
        "LICENSE",
    },
}

.{
    .name = "consumer",
    .version = "0.2.0",
    .minimum_zig_version = "0.15.2",
    .dependencies = .{
        // Path-based dependency (local development)
        .mylib = .{
            .path = "../mylib",
        },
        // URL-based dependency would look like:
        // .known_folders = .{
        //     .url = "https://github.com/ziglibs/known-folders/archive/refs/tags/v1.1.0.tar.gz",
        //     .hash = "1220c1aa96c9cf0a7df5848c9d50e0e1f1e8b6ac8e7f5e4c0f4c5e6f7a8b9c0d",
        // },
    },
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

.{
    .name = "app",
    .version = "1.0.0",
    .minimum_zig_version = "0.15.2",
    .dependencies = .{
        // Eager dependency: always fetched
        .core = .{
            .path = "../core",
        },
        // Lazy dependency: only fetched when actually used
        .benchmark_utils = .{
            .path = "../benchmark_utils",
            .lazy = true,
        },
        .debug_visualizer = .{
            .path = "../debug_visualizer",
            .lazy = true,
        },
    },
    .paths = .{
        "build.zig",
        "build.zig.zon",
        "src",
    },
}

// Conceptual example showing the dependency resolution pipeline
const std = @import("std");

const DependencyState = enum {
    declared, // Listed in build.zig.zon
    downloading, // URL being fetched
    verifying, // Hash being checked
    cached, // Stored in global cache
    available, // Ready for use
};

const Dependency = struct {
    name: []const u8,
    url: ?[]const u8,
    path: ?[]const u8,
    hash: ?[]const u8,
    lazy: bool,
    state: DependencyState,
};

pub fn main() !void {
    std.debug.print("--- Zig Package Manager Resolution Pipeline ---\n\n", .{});

    // Stage 1: Parse build.zig.zon
    std.debug.print("1. Parse build.zig.zon dependencies\n", .{});
    var deps = [_]Dependency{
        .{
            .name = "core",
            .path = "../core",
            .url = null,
            .hash = null,
            .lazy = false,
            .state = .declared,
        },
        .{
            .name = "utils",
            .url = "https://example.com/utils.tar.gz",
            .path = null,
            .hash = "1220abcd...",
            .lazy = false,
            .state = .declared,
        },
        .{
            .name = "optional_viz",
            .url = "https://example.com/viz.tar.gz",
            .path = null,
            .hash = "1220ef01...",
            .lazy = true,
            .state = .declared,
        },
    };

    // Stage 2: Resolve eager dependencies
    std.debug.print("\n2. Resolve eager dependencies\n", .{});
    for (&deps) |*dep| {
        if (!dep.lazy) {
            std.debug.print("   - {s}: ", .{dep.name});
            if (dep.path) |p| {
                std.debug.print("local path '{s}' → available\n", .{p});
                dep.state = .available;
            } else if (dep.url) |_| {
                std.debug.print("fetching → verifying → cached → available\n", .{});
                dep.state = .available;
            }
        }
    }

    // Stage 3: Lazy dependencies deferred
    std.debug.print("\n3. Lazy dependencies (deferred until used)\n", .{});
    for (deps) |dep| {
        if (dep.lazy) {
            std.debug.print("   - {s}: waiting for lazyDependency() call\n", .{dep.name});
        }
    }

    // Stage 4: Build script execution triggers lazy fetch
    std.debug.print("\n4. Build script requests lazy dependency\n", .{});
    std.debug.print("   - optional_viz requested → fetching now\n", .{});

    // Stage 5: Cache lookup
    std.debug.print("\n5. Cache locations\n", .{});
    std.debug.print("   - Global: ~/.cache/zig/p/<hash>/\n", .{});
    std.debug.print("   - Project: .zig-cache/\n", .{});

    std.debug.print("\n=== Resolution Complete ===\n", .{});
}

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // 获取 build.zig.zon 中定义的依赖项
    const mylib_dep = b.dependency("mylib", .{
        .target = target,
        .optimize = optimize,
    });

    // 从依赖项中获取模块
    const mylib_module = mylib_dep.module("mylib");

    const exe = b.addExecutable(.{
        .name = "app",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    // 导入依赖项模块
    exe.root_module.addImport("mylib", mylib_module);

    b.installArtifact(exe);

    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());
    if (b.args) |args| {
        run_cmd.addArgs(args);
    }

    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);
}

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    // 核心依赖项始终加载
    const core_dep = b.dependency("core", .{
        .target = target,
        .optimize = optimize,
    });

    const exe = b.addExecutable(.{
        .name = "app",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    exe.root_module.addImport("core", core_dep.module("core"));
    b.installArtifact(exe);

    // 根据构建选项有条件地使用延迟依赖项
    const enable_benchmarks = b.option(bool, "benchmarks", "Enable benchmark mode") orelse false;
    const enable_debug_viz = b.option(bool, "debug-viz", "Enable debug visualizations") orelse false;

    if (enable_benchmarks) {
        // lazyDependency 如果未获取，则返回 null
        if (b.lazyDependency("benchmark_utils", .{
            .target = target,
            .optimize = optimize,
        })) |bench_dep| {
            exe.root_module.addImport("benchmark", bench_dep.module("benchmark"));
        }
    }

    if (enable_debug_viz) {
        if (b.lazyDependency("debug_visualizer", .{
            .target = target,
            .optimize = optimize,
        })) |viz_dep| {
            exe.root_module.addImport("visualizer", viz_dep.module("visualizer"));
        }
    }

    const run_cmd = b.addRunArtifact(exe);
    run_cmd.step.dependOn(b.getInstallStep());

    const run_step = b.step("run", "Run the app");
    run_step.dependOn(&run_cmd.step);
}

$ zig build                          # Core functionality only
$ zig build -Dbenchmarks=true        # Fetches benchmark_utils if needed
$ zig build -Ddebug-viz=true         # Fetches debug_visualizer if needed

// This example demonstrates how hash verification works conceptually.
// In practice, Zig handles this automatically during `zig fetch`.

const std = @import("std");

pub fn main() !void {
    // Simulate fetching a package
    const package_contents = "This is the package source code.";

    // Compute the hash
    var hasher = std.crypto.hash.sha2.Sha256.init(.{});
    hasher.update(package_contents);
    var digest: [32]u8 = undefined;
    hasher.final(&digest); // Format as hex for display
    std.debug.print("Package hash: {x}\n", .{digest});
    std.debug.print("Expected hash in build.zig.zon: 1220{x}\n", .{digest});
    std.debug.print("\nNote: The '1220' prefix indicates SHA-256 in multihash format.\n", .{});
}

$ zig fetch https://example.com/package.tar.gz

$ zig fetch --save https://github.com/example/package/archive/v1.0.0.tar.gz

$ zig fetch https://example.com/package.tar.gz

$ zig build --fetch