Documentation › buildpy-targets

LeonOS 4 旧构建系统：生产目标全量清单（P0-a 事实底稿）

供主 Agent 撰写 docs/build/migration-inventory.md 使用。

全部行号基于 2026-09-19 工作区 build.py（4958 行）与 buildsystem/。

本文件位于 gitignore 的 buildsystem/logs/ 下，不是交付物本身。

未运行任何 python3 build.py ...；所有统计来自静态阅读 + 只读文件系统 glob。

0. 对任务描述中已知前提的事实校正

1. paths.out 与旧目录布局（buildsystem/core/state.py:47-137）

BuildPaths(root=ROOT)，ROOT = Path(build.py).resolve().parent。没有 arch/profile 维度，全仓库只有一棵输出树。

其他硬编码输出位置（不走 BuildPaths）：

• include/generated/build_info.h —— 受版本控制的源码树路径（build.py:763），由 build-info 每次重写。
• LeonOS4-Developer-SDK.zip = ROOT / "LeonOS4-Developer-SDK.zip"（build.py:936）—— 源码根目录，gitignore 已豁免（.gitignore 末段）。
• Kconfig.components —— tools/generate_component_kconfig.py 默认 --output Kconfig.components，受版本控制的源码树路径，由 config-sync 每次重生成。
• buildsystem/cache/apk/{downloads,distributions} —— 真正的内容寻址缓存（键 = SHA-256），见 §7。

relative()（build.py:302-310）：绝对路径若在 ROOT 下则转 ROOT 相对，否则保留绝对。所有 target command 以 cwd=ROOT 执行（Target.cwd 在本仓库从未被赋值，grep 'cwd=' build.py 只命中 subprocess 调用），因此命令里大量出现 ROOT 相对路径。

2. 机制层：buildsystem/core/

2.1 数据模型（model.py，187 行）

Target slots（model.py:15-37）：name, outputs, inputs, implicit_inputs, depends_on, kind, description, command, action, action_key, depfile, cwd, group, always, source, environment。all_inputs() = inputs + implicit_inputs。

BuildGraph（model.py:44-187）关键行为：

2.2 调度与并行（runner.py:557-773）

• 闭包：graph.closure(roots)（roots 由 build_roots() 决定，见 §2.6）。
• 就绪集：ready = [无依赖目标]，LIFO（ready.pop()，runner.py:743）→ 完成顺序不稳定，A08（-j1 vs -j8 可比性）基线需注意。
• 线程池：ThreadPoolExecutor(max_workers=settings.worker_threads)（runner.py:739）。
• 进程上限：threading.BoundedSemaphore(max_processes)（runner.py:585），只包裹 run_process，不包裹 Python 侧 action 的文件 IO。
• worker 槽位：queue.Queue 里放 worker_threads 个整数，仅用于日志 <N> 前缀。
• 失败处理：第一个 future 抛异常 → 记录 failed → pending.cancel() 所有在跑 future → break → 重新抛出（runner.py:750-771）。已启动的子进程不被杀（无进程组管理）。
• 完成后校验 metrics.completed != len(closure) → BuildFailure("build graph did not complete")。
• mtime 缓存：self._mtime_cache + _mtime_lock（runner.py:592-593, 943-966），单次构建内同一路径只 lstat 一次；_refresh_mtimes 在执行后刷新。
• 进度 UI：ProgressRenderer（runner.py:102-175），仅 TTY 且 theme=="default" 时启用；--theme linux|meson|cargo 伪装 make/ninja/cargo 输出（runner.py:226-424）。规格 §3 明确不重新实现。
• 配置来源：buildsystem/config/settings.toml → load_settings（ui.py:14-30），缺文件时自动写入 worker_threads = max_processes = os.cpu_count()、download_retries = 3。build.py settings 提供 curses 编辑器。

2.3 缓存与增量判定（runner.py:918-1030）

不是内容寻址。 三层：

1. 声明指纹 _fingerprint()（runner.py:918-932） sha256(json.dumps({name, kind, outputs[], inputs(all_inputs)[], depends_on[], command[], action: action_key, depfile, environment}, sort_keys=True))，路径先经 root_relative()。 → 只哈希声明字符串，不哈希任何文件内容。改变 action_key 字面量、增删输入、改命令 argv、改 environment 都会让该 target 及其下游（靠 mtime 链）重建。
2. 时间戳比较 rebuild_reasons()（runner.py:968-997）

always                              → 重建
无 outputs 且有 action/command       → 重建（"target has no declared outputs"）
无 outputs 且无 action/command（group）→ 永不重建
任一 output 缺失                     → 重建
指纹变化                             → 重建
oldest_output = min(lstat mtime_ns(outputs))
对 inputs + implicit_inputs + depfile_dependencies 逐项：
    缺失            → 重建
    mtime > oldest_output → 重建

artifact_mtime()（runner.py:447-459）用 lstat，若是符号链接再取 max(lstat, stat)（跟随目标，允许 dangling）。

1. depfile：仅 add_compile 生成的 .o.d。parse_depfile()（runner.py:469-503）自己实现 Make 风格解析（\-续行、:-分隔、反斜杠转义、相对路径归 ROOT），结果存入状态 depfile_dependencies，下次参与 mtime 比较。

状态持久化：TaskStore.write_target 只改内存 dict，flush_target_states() 在 close() / 成功 / 异常时把整个 buildsystem/state/targets.json（{"version":1,"targets":{...}}）用 atomic_json（tempfile + os.replace，state.py:26-34）一次性替换。当前该文件已 2.6 MB / 1568 条，其中含大量已删除的旧 target（compile:libc、compile:static-libc、compile:ld-leonos、picolibc、tcc、python、musl-gcc、esp:api:、gcc-probe-、installer-policy:oobe），只有显式 build.py cache prune（prune_target_states，state.py:240-268，按输出是否存在判过期）才清理。

关键缺陷（迁移必修复位）：mtime 判定对"内容变了但 mtime 变旧/相同"（touch -d、rsync、git checkout）不敏感；符号链接目标改变但 lstat 未变时 esp:layout-links 一类可能漏重建；always=True 目标每次都跑，其"输出"即使内容不变也会让依赖它的 mtime 链不动（因为 ensure_parent 只在内容变化时写）——这层"内容稳定写"完全散落在 action 里。

2.4 配置解析（Kconfig → 构建选择）

2.5 组件清单解析（buildsystem/components.py，361 行）

• load_components(configs/components.toml)（81-199）：tomllib，强制 version == 1；字段校验（ID_RE/SYMBOL_RE/STAGE_PATH_RE，kind ∈ {system-app, program-app, package-app, tool, library}，default/required/stage/entry/sdk/api 必须 bool，extensions 必须 .name 形式）；depends / api_requires 引用存在性 + 两次独立 DFS 环检测；重复 id/symbol 拒绝。当前 73 个组件：system-app 24、program-app 35、package-app 3、tool 7、library 4。
• resolve_components(components, values)（218-290）：build = required or CONFIG_..._BUILD，depends 递归强制置真，api_requires 会反向把依赖也置真；导出 {build, image, entry, sdk, api} 五个布尔。required 组件忽略用户符号、直接用 manifest 默认（266-275 注释）。
• validate_component_targets(components, ROOT)（316-361）：app 类必须在 userland/apps/<id> 或 userland/<id>（nano 额外允许 third_party/nano/src，fastfetch 走 5 个固定 package 输入）有 .c/.S/.cpp；tool 类要求 userland/<id> 存在；library 类要求 third_party/<id> 存在。构图阶段的前置断言。
• 消费点：build_graph 里 component_enabled(id, option)（build.py:735-737）驱动约 40 处 if 分支，决定 target 是否存在、esp_names 内容、user_targets 聚合成员、SDK 参数列表。
• 唯一"权威面"（对齐规格 §7）：configs/components.toml = 组件元数据；Kconfig + Kconfig.components = 功能选择；configs/default.conf = 编译/运行默认值。build.py 里没有第三份 defaults 副本（除 BUILD_PRESET_VALUES 与 CONFIG_CHOICE_GROUPS）。

2.6 build-info 与 build number（污染每次构建）

• build_roots()（build.py:4213-4216）：除 BUILD_NUMBER_EXEMPT_TARGETS（build.py:135-197，61 个名字，几乎全是 test-*）和 build-info 本身以外，所有 CLI 运行都把 build-info 当作额外根节点。
• build-info 是 always=True（build.py:1074），执行 python3 tools/build_info.py --header include/generated/build_info.h --state buildsystem/state/build_number.txt；build_info.py:36 无条件 build_number = read + 1，:37 datetime.now() 写入 LEONOS_BUILD_TIME / LEONOS_COPYRIGHT_YEAR，无 SOURCE_DATE_EPOCH 支持，且总是重写（无 write-if-changed）。
• 后果：include/generated/build_info.h 每次 mtime 变化 → 所有把它列为 input/implicit input 的 target 全部重建（kernel/ntclks/version.c 的编译显式带 build_info，见 build.py:1230）→ 内核重链 → loader-integrity → loader-image → 所有镜像。
• 下游读 header 内容：tools/build_rpr_pages.py:19-20, 42-55 用正则解析 LEONOS_KERNEL_VERSION / LEONOS_BUILD_NUMBER 并断言二者一致；tools/build_rpr_apps.py:16 同理。

2.7 任务记录、日志与后台 client

• TaskStore.new_id()（state.py:152-175）：secrets.randbelow(900_000_000)+100_000_000，open("x") 独占创建，最多重试 256 次 → 九位随机任务 ID（规格 §3 明确不再这么做）。
• 记录：buildsystem/state/tasks/<id>.json，字段 id/command/status/created_at/log，运行中被 update() 追加 queued_at/started_at/finished_at/task/total_targets/completed_targets/running_targets/progress_percent/elapsed_seconds/metrics/error/profile。每次 update = 读 JSON → 合并 → atomic_json 整文件重写（runner.py:775-786 _publish_progress 在每次 dispatch 和每次完成都调用 → O(N) 次全量写）。
• 日志：buildsystem/logs/<id>.log，TaskLogger 构造时 open("w") 截断（runner.py:198），每行 strip_ansi 后写入并 flush，带线程锁。
• build.py status <id> / build.py log <id>：log 直接 subprocess.run(["vim","-R",<path>])（build.py:4822）→ 隐式依赖 vim。
• 后台执行 build.py client run <task>：run_client（build.py:4613-4667）写一条 queued 记录 → subprocess.Popen([PYTHON,"build.py","--worker","--task-id",id,...], stdin=DEVNULL, stdout=stderr=/dev/null, start_new_session=True) 立即返回，无守护进程、无 wait、无并发限制。这是规格 §3 "不做后台 daemon" 的对应物。

2.8 前置检查与宿主工具表

• require_linux()（4130）：platform.system() != "Linux" 即失败；另外模块导入时 os.name == "nt" 直接 SystemExit（build.py:95-98）。
• require_tools(task_tools(task))（4135-4198）：手工 if 链，按 target 名返回工具元组，未命中返回 ()。已登记：clang, ld.lld, llvm-ar, autoreconf, autoconf, automake, libtoolize, make, gcc, g++, gperf, flex, bison, rustc, grub-mkfont, grub-mkstandalone, truncate, mkfs.fat, mcopy, mke2fs, dd, qemu-img, grub-mkrescue, xorriso, qemu-system-x86_64。 表里缺失但实际会被调用：curl、git、openssl、patch、fakeroot、unshare、e2fsck、readelf、llvm-ranlib、grub-mkimage、python3 本身、llvm-objcopy、apk.static。→ 迁移到 make doctor 时必须补全（规格 §4）。
• require_grub_efi_modules()（4142-4153）：只对 10 个 target 名生效，检查 buildsystem/deps/grub-efi-amd64-bin/... 或 /usr/lib/grub/x86_64-efi/modinfo.sh。
• 构图阶段的源码存在性断言：build.py:1005-1046（busybox / nano / fastfetch / sl / less / lua / cmd / pleditor / zlib / libpng / file / sqlite / portablegl 各缺文件即 GraphError）。这些是子模块初始化检查，等价 make doctor 的一部分。

3. 生产目标全量清单（顶层：build.py help 列出的 21 个）

列宽有限，输入/输出 只写代表性路径；<...> 表示变量展开。always 列：A=Target.always=True（无条件跑），C=kind=command/test 且无 outputs（rebuild_reasons 必然返回原因，等效每次跑），G=group/aggregate（永不执行动作），空=mtime+指纹判定。

4. 未列入 help 但生产必需的目标（按区域）

4.1 工具链 / sysroot / 上游（tools/build_*.py）

4.2 运行库与归档

4.3 用户态应用（详见 §6 动态规则）

关键固定 target：app:pleditor(2029)、archive:stardustui(2109)、app:stardust{hello,layout,showcase}(2135 循环)、musl-userland(2219)、installer-policy:{desktop,settings}(2236 循环)、installer-tool:gptinit(2254)、app-manifests(2305)、资源组（2329-2353）。

musl-app:<app> ×62（2216，add_copy 到 build/musl/userland/<app>.elf）——把用户态 ELF 再复制一份给 musl checkpoint 镜像使用，是 musl-checkpoint-root:* 的输入。

app-manifests（2305）输出 = 每个 registry 应用一个 manifest.ini，路径含 guest 目录结构（registry_manifest_dir / (runtime_app_relative(app,'elf').parent / "manifest.ini")），命令 python3 tools/generate_app_manifests.py --out-dir ... --apps <62 个名字> --system-apps <24 个>，depends_on=("userland",)。

4.4 GRUB / staging（ESP）

4.5 APK 仓库与 RPR

4.6 镜像与安装器（除 §3 的 12/13/14 外）

4.7 测试目标（build.py test <item> / 独立 target）

另有未注册的孤儿/特殊构图：main() 在 test svga 时另建一张只含 test-svga 的空图（build.py:4858-4863），绕过全图构建。

5. 图构造期的"非 target"副作用（必须迁移但清单里没有节点）

6. 动态生成规则（按 configs/components.toml 与源码 glob）

组件计数（实测 2026-09-19）：73 组件（24 system-app / 35 program-app / 3 package-app / 7 tool / 4 library）。

7. buildsystem/cache（唯一真正内容寻址的地方）

tools/apk_distribution.py:88-120：_download_verified(urls, destination, expected_sha256)，若 destination 在 ROOT 下则

1. 查 buildsystem/cache/apk/downloads/<sha256>，命中即 shutil.copyfile 返回（键 = SHA-256，不查 URL）；
2. 未命中则逐个 curl --fail --location --retry 3 到 <name>.download，摘要匹配才 replace，再 copyfile→<sha256>.tmp→rename 入缓存。

buildsystem/cache/apk/distributions/<64位十六进制>/root/... 是解包后的 APK 根（当前 36 份，每份含完整 vim 等，这就是任务描述把 buildsystem/ 数成 7150 行 Python 的原因）。buildsystem/deps/apk-tools/.lock 用 flock(LOCK_EX) 串行 bootstrap。

spec §3 说"不实现内容寻址构建缓存"，但 §9 要求 cache/downloads/ 保持"校验过的下载文件 + 与 profile 无关"——旧系统这一条已经符合，迁移时应保留同语义（curl + sha256 文件名）而非重新发明。

8. 下游消费者（外部契约）

9. 机制 → Make 映射判定

9.1 Make 原生可替代（删除旧实现，不重做）

9.2 必须显式重做（Make 无原生等价物）

9.3 属于"不要重新实现"的非目标（spec §3 直接命中）

依赖图引擎、线程池调度器、内容寻址构建缓存、后台 daemon、任务数据库、远程执行平台、插件框架、随机 9 位任务 ID、进度条/主题拦截输出、curses UI —— 上述在旧系统分别对应 BuildGraph/_schedule/cache/apk(保留但降级为下载缓存)/run_client/TaskStore/—/Target.action 闭包/TaskStore.new_id/ProgressRenderer+LOG_THEMES/tui.py+ui.py。

10. 风险清单（按"卡住可行性"排序）

1. Meson/Ninja/Python 三处在生产链上，且不是"一个脚本"而是结构性依赖： (a) tools/build_auth_upstream.py:156-164 对 linux-pam 走 meson setup/compile/install（Meson 本体是 Python，生成 build.ninja 由 Ninja 执行）；auth-upstream 又是 storage-upstream、esp:auth、sdk、apk-root、全部镜像的上游。 (b) tools/leonos_musl_cc.py 原样作为 bin/leonos-musl-cc 打进 SDK（package_devtools.py:407），并被 musl-probe:*(1529) 与 musl-ltp(1561) 当作链接器直接 exec（argv[0] = python3）。 (c) musl_link.py / storage_tools.py / package_fastfetch.py 被 import 进构图。 → spec §2 A16 的 execve 追踪在 installer 一条链上就会同时命中 Meson、Ninja、Python。必须先给出 linux-pam 的 autotools/Makefile 替代或等价适配，否则整个计划的验收前提不成立。
2. 构建污染受跟踪源码树：include/generated/build_info.h（build-info，always）、Kconfig.components（config-sync，always）、buildsystem/state/build_number.txt（已用 ! 反向豁免）、LeonOS4-Developer-SDK.zip 落在源码根、tools/package_devtools.py 会 stage 进 devtools/。本任务开始时工作区曾出现 buildsystem/state/build_number.txt 与 include/generated/build_info.h 被改动（spec §2 已预警，实为并发构建进程所为）→ A17（"构建前后受跟踪文件无新增变化"）与 spec §7"版本头移至 O/generated、移除源码目录自动写入"是硬冲突需要一并解决。
3. prune 是镜像正确性的唯一防线，Make 没有等价物：staging-prune（100 行 action + 硬编码 obsolete 清单 + 组件差集）与 esp:layout-links（读上次 layout-links.json 删除消失的符号链接，并与 BusyBox applet 链接、已打包命令优先级三方仲裁）。删掉一个组件 / 删一个源文件 / 改名一个应用，靠"时间戳重建"完全不会让 build/esp 变干净，最终 ext2/ISO 会残留旧 ELF。A06 只能通过新的成员清单 + 从空 staging 原子发布达成，这是 P3 最大工作量集中点。
4. 增量正确性建立在"mtime + 只哈希声明的指纹"上，且没有任何构建级互斥锁：

• _fingerprint 不含文件内容、不含被调用 Python 脚本的内容（脚本内容只作为独立 input 文件被 mtime 跟踪）、不含 find_compiler_rt_archive 探测结果、不含 4 个环境变量。
• archive:zlib / archive:libpng / archive:stardustui 用 ar rcs（追加）而非 rebuild_archive.py，当前就会残留已删成员 —— 基线抓取时必须记录这一已知缺陷，避免把它当"正确行为"照搬到 Make。
• 两个 build.py 进程可无保护并发：targets.json 单文件整表重写 → 后者覆盖前者的状态；build/obj、build/esp 共享。spec §6.3 的锁是净新增能力，不是"保留旧行为"。

1. 多输出/条件输出/未声明输出遍地（image-vmdk 4、musl-ltp 22、app-icons 62、app-manifests 67、esp:layout-links 200+、musl 实际 12+ 而真实 sysroot 上千；release/esp:terminal-packages/image-iso 的输出集合随配置或环境变量而变）。用单个 .stamp 表达会在 A07 立刻失败；&: grouped targets 与"按成员清单校验"必须成对设计。
2. 聚合面的语义与 spec §4 不同：旧 all = config-sync+build-info+loader+kernel+kerneldebug-module+drivers+middlelayer+userland+sdk+esp，不含任何镜像；installer = all+installer-root+installer-image；esp/image-vmdk/apk-root 都不在 help 列表里。新 all 要求含 rootfs/apk-repo/image-vmdk/iso/installer → 这不是重命名而是改变聚合契约，CI 与 .vscode/tasks.json 三条链都要同步。
3. 宿主工具事实表不完整：task_tools() 未登记 curl/git/openssl/patch/fakeroot/unshare/e2fsck/readelf/llvm-ranlib/grub-mkimage/llvm-objcopy/vim，而 musl（git）、auth-upstream（curl+patch+make+meson）、apk-root（curl+openssl+unshare/fakeroot+e2fsck）、image-*（grub-mkimage、grub-mkrescue、mcopy、dd、qemu-img）都依赖它们。make doctor 必须从实测调用重建，不能照抄 §2.8 表。
4. 测试面的真实断言在 Python 里：12+1 个 QMP 测试把"来宾串口正则 + 截图存在性 + 退出码"的判定写在 build.py:3840-4042 与 tools/qmp_terminal_smoke.py，用 context.runner.task_id 生成临时 socket/overlay 名。spec §11 要求测试识别来宾成功标记并核验退出状态 —— 迁移到 C/Shell 意味着重写这套断言，且旧断言文本（例如 spawn path=、[abittest] ALL PASS、scheduler task exited pid=... code=0）是内核日志格式的隐式契约。

11. 建议的验收证据来源（P0-b 对应用）