C
Zig 独立于 C,也不像多数其他语言那样依赖 libc,但它重视与现有 C 代码交互。
Zig 通过多种方式便利 C 互操作。
C 基本类型
这些类型保证兼容 C ABI,可以像其他类型一样使用。
c_charc_shortc_ushortc_intc_uintc_longc_ulongc_longlongc_ulonglongc_longdouble
与 C 的 void 类型交互时,使用 anyopaque。
另见:
C 翻译命令行工具
Zig 的 C 翻译能力通过命令行工具 zig translate-c 提供。必须传入一个文件名参数,还可接收一组转交给 clang 的可选参数。翻译后的文件写入标准输出。
命令行选项
- -I:指定头文件搜索目录,可以重复使用。等价于 clang 的 -I 选项。默认不包含当前目录,可使用 -I. 将其包含。
- -D:定义预处理器宏。等价于 clang 的 -D 选项。
- -cflags [flags] --:向 clang 传递任意附加命令行选项。注意,选项列表必须以 -- 结束。
- -target:翻译后 Zig 代码的目标三元组。未指定时,使用当前宿主目标。
使用 -target 与 -cflags
重要!使用 zig translate-c 翻译 C 代码时,必须使用与编译翻译后代码时相同的 -target 三元组。此外,如有使用 -cflags,必须确保它与目标系统代码采用的 cflags 一致。错误的 -target 或 -cflags 可能导致 clang 或 Zig 解析失败,或者在链接 C 代码时出现隐蔽的 ABI 不兼容问题。
long FOO = __LONG_MAX__;$ zig translate-c -target thumb-freestanding-gnueabihf varytarget.h|grep FOO
pub export var FOO: c_long = 2147483647;
$ zig translate-c -target x86_64-macos-gnu varytarget.h|grep FOO
pub export var FOO: c_long = 9223372036854775807;
enum FOO { BAR };
int do_something(enum FOO foo);$ zig translate-c varycflags.h|grep -B1 do_something
pub const enum_FOO = c_uint;
pub extern fn do_something(foo: enum_FOO) c_int;
$ zig translate-c -cflags -fshort-enums -- varycflags.h|grep -B1 do_something
pub const enum_FOO = u8;
pub extern fn do_something(foo: enum_FOO) c_int;
翻译失败
部分 C 结构无法翻译为 Zig,例如 goto、带位域的结构体和进行标记拼接的宏。Zig 采用降级机制,在遇到不可翻译实体时继续翻译。
降级有三种形式:opaque、extern 和 @compileError。无法正确翻译的 C 结构体与联合会转换为 opaque{}。包含不透明类型或不可翻译代码结构的函数,会降级为 extern 声明。因此,不可翻译的类型仍可通过指针使用;只要链接器知道其编译后函数,不可翻译的函数仍可调用。
顶层定义(全局变量、函数原型、宏)无法翻译或降级时,使用 @compileError。Zig 对顶层声明采用惰性分析,因此除非实际使用这些不可翻译实体,否则不会导致编译错误。
另见:
C 指针
应尽可能避免此类型。使用 C 指针唯一合理的理由,是它出现在翻译 C 代码自动生成的代码中。
导入 C 头文件时,指针应该翻译为单项指针 *T 还是多项指针 [*]T 并不明确。C 指针是一种折中,使 Zig 代码可以直接使用翻译后的头文件。
[*c]T —— C 指针。
- 支持另外两种指针类型
*T和[*]T的全部语法。 - 可以强制转换为其他指针类型及可选指针。C 指针强制转换为非可选指针时,如果地址为 0,就会发生带安全检查的非法行为。
- 允许零地址。在非独立环境目标上,解引用零地址属于带安全检查的非法行为。可选 C 指针会像
?usize一样引入额外的一位来记录空值。不过无须创建可选 C 指针,直接使用普通可选指针即可。 - 支持与整数之间进行类型强制转换。
- 支持与整数比较。
- 不支持对齐等 Zig 专属指针属性。请使用普通指针。
C 指针指向单个结构体而非数组时,需要先解引用 C 指针,再访问结构体字段或成员数据,语法如下:
ptr_to_struct.*.struct_member
这类似于 C 中的 ->。
C 指针指向结构体数组时,语法恢复为:
ptr_to_struct_array[index].struct_member
C 可变参数函数
Zig 支持 extern 可变参数函数。
const std = @import("std");
const testing = std.testing;
pub extern "c" fn printf(format: [*:0]const u8, ...) c_int;
test "variadic function" {
try testing.expectEqual(14, printf("Hello, world!\n"));
try testing.expect(@typeInfo(@TypeOf(printf)).@"fn".attrs.varargs);
}$ zig test test_variadic_function.zig -lc
1/1 test_variadic_function.test.variadic function...OK
All 1 tests passed.
Hello, world!
可使用 @cVaStart、@cVaEnd、@cVaArg 和 @cVaCopy 实现可变参数函数。
const std = @import("std");
const testing = std.testing;
const builtin = @import("builtin");
fn add(count: c_int, ...) callconv(.c) c_int {
var ap = @cVaStart();
defer @cVaEnd(&ap);
var i: usize = 0;
var sum: c_int = 0;
while (i < count) : (i += 1) {
sum += @cVaArg(&ap, c_int);
}
return sum;
}
test "defining a variadic function" {
if (builtin.cpu.arch == .aarch64 and builtin.os.tag != .macos) {
// https://github.com/ziglang/zig/issues/14096
return error.SkipZigTest;
}
if (builtin.cpu.arch == .x86_64 and builtin.os.tag == .windows) {
// https://github.com/ziglang/zig/issues/16961
return error.SkipZigTest;
}
if (builtin.cpu.arch == .s390x) {
// https://github.com/ziglang/zig/issues/21350#issuecomment-3543006475
return error.SkipZigTest;
}
try std.testing.expectEqual(@as(c_int, 0), add(0));
try std.testing.expectEqual(@as(c_int, 1), add(1, @as(c_int, 1)));
try std.testing.expectEqual(@as(c_int, 3), add(2, @as(c_int, 1), @as(c_int, 2)));
}$ zig test test_defining_variadic_function.zig
1/1 test_defining_variadic_function.test.defining a variadic function...OK
All 1 tests passed.
导出 C 库
Zig 的主要用例之一是导出 C ABI 库,以供其他编程语言调用。在函数、变量和类型前添加 export 关键字,使它们成为库接口的一部分:
export fn add(a: i32, b: i32) i32 {
return a + b;
}创建静态库:
$ zig build-lib mathtest.zig
创建共享库:
$ zig build-lib mathtest.zig -dynamic
以下是使用 Zig 构建系统的示例:
// This header is generated by zig from mathtest.zig
#include "mathtest.h"
#include <stdio.h>
int main(int argc, char **argv) {
int32_t result = add(42, 1337);
printf("%d\n", result);
return 0;
}const std = @import("std");
pub fn build(b: *std.Build) void {
const lib = b.addLibrary(.{
.linkage = .dynamic,
.name = "mathtest",
.root_module = b.createModule(.{
.root_source_file = b.path("mathtest.zig"),
}),
.version = .{ .major = 1, .minor = 0, .patch = 0 },
});
const exe = b.addExecutable(.{
.name = "test",
.root_module = b.createModule(.{
.link_libc = true,
}),
});
exe.root_module.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.root_module.linkLibrary(lib);
b.default_step.dependOn(&exe.step);
const run_cmd = exe.run();
const test_step = b.step("test", "Test the program");
test_step.dependOn(&run_cmd.step);
}$ zig build test
1379
另见:
混合目标文件
Zig 目标文件可以与任何遵循 C ABI 的其他目标文件混合使用。例如:
const base64 = @import("std").base64;
export fn decode_base_64(
dest_ptr: [*]u8,
dest_len: usize,
source_ptr: [*]const u8,
source_len: usize,
) usize {
const src = source_ptr[0..source_len];
const dest = dest_ptr[0..dest_len];
const base64_decoder = base64.standard.Decoder;
const decoded_size = base64_decoder.calcSizeForSlice(src) catch unreachable;
base64_decoder.decode(dest[0..decoded_size], src) catch unreachable;
return decoded_size;
}// This header is generated by zig from base64.zig
#include "base64.h"
#include <string.h>
#include <stdio.h>
int main(int argc, char **argv) {
const char *encoded = "YWxsIHlvdXIgYmFzZSBhcmUgYmVsb25nIHRvIHVz";
char buf[200];
size_t len = decode_base_64(buf, 200, encoded, strlen(encoded));
buf[len] = 0;
puts(buf);
return 0;
}const std = @import("std");
pub fn build(b: *std.Build) void {
const obj = b.addObject(.{
.name = "base64",
.root_module = b.createModule(.{
.root_source_file = b.path("base64.zig"),
}),
});
const exe = b.addExecutable(.{
.name = "test",
.root_module = b.createModule(.{
.link_libc = true,
}),
});
exe.root_module.addCSourceFile(.{ .file = b.path("test.c"), .flags = &.{"-std=c99"} });
exe.root_module.addObject(obj);
b.installArtifact(exe);
}$ zig build
$ ./zig-out/bin/test
all your base are belong to us
另见: