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` 将能力分成两层：

1. **bindings 层**

   直接映射底层 C API，适合：

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

2. **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` 需要完成两件事：

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

参考写法：

.. code-block:: cmake

   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 工程的一部分参与交叉编译和链接。

最小工作流
----------

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

.. code-block:: zig

   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 时需先确认硬件条件