openwrt-target-switch-hygiene

name	openwrt-target-switch-hygiene
description	Switch build targets safely and clean stale artifacts in this OpenWrt repository. Trigger when asked to switch target architecture or device (switch target, change target, 切换目标, 换架构, 换设备), compare .config files, preview or apply pre-build cleanup (clean, 清理), or determine which old-arch artifacts can be removed without discarding reusable cache.

OpenWrt Target Switch Hygiene

Use this skill before any large rebuild that follows a target or device change, or as a pre-build step for full firmware builds. The goal is to do the least cleanup that still produces a correct build, and to preserve everything else as reusable cache.

Why minimal cleanup is correct

OpenWrt partitions per-target artifacts by architecture in directory names:

• build_dir/toolchain-aarch64_cortex-a72_…
• staging_dir/target-aarch64_cortex-a53_…

Two targets' trees coexist without interference — the new target's build never touches the old target's directories. Cross-arch deletion is therefore a disk-space decision, not a correctness one.

Buildroot's single source of truth for active package versions is tmp/.packageinfo, which lists exactly one PKG_VERSION per PKG_NAME. When PKG_VERSION changes, make defconfig regenerates .packageinfo and the old version disappears from buildroot's view. Old build_dir/<pkg>-<oldversion>/ directories with stale .built stamps become inert orphans — invisible to the build, but free rollback cache if PKG_VERSION is ever reverted.

Inside staging_dir/target-*/, files install to un-versioned paths (usr/bin/<pkg>, pkginfo/<pkg>.provides). New-version installs overwrite old-version files at the same path. There is no "two versions installed simultaneously" failure mode.

Workflow

1. Read the current .config and capture CONFIG_TARGET_BOARD, CONFIG_TARGET_SUBTARGET, CONFIG_TARGET_ARCH_PACKAGES.
2. (Optional) Identify the previous target from a snapshot config or an explicit old-arch string — only needed for the optional --full cleanup mode.
3. Run scripts/target_switch.py in dry-run mode (default) to preview what will be removed.
4. Apply the suggested commands. The default mode (--mode minimal) is safe to apply without asking. The --mode full mode deletes old-arch toolchain/target trees and should be confirmed with the user.
5. Run make defconfig, then openwrt-build-runner for the next compile.

Cleanup tiers

--mode minimal (default) — required for correctness

rm -rf tmp/
rm -rf bin/targets/<NEW_BOARD>/<NEW_SUB>/

tmp/ is rebuilt by make defconfig in seconds. Clearing the new target's bin/targets/<board>/<sub>/ avoids stale image files mixing with the new output. Other targets' subdirs under bin/targets/ are left alone.

--mode full — disk reclamation, requires --old-arch or --old-config

In addition to the minimal set:

rm -rf build_dir/toolchain-<OLD_ARCH>* \
       build_dir/target-<OLD_ARCH>* \
       staging_dir/toolchain-<OLD_ARCH>* \
       staging_dir/target-<OLD_ARCH>*

Approximate sizes per old target: toolchain ~1.6 GB, target build ~10–20 GB, staging toolchain ~200 MB, staging target ~1–2 GB. Re-creating on switch-back: ~30 min toolchain, hours for the package set. Use only under genuine disk pressure.

Commands

# Preview minimal cleanup (dry run — no changes)
skills/openwrt-target-switch-hygiene/scripts/target_switch.py

# Apply minimal cleanup (always safe)
skills/openwrt-target-switch-hygiene/scripts/target_switch.py --apply

# Disk reclamation: drop old-arch trees (confirm with user first)
skills/openwrt-target-switch-hygiene/scripts/target_switch.py \
  --mode full --old-arch aarch64_cortex-a53 --apply

# Use a saved config snapshot to derive the old arch
skills/openwrt-target-switch-hygiene/scripts/target_switch.py \
  --mode full --old-config config/.config.GL-iNet-MT6000_23.05.5 --apply

Guardrails

• Never remove dl/, feeds/, build_dir/host/, build_dir/hostpkg/, staging_dir/host/, staging_dir/hostpkg/, or staging_dir/packages/.
• Default cleanup mode must be minimal. full mode is opt-in and must be confirmed with the user before applying.
• Refuse --mode full if --old-arch/--old-config matches the current target's CONFIG_TARGET_ARCH_PACKAGES.
• Treat orphan build_dir/<pkg>-<oldversion>/ directories as valuable — inert to the current build but they accelerate PKG_VERSION rollbacks. Do not delete them as part of routine target switches.

References

Read references/workflow.md for the long-form explanation of why cross-arch trees do not conflict and how tmp/.packageinfo drives version selection.