应用开发

PXA 创作与开发指南

打包、签名与版本

选择目标架构、维护发布者身份,并生成可验证的交付产物。

中文指南 · 4 分钟阅读 · PXA 0.10.0
适用环境与阅读准备

适用环境独立 App

开始前Hello 已创建;命令中的路径均从项目父目录计算

术语速查 →

一次构建,多目标交付

pxa build hello --target esp32s3,esp32s31,simulator

CMake/Ninja 编译一次 Wasm,每个 CPU 生成匹配 AOT,资源统一编译,最后签名并组装一个 .pxa 容器。设备按目标、引擎 ABI 和 Core/服务要求选择可运行制品。使用 --aot-only 可移除不需要的 Wasm 回退。需要同时支持浏览器试玩时应保留 Wasm:芯片 AOT 不能在网页执行,只有 AOT 的包仍可安装到目标设备。

hello/dist/pxa-hello.pxa 是安装和发布单位。旁边的 provenance 与 build JSON 记录实际工具路径/版本、锁定输入、目标和哈希;它们不会被加载到设备内存。容器分块编码按流读取,避免同时保留源文件、所有分块和压缩副本。

新容器与安装内存

DevKit 0.9.0 起新构建默认使用 Container 0.2、DEFLATE 和 4 KiB 解压块,扩展名仍为 .pxa。支持它的固件先认证块索引,再边接收边校验和解压到候选目录,成功后提交。无需同时保留完整压缩包和展开副本;应用更新仍需保留旧版本直到提交完成。

运行时直接读取已展开文件,没有压缩包解压开销。解压工作内存随块大小有界,不随整个包大小增长;内存不足时安装失败并清理候选,已安装版本保留。普通启动不再对所有文件做完整扫描,安装及事务恢复仍执行完整校验。

PXA 0.7 默认关闭旧版 Container 0.1 安装兼容,已经安装的应用及存档不受影响。自定义固件可开启 CONFIG_PXA_ENABLE_LEGACY_CONTAINER=y;原生 Host 使用 CMake -DPXA_ENABLE_LEGACY_CONTAINER=ON,对应 C 宏默认为 0。标准 0.7 商城目录只提供新容器,开启兼容后可用 PXADB 手动安装旧包。旧固件不能安装新格式,商城会同时检查应用包和绑定资源包的格式要求。确需向旧固件打包时,工作区打包脚本可设置 PXA_CONTAINER_STREAM=0,底层容器工具可用 --legacy,默认生成旧版 LZ4 包。既有项目的 pxa.lock 不会被自动改写。

缓存与可复现输入

项目 .pxa/ 分别保存稳定的 CMake 构建目录、AOT 内容缓存、资源缓存和签名包缓存。AOT 缓存由 Wasm、编译器和 CPU 参数决定;资源缓存包含声明的源图与调色板,即使它们不在 assets 目录内。

无改动重建复用最终签名包,因此哈希保持不变。P-256 签名本身包含随机性,清空缓存后重新签名的文件哈希可能变化;比较构建内容与比较已签名容器不是同一件事。

锁与升级

pxa.lock 记录发行版本、SDK 内容、WASI SDK、AOT 编译器和 WAMR/LLVM 固定提交。它不包含开发私钥或本机绝对路径。

pxa sdk update hello --offline
pxa build hello --offline

升级是显式操作,之后须重新验证。Core major 不兼容时旧包不可直接运行。AOT ABI 标签是运行时格式标识,名称含 core-1 不代表 Guest 仍使用 Core 1。

正式发布:生成并保存自己的密钥

下面操作只执行一次。设置 DevKit 的实际绝对路径,并选一个仓库以外的私钥路径;子 shell 的检查防止误覆盖已有密钥:

export PXA_DEVKIT="$PWD/pxa-devkit-0.10.0-linux-x86_64"
export PXA_SIGNING_KEY="$HOME/.local/share/pxa/publishers/my-publisher.pem"
(
  set -eu
  test ! -e "$PXA_SIGNING_KEY"
  mkdir -p "$(dirname "$PXA_SIGNING_KEY")"
  umask 077
  "$PXA_DEVKIT/runtime/bin/openssl" genpkey -algorithm EC \
    -pkeyopt ec_paramgen_curve:P-256 -out "$PXA_SIGNING_KEY"
)
pxa build hello --target esp32s3,esp32s31,simulator --signing-key "$PXA_SIGNING_KEY"
pxa publish hello/dist/pxa-hello.pxa --check-only

若该路径已有自己的密钥,跳过生成子 shell,直接使用;不要删除旧密钥来消除 test 的失败。下一篇商城发布使用同一个私钥生成公钥持有证明。私钥需自行安全备份,不能由商城找回。此例生成未加口令的 PEM,权限为仅当前用户可读写。

资源与发布者身份

资源文件放在 assets,或在 resources.json 声明编译输入。多目标包共享资源;具有 assets-esp32s3 等目标专属目录时,分别构建目标包再作为同一版本提交。应用版本和 release_sequence 必须一致,且使用同一发布者身份。

默认开发密钥在用户数据目录生成。正式发布应使用 --signing-key /安全目录/publisher.pem 或 PXA_SIGNING_KEY,并登记对应公钥。不要把私钥、上传令牌或 SDK 缓存放入应用仓库。

pxa publish 校验并上传现有文件,不构建、不重新签名。商城审核发布以后禁止覆盖制品;更新必须提高 release_sequence。

参考实现与资料tools/app.sh ↗pxa/package_app.sh ↗package/build_package_manifest.py ↗

输入关键词,搜索全部教程。