| ... | ... | @@ -3249,6 +3249,31 @@ fn makeNumber() Number { |
| 3249 | 3249 | |
| 3250 | 3250 | {#header_close#} |
| 3251 | 3251 | |
| 3252 | {#header_open|opaque#} |
| 3253 | <p> |
| 3254 | {#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment. |
| 3255 | It can contain declarations the same as {#link|structs|struct#}, {#link|unions|union#}, |
| 3256 | and {#link|enums|enum#}. |
| 3257 | </p> |
| 3258 | <p> |
| 3259 | This is typically used for type safety when interacting with C code that does not expose struct details. |
| 3260 | Example: |
| 3261 | </p> |
| 3262 | {#code_begin|test_err|expected type '*Derp', found '*Wat'#} |
| 3263 | const Derp = opaque {}; |
| 3264 | const Wat = opaque {}; |
| 3265 | |
| 3266 | extern fn bar(d: *Derp) void; |
| 3267 | fn foo(w: *Wat) callconv(.C) void { |
| 3268 | bar(w); |
| 3269 | } |
| 3270 | |
| 3271 | test "call foo" { |
| 3272 | foo(undefined); |
| 3273 | } |
| 3274 | {#code_end#} |
| 3275 | {#header_close#} |
| 3276 | |
| 3252 | 3277 | {#header_open|blocks#} |
| 3253 | 3278 | <p> |
| 3254 | 3279 | Blocks are used to limit the scope of variable declarations: |
| ... | ... | @@ -8547,30 +8572,6 @@ fn foo(comptime T: type, ptr: *T) T { |
| 8547 | 8572 | {#header_close#} |
| 8548 | 8573 | {#header_close#} |
| 8549 | 8574 | |
| 8550 | | {#header_open|opaque#} |
| 8551 | | <p> |
| 8552 | | {#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment. |
| 8553 | | It can have declarations like structs, unions, or enums. |
| 8554 | | </p> |
| 8555 | | <p> |
| 8556 | | This is typically used for type safety when interacting with C code that does not expose struct details. |
| 8557 | | Example: |
| 8558 | | </p> |
| 8559 | | {#code_begin|test_err|expected type '*Derp', found '*Wat'#} |
| 8560 | | const Derp = opaque {}; |
| 8561 | | const Wat = opaque {}; |
| 8562 | | |
| 8563 | | extern fn bar(d: *Derp) void; |
| 8564 | | fn foo(w: *Wat) callconv(.C) void { |
| 8565 | | bar(w); |
| 8566 | | } |
| 8567 | | |
| 8568 | | test "call foo" { |
| 8569 | | foo(undefined); |
| 8570 | | } |
| 8571 | | {#code_end#} |
| 8572 | | {#header_close#} |
| 8573 | | |
| 8574 | 8575 | {#header_open|Build Mode#} |
| 8575 | 8576 | <p> |
| 8576 | 8577 | Zig has four build modes: |
| ... | ... | @@ -9625,10 +9626,102 @@ test "assert in release fast mode" { |
| 9625 | 9626 | isolation. |
| 9626 | 9627 | </p> |
| 9627 | 9628 | {#header_close#} |
| 9629 | |
| 9628 | 9630 | {#header_open|Zig Build System#} |
| 9629 | | <p>TODO: explain purpose, it's supposed to replace make/cmake</p> |
| 9630 | | <p>TODO: example of building a zig executable</p> |
| 9631 | | <p>TODO: example of building a C library</p> |
| 9631 | <p> |
| 9632 | The Zig Build System provides a cross-platform, dependency-free way to declare |
| 9633 | the logic required to build a project. With this system, the logic to build |
| 9634 | a project is written in a build.zig file, using the Zig Build System API to |
| 9635 | declare and configure build artifacts and other tasks. |
| 9636 | </p> |
| 9637 | <p> |
| 9638 | Some examples of tasks the build system can help with: |
| 9639 | </p> |
| 9640 | <ul> |
| 9641 | <li>Creating build artifacts by executing the Zig compiler. This includes |
| 9642 | building Zig source code as well as C and C++ source code.</li> |
| 9643 | <li>Capturing user-configured options and using those options to configure |
| 9644 | the build.</li> |
| 9645 | <li>Surfacing build configuration as {#link|comptime#} values by providing a |
| 9646 | file that can be {#link|imported|@import#} by Zig code.</li> |
| 9647 | <li>Caching build artifacts to avoid unnecessarily repeating steps.</li> |
| 9648 | <li>Executing build artifacts or system-installed tools.</li> |
| 9649 | <li>Running tests and verifying the output of executing a build artifact matches |
| 9650 | the expected value.</li> |
| 9651 | <li>Running <code>zig fmt</code> on a codebase or a subset of it.</li> |
| 9652 | <li>Custom tasks.</li> |
| 9653 | </ul> |
| 9654 | <p> |
| 9655 | To use the build system, run <code class="shell">zig build --help</code> |
| 9656 | to see a command-line usage help menu. This will include project-specific |
| 9657 | options that were declared in the build.zig script. |
| 9658 | </p> |
| 9659 | |
| 9660 | {#header_open|Building an Executable#} |
| 9661 | <p>This <code>build.zig</code> file is automatically generated |
| 9662 | by <code>zig init-exe</code>.</p> |
| 9663 | {#code_begin|syntax|build#} |
| 9664 | const Builder = @import("std").build.Builder; |
| 9665 | |
| 9666 | pub fn build(b: *Builder) void { |
| 9667 | // Standard target options allows the person running `zig build` to choose |
| 9668 | // what target to build for. Here we do not override the defaults, which |
| 9669 | // means any target is allowed, and the default is native. Other options |
| 9670 | // for restricting supported target set are available. |
| 9671 | const target = b.standardTargetOptions(.{}); |
| 9672 | |
| 9673 | // Standard release options allow the person running `zig build` to select |
| 9674 | // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. |
| 9675 | const mode = b.standardReleaseOptions(); |
| 9676 | |
| 9677 | const exe = b.addExecutable("example", "src/main.zig"); |
| 9678 | exe.setTarget(target); |
| 9679 | exe.setBuildMode(mode); |
| 9680 | exe.install(); |
| 9681 | |
| 9682 | const run_cmd = exe.run(); |
| 9683 | run_cmd.step.dependOn(b.getInstallStep()); |
| 9684 | if (b.args) |args| { |
| 9685 | run_cmd.addArgs(args); |
| 9686 | } |
| 9687 | |
| 9688 | const run_step = b.step("run", "Run the app"); |
| 9689 | run_step.dependOn(&run_cmd.step); |
| 9690 | } |
| 9691 | {#code_end#} |
| 9692 | {#header_close#} |
| 9693 | |
| 9694 | {#header_open|Building a Library#} |
| 9695 | <p>This <code>build.zig</code> file is automatically generated |
| 9696 | by <code>zig init-lib</code>.</p> |
| 9697 | {#code_begin|syntax|build#} |
| 9698 | const Builder = @import("std").build.Builder; |
| 9699 | |
| 9700 | pub fn build(b: *Builder) void { |
| 9701 | const mode = b.standardReleaseOptions(); |
| 9702 | const lib = b.addStaticLibrary("example", "src/main.zig"); |
| 9703 | lib.setBuildMode(mode); |
| 9704 | lib.install(); |
| 9705 | |
| 9706 | var main_tests = b.addTest("src/main.zig"); |
| 9707 | main_tests.setBuildMode(mode); |
| 9708 | |
| 9709 | const test_step = b.step("test", "Run library tests"); |
| 9710 | test_step.dependOn(&main_tests.step); |
| 9711 | } |
| 9712 | {#code_end#} |
| 9713 | {#header_close#} |
| 9714 | |
| 9715 | {#header_open|Compiling C Source Code#} |
| 9716 | <pre>{#syntax#} |
| 9717 | lib.addCSourceFile("src/lib.c", &[_][]const u8{ |
| 9718 | "-Wall", |
| 9719 | "-Wextra", |
| 9720 | "-Werror", |
| 9721 | }); |
| 9722 | {#endsyntax#}</pre> |
| 9723 | {#header_close#} |
| 9724 | |
| 9632 | 9725 | {#header_close#} |
| 9633 | 9726 | {#header_open|C#} |
| 9634 | 9727 | <p> |
Andrew Kelley <andrew@ziglang.org> 2020-10-16 21:33:04-07:00