Build BSP Source

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.

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.

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:

Mode	What's built	Auto-picks when
dt	NVIDIA DTBs only	only `hardware/nvidia/*` or `kernel-devicetree` dirty
oot	OOT modules (six repos)	only OOT repos dirty
kernel	Kernel `Image` + full in-tree `.ko` set + kernel-side dtbs	only `kernel/$KERNEL_SRC_DIR` dirty
full	Everything above + optional install consolidation	mixed 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.

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).

Instructions

Resolve active target + paths + upstream env

Resolve the active profile per

../../context/target-platform-contract.md

. Refuse and route in these cases:

Condition	Route 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"
# Now in scope: KERNEL_SRC_DIR (e.g. kernel-noble), KERNEL_DEF_CONFIG,
# OOT_SOURCE_LIST, kernel_name (e.g. 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

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

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).

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.

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.

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.

Register composite custom overlay (dt + full only)

Skip unless the selected mode is

dt

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.

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
```
.
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."

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

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.

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.

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

Troubleshooting

Error	Cause	Solution
`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 prepared	Run `/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 artifacts	Trace-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` .

jetson-build-source

NPX Install

Tags

SKILL.md Content

Build BSP Source

Purpose

Prerequisites

Overview

When to invoke

Instructions

Resolve active target + paths + upstream env

Resolve toolchain (read-only)

Detect dirty source repos

Pick build mode

Execute build

Common setup + per-mode build snippets

Register composite custom overlay (dt + full only)

Write the build manifest

Update watermark + summary

Limitations

Examples

Troubleshooting

See also