mirror/zig
1
0
Fork 0
mirror of https://github.com/ziglang/zig.git synced 2026-02-13 21:08:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

langref cleanups

Browse Source 
* 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
This commit is contained in:
Andrew Kelley 2020-10-16 21:29:33 -07:00
parent eb80cc2b9e
commit 9ca8bcb4d9
1 changed files with 78 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
doc/langref.html.in
View File

@ -3249,6 +3249,31 @@ fn makeNumber() Number {
{#header_close#}
{#header_open|opaque#}
<p>
{#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#}.
</p>
<p>
This is typically used for type safety when interacting with C code that does not expose struct details.
Example:
</p>
{#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#}
<p>
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#}
<p>
{#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#}.
</p>
<p>
This is typically used for type safety when interacting with C code that does not expose struct details.
Example:
</p>
{#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#}
<p>
Zig has four build modes:
@ -9626,24 +9626,38 @@ test "assert in release fast mode" {
isolation.
</p>
{#header_close#}
{#header_open|Zig Build System#}
<p>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.</p>
<p>To use the build system, run
<code class="shell">$ zig build [command]</code>
where {#syntax#}[command]{#endsyntax#} is an optional target,
configured by your build.zig file. There is more detail
on <a href="https://github.com/ziglang/zig/wiki/Zig-Build-System">the
wiki</a> but here are some example build.zig files to get you
started:</p>
{#header_open|Zig Build System#}
<p>
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.
</p>
<p>
Some examples of tasks the build system can help with:
</p>
<ul>
<li>Creating build artifacts by executing the Zig compiler. This includes
building Zig source code as well as C and C++ source code.</li>
<li>Capturing user-configured options and using those options to configure
the build.</li>
<li>Surfacing build configuration as {#link|comptime#} values by providing a
file that can be {#link|imported|@import#} by Zig code.</li>
<li>Caching build artifacts to avoid unnecessarily repeating steps.</li>
<li>Executing build artifacts or system-installed tools.</li>
<li>Running tests and verifying the output of executing a build artifact matches
the expected value.</li>
<li>Running <code>zig fmt</code> on a codebase or a subset of it.</li>
<li>Custom tasks.</li>
</ul>
<p>
To use the build system, run <code class="shell">zig build --help</code>
to see a command-line usage help menu. This will include project-specific
options that were declared in the build.zig script.
</p>
{#header_open|Building a Zig Executable#}
{#header_open|Building an Executable#}
<p>This <code>build.zig</code> file is automatically generated
by <code>zig init-exe</code>.</p>
{#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#}
<p>This <code>build.zig</code> file is automatically generated
by <code>zig init-lib</code>.</p>
{#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#}
<pre>{#syntax#}
lib.addCSourceFile("src/lib.c", &[_][]const u8{
"-Wall",
"-Wextra",
"-Werror",
});
{#endsyntax#}</pre>
{#header_close#}
{#header_close#}
{#header_open|C#}
<p>