| ... | @@ -10808,6 +10808,9 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/'; | ... | @@ -10808,6 +10808,9 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/'; |
| 10808 | Some examples of tasks the build system can help with: | 10808 | Some examples of tasks the build system can help with: |
| 10809 | </p> | 10809 | </p> |
| 10810 | <ul> | 10810 | <ul> |
| | 10811 | <li>Performing tasks in parallel and caching the results.</li> |
| | 10812 | <li>Depending on other projects.</li> |
| | 10813 | <li>Providing a package for other projects to depend on.</li> |
| 10811 | <li>Creating build artifacts by executing the Zig compiler. This includes | 10814 | <li>Creating build artifacts by executing the Zig compiler. This includes |
| 10812 | building Zig source code as well as C and C++ source code.</li> | 10815 | building Zig source code as well as C and C++ source code.</li> |
| 10813 | <li>Capturing user-configured options and using those options to configure | 10816 | <li>Capturing user-configured options and using those options to configure |
| ... | @@ -10826,148 +10829,10 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/'; | ... | @@ -10826,148 +10829,10 @@ const separator = if (builtin.os.tag == .windows) '\\' else '/'; |
| 10826 | to see a command-line usage help menu. This will include project-specific | 10829 | to see a command-line usage help menu. This will include project-specific |
| 10827 | options that were declared in the build.zig script. | 10830 | options that were declared in the build.zig script. |
| 10828 | </p> | 10831 | </p> |
| 10829 | | 10832 | <p> |
| 10830 | {#header_open|Building an Executable#} | 10833 | For the time being, the build system documentation is hosted externally: |
| 10831 | <p>This <code class="file">build.zig</code> file is automatically generated | 10834 | <a href="https://ziglang.org/learn/build-system/">Build System Documentation</a> |
| 10832 | by <kbd>zig init-exe</kbd>.</p> | 10835 | </p> |
| 10833 | {#code_begin|syntax|build_executable#} | | |
| 10834 | const std = @import("std"); | | |
| 10835 | | | |
| 10836 | // Although this function looks imperative, note that its job is to | | |
| 10837 | // declaratively construct a build graph that will be executed by an external | | |
| 10838 | // runner. | | |
| 10839 | pub fn build(b: *std.Build) void { | | |
| 10840 | // Standard target options allows the person running `zig build` to choose | | |
| 10841 | // what target to build for. Here we do not override the defaults, which | | |
| 10842 | // means any target is allowed, and the default is native. Other options | | |
| 10843 | // for restricting supported target set are available. | | |
| 10844 | const target = b.standardTargetOptions(.{}); | | |
| 10845 | | | |
| 10846 | // Standard optimization options allow the person running `zig build` to select | | |
| 10847 | // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not | | |
| 10848 | // set a preferred release mode, allowing the user to decide how to optimize. | | |
| 10849 | const optimize = b.standardOptimizeOption(.{}); | | |
| 10850 | | | |
| 10851 | const exe = b.addExecutable(.{ | | |
| 10852 | .name = "example", | | |
| 10853 | // In this case the main source file is merely a path, however, in more | | |
| 10854 | // complicated build scripts, this could be a generated file. | | |
| 10855 | .root_source_file = .{ .path = "src/main.zig" }, | | |
| 10856 | .target = target, | | |
| 10857 | .optimize = optimize, | | |
| 10858 | }); | | |
| 10859 | | | |
| 10860 | // This declares intent for the executable to be installed into the | | |
| 10861 | // standard location when the user invokes the "install" step (the default | | |
| 10862 | // step when running `zig build`). | | |
| 10863 | b.installArtifact(exe); | | |
| 10864 | | | |
| 10865 | // This *creates* a Run step in the build graph, to be executed when another | | |
| 10866 | // step is evaluated that depends on it. The next line below will establish | | |
| 10867 | // such a dependency. | | |
| 10868 | const run_cmd = b.addRunArtifact(exe); | | |
| 10869 | | | |
| 10870 | // By making the run step depend on the install step, it will be run from the | | |
| 10871 | // installation directory rather than directly from within the cache directory. | | |
| 10872 | // This is not necessary, however, if the application depends on other installed | | |
| 10873 | // files, this ensures they will be present and in the expected location. | | |
| 10874 | run_cmd.step.dependOn(b.getInstallStep()); | | |
| 10875 | | | |
| 10876 | // This allows the user to pass arguments to the application in the build | | |
| 10877 | // command itself, like this: `zig build run -- arg1 arg2 etc` | | |
| 10878 | if (b.args) |args| { | | |
| 10879 | run_cmd.addArgs(args); | | |
| 10880 | } | | |
| 10881 | | | |
| 10882 | // This creates a build step. It will be visible in the `zig build --help` menu, | | |
| 10883 | // and can be selected like this: `zig build run` | | |
| 10884 | // This will evaluate the `run` step rather than the default, which is "install". | | |
| 10885 | const run_step = b.step("run", "Run the app"); | | |
| 10886 | run_step.dependOn(&run_cmd.step); | | |
| 10887 | | | |
| 10888 | // Creates a step for unit testing. This only builds the test executable | | |
| 10889 | // but does not run it. | | |
| 10890 | const unit_tests = b.addTest(.{ | | |
| 10891 | .root_source_file = .{ .path = "src/main.zig" }, | | |
| 10892 | .target = target, | | |
| 10893 | .optimize = optimize, | | |
| 10894 | }); | | |
| 10895 | | | |
| 10896 | const run_unit_tests = b.addRunArtifact(unit_tests); | | |
| 10897 | | | |
| 10898 | // Similar to creating the run step earlier, this exposes a `test` step to | | |
| 10899 | // the `zig build --help` menu, providing a way for the user to request | | |
| 10900 | // running the unit tests. | | |
| 10901 | const test_step = b.step("test", "Run unit tests"); | | |
| 10902 | test_step.dependOn(&run_unit_tests.step); | | |
| 10903 | } | | |
| 10904 | {#code_end#} | | |
| 10905 | {#header_close#} | | |
| 10906 | | | |
| 10907 | {#header_open|Building a Library#} | | |
| 10908 | <p>This <code class="file">build.zig</code> file is automatically generated | | |
| 10909 | by <kbd>zig init-lib</kbd>.</p> | | |
| 10910 | {#code_begin|syntax|build_library#} | | |
| 10911 | const std = @import("std"); | | |
| 10912 | | | |
| 10913 | // Although this function looks imperative, note that its job is to | | |
| 10914 | // declaratively construct a build graph that will be executed by an external | | |
| 10915 | // runner. | | |
| 10916 | pub fn build(b: *std.Build) void { | | |
| 10917 | // Standard target options allows the person running `zig build` to choose | | |
| 10918 | // what target to build for. Here we do not override the defaults, which | | |
| 10919 | // means any target is allowed, and the default is native. Other options | | |
| 10920 | // for restricting supported target set are available. | | |
| 10921 | const target = b.standardTargetOptions(.{}); | | |
| 10922 | | | |
| 10923 | // Standard optimization options allow the person running `zig build` to select | | |
| 10924 | // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. Here we do not | | |
| 10925 | // set a preferred release mode, allowing the user to decide how to optimize. | | |
| 10926 | const optimize = b.standardOptimizeOption(.{}); | | |
| 10927 | | | |
| 10928 | const lib = b.addStaticLibrary(.{ | | |
| 10929 | .name = "example", | | |
| 10930 | // In this case the main source file is merely a path, however, in more | | |
| 10931 | // complicated build scripts, this could be a generated file. | | |
| 10932 | .root_source_file = .{ .path = "src/main.zig" }, | | |
| 10933 | .target = target, | | |
| 10934 | .optimize = optimize, | | |
| 10935 | }); | | |
| 10936 | | | |
| 10937 | // This declares intent for the library to be installed into the standard | | |
| 10938 | // location when the user invokes the "install" step (the default step when | | |
| 10939 | // running `zig build`). | | |
| 10940 | b.installArtifact(lib); | | |
| 10941 | | | |
| 10942 | // Creates a step for unit testing. This only builds the test executable | | |
| 10943 | // but does not run it. | | |
| 10944 | const main_tests = b.addTest(.{ | | |
| 10945 | .root_source_file = .{ .path = "src/main.zig" }, | | |
| 10946 | .target = target, | | |
| 10947 | .optimize = optimize, | | |
| 10948 | }); | | |
| 10949 | | | |
| 10950 | const run_main_tests = b.addRunArtifact(main_tests); | | |
| 10951 | | | |
| 10952 | // This creates a build step. It will be visible in the `zig build --help` menu, | | |
| 10953 | // and can be selected like this: `zig build test` | | |
| 10954 | // This will evaluate the `test` step rather than the default, which is "install". | | |
| 10955 | const test_step = b.step("test", "Run library tests"); | | |
| 10956 | test_step.dependOn(&run_main_tests.step); | | |
| 10957 | } | | |
| 10958 | {#code_end#} | | |
| 10959 | {#header_close#} | | |
| 10960 | | | |
| 10961 | {#header_open|Compiling C Source Code#} | | |
| 10962 | <pre>{#syntax#} | | |
| 10963 | lib.addCSourceFile(.{ .file = .{ .path = "src/lib.c" }, .flags = &.{ | | |
| 10964 | "-Wall", | | |
| 10965 | "-Wextra", | | |
| 10966 | "-Werror", | | |
| 10967 | } }); | | |
| 10968 | {#endsyntax#}</pre> | | |
| 10969 | {#header_close#} | | |
| 10970 | | | |
| 10971 | {#header_close#} | 10836 | {#header_close#} |
| 10972 | {#header_open|C#} | 10837 | {#header_open|C#} |
| 10973 | <p> | 10838 | <p> |
Andrew Kelley <andrew@ziglang.org> 2024-01-18 21:14:44-07:00