# Coreutils 8.32 (clib4) port plan

Goal: add a **new parallel port track** for Coreutils **8.32** targeting **AmigaOS4 + clib4**, while keeping existing `5.2` and `8.27` tracks untouched.

---

## 0) Current baseline facts (for planning)

- Existing coreutils tracks:
  - `5.2` (`COREUTILS-5_2_1`)
  - `8.27` (`v8.27`)
- Existing gnulib track tied to 8.27:
  - `for-coreutils-8.27` @ `405cd675...`
- Upstream Coreutils `v8.32` exists.
- In upstream `v8.32`, `gnulib` is a submodule at:
  - `d279bc6d9f9323e19ad8c32b6d12ff96dfb0f5ba`
- Native build flow currently hardcodes old coreutils version and clib2 flags in `native-build/makefile`.

---

## 1) Add new patch tracks (non-disruptive)

Create new branch entries without changing old ones:

1. `coreutils/series`
   - add:
     - `8.32\tv8.32\thttps://ftp.gnu.org/gnu/coreutils/coreutils-8.32.tar.xz`

2. `gnulib/series`
   - add:
     - `for-coreutils-8.32\td279bc6d9f9323e19ad8c32b6d12ff96dfb0f5ba\t?`

3. create empty patch dirs:
   - `coreutils/8.32/patches/`
   - `gnulib/for-coreutils-8.32/patches/`

Rationale: this keeps 5.2/8.27 intact and enables independent iteration.

---

## 2) Bootstrap + gnulib strategy for 8.32

**Mandatory pairing rule:** coreutils 8.32 must use a matching gnulib baseline for 8.32 (do not reuse the 8.27 gnulib track).

- Baseline to use: gnulib commit `d279bc6d9f9323e19ad8c32b6d12ff96dfb0f5ba` (the submodule commit referenced by upstream coreutils `v8.32`).
- Then apply AmigaOS-specific gnulib patches in the new `for-coreutils-8.32` track.

Use same architecture used in 8.27 track (external gnulib repo), but cleanly for 8.32:

1. Apply a coreutils patch equivalent to 8.27 submodule-removal:
   - remove `.gitmodules` submodule entry and gitlink (`gnulib`).

2. Ensure `bootstrap` uses local gnulib repo path, not network submodule fetch:
   - `use_git=false`
   - `GNULIB_SRCDIR=../../gnulib/repo`

3. In gnulib 8.32 track, port only minimal AmigaOS-related m4 changes needed for configure/bootstrap to succeed:
   - mounted-fs detection behavior (warn/usable path)
   - warning policy only if still necessary.

---

## 3) Build-system enabling for parallel version selection

Do not replace old defaults yet. Add configurable knobs.

In `native-build/makefile`:

1. Add branch/version selector variables for coreutils:
   - e.g. `COREUTILS_BRANCH ?= 5.2`
   - and set `COREUTILS_VERSION` from branch mapping (`5.2.1`, `8.27`, `8.32`).

2. Add libc runtime selector for coreutils build:
   - e.g. `COREUTILS_CRT ?= clib2`
   - for new track use `COREUTILS_CRT=clib4`
   - propagate to `CPPFLAGS/LDFLAGS` as `-mcrt=$(COREUTILS_CRT)`.

3. Keep backward-compatible defaults:
   - existing builds unchanged unless branch/CRT is explicitly set.

4. Add a new documented invocation path for 8.32+clib4.

---

## 4) Patching strategy for 8.32 (clib4-first)

Use a phased approach to avoid importing all 5.2/8.27 debt.

### Phase A — minimal compile/bootstrap viability

1. Coreutils 8.32 base patch:
   - AmigaOS target compile fixes only.
   - disable or exclude fragile/non-essential pieces initially (including `stty`, per your decision).

2. Gnulib 8.32 base patch:
   - only mandatory m4/autoconf behavior fixes needed to configure/build.

3. Confirm `./bootstrap` succeeds with local gnulib track.

### Phase B — functional parity essentials

Port only proven-necessary deltas from prior tracks:

1. `copy.c` `fstat` fallback check:
   - test whether old Amiga inode issue still reproduces under clib4;
   - patch only if needed.

2. path semantics audit:
   - ensure Amiga absolute path rules (`:` and `/`) are handled consistently in key utilities.

3. newlib-specific 5.2 tweaks are **not** default scope now (target is clib4).

### Phase C — runtime cleanup

1. Eliminate clib2-specific assumptions (avoid `__CLIB2__`-locked logic).
2. Keep patches narrow and upstream-structured.
3. Avoid old-code replacement unless a hard blocker appears.

---

## 5) Testing matrix (required before declaring usable)

## Build tests

- `gild checkout gnulib for-coreutils-8.32`
- `gild checkout coreutils 8.32`
- `cd coreutils/repo && ./bootstrap`
- native build with `-mcrt=clib4`

## Runtime smoke tests (AmigaOS4)

Core file ops:
- `cp`, `mv`, `rm`, `install`, `ln`, `readlink`, `realpath`, `stat`, `ls`

Text/data ops:
- `sort`, `split`, `cut`, `tee`, `dd`, `od`

Environment/shell behavior:
- `env`, `printenv`, `path handling`, temp file behavior

Negative tests:
- permissions edge cases
- missing files / diagnostics

`stty`:
- verify it is disabled intentionally and does not break packaging.

## 5.1) End-state requirement: per-tool test scripts (AmigaOS4)

At the end of this porting effort, we must have an automated test script set that validates **each shipped coreutils tool** on AmigaOS4.

Required outcome:

1. A test harness script (or small runner) that executes all per-tool tests and returns a non-zero code on any failure.
2. One test script per tool (or clearly grouped scripts with explicit per-tool sections) covering at least:
   - command starts and exits correctly,
   - basic expected behavior with normal inputs,
   - at least one error-path/diagnostic check.
3. A generated summary report showing pass/fail per tool.
4. Documentation for how to run the full suite on AmigaOS4.

Minimum acceptance criterion:

- No 8.32 clib4 release candidate is considered ready unless the per-tool AmigaOS4 test suite passes.

## 5.2) Coreutils 8.32 tool list to cover with tests

Test coverage target is based on the upstream `v8.32` utility set (from man pages). The per-tool scripts must cover the shipped tools below:

`arch, b2sum, base32, base64, basename, basenc, cat, chcon, chgrp, chmod, chown, chroot, cksum, comm, cp, csplit, cut, date, dd, df, dir, dircolors, dirname, du, echo, env, expand, expr, factor, false, fmt, fold, groups, head, hostid, hostname, id, install, join, kill, link, ln, logname, ls, md5sum, mkdir, mkfifo, mknod, mktemp, mv, nice, nl, nohup, nproc, numfmt, od, paste, pathchk, pinky, pr, printenv, printf, ptx, pwd, readlink, realpath, rm, rmdir, runcon, seq, sha1sum, sha224sum, sha256sum, sha384sum, sha512sum, shred, shuf, sleep, sort, split, stat, stdbuf, stty, sum, sync, tac, tail, tee, test, timeout, touch, tr, true, truncate, tsort, tty, uname, unexpand, uniq, unlink, uptime, users, vdir, wc, who, whoami, yes`

Notes:

- `stty` is expected to be disabled in this port, but still needs a test that confirms expected disabled behavior.
- `[` (left bracket) should be validated as part of `test` coverage if it is shipped as an alias/hardlink in the final package.

---

## 6) Suggested patch/commit structure

Keep reviewable, layered patches:

1. `coreutils8.32: track scaffolding + series entries`
2. `gnulib8.32: track scaffolding + series entry`
3. `coreutils8.32: remove gnulib submodule references`
4. `coreutils8.32: bootstrap local gnulib wiring`
5. `gnulib8.32: minimal m4 AmigaOS fixes`
6. `coreutils8.32: minimal AmigaOS/clib4 compile fixes`
7. `build: parameterize coreutils branch + CRT`
8. `coreutils8.32: targeted runtime fixes from validation`

---

## 7) Risks to manage

- Dragging 8.27 technical debt into 8.32 (especially large source replacements).
- Hidden clib2 assumptions in previous patches.
- Bootstrap mismatch between chosen coreutils tag and gnulib commit if not pinned correctly.

Mitigation:
- start minimal, test-driven,
- patch only validated failures,
- keep gnulib pin aligned with upstream 8.32 submodule SHA first.

---

## 8) Open confirmations before implementation

Please confirm these before I draft concrete first patches:

1. For 8.32 track, do you want me to keep `sort/split` **upstream 8.32 code** unless proven broken (recommended)?
2. Should docs/man/tests remain excluded initially (like 8.27), or try full default first?
3. Do you want `native-build/makefile` default to remain `5.2 + clib2`, with 8.32+clib4 enabled only via explicit vars (recommended)?