Project

General

Profile

Download (7.77 KB)

Feature #155 » 8.32_CLIB4_PORT_PLAN.md

walkero, 06/18/2026 11:08 PM

 

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)?
(1-1/3)