std.Build: add precompiled C header creation

adds a new mode to the Compile step.
It shares most of the code with previous compile steps, but with extra constraints expressed by assert checks.

Author: xxxbxxx

lib/std/Build.zig

@@ -748,6 +748,31 @@ pub fn addObject(b: *Build, options: ObjectOptions) *Step.Compile {
     });
 }
 
+pub const PchOptions = struct {
+    name: []const u8,
+    target: ResolvedTarget,
+    optimize: std.builtin.OptimizeMode,
+    max_rss: usize = 0,
+    link_libc: ?bool = null,
+    link_libcpp: ?bool = null,
+};
+
+pub fn addPrecompiledCHeader(b: *Build, options: PchOptions, source: Module.CSourceFile) *Step.Compile {
+    const pch = Step.Compile.create(b, .{
+        .name = options.name,
+        .root_module = .{
+            .target = options.target,
+            .optimize = options.optimize,
+            .link_libc = options.link_libc,
+            .link_libcpp = options.link_libcpp,
+        },
+        .kind = .pch,
+        .max_rss = options.max_rss,
+    });
+    pch.addCSourceFile(source);
+    return pch;
+}
+
 pub const SharedLibraryOptions = struct {
     name: []const u8,
     /// To choose the same computer as the one building the package, pass the

lib/std/Build/Step/Compile.zig

@@ -273,6 +273,7 @@ pub const Kind = enum {
     exe,
     lib,
     obj,
+    pch,
     @"test",
 };
 
@@ -356,24 +357,29 @@ pub fn create(owner: *std.Build, options: Options) *Compile {
             .exe => "zig build-exe",
             .lib => "zig build-lib",
             .obj => "zig build-obj",
+            .pch => "zig build-pch",
             .@"test" => "zig test",
         },
         name_adjusted,
         @tagName(options.root_module.optimize orelse .Debug),
         resolved_target.query.zigTriple(owner.allocator) catch @panic("OOM"),
     });
 
-    const out_filename = std.zig.binNameAlloc(owner.allocator, .{
-        .root_name = name,
-        .target = target,
-        .output_mode = switch (options.kind) {
-            .lib => .Lib,
-            .obj => .Obj,
-            .exe, .@"test" => .Exe,
-        },
-        .link_mode = options.linkage,
-        .version = options.version,
-    }) catch @panic("OOM");
+    const out_filename = if (options.kind == .pch)
+        std.fmt.allocPrint(owner.allocator, "{s}.pch", .{name}) catch @panic("OOM")
+    else
+        std.zig.binNameAlloc(owner.allocator, .{
+            .root_name = name,
+            .target = target,
+            .output_mode = switch (options.kind) {
+                .lib => .Lib,
+                .obj => .Obj,
+                .exe, .@"test" => .Exe,
+                .pch => unreachable,
+            },
+            .link_mode = options.linkage,
+            .version = options.version,
+        }) catch @panic("OOM");
 
     const compile = owner.allocator.create(Compile) catch @panic("OOM");
     compile.* = .{
@@ -802,17 +808,20 @@ pub fn linkFrameworkWeak(c: *Compile, name: []const u8) void {
 
 /// Handy when you have many C/C++ source files and want them all to have the same flags.
 pub fn addCSourceFiles(compile: *Compile, options: Module.AddCSourceFilesOptions) void {
+    assert(compile.kind != .pch); // pch can only be generated from a single C header file
     compile.root_module.addCSourceFiles(options);
 }
 
 pub fn addCSourceFile(compile: *Compile, source: Module.CSourceFile) void {
+    assert(compile.kind != .pch or compile.root_module.link_objects.items.len == 0); // pch can only be generated from a single C header file
     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.
 pub fn addWin32ResourceFile(compile: *Compile, source: Module.RcSourceFile) void {
+    assert(compile.kind != .pch); // pch can only be generated from a single C header file
     compile.root_module.addWin32ResourceFile(source);
 }
 
@@ -893,14 +902,17 @@ pub fn getEmittedLlvmBc(compile: *Compile) LazyPath {
 }
 
 pub fn addAssemblyFile(compile: *Compile, source: Module.AsmSourceFile) void {
+    assert(compile.kind != .pch); // pch can only be generated from a single C header file
     compile.root_module.addAssemblyFile(source);
 }
 
 pub fn addObjectFile(compile: *Compile, source: LazyPath) void {
+    assert(compile.kind != .pch); // pch can only be generated from a single C header file
     compile.root_module.addObjectFile(source);
 }
 
 pub fn addObject(compile: *Compile, object: *Compile) void {
+    assert(compile.kind != .pch); // pch can only be generated from a single C header file
     compile.root_module.addObject(object);
 }
 
@@ -1025,6 +1037,7 @@ fn getZigArgs(compile: *Compile, fuzz: bool) ![][]const u8 {
         .lib => "build-lib",
         .exe => "build-exe",
         .obj => "build-obj",
+        .pch => "build-pch",
         .@"test" => "test",
     };
     try zig_args.append(cmd);
@@ -1092,6 +1105,14 @@ fn getZigArgs(compile: *Compile, fuzz: bool) ![][]const u8 {
             }
         }
 
+        if (compile.kind == .pch) {
+            // precompiled headers must have a single input header file.
+            var it = compile.root_module.iterateDependencies(compile, false);
+            const link_objects = it.next().?.module.link_objects;
+            assert(link_objects.items.len == 1 and link_objects.items[0] == .c_source_file);
+            assert(it.next() == null);
+        }
+
         var cli_named_modules = try CliNamedModules.init(arena, &compile.root_module);
 
         // For this loop, don't chase dynamic libraries because their link
@@ -1203,6 +1224,7 @@ fn getZigArgs(compile: *Compile, fuzz: bool) ![][]const u8 {
                         switch (other.kind) {
                             .exe => return step.fail("cannot link with an executable build artifact", .{}),
                             .@"test" => return step.fail("cannot link with a test", .{}),
+                            .pch => @panic("Cannot link with a precompiled header file"),
                             .obj => {
                                 const included_in_lib_or_obj = !my_responsibility and
                                     (dep.compile.?.kind == .lib or dep.compile.?.kind == .obj);

lib/std/Build/Step/InstallArtifact.zig

@@ -56,7 +56,7 @@ pub fn create(owner: *std.Build, artifact: *Step.Compile, options: Options) *Ins
     const dest_dir: ?InstallDir = switch (options.dest_dir) {
         .disabled => null,
         .default => switch (artifact.kind) {
-            .obj => @panic("object files have no standard installation procedure"),
+            .obj, .pch => @panic("object files have no standard installation procedure"),
             .exe, .@"test" => .bin,
             .lib => if (artifact.isDll()) .bin else .lib,
         },