Zig 模块本体与关键文件

Linux 安装示例

未安装 Zig 时的典型表现

labs/zig/adapter/CMakeLists.txt 与 labs/zig/adapter/zig_target.cmake 都会通过 find_program() 查找 zig。如果开发机未安装 Zig，或者 PATH 中找不到 zig，配置阶段会直接失败。

Zig 支持的核心文件如下：

labs/zig/adapter/CMakeLists.txt：注册共享 arcs-zig 目标并导出头文件路径
labs/zig/adapter/build.zig：定义 Zig 侧库构建入口、目标平台与 include 路径
labs/zig/adapter/zig_target.cmake：为 target 编译单独的 .zig 源文件并参与链接
labs/zig/adapter/src/root.zig：定义 @import(“arcs”) 暴露的总入口

架构分层

labs/zig/adapter/src/root.zig 将能力分成两层：

bindings 层

直接映射底层 C API，适合：
- 保持与 C 数据结构/ABI 严格一致
- 做绑定验证、结构体布局检查
- 在 Zig 中直接访问底层接口
HAL 层

提供更符合 Zig 风格的封装，适合：
- 以对象/方法方式使用设备
- 统一错误处理
- 在 sample 中快速编写应用逻辑

@import(“arcs”) 提供的主要能力

系统与基础设施：

allocator
log
Thread
Mutex
Semaphore
Channel
Timer
RingBuffer

设备与外设：

Device
Gpio
Uart
I2c
Spi
Adc
Pwm
Flash
Display
Rtc
Audio

连接相关：

Bluetooth
WiFi

构建集成方式

典型的 target CMakeLists.txt 需要完成两件事：

正常创建 ARCS SDK 可执行目标
通过 LISTENAI_ZIG_APP 声明 target 自己的 .zig 文件

参考写法：

cmake_minimum_required(VERSION 3.19)
set(CMAKE_EXPORT_COMPILE_COMMANDS ON)

find_package(listenai-cmake REQUIRED HINTS $ENV{ARCS_BASE})
project(zig_helloworld)

set(LISTENAI_ZIG_APP ${CMAKE_CURRENT_SOURCE_DIR}/src/zig_app.zig)

listenai_add_executable(${PROJECT_NAME})
listenai_maybe_enable_zig_target(${PROJECT_NAME})
target_sources(${PROJECT_NAME} PRIVATE src/main.c)

listenai_maybe_enable_zig_target() 会在检测到 LISTENAI_ZIG_APP 后自动完成以下工作：

链接 arcs-zig
编译并链接 target 自己的 .zig 文件

zig_target.cmake 内部会执行以下工作：

调用共享 Zig adapter 的按需初始化逻辑
编译 target 中的 .zig 文件并挂接到当前目标

更具体地说，helper 内部会继续完成这些底层步骤： - 查找本机 Zig 编译器 - 将 target 中的 .zig 文件编译为目标文件 - 为 root module 注入 arcs 依赖 - 追加 ARCS SDK 头文件搜索路径，以满足 @cImport 所需的 C 头文件访问

目标平台与工具链约束

根据 labs/zig/adapter/build.zig 与 labs/zig/adapter/zig_target.cmake 的定义，当前 Zig 构建链路面向：

riscv32-freestanding-none
与现有 ARCS SoC / RISC-V 工具链兼容的 CPU 特性配置
与 SDK 现有 C 代码一致的 include 体系

这意味着 Zig 代码并不是脱离 ARCS SDK 独立构建，而是作为当前 SDK 工程的一部分参与交叉编译和链接。

最小工作流

在 sample 中保留一个 C 入口文件，例如 src/main.c
在 Zig 侧导出可由 C 调用的函数，例如：

const arcs = @import("arcs");

export fn zig_hello_main() callconv(.C) i32 {
    arcs.log.init() catch return -1;
    arcs.log.info("Hello from Zig on ARCS SDK!", .{});
    return 0;
}

注意事项

Zig sample 仍依赖 C 入口和现有 ARCS SDK 工程骨架，不是纯 Zig 裸工程
工程必须能找到 Zig 编译器，否则 labs/zig/adapter/CMakeLists.txt 与 zig_target.cmake 会直接报错
Zig bindings 与 HAL 暂时以当前已封装模块为准，后续能力范围可能继续扩展
某些 sample 依赖特定板级外设、panel、WiFi 或音频设备，阅读 sample README 时需先确认硬件条件