authorgravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2020-10-16 21:29:33-07:00
committergravatar for andrew@ziglang.orgAndrew Kelley <andrew@ziglang.org> 2020-10-16 21:29:33-07:00
log9ca8bcb4d928da4a50e9970d4335317725744f72
tree22e8c4533ee2498d9a42f7daf7749e140e79224d
parenteb80cc2b9ee687313dda77e9c3b328a882ae849e

langref cleanups

* move the opaque section to after struct, enum, union, and add hyperlinks * improve the introduction of the zig build system. don't link to the wiki. * update to the latest zig init-exe example code * rename headers to avoid redundant words such as "zig" * simplify example code

1 files changed, 78 insertions(+), 76 deletions(-)

doc/langref.html.in+78-76
...@@ -3249,6 +3249,31 @@ fn makeNumber() Number {...@@ -3249,6 +3249,31 @@ fn makeNumber() Number {
32493249
3250 {#header_close#}3250 {#header_close#}
32513251
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'#}
3263const Derp = opaque {};
3264const Wat = opaque {};
3265
3266extern fn bar(d: *Derp) void;
3267fn foo(w: *Wat) callconv(.C) void {
3268 bar(w);
3269}
3270
3271test "call foo" {
3272 foo(undefined);
3273}
3274 {#code_end#}
3275 {#header_close#}
3276
3252 {#header_open|blocks#}3277 {#header_open|blocks#}
3253 <p>3278 <p>
3254 Blocks are used to limit the scope of variable declarations:3279 Blocks are used to limit the scope of variable declarations:
...@@ -8547,31 +8572,6 @@ fn foo(comptime T: type, ptr: *T) T {...@@ -8547,31 +8572,6 @@ fn foo(comptime T: type, ptr: *T) T {
8547 {#header_close#}8572 {#header_close#}
8548 {#header_close#}8573 {#header_close#}
85498574
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 contain declarations the same as {#link|structs|struct#}, {#link|unions|union#},
8554 and {#link|enums|enum#}.
8555 </p>
8556 <p>
8557 This is typically used for type safety when interacting with C code that does not expose struct details.
8558 Example:
8559 </p>
8560 {#code_begin|test_err|expected type '*Derp', found '*Wat'#}
8561const Derp = opaque {};
8562const Wat = opaque {};
8563
8564extern fn bar(d: *Derp) void;
8565fn foo(w: *Wat) callconv(.C) void {
8566 bar(w);
8567}
8568
8569test "call foo" {
8570 foo(undefined);
8571}
8572 {#code_end#}
8573 {#header_close#}
8574
8575 {#header_open|Build Mode#}8575 {#header_open|Build Mode#}
8576 <p>8576 <p>
8577 Zig has four build modes:8577 Zig has four build modes:
...@@ -9626,24 +9626,38 @@ test "assert in release fast mode" {...@@ -9626,24 +9626,38 @@ test "assert in release fast mode" {
9626 isolation.9626 isolation.
9627 </p>9627 </p>
9628 {#header_close#}9628 {#header_close#}
9629 {#header_open|Zig Build System#}
96309629
9631 <p>Simple programs can be built with {#syntax#}zig9630 {#header_open|Zig Build System#}
9632 build-exe{#endsyntax#} and {#syntax#}zig build-lib{#endsyntax#},9631 <p>
9633 but running those commands manually gets tedious and error9632 The Zig Build System provides a cross-platform, dependency-free way to declare
9634 prone. Zig's build system lets you keep all the command line9633 the logic required to build a project. With this system, the logic to build
9635 switches and build modes in one place. It has no external9634 a project is written in a build.zig file, using the Zig Build System API to
9636 dependencies, so Zig code can be built on any platform without9635 declare and configure build artifacts and other tasks.
9637 installing more programs.</p>9636 </p>
9638 <p>To use the build system, run 9637 <p>
9639 <code class="shell">$ zig build [command]</code>9638 Some examples of tasks the build system can help with:
9640 where {#syntax#}[command]{#endsyntax#} is an optional target,9639 </p>
9641 configured by your build.zig file. There is more detail9640 <ul>
9642 on <a href="https://github.com/ziglang/zig/wiki/Zig-Build-System">the9641 <li>Creating build artifacts by executing the Zig compiler. This includes
9643 wiki</a> but here are some example build.zig files to get you9642 building Zig source code as well as C and C++ source code.</li>
9644 started:</p>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>
9645 9659
9646 {#header_open|Building a Zig Executable#}9660 {#header_open|Building an Executable#}
9647 <p>This <code>build.zig</code> file is automatically generated9661 <p>This <code>build.zig</code> file is automatically generated
9648 by <code>zig init-exe</code>.</p>9662 by <code>zig init-exe</code>.</p>
9649 {#code_begin|syntax|build#}9663 {#code_begin|syntax|build#}
...@@ -9660,58 +9674,34 @@ pub fn build(b: *Builder) void {...@@ -9660,58 +9674,34 @@ pub fn build(b: *Builder) void {
9660 // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.9674 // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
9661 const mode = b.standardReleaseOptions();9675 const mode = b.standardReleaseOptions();
96629676
9663 // This line tells the Zig build system where to find the file9677 const exe = b.addExecutable("example", "src/main.zig");
9664 // that contains main and what to call the executable.
9665 const exe = b.addExecutable("main", "src/main.zig");
9666 exe.setTarget(target);9678 exe.setTarget(target);
9667 exe.setBuildMode(mode);9679 exe.setBuildMode(mode);
9668 exe.install();9680 exe.install();
96699681
9670 const run_cmd = exe.run();9682 const run_cmd = exe.run();
9671 run_cmd.step.dependOn(b.getInstallStep());9683 run_cmd.step.dependOn(b.getInstallStep());
9684 if (b.args) |args| {
9685 run_cmd.addArgs(args);
9686 }
96729687
9673 // This will be executed by "zig build run"
9674 const run_step = b.step("run", "Run the app");9688 const run_step = b.step("run", "Run the app");
9675 run_step.dependOn(&run_cmd.step);9689 run_step.dependOn(&run_cmd.step);
9676}9690}
9677 {#code_end#}{#header_close#}
9678
9679 {#header_open|Building a C library#}
9680 {#code_begin|syntax#}
9681 const Builder = @import("std").build.Builder;
9682
9683 pub fn build(b: *Builder) void {
9684 const mode = b.standardReleaseOptions();
9685 // Add a target that generates libbadmath, with no Zig source files.
9686 const lib = b.addStaticLibrary("badmath", null);
9687 lib.setBuildMode(mode);
9688 // This particular library exists entirely in src/lib.c.
9689 lib.addCSourceFile("src/lib.c", &[_][]const u8{
9690 "-Wall",
9691 "-Wextra",
9692 "-Werror",
9693 });
9694 // libbadmath.a will be put in this directory, instead of only
9695 // living in zig-cache.
9696 lib.setOutputDir("obj");
9697 lib.install();
9698 }
9699 {#code_end#}9691 {#code_end#}
9700 {#header_close#}9692 {#header_close#}
97019693
9702 {#header_open|Extending a C library#}9694 {#header_open|Building a Library#}
9703 {#code_begin|syntax#}9695 <p>This <code>build.zig</code> file is automatically generated
9696 by <code>zig init-lib</code>.</p>
9697 {#code_begin|syntax|build#}
9704const Builder = @import("std").build.Builder;9698const Builder = @import("std").build.Builder;
97059699
9706pub fn build(b: *Builder) void {9700pub fn build(b: *Builder) void {
9707 const mode = b.standardReleaseOptions();9701 const mode = b.standardReleaseOptions();
9708 // This line tells the build system to make a static library9702 const lib = b.addStaticLibrary("example", "src/main.zig");
9709 // called "add" using source from "src/main.zig".
9710 const lib = b.addStaticLibrary("add", "src/main.zig");
9711 lib.setBuildMode(mode);9703 lib.setBuildMode(mode);
9712 lib.force_pic = true;9704 lib.install();
9713 // Include the compiler's runtime environment in the static library.
9714 lib.bundle_compiler_rt = true;
97159705
9716 var main_tests = b.addTest("src/main.zig");9706 var main_tests = b.addTest("src/main.zig");
9717 main_tests.setBuildMode(mode);9707 main_tests.setBuildMode(mode);
...@@ -9719,7 +9709,19 @@ pub fn build(b: *Builder) void {...@@ -9719,7 +9709,19 @@ pub fn build(b: *Builder) void {
9719 const test_step = b.step("test", "Run library tests");9709 const test_step = b.step("test", "Run library tests");
9720 test_step.dependOn(&main_tests.step);9710 test_step.dependOn(&main_tests.step);
9721}9711}
9722 {#code_end#}{#header_close#}9712 {#code_end#}
9713 {#header_close#}
9714
9715 {#header_open|Compiling C Source Code#}
9716 <pre>{#syntax#}
9717lib.addCSourceFile("src/lib.c", &[_][]const u8{
9718 "-Wall",
9719 "-Wextra",
9720 "-Werror",
9721});
9722 {#endsyntax#}</pre>
9723 {#header_close#}
9724
9723 {#header_close#}9725 {#header_close#}
9724 {#header_open|C#}9726 {#header_open|C#}
9725 <p>9727 <p>