From eb80cc2b9ee687313dda77e9c3b328a882ae849e Mon Sep 17 00:00:00 2001 From: Nathan Michaels Date: Sun, 5 Jul 2020 18:37:44 -0400 Subject: [PATCH 1/2] Add some basic examples for the Zig Build System. --- doc/langref.html.in | 99 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 95 insertions(+), 4 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 12af3eaadd..0a44203b55 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -8550,7 +8550,8 @@ fn foo(comptime T: type, ptr: *T) T { {#header_open|opaque#}

{#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment. - It can have declarations like structs, unions, or enums. + It can contain declarations the same as {#link|structs|struct#}, {#link|unions|union#}, + and {#link|enums|enum#}.

This is typically used for type safety when interacting with C code that does not expose struct details. @@ -9626,9 +9627,99 @@ test "assert in release fast mode" {

{#header_close#} {#header_open|Zig Build System#} -

TODO: explain purpose, it's supposed to replace make/cmake

-

TODO: example of building a zig executable

-

TODO: example of building a C library

+ +

Simple programs can be built with {#syntax#}zig + build-exe{#endsyntax#} and {#syntax#}zig build-lib{#endsyntax#}, + but running those commands manually gets tedious and error + prone. Zig's build system lets you keep all the command line + switches and build modes in one place. It has no external + dependencies, so Zig code can be built on any platform without + installing more programs.

+

To use the build system, run + $ zig build [command] + where {#syntax#}[command]{#endsyntax#} is an optional target, + configured by your build.zig file. There is more detail + on the + wiki but here are some example build.zig files to get you + started:

+ + {#header_open|Building a Zig Executable#} +

This build.zig file is automatically generated + by zig init-exe.

+ {#code_begin|syntax|build#} +const Builder = @import("std").build.Builder; + +pub fn build(b: *Builder) void { + // Standard target options allows the person running `zig build` to choose + // what target to build for. Here we do not override the defaults, which + // means any target is allowed, and the default is native. Other options + // for restricting supported target set are available. + const target = b.standardTargetOptions(.{}); + + // Standard release options allow the person running `zig build` to select + // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. + const mode = b.standardReleaseOptions(); + + // This line tells the Zig build system where to find the file + // that contains main and what to call the executable. + const exe = b.addExecutable("main", "src/main.zig"); + exe.setTarget(target); + exe.setBuildMode(mode); + exe.install(); + + const run_cmd = exe.run(); + run_cmd.step.dependOn(b.getInstallStep()); + + // This will be executed by "zig build run" + const run_step = b.step("run", "Run the app"); + run_step.dependOn(&run_cmd.step); +} + {#code_end#}{#header_close#} + + {#header_open|Building a C library#} + {#code_begin|syntax#} + const Builder = @import("std").build.Builder; + + pub fn build(b: *Builder) void { + const mode = b.standardReleaseOptions(); + // Add a target that generates libbadmath, with no Zig source files. + const lib = b.addStaticLibrary("badmath", null); + lib.setBuildMode(mode); + // This particular library exists entirely in src/lib.c. + lib.addCSourceFile("src/lib.c", &[_][]const u8{ + "-Wall", + "-Wextra", + "-Werror", + }); + // libbadmath.a will be put in this directory, instead of only + // living in zig-cache. + lib.setOutputDir("obj"); + lib.install(); + } + {#code_end#} + {#header_close#} + + {#header_open|Extending a C library#} + {#code_begin|syntax#} +const Builder = @import("std").build.Builder; + +pub fn build(b: *Builder) void { + const mode = b.standardReleaseOptions(); + // This line tells the build system to make a static library + // called "add" using source from "src/main.zig". + const lib = b.addStaticLibrary("add", "src/main.zig"); + lib.setBuildMode(mode); + lib.force_pic = true; + // Include the compiler's runtime environment in the static library. + lib.bundle_compiler_rt = true; + + var main_tests = b.addTest("src/main.zig"); + main_tests.setBuildMode(mode); + + const test_step = b.step("test", "Run library tests"); + test_step.dependOn(&main_tests.step); +} + {#code_end#}{#header_close#} {#header_close#} {#header_open|C#}

From 9ca8bcb4d928da4a50e9970d4335317725744f72 Mon Sep 17 00:00:00 2001 From: Andrew Kelley Date: Fri, 16 Oct 2020 21:29:33 -0700 Subject: [PATCH 2/2] 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 --- doc/langref.html.in | 154 ++++++++++++++++++++++---------------------- 1 file changed, 78 insertions(+), 76 deletions(-) diff --git a/doc/langref.html.in b/doc/langref.html.in index 0a44203b55..31d3b9b1ec 100644 --- a/doc/langref.html.in +++ b/doc/langref.html.in @@ -3249,6 +3249,31 @@ fn makeNumber() Number { {#header_close#} + {#header_open|opaque#} +

+ {#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment. + It can contain declarations the same as {#link|structs|struct#}, {#link|unions|union#}, + and {#link|enums|enum#}. +

+

+ This is typically used for type safety when interacting with C code that does not expose struct details. + Example: +

+ {#code_begin|test_err|expected type '*Derp', found '*Wat'#} +const Derp = opaque {}; +const Wat = opaque {}; + +extern fn bar(d: *Derp) void; +fn foo(w: *Wat) callconv(.C) void { + bar(w); +} + +test "call foo" { + foo(undefined); +} + {#code_end#} + {#header_close#} + {#header_open|blocks#}

Blocks are used to limit the scope of variable declarations: @@ -8547,31 +8572,6 @@ fn foo(comptime T: type, ptr: *T) T { {#header_close#} {#header_close#} - {#header_open|opaque#} -

- {#syntax#}opaque {}{#endsyntax#} declares a new type with an unknown (but non-zero) size and alignment. - It can contain declarations the same as {#link|structs|struct#}, {#link|unions|union#}, - and {#link|enums|enum#}. -

-

- This is typically used for type safety when interacting with C code that does not expose struct details. - Example: -

- {#code_begin|test_err|expected type '*Derp', found '*Wat'#} -const Derp = opaque {}; -const Wat = opaque {}; - -extern fn bar(d: *Derp) void; -fn foo(w: *Wat) callconv(.C) void { - bar(w); -} - -test "call foo" { - foo(undefined); -} - {#code_end#} - {#header_close#} - {#header_open|Build Mode#}

Zig has four build modes: @@ -9626,24 +9626,38 @@ test "assert in release fast mode" { isolation.

{#header_close#} - {#header_open|Zig Build System#} -

Simple programs can be built with {#syntax#}zig - build-exe{#endsyntax#} and {#syntax#}zig build-lib{#endsyntax#}, - but running those commands manually gets tedious and error - prone. Zig's build system lets you keep all the command line - switches and build modes in one place. It has no external - dependencies, so Zig code can be built on any platform without - installing more programs.

-

To use the build system, run - $ zig build [command] - where {#syntax#}[command]{#endsyntax#} is an optional target, - configured by your build.zig file. There is more detail - on the - wiki but here are some example build.zig files to get you - started:

+ {#header_open|Zig Build System#} +

+ The Zig Build System provides a cross-platform, dependency-free way to declare + the logic required to build a project. With this system, the logic to build + a project is written in a build.zig file, using the Zig Build System API to + declare and configure build artifacts and other tasks. +

+

+ Some examples of tasks the build system can help with: +

+ +

+ To use the build system, run zig build --help + to see a command-line usage help menu. This will include project-specific + options that were declared in the build.zig script. +

- {#header_open|Building a Zig Executable#} + {#header_open|Building an Executable#}

This build.zig file is automatically generated by zig init-exe.

{#code_begin|syntax|build#} @@ -9660,58 +9674,34 @@ pub fn build(b: *Builder) void { // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall. const mode = b.standardReleaseOptions(); - // This line tells the Zig build system where to find the file - // that contains main and what to call the executable. - const exe = b.addExecutable("main", "src/main.zig"); + const exe = b.addExecutable("example", "src/main.zig"); exe.setTarget(target); exe.setBuildMode(mode); exe.install(); const run_cmd = exe.run(); run_cmd.step.dependOn(b.getInstallStep()); + if (b.args) |args| { + run_cmd.addArgs(args); + } - // This will be executed by "zig build run" const run_step = b.step("run", "Run the app"); run_step.dependOn(&run_cmd.step); } - {#code_end#}{#header_close#} - - {#header_open|Building a C library#} - {#code_begin|syntax#} - const Builder = @import("std").build.Builder; - - pub fn build(b: *Builder) void { - const mode = b.standardReleaseOptions(); - // Add a target that generates libbadmath, with no Zig source files. - const lib = b.addStaticLibrary("badmath", null); - lib.setBuildMode(mode); - // This particular library exists entirely in src/lib.c. - lib.addCSourceFile("src/lib.c", &[_][]const u8{ - "-Wall", - "-Wextra", - "-Werror", - }); - // libbadmath.a will be put in this directory, instead of only - // living in zig-cache. - lib.setOutputDir("obj"); - lib.install(); - } {#code_end#} {#header_close#} - {#header_open|Extending a C library#} - {#code_begin|syntax#} + {#header_open|Building a Library#} +

This build.zig file is automatically generated + by zig init-lib.

+ {#code_begin|syntax|build#} const Builder = @import("std").build.Builder; pub fn build(b: *Builder) void { const mode = b.standardReleaseOptions(); - // This line tells the build system to make a static library - // called "add" using source from "src/main.zig". - const lib = b.addStaticLibrary("add", "src/main.zig"); + const lib = b.addStaticLibrary("example", "src/main.zig"); lib.setBuildMode(mode); - lib.force_pic = true; - // Include the compiler's runtime environment in the static library. - lib.bundle_compiler_rt = true; + lib.install(); var main_tests = b.addTest("src/main.zig"); main_tests.setBuildMode(mode); @@ -9719,7 +9709,19 @@ pub fn build(b: *Builder) void { const test_step = b.step("test", "Run library tests"); test_step.dependOn(&main_tests.step); } - {#code_end#}{#header_close#} + {#code_end#} + {#header_close#} + + {#header_open|Compiling C Source Code#} + 
{#syntax#}
+lib.addCSourceFile("src/lib.c", &[_][]const u8{
+    "-Wall",
+    "-Wextra",
+    "-Werror",
+});
+      {#endsyntax#}
+ {#header_close#} + {#header_close#} {#header_open|C#}