Extracted from #14265.

Terminology clarification: #14307

For many zig modules, advanced build system features are not needed, such as generating source files, compiling C code, or accepting build options. In such cases, build.zig is overkill. All that is really needed is the .zig source files to be available to the project which has the dependency on this one.

For this I propose the package to be organized like this:

• build.zig - may or may not exist. Perhaps the package still has a test harness to be run, or has development dependencies.
• build.zig.zon - may or may not exist.

Meanwhile the package depending on it will do something like this:

build.zig.zon

.{
    .name = "clap",
    .url = "...",
    .hash = "...",
}

build.zig

// "clap" here references the dependency.name field of the build.zig.ini file.
const exe = b.addExecutable("app", "src/main.zig");
exe.addModuleFromDependencyPath(
    // name to be used by @import
    "clap",
    // module root directory, relative to clap dependency build root
    ".",
    // module root source file, relative to module root directory
    "clap.zig",
);

Note that this allows a project to add a dependency based on any arbitrary directory of files without the dependee being aware of it being used that way.

When a module is added this way, no build.zig logic is executed. Note that this could be problematic, such as in the case of a dependency introducing a new generated file as part of their package, or adding build options. To future-proof against this situation, instead of addModuleFromDependencyPath, build scripts should use b.dependency() which will execute the dependency's build logic.

See #14278 for depending on zig packages while respecting build.zig logic.

See #14286 for running build.zig logic in a sandbox.