# 构建、Git、imgs 与 PSP 交接证据

## 项目内证据目录

新项目必须包含：

```text
doc/bsp_adaptation/
├── adaptation_report.md
├── inputs/
├── validation/
├── handoff/
│   └── psp_handoff.json
└── status.json
```

`adaptation_report.md` 至少记录参考与目标、芯片/SDK/Flash/系统形态、交付级别、调查范围、验证模式、用户确认、输入依据、修改文件、旧值与新值、继承项、GPIO/DTS 冲突处理、内存/分区检查、未执行验证、风险和真实状态。

小型 GPIO List、内存或分区需求原样复制到 `inputs/`。大型或敏感原理图、芯片手册和工程资料默认不重复复制，只记录受控路径、版本、适用型号和 SHA-256。禁止保存密钥、token、证书内容或许可证凭据。

CSV 只有从原理图提取或重新映射 Pinmux 时才作为派生审核证据写入 `inputs/`；它不是唯一事实源。

## 本地 Git

`EmxRes` 已有 Git worktree 只用于只读状态、参考项目脏文件发现和差异证据。不得执行 `git init`、`add`、`commit`、`stash`、清理、分支切换、历史改写或 `push`。

项目创建本身不需要远端 Git。根仓库其他项目的改动不阻塞；与参考或目标重叠的已有改动必须先确认。

## 项目创建阶段

仅创建 `config-project` 或只读审查时不执行：

- `ep_kernel.sh`；
- `ep_uboot.sh`；
- `EPSYNCSDKConfig.sh`；
- `EMX2_BuildSDKTool`。

这些脚本会将配置复制或 `rsync` 到项目外 SDK，有的还会改变脚本权限或访问远端。仅创建配置项目时只完成目录、配置回读、DTS/GPIO 静态一致性、精确差异白名单和文档检查。任务要求 `bsp-build-artifacts` 或更高交付级别时，静态检查完成后按下一节自动执行标准全量编译。

## 统一编译

需求和实施方案已经确认、任务需要构建产物时，标准流程自动执行：

```bash
cd ~/EapilBsp/EMX2.0/EmxRes
source tools/script_completion.sh
EMX2_BuildSDKTool <项目名> <YYYYMMDD_N> all
```

`YYYYMMDD` 使用 Asia/Shanghai 当前日期；未指定时选择尚不存在的最小正整数序号。默认全量 `all`，只有用户明确要求时使用组件构建。

先运行：

```bash
python3 <BSP Skill>/scripts/bsp/bsp_preflight.py build \
  --project <项目名> \
  --version <YYYYMMDD_N>
```

`passed=true` 只是构建的必要条件。执行前把工具返回的精确工作目录、完整命令、项目与 SDK 路径、构建范围、最终 imgs 版本路径、工作区状态、配置同步副作用，以及统一脚本中的远端 `git fetch origin` 写入记录。CV184X 还须按下文检查 `requires_patch_precheck`；不能把这一字段当成普通提示后继续自动构建。不得从 `EmxRes` 的父目录启动，也不得依赖登录 Shell 的偶然当前目录。

CV184X 还要执行 [CV184X 板级配置与构建链](cv184x-sdk-readonly-review.md)中的补丁门禁。其统一脚本在补丁检查失败后会尝试 `--applypatch --force`，可能重置多个 SDK 子仓库；这不属于上述自动构建授权。相关仓库存在未确认改动、补丁检查未通过或无法证明不会进入强制重置分支时，停止自动构建并向用户展示精确风险，不能静默运行或代替用户批准丢弃改动。CV181X 不套用这个补丁流程。

下列情况不自动处理：预检失败、统一脚本或路径与固定规则不符、输出版本已存在、参考或目标出现新的重叠改动、需要直接运行同步脚本、需要组件构建、需要改变构建参数、需要修改统一脚本，或者构建失败后需要清理和重试。此时停止并向用户说明异常、影响和可选处理方式。

不得修改、注入或静默绕过统一构建脚本的远端检查。本地免远端模式属于独立工具优化任务。

## 输出冲突与权限

输出目录通常为：

```text
/epbuild/EMX2.0/EmxRes/<项目名>/imgs/<构建版本>
```

已存在时默认停止并建议下一序号。绝不自动向“强制删除并继续”回答 `yes`；覆盖需要针对精确绝对路径的独立确认。

构建前记录新项目内同步脚本权限；统一脚本临时 `chmod 777` 后，构建结束恢复已记录的原权限并写入报告。只恢复新项目内的已知文件，不改 SDK 或其他项目权限。

编译命令成功后，`record_build_handoff.py` 必须在生成交接文件前自动处理本次精确 imgs 版本路径：

- 从 `--output-root` 到本次 `<项目名>/imgs/<构建版本>` 的路径节点都补齐 `a+rx`，保证所有用户都能读取并进入目录；
- 本次版本目录内递归执行等价于 `a+rX` 的受控处理：目录补齐 `a+rx`，普通文件补齐 `a+r`，只有原本带执行位的文件才补齐 `a+x`；
- 不跟随软链接，不改软链接目标，不处理其他项目或其他构建版本，也不使用 `chmod -R 777`；
- 不使用 `sudo`。当前用户无法修改权限、路径节点不是普通目录、输出包含特殊文件或复核仍不满足要求时立即停止，不能生成 `build_passed`；
- 将处理前后模式、变更数量和复核结果写入 `validation/output_permissions_<构建版本>.json`，并同时写入 PSP 交接 manifest。

## 构建证据与状态

成功必须同时满足：

- 命令退出码为零；
- 日志到达正常完成阶段；
- 输出目录存在且含非空固件文件；
- 本次精确 imgs 版本路径已经通过 `a+rX` 权限处理与复核；
- 当前项目实际生效的分区表可唯一确定，或已显式指定 `configs/` 内精确文件；
- 最终 imgs 中唯一 `kernel.bin` 和 `rootfs.bin` 相对各自最小对应分区均保留至少 512 KiB（524288 字节）；
- 文件名、大小和 SHA-256 清单写入 `validation/`；
- 构建后项目源码差异仍通过白名单。

满足以上条件后运行：

```bash
python3 <BSP Skill>/scripts/bsp/record_build_handoff.py \
  --project <项目名> \
  --build-version <YYYYMMDD_N> \
  --build-exit-code 0 \
  --completion-marker-seen \
  --risk <仍存在的硬件风险>

python3 <BSP Skill>/scripts/bsp/project_guard.py audit-final \
  --target-project <项目名>
```

自动发现多个 `partition*.xml` 时，上述记录命令必须追加：

```bash
--partition-table configs/<实际生效路径>/partition_spinand.xml
```

该参数只接受当前 BSP 项目 `configs/` 内的文件。检查失败时脚本不会生成 `build_passed` handoff。

记录脚本生成或更新：

- `validation/artifact_manifest_<构建版本>.sha256`；
- `validation/image_partition_margin_<构建版本>.json`；
- `validation/output_permissions_<构建版本>.json`；
- `handoff/psp_handoff.json`；
- `status.json`。

`psp_handoff.json` 遵循统一入口的 [BSP→PSP 交接契约](../../firmware-lowlevel-development/references/bsp-psp-handoff.md)。`audit-final` 必须在这些文档写入后执行；它使用 prepare 时冻结的参考清单，而不是假定参考项目从未变化。

成功时保存简明摘要、输出路径权限证据、kernel/rootfs 分区余量证据、固件哈希清单和精确 imgs 版本路径；失败时保存完整日志、阶段和关键错误。后续同步或编译失败不删除已经通过静态门禁的正式项目，只更新状态。不得只记录 `imgs` 软链接、父目录或“latest”；交付和 PSP 依赖必须绑定具体构建版本目录。

没有同步和编译时写：

```text
本地 BSP 配置项目已创建；尚未同步 SDK，尚未完成编译验证
```

本地编译成功也不能替代板上 GPIO、电平、时序、外设或负责人验收。

## 最终回复

完成构建时必须显式输出：项目路径、精确 imgs 版本路径、`a+rX` 权限复核结果及证据路径、kernel/rootfs 的镜像大小、最小对应分区大小和实际余量、余量证据路径、交接 manifest 路径、产物清单/hash 路径、`audit-final` 结果，以及硬件/负责人/发布状态。没有生成交接 manifest 时不能声称已完成 PSP 交接。