diff options
| -rw-r--r-- | docs/superpowers/specs/2026-07-04-buildsystem-page-design.md | 146 |
1 files changed, 146 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-07-04-buildsystem-page-design.md b/docs/superpowers/specs/2026-07-04-buildsystem-page-design.md new file mode 100644 index 0000000..59a07dc --- /dev/null +++ b/docs/superpowers/specs/2026-07-04-buildsystem-page-design.md @@ -0,0 +1,146 @@ +# Slackware project page: Package buildsystem + +Date: 2026-07-04 +Status: approved design, pending spec review + +## Goal + +A new Slackware project page describing the whole slackware64-current package +buildsystem: the QEMU VM it lives in, how the repo is assembled, how the +dependency layer works, how packages are built and published, and the separate +15.0 stable-testing safety net. It is a **system/architecture overview** that +ties the individual tools together and links out to their own pages rather than +re-documenting each tool in depth. + +## Placement and schema + +Reuses the existing Slackware project-page schema (same as the mkhint page): +front-matter + freeform markdown body, thumbnail/header images inferred by +filename, `[menus.main]` under the `slackware` parent. Bilingual EN + IT at +`content/{en,it}/slackware/buildsystem/index.md`. + +Front-matter: + +- `title = "Package buildsystem"` +- `tagline` — one line, "How I build and publish my personal slackware64-current + package repository." (IT: translated) +- `status = "active"` +- `repo_url` — omit. This page describes a system, not a single repo. The body + links the relevant repos inline. (If a canonical repo is wanted later it can + be added; not for the first draft.) +- `tags = ["slackware", "slackrepo", "packaging", "buildsystem"]` (reuse shared + tags taxonomy) +- `[menus.main]` with `parent = "slackware"`, a literal `name` (e.g. "buildsystem"), + and a `weight` after mkhint's 10 (use 20). + +## Images + +Crop from `/usr/share/wallpapers/cyan-02-1600x900.png` (same technique as +mkhint, which cropped from a text-logo wallpaper): + +- `thumbnail.jpg` — 900x600, 3:2, center crop. Hub row image. +- `header.jpg` — 1920x480, wide, center crop. Banner above the title. Source is + 1600 wide, so the 1920-wide header upscales slightly; acceptable. + +Written into both `content/en/slackware/buildsystem/` and +`content/it/slackware/buildsystem/`. + +## Cross-reference policy + +- **mkhint** — existing page. Link to `/slackware/mkhint/` (and `/it/slackware/mkhint/`). +- **slackrepo_setup** — future page planned. Name it, describe it, do not link + yet (page does not exist). Phrase so a link can be added later without rewrite. +- **sbo-batch-tester** — future page planned. Same treatment as slackrepo_setup. +- **repo-html-structure** — future page planned. Mention + link the live site + `https://packages.danix.xyz`. Do not link a page yet. +- **slackrepo** — external upstream tool (not mine). Link + `https://github.com/aclemons/slackrepo` (or idlemoor homepage + `https://idlemoor.github.io/slackrepo/`), describe what it does and how I use + it, no ownership implied. +- **Ponce/slackbuilds**, **my-slackbuilds**, **Slackware-Pentesting-Suite** — + external GitHub repos, linked inline where the assembly step is described: + - `https://github.com/Ponce/slackbuilds` + - `https://github.com/danixland/my-slackbuilds` + - `https://github.com/danixland/Slackware-Pentesting-Suite` +- **manage-packages.sh** — left out. The finish-hook chain is described + generically without naming it. + +## Body structure (pipeline narrative) + +Sections in the order a build actually flows: + +1. **Intro** — what the buildsystem is: a QEMU slackware64-current VM that builds + my personal SlackBuilds repo into installable packages for -current, published + at packages.danix.xyz. One paragraph. + +2. **The VM** — the base is slackware64-current, kept up to date with `slackpkg` + against a local mirror of Slackware's system packages, reached over SSH. It is + isolated so building never disturbs my daily driver. CPU cores and RAM may be + stated (8 cores, ~8 GB). Do not leak hostnames, paths, or other setup details. + +3. **Assembling the repo** (`slackrepo_setup`, future page) — once a week the repo + is regenerated from scratch: clone `Ponce/slackbuilds` and check out the + `current` branch, overlay my two personal repos as squashed git subtrees + (`my-slackbuilds` → `personal/`, `Slackware-Pentesting-Suite` → `pentesting/`), + then **shadow** any upstream package whose directory name collides with a + personal one so my version wins. Links: Ponce, my-slackbuilds, pentesting. + Output: a single local SBo tree at the repo path that slackrepo builds from. + +4. **The -current dependency problem** (`mkhint`, existing page) — SBo SlackBuilds + target Slackware stable; some of their build REQUIRES are phantom on -current + (already shipped as system packages or newer, e.g. `rust-opt`, + `google-go-lang`). slackrepo strips a dep per package with a `.hint` file + carrying `DELREQUIRES`. Hand-writing one per dependent each week is tedious, so + `mkhint -F` sweeps the freshly-regenerated repo and writes/merges the right + `DELREQUIRES` everywhere, from a phantom-dep list. Link mkhint page. + +5. **Building** (`slackrepo`, external) — slackrepo builds packages (and their + deps) from the SBo tree in a clean chroot, tracks upstream git revisions to + detect what needs rebuilding, and produces a repository usable with `slackpkg+`. + A start hook rebases my SBo tree onto upstream before each run so the tree is + current. Link slackrepo GitHub/homepage. + +6. **Publishing** (finish hooks + `repo-html-structure`, future page) — after a + successful build slackrepo's finish-hook chain regenerates the slackpkg+ repo + metadata, builds the styled HTML frontend for the repository, rsyncs it to the + live server, and fires a notification. The frontend (repo-html-structure) wraps + Apache's directory autoindex in themed header/footer chrome. Link + packages.danix.xyz. Describe the hook chain generically (do not name + manage-packages.sh). + +7. **Stable-testing layer** (`sbo-batch-tester`, future page) — a separate, + independent safety net, used only for **packages I authored that I want to + submit to SlackBuilds.org**. SBo targets Slackware stable, but my buildsystem + is -current, so before submitting I need to know a SlackBuild still builds on + 15.0. sbo-batch-tester resolves a SlackBuild's dep tree locally, then builds + and installs every package in a fresh disposable overlay chroot over a clean, + read-only Slackware 15.0 base, catching the current-vs-15.0 drift a -current + build would hide. It does not touch or drive slackrepo; built packages are + throwaway, the point is "does it still build clean on 15.0". Note limit: shares + the host kernel, so kernel-module packages still want a real 15.0 VM. Future + page. + +8. **The weekly rhythm** — short recap tying it into one repeatable cycle: + regenerate the repo (slackrepo_setup) → sweep phantom-dep hints (`mkhint -F`) → + build and publish (slackrepo + hooks) → spot-test against 15.0 + (sbo-batch-tester) as needed. + +9. **actions CTA** — closing note via the `actions` shortcode, mirroring the + mkhint page's ending. `use` and `url` TBD in draft (likely link + packages.danix.xyz or the git server); caption holds a closing line. No em + dashes. + +## Style constraints + +- No em dashes anywhere (global preference). Use commas/periods; colons for + bullet separators as in the mkhint page. +- Match the mkhint page's narrative voice and markdown conventions. +- Facts only. Everything above is grounded in the repo CLAUDE/README files and a + general (non-leaking) inspection of the `buildsystem` host. No invented specs. + +## Build / ship flow (not part of the page) + +Content-only change (markdown + images, no new Tailwind classes) → no CSS +rebuild. `hugo --gc` must exit 0. Draft first, review live locally (`hugo server`), +then ship (commit content repo, push master, merge to production) once approved. +Bilingual EN + IT must both be present before shipping. |