⚡

Jetson源码构建Skill jetson-build-source

该技能用于根据bsp_sources下的源码变化，重建Jetson平台的BSP内核侧产物（设备树DTB、OOT模块、内核镜像Image等），并生成构建清单供后续镜像部署（/jetson-promote-image）使用。适用于需要重新编译内核、设备树或OOT模块、强制重建、或自定义提交后的自动构建等场景。关键词：Jetson, BSP, 源码构建, 设备树DTB, OOT模块, 内核编译, 镜像部署, 构建清单, 交叉编译。

源码构建与打包 0 次安装 0 次浏览 更新于 9/6/2026
名称 jetson-build-source
描述 >- 当你需要从bsp_sources/下的更改重建BSP overlay — DT、OOT模块或内核时使用。触发场景：构建bsp、重建dtb、重建内核。
版本 0.0.1
开源协议 “Apache-2.0” argument-hint: "dt
作者 “Jetson团队” team: pts tags: - bsp - build domain: meta

构建 BSP 源码

目的

重建内核侧产物（DTB、OOT模块、内核树内模块、内核Image），这些产物由 <source.root_path>/bsp_sources/ 下的变更所隐含，并写入一个manifest文件，/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，了解它在 Setup → Customize → Build → Deploy 流水线中的位置以及触发条件。该技能接受源码侧的自定义提交，重建所隐含的产物，并在清单中记录哪些内容被重建。输出保留在树内的 <source.root_path>/bsp_sources/ 下；jetson-promote-image 在 Deploy 阶段读取清单，将每个重建的产物复制到 <bsp_image.root_path>/Linux_for_Tegra/ 下对应的路径。

仅修改 overlay 的内容（nvpmodel.conf、nvfancontrol.conf、BPMP DTB）会跳过 Build — customize-* 阶段会直接将它们暂存到 overlay 跟踪器中；BPMP DTB 使用 ../../references/bsp-customization-bpmp-dtb.md 中的 dtc 反编译→编辑→重新编译循环。

自定义 overlay 插槽所有权。 来自每个 customize-* 技能的内核-DT自定义收集到一个复合文件中：每个活动目标对应一个 tegra<soc>-<carrier-id-sku>+<module-id>-xxxx-custom.dts — 参见 ../../references/bsp-customization-kernel-dtb.md 了解文件名/位置/追加协议。本技能是复合文件在每目录 Makefile 中的注册（dtbo-y += <name>.dtbo）以及载板 flash 配置中的 OVERLAY_DTB_FILE+= 行的唯一所有者（即“注册复合自定义 overlay”步骤）。

四种构建模式与脏仓库状态匹配：

模式 构建内容 自动选择时机
dt 仅 NVIDIA DTB 仅有 hardware/nvidia/* 或 kernel-devicetree 脏
oot OOT 模块（六个仓库） 仅有 OOT 仓库脏
kernel 内核 Image + 完整 in-tree .ko 集合 + 内核侧 dtb 仅有 kernel/$KERNEL_SRC_DIR 脏
full 以上所有 + 可选安装合并 脏集合混合

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

设计原则：委托给上游。 每个构建原语已经存在于 <bsp_image.root_path>/Linux_for_Tegra/source/ 中 — env 文件、顶层 Makefile（nvidia-dtbs / modules / modules_install）、内核 Makefile（kernel / install）。该技能针对 <source.root_path>/bsp_sources/ 驱动这些原语 — 绝不在 shell 中复制它们的逻辑。

何时调用

  • 自动链接在 Customize 的 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 构建原语
KS=<source.root_path>/bsp_sources                      # 我们的内核侧检出
KOUT=<source.root_path>/.build/kernel-out              # DT模式的树外构建目录
STAGE=<source.root_path>/.build/install-stage          # 安装合并（full模式/可选）
STATE=<source.root_path>/.build-state.yaml             # 每仓库水位
MANIFEST=<source.root_path>/.build-manifest.yaml       # 重建产物列表，供jetson-promote-image使用

引用 NVIDIA 构建环境以继承规范名称 — 绝不硬编码 kernel-noble、OOT 模块列表或 KERNEL_DEF_CONFIG：

source "$BSP_SRC/kernel_src_build_env.sh"
# 现在作用域内：KERNEL_SRC_DIR（如 kernel-noble）、KERNEL_DEF_CONFIG、
# OOT_SOURCE_LIST、kernel_name（如 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>   # 必须带尾部横杠
[ -f "${CROSS_COMPILE}gcc" ] || refuse \
  "source.toolchain 指向 ${CROSS_COMPILE}gcc，但该文件不存在。重新运行 /jetson-init-source。"

CROSS_COMPILE 的尾部横杠是强制的 — kbuild 将其视为前缀（${CROSS_COMPILE}gcc）；缺少横杠会报 command not found。[ -f ] 检查在任何 make 运行前捕获它。

本技能永不提示工具链或尝试解析缺失的工具链 — 这是 jetson-init-source 的专属职责。字段缺失是 Setup 缺口；转到那里。

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

for p in flex bison libssl-dev; do
  dpkg -s "$p" >/dev/null 2>&1 || refuse "缺少主机软件包：$p"
done
for p in git build-essential bc zstd; do
  dpkg -s "$p" >/dev/null 2>&1 || warn "缺少主机软件包：$p"
done

检测脏源码仓库

水位文件 $STATE 记录每个内核侧仓库最近成功构建的提交。仓库列表在运行时从 OOT_SOURCE_LIST + kernel/$KERNEL_SRC_DIR 派生。对于每个仓库：HEAD ≠ 水位 → 脏；未提交的编辑（git diff --quiet 非零）→ 也脏。

Branch-A 注释：当 bsp_sources/ 是一个带单一 .git 的单一仓库时，每个规范的子路径共享同一 HEAD — 水位 schema 仍按子路径键控，脏集合仍然有效（任何地方的任何更改都会翻转每个子路径的 HEAD）。

如果 STATE 不存在（首次构建），将所有仓库视为干净，除非自动链上下文说“Customize 刚提交”。如果 DIRTY 为空且没有传入模式参数：报告“没有可构建的内容”并返回。

选择构建模式

将脏集合映射到模式（自动），或遵循模式参数：

脏仓库（自动） 模式
仅 hardware/nvidia/* 或 kernel-devicetree dt
仅 $OOT_SOURCE_LIST 的 OOT 子集 oot
仅 kernel/$KERNEL_SRC_DIR kernel
任意跨越上述的混合 full

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

执行构建

通用设置 + 按模式构建片段

通用设置（验证编排 Makefile，cd $KS）以及每种模式（dt、oot、kernel、full）以及可选的安装合并传递的精确 make 调用位于 references/build-modes.md。针对“解析活动目标 + 路径 + 上游环境”步骤的绑定驱动相关模式的片段。

注册复合自定义 overlay（仅 dt 和 full）

除非选定的模式是 dt 或 full，否则跳过。复合 overlay 插槽在 ../../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 跟踪器上的 first-touch pristine 导入追加 OVERLAY_DTB_FILE+=",<name>.dtbo"。在新工作区，跟踪器是空的 git-init；先从 bsp_image 导入 conf 并在自定义提交之前提交为 pristine:（工作流契约）。完整片段：references/composite-registration.md。

复合文件所在子仓库在 customize-* 追加期间翻转 HEAD，是“检测脏源码仓库”步骤消费的 — 这里无需额外记账。

自检在调用 nvidia-dtbs 之前：

grep -qxF "dtbo-y += ${COMPOSITE_BASE}.dtbo" "$COMPOSITE_MK" \
  || refuse "补丁后缺失复合 Makefile 注册。"
grep -qxF "$line" "$FLASH_CONF" \
  || refuse "补丁后缺失复合 flash-conf 注册。"

写构建清单

遍历 DIRTY 集合，为每个隐含产物发出清单条目，遵循trace-to-dirty 政策 — 仅限可追溯到脏源码仓库的产物。提升基线偏差噪声会将其归于自定义的审计跟踪（禁止）。

完整的源码 → kbuild → 目标映射、YAML schema 和过滤规则见 references/manifest-schema.md。

原子写入：暂存到 ${MANIFEST}.tmp，然后 mv -f。

更新水位 + 摘要

成功后，用新的每仓库 HEAD、工具链、bsp_image.version 和上次运行模式重写 $STATE（schema 见 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 头文件，并使 arm64 交叉构建与 '-mlittle-endian' unrecognized 中断。R38+ 解压不受影响。/jetson-init-source 的步骤 3a 是主要防御（解压时）；这里的“通用设置”检查是安全网。不要放宽正则表达式。
  • 内核-DT 变化：仅复合 overlay，所有权分离。 对 bsp_sources/ 下树内 .dts / .dtsi 文件的直接编辑对 customize-* 技能是禁止的 — 每个内核-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”步骤的首次接触需要 pristine 导入。 在新工作区，overlay 跟踪器是空的 git-init — 载板 flash conf 从 bsp_image 导入并在自定义提交之前提交为 pristine:。两个提交都经过工作流验收门。
  • 避免在 SKILL.md 内的 shell 片段中使用裸 $0。 当带参数调用时，harness 会在将渲染后的提示交给模型前，根据调用者的 $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 会拒绝并报“先运行 kernel（或 full）”，而不是产生令人困惑的构建错误。

示例

从脏源码树自动检测模式（典型调用）：

/jetson-build-source

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

/jetson-build-source dt       # 仅重建 NVIDIA DTB
/jetson-build-source oot      # 仅重建 OOT 模块
/jetson-build-source kernel   # 重建内核 Image + 树内模块
/jetson-build-source full     # 重建一切 + 安装合并

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

/jetson-customize-pcie ...   # 提交到 hardware/nvidia/.../nv-public
   ↓
/jetson-build-source         # 从脏集合自动选择 `dt`
   ↓
/jetson-promote-image        # 读取 .build-manifest.yaml，暂存到 bsp_image
   ↓
/jetson-flash-image          # 烧写

故障排查

错误 原因 解决方案
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。
'-mlittle-endian' unrecognized 在 make modules 期间 R36.x Branch-A $KS/Makefile 冲突 — dGPU/OpenRM Makefile 替代 Tegra 编排器 “通用设置”安全网通常会修复；若没有，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 而非文件 mtime。
host package missing: <pkg> flex/bison/libssl-dev 拒绝；其他警告。 sudo apt install <pkg> 根据 references/upstream-recipe.md。

另见