---

name: jetson-build-source description: >- Use when you need to rebuild the BSP overlay — DT, OOT modules, or kernel — from changes under bsp_sources/. Triggers: build bsp, rebuild dtb, rebuild kernel. version: 0.0.1 license: "Apache-2.0" argument-hint: "dt | oot | kernel | full" metadata: data-classification: public author: "Jetson Team" team: pts tags: - bsp - build domain: meta

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:

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:

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:

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:

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

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.

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 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:

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, `