快速入门
本文档介绍如何快速开始使用 ARCS SDK 进行开发，包括环境搭建、编译示例和烧录运行。
Note
SDK 支持 Linux 和 Windows PowerShell 开发环境。请选择与你的主机系统对应的选项卡；Linux 推荐使用 Ubuntu 18.04 以上版本。
环境搭建
系统依赖
sudo apt update
sudo apt install -y wget bzip2 python3 git vim-common
vim-common 提供 tools/mkhdr/mkhdr.sh 写 image header 所需的 xxd 命令。
自动搭建（推荐）
在 SDK 根目录执行：
source env.sh
该命令会自动检测并设置工具链、开发工具包和 PATH，同时检查子模块状态。已就绪的环境可重复执行。
Tip
可使用子命令进行专项排查：
source env.sh check
source env.sh setup
source env.sh submodule sync
source env.sh info
手动搭建
如果自动搭建失败，可使用 SDK 内置脚本，或先下载对应平台的工具包：
bash tools/scripts/prepare_toolchain.sh
bash tools/scripts/prepare_listenai_tools.sh
手动安装后设置环境变量。路径必须使用绝对路径：
export NUCLEI_TOOLCHAIN_PATH=$HOME/.listenai/gcc
export LISTENAI_TOOLS_PATH=$HOME/.listenai/listenai-tools
$HOME 会由 shell 展开为绝对路径；在 IDE 配置等非 shell 环境中，请勿使用 ~。
使用 Windows 10/11 自带的 Windows PowerShell 5.1 或更新版本。 以下命令均在 SDK 根目录的 PowerShell 中执行。
选择工具安装目录
默认目录为 %USERPROFILE%\.listenai。如需更换目录，请在首次运行 env.ps1 前设置 LISTENAI_HOME。
工具安装路径不能含中文、空格；Windows 用户名含中文或空格时，必须更换默认目录。
建议 SDK 也使用不含中文、空格的目录，例如 C:\arcs-sdk。
以下以 C:\listenai 为例，请替换为实际安装目录：
# 当前终端使用此目录
$env:LISTENAI_HOME = "C:\listenai"
# 保存为用户环境变量，供以后启动的终端使用（无需管理员权限）
[Environment]::SetEnvironmentVariable("LISTENAI_HOME", "C:\listenai", "User")
当前终端设置后即可继续下一步。
保存后，重新启动终端应用（如 Windows Terminal、VS Code），即可读取该设置。
为所有用户配置时，在管理员 PowerShell 中将
"User"改为"Machine"。
选择以下一种方式搭建环境。
自动搭建（推荐）
在 SDK 根目录执行：
.\env.ps1
脚本会自动下载缺失的工具，设置工具路径和当前终端的 PATH。已就绪的环境可重复执行。
Tip
如提示禁止运行脚本，可在当前终端临时放开执行策略后重试：
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\env.ps1
手动搭建
下载工具链和开发工具包：
解压到工具安装目录。以
C:\listenai为例，目录结构如下：C:\listenai\ ├── gcc\bin\riscv64-unknown-elf-gcc.exe └── listenai-tools\cmake\bin\cmake.exe
设置环境变量，替换为实际安装路径。路径必须使用绝对路径和正斜杠
/：$env:NUCLEI_TOOLCHAIN_PATH = "C:/listenai/gcc" $env:LISTENAI_TOOLS_PATH = "C:/listenai/listenai-tools"
工具链和开发工具包可放在不同目录，路径不能含中文、空格。
两个变量分别优先于
LISTENAI_HOME；只设置一个时，另一个仍由LISTENAI_HOME推导。以上赋值仅对当前终端及其子进程生效。如需持久保存，参照前文设置对应的用户环境变量。
验证环境
完成自动或手动搭建后，在 SDK 根目录执行：
.\env.ps1 check
确认输出包含 GCC toolchain ready 和 listenai-tools ready，且无报错。
检查通过后，按 快速开始 编译示例。
Tip
可使用子命令查看路径或重新下载工具包：
.\env.ps1 info
.\env.ps1 setup
info 仅显示路径，不检查依赖；setup 会重新下载工具包。
FAQ / 常见问题
Q：构建时未找到 Python，或需要选择其他版本时怎么办？
通过构建参数指定实际的 Python 绝对路径：
.\build.ps1 -S samples/helloworld -DBOARD=arcs_evb `
"-DPython3_EXECUTABLE=C:/Python/python.exe"
实际使用的 Python 路径以构建日志为准。
Q：修改安装目录后，为什么仍使用旧路径？
自动推导的工具路径会随 LISTENAI_HOME 更新；单独指定的路径保持优先。
如需恢复自动推导，或当前终端运行过旧版 env.ps1，先清除相应变量再重试：
Remove-Item Env:NUCLEI_TOOLCHAIN_PATH, Env:LISTENAI_TOOLS_PATH `
-ErrorAction SilentlyContinue
.\env.ps1
若之前还保存了这两个用户或系统环境变量，请同步在 Windows 环境变量设置中删除需要恢复自动推导的项。
Q：SDK 路径包含中文、空格或位于 OneDrive 下时怎么办？
env.ps1会尝试将 SDK 映射到R:，也可用.\env.ps1 -ForceSubst主动启用。R:不可用时，只会复用已存在的有效目录联结%USERPROFILE%\arcs-sdk-win，不会自动创建。映射失败时，将 SDK 移至不含中文、空格的目录（如
C:\arcs-sdk）后重试。工具安装目录不参与映射，仍需满足前文的路径要求。
快速开始
编译示例
以 helloworld 工程为例，在 SDK 根目录下执行：
./build.sh -C -S samples/helloworld -DBOARD=arcs_evb
.\build.ps1 -C -S samples/helloworld -DBOARD=arcs_evb
命令参数：
-S：指定项目源码路径-DBOARD：指定目标板型-C：清理构建目录-B：指定构建目录（默认build）
编译成功后，构建目录会生成 helloworld.bin（烧录文件）和 helloworld.elf（调试文件）及其他相关文件。
烧录运行
准备工作
连接硬件
将串口板连接到开发板：开发板 TX 脚（默认 PA2）连接串口板 RX，开发板 RX 脚（默认 PA3）连接串口板 TX，开发板 GND 连接串口板 GND。具体引脚请以板型文件为准。
进入烧录模式
按住 BOOT 脚后复位开发板，进入烧录模式。每次重新烧录前都需要执行此操作。
自动烧录（推荐）
将开发板 BOOT 脚连接串口板 RTS 脚、RESET 脚连接串口板 DTR 脚，cskburn 即可自动控制进入烧录模式。
烧录命令
请根据当前系统选择命令：
./tools/burn/cskburn -C arcs -s /dev/ttyUSB0 -b 3000000 0x0 build/helloworld.bin
使用 ls /dev/ttyUSB* /dev/ttyACM* 查看设备；常见设备名为 /dev/ttyUSB0 或 /dev/ttyACM0。
.\tools\burn\cskburn.exe -C arcs -s COM7 -b 3000000 0x0 .\build\helloworld.bin
COM7 请替换为设备管理器中显示的实际端口号。
-s 指定烧录设备，-b 指定烧录波特率（推荐 3000000），0x0 为烧录起始地址，-C arcs 指定芯片类型。
验证运行
烧录完成后复位开发板，串口控制台应看到：
Running on hart-id: 1
Hello, world!
常见问题
Linux 串口权限
如果遇到串口权限问题，将当前用户添加到 dialout 组，然后重新登录：
sudo usermod -a -G dialout $USER