autodocs: recognize lib.zig as a library root source file

[tensorush]

Hi, I'd like to plead the case for lib.zig as a valid library root source file, and moreover, to challenge the current convention of root.zig being the library root source file.

Here're some points to consider:

• Is This Your Root or Mine?
  Since library code can sometimes resort to inspecting users' root source files with @import("root"), having root.zig as the library root source file can be confusing, whereas lib.zig would avoid this confusion.
• What in the Root Is This?
  The word root (either a noun or an adjective) is objectively more likely to be encountered in other contexts across potential Zig codebases (tree-like data structures, file system hierarchies, privileged access permissions) and conflict with these other uses, compared to the word lib which, being a common alias for library (a noun), is much less likely to emerge beyond the compiler-related projects.
• Is This Even a Library?
  A lib.zig file succeeds at being perceived as exclusively a library root source file, similarly to how a main.zig file is seen as an executable root source file, whereas root.zig only communicates that it's a root source file, without making it immediately apparent that it's a library root source file.
• We Want Lib!
  FWIW, querying GitHub Search with root.zig language:Zig gives 4.8k source code results while lib.zig language:Zig produces 5.1k results, which may suggest that Zig users are already slightly more biased towards lib.zig.

In the unlikely expected case that you become convinced that lib.zig is a better library root source file, I'd be happy to change the zig init template and its generation logic (the only other places where root.zig convention is enforced) in a follow-up PR.

[mochalins]

I'm fairly neutral to whether lib.zig becomes the default name, but just to throw out more data points:

One fairly common pattern I've used in certain projects makes use of root.zig, lib.zig, and main.zig.

• root.zig (or sometimes foo.zig, where the project name is foo) - Module root, used for Zig library consumers
• lib.zig - Exported C library root, also conveniently matches up with the typical libfoo.a naming pattern of C library artifacts
• main.zig - Executable root, typically of an accompanying CLI tool

This naming also lines up nicely with build.zig functions, where lib.zig is passed to addLibrary and root.zig is passed to addModule.

[tensorush]

• lib.zig - Exported C library root

Arguably, lib.zig is ambiguous in the case of exporting C bindings to your Zig library, it may be better to use c.zig or bindings.zig. Sidenote, bindings.zig is also fine to use in the opposite case of exposing Zig bindings to a C library, since the project itself indicates which way the bindings are being exposed to.

[mochalins]

Arguably, lib.zig is ambiguous in the case of exporting C bindings to your Zig library

Perhaps, although I lean towards viewing it as quite clear in its meaning when existing alongside root.zig.

it may be better to use c.zig

I don't view that as better at all. "c" is quite overloaded; used commonly with cImport (sometimes gathering common cImports in one file), and "c.zig" also sometimes used when writing extern stubs to a C dependency. I find that having a file named "c.zig" is strictly more ambiguous.

And, as an aside, any library that both consumes and exports C libraries would make "bindings.zig" an ambiguous name. The project would not make it clear whether bindings refers to bindings for the project proper, or bindings to its C dependencies. At the very least, no less ambiguous (and arguably more ambiguous) than lib.zig.

Whatever the case may be, this should probably be written as a proper proposal issue rather than in a PR.

[tensorush]

"c" is quite overloaded; used commonly with cImport (sometimes gathering common cImports in one file), and "c.zig" also sometimes used when writing extern stubs to a C dependency.

@cImport will be removed in favour of the TranslateC build step (see accepted proposal #20630).

And, as an aside, any library that both consumes and exports C libraries would make "bindings.zig" an ambiguous name.

Building C/C++ libraries with Zig for consumption (with or without bindings) is better done as a separate repo, properly utilizing the package manager (see @allyourcodebase for examples).

So consuming C libraries by Zig projects won't be happening under src/, which makes it unambiguously appealing to use c.zig for writing extern stubs to C dependencies, like you said, and bindings.zig for creating Zig-to-C (and vice versa) bindings.

[mochalins]

"c" is quite overloaded; used commonly with cImport (sometimes gathering common cImports in one file), and "c.zig" also sometimes used when writing extern stubs to a C dependency.

@cImport will be removed in favour of the TranslateC build step (see accepted proposal #20630).

And, as an aside, any library that both consumes and exports C libraries would make "bindings.zig" an ambiguous name.

Building C/C++ libraries with Zig for consumption (with or without bindings) is better done as a separate repo, properly utilizing the package manager (see @allyourcodebase for examples).

So consuming C libraries by Zig projects won't be happening under src/, which makes it unambiguously appealing to use c.zig for writing extern stubs to C dependencies, like you said, and bindings.zig for creating Zig-to-C (and vice versa) bindings.

Ok, it seems we are talking circles around each other so let me be very explicit.

It doesn't matter what you or I believe is/isn't a good naming choice; I didn't make my original point to bikeshed recommendations on what to name a library root source file. Irregardless of our personal tastes/opinions, there are Zig users and projects existing in the wild that use the name lib.zig for something other than a Zig package root module source file name.

Moreover, the use of lib.zig as a name in this way is not some inane blatant disregard of recommendations from Zig docs/core team; it's quite reasonable and consistent with naming in other parts of the Zig standard library, e.g. build functions.

I've stated that such naming patterns using lib.zig exist, I've shown their connections with the build functions, and even explained why it is not a ridiculous name to use with some sort of universally accepted superior alternative.

With the above said, I hope you can now acknowledge that your proposed changes are indeed breaking; I am not asking for advice on what I should be doing.

Now, with that out of the way, here are more reasons why your proposal is not as cut-and-dry as you initially suggested:

1. Your original post seems to work off the assumption that it is correct to call a Zig package a "library". This is not a universally accepted truth; to some users, a "library" will be a technical definition that includes a linkable artifact. As Zig packages are just bundles of sources that do not, on their own, produce any build artifact; it is very reasonable for some to argue that they shouldn't even be called a library. This would render the whole basis of lib.zig as a "library" root module moot. (In fact, when I first read your original post, I assumed your use of the word "library" was referring specifically to library artifacts à la those added by addLibrary, linkSystemLibrary, etc... my response was in support of your proposal, to attribute lib.zig to roots of said artifacts and root.zig only to Zig package root module, rather than the current template project default of using root.zig for both. I only realized you meant otherwise in your response recommending against using lib.zig)
2. Your evidence of lib.zig usage only shows that people use a file named as such, not necessarily that they use it as their package root module file name. I've already explained above how people might (reasonably) be using this name in other ways, and as such the GitHub search statistics do not seem relevant.
3. This really is not a change that matters much in the grand scheme of things, particularly compared to other ongoing work in compiler frontend/backends, language features, debugging the CI, etc. However, if said change was to be implemented, then really the rest of the standard library should be looked at for naming consistency.

Finally, I'd like to reiterate that you are proposing a breaking change in a PR. It's not really the

expected case

to agree with your proposal here, for the multitude of reasons listed above, and it would be really great if users actually have a chance to discover this proposal and contribute their opinions through the proper channels; e.g., making a proposal issue.