zig-0.15

📁 zigcc/skills 📅 12 days ago

总安装量

周安装量

#27404

全站排名

安装命令

npx skills add https://github.com/zigcc/skills --skill zig-0.15

Agent 安装分布

claude-code 4

opencode 3

amp 2

kimi-cli 2

github-copilot 2

Skill 文档

Zig 0.15.x Programming Guide

Version Scope: This skill is pinned to Zig 0.15.x (specifically 0.15.2). For master/nightly builds, APIs may differ. Always check official docs for your version.

This skill ensures correct Zig 0.15.x API usage. Many LLMs have outdated Zig knowledge (0.11-0.14), causing compilation errors.

Official Documentation (0.15.2):

Language Reference: https://ziglang.org/documentation/0.15.2/
Standard Library: https://ziglang.org/documentation/0.15.2/std/
Release Notes: https://ziglang.org/download/0.15.1/release-notes.html
Build System Guide: https://ziglang.org/learn/build-system/

Community Resources (0.15.x):

Zig Cookbook: https://cookbook.ziglang.cc/ (practical recipes, tracks 0.15.x)
Zig Cookbook Source: https://github.com/zigcc/zig-cookbook

Production Zig Codebases (learn from real-world projects):

Bun: https://github.com/oven-sh/bun (JS runtime, ~200k+ lines of Zig)
Tigerbeetle: https://github.com/tigerbeetle/tigerbeetle (financial database)
Mach Engine: https://github.com/hexops/mach (game engine)

Learning Resources (All 0.15.x Compatible):

Zig Algorithms: https://github.com/TheAlgorithms/Zig (data structures & algorithms)
zig-clap: https://github.com/Hejsil/zig-clap (CLI argument parser, 1.4k stars)
zig-bench: https://github.com/Hejsil/zig-bench (benchmarking library, 68 stars)
libvaxis: https://github.com/rockorager/libvaxis (TUI framework, 1.5k stars, v0.15.2)
ZLS: https://github.com/zigtools/zls (Language Server, 4.5k stars, v0.15.0)
zig-protobuf: https://github.com/Arwalk/zig-protobuf (Protocol Buffers, 365 stars)
libxev: https://github.com/mitchellh/libxev (event loop, 2k+ stars)
zig-aio: https://github.com/Cloudef/zig-aio (async I/O library)
zig-toml: https://github.com/sam701/zig-toml (TOML parser)
zig-xml: https://github.com/nektro/zig-xml (XML parser)
log.zig: https://github.com/karlseguin/log.zig (structured logging)
http.zig: https://github.com/karlseguin/http.zig (HTTP server, 1.3k stars)
cache.zig: https://github.com/karlseguin/cache.zig (thread-safe LRU cache, 79 stars)
pretty: https://github.com/timfayz/pretty (pretty printer for debugging, 98 stars)
tls.zig: https://github.com/ianic/tls.zig (TLS 1.2/1.3, client & server)
zig-network: https://github.com/ikskuh/zig-network (TCP/UDP networking)
zmath: https://github.com/zig-gamedev/zmath (SIMD math library)

Mitchell Hashimoto’s Zig Libraries (Ghostty author, high quality):

libxev: https://github.com/mitchellh/libxev (cross-platform event loop)
zig-graph: https://github.com/mitchellh/zig-graph (directed graph data structure)
zig-libxml2: https://github.com/mitchellh/zig-libxml2 (libxml2 bindings)

Compiler/Toolchain:

llvm-zig: https://github.com/kassane/llvm-zig (LLVM/Clang bindings, 53 stars)

AI/ML:

ZML: https://github.com/zml/zml (high-performance AI inference, 3k stars)

Blockchain/Ethereum:

Zeam: https://github.com/blockblaz/zeam (Ethereum client in Zig)
ssz.zig: https://github.com/blockblaz/ssz.zig (SSZ serialization for Eth2, 30 stars, â ï¸ 0.14.x)

Ecosystem Index:

awesome-zig: https://github.com/zigcc/awesome-zig (curated list, â ï¸ check version compatibility!)
Zigistry: https://zigistry.dev/ (package registry with version info)

For Other Versions:

Master (unstable): https://ziglang.org/documentation/master/
Source Code: https://codeberg.org/ziglang/zig
All Releases: https://ziglang.org/download/

Critical API Changes in Zig 0.15

ArrayList (BREAKING)

All mutating methods now require explicit allocator parameter:

// â WRONG (0.13 and earlier)
var list = std.ArrayList(T).init(allocator);
try list.append(item);
try list.appendSlice(items);
_ = try list.addOne();
_ = try list.toOwnedSlice();

// â CORRECT (0.15+)
var list = try std.ArrayList(T).initCapacity(allocator, 16);
defer list.deinit(allocator);
try list.append(allocator, item);
try list.appendSlice(allocator, items);
_ = try list.addOne(allocator);
_ = try list.toOwnedSlice(allocator);

// AssumeCapacity variants do NOT need allocator
list.appendAssumeCapacity(item);

Method	0.13	0.15+
`append`	`try list.append(item)`	`try list.append(allocator, item)`
`appendSlice`	`try list.appendSlice(items)`	`try list.appendSlice(allocator, items)`
`addOne`	`try list.addOne()`	`try list.addOne(allocator)`
`ensureTotalCapacity`	`try list.ensureTotalCapacity(n)`	`try list.ensureTotalCapacity(allocator, n)`
`toOwnedSlice`	`try list.toOwnedSlice()`	`try list.toOwnedSlice(allocator)`
`deinit`	`list.deinit()`	`list.deinit(allocator)`

HashMap

Managed (stores allocator internally):

var map = std.StringHashMap(V).init(allocator);
defer map.deinit();
try map.put(key, value);  // No allocator needed

Unmanaged (requires allocator for each operation):

var map = std.StringHashMapUnmanaged(V){};
defer map.deinit(allocator);
try map.put(allocator, key, value);  // Allocator required

Writergate: New std.Io.Writer and std.Io.Reader (MAJOR REWRITE)

Zig 0.15 introduces completely new I/O interfaces. All old std.io readers/writers are deprecated.

Key Changes

Non-generic: New interfaces are concrete types, not anytype
Buffer in interface: User provides buffer, implementation decides minimum size
Ring buffer based: More efficient peek and streaming operations
Precise error sets: No more anyerror propagation

New stdout Pattern

// â WRONG (0.14 and earlier)
const stdout = std.io.getStdOut().writer();
try stdout.print("Hello\n", .{});

// â CORRECT (0.15+)
var stdout_buffer: [1024]u8 = undefined;
var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
const stdout: *std.Io.Writer = &stdout_writer.interface;

try stdout.print("Hello\n", .{});
try stdout.flush();  // Don't forget to flush!

Adapter for Migration

If you have old-style writers and need new interface:

fn useOldWriter(old_writer: anytype) !void {
    var adapter = old_writer.adaptToNewApi(&.{});
    const w: *std.Io.Writer = &adapter.new_interface;
    try w.print("{s}", .{"example"});
}

New Reader API

// Reading lines with delimiter
while (reader.takeDelimiterExclusive('\n')) |line| {
    // process line
} else |err| switch (err) {
    error.EndOfStream => {},
    error.StreamTooLong => return err,
    error.ReadFailed => return err,
}

HTTP Client (MAJOR REWRITE)

Zig 0.15.2 has both fetch() (high-level) and request() (low-level) APIs:

// â CORRECT: High-level fetch() API (Zig 0.15.2)
var client: std.http.Client = .{ .allocator = allocator };
defer client.deinit();

const result = try client.fetch(.{
    .location = .{ .url = "https://example.com/api" },
    .method = .GET,
});
// result.status contains the HTTP status

// â CORRECT: Low-level request/response API (Zig 0.15.2)
var client: std.http.Client = .{ .allocator = allocator };
defer client.deinit();

const uri = try std.Uri.parse("https://example.com/api");

// Create request with client.request() (NOT client.open!)
var req = try client.request(.POST, uri, .{
    .extra_headers = &.{
        .{ .name = "Content-Type", .value = "application/json" },
    },
});
defer req.deinit();

// Send body (use @constCast for const slices)
try req.sendBodyComplete(@constCast("{\"key\": \"value\"}"));

// Receive response
var redirect_buf: [4096]u8 = undefined;
var response = try req.receiveHead(&redirect_buf);

// Check status
const status = @intFromEnum(response.head.status);
if (status >= 200 and status < 300) {
    // Read response body using std.Io.Reader
    var body_reader = response.reader(&redirect_buf);
    const body = try body_reader.allocRemaining(allocator, std.Io.Limit.limited(1024 * 1024));
    defer allocator.free(body);
}

Key API functions (verified in Zig 0.15.2):

client.request(method, uri, options) â Request
client.fetch(options) â FetchResult
req.sendBodyComplete(body) – sends body and flushes
req.sendBodiless() – for GET requests without body
req.receiveHead(buffer) â Response
response.reader(buffer) â *std.Io.Reader
reader.allocRemaining(allocator, limit) â []u8

Base64 Encoding

// â WRONG (0.13)
const encoder = std.base64.standard;
const encoded = encoder.encode(&buf, data);

// â CORRECT (0.15+)
const encoder = std.base64.standard.Encoder;
const encoded = encoder.encode(&buf, data);

Ed25519 Cryptography (MAJOR CHANGES)

Key types are now structs, not raw byte arrays:

const Ed25519 = std.crypto.sign.Ed25519;

// â WRONG (0.13 - SecretKey was [32]u8)
const secret: [32]u8 = ...;
const kp = Ed25519.KeyPair.fromSecretKey(secret);

// â CORRECT (0.15+ - SecretKey is struct with 64 bytes)
// From 32-byte seed (deterministic):
const seed: [32]u8 = ...;
const kp = try Ed25519.KeyPair.generateDeterministic(seed);

// From 64-byte secret key:
var secret_bytes: [64]u8 = ...;
const secret_key = try Ed25519.SecretKey.fromBytes(secret_bytes);
const kp = try Ed25519.KeyPair.fromSecretKey(secret_key);

// Get public key bytes:
const pubkey_bytes: [32]u8 = kp.public_key.toBytes();

// Get seed:
const seed: [32]u8 = kp.secret_key.seed();

Signature changes:

// â WRONG (0.13 - fromBytes returned error union)
const sig = try Ed25519.Signature.fromBytes(bytes);

// â CORRECT (0.15+ - fromBytes does NOT return error)
const sig = Ed25519.Signature.fromBytes(bytes);

Type Introspection Enums (Case Change)

// â WRONG (0.13 - PascalCase)
if (@typeInfo(T) == .Slice) { ... }
if (@typeInfo(T) == .Pointer) { ... }
if (@typeInfo(T) == .Struct) { ... }

// â CORRECT (0.15+ - lowercase/escaped)
if (@typeInfo(T) == .slice) { ... }
if (@typeInfo(T) == .pointer) { ... }
if (@typeInfo(T) == .@"struct") { ... }
if (@typeInfo(T) == .@"enum") { ... }
if (@typeInfo(T) == .@"union") { ... }
if (@typeInfo(T) == .array) { ... }
if (@typeInfo(T) == .optional) { ... }

Custom Format Functions

// â WRONG (0.13 - used {} format specifier)
pub fn format(
    self: Self,
    comptime fmt: []const u8,
    options: std.fmt.FormatOptions,
    writer: anytype,
) !void {
    _ = fmt;
    _ = options;
    try writer.writeAll("...");
}
// Usage: std.fmt.bufPrint(&buf, "{}", .{value});

// â CORRECT (0.15+ - use {f} format specifier)
pub fn format(self: Self, writer: anytype) !void {
    _ = self;
    try writer.writeAll("...");
}
// Usage: std.fmt.bufPrint(&buf, "{f}", .{value});

JSON Parsing and Serialization

const MyStruct = struct {
    name: []const u8,
    value: u32,
};

// â CORRECT: Parsing (0.15+)
const json_str =
    \\{"name": "test", "value": 42}
;
const parsed = try std.json.parseFromSlice(MyStruct, allocator, json_str, .{});
defer parsed.deinit();
const data = parsed.value;

// â CORRECT: Serialization (0.15.2 - writer-based API)
// Note: There is NO stringifyAlloc in 0.15.2!

// Method 1: Using std.json.Stringify with Allocating writer
var out: std.Io.Writer.Allocating = .init(allocator);
defer out.deinit();
var stringify: std.json.Stringify = .{
    .writer = &out.writer,
    .options = .{},
};
try stringify.write(data);
const json_output = out.written();

// Method 2: Using std.fmt with json.fmt wrapper
const formatted = try std.fmt.allocPrint(allocator, "{f}", .{std.json.fmt(data, .{})});
defer allocator.free(formatted);

// Method 3: To fixed buffer
var buf: [1024]u8 = undefined;
var fbs = std.io.fixedBufferStream(&buf);
var writer = fbs.writer();
var stringify2: std.json.Stringify = .{
    .writer = &writer.adaptToNewApi(&.{}).new_interface,
    .options = .{},
};
try stringify2.write(data);
const output = fbs.getWritten();

Memory/Formatting

// Allocating format
const formatted = try std.fmt.allocPrint(allocator, "value: {d}", .{42});
defer allocator.free(formatted);

// Non-allocating format
var buffer: [256]u8 = undefined;
const result = try std.fmt.bufPrint(&buffer, "value: {d}", .{42});

Common Error Messages and Fixes

Error	Cause	Fix
`expected 2 argument(s), found 1`	ArrayList method missing allocator	Add allocator as first argument
`no field or member function named 'encode'`	Using `std.base64.standard.encode`	Use `std.base64.standard.Encoder.encode`
`no field or member function named 'open'`	Using old HTTP API	Use `client.request()` or `client.fetch()`
`expected type 'SecretKey', found '[32]u8'`	Ed25519 SecretKey is now struct	Use `generateDeterministic(seed)`
`expected error union type, found 'Signature'`	Signature.fromBytes doesn’t return error	Remove `try`
`enum has no member named 'Slice'`	@typeInfo enum case changed	Use lowercase `.slice`
`no field named 'root_source_file'`	Old build.zig API	Use `root_module = b.createModule(...)`

Verification Workflow

After writing Zig code:

Run zig build to check for compilation errors
If errors match patterns above, apply the 0.15 fix
Run zig build test to verify functionality
Use zig build -Doptimize=ReleaseFast test to catch UB

Build System (build.zig) Changes (MAJOR REWRITE)

Official Guide: https://ziglang.org/learn/build-system/

Executable Creation

// â WRONG (0.14 and earlier)
const exe = b.addExecutable(.{
    .name = "hello",
    .root_source_file = .{ .path = "src/main.zig" },
    .target = target,
    .optimize = optimize,
});

// â CORRECT (0.15+)
const exe = b.addExecutable(.{
    .name = "hello",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,
        .optimize = optimize,
    }),
});

Library Creation

// â WRONG (0.14 - addSharedLibrary/addStaticLibrary)
const lib = b.addSharedLibrary(.{
    .name = "mylib",
    .root_source_file = .{ .path = "src/lib.zig" },
});

// â CORRECT (0.15+ - unified addLibrary with linkage)
const lib = b.addLibrary(.{
    .name = "mylib",
    .linkage = .dynamic,  // or .static
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/lib.zig"),
        .target = target,
        .optimize = optimize,
    }),
});

Path Handling

// â WRONG (0.14 - .path field)
.root_source_file = .{ .path = "src/main.zig" },

// â CORRECT (0.15+ - use b.path())
.root_source_file = b.path("src/main.zig"),

Module Dependencies

// â WRONG (0.14)
exe.addModule("sdk", sdk_module);

// â CORRECT (0.15+)
exe.root_module.addImport("sdk", sdk_module);

Target Options

// â WRONG (0.14)
const target = b.standardTargetOptions(.{});
// then use target directly

// â CORRECT (0.15+)
const target = b.standardTargetOptions(.{});
const optimize = b.standardOptimizeOption(.{});

const exe = b.addExecutable(.{
    .name = "app",
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = target,      // pass to createModule
        .optimize = optimize,  // pass to createModule
    }),
});

Testing

// â CORRECT (0.15+)
const unit_tests = b.addTest(.{
    .root_module = b.createModule(.{
        .root_source_file = b.path("src/main.zig"),
        .target = b.graph.host,  // use b.graph.host for native target
    }),
});

const run_unit_tests = b.addRunArtifact(unit_tests);
const test_step = b.step("test", "Run unit tests");
test_step.dependOn(&run_unit_tests.step);

Complete build.zig Example

const std = @import("std");

pub fn build(b: *std.Build) void {
    const target = b.standardTargetOptions(.{});
    const optimize = b.standardOptimizeOption(.{});

    const exe = b.addExecutable(.{
        .name = "hello",
        .root_module = b.createModule(.{
            .root_source_file = b.path("src/main.zig"),
            .target = target,
            .optimize = optimize,
        }),
    });

    b.installArtifact(exe);

    const run_exe = b.addRunArtifact(exe);
    const run_step = b.step("run", "Run the application");
    run_step.dependOn(&run_exe.step);
}

std.mem Patterns

Memory Operations

// Copy memory
@memcpy(dest, src);  // Same as std.mem.copyForwards

// Set memory
@memset(buffer, 0);  // Zero-fill

// Compare memory
const equal = std.mem.eql(u8, slice1, slice2);

// Find in slice
const index = std.mem.indexOf(u8, haystack, needle);

Alignment

// Check alignment
const is_aligned = std.mem.isAligned(@intFromPtr(ptr), @alignOf(T));

// Align pointer
const aligned = std.mem.alignPointer(ptr, @alignOf(T));

std.io Patterns

Fixed Buffer Stream

var buf: [1024]u8 = undefined;
var fbs = std.io.fixedBufferStream(&buf);
const writer = fbs.writer();

try writer.writeAll("Hello");
try writer.print(" {d}", .{42});

const written = fbs.getWritten();  // "Hello 42"

Counting Writer

var counting = std.io.countingWriter(underlying_writer);
try counting.writer().writeAll("test");
const bytes_written = counting.bytes_written;  // 4

Testing Patterns

Testing Allocator (Detects Leaks)

test "no memory leaks" {
    const allocator = std.testing.allocator;  // Auto-detects leaks
    
    const data = try allocator.alloc(u8, 100);
    defer allocator.free(data);  // MUST free or test fails
    
    // ... test code ...
}

Assertions

test "assertions" {
    try std.testing.expect(condition);              // Boolean
    try std.testing.expectEqual(expected, actual);  // Equality
    try std.testing.expectEqualSlices(u8, expected, actual);  // Slices
    try std.testing.expectError(error.SomeError, result);     // Error
    try std.testing.expectEqualStrings("hello", str);         // Strings
}

Comptime Patterns

Type Reflection

fn serialize(comptime T: type, value: T) ![]u8 {
    const info = @typeInfo(T);
    
    switch (info) {
        .int => |i| {
            // Handle integer
            const byte_count = @divExact(i.bits, 8);
            // ...
        },
        .@"struct" => |s| {
            // Handle struct
            inline for (s.fields) |field| {
                // Process each field
                const field_value = @field(value, field.name);
                // ...
            }
        },
        else => @compileError("Unsupported type"),
    }
}

Optional Type Handling

fn getInner(comptime T: type) type {
    const info = @typeInfo(T);
    if (info == .optional) {
        return info.optional.child;
    }
    return T;
}

Pointer and Slice Patterns

Slice to Many-Item Pointer

const slice: []u8 = buffer[0..10];
const ptr: [*]u8 = slice.ptr;

Creating Slices

// From array
const arr = [_]u8{ 1, 2, 3, 4, 5 };
const slice = arr[1..4];  // [2, 3, 4]

// From pointer + length
const slice = ptr[0..len];

Sentinel-Terminated Slices

// Null-terminated string
const str: [:0]const u8 = "hello";
const c_str: [*:0]const u8 = str.ptr;

// Get length without sentinel
const len = str.len;  // 5, not including null

Language Changes

usingnamespace Removed

The usingnamespace keyword has been completely removed in Zig 0.15.

// â WRONG (removed in 0.15)
pub usingnamespace @import("other.zig");

// â CORRECT - explicit re-exports
pub const foo = @import("other.zig").foo;
pub const bar = @import("other.zig").bar;

// â CORRECT - namespace via field
pub const other = @import("other.zig");
// Usage: other.foo, other.bar

Migration for mixins: Use zero-bit fields with @fieldParentPtr:

// â OLD mixin pattern
pub const Foo = struct {
    count: u32 = 0,
    pub usingnamespace CounterMixin(Foo);
};

// â NEW mixin pattern (0.15+)
pub fn CounterMixin(comptime T: type) type {
    return struct {
        pub fn increment(m: *@This()) void {
            const x: *T = @alignCast(@fieldParentPtr("counter", m));
            x.count += 1;
        }
    };
}

pub const Foo = struct {
    count: u32 = 0,
    counter: CounterMixin(Foo) = .{},  // zero-bit field
};
// Usage: foo.counter.increment()

async/await Keywords Removed

The async, await, and @frameSize have been removed. Async functionality will be provided via the standard library’s new I/O interface.

// â REMOVED - no async/await keywords
async fn fetchData() ![]u8 { ... }
const result = await fetchData();

// â Use std.Io interfaces or threads instead

Arithmetic on undefined

Operations on undefined that could trigger illegal behavior now cause compile errors:

const a: u32 = 0;
const b: u32 = undefined;

// â COMPILE ERROR in 0.15+
_ = a + b;  // error: use of undefined value here causes illegal behavior

Lossy Integer to Float Coercion

Compile error if integer cannot be precisely represented:

// â COMPILE ERROR in 0.15+
const val: f32 = 123_456_789;  // error: cannot represent precisely

// â CORRECT - opt-in to floating-point rounding
const val: f32 = 123_456_789.0;

Extended References (This Skill)

è¯¦ç»ç API åèåè¿ç§»æåè¯·æ¥éä»¥ä¸ææ¡£ï¼

ææ¡£	è·¯å¾	åå®¹
æ ååº API è¯¦è§£	`references/stdlib-api-reference.md`	ArrayListãHashMapãHTTP ClientãEd25519ãBase64ãJSONã@typeInfoãstd.fmt çå®æ´ API åè
è¿ç§»æ¨¡å¼æå	`references/migration-patterns.md`	ä» 0.13/0.14 è¿ç§»å° 0.15 çè¯¦ç»å¯¹ç§ï¼åæ¬ WritergateãArrayListãBuild System ç
çäº§çº§ä»£ç åº	`references/production-codebases.md`	Sigï¼Solanaï¼ãZMLï¼AIï¼ãZeamï¼Ethereumï¼ãBunãTigerbeetle çé¡¹ç®å¦ä¹ æåï¼ä»¥å 0.15.x å¼å®¹åºåè¡¨
çæ¬çç¥	`VERSIONING.md`	çæ¬å¼å®¹æ§è¯´æåæ´æ°çç¥

å¿«éæ¥éå»ºè®®

ç¼å HTTP è¯·æ±ï¼ â æ¥ç references/stdlib-api-reference.md ç std.http.Client é¨å
ArrayList æ¥éï¼ â æ¥ç references/migration-patterns.md ç ArrayList Migration é¨å
å¦ä¹ æä½³å®è·µï¼ â æ¥ç references/production-codebases.md ä¸ç Sig é¡¹ç®ï¼Solana éªè¯å¨ï¼
å¯»æ¾ç¬¬ä¸æ¹åºï¼ â æ¥ç references/production-codebases.md ç Smaller Learning Projects è¡¨æ ¼

References