环境与源码准备

获取工作区与系统仓库

工作区与系统核心分别维护。工作区中的 deps/pxa-system 是独立 checkout；如果该目录已经存在，不要覆盖它。

git clone https://github.com/SmartArduino/pxa-workspace.git
cd pxa-workspace
git clone --recurse-submodules https://github.com/SmartArduino/pxa-system.git deps/pxa-system
git -C deps/pxa-system submodule update --init --recursive

已有环境先记录两个仓库的提交号。WAMR 版本以 deps/pxa-system/config/wamr.json 为准，避免单独升级运行时导致 AOT ABI 不匹配。

主机依赖

准备 Git、Bash、Python 3.11+、CMake、C/C++ 编译器、支持 WebAssembly 的 Clang 与 OpenSSL。桌面构建需要 OpenSSL、LZ4、SDL2、libpng 开发库；使用 WASI libc 的应用还需要匹配的 WASI SDK。

Ubuntu / Debian 的常用基础依赖示例：

sudo apt-get install git build-essential cmake ninja-build python3-venv \
  clang lld openssl libssl-dev liblz4-dev libsdl2-dev libpng-dev
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e tools/pxadb
pxadb --help

发行版的 Clang 包不一定包含完整 WASI sysroot。出现缺少标准头文件或链接器错误时，检查 WASI_SDK_DIR 与应用的 CMake 配置；只设置一个不存在的目录不会安装工具链。首次 AOT 打包可能还需下载或构建匹配的 WAMR 编译器。

检查系统构建

cmake -S deps/pxa-system -B build/pxa-system
cmake --build build/pxa-system
ctest --test-dir build/pxa-system --output-on-failure

桌面模拟器默认获取固定 LVGL 版本。离线构建可提供 -DPXSYS_LVGL_SOURCE_DIR=/path/to/lvgl。这一步验证主机侧核心和依赖，不代表真实板子已经适配。

ESP 固件环境

只做桌面 App 开发可暂时跳过 ESP-IDF。编译固件前，先安装板子需要的 ESP-IDF 及目标工具链，并在当前终端执行其 export.sh，确认 idf.py --version 正常。

工作区公共 manifest 当前声明 IDF >=5.5.4；ESP32-S31 等目标还需要支持该芯片的 IDF / 工具链版本。应同时检查对应板子的 README、board.cmake 与依赖锁文件，而不是把最低版本当作所有板子的推荐版本。

目录约定

目录	用途
`deps/pxa-system`	系统核心、SDK、示例与打包器
`firmware/boards`	每块板子的配置和驱动
`local/apps.toml`	本机源码 catalog，让开发命令省去 --source-root
`local/my-apps`	本教程的个人 App 源码
`local/app-output`	打包产物
`local/dev-logs`	开发循环日志
`local/simulator`	模拟器持久状态

下一步：构建并运行第一个应用。

完成第一个 App 后，建议设置 local/apps.toml，再选择合适的模拟器 Profile。

获取开源应用集合（可选）

想直接运行商城、天气或游戏示例，可在工作区根目录添加第三个独立仓库；已有该目录时不要覆盖：

git clone https://github.com/SmartArduino/pxa-apps.git local/pxa-apps

这份仓库由工具自动发现，通常不需要逐个登记源码路径。完整说明见开源应用仓库 pxa-apps。