zig

commit d99e44a157dee9204c38e66bf7eba00c051690ba (tree)
parent 5af4e91e0036a5d83889d20ee1477a366c6c12ac
Author: Carl Åstholm <carl@astholm.se>
Date:   Sun, 10 Mar 2024 12:17:33 +0100

Document added/updated functions

Also renames `addHeaders` to `addHeadersDirectory` for clarity.

Diffstat:
M
lib/std/Build.zig
 | 
7
++++---
M
lib/std/Build/Step/Compile.zig
 | 
14
+++++++++++++-
M
lib/std/Build/Step/WriteFile.zig
 | 
3
+++
M
test/standalone/install_headers/build.zig
 | 
2
+-

4 files changed, 21 insertions(+), 5 deletions(-)
diff --git a/lib/std/Build.zig b/lib/std/Build.zig
@@ -1568,21 +1568,22 @@ 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
+/// `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
+/// `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
+/// `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);
 }
 
+/// `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);
 }
diff --git a/lib/std/Build/Step/Compile.zig b/lib/std/Build/Step/Compile.zig
@@ -446,6 +446,9 @@ pub fn create(owner: *std.Build, options: Options) *Compile {
     return self;
 }
 
+/// 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 installation: HeaderInstallation = .{ .file = .{
@@ -457,7 +460,10 @@ pub fn installHeader(cs: *Compile, source: LazyPath, dest_rel_path: []const u8) 
     installation.getSource().addStepDependencies(&cs.step);
 }
 
-pub fn installHeaders(
+/// 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(
     cs: *Compile,
     source: LazyPath,
     dest_rel_path: []const u8,
@@ -474,10 +480,16 @@ pub fn installHeaders(
     installation.getSource().addStepDependencies(&cs.step);
 }
 
+/// 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);
     const b = cs.step.owner;
diff --git a/lib/std/Build/Step/WriteFile.zig b/lib/std/Build/Step/WriteFile.zig
@@ -126,6 +126,9 @@ 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,
diff --git a/test/standalone/install_headers/build.zig b/test/standalone/install_headers/build.zig
@@ -32,7 +32,7 @@ pub fn build(b: *std.Build) void {
         \\}
     ) });
 
-    libfoo.installHeaders(.{ .path = "include" }, "foo", .{ .exclude_extensions = &.{".ignore_me.h"} });
+    libfoo.installHeadersDirectory(.{ .path = "include" }, "foo", .{ .exclude_extensions = &.{".ignore_me.h"} });
     libfoo.installHeader(b.addWriteFiles().add("d.h",
         \\#define FOO_D "D"
         \\