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 in the future:

• 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.