jetson-build-source

构建 BSP 源码

用途

根据 <source.root_path>/bsp_sources/ 下的更改，重建内核侧产物（DTB、OOT 模块、树内模块、内核 Image），并写入一份清单，供 /jetson-promote-image 读取，以便将这些产物暂存到 BSP 镜像中。本技能绝不会写入 <bsp_image.root_path> 本身。

前置条件

• 已激活的目标平台配置文件，其中 bsp_image: 和 source.toolchain: 已解析（先运行 /jetson-init-image 和 /jetson-init-source）。
• <source.root_path>/bsp_sources/ 中已填充 /jetson-init-source 生成的内核侧检出目录结构。
• 存在 <bsp_image.root_path>/Linux_for_Tegra/source/kernel_src_build_env.sh（从 public_sources.tbz2 解压而来）。
• 主机软件包：flex、bison、libssl-dev（必需）；git、build-essential、bc、zstd（仅警告）。
• 磁盘上可解析 ${source.toolchain}gcc 对应的交叉工具链。

概述

本技能是工作流中的构建阶段——关于其在设置 → 自定义 → 构建 → 部署流程中的位置及触发条件，请参阅 ../../context/bsp-customization-workflow.md。本技能接收源代码侧的自定义提交，重建相应产物，并在清单中记录哪些产物已重建。输出保留在 <source.root_path>/bsp_sources/ 内的源码树中；jetson-promote-image 会在部署阶段读取清单，将每个已重建的产物复制到 <bsp_image.root_path>/Linux_for_Tegra/ 下对应的路径。

仅涉及覆盖层的编辑（nvpmodel.conf、nvfancontrol.conf、BPMP DTB）会跳过构建阶段——customize-* 阶段会将它们直接暂存到覆盖层跟踪器；BPMP DTB 使用 ../../references/bsp-customization-bpmp-dtb.md 中的 dtc 反编译 → 编辑 → 重新编译流程。

自定义覆盖层槽位归属。 来自所有 customize-* 技能的内核 DT 自定义内容，都会汇总到每个活动目标对应的单个组合文件 tegra<soc>-<carrier-id-sku>+<module-id>-xxxx-custom.dts 中——文件名、位置及追加协议请参阅 ../../references/bsp-customization-kernel-dtb.md。本技能是组合文件按目录注册到 Makefile（dtbo-y += <name>.dtbo）以及在载板刷写配置文件中添加 OVERLAY_DTB_FILE+= 行的唯一所有者（即“注册组合自定义覆盖层”步骤）。

四种构建模式与脏仓库配置相匹配：

模式	构建内容	自动选择条件
dt	仅 NVIDIA DTB	仅 hardware/nvidia/* 或 kernel-devicetree 有更改
oot	OOT 模块（六个仓库）	仅 OOT 仓库有更改
kernel	内核 Image + 完整的树内 .ko 集合 + 内核侧 DTB	仅 kernel/$KERNEL_SRC_DIR 有更改
full	上述全部内容 + 可选的安装整合	更改涉及多个类别

模式选择：auto（默认——不带参数调用 /jetson-build-source）会遍历脏仓库集合；传入技能参数即可强制指定模式。

设计原则：委托上游处理。 所有构建基本操作都已存在于 <bsp_image.root_path>/Linux_for_Tegra/source/ 中——环境文件、顶层 Makefile（nvidia-dtbs / modules / modules_install）、内核 Makefile（kernel / install）。本技能会使用这些基本操作来构建 <source.root_path>/bsp_sources/ 中的源码——绝不在 shell 中重复实现这些逻辑。

何时调用

• 每当 Customize 在某个内核侧源码仓库中提交更改时，customize-* 调用结束后会自动链式调用本技能。
• 通过 /jetson-build-source [<mode>] 手动重新运行，适用于以下情况：
  • 自动链式构建被中断；
  • 其他用户通过 git pull 提交了源码更改；
  • 用户希望在没有新编辑的情况下强制重新构建；
  • 用户希望指定模式（例如，为手动 scp 部署到 DUT 执行安装整合）。

操作说明

解析活动目标、路径和上游环境变量

按照 ../../context/target-platform-contract.md 解析活动配置文件。在以下情况下拒绝并转到指定位置：

条件	转到
没有活动配置文件，或 active: NA	/jetson-set-target 或 /jetson-init-target
配置文件缺少 bsp_image:	/jetson-init-image
配置文件缺少 source.toolchain:	/jetson-init-source
<source.root_path>/bsp_sources/ 不存在或为空	/jetson-init-source
<bsp_image.root_path>/Linux_for_Tegra/source/kernel_src_build_env.sh 不存在	/jetson-init-image（BSP 未正确解压）

绑定：

WORKSPACE=<parent of target-platform/>
BSP_SRC=<bsp_image.root_path>/Linux_for_Tegra/source   # NVIDIA's build primitives
KS=<source.root_path>/bsp_sources                      # our kernel-side checkout
KOUT=<source.root_path>/.build/kernel-out              # DT-mode out-of-tree build dir
STAGE=<source.root_path>/.build/install-stage          # install consolidation (full mode / opt-in)
STATE=<source.root_path>/.build-state.yaml             # per-repo watermark
MANIFEST=<source.root_path>/.build-manifest.yaml       # rebuilt-artifact list for jetson-promote-image

加载 NVIDIA 构建环境以继承规范名称——切勿将 kernel-noble、OOT 模块列表或 KERNEL_DEF_CONFIG 硬编码：

source "$BSP_SRC/kernel_src_build_env.sh"
# Now in scope: KERNEL_SRC_DIR (e.g. kernel-noble), KERNEL_DEF_CONFIG,
# OOT_SOURCE_LIST, kernel_name (e.g. noble), KERNEL_MODULAR_BUILD

如果 $KS/kernel/$KERNEL_SRC_DIR/ 不存在，或 $OOT_SOURCE_LIST 中的任何名称在 $KS/ 下不存在，则拒绝并转到 /jetson-init-source。

解析工具链（只读）

从活动配置文件中读取 source.toolchain（由 jetson-init-source 编写）。验证：

export ARCH=arm64
export CROSS_COMPILE=<source.toolchain>   # trailing dash mandatory
[ -f "${CROSS_COMPILE}gcc" ] || refuse \
  "source.toolchain points at ${CROSS_COMPILE}gcc which does not exist. Re-run /jetson-init-source."

CROSS_COMPILE 末尾必须有连字符——kbuild 会将其视为前缀（${CROSS_COMPILE}gcc）；缺少连字符会导致 command not found。[ -f ] 检查会在运行任何 make 之前发现此问题。

此技能绝不提示用户指定工具链，也不尝试解析缺失的工具链——这是 jetson-init-source 独有的职责。缺少字段属于设置缺漏；请转到该处。

验证一次构建主机的先决条件：

for p in flex bison libssl-dev; do
  dpkg -s "$p" >/dev/null 2>&1 || refuse "host package missing: $p"
done
for p in git build-essential bc zstd; do
  dpkg -s "$p" >/dev/null 2>&1 || warn "host package missing: $p"
done

检测源代码仓库是否有未提交更改

水位线文件 $STATE 记录每个内核侧仓库上次成功构建的提交。仓库列表在运行时根据 OOT_SOURCE_LIST + kernel/$KERNEL_SRC_DIR 推导。对于每个仓库： HEAD ≠ 水位线 → 存在未提交更改；未提交的编辑（git diff --quiet 返回非零）→ 同样视为存在未提交更改。

Branch-A 说明：如果 bsp_sources/ 是一个只有单个 .git 的单体仓库，每个规范子路径都会共享同一个 HEAD——水位线架构仍按子路径分别记录，未提交更改集合仍然有效（任何位置的更改都会导致每个子路径的 HEAD 变化）。

如果 STATE 不存在（首次构建），则将所有仓库视为没有未提交更改，除非自动链上下文表明“刚刚提交了 Customize”。如果 DIRTY 为空且未传入模式参数，则报告“没有需要构建的内容”并返回。

选择构建模式

将未提交更改集合映射到一种模式（自动），或遵循传入的模式参数：

未提交更改的仓库（自动）	模式
仅 hardware/nvidia/* 或 kernel-devicetree	dt
仅 $OOT_SOURCE_LIST 的 OOT 子集	oot
仅 kernel/$KERNEL_SRC_DIR	kernel
涉及以上类别的任意组合	full

模式可以组合：full 按 kernel → oot → dt 的顺序运行（kernel 会生成 OOT 所需的头文件；nvidia-dtbs 使用相同的生成头文件）。手动传入模式参数时会跳过自动检测。

执行构建

通用设置和各模式构建代码片段

通用设置（验证编排器 Makefile、cd $KS）以及各模式（dt、oot、kernel、full）的精确 make 调用和可选的安装合并步骤，位于 references/build-modes.md。根据“解析活动目标、路径和上游环境变量”步骤中的绑定，运行相关模式的代码片段。

注册复合自定义覆盖层（仅限 dt + full）

除非所选模式为 dt 或 full，否则跳过。复合 覆盖层槽位的说明见 ../../references/bsp-customization-kernel-dtb.md； 此子步骤负责其构建 / Makefile / flash-conf 相关部分。

使用当前配置文件的芯片系列、载板 ID/SKU 和模块 ID， 解析当前目标的复合路径（$COMPOSITE_BASE、 $COMPOSITE_DTS、$COMPOSITE_MK）——完整片段见 references/composite-registration.md。

门控（对称）。 $COMPOSITE_DTS 决定两个方向： 存在 → 应用以下两个幂等补丁；不存在 → 运行 清理流程， 移除之前运行遗留的任何 dtbo-y += / OVERLAY_DTB_FILE+= 行。 两种路径都能确保 OVERLAY_DTB_FILE+= 不会引用尚未构建的 .dtbo—— 这是禁止直接编辑树内 DT 文件规则的 构建时强制措施。

1. 每目录 Makefile —— 在最后一个字面命名的 dtbo-y += 条目后追加 dtbo-y += <name>.dtbo。插入到 $(old-dtbo) 合并回写行之后，会跳过 $(addprefix makefile-path/,…) 前缀处理，导致构建静默丢弃复合项。提交到 bsp_sources/ 单体仓库。完整片段和理由见： references/composite-registration.md。
2. 载板 flash 配置 —— 追加 OVERLAY_DTB_FILE+=",<name>.dtbo"， 并在覆盖层跟踪器上首次触及时导入原始版本。在全新工作区中，跟踪器为空的 git-init； 从 bsp_image 导入配置，并在自定义提交之前以 pristine: 提交 （工作流约定）。完整片段见： references/composite-registration.md。

自定义追加期间，复合项的父级子仓库切换 HEAD，正是“检测有改动的源代码仓库”步骤 脏状态检测所依赖的内容——此处无需额外记录。

调用 nvidia-dtbs 之前进行自检：

grep -qxF "dtbo-y += ${COMPOSITE_BASE}.dtbo" "$COMPOSITE_MK" \
  || refuse "Composite Makefile registration missing after patch."
grep -qxF "$line" "$FLASH_CONF" \
  || refuse "Composite flash-conf registration missing after patch."

编写构建清单

遍历 DIRTY 集合，并为每个推导出的构件生成一条清单项， 遵循追溯至脏仓库策略——只包含可追溯到有改动源代码仓库的构件。 将基线差异噪声纳入清单会把它错误归因到自定义审计记录中（禁止）。

完整的源代码 → kbuild → 目标映射、YAML 架构和筛选规则见 references/manifest-schema.md。

原子写入：先写入 ${MANIFEST}.tmp，然后执行 mv -f。

更新水位标记 + 摘要

成功后，使用新的每仓库 HEAD、工具链、 bsp_image.version 和上次运行模式重写 $STATE（架构见 references/manifest-schema.md）。

报告：

• 工具链（来自 source.toolchain）。
• 构建模式：<dt|oot|kernel|full>（由技能参数自动选择或强制指定）。
• 有改动的仓库及其新 HEAD。
• 已构建构件：按类型统计数量（.dtb、树内 .ko、OOT .ko、Image）。
• 清单路径 + 条目数。
• 合并后的安装阶段路径（如果运行了“安装合并”步骤）。
• 下一步：/jetson-promote-image。

如果此次运行由 Customize 技能触发，请提示用户重新提交其原始请求。

限制

最高优先级——会阻止构建或悄然生成错误构件的故障模式。有关不变量、部署模式和性能提示，请参阅 references/long-tail-gotchas.md。

• 工具链解析是 jetson-init-source 的职责。 此技能只读取 source.toolchain 并导出 CROSS_COMPILE。 字段缺失 → 拒绝执行并转交，绝不在技能内部解析。
• R36.x Branch-A $KS/Makefile 冲突。 R36.x 的 public_sources.tbz2 可能会将 dGPU/OpenRM 专有 Makefile 留在 $KS/Makefile，而不是 Tegra 编排文件； 其 modules 目标会递归进入 kernel-open/ + src/nvidia/， 拉取主机的 /lib/modules 头文件，并因 '-mlittle-endian' unrecognized 破坏 arm64 交叉构建。R38+ 的提取不受影响。/jetson-init-source 的第 3a 步是主要防护措施（提取时）；此处的“通用设置”检查是安全网。 不要放宽正则表达式。
• Kernel-DT 更改：仅限复合 overlay，所有权分开。 customize-* 技能禁止直接编辑 bsp_sources/ 下树内的 .dts / .dtsi 文件——每项 Kernel-DT 更改都必须作为片段放入复合 overlay 插槽 （规则 + 原因）。 复合 .dts 内容由各 customize-* 技能负责；构建 / Makefile / flash-conf 注册由此技能负责（仅在复合 .dts 存在时执行门控——这样 OVERLAY_DTB_FILE+= 就不会引用尚未构建的 .dtbo）。
• “注册复合自定义 overlay”步骤的 Makefile 插入位置很重要。 插入到最后一个名称为字面值的 dtbo-y += 条目之后；若插入到 $(old-dtbo) 之后，就会跳过 $(addprefix makefile-path/,…) 前缀处理，构建会悄然丢弃你的 .dtbo。正则表达式 ^dtbo-y *+= *[a-zA-Z0-9] 能正确筛选；不要放宽它。
• “注册复合自定义 overlay”步骤首次修改时需要原始导入。 在新建工作区中，overlay 跟踪器是空的 git-init 仓库——承载用的 flash conf 会从 bsp_image 导入，并在自定义提交之前提交为 pristine:。这两次提交都要经过工作流验收门。
• 避免在此 SKILL.md 的 shell 代码片段中裸用 $0。 使用参数调用时，运行框架会在将渲染后的提示词交给模型之前，用调用方的 $0 展开技能正文中的 $0。请使用基于 sed 的行拼接或 awk -v ROW="$0"。请参阅 references/composite-registration.md。
• 不要暂存 overlay。 构建输出保留在构建生成它们的位置；清单是提供给 jetson-promote-image 的契约。这是对原始 overlay→promote 间接流程的刻意偏离——可避免完整构建输出集进入 overlay 跟踪器的 git 历史。
• DT 模式下的 KERNEL_HEADERS 与 KERNEL_OUTPUT。 两者语义不同（srctree 与 objtree）；不要合并。“仅 DT”步骤中的代码片段写法正确。
• OOT 模式前提：此前已构建的内核头文件。 对从未构建过的树手动调用 oot 时，会拒绝执行并提示“run kernel (or full) first”，而不是产生令人困惑的构建错误。

示例

从有未提交更改的源代码树自动检测模式（典型调用）：

/jetson-build-source

强制使用单一模式（跳过自动检测）：

/jetson-build-source dt       # rebuild NVIDIA DTBs only
/jetson-build-source oot      # rebuild OOT modules only
/jetson-build-source kernel   # rebuild kernel Image + in-tree modules
/jetson-build-source full     # rebuild everything + install consolidation

customize-* 技能提交到内核侧仓库之后的典型调用链（customize-* 技能会自动调用此技能）：

/jetson-customize-pcie ...   # commits to hardware/nvidia/.../nv-public
   ↓
/jetson-build-source         # auto-picks `dt` from the dirty set
   ↓
/jetson-promote-image        # reads .build-manifest.yaml, stages into bsp_image
   ↓
/jetson-flash-image          # flashes

故障排查

错误	原因	解决方案
source.toolchain points at <...>gcc which does not exist	工具链字段已过时（路径已移动，或缺少安装）	重新运行 /jetson-init-source 以重新解析。此技能不会自行解析工具链。
No rule to make target '$KOUT/scripts/Makefile.compiler'	KERNEL_HEADERS 被设为 $KOUT，而不是 $KS/kernel/$KERNEL_SRC_DIR	原样使用 references/build-modes.md 中的 DT 模式代码片段——srctree 与 objtree 必须保持区分。
执行 make modules 时出现 '-mlittle-endian' unrecognized	R36.x Branch-A $KS/Makefile 冲突——dGPU/OpenRM Makefile 替代了 Tegra 编排 Makefile	通常，Common-setup 安全网会修复此问题；若未修复，运行 git checkout HEAD -- Makefile，然后重新运行 /jetson-init-source 的第 3a 步。
手动调用 oot 时出现 run kernel (or full) first	从未准备过内核源代码树	先运行一次 /jetson-build-source kernel（或 full），然后再运行 oot。
出现 nothing to build，且存在未提交的编辑	编辑在子仓库中尚未提交，但 .build-state.yaml 水位标记已与 HEAD 匹配	提交这些编辑，或使用显式模式参数重新运行（如 /jetson-build-source dt）。
输出集里静默缺少复合 .dtbo	每个目录的 Makefile 插入位置落在 $(old-dtbo) 合并回填行之后	请参阅 references/composite-registration.md——在最后一个 字面命名的 dtbo-y += 条目之后插入。
Promote 步骤复制了过时的基线构件	手动 cp 到 $KS 后，Trace-to-dirty 过滤器被跳过	仅通过 customize-* 技能或 git 进行编辑；脏文件检测器依据 git HEAD，而非文件修改时间。
host package missing: <pkg>	flex/bison/libssl-dev 安装失败；其他软件包只会发出警告。	按照 references/upstream-recipe.md 运行 sudo apt install <pkg>。

另请参阅

• references/build-modes.md — 各模式的 make 代码片段和安装合并。
• references/manifest-schema.md — .build-manifest.yaml 和 .build-state.yaml 架构。
• references/composite-registration.md —“注册复合自定义覆盖层”步骤的完整代码片段和原理说明。
• references/long-tail-gotchas.md — 不变量、部署模式和性能提示。
• references/upstream-recipe.md — NVIDIA 原始配方、差异和规范状态。
• ../../context/bsp-customization-workflow.md — 工作区编辑协议。
• ../../references/bsp-customization-kernel-dtb.md — 复合自定义覆盖层约定。
• ../../references/bsp-customization-bpmp-dtb.md — BPMP-DTB 编辑约定（由其他技能处理）。
• ../jetson-init-source/SKILL.md — 设置；用于编写 source.toolchain。
• ../jetson-promote-image/SKILL.md — 部署发布工具；读取此技能的清单。