buildbrain/AGENTS.md

# AGENTS.md

## Purpose

This repository builds Brainux, a Debian-based Linux distribution and SD card image for SHARP Brain devices. The root repo is the orchestration layer: it wires together kernel, bootloader, rootfs, image-building scripts, CI, and several hardware-specific submodules.

Future agents should treat this file as project memory plus operating instructions for working in `buildbrain`.

## Repository map

- `linux-brain/`: Linux kernel submodule.
- `u-boot-brain/`: U-Boot submodule.
- `boot4u/`: chain-boot tool for newer models.
- `brainlilo/`: chain-boot tool for older models.
- `nkbin_maker/`: converts `u-boot.bin` into `nk.bin` for the Windows CE boot flow.
- `buildroot/`: alternative lightweight rootfs build.
- `os-brainux/`: Brainux rootfs customization scripts and overrides.
- `os-buildroot/`: Buildroot-side overrides.
- `image/`: SD image creation scripts.
- `tools/`: helper scripts such as cross-prefix detection and APT cache tooling.
- `docs/knowledge/`: hardware and boot-process knowledge for SHARP Brain devices. Prefer the Markdown files over PDFs for fast reading and search.

## Search strategy

Do not start with a repo-wide search from the root unless you actually need submodule results. This repo contains large submodules, and broad searches are noisy and slow.

Prefer scoped searches:

- Kernel work: search only under `linux-brain/`.
- U-Boot work: search only under `u-boot-brain/`.
- Rootfs and image work: search `os-brainux/`, `image/`, `tools/`, and the root `Makefile`.
- Hardware/background research: read `docs/knowledge/*.md`.

## Important project knowledge

- Brainux development often happens in submodules, not in the root repo.
- Typical kernel workflow:
  1. work inside `linux-brain/` on a branch based on `brain`
  2. return to the repo root
  3. run `make lclean ldefconfig lbuild` for a clean rebuild, or `make lbuild` for incremental rebuilds
  4. test on real hardware by copying `linux-brain/arch/arm/boot/zImage` and matching DTBs
  5. commit in `linux-brain/` using the surrounding kernel commit style
- Typical U-Boot workflow is similar, but uses `u-boot-brain/` plus the `make udefconfig-*` and `make ubuild` targets.
- Typical Brainux rootfs workflow edits files under `os-brainux/`, then runs `make brainux` or `make image/sd.img`.
- Real-device testing is part of the normal loop. A local build passing is useful but not sufficient for hardware changes.

## Main build targets

The root `Makefile` is the main entry point.

- Setup:
  - `make setup`: initialize submodules.
  - `make setup-dev`: create `env/` and install `r3build`.
  - `make watch`: run the file watcher after `setup-dev`.
- Linux:
  - `make ldefconfig`
  - `make ldefconfig-x1`
  - `make lbuild`
  - `make lclean`
- U-Boot:
  - `make udefconfig-<model>` such as `udefconfig-sh1` or `udefconfig-h1`
  - `make ubuild`
  - `make uclean`
- NK.bin:
  - `make nkbin-maker`
  - `make nk.bin`
- Chain boot tools:
  - `make boot4ubuild`
  - `make lilobuild`
- Rootfs and images:
  - `make brainux`
  - `make brainux-umount-special`
  - `make brainux-clean`
  - `make buildroot_rootfs`
  - `make image/sd.img`
  - `make image/sd_x1.img`
  - `make image/sd_buildroot.img`
- Utilities:
  - `make aptcache`
  - `make uuu`

## Build behavior and constraints

- `make brainux` only works on Linux. It uses `debootstrap`, `qemu-arm-static`, `sudo`, chroot, and bind mounts.
- Outside CI, `make brainux` expects the local APT cache from `make aptcache` and points debootstrap at `http://localhost:65432/debian/`.
- `make brainux-umount-special` is the normal cleanup step after rootfs builds.
- `make image/sd.img` and related image targets depend on a prepared rootfs and remove `image/work` via `make clean_work`.
- `make ubuild` chooses the output format from the detected cross toolchain:
  - `arm-linux-gnueabi-` builds `u-boot.sb`
  - other configured prefixes build `u-boot.imx`

## CI reference

The authoritative automation is `.github/workflows/build.yml`.

CI currently does the following:

- Builds Linux artifacts for both the default family and the `x1` family.
- Builds U-Boot artifacts for multiple models through a matrix.
- Builds `nk.bin` for the older-model U-Boot jobs.
- Builds full Debian-based SD images for the default family and for `x1`.

When changing build logic, keep the local Makefile workflow and CI workflow aligned.

## Files and outputs to know

- Linux outputs:
  - `linux-brain/arch/arm/boot/zImage`
  - DTBs under `linux-brain/arch/arm/boot/dts/`
- U-Boot outputs:
  - `u-boot-brain/u-boot.bin`
  - `u-boot-brain/u-boot.sb` or `u-boot-brain/u-boot.imx`
- Converted boot image:
  - `nk.bin`
- SD images:
  - `image/sd.img`
  - `image/sd_x1.img`
  - `image/sd_buildroot.img`

## Guidance for edits

- If the task is about kernel or U-Boot source, make the change in the relevant submodule rather than trying to patch generated outputs or wrapper scripts in the root repo.
- If the task is about Brainux package selection, startup behavior, or filesystem contents, inspect `os-brainux/` first.
- If the task is about image layout or packaging, inspect `image/` and the root `Makefile`.
- If the task is about cross-compile behavior, inspect `tools/getcross` and the relevant Makefile targets.
- Avoid using interactive config editors such as `menuconfig` unless the user explicitly asks; prefer editing committed defconfig/config sources where practical.

## Validation expectations

Choose the lightest validation that matches the change:

- Makefile or CI edits: run the directly affected `make` target when feasible.
- Kernel build plumbing: at least run the relevant `make ldefconfig*` or `make lbuild` path if the environment supports it.
- U-Boot build plumbing: at least run the matching `make udefconfig-*` and `make ubuild` path if feasible.
- Rootfs/image changes: prefer `make brainux brainux-umount-special`, and image targets when dependencies and privileges are available.

If a full build is not possible because of missing toolchains, root privileges, mounts, or long runtime, say that explicitly and leave the repo in a clean state.

## Knowledge docs

- Start with `docs/knowledge/*.md` when you need hardware, boot-sequence, suspend, or eMMC-install context.
- `docs/knowledge/AGENTS.md` defines the rule for converting a knowledge PDF into Markdown. If asked to do such a conversion, preserve page positions with `# Page NN` headings, add an abstract, and write a concise text-first technical explanation rather than raw OCR.

## Commit and review notes

- Submodules have their own history and conventions. Kernel commits should follow the style already used in `linux-brain/`.
- Root-repo changes should stay focused on orchestration, config, CI, docs, image assembly, and rootfs customization.
- When a task spans both the root repo and a submodule, keep the responsibility split clear in the final report.