AlvinArch/AGENTS.md

AGENTS.md

Arch Linux ISO profile (archiso). Builds a live ISO with Hyprland desktop, end-4 dots-hyprland, and curated packages. Hosted on Gitea.

Build & Test Commands

# Build the ISO (repo root IS the profile directory)
sudo mkarchiso -v -w work -o out/ .

# Build AUR deps for end-4 (run locally before ISO build if localrepo/ is stale)
./localrepo/build-end4-deps.sh          # build all
./localrepo/build-end4-deps.sh --quick  # skip large AUR pkgs

# Refresh localrepo DB after adding/moving .pkg.tar.zst files
./localrepo/update.sh                    # re-indexes existing packages
./localrepo/update.sh pkg1.pkg.tar.zst   # add files, then re-index

CI Checks (must pass before merge)

• ShellCheck: all .sh files checked with shellcheck -x -s bash
• yamllint: all .yml/.yaml files (relaxed config)
• packages.x86_64 syntax: one package per line, no trailing whitespace, [a-zA-Z0-9._@+\-]+ only
• Package repo check: every package in packages.x86_64 must be resolvable via pacman -Si in allowed repos (cachyos, extra, multilib, chaotic-aur), OR have a pre-built .pkg.tar.zst in localrepo/, OR appear in localrepo/build-end4-deps.sh

Package Management

Three sources contribute packages to the ISO:

1. packages.x86_64 — main list, installed by mkarchiso. Must be in an allowed repo.
2. localrepo/*.pkg.tar.zst — pre-built AUR packages. The local-aur repo is configured in pacman.conf and picked up by mkarchiso automatically.
3. build-end4-deps.sh — builds end-4 AUR deps at build time.

Important: localrepo/update.sh auto-appends new package names to packages.x86_64. If you remove a package from packages.x86_64 that exists in localrepo/, it will be re-added on the next update.sh run.

Key Files

File	Purpose
packages.x86_64	Live ISO package list (~402 packages)
profiledef.sh	ISO metadata, compression, boot modes
pacman.conf	Repos: cachyos → core → extra → multilib → chaotic-aur → local-aur
bootstrap_packages	Minimal build-time packages (base, arch-install-scripts)
airootfs/root/customize_airootfs.sh	Runs inside chroot during build: keyrings, oh-my-zsh, lazy.nvim, plugins
localrepo/build-end4-deps.sh	Non-interactive AUR builds for end-4 dependencies
localrepo/update.sh	Regenerates localrepo DB + syncs names to packages.x86_64

Gotchas

• The profile root is the repo root (not a releng/ subdirectory). The CI build-iso workflow uses mkarchiso -v -w work -o out/ releng but this is a naming convention — the actual profile files live at the repo root.
• customize_airootfs.sh clones git repos (oh-my-zsh, lazy.nvim, plugins) into /etc/skel during the ISO build. These require network access at build time but make the live ISO work offline.
• The [local-aur] repo path in pacman.conf (file:///home/alvin/alvinarch/localrepo) is for local builds only. The CI does not use this path.
• End-4 metapackages are built from localrepo/end4-pkgbuilds/ (quickshell-git, bibata-modern-classic-bin, microtex-git).
• packages.x86_64 is sorted alphabetically. Keep it sorted when adding/removing entries.