std.Build: Deprecate Step.Compile APIs that mutate the root module

[castholm]

Not only are Step.Compile methods like linkLibC() redundant because Module exposes the same APIs, it also might not be immediately obvious to users that these methods modify the underlying root module, which can be a footgun and lead to unintended results if the module is exported to package consumers or shared by multiple compile steps. For example, I personally almost ran in to this:

// module exported to package consumers, doesn't require libc
const mod = b.addModule("mymodule", .{
    .root_source_file = b.path("main.zig"),
    .target = target,
    .optimize = optimize,
});

// some unit tests require libc
const tests = b.addTest(.{ .root_module = mod });
tests.linkLibC(); // uh-oh! now the exported module requires libc!

const run_tests = b.addRunArtifact(tests);

const test_step = b.step("test", "Run tests");
test_step.dependOn(&run_tests.step);

Using compile.root_module.link_libc = true or compile.root_module.linkLibrary(lib) makes it more clear to users which of the compile step and the module owns which options.

Suggested release notes (if you think deprecation notices are relevant):

Deprecated std.Build.Step.Compile APIs

The following std.Build.Step.Compile methods have been deprecated in favor of their std.Build.Module equivalents and are slated for removal during the next release cycle:

• addAfterIncludePath
• addAssemblyFile
• addCSourceFile
• addCSourceFiles
• addConfigHeader
• addEmbedPath
• addFrameworkPath
• addIncludePath
• addLibraryPath
• addObject
• addObjectFile
• addRPath
• addSystemFrameworkPath
• addSystemIncludePath
• addWin32ResourceFile
• linkFramework
• linkLibC
• linkLibCpp
• linkLibrary
• linkSystemLibrary
• linkSystemLibrary2

Upgrade guide:

 // Most uses can be migrated by inserting `root_module` before the method call
-exe.linkLibrary(lib);
+exe.root_module.linkLibrary(lib);

 // Set the corresponding field directly
-exe.linkLibC();
-exe.linkLibCpp();
+exe.root_module.link_libc = true;
+exe.root_module.link_libcpp = true;

 // Pass '.{}' as the second argument
-exe.linkSystemLibrary("foo");
+exe.root_module.linkSystemLibrary("foo", .{});

 // Omit the '2' from the method name
-exe.linkSystemLibrary2("foo", .{ .needed = false });
+exe.root_module.linkSystemLibrary("foo", .{ .needed = false });

[alexrp]

@mlugg would you mind reviewing this (considering #20388/#18752)? Also @BratishkaErik.

[andrewrk]

Sounds good, let's make this depend on #22822 yeah?

[castholm]

@andrewrk Updating these APIs to make use of @deprecated is blocked by the fact that @deprecated does not seem to work as envisioned. I opened a topic on Zulip with more details but the gist of the problem is that if you have a function marked with @deprecated, it becomes an error if the context in which it is declared forbids deprecations, when it should be the context from which it is called. Because Compile.linkLibrary etc. reside in the std module, which is configured with fno-allow-deprecated by default, this means that it becomes a compile error to use them even from a dependency's build.zig module which is configured with -fallow-deprecated. This makes it painful to depend on "legacy packages" that haven't been updated to use the module APIs and seems contrary to the spirit of soft-deprecating the APIs in the first place (instead of simply removing them right here and now).

[castholm]

This did not make the 0.14 cutoff. I've removed references to version numbers from the doc comments so this can be merged whenever you feel is appropriate.

[mlugg]

This looks good to me. Note that reaching through to exe.root_module is probably not actually great style -- I would say it's nicer to construct the module separately in most non-trivial cases -- but certainly for a simple migration it's a fine approach.

One last request, sorry. Would it be possible to add /// Remove after the 0.15.0 release. to all of the deprecation comments? This just makes it easier to spot them by grepping the standard library in the future, so helps stop us accidentally leaving deprecated stuff hanging around for a long time.

If you can amend the first commit with that, I'll then be happy to press the big green button -- you can give me a ping on Zulip to make sure I don't miss it.

[castholm]

I would say it's nicer to construct the module separately in most non-trivial cases -- but certainly for a simple migration it's a fine approach.

I agree that it's the better and more hygienic style to construct and configure the module separately since modifying exe.root_module could still inadvertently modify a module shared by two compile steps, it just makes it more obvious that the option resides in the module. It's difficult to fit guidance about the preferred way of constructing modules/compile steps in the deprecation notices but I could try to add a mention of it to the release notes draft if you think that sounds good.

[mlugg]

This looks great, thanks very much. You can add a mention to the release notes of the fact that directly using exe.root_module (etc) is discouraged if you would like to, but it's not that important, so don't worry too much.