如何在Zig多模块项目中导入tools模块并兼容测试？

问题场景 #

现有Zig项目结构如下：

src/
   lib.zig
   module_a/
      file_a.zig
      file_a_test.zig
   module_b/
      file_b.zig
      file_b_test.zig
   tools/
      tools.zig
      tools_test.zig

需要实现：

1. 在module_a/file_a.zig和module_b/file_b.zig中直接用const tools = @import("tools")引用tools模块
2. 支持单独执行测试命令（如zig test src/module_a/file_a_test.zig）正常运行
3. 项目无main.zig，可借助src/lib.zig完成配置

之前的方案要么依赖旧版std.build.Pkg，要么必须搭配main.zig用b.addModule，均不满足需求。

解决方案 #

1. 编写build.zig配置 #

通过模块映射实现跨模块引用，同时为每个测试目标配置依赖：

const std = @import("std");

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

    // 定义tools模块，指向对应源码文件
    const tools_mod = b.addModule("tools", .{
        .source_file = .{ .path = "src/tools/tools.zig" },
    });

    // 构建项目静态库（无main.zig时用静态库作为核心目标）
    const lib = b.addStaticLibrary(.{
        .name = "project-lib",
        .root_source_file = .{ .path = "src/lib.zig" },
        .target = target,
        .optimize = optimize,
    });
    // 给库关联tools模块
    lib.addModule("tools", tools_mod);
    b.installArtifact(lib);

    // 配置module_a的测试
    const module_a_test = b.addTest(.{
        .root_source_file = .{ .path = "src/module_a/file_a_test.zig" },
        .target = target,
        .optimize = optimize,
    });
    module_a_test.addModule("tools", tools_mod);
    const run_module_a_test = b.addRunArtifact(module_a_test);
    b.step("test-module-a", "Run module_a tests").dependOn(&run_module_a_test.step);

    // 配置module_b的测试
    const module_b_test = b.addTest(.{
        .root_source_file = .{ .path = "src/module_b/file_b_test.zig" },
        .target = target,
        .optimize = optimize,
    });
    module_b_test.addModule("tools", tools_mod);
    const run_module_b_test = b.addRunArtifact(module_b_test);
    b.step("test-module-b", "Run module_b tests").dependOn(&run_module_b_test.step);

    // 配置tools自身的测试（可选）
    const tools_test = b.addTest(.{
        .root_source_file = .{ .path = "src/tools/tools_test.zig" },
        .target = target,
        .optimize = optimize,
    });
    const run_tools_test = b.addRunArtifact(tools_test);
    b.step("test-tools", "Run tools tests").dependOn(&run_tools_test.step);

    // 总测试步骤，一键运行所有测试
    const all_tests = b.step("test", "Run all tests");
    all_tests.dependOn(&run_module_a_test.step);
    all_tests.dependOn(&run_module_b_test.step);
    all_tests.dependOn(&run_tools_test.step);
}

2. 配置src/lib.zig #

作为项目根模块，统一导出子模块，确保模块路径解析正确：

// 导出各子模块，让构建系统能识别模块关系
pub const module_a = @import("module_a/file_a.zig");
pub const module_b = @import("module_b/file_b.zig");
pub const tools = @import("tools/tools.zig");

3. 确保单独运行zig test正常工作 #

直接执行zig test时，需要告诉Zig如何找到tools模块，有两种方式：

方式一：手动添加参数

# 用-I指定src为根目录，@import("tools")会自动解析为src/tools/tools.zig
zig test src/module_a/file_a_test.zig -I src

# 或者用--mod明确指定模块映射
zig test src/module_a/file_a_test.zig --mod tools:src/tools/tools.zig

方式二：配置默认映射文件

在项目根目录创建zig.settings.json，配置默认模块映射，以后执行zig test无需手动加参数：

{
    "build_options": {
        "modules": {
            "tools": "src/tools/tools.zig"
        }
    }
}

核心要点 #

• 用b.addModule定义全局模块，再通过addModule给库和测试目标关联依赖，解决构建时的模块引用问题
• src/lib.zig作为根模块统一导出子模块，符合Zig的模块设计规范，同时简化构建配置
• 单独测试时通过-I/--mod或配置文件解决路径解析问题，保证手动测试流程正常

内容的提问来源于stack exchange，提问作者Piotr Tutak