Back to Details

jetson-build-source

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Build BSP Source

构建BSP源码

Purpose

用途

Rebuild the kernel-side artifacts (DTBs, OOT modules, in-tree modules, kernel 
Image
) implied by changes under 
<source.root_path>/bsp_sources/
, and write a manifest that 
/jetson-promote-image
reads to stage those outputs into the BSP image. The skill never writes into 
<bsp_image.root_path>
itself.
重新构建由
<source.root_path>/bsp_sources/
目录下的更改所涉及的内核端产物（DTBs、OOT模块、树内模块、内核
Image
），并生成一份清单供
/jetson-promote-image
读取，以便将这些输出产物部署到BSP镜像中。本技能绝不会直接写入
<bsp_image.root_path>
目录。

Prerequisites

前提条件

  • Active target-platform profile with 
    bsp_image:
    and 
    source.toolchain:
    resolved (run 
    /jetson-init-image
    and 
    /jetson-init-source
    first).
  • <source.root_path>/bsp_sources/
    populated with the kernel-side checkout layout 
    /jetson-init-source
    materializes.
  • <bsp_image.root_path>/Linux_for_Tegra/source/kernel_src_build_env.sh
    present (extracted from 
    public_sources.tbz2
    ).
  • Host packages: 
    flex
    , 
    bison
    , 
    libssl-dev
    (hard); 
    git
    , 
    build-essential
    , 
    bc
    , 
    zstd
    (warn-only).
  • Cross-toolchain at 
    ${source.toolchain}gcc
    resolvable on disk.
  • 已激活的目标平台配置文件，其中
    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
    的交叉工具链。

Overview

概述

This skill is the Build stage of the workflow — see 
../../context/bsp-customization-workflow.md
 for where it sits in the Setup → Customize → Build → Deploy pipeline and what triggers it. The skill takes source-side customization commits, rebuilds the implied artifacts, and records which were rebuilt in a manifest. Outputs stay in-tree under 
<source.root_path>/bsp_sources/
; 
jetson-promote-image
 reads the manifest at Deploy to copy each rebuilt artifact into the matching path under 
<bsp_image.root_path>/Linux_for_Tegra/
.
Overlay-only edits (
nvpmodel.conf
, 
nvfancontrol.conf
, BPMP DTB) skip Build — 
customize-*
stages them directly to the overlay tracker; BPMP DTB uses the 
dtc
decompile → edit → recompile loop in 
../../references/bsp-customization-bpmp-dtb.md
.
Custom-overlay slot ownership. Kernel-DT customizations from every customize-* skill collect into a single composite 
tegra<soc>-<carrier-id-sku>+<module-id>-xxxx-custom.dts
per active target — see 
../../references/bsp-customization-kernel-dtb.md
 for the filename / location / append protocol. This skill is the sole owner of the composite's per-dir Makefile registration (
dtbo-y += <name>.dtbo
) and the carrier flash conf's 
OVERLAY_DTB_FILE+=
line (the "Register composite custom overlay" step).
Four build modes matched to the dirty-repo profile:
ModeWhat's builtAuto-picks when
dtNVIDIA DTBs onlyonly 
hardware/nvidia/*
or 
kernel-devicetree
dirty
ootOOT modules (six repos)only OOT repos dirty
kernelKernel 
Image
+ full in-tree 
.ko
set + kernel-side dtbs		only 
kernel/$KERNEL_SRC_DIR
dirty
fullEverything above + optional install consolidationmixed dirty set
Mode selection: auto (default — invoke 
/jetson-build-source
with no argument) walks the dirty-repo set; force a specific mode by passing it as the skill argument.
Design principle: delegate to upstream. Every build primitive already exists in 
<bsp_image.root_path>/Linux_for_Tegra/source/
— the env file, top-level Makefile (
nvidia-dtbs
/ 
modules
/ 
modules_install
), kernel Makefile (
kernel
/ 
install
). The skill drives those primitives against 
<source.root_path>/bsp_sources/
— never duplicates their logic in shell.
本技能是工作流中的构建阶段——请参阅
../../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 DTBs仅
hardware/nvidia/*
或
kernel-devicetree
目录有改动
ootOOT模块（六个仓库）仅OOT仓库有改动
kernel内核
Image
+ 完整树内
.ko
集合 + 内核端dtbs		仅
kernel/$KERNEL_SRC_DIR
目录有改动
full以上所有内容 + 可选的安装整合存在跨上述类别的混合改动
模式选择：自动（默认——不带参数调用
/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中复制它们的逻辑。

When to invoke

调用时机

  • Auto-chained at the end of a Customize 
    customize-*
    invocation whenever Customize committed to a kernel-side source repo.
  • Manual re-run via 
    /jetson-build-source [<mode>]
    when:
    • the auto-chained build was interrupted,
    • source commits arrived via 
      git pull
      from other users,
    • the user wants to force a rebuild without a fresh edit,
    • the user wants a specific mode (e.g. install consolidation for a manual scp deploy to a DUT).
  • 自动链式调用：当
    customize-*
    定制技能提交到内核端源码仓库时，会在其末尾自动调用本技能。
  • 手动重新运行：通过
    /jetson-build-source [<mode>]
    手动调用，适用于以下场景：
    • 自动链式构建被中断，
    • 其他用户通过
      git pull
      提交了源码改动，
    • 用户希望无需新编辑即可强制重新构建，
    • 用户需要特定模式（例如，为手动scp部署到DUT进行安装整合）。

Instructions

操作步骤

Resolve active target + paths + upstream env

解析激活目标 + 路径 + 上游环境

Resolve the active profile per 
../../context/target-platform-contract.md
. Refuse and route in these cases:
ConditionRoute to
No active profile, or 
active: NA
/jetson-set-target
or 
/jetson-init-target
Profile lacks 
bsp_image:
/jetson-init-image
Profile lacks 
source.toolchain:
/jetson-init-source
<source.root_path>/bsp_sources/
missing or empty
/jetson-init-source
<bsp_image.root_path>/Linux_for_Tegra/source/kernel_src_build_env.sh
missing
/jetson-init-image
(BSP not properly extracted)
Bind:
bash
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
Source the NVIDIA build env to inherit canonical names — never hardcode 
kernel-noble
, the OOT module list, or 
KERNEL_DEF_CONFIG
:
bash
source "$BSP_SRC/kernel_src_build_env.sh"
根据
../../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未正确提取）
绑定变量：
bash
WORKSPACE=<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
：
bash
source "$BSP_SRC/kernel_src_build_env.sh"

Now in scope: KERNEL_SRC_DIR (e.g. kernel-noble), KERNEL_DEF_CONFIG,

现在可用的变量：KERNEL_SRC_DIR（例如kernel-noble）、KERNEL_DEF_CONFIG、

OOT_SOURCE_LIST, kernel_name (e.g. noble), KERNEL_MODULAR_BUILD

OOT_SOURCE_LIST、kernel_name（例如noble）、KERNEL_MODULAR_BUILD


Refuse if `$KS/kernel/$KERNEL_SRC_DIR/` is missing or if any name
in `$OOT_SOURCE_LIST` is missing under `$KS/`. Route to
`/jetson-init-source`.

如果`$KS/kernel/$KERNEL_SRC_DIR/`目录缺失，或`$OOT_SOURCE_LIST`中的任何名称在`$KS/`下缺失，则拒绝操作并引导至`/jetson-init-source`。

Resolve toolchain (read-only)

解析工具链（只读）

Read 
source.toolchain
from the active profile (authored by 
jetson-init-source
). Validate:
bash
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."
A trailing dash on 
CROSS_COMPILE
is mandatory — kbuild treats it as a prefix (
${CROSS_COMPILE}gcc
); a missing dash breaks with 
command not found
. The 
[ -f ]
check catches it before any 
make
runs.
This skill never prompts for the toolchain or attempts to resolve a missing one — that's 
jetson-init-source
's exclusive responsibility. A missing field is a Setup gap; route there.
Verify build-host prerequisites once:
bash
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
从激活配置文件中读取
source.toolchain
（由
jetson-init-source
生成）。验证：
bash
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
的专属职责。缺失字段属于设置环节的漏洞；引导至对应操作。
一次性验证构建主机的前提条件：
bash
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

Detect dirty source repos

检测脏源码仓库

The watermark file 
$STATE
records the last successfully built commit per kernel-side repo. The repo list is derived at runtime from 
OOT_SOURCE_LIST
+ 
kernel/$KERNEL_SRC_DIR
. For each repo: HEAD ≠ watermark → dirty; uncommitted edits (
git diff --quiet
non-zero) → also dirty.
Branch-A note: when 
bsp_sources/
is one mono-repo with a single 
.git
, every canonical sub-path shares the same HEAD — the watermark schema still keys per-sub-path and the dirty set still works (any change anywhere flips every sub-path's HEAD).
If 
STATE
is absent (first build), treat all repos as clean unless the auto-chain context says "Customize just committed". If 
DIRTY
is empty and no mode argument was passed: report "nothing to build" and return.
水印文件
$STATE
记录了每个内核端仓库最后一次成功构建的提交。仓库列表在运行时由
OOT_SOURCE_LIST
+ 
kernel/$KERNEL_SRC_DIR
生成。对于每个仓库：HEAD≠水印→脏仓库；存在未提交编辑（
git diff --quiet
返回非零值）→同样视为脏仓库。
Branch-A说明：当
bsp_sources/
是一个包含单个
.git
的单体仓库时，每个规范子路径共享相同的HEAD——水印模式仍会按子路径建立索引，脏集合仍可正常工作（任何位置的更改都会改变所有子路径的HEAD）。
如果
STATE
文件缺失（首次构建），则将所有仓库视为干净，除非自动链式上下文显示“定制操作刚刚提交”。如果
DIRTY
集合为空且未传递模式参数：报告“无内容需构建”并返回。

Pick build mode

选择构建模式

Map the dirty set to a mode (auto), or honor the mode argument:
Dirty repos (auto)Mode
Only 
hardware/nvidia/*
or 
kernel-devicetree
dt
Only OOT subset of 
$OOT_SOURCE_LIST
oot
Only 
kernel/$KERNEL_SRC_DIR
kernel
Any mix spanning the above
full
Modes are union-able: 
full
runs 
kernel
→ 
oot
→ 
dt
in that order (kernel produces headers OOT needs; 
nvidia-dtbs
uses the same generated headers). A manually passed mode argument skips auto-detection.
将脏集合映射到对应模式（自动），或遵循传入的模式参数：
脏仓库（自动）模式
仅
hardware/nvidia/*
或
kernel-devicetree
dt
仅
$OOT_SOURCE_LIST
中的OOT子集
oot
仅
kernel/$KERNEL_SRC_DIR
kernel
上述类别的任意混合
full
模式可联合使用：
full
模式会按
kernel
→
oot
→
dt
的顺序运行（内核会生成OOT所需的头文件；
nvidia-dtbs
使用相同的生成头文件）。手动传入的模式参数会跳过自动检测。

Execute build

执行构建

Common setup + per-mode build snippets

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

Common setup (validate orchestrator Makefiles, 
cd $KS
) and the exact 
make
invocations for each mode (
dt
, 
oot
, 
kernel
, 
full
) plus the optional install consolidation pass live in 
references/build-modes.md
. Drive the relevant mode's snippet against the bindings from the "Resolve active target + paths + upstream env" step.
通用设置（验证编排器Makefiles，
cd $KS
）以及每个模式（
dt
、
oot
、
kernel
、
full
）的精确
make
调用，加上可选的安装整合步骤，均位于
references/build-modes.md
中。结合“解析激活目标 + 路径 + 上游环境”步骤中的绑定变量，调用对应模式的代码片段。

Register composite custom overlay (dt + full only)

注册复合自定义覆盖层（仅dt和full模式）

Skip unless the selected mode is 
dt
or 
full
. The composite overlay slot is documented in 
../../references/bsp-customization-kernel-dtb.md
; this sub-step owns the build / Makefile / flash-conf side of it.
Resolve the composite path for the active target (
$COMPOSITE_BASE
, 
$COMPOSITE_DTS
, 
$COMPOSITE_MK
) using the active profile's chip family, carrier ID/SKU, and module ID — full snippet in 
references/composite-registration.md
.
Gate (symmetric). 
$COMPOSITE_DTS
drives both directions: present → apply the two idempotent patches below; absent → run the cleanup pass to strip any stale 
dtbo-y +=
/ 
OVERLAY_DTB_FILE+=
line from a prior run. Either path keeps 
OVERLAY_DTB_FILE+=
from referencing an unbuilt 
.dtbo
— the build-time enforcement of the no-direct-in-tree-DT-edits rule.
  1. Per-dir Makefile — append 
    dtbo-y += <name>.dtbo
    after the last literal-named 
    dtbo-y +=
    entry. Inserting after the 
    $(old-dtbo)
    merge-back line skips the 
    $(addprefix makefile-path/,…)
    prefix pass and the build silently drops the composite. Commit to the 
    bsp_sources/
    mono-repo. Full snippet + rationale: 
    references/composite-registration.md
    .
  2. Carrier flash conf — append 
    OVERLAY_DTB_FILE+=",<name>.dtbo"
    with first-touch pristine import on the overlay tracker. On a fresh workspace the tracker is empty git-init; import the conf from 
    bsp_image
    and commit as 
    pristine:
    before the customization commit (workflow contract). Full snippet: 
    references/composite-registration.md
    .
The composite's parent sub-repo flipping HEAD during a customize-* append is what the "Detect dirty source repos" step's dirty detection consumes — no extra bookkeeping needed here.
Self-check before invoking 
nvidia-dtbs
:
bash
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."
除非所选模式为
dt
或
full
，否则跳过此步骤。复合覆盖层插槽的文档位于
../../references/bsp-customization-kernel-dtb.md
中；此子步骤负责其构建/Makefile/闪存配置端的操作。
使用激活配置文件的芯片系列、载体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. 载体闪存配置——追加
    OVERLAY_DTB_FILE+=",<name>.dtbo"
    ，首次接触时从覆盖层跟踪器导入原始版本。在新工作区中，跟踪器是空的git初始化仓库；在定制提交之前，从
    bsp_image
    导入配置并提交为
    pristine:
    （工作流约定）。完整代码片段：
    references/composite-registration.md
    。
定制操作追加时复合文件的父子仓库HEAD变化，会被“检测脏源码仓库”步骤的脏检测逻辑捕获——此处无需额外记录。
调用
nvidia-dtbs
前的自检：
bash
grep -qxF "dtbo-y += ${COMPOSITE_BASE}.dtbo" "$COMPOSITE_MK" \\
  || refuse "补丁后复合Makefile注册缺失。"
grep -qxF "$line" "$FLASH_CONF" \\
  || refuse "补丁后复合闪存配置注册缺失。"

Write the build manifest

写入构建清单

Walk the 
DIRTY
set and emit a manifest entry per implied artifact, following the trace-to-dirty policy — only artifacts traceable to a dirty source repo. Promoting baseline-divergence noise would attribute it to a customization's audit trail (forbidden).
The full source → kbuild → destination mapping, YAML schema, and filter rules live in 
references/manifest-schema.md
.
Atomic write: stage to 
${MANIFEST}.tmp
, then 
mv -f
.
遍历
DIRTY
集合，为每个相关产物生成清单条目，遵循跟踪到脏文件规则——仅包含可追溯到脏源码仓库的产物。禁止将基线差异的冗余内容纳入定制的审计跟踪中。
完整的源码→kbuild→目标路径映射、YAML模式和过滤规则位于
references/manifest-schema.md
中。
原子写入：先写入到
${MANIFEST}.tmp
，然后执行
mv -f
。

Update watermark + summary

更新水印 + 摘要

On success, rewrite 
$STATE
with the new per-repo HEADs, toolchain, 
bsp_image.version
, and last-run mode (schema in 
references/manifest-schema.md
).
Report:
  • Toolchain (from 
    source.toolchain
    ).
  • Build mode: 
    <dt|oot|kernel|full>
    (auto-picked or forced by skill argument).
  • Dirty repos and their new HEADs.
  • Artifacts built: counts per kind (
    .dtb
    , in-tree 
    .ko
    , OOT 
    .ko
    , 
    Image
    ).
  • Manifest path + entry count.
  • Consolidated install stage path (if the "Install consolidation" step ran).
  • Next step: 
    /jetson-promote-image
    .
If a Customize skill triggered this run, prompt the user to re-issue their original request.
成功后，用每个仓库的新HEAD、工具链、
bsp_image.version
和上次运行模式重写
$STATE
（模式位于
references/manifest-schema.md
中）。
报告内容：
  • 工具链（来自
    source.toolchain
    ）。
  • 构建模式：
    <dt|oot|kernel|full>
    （自动选择或由技能参数强制指定）。
  • 脏仓库及其新HEAD。
  • 已构建产物：按类型统计数量（
    .dtb
    、树内
    .ko
    、OOT
    .ko
    、
    Image
    ）。
  • 清单路径 + 条目数量。
  • 整合安装阶段路径（如果运行了“安装整合”步骤）。
  • 下一步操作：
    /jetson-promote-image
    。
如果是由定制技能触发的本次运行，提示用户重新发出原始请求。

Limitations

局限性

The top tier — failure modes that block a build or silently produce wrong artifacts. See 
references/long-tail-gotchas.md
 for invariants, deploy patterns, and performance hints.
  • Toolchain resolution is 
    jetson-init-source
    's job.     This skill only reads 
    source.toolchain
    and exports 
    CROSS_COMPILE
    . Missing field → refuse and route, never resolve in-skill.
  • R36.x Branch-A 
    $KS/Makefile
    collision.     R36.x's 
    public_sources.tbz2
    can leave the dGPU/OpenRM proprietary Makefile at 
    $KS/Makefile
    instead of the Tegra orchestrator; its 
    modules
    target recurses into 
    kernel-open/
    + 
    src/nvidia/
    , pulls host 
    /lib/modules
    headers, and breaks arm64 cross-builds with 
    '-mlittle-endian' unrecognized
    . R38+ extractions are unaffected. 
    /jetson-init-source
    's step 3a is the primary defense (extract-time); the "Common setup" check here is the safety net. Don't relax the regex.
  • Kernel-DT changes: composite-overlay-only, split ownership. Direct edits to in-tree 
    .dts
    / 
    .dtsi
    files under 
    bsp_sources/
    are forbidden for customize-* skills — every kernel-DT change lands as a fragment in the composite overlay slot (rule + rationale). The composite 
    .dts
    content is owned by each customize-* skill; the build / Makefile / flash-conf registration is owned by this skill (gated on the composite 
    .dts
    existing — so 
    OVERLAY_DTB_FILE+=
    can't reference an unbuilt 
    .dtbo
    ).
  • the "Register composite custom overlay" step Makefile insertion point matters. Insert after the last literal-named 
    dtbo-y +=
    entry; inserting after 
    $(old-dtbo)
    skips the 
    $(addprefix makefile-path/,…)
    prefix pass and the build silently drops your 
    .dtbo
    . The regex 
    ^dtbo-y *+= *[a-zA-Z0-9]
    filters correctly; do not relax it.
  • the "Register composite custom overlay" step first-touch needs pristine import. On a fresh workspace the overlay tracker is empty git-init — the carrier flash conf is imported from 
    bsp_image
    and committed as 
    pristine:
    before the customization commit. Both commits go through the workflow acceptance gate.
  • Avoid bare 
    $0
    in shell snippets inside this SKILL.md.     When invoked with an argument, the harness expands skill-body 
    $0
    against the caller's 
    $0
    before handing the rendered prompt to the model. Use sed-based line splicing or 
    awk -v ROW="$0"
    . See 
    references/composite-registration.md
    .
  • No overlay staging. Build outputs stay where the build put them; the manifest is the contract to 
    jetson-promote-image
    . Deliberate divergence from the original overlay→promote indirection — keeps the full build output set out of the overlay tracker's git history.
  • KERNEL_HEADERS
    vs 
    KERNEL_OUTPUT
    in DT mode.     Different semantics (srctree vs objtree); do not collapse. the "DT-only" step's snippet is correct as written.
  • OOT mode prereq: previously-built kernel headers. A manual 
    oot
    invocation against a never-built tree refuses with "run 
    kernel
    (or 
    full
    ) first" rather than producing a confusing build error.
以下是顶级限制——会阻止构建或静默生成错误产物的故障模式。请参阅
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更改：仅复合覆盖层，拆分所有权。禁止
    customize-*
    技能直接编辑
    bsp_sources/
    下的树内
    .dts
    /
    .dtsi
    文件——所有内核DT更改必须作为片段添加到复合覆盖层插槽中（规则+原理）。复合
    .dts
    的内容由每个
    customize-*
    技能所有；构建/Makefile/闪存配置注册由本技能所有（以复合
    .dts
    存在为门控——因此
    OVERLAY_DTB_FILE+=
    不会引用未构建的
    .dtbo
    ）。
  • “注册复合自定义覆盖层”步骤的Makefile插入位置至关重要。必须插入到最后一个字面命名的
    dtbo-y +=
    条目之后；如果插入到
    $(old-dtbo)
    之后，会跳过
    $(addprefix makefile-path/,…)
    前缀处理，构建会静默丢弃您的
    .dtbo
    。正则表达式
    ^dtbo-y *+= *[a-zA-Z0-9]
    可正确过滤；请勿放宽。
  • “注册复合自定义覆盖层”步骤的首次接触需要原始导入。在新工作区中，覆盖层跟踪器是空的git初始化仓库——载体闪存配置会从
    bsp_image
    导入并提交为
    pristine:
    ，然后再进行定制提交。两次提交均需通过工作流验收门控。
  • 本SKILL.md中的shell代码片段避免使用裸
    $0
    。当带有参数调用时，工具会在将渲染后的提示交给模型前，将技能主体中的
    $0
    替换为调用者的
    $0
    。请使用基于sed的行拼接或
    awk -v ROW="$0"
    。请参阅
    references/composite-registration.md
    。
  • 无覆盖层部署。构建输出产物保留在构建生成的位置；清单是与
    jetson-promote-image
    的约定。故意偏离原始的“覆盖层→部署”间接方式——可避免将完整构建输出集合纳入覆盖层跟踪器的git历史中。
  • DT模式中的
    KERNEL_HEADERS
    与
    KERNEL_OUTPUT
    。语义不同（源码树与目标树）；请勿合并。“仅DT”步骤的代码片段按编写方式是正确的。
  • OOT模式前提条件：已构建的内核头文件。针对从未构建过的树手动调用
    oot
    会拒绝操作，并提示“先运行
    kernel
    （或
    full
    ）”，而非产生令人困惑的构建错误。

Examples

示例

Auto-detect mode from the dirty source tree (typical invocation):
/jetson-build-source
Force a single mode (skips auto-detect):
/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
Typical chain after a customize-* skill commits to a kernel-side repo (the customize-* skill calls this automatically):
/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
根据脏源码树自动检测模式（典型调用）：
/jetson-build-source
强制指定单个模式（跳过自动检测）：
/jetson-build-source dt       # 仅重新构建NVIDIA DTBs
/jetson-build-source oot      # 仅重新构建OOT模块
/jetson-build-source kernel   # 重新构建内核Image + 树内模块
/jetson-build-source full     # 重新构建所有内容 + 安装整合
定制技能提交到内核端仓库后的典型链式调用（定制技能会自动调用本技能）：
/jetson-customize-pcie ...   # 提交到hardware/nvidia/.../nv-public
   ↓
/jetson-build-source         # 从脏集合自动选择`dt`模式
   ↓
/jetson-promote-image        # 读取.build-manifest.yaml，部署到bsp_image
   ↓
/jetson-flash-image          # 刷写镜像

Troubleshooting

故障排除

ErrorCauseSolution
source.toolchain points at <...>gcc which does not exist
Toolchain field stale (path moved, install missing)Re-run 
/jetson-init-source
to re-resolve. This skill never resolves toolchain itself.
No rule to make target '$KOUT/scripts/Makefile.compiler'
KERNEL_HEADERS
set to 
$KOUT
instead of 
$KS/kernel/$KERNEL_SRC_DIR
Use the DT-mode snippet in 
references/build-modes.md
 verbatim — srctree vs objtree must not collapse.
'-mlittle-endian' unrecognized
during 
make modules
R36.x Branch-A 
$KS/Makefile
collision — dGPU/OpenRM Makefile in place of Tegra orchestrator		The Common-setup safety net normally repairs it; if not, 
git checkout HEAD -- Makefile
then re-run 
/jetson-init-source
step 3a.
run kernel (or full) first
on manual 
oot
invocation		Kernel source tree never preparedRun 
/jetson-build-source kernel
(or 
full
) once, then 
oot
.
nothing to build
and dirty edits exist		Edits uncommitted in a sub-repo but 
.build-state.yaml
watermark already matches HEAD		Commit the edits, or re-run with an explicit mode argument (
/jetson-build-source dt
etc.).
Composite 
.dtbo
silently missing from the output set		Per-dir Makefile insertion landed after 
$(old-dtbo)
merge-back line		See 
references/composite-registration.md
 — insert after the last literal-named 
dtbo-y +=
entry.
Promote step copies stale baseline artifactsTrace-to-dirty filter skipped after a manual 
cp
into 
$KS
Only edit via a customize-* skill or 
git
; the dirty detector keys on git HEAD, not file mtime.
host package missing: <pkg>
flex
/
bison
/
libssl-dev
refuse; others warn.
sudo apt install <pkg>
per 
references/upstream-recipe.md
.
错误原因解决方案
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模式代码片段——源码树与目标树不得合并。
make modules
期间出现
'-mlittle-endian' unrecognized
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 +=
条目之后。
部署步骤复制了过期的基线产物手动
cp
到
$KS
后跳过了跟踪到脏文件的过滤		仅通过
customize-*
技能或
git
进行编辑；脏检测器基于git HEAD，而非文件修改时间。
host package missing: <pkg>
flex
/
bison
/
libssl-dev
缺失会拒绝操作；其他包缺失仅警告		根据
references/upstream-recipe.md
执行
sudo apt install <pkg>
。

See also

另请参阅

  • references/build-modes.md
     — per-mode 
    make
    snippets + install consolidation.
  • references/manifest-schema.md
     — 
    .build-manifest.yaml
    + 
    .build-state.yaml
    schemas.
  • references/composite-registration.md
     — the "Register composite custom overlay" step full snippets + rationale.
  • references/long-tail-gotchas.md
     — invariants, deploy patterns, performance hints.
  • references/upstream-recipe.md
     — verbatim NVIDIA recipe, divergences, spec status.
  • ../../context/bsp-customization-workflow.md
     — workspace edit protocol.
  • ../../references/bsp-customization-kernel-dtb.md
     — composite custom-overlay contract.
  • ../../references/bsp-customization-bpmp-dtb.md
     — BPMP-DTB edit contract (routed around this skill).
  • ../jetson-init-source/SKILL.md
     — Setup; authors 
    source.toolchain
    .
  • ../jetson-promote-image/SKILL.md
     — Deploy promoter; reads this skill's manifest.
  • 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
    ——部署推广器；读取本技能的清单。",