Merge pull request #19167 from castholm/installHeader

std.Build: fix `Compile.installHeader` behavior, add `WriteFile.addCopyDirectory`

lib/std/Build.zig

@@ -1568,23 +1568,24 @@ pub fn addObjCopy(b: *Build, source: LazyPath, options: Step.ObjCopy.Options) *S
     return Step.ObjCopy.create(b, source, options);
 }
 
-///`dest_rel_path` is relative to install prefix path
-pub fn addInstallFile(self: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
-    return self.addInstallFileWithDir(source.dupe(self), .prefix, dest_rel_path);
+/// `dest_rel_path` is relative to install prefix path
+pub fn addInstallFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
+    return b.addInstallFileWithDir(source, .prefix, dest_rel_path);
 }
 
-///`dest_rel_path` is relative to bin path
-pub fn addInstallBinFile(self: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
-    return self.addInstallFileWithDir(source.dupe(self), .bin, dest_rel_path);
+/// `dest_rel_path` is relative to bin path
+pub fn addInstallBinFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
+    return b.addInstallFileWithDir(source, .bin, dest_rel_path);
 }
 
-///`dest_rel_path` is relative to lib path
-pub fn addInstallLibFile(self: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
-    return self.addInstallFileWithDir(source.dupe(self), .lib, dest_rel_path);
+/// `dest_rel_path` is relative to lib path
+pub fn addInstallLibFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
+    return b.addInstallFileWithDir(source, .lib, dest_rel_path);
 }
 
-pub fn addInstallHeaderFile(b: *Build, src_path: []const u8, dest_rel_path: []const u8) *Step.InstallFile {
-    return b.addInstallFileWithDir(.{ .path = src_path }, .header, dest_rel_path);
+/// `dest_rel_path` is relative to header path
+pub fn addInstallHeaderFile(b: *Build, source: LazyPath, dest_rel_path: []const u8) *Step.InstallFile {
+    return b.addInstallFileWithDir(source, .header, dest_rel_path);
 }
 
 pub fn addInstallFileWithDir(
@@ -1593,7 +1594,7 @@ pub fn addInstallFileWithDir(
     install_dir: InstallDir,
     dest_rel_path: []const u8,
 ) *Step.InstallFile {
-    return Step.InstallFile.create(self, source.dupe(self), install_dir, dest_rel_path);
+    return Step.InstallFile.create(self, source, install_dir, dest_rel_path);
 }
 
 pub fn addInstallDirectory(self: *Build, options: Step.InstallDir.Options) *Step.InstallDir {

lib/std/Build/Module.zig

@@ -265,8 +265,7 @@ fn addShallowDependencies(m: *Module, dependee: *Module) void {
     for (dependee.link_objects.items) |link_object| switch (link_object) {
         .other_step => |compile| {
             addStepDependencies(m, dependee, &compile.step);
-            for (compile.installed_headers.items) |install_step|
-                addStepDependenciesOnly(m, install_step);
+            addLazyPathDependenciesOnly(m, compile.getEmittedIncludeTree());
         },
 
         .static_path,
@@ -691,20 +690,14 @@ pub fn appendZigProcessFlags(
             },
             .other_step => |other| {
                 if (other.generated_h) |header| {
-                    try zig_args.append("-isystem");
-                    try zig_args.append(std.fs.path.dirname(header.path.?).?);
+                    try zig_args.appendSlice(&.{ "-isystem", std.fs.path.dirname(header.getPath()).? });
                 }
-                if (other.installed_headers.items.len > 0) {
-                    try zig_args.append("-I");
-                    try zig_args.append(b.pathJoin(&.{
-                        other.step.owner.install_prefix, "include",
-                    }));
+                if (other.installed_headers_include_tree) |include_tree| {
+                    try zig_args.appendSlice(&.{ "-I", include_tree.generated_directory.getPath() });
                 }
             },
             .config_header_step => |config_header| {
-                const full_file_path = config_header.output_file.path.?;
-                const header_dir_path = full_file_path[0 .. full_file_path.len - config_header.include_path.len];
-                try zig_args.appendSlice(&.{ "-I", header_dir_path });
+                try zig_args.appendSlice(&.{ "-I", std.fs.path.dirname(config_header.output_file.getPath()).? });
             },
         }
     }
@@ -752,9 +745,7 @@ fn linkLibraryOrObject(m: *Module, other: *Step.Compile) void {
     m.link_objects.append(allocator, .{ .other_step = other }) catch @panic("OOM");
     m.include_dirs.append(allocator, .{ .other_step = other }) catch @panic("OOM");
 
-    for (other.installed_headers.items) |install_step| {
-        addStepDependenciesOnly(m, install_step);
-    }
+    addLazyPathDependenciesOnly(m, other.getEmittedIncludeTree());
 }
 
 fn requireKnownTarget(m: *Module) std.Target {

lib/std/Build/Step/Compile.zig

@@ -59,7 +59,13 @@ test_runner: ?[]const u8,
 test_server_mode: bool,
 wasi_exec_model: ?std.builtin.WasiExecModel = null,
 
-installed_headers: ArrayList(*Step),
+installed_headers: ArrayList(HeaderInstallation),
+
+/// This step is used to create an include tree that dependent modules can add to their include
+/// search paths. Installed headers are copied to this step.
+/// This step is created the first time a module links with this artifact and is not
+/// created otherwise.
+installed_headers_include_tree: ?*Step.WriteFile = null,
 
 // keep in sync with src/Compilation.zig:RcIncludes
 /// Behavior of automatic detection of include directories when compiling .rc files.
@@ -249,6 +255,90 @@ pub const Kind = enum {
     @"test",
 };
 
+pub const HeaderInstallation = union(enum) {
+    file: File,
+    directory: Directory,
+
+    pub const File = struct {
+        source: LazyPath,
+        dest_rel_path: []const u8,
+
+        pub fn dupe(self: File, b: *std.Build) File {
+            // 'path' lazy paths are relative to the build root of some step, inferred from the step
+            // in which they are used. This means that we can't dupe such paths, because they may
+            // come from dependencies with their own build roots and duping the paths as is might
+            // cause the build script to search for the file relative to the wrong root.
+            // As a temporary workaround, we convert build root-relative paths to absolute paths.
+            // If/when the build-root relative paths are updated to encode which build root they are
+            // relative to, this workaround should be removed.
+            const duped_source: LazyPath = switch (self.source) {
+                .path => |root_rel| .{ .cwd_relative = b.pathFromRoot(root_rel) },
+                else => self.source.dupe(b),
+            };
+
+            return .{
+                .source = duped_source,
+                .dest_rel_path = b.dupePath(self.dest_rel_path),
+            };
+        }
+    };
+
+    pub const Directory = struct {
+        source: LazyPath,
+        dest_rel_path: []const u8,
+        options: Directory.Options,
+
+        pub const Options = struct {
+            /// File paths that end in any of these suffixes will be excluded from installation.
+            exclude_extensions: []const []const u8 = &.{},
+            /// Only file paths that end in any of these suffixes will be included in installation.
+            /// `null` means that all suffixes will be included.
+            /// `exclude_extensions` takes precedence over `include_extensions`.
+            include_extensions: ?[]const []const u8 = &.{".h"},
+
+            pub fn dupe(self: Directory.Options, b: *std.Build) Directory.Options {
+                return .{
+                    .exclude_extensions = b.dupeStrings(self.exclude_extensions),
+                    .include_extensions = if (self.include_extensions) |incs| b.dupeStrings(incs) else null,
+                };
+            }
+        };
+
+        pub fn dupe(self: Directory, b: *std.Build) Directory {
+            // 'path' lazy paths are relative to the build root of some step, inferred from the step
+            // in which they are used. This means that we can't dupe such paths, because they may
+            // come from dependencies with their own build roots and duping the paths as is might
+            // cause the build script to search for the file relative to the wrong root.
+            // As a temporary workaround, we convert build root-relative paths to absolute paths.
+            // If/when the build-root relative paths are updated to encode which build root they are
+            // relative to, this workaround should be removed.
+            const duped_source: LazyPath = switch (self.source) {
+                .path => |root_rel| .{ .cwd_relative = b.pathFromRoot(root_rel) },
+                else => self.source.dupe(b),
+            };
+
+            return .{
+                .source = duped_source,
+                .dest_rel_path = b.dupePath(self.dest_rel_path),
+                .options = self.options.dupe(b),
+            };
+        }
+    };
+
+    pub fn getSource(self: HeaderInstallation) LazyPath {
+        return switch (self) {
+            inline .file, .directory => |x| x.source,
+        };
+    }
+
+    pub fn dupe(self: HeaderInstallation, b: *std.Build) HeaderInstallation {
+        return switch (self) {
+            .file => |f| .{ .file = f.dupe(b) },
+            .directory => |d| .{ .directory = d.dupe(b) },
+        };
+    }
+};
+
 pub fn create(owner: *std.Build, options: Options) *Compile {
     const name = owner.dupe(options.name);
     if (mem.indexOf(u8, name, "/") != null or mem.indexOf(u8, name, "\\") != null) {
@@ -308,7 +398,7 @@ pub fn create(owner: *std.Build, options: Options) *Compile {
         .out_lib_filename = undefined,
         .major_only_filename = null,
         .name_only_filename = null,
-        .installed_headers = ArrayList(*Step).init(owner.allocator),
+        .installed_headers = ArrayList(HeaderInstallation).init(owner.allocator),
         .zig_lib_dir = null,
         .exec_cmd_args = null,
         .filters = options.filters,
@@ -380,78 +470,85 @@ pub fn create(owner: *std.Build, options: Options) *Compile {
     return self;
 }
 
-pub fn installHeader(cs: *Compile, src_path: []const u8, dest_rel_path: []const u8) void {
+/// Marks the specified header for installation alongside this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
+pub fn installHeader(cs: *Compile, source: LazyPath, dest_rel_path: []const u8) void {
     const b = cs.step.owner;
-    const install_file = b.addInstallHeaderFile(src_path, dest_rel_path);
-    b.getInstallStep().dependOn(&install_file.step);
-    cs.installed_headers.append(&install_file.step) catch @panic("OOM");
-}
-
-pub const InstallConfigHeaderOptions = struct {
-    install_dir: InstallDir = .header,
-    dest_rel_path: ?[]const u8 = null,
-};
-
-pub fn installConfigHeader(
-    cs: *Compile,
-    config_header: *Step.ConfigHeader,
-    options: InstallConfigHeaderOptions,
-) void {
-    const dest_rel_path = options.dest_rel_path orelse config_header.include_path;
-    const b = cs.step.owner;
-    const install_file = b.addInstallFileWithDir(
-        .{ .generated = &config_header.output_file },
-        options.install_dir,
-        dest_rel_path,
-    );
-    install_file.step.dependOn(&config_header.step);
-    b.getInstallStep().dependOn(&install_file.step);
-    cs.installed_headers.append(&install_file.step) catch @panic("OOM");
+    const installation: HeaderInstallation = .{ .file = .{
+        .source = source.dupe(b),
+        .dest_rel_path = b.dupePath(dest_rel_path),
+    } };
+    cs.installed_headers.append(installation) catch @panic("OOM");
+    cs.addHeaderInstallationToIncludeTree(installation);
+    installation.getSource().addStepDependencies(&cs.step);
 }
 
+/// Marks headers from the specified directory for installation alongside this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
 pub fn installHeadersDirectory(
-    a: *Compile,
-    src_dir_path: []const u8,
-    dest_rel_path: []const u8,
-) void {
-    return installHeadersDirectoryOptions(a, .{
-        .source_dir = .{ .path = src_dir_path },
-        .install_dir = .header,
-        .install_subdir = dest_rel_path,
-    });
-}
-
-pub fn installHeadersDirectoryOptions(
     cs: *Compile,
-    options: std.Build.Step.InstallDir.Options,
+    source: LazyPath,
+    dest_rel_path: []const u8,
+    options: HeaderInstallation.Directory.Options,
 ) void {
     const b = cs.step.owner;
-    const install_dir = b.addInstallDirectory(options);
-    b.getInstallStep().dependOn(&install_dir.step);
-    cs.installed_headers.append(&install_dir.step) catch @panic("OOM");
+    const installation: HeaderInstallation = .{ .directory = .{
+        .source = source.dupe(b),
+        .dest_rel_path = b.dupePath(dest_rel_path),
+        .options = options.dupe(b),
+    } };
+    cs.installed_headers.append(installation) catch @panic("OOM");
+    cs.addHeaderInstallationToIncludeTree(installation);
+    installation.getSource().addStepDependencies(&cs.step);
 }
 
-pub fn installLibraryHeaders(cs: *Compile, l: *Compile) void {
-    assert(l.kind == .lib);
-    const b = cs.step.owner;
-    const install_step = b.getInstallStep();
-    // Copy each element from installed_headers, modifying the builder
-    // to be the new parent's builder.
-    for (l.installed_headers.items) |step| {
-        const step_copy = switch (step.id) {
-            inline .install_file, .install_dir => |id| blk: {
-                const T = id.Type();
-                const ptr = b.allocator.create(T) catch @panic("OOM");
-                ptr.* = step.cast(T).?.*;
-                ptr.dest_builder = b;
-                break :blk &ptr.step;
-            },
-            else => unreachable,
-        };
-        cs.installed_headers.append(step_copy) catch @panic("OOM");
-        install_step.dependOn(step_copy);
+/// Marks the specified config header for installation alongside this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
+pub fn installConfigHeader(cs: *Compile, config_header: *Step.ConfigHeader) void {
+    cs.installHeader(config_header.getOutput(), config_header.include_path);
+}
+
+/// Forwards all headers marked for installation from `lib` to this artifact.
+/// When a module links with this artifact, all headers marked for installation are added to that
+/// module's include search path.
+pub fn installLibraryHeaders(cs: *Compile, lib: *Compile) void {
+    assert(lib.kind == .lib);
+    for (lib.installed_headers.items) |installation| {
+        const installation_copy = installation.dupe(lib.step.owner);
+        cs.installed_headers.append(installation_copy) catch @panic("OOM");
+        cs.addHeaderInstallationToIncludeTree(installation_copy);
+        installation_copy.getSource().addStepDependencies(&cs.step);
     }
-    cs.installed_headers.appendSlice(l.installed_headers.items) catch @panic("OOM");
+}
+
+fn addHeaderInstallationToIncludeTree(cs: *Compile, installation: HeaderInstallation) void {
+    if (cs.installed_headers_include_tree) |wf| switch (installation) {
+        .file => |file| {
+            _ = wf.addCopyFile(file.source, file.dest_rel_path);
+        },
+        .directory => |dir| {
+            _ = wf.addCopyDirectory(dir.source, dir.dest_rel_path, .{
+                .exclude_extensions = dir.options.exclude_extensions,
+                .include_extensions = dir.options.include_extensions,
+            });
+        },
+    };
+}
+
+pub fn getEmittedIncludeTree(cs: *Compile) LazyPath {
+    if (cs.installed_headers_include_tree) |wf| return wf.getDirectory();
+    const b = cs.step.owner;
+    const wf = b.addWriteFiles();
+    cs.installed_headers_include_tree = wf;
+    for (cs.installed_headers.items) |installation| {
+        cs.addHeaderInstallationToIncludeTree(installation);
+    }
+    // The compile step itself does not need to depend on the write files step,
+    // only dependent modules do.
+    return wf.getDirectory();
 }
 
 pub fn addObjCopy(cs: *Compile, options: Step.ObjCopy.Options) *Step.ObjCopy {

lib/std/Build/Step/InstallArtifact.zig

@@ -77,12 +77,10 @@ pub fn create(owner: *std.Build, artifact: *Step.Compile, options: Options) *Ins
         },
         .h_dir = switch (options.h_dir) {
             .disabled => null,
-            // https://github.com/ziglang/zig/issues/9698
-            .default => null,
-            //.default => switch (artifact.kind) {
-            //    .lib => .header,
-            //    else => null,
-            //},
+            .default => switch (artifact.kind) {
+                .lib => .header,
+                else => null,
+            },
             .override => |o| o,
         },
         .implib_dir = switch (options.implib_dir) {
@@ -113,7 +111,8 @@ pub fn create(owner: *std.Build, artifact: *Step.Compile, options: Options) *Ins
 
     if (self.dest_dir != null) self.emitted_bin = artifact.getEmittedBin();
     if (self.pdb_dir != null) self.emitted_pdb = artifact.getEmittedPdb();
-    if (self.h_dir != null) self.emitted_h = artifact.getEmittedH();
+    // https://github.com/ziglang/zig/issues/9698
+    //if (self.h_dir != null) self.emitted_h = artifact.getEmittedH();
     if (self.implib_dir != null) self.emitted_implib = artifact.getEmittedImplib();
 
     return self;
@@ -122,14 +121,14 @@ pub fn create(owner: *std.Build, artifact: *Step.Compile, options: Options) *Ins
 fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     _ = prog_node;
     const self: *InstallArtifact = @fieldParentPtr("step", step);
-    const dest_builder = step.owner;
+    const b = step.owner;
     const cwd = fs.cwd();
 
     var all_cached = true;
 
     if (self.dest_dir) |dest_dir| {
-        const full_dest_path = dest_builder.getInstallPath(dest_dir, self.dest_sub_path);
-        const full_src_path = self.emitted_bin.?.getPath2(step.owner, step);
+        const full_dest_path = b.getInstallPath(dest_dir, self.dest_sub_path);
+        const full_src_path = self.emitted_bin.?.getPath2(b, step);
         const p = fs.Dir.updateFile(cwd, full_src_path, cwd, full_dest_path, .{}) catch |err| {
             return step.fail("unable to update file from '{s}' to '{s}': {s}", .{
                 full_src_path, full_dest_path, @errorName(err),
@@ -145,8 +144,8 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     }
 
     if (self.implib_dir) |implib_dir| {
-        const full_src_path = self.emitted_implib.?.getPath2(step.owner, step);
-        const full_implib_path = dest_builder.getInstallPath(implib_dir, fs.path.basename(full_src_path));
+        const full_src_path = self.emitted_implib.?.getPath2(b, step);
+        const full_implib_path = b.getInstallPath(implib_dir, fs.path.basename(full_src_path));
         const p = fs.Dir.updateFile(cwd, full_src_path, cwd, full_implib_path, .{}) catch |err| {
             return step.fail("unable to update file from '{s}' to '{s}': {s}", .{
                 full_src_path, full_implib_path, @errorName(err),
@@ -156,8 +155,8 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     }
 
     if (self.pdb_dir) |pdb_dir| {
-        const full_src_path = self.emitted_pdb.?.getPath2(step.owner, step);
-        const full_pdb_path = dest_builder.getInstallPath(pdb_dir, fs.path.basename(full_src_path));
+        const full_src_path = self.emitted_pdb.?.getPath2(b, step);
+        const full_pdb_path = b.getInstallPath(pdb_dir, fs.path.basename(full_src_path));
         const p = fs.Dir.updateFile(cwd, full_src_path, cwd, full_pdb_path, .{}) catch |err| {
             return step.fail("unable to update file from '{s}' to '{s}': {s}", .{
                 full_src_path, full_pdb_path, @errorName(err),
@@ -167,14 +166,68 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     }
 
     if (self.h_dir) |h_dir| {
-        const full_src_path = self.emitted_h.?.getPath2(step.owner, step);
-        const full_h_path = dest_builder.getInstallPath(h_dir, fs.path.basename(full_src_path));
-        const p = fs.Dir.updateFile(cwd, full_src_path, cwd, full_h_path, .{}) catch |err| {
-            return step.fail("unable to update file from '{s}' to '{s}': {s}", .{
-                full_src_path, full_h_path, @errorName(err),
-            });
+        if (self.emitted_h) |emitted_h| {
+            const full_src_path = emitted_h.getPath2(b, step);
+            const full_h_path = b.getInstallPath(h_dir, fs.path.basename(full_src_path));
+            const p = fs.Dir.updateFile(cwd, full_src_path, cwd, full_h_path, .{}) catch |err| {
+                return step.fail("unable to update file from '{s}' to '{s}': {s}", .{
+                    full_src_path, full_h_path, @errorName(err),
+                });
+            };
+            all_cached = all_cached and p == .fresh;
+        }
+
+        for (self.artifact.installed_headers.items) |installation| switch (installation) {
+            .file => |file| {
+                const full_src_path = file.source.getPath2(b, step);
+                const full_h_path = b.getInstallPath(h_dir, file.dest_rel_path);
+                const p = fs.Dir.updateFile(cwd, full_src_path, cwd, full_h_path, .{}) catch |err| {
+                    return step.fail("unable to update file from '{s}' to '{s}': {s}", .{
+                        full_src_path, full_h_path, @errorName(err),
+                    });
+                };
+                all_cached = all_cached and p == .fresh;
+            },
+            .directory => |dir| {
+                const full_src_dir_path = dir.source.getPath2(b, step);
+                const full_h_prefix = b.getInstallPath(h_dir, dir.dest_rel_path);
+
+                var src_dir = b.build_root.handle.openDir(full_src_dir_path, .{ .iterate = true }) catch |err| {
+                    return step.fail("unable to open source directory '{s}': {s}", .{
+                        full_src_dir_path, @errorName(err),
+                    });
+                };
+                defer src_dir.close();
+
+                var it = try src_dir.walk(b.allocator);
+                next_entry: while (try it.next()) |entry| {
+                    for (dir.options.exclude_extensions) |ext| {
+                        if (std.mem.endsWith(u8, entry.path, ext)) continue :next_entry;
+                    }
+                    if (dir.options.include_extensions) |incs| {
+                        for (incs) |inc| {
+                            if (std.mem.endsWith(u8, entry.path, inc)) break;
+                        } else {
+                            continue :next_entry;
+                        }
+                    }
+                    const full_src_entry_path = b.pathJoin(&.{ full_src_dir_path, entry.path });
+                    const full_dest_path = b.pathJoin(&.{ full_h_prefix, entry.path });
+                    switch (entry.kind) {
+                        .directory => try cwd.makePath(full_dest_path),
+                        .file => {
+                            const p = fs.Dir.updateFile(cwd, full_src_entry_path, cwd, full_dest_path, .{}) catch |err| {
+                                return step.fail("unable to update file from '{s}' to '{s}': {s}", .{
+                                    full_src_entry_path, full_dest_path, @errorName(err),
+                                });
+                            };
+                            all_cached = all_cached and p == .fresh;
+                        },
+                        else => continue,
+                    }
+                }
+            },
         };
-        all_cached = all_cached and p == .fresh;
     }
 
     step.result_cached = all_cached;

lib/std/Build/Step/InstallDir.zig

@@ -8,9 +8,6 @@ const InstallDirStep = @This();
 
 step: Step,
 options: Options,
-/// This is used by the build system when a file being installed comes from one
-/// package but is being installed by another.
-dest_builder: *std.Build,
 
 pub const base_id = .install_dir;
 
@@ -55,7 +52,6 @@ pub fn create(owner: *std.Build, options: Options) *InstallDirStep {
             .makeFn = make,
         }),
         .options = options.dupe(owner),
-        .dest_builder = owner,
     };
     options.source_dir.addStepDependencies(&self.step);
     return self;
@@ -63,15 +59,14 @@ pub fn create(owner: *std.Build, options: Options) *InstallDirStep {
 
 fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     _ = prog_node;
+    const b = step.owner;
     const self: *InstallDirStep = @fieldParentPtr("step", step);
-    const dest_builder = self.dest_builder;
-    const arena = dest_builder.allocator;
-    const dest_prefix = dest_builder.getInstallPath(self.options.install_dir, self.options.install_subdir);
-    const src_builder = self.step.owner;
-    const src_dir_path = self.options.source_dir.getPath2(src_builder, step);
-    var src_dir = src_builder.build_root.handle.openDir(src_dir_path, .{ .iterate = true }) catch |err| {
+    const arena = b.allocator;
+    const dest_prefix = b.getInstallPath(self.options.install_dir, self.options.install_subdir);
+    const src_dir_path = self.options.source_dir.getPath2(b, step);
+    var src_dir = b.build_root.handle.openDir(src_dir_path, .{ .iterate = true }) catch |err| {
         return step.fail("unable to open source directory '{}{s}': {s}", .{
-            src_builder.build_root, src_dir_path, @errorName(err),
+            b.build_root, src_dir_path, @errorName(err),
         });
     };
     defer src_dir.close();
@@ -104,20 +99,20 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
             .file => {
                 for (self.options.blank_extensions) |ext| {
                     if (mem.endsWith(u8, entry.path, ext)) {
-                        try dest_builder.truncateFile(dest_path);
+                        try b.truncateFile(dest_path);
                         continue :next_entry;
                     }
                 }
 
                 const prev_status = fs.Dir.updateFile(
-                    src_builder.build_root.handle,
+                    b.build_root.handle,
                     src_sub_path,
                     cwd,
                     dest_path,
                     .{},
                 ) catch |err| {
                     return step.fail("unable to update file from '{}{s}' to '{s}': {s}", .{
-                        src_builder.build_root, src_sub_path, dest_path, @errorName(err),
+                        b.build_root, src_sub_path, dest_path, @errorName(err),
                     });
                 };
                 all_cached = all_cached and prev_status == .fresh;

lib/std/Build/Step/InstallFile.zig

@@ -11,9 +11,6 @@ step: Step,
 source: LazyPath,
 dir: InstallDir,
 dest_rel_path: []const u8,
-/// This is used by the build system when a file being installed comes from one
-/// package but is being installed by another.
-dest_builder: *std.Build,
 
 pub fn create(
     owner: *std.Build,
@@ -34,7 +31,6 @@ pub fn create(
         .source = source.dupe(owner),
         .dir = dir.dupe(owner),
         .dest_rel_path = owner.dupePath(dest_rel_path),
-        .dest_builder = owner,
     };
     source.addStepDependencies(&self.step);
     return self;
@@ -42,11 +38,10 @@ pub fn create(
 
 fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     _ = prog_node;
-    const src_builder = step.owner;
+    const b = step.owner;
     const self: *InstallFile = @fieldParentPtr("step", step);
-    const dest_builder = self.dest_builder;
-    const full_src_path = self.source.getPath2(src_builder, step);
-    const full_dest_path = dest_builder.getInstallPath(self.dir, self.dest_rel_path);
+    const full_src_path = self.source.getPath2(b, step);
+    const full_dest_path = b.getInstallPath(self.dir, self.dest_rel_path);
     const cwd = std.fs.cwd();
     const prev = std.fs.Dir.updateFile(cwd, full_src_path, cwd, full_dest_path, .{}) catch |err| {
         return step.fail("unable to update file from '{s}' to '{s}': {s}", .{

lib/std/Build/Step/WriteFile.zig

@@ -15,9 +15,11 @@ const ArrayList = std.ArrayList;
 const WriteFile = @This();
 
 step: Step,
-/// The elements here are pointers because we need stable pointers for the
-/// GeneratedFile field.
+
+// The elements here are pointers because we need stable pointers for the GeneratedFile field.
 files: std.ArrayListUnmanaged(*File),
+directories: std.ArrayListUnmanaged(*Directory),
+
 output_source_files: std.ArrayListUnmanaged(OutputSourceFile),
 generated_directory: std.Build.GeneratedFile,
 
@@ -33,6 +35,33 @@ pub const File = struct {
     }
 };
 
+pub const Directory = struct {
+    source: std.Build.LazyPath,
+    sub_path: []const u8,
+    options: Options,
+    generated_dir: std.Build.GeneratedFile,
+
+    pub const Options = struct {
+        /// File paths that end in any of these suffixes will be excluded from copying.
+        exclude_extensions: []const []const u8 = &.{},
+        /// Only file paths that end in any of these suffixes will be included in copying.
+        /// `null` means that all suffixes will be included.
+        /// `exclude_extensions` takes precedence over `include_extensions`.
+        include_extensions: ?[]const []const u8 = null,
+
+        pub fn dupe(self: Options, b: *std.Build) Options {
+            return .{
+                .exclude_extensions = b.dupeStrings(self.exclude_extensions),
+                .include_extensions = if (self.include_extensions) |incs| b.dupeStrings(incs) else null,
+            };
+        }
+    };
+
+    pub fn getPath(self: *Directory) std.Build.LazyPath {
+        return .{ .generated = &self.generated_dir };
+    }
+};
+
 pub const OutputSourceFile = struct {
     contents: Contents,
     sub_path: []const u8,
@@ -53,6 +82,7 @@ pub fn create(owner: *std.Build) *WriteFile {
             .makeFn = make,
         }),
         .files = .{},
+        .directories = .{},
         .output_source_files = .{},
         .generated_directory = .{ .step = &wf.step },
     };
@@ -96,6 +126,31 @@ pub fn addCopyFile(wf: *WriteFile, source: std.Build.LazyPath, sub_path: []const
     return file.getPath();
 }
 
+/// Copy files matching the specified exclude/include patterns to the specified subdirectory
+/// relative to this step's generated directory.
+/// The returned value is a lazy path to the generated subdirectory.
+pub fn addCopyDirectory(
+    wf: *WriteFile,
+    source: std.Build.LazyPath,
+    sub_path: []const u8,
+    options: Directory.Options,
+) std.Build.LazyPath {
+    const b = wf.step.owner;
+    const gpa = b.allocator;
+    const dir = gpa.create(Directory) catch @panic("OOM");
+    dir.* = .{
+        .source = source.dupe(b),
+        .sub_path = b.dupePath(sub_path),
+        .options = options.dupe(b),
+        .generated_dir = .{ .step = &wf.step },
+    };
+    wf.directories.append(gpa, dir) catch @panic("OOM");
+
+    wf.maybeUpdateName();
+    source.addStepDependencies(&wf.step);
+    return dir.getPath();
+}
+
 /// A path relative to the package root.
 /// Be careful with this because it updates source files. This should not be
 /// used as part of the normal build process, but as a utility occasionally
@@ -130,11 +185,16 @@ pub fn getDirectory(wf: *WriteFile) std.Build.LazyPath {
 }
 
 fn maybeUpdateName(wf: *WriteFile) void {
-    if (wf.files.items.len == 1) {
+    if (wf.files.items.len == 1 and wf.directories.items.len == 0) {
         // First time adding a file; update name.
         if (std.mem.eql(u8, wf.step.name, "WriteFile")) {
             wf.step.name = wf.step.owner.fmt("WriteFile {s}", .{wf.files.items[0].sub_path});
         }
+    } else if (wf.directories.items.len == 1 and wf.files.items.len == 0) {
+        // First time adding a directory; update name.
+        if (std.mem.eql(u8, wf.step.name, "WriteFile")) {
+            wf.step.name = wf.step.owner.fmt("WriteFile {s}", .{wf.directories.items[0].sub_path});
+        }
     }
 }
 
@@ -209,6 +269,12 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
             },
         }
     }
+    for (wf.directories.items) |dir| {
+        man.hash.addBytes(dir.source.getPath2(b, step));
+        man.hash.addBytes(dir.sub_path);
+        for (dir.options.exclude_extensions) |ext| man.hash.addBytes(ext);
+        if (dir.options.include_extensions) |incs| for (incs) |inc| man.hash.addBytes(inc);
+    }
 
     if (try step.cacheHit(&man)) {
         const digest = man.final();
@@ -233,6 +299,8 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
     };
     defer cache_dir.close();
 
+    const cwd = fs.cwd();
+
     for (wf.files.items) |file| {
         if (fs.path.dirname(file.sub_path)) |dirname| {
             cache_dir.makePath(dirname) catch |err| {
@@ -252,7 +320,7 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
             .copy => |file_source| {
                 const source_path = file_source.getPath(b);
                 const prev_status = fs.Dir.updateFile(
-                    fs.cwd(),
+                    cwd,
                     source_path,
                     cache_dir,
                     file.sub_path,
@@ -279,6 +347,64 @@ fn make(step: *Step, prog_node: *std.Progress.Node) !void {
             cache_path, file.sub_path,
         });
     }
+    for (wf.directories.items) |dir| {
+        const full_src_dir_path = dir.source.getPath2(b, step);
+        const dest_dirname = dir.sub_path;
+
+        if (dest_dirname.len != 0) {
+            cache_dir.makePath(dest_dirname) catch |err| {
+                return step.fail("unable to make path '{}{s}{c}{s}': {s}", .{
+                    b.cache_root, cache_path, fs.path.sep, dest_dirname, @errorName(err),
+                });
+            };
+        }
+
+        var src_dir = b.build_root.handle.openDir(full_src_dir_path, .{ .iterate = true }) catch |err| {
+            return step.fail("unable to open source directory '{s}': {s}", .{
+                full_src_dir_path, @errorName(err),
+            });
+        };
+        defer src_dir.close();
+
+        var it = try src_dir.walk(b.allocator);
+        next_entry: while (try it.next()) |entry| {
+            for (dir.options.exclude_extensions) |ext| {
+                if (std.mem.endsWith(u8, entry.path, ext)) continue :next_entry;
+            }
+            if (dir.options.include_extensions) |incs| {
+                for (incs) |inc| {
+                    if (std.mem.endsWith(u8, entry.path, inc)) break;
+                } else {
+                    continue :next_entry;
+                }
+            }
+            const full_src_entry_path = b.pathJoin(&.{ full_src_dir_path, entry.path });
+            const dest_path = b.pathJoin(&.{ dest_dirname, entry.path });
+            switch (entry.kind) {
+                .directory => try cache_dir.makePath(dest_path),
+                .file => {
+                    const prev_status = fs.Dir.updateFile(
+                        cwd,
+                        full_src_entry_path,
+                        cache_dir,
+                        dest_path,
+                        .{},
+                    ) catch |err| {
+                        return step.fail("unable to update file from '{s}' to '{}{s}{c}{s}': {s}", .{
+                            full_src_entry_path,
+                            b.cache_root,
+                            cache_path,
+                            fs.path.sep,
+                            dest_path,
+                            @errorName(err),
+                        });
+                    };
+                    _ = prev_status;
+                },
+                else => continue,
+            }
+        }
+    }
 
     try step.writeManifest(&man);
 }

test/standalone.zig

@@ -266,6 +266,10 @@ pub const build_cases = [_]BuildCase{
         .build_root = "test/standalone/depend_on_main_mod",
         .import = @import("standalone/depend_on_main_mod/build.zig"),
     },
+    .{
+        .build_root = "test/standalone/install_headers",
+        .import = @import("standalone/install_headers/build.zig"),
+    },
 };
 
 const std = @import("std");

test/standalone/install_headers/build.zig

@@ -0,0 +1,99 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const test_step = b.step("test", "Test");
+    b.default_step = test_step;
+
+    const empty_c = b.addWriteFiles().add("empty.c", "");
+
+    const libfoo = b.addStaticLibrary(.{
+        .name = "foo",
+        .target = b.resolveTargetQuery(.{}),
+        .optimize = .Debug,
+    });
+    libfoo.addCSourceFile(.{ .file = empty_c });
+
+    const exe = b.addExecutable(.{
+        .name = "exe",
+        .target = b.resolveTargetQuery(.{}),
+        .optimize = .Debug,
+        .link_libc = true,
+    });
+    exe.addCSourceFile(.{ .file = b.addWriteFiles().add("main.c",
+        \\#include <stdio.h>
+        \\#include <foo/a.h>
+        \\#include <foo/sub_dir/b.h>
+        \\#include <foo/d.h>
+        \\#include <foo/config.h>
+        \\#include <bar.h>
+        \\int main(void) {
+        \\    printf(FOO_A FOO_B FOO_D FOO_CONFIG_1 FOO_CONFIG_2 BAR_X);
+        \\    return 0;
+        \\}
+    ) });
+
+    libfoo.installHeadersDirectory(.{ .path = "include" }, "foo", .{ .exclude_extensions = &.{".ignore_me.h"} });
+    libfoo.installHeader(b.addWriteFiles().add("d.h",
+        \\#define FOO_D "D"
+        \\
+    ), "foo/d.h");
+
+    if (libfoo.installed_headers_include_tree != null) std.debug.panic("include tree step was created before linking", .{});
+
+    // Link before we have registered all headers for installation,
+    // to verify that the lazily created write files step is properly taken into account.
+    exe.linkLibrary(libfoo);
+
+    if (libfoo.installed_headers_include_tree == null) std.debug.panic("include tree step was not created after linking", .{});
+
+    libfoo.installConfigHeader(b.addConfigHeader(.{
+        .style = .blank,
+        .include_path = "foo/config.h",
+    }, .{
+        .FOO_CONFIG_1 = "1",
+        .FOO_CONFIG_2 = "2",
+    }));
+
+    const libbar = b.addStaticLibrary(.{
+        .name = "bar",
+        .target = b.resolveTargetQuery(.{}),
+        .optimize = .Debug,
+    });
+    libbar.addCSourceFile(.{ .file = empty_c });
+    libbar.installHeader(b.addWriteFiles().add("bar.h",
+        \\#define BAR_X "X"
+        \\
+    ), "bar.h");
+    libfoo.installLibraryHeaders(libbar);
+
+    const run_exe = b.addRunArtifact(exe);
+    run_exe.expectStdOutEqual("ABD12X");
+    test_step.dependOn(&run_exe.step);
+
+    const install_libfoo = b.addInstallArtifact(libfoo, .{
+        .dest_dir = .{ .override = .{ .custom = "custom" } },
+        .h_dir = .{ .override = .{ .custom = "custom/include" } },
+        .implib_dir = .disabled,
+        .pdb_dir = .disabled,
+    });
+    const check_exists = b.addExecutable(.{
+        .name = "check_exists",
+        .root_source_file = .{ .path = "check_exists.zig" },
+        .target = b.resolveTargetQuery(.{}),
+        .optimize = .Debug,
+    });
+    const run_check_exists = b.addRunArtifact(check_exists);
+    run_check_exists.addArgs(&.{
+        "custom/include/foo/a.h",
+        "!custom/include/foo/ignore_me.txt",
+        "custom/include/foo/sub_dir/b.h",
+        "!custom/include/foo/sub_dir/c.ignore_me.h",
+        "custom/include/foo/d.h",
+        "custom/include/foo/config.h",
+        "custom/include/bar.h",
+    });
+    run_check_exists.setCwd(.{ .cwd_relative = b.getInstallPath(.prefix, "") });
+    run_check_exists.expectExitCode(0);
+    run_check_exists.step.dependOn(&install_libfoo.step);
+    test_step.dependOn(&run_check_exists.step);
+}

test/standalone/install_headers/check_exists.zig

@@ -0,0 +1,37 @@
+const std = @import("std");
+
+/// Checks the existence of files relative to cwd.
+/// A path starting with ! should not exist.
+pub fn main() !void {
+    var arena_state = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+    defer arena_state.deinit();
+
+    const arena = arena_state.allocator();
+
+    var arg_it = try std.process.argsWithAllocator(arena);
+    _ = arg_it.next();
+
+    const cwd = std.fs.cwd();
+    const cwd_realpath = try cwd.realpathAlloc(arena, ".");
+
+    while (arg_it.next()) |file_path| {
+        if (file_path.len > 0 and file_path[0] == '!') {
+            errdefer std.log.err(
+                "exclusive file check '{s}{c}{s}' failed",
+                .{ cwd_realpath, std.fs.path.sep, file_path[1..] },
+            );
+            if (std.fs.cwd().statFile(file_path[1..])) |_| {
+                return error.FileFound;
+            } else |err| switch (err) {
+                error.FileNotFound => {},
+                else => return err,
+            }
+        } else {
+            errdefer std.log.err(
+                "inclusive file check '{s}{c}{s}' failed",
+                .{ cwd_realpath, std.fs.path.sep, file_path },
+            );
+            _ = try std.fs.cwd().statFile(file_path);
+        }
+    }
+}

test/standalone/install_headers/include/a.h

@@ -0,0 +1 @@
+#define FOO_A "A"

test/standalone/install_headers/include/ignore_me.txt

@@ -0,0 +1 @@
+ignore me

test/standalone/install_headers/include/sub_dir/b.h

@@ -0,0 +1 @@
+#define FOO_B "B"

test/standalone/install_headers/include/sub_dir/c.ignore_me.h

@@ -0,0 +1 @@
+#error "ignore me"