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 {
32493249
32503250 {#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
32523277 {#header_open|blocks#}
32533278 <p>
32543279 Blocks are used to limit the scope of variable declarations:
......@@ -8547,31 +8572,6 @@ fn foo(comptime T: type, ptr: *T) T {
85478572 {#header_close#}
85488573 {#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
85758575 {#header_open|Build Mode#}
85768576 <p>
85778577 Zig has four build modes:
......@@ -9626,24 +9626,38 @@ test "assert in release fast mode" {
96269626 isolation.
96279627 </p>
96289628 {#header_close#}
9629 {#header_open|Zig Build System#}
96309629
9631 <p>Simple programs can be built with {#syntax#}zig
9632 build-exe{#endsyntax#} and {#syntax#}zig build-lib{#endsyntax#},
9633 but running those commands manually gets tedious and error
9634 prone. Zig's build system lets you keep all the command line
9635 switches and build modes in one place. It has no external
9636 dependencies, so Zig code can be built on any platform without
9637 installing more programs.</p>
9638 <p>To use the build system, run
9639 <code class="shell">$ zig build [command]</code>
9640 where {#syntax#}[command]{#endsyntax#} is an optional target,
9641 configured by your build.zig file. There is more detail
9642 on <a href="https://github.com/ziglang/zig/wiki/Zig-Build-System">the
9643 wiki</a> but here are some example build.zig files to get you
9644 started:</p>
9630 {#header_open|Zig Build System#}
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>
96459659
9646 {#header_open|Building a Zig Executable#}
9660 {#header_open|Building an Executable#}
96479661 <p>This <code>build.zig</code> file is automatically generated
96489662 by <code>zig init-exe</code>.</p>
96499663 {#code_begin|syntax|build#}
......@@ -9660,58 +9674,34 @@ pub fn build(b: *Builder) void {
96609674 // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
96619675 const mode = b.standardReleaseOptions();
96629676
9663 // This line tells the Zig build system where to find the file
9664 // that contains main and what to call the executable.
9665 const exe = b.addExecutable("main", "src/main.zig");
9677 const exe = b.addExecutable("example", "src/main.zig");
96669678 exe.setTarget(target);
96679679 exe.setBuildMode(mode);
96689680 exe.install();
96699681
96709682 const run_cmd = exe.run();
96719683 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"
96749688 const run_step = b.step("run", "Run the app");
96759689 run_step.dependOn(&run_cmd.step);
96769690}
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 }
96999691 {#code_end#}
97009692 {#header_close#}
97019693
9702 {#header_open|Extending a C library#}
9703 {#code_begin|syntax#}
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#}
97049698const Builder = @import("std").build.Builder;
97059699
97069700pub fn build(b: *Builder) void {
97079701 const mode = b.standardReleaseOptions();
9708 // This line tells the build system to make a static library
9709 // called "add" using source from "src/main.zig".
9710 const lib = b.addStaticLibrary("add", "src/main.zig");
9702 const lib = b.addStaticLibrary("example", "src/main.zig");
97119703 lib.setBuildMode(mode);
9712 lib.force_pic = true;
9713 // Include the compiler's runtime environment in the static library.
9714 lib.bundle_compiler_rt = true;
9704 lib.install();
97159705
97169706 var main_tests = b.addTest("src/main.zig");
97179707 main_tests.setBuildMode(mode);
......@@ -9719,7 +9709,19 @@ pub fn build(b: *Builder) void {
97199709 const test_step = b.step("test", "Run library tests");
97209710 test_step.dependOn(&main_tests.step);
97219711}
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
97239725 {#header_close#}
97249726 {#header_open|C#}
97259727 <p>