enforce build.zig.zon declares paths that are accessed by the build

[marler8997]

Updates std.Build.path and std.Build.Dependency.path to verify that path names are included in the corresponding build.zig.zon if present.

This would have caught a mistake in this commit allyourcodebase/SDL@b77d252 where I forgot to add a new directory include-pregen to the build.zig.zon file, which, caused my local testing to pass but ultimately push a broken commit that only manifests when newly downloading dependencies.

[castholm]

Preventing people from shipping broken packages that reference non-existent paths is a good thing, but it should be noted that the approach this PR takes means that larger scale projects might no longer be able to use the same build.zig for both building as the root project and building as a dependency.

For example, imagine you have a single build.zig for a large library which in addition to artifacts and modules also includes integration tests, example programs and other things which are irrelevant for package consumers. Depending on the size of these redundant files, you might want to exclude them from the paths list in your build.zig.zon so that they don't take up unnecessary space (the Zig package manager deletes files not matched by paths when untarring).

But with this change making referencing files not matched by paths a hard error, this use case would no longer be supported. Projects which want to provide a tidy and trimmed package tarball will need to maintain two separate build.zig files, one for building as the root project and another for building as a dependency, which may become an annoying maintenance hassle.

Another thing worth considering is that only the files matched by paths are used to compute a package's hash. If a project adds or modifies internal documentation files or example programs that don't affect the modules/artifacts that consumers depend on in a package manager context, the package hash should probably not change.

Instead of checking that a path is matched by the package manifest immediately when invoking b.path()/dependency.path(), an alternative approach might be to delegate these checks to the build runner and have it check the paths when they are being resolved, but only if/when the paths are referenced by public modules/artifacts that are exposed to package consumers. That way, "private" steps and artifacts will retain the ability to reference files not matched by paths.

[marler8997]

But with this change making referencing files not matched by paths a hard error, this use case would no longer be supported.

I'm not sure this is true. There was in fact a similar example in this repo that I had to fix in this PR in test/standalone/build.zig. The build.zig file was referencing paths outside of test/standalone inside tools, the fix was simply to add a new dependency in build.zig.zon that pointed to ../../tools. I liked this change since now it's clear from the manifest file where all the files this package needs are located. Before this change, you'd only know all the files by executing the build runner, you couldn't determine this beforehand.

There's also another solution currently available which is to just add these extra files to your "paths" field in the zon file, I also tested this currently works in this example. However, I'm not sure it would work on a top-level zon file as any paths accessed outside a package wouldn't exist.

There's also things you can do in your build.zig file to modify which files it accesses depending on the context. Maybe there are cases that can't be covered with these various solution I've described (and ones I haven't), but it's hard to know for sure without any concrete examples. If you can come up with one let me know and I can see if I can come up with a reasonable solution.

Another thing worth considering is that only the files matched by paths are used to compute a package's hash. If a project adds or modifies internal documentation files or example programs that don't affect the modules/artifacts that consumers depend on in a package manager context, the package hash should probably not change.

This feels a bit "off-topic" to this PR but I do have thoughts to share :) I believe that being able to determine that certain files accessed by a build can NEVER affect certain outputs "in general" is "undecidable" (i.e. determine that certain documentation/examples file can have no affect on certain outputs). There is a lot you can do here with containerized builds that can track/audit all files accessed by a process, but those can also be less fine-grained than you'd like as you'd have to treat each process as an atomic unit, where you couldn't de-couple particular inputs/outputs given to the same process.

Without a full-proof general solution like containerization, I don't see enough benefit to try and exclude files from affecting particular output files of a build to try and implement a system that is sophisticated enough to do it correctly (especially in the general case).

Instead of checking that a path is matched by the package manifest immediately when invoking b.path()/dependency.path(), an alternative approach might be to delegate these checks to the build runner and have it check the paths when they are being resolved, but only if/when the paths are referenced by public modules/artifacts that are exposed to package consumers. That way, "private" steps and artifacts will retain the ability to reference files not matched by paths.

"Lazy enforcment" is a good idea to consider. However, I'd recommend first trying "greedy enforcement" as this more restrictive design may lead to simpler packages with less bugs/problems, unless we find real use cases that this doesn't work with and that don't have reasonable alternatives.

[marler8997]

This one's been sitting for about 3 months and a whole bunch of conflicts have come in since. It doesn't seem like I should take time to rebase it as no one from the core team has indicated this is a change that would be accepted. Is there anything I can do to help here? Should we close this, leave it open, keep waiting until the core team has time?

[andrewrk]

I'm not focused on the build system right now. I suggest to just leave it as is, if I want the change it looks like it would be trivial to rework a 200 line diff onto whatever the current state of the codebase is at the time.

This change also offers a chance to rethink how paths work because there are some flaws with the current setup so I wont merge a bandage without considering that.