zig-0.16

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zig 0.16-dev Porting Notes

Zig 0.16-dev 移植笔记

This skill captures gotchas hit when porting a 0.15 project to Zig 0.16-dev (std.Io world). APIs keep moving; always check the stdlib sources for your exact build.

本文记录了将Zig 0.15项目移植到Zig 0.16-dev（std.Io环境）时遇到的常见问题。API一直在迭代更新，请务必根据你使用的具体版本查看标准库源码。

Std.Io replaces std.net / legacy std.posix wrappers

Std.Io 替代 std.net / 旧版 std.posix 包装器

```
std.net
```
is gone. The new networking lives under std.Io.net
(types:
```
IpAddress
```
,
```
Stream
```
,
```
Server
```
,
```
UnixAddress
```
, etc.).

High-level functions like

tcpConnectToHost

Address.parseIp

Stream.connect

Stream.read/writeAll

no longer exist. You must use

Io

vtables (

io.vtable.netConnectIp

netRead

netWrite

netListenIp

netAccept

If you need raw fds, call platform syscalls (
```
std.os.linux.socket
```
,
```
accept4
```
,
```
connect
```
,
```
bind
```
,
```
listen
```
,
```
write
```
,
```
writev
```
,
```
read
```
,
```
close
```
). Many helpers that were under
```
std.posix
```
are gone.

posix.socket

posix.bind

posix.accept

posix.shutdown

posix.writev

posix.listen

posix.pipe2

posix.getrandom

std.net.has_unix_sockets

, etc. are removed. Use

std.os.<platform>

syscalls and

posix.system.*

where available, or the Io vtable.

Epoll: use
```
std.os.linux.epoll_create1/epoll_ctl/epoll_wait
```
directly; signatures include an explicit
```
count
```
param for writev/epoll_wait.

```
std.net
```
已被移除。新的网络功能位于**
```
std.Io.net
```
**下（类型包括：
```
IpAddress
```
、
```
Stream
```
、
```
Server
```
、
```
UnixAddress
```
等）。

诸如

tcpConnectToHost

、

Address.parseIp

、

Stream.connect

、

Stream.read/writeAll

等高级函数已不存在。你必须使用

Io

虚表（

io.vtable.netConnectIp

、

netRead

、

netWrite

、

netListenIp

、

netAccept

）。

如果需要原始文件描述符，请调用平台系统调用（
```
std.os.linux.socket
```
、
```
accept4
```
、
```
connect
```
、
```
bind
```
、
```
listen
```
、
```
write
```
、
```
writev
```
、
```
read
```
、
```
close
```
）。原
```
std.posix
```
下的许多辅助函数已被移除。

posix.socket

、

posix.bind

、

posix.accept

、

posix.shutdown

、

posix.writev

、

posix.listen

、

posix.pipe2

、

posix.getrandom

、

std.net.has_unix_sockets

等已被移除。请使用

std.os.<platform>

系统调用和可用的

posix.system.*

，或者Io虚表。

Epoll：直接使用

std.os.linux.epoll_create1/epoll_ctl/epoll_wait

；函数签名中

writev/epoll_wait

包含显式的

count

参数。

Std.Io Readers/Writers

Std.Io 读取器/写入器

New writer/reader interfaces live under
```
std.Io
```
. TLS expects
```
*std.Io.Reader
```
/
```
*std.Io.Writer
```
(struct fields
```
.interface
```
). Pass pointers to interfaces, not call
```
interface()
```
as a function.

std.time.sleep

removed; use

std.Io.sleep(io, Duration, Clock)

新的写入器/读取器接口位于
```
std.Io
```
下。TLS需要
```
*std.Io.Reader
```
/
```
*std.Io.Writer
```
（结构体字段为
```
.interface
```
）。请传递接口指针，不要将
```
interface()
```
作为函数调用。

std.time.sleep

已被移除；请使用

std.Io.sleep(io, Duration, Clock)

。

Time / Random / Env / Exit

时间 / 随机数 / 环境变量 / 退出

std.time.milliTimestamp

removed. Use

std.time.Timer

std.Io.Clock.now(clock, io)

and compare

Timestamp.nanoseconds

Random secure bytes:

std.Io.randomSecure(io, buf)

; no

std.crypto.random

std.posix.getrandom

convenience.

```
std.process.getEnvVarOwned
```
is gone; use
```
std.c.getenv
```
and copy.
```
std.posix.exit
```
removed; use
```
std.process.exit
```
.

std.time.milliTimestamp

已被移除。请使用

std.time.Timer

或

std.Io.Clock.now(clock, io)

并比较

Timestamp.nanoseconds

。

生成安全随机字节：使用
```
std.Io.randomSecure(io, buf)
```
；不再提供
```
std.crypto.random
```
或
```
std.posix.getrandom
```
的便捷方法。
```
std.process.getEnvVarOwned
```
已被移除；请使用
```
std.c.getenv
```
并自行复制。
```
std.posix.exit
```
已被移除；请使用
```
std.process.exit
```
。

TLS Client options

TLS 客户端选项

std.crypto.tls.Client.Options

now requires

entropy: *const [entropy_len]u8

and

realtime_now_seconds: i64

. Fill entropy with

std.Io.randomSecure

; compute seconds with

Io.Clock.now(.real, io)

ns_per_s

std.crypto.tls.Client.Options

现在需要

entropy: *const [entropy_len]u8

和

realtime_now_seconds: i64

参数。使用

std.Io.randomSecure

填充熵值；通过

Io.Clock.now(.real, io)

ns_per_s

计算秒数。

MemoryPool API changes

MemoryPool API 变更

std.heap.MemoryPool(T).initCapacity(allocator, n)

returns the pool;

create

destroy

now require allocator. No bare

init()

or zero-arg

deinit()

```
std.heap.MemoryPool(T).initCapacity(allocator, n)
```
返回内存池；
```
create
```
/
```
destroy
```
现在需要传入allocator参数。不再支持无参数的
```
init()
```
或
```
deinit()
```
。

Atomic order & Thread

原子顺序与线程

Atomic orders use
```
.monotonic
```
/
```
.seq_cst
```
;
```
.awake
```
removed.

原子顺序使用
```
.monotonic
```
/
```
.seq_cst
```
；
```
.awake
```
已被移除。

Format options

格式化选项

```
std.fmt.Options
```
replaces
```
FormatOptions
```
.
```
std.fmt.format
```
helper is gone; call
```
writer.print
```
directly (writers live in
```
std.Io.Writer
```
).

```
std.fmt.Options
```
替代了
```
FormatOptions
```
。
```
std.fmt.format
```
辅助函数已被移除；请直接调用
```
writer.print
```
（写入器位于
```
std.Io.Writer
```
中）。

Randomness / crypto changes

随机数 / 加密功能变更

std.crypto.random

was removed. Use an

std.Io

instance:

const io = std.Io.Threaded.global_single_threaded.ioBasic(); io.random(&buf);

Ed25519.KeyPair.generate

now requires an

io: std.Io

argument:

Ed25519.KeyPair.generate(io);

std.crypto.random

已被移除。请使用

std.Io

实例：

const io = std.Io.Threaded.global_single_threaded.ioBasic(); io.random(&buf);

。

Ed25519.KeyPair.generate

现在需要传入

io: std.Io

参数：

Ed25519.KeyPair.generate(io);

。

Enum conversion

枚举转换

std.meta.intToEnum

removed. Use

std.enums.fromInt(EnumType, value)

(returns

?EnumType

std.meta.intToEnum

已被移除。请使用

std.enums.fromInt(EnumType, value)

（返回

?EnumType

）。

Fixed-buffer writers in tests

测试中的固定缓冲区写入器

std.io.fixedBufferStream

was removed. For in-memory writes use

var w = std.Io.Writer.fixed(buf);

and read bytes with

std.Io.Writer.buffered(&w)

```
std.ArrayList
```
no longer has
```
.init(allocator)
```
shorthand; use
```
.initBuffer(slice)
```
for stack buffers or managed variants.

std.io.fixedBufferStream

已被移除。对于内存中的写入操作，请使用

var w = std.Io.Writer.fixed(buf);

并通过

std.Io.Writer.buffered(&w)

读取字节。

```
std.ArrayList
```
不再支持
```
.init(allocator)
```
简写；对于栈缓冲区请使用
```
.initBuffer(slice)
```
，或使用托管变体。

Stream/Conn helpers we added (compat pattern)

我们添加的流/连接辅助工具（兼容模式）

Build a thin compat layer that wraps platform syscalls to reintroduce
```
Stream { read, writeAll, close, readAtLeast }
```
and address parsing/formatting, plus
```
tcpConnectToHost/Address
```
using raw sockets.
For Unix sockets: build sockaddr manually and call
```
connect
```
.

构建一个轻量级兼容层，包装平台系统调用，重新实现
```
Stream { read, writeAll, close, readAtLeast }
```
以及地址解析/格式化，同时基于原始套接字实现
```
tcpConnectToHost/Address
```
。
对于Unix套接字：手动构建sockaddr并调用
```
connect
```
。

Testing adjustments

测试调整

For in-process client/server tests, use
```
socketpair(AF.UNIX, SOCK.STREAM|CLOEXEC, 0, &fds)
```
to avoid relying on Io vtable network (Threaded nets return
```
NetworkDown
```
if not wired).

对于进程内客户端/服务器测试，请使用
```
socketpair(AF.UNIX, SOCK.STREAM|CLOEXEC, 0, &fds)
```
，避免依赖Io虚表网络（如果未配置，Threaded网络会返回
```
NetworkDown
```
）。

Error sets tightened

错误集收紧

Many functions return narrower error sets (e.g., Reader.fill no longer includes
```
WouldBlock
```
/
```
Timeout
```
). Remove unreachable branches accordingly.

许多函数返回更窄的错误集（例如Reader.fill不再包含
```
WouldBlock
```
/
```
Timeout
```
）。请相应地移除不可达分支。

syscalls return types

系统调用返回类型

std.os.linux.*

return

usize

; cast with

@as(isize, @bitCast(rc))

before checking

< 0

. For

writev/epoll_wait

include the

count

argument.

Use this skill when upgrading 0.15-era code to 0.16-dev to avoid common build-breakers.

```
std.os.linux.*
```
返回
```
usize
```
；在检查
```
< 0
```
之前，请使用
```
@as(isize, @bitCast(rc))
```
进行类型转换。对于
```
writev/epoll_wait
```
，请传入
```
count
```
参数。

将0.15时代的代码升级到0.16-dev时，可参考本文避免常见的构建失败问题。