diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 78 |
1 files changed, 78 insertions, 0 deletions
diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dcc195e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,78 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (Claude Code, opencode, etc) working in this repository. + +## What this is + +Single bash script (`slackrepo_setup_SBo-danix.sh`) that builds a personal Slackware SlackBuilds +repo at `/var/lib/sbopkg/SBo-danix`. The repo feeds **slackrepo** (`../GITHUB/slackrepo/`), the +tool used to build slackware64-current packages. The repo is regenerated from scratch weekly. +No build/test tooling; run the script directly. + +## The -current dependency problem + +SBo SlackBuilds target Slackware **stable**. Some of their build-time REQUIRES are unneeded on +**-current** because -current already ships them as system packages or newer versions. Examples: +`google-go-lang` (system package in -current), `rust-opt` (only exists because stable's system +rust is old). These are "phantom deps" on -current. + +slackrepo strips a dep from a package via a per-package **hintfile** (`<prgnam>.hint`) containing +`DELREQUIRES="rust-opt"`. Relevant slackrepo internals: + +- Hintfile search order (`parsefunctions.sh` ~line 414): `$SR_SBREPO/$itemdir`, `$SR_HINTDIR`, + `$SR_HINTDIR/$itemdir`, then `$SR_DEFAULT_HINTDIR[/itemdir]`. **First match wins** — only one + hintfile per package is sourced. +- `DELREQUIRES` (`parsefunctions.sh` ~line 595) removes listed deps from that **single** package's + REQUIRES. There is **no** repo-wide "delete dep X everywhere" mechanism; every dependent needs + its own hintfile. Hintdirs are set in `etc/slackrepo_SBo-danix.conf` (`HINTDIR`, + `DEFAULT_HINTDIR`). + +Pain point: a package with ~20 REQUIRES may pull in several phantom-dep dependents; hand-writing a +hintfile per dependent each week is tedious and error-prone. + +**Solution does not live here.** Hintfiles are owned by the `mkhint` tool (`../mkhintfile/`), which +already creates/backs up/reviews them. The phantom-dep auto-strip is implemented there, not in this +setup script: +- A phantom-dep list at `~/.config/mkhint/phantom-deps` (one dep per line, `#` comments). +- `mkhint --new` auto-adds `DELREQUIRES` for any listed dep it sees in the `.info` REQUIRES. +- `mkhint --fix-current` (`-F`) bulk-sweeps the whole repo after a weekly regen: every package whose + REQUIRES hits a phantom dep gets a hintfile with the right `DELREQUIRES` (created if absent, merged + in place if present). + +Weekly flow: regenerate repo with this script; `sbshadow` runs `mkhint -F` at the end. +Do **not** add a hintfile generator to this script — it would create a second owner of HINT_DIR and +fight mkhint's `.bak` handling. + +## Run + +```bash +./slackrepo_setup_SBo-danix.sh +``` + +Destructive: `rm -rf`s `$REPO` on every run to start clean, then re-clones upstream. Interactive +`read` prompt inside `sbshadow` is the only confirmation (declining exits 0, run continues). + +## Architecture + +Pipeline, in order: + +1. Clone upstream SBo (`Ponce/slackbuilds`), check out `current`, branch to `danix-current`. +2. Overlay two personal remotes as **git subtrees** (squashed): `my-slackbuilds` → `personal/`, + `Slackware-Pentesting-Suite` → `pentesting/`. +3. **Shadowing**: delegated to `sbshadow` (separate script, must be on PATH). It reconciles both + ways against the pristine `current` branch: any upstream package whose directory name matches a + package under `personal/` or `pentesting/` is `git rm`'d (shadow); any upstream package missing + from HEAD and no longer carried in an overlay is restored with `git checkout current -- cat/pkg` + (unshadow). A package is identified by a `$pkg/$pkg.SlackBuild` file. Match by directory + basename only, not content. Then it always runs `mkhint -F`. + +`sbshadow` is also called by the `sbpull` bash function (`sbpull.bash`, sourced from root's `.bashrc` on the build VM) after a +`git subtree pull`, so overlay changes are applied without regenerating the whole repo. It is the +single owner of shadow logic; do not re-inline it here. + +## Constraints + +- `set -euo pipefail` — any unhandled failure aborts. Keep new steps failure-safe. +- Paths under `$REPO`; shadow logic depends on the upstream layout being `category/package/` + (`sbshadow` greps `cat/pkg/pkg.SlackBuild` in `git ls-tree current`). Layout change breaks it. +- Unshadow assumes anything missing from HEAD but present in `current` was removed by shadowing. |