diff options
Diffstat (limited to 'AGENTS.md')
| -rw-r--r-- | AGENTS.md | 182 |
1 files changed, 168 insertions, 14 deletions
@@ -1,7 +1,7 @@ -# Agent Instructions — SlackBuilds Repository +# SlackBuilds Repository -This file governs how AI agents must behave in this repository. -**Read it in full before taking any action.** +Personal collection of SlackBuild scripts maintained by Danilo, compatible with +[SlackBuilds.org (SBo)](https://slackbuilds.org) conventions. --- @@ -38,9 +38,15 @@ Each package lives in its own top-level subfolder: Root-level files you may need to edit: ``` -nvchecker.toml # Upstream version tracking — one entry per package +.extras/nvchecker.toml # Upstream version tracking — one entry per package ``` +### `.extras/` holds all non-package repo files + +Anything that is not a SlackBuild package must live under `.extras/`, never at +the repo root. In particular, design docs and specs go in +`.extras/docs/`, NOT a top-level `docs/`. + --- ## Mandatory Workflow: Updating a Package Version @@ -105,17 +111,50 @@ Before creating any files, ask the user for: - The upstream source URL and version - Any non-SBo runtime dependencies +Also check the package name is free on SlackBuilds.org: search +https://slackbuilds.org/result/?search=<name> (or browse the category). +If the name is taken by an unrelated project, pick a distinct name (e.g. +gitea-cli instead of tea, whose slot is a text editor) and keep the upstream +binary name via a SRCNAM variable in the SlackBuild. + Then proceed: 1. Create the package directory with all required files: `<prgnam>.SlackBuild`, `<prgnam>.info`, `README`, `slack-desc` 2. Follow the SlackBuild scripting rules below exactly. -3. Add an entry for the package in `nvchecker.toml`. +3. Add an entry for the package in `.extras/nvchecker.toml`. 4. Run `sbofixinfo`, then `sbodl` (two-pass if needed), then `sbolint`. 5. Report results and wait for commit instruction. --- +## Templates + +Templates live in `~/Templates/SlackBuilds/sbo/` (a git clone of the SBo +templates). **Always start from these templates** when authoring a NEW +SlackBuild, or when taking over maintenance of an existing script. Read the +matching template first; do not copy an existing package from this repo and +rename it — an old package can carry drift the current template has since fixed. + +Pick by build system: + +| Template | Use for | +|----------|---------| +| `sbo/python-template.SlackBuild` | Python packages (setup.py and pyproject-only paths) | +| `sbo/autotools-template.SlackBuild` | `./configure && make` | +| `sbo/cmake-template.SlackBuild` | CMake | +| `sbo/meson-template.SlackBuild` | Meson | +| `sbo/perl-template.SlackBuild` | Perl modules | +| `sbo/rubygem-template.SlackBuild` | Ruby gems | +| `sbo/haskell-template.SlackBuild` | Haskell | +| `sbo/template.info`, `sbo/slack-desc`, `sbo/README`, `sbo/doinst.sh`, `sbo/douninst.sh` | the other package files | + +Strip the template's instructional comment blocks and unused branches (e.g. the +python2/setup.py path, the man-page gzip block when upstream ships no man pages) +before shipping the script. + +--- + ## SlackBuild Scripting Rules - Base all scripts on the SBo template: https://slackbuilds.org/templates/ @@ -125,6 +164,11 @@ Then proceed: - Strip binaries and libraries (unless upstream explicitly discourages it). - Install docs to `/usr/doc/$PRGNAM-$VERSION/`. - Always include the `find -L` + `chown`/`chmod` cleanup block before packaging. +- Copy repo files into `$PKG` with `cat src > dest`, never `cp`. `cat` writes + through a fresh destination so the build's umask/root ownership sets the + perms; `cp` bleeds the git working-tree mode/ownership into the package. + Applies to `slack-desc`, `doinst.sh`, and any file staged from `$CWD` + (SlackBuild, README, `.nvchecker`) into `$PKG`. - Build the package with `makepkg -l y -c n`. ### `.info` file — required fields @@ -144,19 +188,34 @@ EMAIL="danix@danix.xyz" - `REQUIRES=""` if no SBo dependencies; otherwise space-separated SBo package names. - Checksums must match the exact source archive — verify with `sbodl`. +- `MD5SUM` may be replaced by `SHA256SUM` where preferred. ### `slack-desc` rules - Exactly 11 lines, each prefixed with `package-name: `. - Line 1: `package-name: package-name (short one-liner description)` - Lines 2–11: prose description; blank lines use `package-name:` with nothing after the colon. -- Do not include the ruler line in the committed file. +- Handy ruler line must be included (but not shipped). + +--- + +## Tooling: sbo-maintainer-tools + +Source: https://slackware.uk/~urchlay/repos/sbo-maintainer-tools + +| Tool | Purpose | +|------|---------| +| `sbolint` | Lint `.SlackBuild`, `README`, `.info`, `slack-desc` | +| `sbopkglint` | Lint the built package | +| `sbofixinfo` | Auto-fix common `.info` file issues | +| `sbodl` | Download sources and verify `MD5SUM`/`SHA256SUM` from `.info` | +| `pre-commit-sbolint` | Git pre-commit hook — blocks commits that fail `sbolint` | --- ## Version Tracking: nvchecker.toml -Every package in this repo must have an entry in `nvchecker.toml`. +Every package in this repo must have an entry in `.extras/nvchecker.toml`. Example for a GitHub-hosted package: ```toml @@ -182,12 +241,20 @@ to git. Before any `git add`, run from the repo root: find . -type l -delete ``` -Commit conventions: -- One commit per package add or update. -- Message format: - - Add: `<package-name>: add version X.Y.Z` - - Update: `<package-name>: update to X.Y.Z` - - Fix: `<package-name>: fix <short description>` +### Git hook setup + +Both hooks are tracked in the `.extras/hooks/` directory. Install them after cloning: + +```bash +cp .extras/hooks/pre-commit .git/hooks/pre-commit +cp .extras/hooks/post-commit .git/hooks/post-commit +chmod +x .git/hooks/pre-commit .git/hooks/post-commit +``` + +| Hook | Trigger | Purpose | +|------|---------|---------| +| `pre-commit` | Before every commit | Runs `sbolint` on staged packages; blocks commit on errors. Also checks for staged source archives: symlinks are auto-removed, real files block the commit. | +| `post-commit` | After every commit | Offers to create a `SBo/<pkg>.tar.gz` archive for submission | The pre-commit hook runs `sbolint` automatically. If it blocks the commit, fix the reported errors and retry — do not bypass with `SBOLINT=no` unless the user @@ -196,6 +263,13 @@ explicitly instructs it. The post-commit hook may prompt to create an SBo archive. This is interactive and may fail in non-TTY environments — that failure is harmless and can be ignored. +Commit conventions: +- One commit per package add or update. +- Message format: + - Add: `<package-name>: add version X.Y.Z` + - Update: `<package-name>: update to X.Y.Z` + - Fix: `<package-name>: fix <short description>` + --- ## What Requires User Confirmation @@ -206,5 +280,85 @@ Stop and ask before doing any of the following: - Modifying files in more than one package directory - Deleting any file - Bypassing the pre-commit hook (`SBOLINT=no`) -- Adding or removing entries in `nvchecker.toml` +- Adding or removing entries in `.extras/nvchecker.toml` - Any action not covered by the workflows above + +--- + +## Running Test Builds + +The general rule is: **never run builds directly.** Building is the user's +responsibility. + +The one exception is the `test-build-slackbuild` skill, which builds the package +in a Docker container via `sbo-dockerbuild` without touching the host system. +Use it to verify that a SlackBuild completes successfully, especially for new +packages or after significant changes. + +--- + +## Findings + +Repo-specific gotchas discovered during maintenance. Append new entries here +so they are not rediscovered. Each entry names the package, the symptom, the +cause, and the action. + +Each entry carries a `Found` date. Recheck stale entries (roughly >6 months +old) against current `sbolint`/`sbopkglint`/`test-build` behavior before +trusting them, since upstream tooling fixes can retire a false positive. + +### claude-code-bin: do not strip the bun binary + +- Found: 2026-08-15 +- Symptom: `sbopkglint` 20-arch fails with "ELF object(s) not stripped" on + `usr/bin/claude`. +- Cause: the binary is bun-generated; stripping breaks it at runtime. +- Action: leave it unstripped. The `sbopkglint` failure is expected; do not + add a strip pass to the SlackBuild. + +### claude-desktop-bin: OVMF symlinks flagged as broken + +- Found: 2026-08-15 +- Symptom: `sbopkglint` 05-basic-sanity fails with "broken relative symlinks" + for `/usr/share/OVMF/OVMF_{CODE,VARS}{,_4M}.fd`. +- Cause: the symlinks point at `edk2-ovmf-x64` files provided by the + `edk2-ovmf` REQUIRES dep, which is not installed in the lint sandbox. +- Action: keep the symlinks, they are needed at runtime. The failure is a + false positive. + +### llama.cpp-vulkan: sbolint false flag on tag archive URLs + +- Found: 2026-08-15 +- Symptom: `sbolint` errors "github commit URL needs full 40-digit commit + hash in filename" for the `archive/b<N>/llama.cpp-b<N>.tar.gz` DOWNLOAD. +- Cause: `sbolint` misidentifies the short build tag (e.g. `b10437`) as a + commit hash. +- Action: known false flag and the documented exception to Core Rule 4. Run + the normal checks, then commit with `SBOLINT=no`. Do not switch to full + commit hashes. + +### nvchecker: test-build needs --local-deps + +- Found: 2026-08-15 +- Symptom: `test-build --dry-run nvchecker` reports `UNMET-DEP` for + `python3-awesomeversion` and `python3-structlog`. +- Cause: those deps are siblings in this repo, not in the SBo tree. +- Action: run `test-build --local-deps --dry-run nvchecker` first, then + `test-build --local-deps --yes nvchecker`. + +### opencode-bin: sbodl verifies a stale cached file + +- Found: 2026-08-20 +- Symptom: after bumping the version, `sbodl` reports an md5 identical to + the previous release, or a `matches OK` for a tarball that must have + changed. +- Cause: the sbodl download cache is keyed by filename, and opencode's + tarball has no version in its name (`opencode-linux-x64.tar.gz`). The + cache held the old release under that name, so sbodl verified it without + downloading. +- Action: run `sbodl -f` to force a re-download when the cached file may be + stale, then verify the reported md5 differs from the previous release + before updating `.info`. Use `-f` only when a filename-versionless source + could hide a stale cache entry (e.g. after a version bump); do NOT use it + for every `sbodl` call. If `-f` is not available, delete the entry under + `~/sbodl-cache/` and re-run plain `sbodl`. |