feat: add compat32ctl for Slackware64 -currentHEADmaster

Manage AlienBOB's compat32 package collection: mirror the -current tree with lftp, verify it against CHECKSUMS.md5, and install/update/remove the 32-bit layer with upgradepkg/removepkg. Includes a man page and a dry-run self-check.

1 files changed, 112 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7f85034
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+# compat32ctl
+
+Install, update and remove AlienBOB's `-compat32` package collection on a
+Slackware64 `-current` system.
+
+On `-current` the multilib capability is built into Slackware's own `gcc` and
+`glibc` packages (added 2024-08-30), so no third-party toolchain replacement is
+needed. What is still required is the layer of 32-bit compatibility packages,
+which this script manages from
+<https://slackware.nl/people/alien/multilib/current>.
+
+## Requirements
+
+- Slackware64 `-current`
+- `lftp` (mirroring), `md5sum` (verification)
+- Slackware `pkgtools` (`upgradepkg`, `removepkg`) for install/update/remove
+- root for any command that modifies the system (`sync` also writes to the
+  default cache directory, so run it as root too; `--dry-run` works unprivileged)
+
+## Usage
+
+```sh
+compat32ctl sync      # download/refresh the package tree and verify checksums
+compat32ctl install   # sync, then install compat32-tools and all -compat32 packages
+compat32ctl update    # same as install (upgradepkg --install-new upgrades existing)
+compat32ctl remove    # remove every installed compat32 package
+
+compat32ctl <command> -n   # dry run: print the commands without executing them
+compat32ctl help
+```
+
+`install` and `update` are the same idempotent flow: `upgradepkg --install-new`
+upgrades packages that are already installed and adds any new ones, so the same
+command serves both first-time setup and later refreshes.
+
+## Configuration
+
+Overridable via environment variables:
+
+| Variable     | Default                                             | Purpose                     |
+|--------------|-----------------------------------------------------|-----------------------------|
+| `REPO_URL`   | `https://slackware.nl/people/alien/multilib/current`| Remote package tree          |
+| `MIRROR_DIR` | `/var/cache/compat32`                               | Local package cache          |
+| `PKGDIR`     | `/var/log/packages`                                 | Installed-package database   |
+
+Example: mirror to a staging directory instead of the system cache:
+
+```sh
+MIRROR_DIR=/srv/compat32 compat32ctl sync
+```
+
+## How it works
+
+- **sync** mirrors the remote tree with `lftp ... mirror -c -e -v` (incremental,
+  resumable, prunes locally deleted/stale files) into `MIRROR_DIR`, then
+  verifies the packages against the repository's `CHECKSUMS.md5` with
+  `md5sum -c --ignore-missing`.
+- **install/update** run `sync`, then
+  `upgradepkg --install-new` over `compat32-tools-*.tgz` and
+  `slackware64-compat32/*-compat32/*.t?z`.
+- **remove** deletes every installed package whose name contains `compat32`
+  (the `-compat32` libraries plus `compat32-tools`). No `gcc`/`glibc` rollback
+  is needed on `-current`, since those are Slackware's own packages.
+
+## Download progress
+
+When run on a terminal, `lftp` shows a live status line for the file being
+transferred (bytes, percentage, rate, ETA), and `mirror -v` prints a
+`Transferring file` line per file. Progress is only shown when the output is a
+terminal; under cron or a non-interactive pipe the transfer is silent.
+
+## Note for slackpkg users
+
+If you use `slackpkg`, add these lines to `/etc/slackpkg/blacklist` so it does
+not remove or replace the multilib packages:
+
+```
+[0-9]+alien
+[0-9]+compat32
+```
+
+## Man page
+
+`compat32ctl.8` documents the script. Install it into section 8 with:
+
+```sh
+install -Dm644 compat32ctl.8 /usr/man/man8/compat32ctl.8
+```
+
+Then read it with `man compat32ctl`.
+
+## Testing
+
+`test_compat32ctl.sh` runs unprivileged and exercises argument handling and the
+`--dry-run` previews, including the remove-discovery logic against a temporary
+package database:
+
+```sh
+./test_compat32ctl.sh
+```
+
+## License
+
+GPL v2.0 (see [LICENSE](LICENSE)).
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.