/jetson-init-source

name: jetson-init-source
description: >-
  Set up the BSP source workspace: Linux_for_Tegra overlay tracker,
  bsp_sources, Crosstool-NG toolchain. Use after jetson-init-image;
  not for fetching inputs.
version: 0.0.1
license: "Apache-2.0"
metadata:
  data-classification: public
  author: "Jetson Team"
  tags:
    - bsp
    - workspace
    - kernel
    - bootstrap
  domain: meta

Initialize BSP Customization Workspace

Overview

This skill bootstraps the source-side workspace that customize-* / build skills depend on: the `Linux_for_Tegra` overlay tracker (git repo for pristine + customization commits), the `bsp_sources/` mono-tree (kernel, OOT, nvgpu, display, hwpm, hardware DTs), and a working NVIDIA Crosstool-NG cross-compile prefix. It owns only the `source:` block in the active profile and the on-disk source workspace under `<source.root_path>` (default: `<workspace>/Source`).

Responsibilities:

1. Optionally record a non-default `source.root_path`. 2. Create or mount the `Linux_for_Tegra` overlay tracker. 3. Materialize `bsp_sources` using the precedence in the "Materialize the BSP-sources baseline" step. 4. Resolve and record `source.toolchain`. 5. Clone extra user-defined repos from `source.repos:`.

When to invoke

• The user asks to bootstrap, init, or sync the BSP customization

workspace.

• A downstream customization skill refused with "no workspace

tracker at `<source.root_path>/Linux_for_Tegra/`".

• After `jetson-init-image` (Setup's next step on a fresh target).

Procedure

Quick-start prefill mapping

Follow the shared [`quick_start_prefill` contract](../../context/bsp-customization-workflow.md#quick_start_prefill-contract). This skill has source-specific mappings:

• `quick_start_prefill.source.public_sources_archive` maps to the

Branch-A archive candidate.

• `quick_start_prefill.source.repos` maps to proposed `source.repos:`

entries; validate reserved keys and `url:` / `archive:` mutual exclusion before writing.

• `quick_start_prefill.source.toolchain` may be a cross-compile prefix,

a `gcc` path, a containing `bin/` directory, an `x-tools.tbz2` archive path, or `skip`.

This skill remains the only owner of `source.root_path`, `source.repos:`, and `source.toolchain` profile writes.

Resolve the active target + paths

Resolve the active profile + workspace defaults per the contract in [`../../context/target-platform-contract.md`](../../context/target-platform-contract.md).

• **Refuse** if `<bsp_image.root_path>` does not contain

`Linux_for_Tegra/` (BSP not extracted — route to `/jetson-init-image`).

• If the profile has `source.root_path:`, use it. Otherwise

`<source.root_path>` defaults to `<workspace>/Source`; use that default silently and do not write `source.root_path:` to the profile. Ask only for an explicit custom path, unrelated content at the default path, or an unwritable parent.

Read `source.repos:` (if present) into a map keyed by entry name, each carrying optional `url`, `ref`, `subdir`, `path`. Reserved keys: `Linux_for_Tegra` (overlay tracker), `bsp_sources` (kernel-source repo). Every other key is an extra user-defined repo.

(Optional) prompt for `source.root_path` override

Only when `source.root_path` is absent from the profile **and** one of the override conditions above applies:

> `source.root_path`: default = `<workspace>/Source`. Press Enter to > accept, or enter an absolute path to override.

• **On Enter** — keep the default; do not touch the profile.
• **On override path** — validate the closest existing parent is

writable; refuse and re-prompt if not. Edit `target-platform/<active>.yaml` in place to add/update `source.root_path:`. Preserve all other blocks, comments, and quoting — use a round-tripping YAML loader (e.g. `ruamel.yaml`).

Fires at most once per profile. Otherwise create `<workspace>/Source` as needed and continue without prompting.

Materialize `Linux_for_Tegra`

Mount path is canonical: `<source.root_path>/Linux_for_Tegra/`.

**Default** (no `source.repos.Linux_for_Tegra` entry):

LFT="<source.root_path>/Linux_for_Tegra"
mkdir -p "$LFT"
[ -d "$LFT/.git" ] || git -C "$LFT" init

Empty tracker. **Do not commit anything here** — pristine imports happen file-by-file when customization skills run.

**Override** (`url`, `ref`, optional `subdir`):

# Clone the user's repo to a side location, then mount the
# expected tree (subdir or repo root) at the canonical path.
CLONE="<source.root_path>/.repos/Linux_for_Tegra"
git clone <url> -b <ref> "$CLONE"
ln -s "$CLONE/<subdir or .>" "<source.root_path>/Linux_for_Tegra"

If the mount already exists with valid git state, skip; refuse if it exists with unrelated content.

Materialize the BSP-sources baseline

Three branches, dispatched **in precedence order** against the profile entry `source.repos.bsp_sources`:

| Order | Profile state | Branch | |---|---|---| | 1 | `url:` set | **C. Customer git clone** (explicit override always wins) | | 2 | `archive:` set, **OR** entry absent **AND** `<workspace>/Downloads/public_sources.tbz2` exists | **A. Local archive extraction** (default) | | 3 | Entry absent **AND** no local archive | **B. `source_sync.sh`** (fallback) |

`url:` and `archive:` are **mutually exclusive** — refuse if both are set in the same entry.

Branch A is the preferred default because it sidesteps NVIDIA git egress entirely (the most common Setup failure mode). Branch B exists for fresh workspaces with no pre-downloaded tarball. Branch C is for customer forks of the whole BSP layout.

Branch A — Local archive extraction (default)

Default branch: extract a pre-downloaded `public_sources.tbz2` into `<source.root_path>/bsp_sources/` as a single mono-repo (`git init` + pristine commit). See [`references/branch-a-extraction.md`](references/branch-a-extraction.md) for the full archive shape, path-resolution rules, and the extraction script (including the Tegra OOT Makefile force-repla