openwrt-build-helper/AGENTS.md

AGENTS.md

Guidance for coding agents working in this repository.

What this is

A set of Bash scripts that automate building OpenWrt from source: install the host dependencies, fetch the source tree, import a device's official configuration, and apply a per-device package list.

There is no build system, no test suite and no dependency manifest. The deliverable is the scripts. Everything is plain Bash plus curl/wget, git, awk, sed and python3 (only for reading JSON — jq is deliberately not required).

The governing design rule: a new OpenWrt release must not require editing any file here. Anything version specific is fetched from downloads.openwrt.org at run time; only the user's own package choices are stored in git. Reject changes that would reintroduce a version-pinned file, a hardcoded device table or a copied-in package list.

Repository layout

This repository is helper/ inside an OpenWrt source tree. prepare-openwrt.sh puts it there on first run:

<parent>/openwrt/                 OpenWrt source root (not this repository)
<parent>/openwrt/helper/          this repository
<parent>/openwrt-build-helper     symlink to openwrt/helper, for stale shells

helper/
  *.sh                            the scripts
  lib-openwrt-upstream.sh         shared library, sourced not executed
  packages/<device-id>.txt        tracked: the user's packages for one device
  .generated/                     ignored: combined lists, saved buildinfo
  README.md                       user-facing documentation

<device-id> is the official OpenWrt profile id (linksys_mx8500), so the filename, the --device argument and upstream's profiles.json key are always the same string.

Where the scripts run from

Two groups, and mixing them up is the most common mistake:

• prepare-openwrt-env.sh and prepare-openwrt.sh run from this directory; they exist to create the OpenWrt tree, so they cannot assume one.
• Everything else runs from the OpenWrt root (./helper/<script>.sh) because it reads or writes .config, feeds/, tmp/ or package/. Each of those guards its entry point — require_openwrt_root from the library, or an equivalent inline test for feeds.conf.default + Makefile. Keep that guard when adding a script to this group. The exception is gen-package-list.sh, which only produces text: it needs the tree for version detection (or --version) and delegates the root check to add-openwrt-packages.sh on --apply.

Never derive the OpenWrt root from $0's parent alone: the compat symlink means the script may be invoked through a path outside the tree. Resolve with pwd -P, and use find_openwrt_root when a version query must be anchored to the OpenWrt tree rather than to this repository's own git checkout.

The scripts

Script	Role
prepare-openwrt-env.sh	install host build dependencies; dispatches on the package manager (apt/dnf/yum/pacman/zypper/apk)
prepare-openwrt.sh	clone or update the OpenWrt tree, relocate this repository into it
lib-openwrt-upstream.sh	shared upstream access: URLs, caching, version detection, device lookup
download-config.sh	install a device's official config.buildinfo as .config
gen-package-list.sh	built-in packages from profiles.json + packages/<id>.txt
add-openwrt-packages.sh	apply a package list to .config
update-go-path.sh	point the build at an installed Go toolchain
add-external-repos.sh	clone extra package repositories into package/

Only download-config.sh and gen-package-list.sh source the library; it is guarded against double-sourcing by _OWRT_LIB_LOADED.

Conventions

Match the existing style rather than introducing your own:

• set -euo pipefail and umask 022 at the top of every executable script (add-external-repos.sh predates the convention and still uses bare set -e). The library sets nothing — the caller owns shell options.
• The usage block is the file's own header comment, printed by usage() { sed -n '<start>,<end>p' "$0" | sed 's/^# \{0,1\}//;s/^#$//'; }. Editing the header changes --help — keep the line range correct, and update the header whenever you add an option.
• All logging goes to stderr (info/warn/err). Functions return their value on stdout, so a stray echo to stdout corrupts VAR="$(fn)" at the call site. This has broken the code before.
• Every destructive command goes through run, so --dry-run prints instead of acting; every prompt goes through confirm, so -y skips it. Both honour the DRY_RUN / ASSUME_YES globals.
• Read-only discovery first, mutation after the confirmation prompt. Aborting at the prompt must leave the filesystem untouched.
• Write to a temp file and validate before replacing something that matters; keep a .bak.
• Tunables are ${VAR:-default} so they can be overridden from the environment without editing the file.

Bash traps that have actually bitten this code:

• local a="$1" b="$a" — bash expands every word before assigning any, so $a is unset under set -u. Use one local per dependent variable.
• nullglob only drops words that contain a wildcard; a literal path such as /usr/local/go/ survives even when it does not exist. Check with -d.
• cmd | grep -q under pipefail can fail on SIGPIPE. Prefer a pipe-free form.
• In awk -F'\t', $2 is not whitespace-split. Extract with string operations when the field separator is not space.
• git checkout <ref> is a no-op when HEAD is already at <ref>, so it does not restore deleted tracked files.

Data files

packages/<device-id>.txt is hand written and holds only the user's extra packages — never the built-in set, which is always generated. Format:

curl luci-app-ttyd     whitespace separated, any number per line, applied as =y
-luci-app-wol          leading '-' removes a package (=n)
##module               following packages are set to =m
##remove               ... =n
##built-in             ... back to =y (the default)
pkg  # note            text after a single '#' is a comment

.generated/ is git-ignored build output. Do not commit it, and do not make anything depend on a file in it existing.

Checking your work

There is no test runner. Before committing:

• bash -n <script> on everything you touched.
• shellcheck if available.
• Run the script with -n/--dry-run and with -h; confirm -h still prints the full option list (the sed line range drifts silently).
• Behaviour-changing edits to config handling deserve a real check against a concrete device: generate before and after, and diff the resulting sets of =y packages. Do not claim equivalence you have not diffed.

Assume the user's machine is not the only target: no absolute home paths, no assumption of a distro, an init system, or WSL. Platform-specific advice belongs in the README under an explicit conditional heading.