用 apps.toml 管理应用

每次运行都写 --source-root 容易出错。把源码根目录登记到工作区的 local/apps.toml 后，就可以用 tools/dev.sh sim hello --watch 进入开发循环。

1. 分清三个名称

以入门教程复制的 Hello 为例：

pxa-workspace/
  local/
    apps.toml
    my-apps/              ← source_root：应用目录的父目录
      hello/             ← CLI 参数与 TOML 登记名：hello
        package.json     ← manifest 中的 id：pxa-hello
        main.c
        i18n/

名称	例子	用在哪
源码根目录	`/home/me/pxa-workspace/local/my-apps`	`source_root` 或 `--source-root`
源码目录名	`hello`	`tools/app.sh build hello`、`[apps.hello]`
包内应用身份	`pxa-hello`	`pxadb package run pxa-hello`

source_root 不要写成 .../my-apps/hello，也不要指向 package.json。工具会在它后面拼接源码目录名。

当前 tools/dev.sh 按 pxa-<源码目录名> 构造安装和启动身份。新应用建议保持这条命名约定；如果 manifest 自定义了不同 ID，请分步构建，再按 pxadb package list 返回的实际身份启动。

2. 在 local/apps.toml 登记

从 PXA 工作区根目录执行下面命令，取得真实的绝对路径：

realpath local/my-apps

编辑 local/apps.toml，加入以下条目，把路径替换为刚才的输出。如果文件已有其他应用，保留原内容，只添加或修改对应条目，不要覆盖整份文件。

[apps.hello]
source_root = "/home/me/pxa-workspace/local/my-apps"

用实际绝对路径最稳妥。TOML 不会展开 $HOME、$PWD 或 $(pwd)；也不要依赖 ~，因为 Python 开发工具与 Shell 打包工具对它的处理不同。相对路径受执行命令时的工作目录影响，并非相对 apps.toml 所在目录。

3. 把日常命令缩短

完成登记后，以下命令都不再需要 --source-root：

# 构建桌面包
tools/app.sh build hello --target simulator

# 桌面持续开发
tools/dev.sh sim hello --watch

# 换成 Watcher 圆屏验证同一应用
tools/dev.sh sim hello --profile sensecap-watcher --watch

# 构建设备包
tools/app.sh build hello --board pai-touch --target esp32s3

# 直接在设备上持续开发
tools/dev.sh device hello --port /dev/ttyACM0 --watch

apps.toml 只解决“源码在哪里”。它不会自动为你选择串口、签名私钥、模拟屏幕或芯片目标；这些设置仍由命令参数和对应环境变量控制。

4. 多应用、多个仓库

假设你有如下独立仓库：

/home/me/projects/pxa-apps/
  weather/package.json
  clock/package.json
/home/me/projects/lab-apps/
  sensor-panel/package.json
  demo.clock/package.json

可以在同一份本机 catalog 中登记：

[apps.weather]
source_root = "/home/me/projects/pxa-apps"

[apps.clock]
source_root = "/home/me/projects/pxa-apps"

[apps.sensor-panel]
source_root = "/home/me/projects/lab-apps"

[apps."demo.clock"]
source_root = "/home/me/projects/lab-apps"

带点的名称要用引号：[apps."demo.clock"] 才是一个完整键；不加引号会被 TOML 解析为多层表。当前 catalog 按应用逐项登记，没有“整个目录通配注册”的配置格式。

登记 weather 后即可运行 tools/dev.sh sim weather --watch。新增应用时确保目录、manifest ID 和自己的代码已经准备好；登记条目本身不会创建应用。

5. 自动发现和临时覆盖

若应用位于工作区的 local/pxa-apps/hello/package.json，工具能够自动发现，无需专门登记。外部路径或 local/my-apps 则需要 catalog 或显式参数。

工具	源码选择顺序（从高到低）
`tools/app.sh`	`--source-root` → `PXA_APP_SOURCE_ROOT` → 对应的 `local/apps.toml` 条目 → `local/pxa-apps` 自动发现
`tools/dev.sh`	`--source-root` → 对应的 `local/apps.toml` 条目 → `local/pxa-apps` 自动发现

tools/dev.sh 不直接用 PXA_APP_SOURCE_ROOT 解析入口源码，不能假定两个工具完全一致。想让日常行为一致，优先使用 catalog 或显式参数。

临时测试另一个 checkout，不必修改 catalog：

tools/dev.sh sim hello --source-root /home/me/scratch/my-apps --watch

同名条目一旦选中但路径失效，工具不会因为目录不存在就自动退回其他源码。迁移仓库后要同步更新 catalog。

6. 验证配置与路径

在工作区根目录运行下面的只读检查。它使用 Python 标准库，不会安装、构建或修改应用：

python3 - <<'CHECK'
from pathlib import Path
import tomllib
catalog = tomllib.loads(Path("local/apps.toml").read_text())
for app, entry in catalog.get("apps", {}).items():
    value = entry.get("source_root") if isinstance(entry, dict) else None
    if not isinstance(value, str) or not value:
        print("MISSING source_root:", app)
        continue
    root = Path(value)
    manifest = root / app / "package.json"
    print("OK" if manifest.is_file() else "MISSING", app, manifest)
    if not root.is_absolute():
        print("  建议改为实际绝对路径")
CHECK

错误	常见原因与处理
No source root / no source root	没有登记、登记名与 CLI 参数不同，或不在自动发现目录
app source directory is unavailable	把父目录写成应用目录，或仓库已移动
TOMLDecodeError	重复表名、引号不配对，或把 JSON 写进 TOML
构建的是意外源码	检查显式参数及 `PXA_APP_SOURCE_ROOT` 是否覆盖 catalog
安装后找不到 App	对照源码目录名与 manifest ID，必要时使用实际完整身份启动

7. 团队协作与版本管理

工作区默认忽略 local/ 下的本机文件，local/apps.toml 不应装入设备或发布到商城。App 源码可以保存在独立 Git 仓库；每位开发者填写自己的绝对路径。共享时提供不带个人路径的配置示例和安装说明。

tools/factory.sh 的出厂配置也需要找到相应 App 源码，但 catalog 不负责决定预装哪些 App；预装列表属于 factory/profiles/。常规应用调试继续使用 PXADB，避免用出厂镜像覆盖已有数据。

接下来：建立日常开发循环，或为不同屏幕配置模拟器。

更多可运行应用与真实项目结构，见开源应用仓库 pxa-apps，包括商城、天气、街机游戏、诊断工具与 GameRender 示例。