Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 26, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions doc/langref/build.zig
Original file line number Diff line number Diff line change
@@ -4,8 +4,10 @@ pub fn build(b: *std.Build) void {
const optimize = b.standardOptimizeOption(.{});
const exe = b.addExecutable(.{
.name = "example",
.root_source_file = b.path("example.zig"),
.optimize = optimize,
.root_module = b.createModule(.{
.root_source_file = b.path("example.zig"),
.optimize = optimize,
}),
});
b.default_step.dependOn(&exe.step);
}
12 changes: 8 additions & 4 deletions doc/langref/build_c.zig
Original file line number Diff line number Diff line change
@@ -4,15 +4,19 @@ pub fn build(b: *std.Build) void {
const lib = b.addLibrary(.{
.linkage = .dynamic,
.name = "mathtest",
.root_source_file = b.path("mathtest.zig"),
.root_module = b.createModule(.{
.root_source_file = b.path("mathtest.zig"),
}),
.version = .{ .major = 1, .minor = 0, .patch = 0 },
});
const exe = b.addExecutable(.{
.name = "test",
.root_module = b.createModule(.{
.link_libc = true,
}),
});
exe.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.linkLibrary(lib);
exe.linkSystemLibrary("c");
exe.root_module.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.root_module.linkLibrary(lib);

b.default_step.dependOn(&exe.step);

12 changes: 8 additions & 4 deletions doc/langref/build_object.zig
Original file line number Diff line number Diff line change
@@ -3,15 +3,19 @@ const std = @import("std");
pub fn build(b: *std.Build) void {
const obj = b.addObject(.{
.name = "base64",
.root_source_file = b.path("base64.zig"),
.root_module = b.createModule(.{
.root_source_file = b.path("base64.zig"),
}),
});

const exe = b.addExecutable(.{
.name = "test",
.root_module = b.createModule(.{
.link_libc = true,
}),
});
exe.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.addObject(obj);
exe.linkSystemLibrary("c");
exe.root_module.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.root_module.addObject(obj);
b.installArtifact(exe);
}

46 changes: 42 additions & 4 deletions lib/std/Build/Step/Compile.zig
Original file line number Diff line number Diff line change
@@ -681,10 +681,14 @@ pub fn producesImplib(compile: *Compile) bool {
return compile.isDll();
}

/// Deprecated; use `compile.root_module.link_libc = true` instead.
/// To be removed after 0.15.0 is tagged.
pub fn linkLibC(compile: *Compile) void {
compile.root_module.link_libc = true;
}

/// Deprecated; use `compile.root_module.link_libcpp = true` instead.
/// To be removed after 0.15.0 is tagged.
pub fn linkLibCpp(compile: *Compile) void {
compile.root_module.link_libcpp = true;
}
@@ -802,10 +806,14 @@ fn runPkgConfig(compile: *Compile, lib_name: []const u8) !PkgConfigResult {
};
}

/// Deprecated; use `compile.root_module.linkSystemLibrary(name, .{})` instead.
/// To be removed after 0.15.0 is tagged.
pub fn linkSystemLibrary(compile: *Compile, name: []const u8) void {
return compile.root_module.linkSystemLibrary(name, .{});
}

/// Deprecated; use `compile.root_module.linkSystemLibrary(name, options)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn linkSystemLibrary2(
compile: *Compile,
name: []const u8,
@@ -814,22 +822,26 @@ pub fn linkSystemLibrary2(
return compile.root_module.linkSystemLibrary(name, options);
}

/// Deprecated; use `c.root_module.linkFramework(name, .{})` instead.
/// To be removed after 0.15.0 is tagged.
pub fn linkFramework(c: *Compile, name: []const u8) void {
c.root_module.linkFramework(name, .{});
}

/// Handy when you have many C/C++ source files and want them all to have the same flags.
/// Deprecated; use `compile.root_module.addCSourceFiles(options)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addCSourceFiles(compile: *Compile, options: Module.AddCSourceFilesOptions) void {
compile.root_module.addCSourceFiles(options);
}

/// Deprecated; use `compile.root_module.addCSourceFile(source)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addCSourceFile(compile: *Compile, source: Module.CSourceFile) void {
compile.root_module.addCSourceFile(source);
}

/// Resource files must have the extension `.rc`.
/// Can be called regardless of target. The .rc file will be ignored
/// if the target object format does not support embedded resources.
/// Deprecated; use `compile.root_module.addWin32ResourceFile(source)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addWin32ResourceFile(compile: *Compile, source: Module.RcSourceFile) void {
compile.root_module.addWin32ResourceFile(source);
}
@@ -915,54 +927,80 @@ pub fn getEmittedLlvmBc(compile: *Compile) LazyPath {
return compile.getEmittedFileGeneric(&compile.generated_llvm_bc);
}

/// Deprecated; use `compile.root_module.addAssemblyFile(source)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addAssemblyFile(compile: *Compile, source: LazyPath) void {
compile.root_module.addAssemblyFile(source);
}

/// Deprecated; use `compile.root_module.addObjectFile(source)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addObjectFile(compile: *Compile, source: LazyPath) void {
compile.root_module.addObjectFile(source);
}

/// Deprecated; use `compile.root_module.addObject(object)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addObject(compile: *Compile, object: *Compile) void {
compile.root_module.addObject(object);
}

/// Deprecated; use `compile.root_module.linkLibrary(library)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn linkLibrary(compile: *Compile, library: *Compile) void {
compile.root_module.linkLibrary(library);
}

/// Deprecated; use `compile.root_module.addAfterIncludePath(lazy_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addAfterIncludePath(compile: *Compile, lazy_path: LazyPath) void {
compile.root_module.addAfterIncludePath(lazy_path);
}

/// Deprecated; use `compile.root_module.addSystemIncludePath(lazy_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addSystemIncludePath(compile: *Compile, lazy_path: LazyPath) void {
compile.root_module.addSystemIncludePath(lazy_path);
}

/// Deprecated; use `compile.root_module.addIncludePath(lazy_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addIncludePath(compile: *Compile, lazy_path: LazyPath) void {
compile.root_module.addIncludePath(lazy_path);
}

/// Deprecated; use `compile.root_module.addConfigHeader(config_header)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addConfigHeader(compile: *Compile, config_header: *Step.ConfigHeader) void {
compile.root_module.addConfigHeader(config_header);
}

/// Deprecated; use `compile.root_module.addEmbedPath(lazy_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addEmbedPath(compile: *Compile, lazy_path: LazyPath) void {
compile.root_module.addEmbedPath(lazy_path);
}

/// Deprecated; use `compile.root_module.addLibraryPath(directory_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addLibraryPath(compile: *Compile, directory_path: LazyPath) void {
compile.root_module.addLibraryPath(directory_path);
}

/// Deprecated; use `compile.root_module.addRPath(directory_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addRPath(compile: *Compile, directory_path: LazyPath) void {
compile.root_module.addRPath(directory_path);
}

/// Deprecated; use `compile.root_module.addSystemFrameworkPath(directory_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addSystemFrameworkPath(compile: *Compile, directory_path: LazyPath) void {
compile.root_module.addSystemFrameworkPath(directory_path);
}

/// Deprecated; use `compile.root_module.addFrameworkPath(directory_path)` instead.
/// To be removed after 0.15.0 is tagged.
pub fn addFrameworkPath(compile: *Compile, directory_path: LazyPath) void {
compile.root_module.addFrameworkPath(directory_path);
}
738 changes: 369 additions & 369 deletions test/link/elf.zig

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions test/link/link.zig
Original file line number Diff line number Diff line change
@@ -140,20 +140,20 @@ pub fn addRunArtifact(comp: *Compile) *Run {
pub fn addCSourceBytes(comp: *Compile, bytes: []const u8, flags: []const []const u8) void {
const b = comp.step.owner;
const file = WriteFile.create(b).add("a.c", bytes);
comp.addCSourceFile(.{ .file = file, .flags = flags });
comp.root_module.addCSourceFile(.{ .file = file, .flags = flags });
}

pub fn addCppSourceBytes(comp: *Compile, bytes: []const u8, flags: []const []const u8) void {
const b = comp.step.owner;
const file = WriteFile.create(b).add("a.cpp", bytes);
comp.addCSourceFile(.{ .file = file, .flags = flags });
comp.root_module.addCSourceFile(.{ .file = file, .flags = flags });
}

pub fn addAsmSourceBytes(comp: *Compile, bytes: []const u8) void {
const b = comp.step.owner;
const actual_bytes = std.fmt.allocPrint(b.allocator, "{s}\n", .{bytes}) catch @panic("OOM");
const file = WriteFile.create(b).add("a.s", actual_bytes);
comp.addAssemblyFile(file);
comp.root_module.addAssemblyFile(file);
}

pub fn expectLinkErrors(comp: *Compile, test_step: *Step, expected_errors: Compile.ExpectedCompileErrors) void {
246 changes: 123 additions & 123 deletions test/link/macho.zig

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion test/link/wasm/extern/build.zig
Original file line number Diff line number Diff line change
@@ -16,7 +16,7 @@ fn add(b: *std.Build, test_step: *std.Build.Step, optimize: std.builtin.Optimize
.target = b.resolveTargetQuery(.{ .cpu_arch = .wasm32, .os_tag = .wasi }),
}),
});
exe.addCSourceFile(.{ .file = b.path("foo.c"), .flags = &.{} });
exe.root_module.addCSourceFile(.{ .file = b.path("foo.c"), .flags = &.{} });
exe.use_llvm = false;
exe.use_lld = false;

2 changes: 1 addition & 1 deletion test/src/Cases.zig
Original file line number Diff line number Diff line change
@@ -560,7 +560,7 @@ pub fn lowerToTranslateCSteps(
.root_module = translate_c.createModule(),
});
run_exe.step.name = b.fmt("{s} build-exe", .{annotated_case_name});
run_exe.linkLibC();
run_exe.root_module.link_libc = true;
const run = b.addRunArtifact(run_exe);
run.step.name = b.fmt("{s} run", .{annotated_case_name});
run.expectStdOutEqual(output);
2 changes: 1 addition & 1 deletion test/src/RunTranslatedC.zig
Original file line number Diff line number Diff line change
@@ -89,7 +89,7 @@ pub fn addCase(self: *RunTranslatedCContext, case: *const TestCase) void {
.root_module = translate_c.createModule(),
});
exe.step.name = b.fmt("{s} build-exe", .{annotated_case_name});
exe.linkLibC();
exe.root_module.link_libc = true;
const run = b.addRunArtifact(exe);
run.step.name = b.fmt("{s} run", .{annotated_case_name});
if (!case.allow_warnings) {
6 changes: 3 additions & 3 deletions test/standalone/c_embed_path/build.zig
Original file line number Diff line number Diff line change
@@ -13,12 +13,12 @@ pub fn build(b: *std.Build) void {
.optimize = optimize,
}),
});
exe.addCSourceFile(.{
exe.root_module.addCSourceFile(.{
.file = b.path("test.c"),
.flags = &.{"-std=c23"},
});
exe.linkLibC();
exe.addEmbedPath(b.path("data"));
exe.root_module.link_libc = true;
exe.root_module.addEmbedPath(b.path("data"));

const run_c_cmd = b.addRunArtifact(exe);
run_c_cmd.expectExitCode(0);
4 changes: 2 additions & 2 deletions test/standalone/extern/build.zig
Original file line number Diff line number Diff line change
@@ -31,8 +31,8 @@ pub fn build(b: *std.Build) void {
.target = b.graph.host,
.optimize = optimize,
}) });
test_exe.addObject(obj);
test_exe.linkLibrary(shared);
test_exe.root_module.addObject(obj);
test_exe.root_module.linkLibrary(shared);

test_step.dependOn(&b.addRunArtifact(test_exe).step);
}
2 changes: 1 addition & 1 deletion test/standalone/issue_794/build.zig
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@ pub fn build(b: *std.Build) void {
.root_source_file = b.path("main.zig"),
.target = b.graph.host,
}) });
test_artifact.addIncludePath(b.path("a_directory"));
test_artifact.root_module.addIncludePath(b.path("a_directory"));

// TODO: actually check the output
_ = test_artifact.getEmittedBin();
2 changes: 1 addition & 1 deletion test/standalone/stack_iterator/build.zig
Original file line number Diff line number Diff line change
@@ -109,7 +109,7 @@ pub fn build(b: *std.Build) void {
// .use_llvm = true,
// });

// exe.linkLibrary(c_shared_lib);
// exe.root_module.linkLibrary(c_shared_lib);

// const run_cmd = b.addRunArtifact(exe);
// test_step.dependOn(&run_cmd.step);
4 changes: 2 additions & 2 deletions test/tests.zig
Original file line number Diff line number Diff line change
@@ -2371,10 +2371,10 @@ pub fn addModuleTests(b: *std.Build, options: ModuleTestOptions) *Step {
} else "";
const use_pic = if (test_target.pic == true) "-pic" else "";

for (options.include_paths) |include_path| these_tests.addIncludePath(b.path(include_path));
for (options.include_paths) |include_path| these_tests.root_module.addIncludePath(b.path(include_path));

if (target.os.tag == .windows) {
for (options.windows_libs) |lib| these_tests.linkSystemLibrary(lib);
for (options.windows_libs) |lib| these_tests.root_module.linkSystemLibrary(lib, .{});
}

const qualified_name = b.fmt("{s}-{s}-{s}-{s}{s}{s}{s}{s}{s}{s}", .{