build system terminology update: package, project, module, dependency

[andrewrk]

Status Quo

• A project is a directory of files, uniquely identified by a hash of all files. Projects can export any number of compilation artifacts and packages.
• A dependency is a directed edge between projects. A project may depend on any number of projects. A project may be a dependency of any number of projects.
• A package is a directory of files, along with a root source file that identifies the file referred to when the package is used with @import.
• A compilation artifact is a static library, a dynamic library, an executable, or an object file. Corresponds to std.build.LibExeObjStep.

The Problem

We have been using the word "package" already, including in build system APIs:

zig/lib/std/build.zig

Lines 1479 to 1483 in d813cef

	pub const Pkg = struct {
	name: []const u8,
	source: FileSource,
	dependencies: ?[]const Pkg = null,
	};

zig/lib/std/build/LibExeObjStep.zig

Lines 977 to 980 in d813cef

	pub fn addPackage(self: *LibExeObjStep, package: Pkg) void {
	self.packages.append(self.builder.dupePkg(package)) catch unreachable;
	self.addRecursiveBuildDeps(package);
	}

However, people are 100% going to say "package" when they mean "project". This is unavoidable, inescapable, and we should not fight against it, but rather embrace it. That leaves us with the following lingo:

• A package is a directory of files, uniquely identified by a hash of all files. Packages can export any number of compilation artifacts and packages.
• A package is a directory of files, along with a root source file that identifies the file referred to when the package is used with @import.

Ambiguity strikes ruthlessly.

The Solution

Our hero is the word "module". The word "project" is no longer needed.

• A package is a directory of files, uniquely identified by a hash of all files. Packages can export any number of compilation artifacts and modules.
• A dependency is a directed edge between packages. A package may depend on any number of packages. A package may be a dependency of any number of packages.
• A module is a directory of files, along with a root source file that identifies the file referred to when the module is used with @import.
• A compilation artifact is a static library, a dynamic library, an executable, or an object file. Corresponds to std.build.LibExeObjStep.

I would also like to rename LibExeObjStep to CompilationArtifact while we're at it.

This issue is to do the following things:

• update the terminology in documentation
• update the terminology in the zig compiler internal source code
• update the terminology in the build system APIs and internal source code
• update the terminology in build.zig.zon
• update the CLI arguments

[kuon]

Just to clarify, would addPackage become addModule as now module are what is being @imported?

[andrewrk]

Yes, addPackage will become addModule.

[kuon]

Ok. I think this is a good naming, but this leads to one question.

As addModule is not aware of the package it comes from, how do you plan to handle name clash?

If I understand it correctly, a package like png could have a compress and decompress module, which would be imported with @import("compress"); (very generic name) and not @import("png").compress ?

[andrewrk]

@kuon I believe this question is answered by #14278. I have just now edited it for the terminology update.

[kuon]

Ok, so this in the app build.zig:

// "clap" here is the string used when calling b.addModule (see code snippet below)
const clap_module = clap_dep.module("clap");

// "clap" here is the name used for `@import` within src/main.zig
exe.addModule("clap", clap_module);

would be in my example:

const png_compress_mod = png_dep.module("compress");
exe.addModule("png:compress", png_compress_mod);

And then in my wherever_I_use_png.zig

const png_compress = @import("png:compress"); // name defined in `build.zig` and specific to the app

Here I use : but it could be whatever your heart desire. Maybe a convention for it?

[andrewrk]

Oops, I got the comments backwards (and therefore so did you from copy-pasting). It should be:

// "clap" here is the string used when calling b.addModule (see code snippet below)
const clap_module = clap_dep.module("clap");

// "clap" here is the name used for `@import` within src/main.zig
exe.addModule("clap", clap_module);

But then you got it right with your png example 👍

[kuon]

Yeah I was confused by the comment, but your former explanation was clear enough for me to get it right. I have updated my post to reflect the fixed code.

Now that I get a full circle understanding of the concepts, I fully agree with your terminology.

Btw, I am happy you are not introducing a special name like crate for rust. It always confuses me, as rust has crate, package, workspace, module and namespace. Effectively reducing that to package and module is a nice simplification.