# Coreutils upgrade context (AmigaOS 4)

This document summarizes how the existing Coreutils patch stacks are organized in this repository, how they interact with the `gnulib` component, and what that implies for upgrading from the current 5.2-based flow.

---

## 1) What is in this repository

### Coreutils branches tracked by gild

From `coreutils/series`:

- `5.2` → checkout `COREUTILS-5_2_1` (GNU tarball URL points to `coreutils-5.2.1.tar.bz2`)
- `8.27` → checkout `v8.27` (GNU tarball URL points to `coreutils-8.27.tar.xz`)

Patch folders:

- `coreutils/5.2/patches/` (9 patches)
- `coreutils/8.27/patches/` (2 patches)

### Gnulib branch tracked for coreutils 8.27

From `gnulib/series`:

- `for-coreutils-8.27` → checkout `405cd675384221b541b460c43de26d159914fe0a`

Patch folder:

- `gnulib/for-coreutils-8.27/patches/` (2 patches)

Important: this SHA is the same submodule revision removed by `coreutils/8.27/patches/0002-...`.

---

## 2) How gild wiring works here

Gild behavior (from `gild/bin/gild-checkout`):

1. `git checkout <checkout-id> -B <branch>` in `<component>/repo`
2. create `<branch>-base`
3. apply all patches from `../<branch>/patches/*.patch` via `git am`

Implications:

- The patch stack is applied against upstream git checkout IDs (tag/SHA), not against already patched trees.
- `series` third column URL is only used by `gild get` (archive download), not by `gild checkout`.

---

## 3) Current build integration status (very important)

`native-build/makefile` is still pinned to:

- `COREUTILS_VERSION=5.2.1`
- `COREUTILS_SRC_DIR=../coreutils/repo`

The active native packaging flow still builds the checked out coreutils tree with host `ppc-amigaos` and clib2 flags.

Also, `build-gcc.sh` currently executes:

- `gild/bin/gild checkout coreutils 5.2`

and has 8.27 preparation commented out.

So operationally, **5.2 is still the default build path**.

---

## 4) 5.2 patch stack overview (`coreutils/5.2/patches`)

### 0001 (large base port)

`0001-Changes-for-AmigaOS-imported-from-adtools-svn-with-modifications.patch`

- Very large foundational AmigaOS port.
- Adds `lib/amigaos.c` and `lib/amigaos.h`.
- Touches `configure`, `config.hin`, many `lib/*` and `src/*` files.
- Introduces many `#ifdef __amigaos4__` and `__NEWLIB__`/clib-specific code paths.

Notable behavior/themes:

- Path semantics adaptations (e.g. Amiga absolute path handling with `:`).
- Environment handling and startup/shutdown hooks in custom Amiga support code.
- User/group wrappers via `usergroup.library` where applicable.
- Build-system behavior relaxed for mounted-fs detection (warn instead of hard error).
- Various function-level compatibility workarounds in utilities.

### 0002

- Bison 3 compatibility fix in `lib/getdate.y`.

### 0003

- Makes `stty` non-functional on AmigaOS by compiling a stub main that prints “Not implemented!”.

### 0004

- Removes `doc` and `man` from top-level `SUBDIRS` (toolchain/doc generation simplification).

### 0005

- In `src/copy.c`, uses `stat(path)` instead of `fstat(fd)` for AmigaOS4 due to inode behavior mismatch.

### 0006

- Adds `.gitignore` for generated artifacts.

### 0007

- Forces `HAVE_WORKING_READDIR=1` for `__amigaos4__ && __NEWLIB__`.

### 0008

- clib2/rlimit portability tweak in `src/sort.c` (e.g. `RLIMIT_DATA` mapping).

### 0009

- Replaces `config/config.guess` and `config/config.sub` with newer upstream versions (2023 refresh) to support modern hosts (e.g. aarch64 Linux build hosts).

---

## 5) 8.27 patch stack overview (`coreutils/8.27/patches`)

### 0001 (main AmigaOS4 build patch)

`0001-build-Changes-for-AmigaOS4-compile.patch`

Large patch with these key characteristics:

- Adds Amiga installer scripts:
  - `AutoInstall/AutoInstall`
  - `AutoInstall/SubScript`
- Adds `README.os4` with port history notes.
- Adjusts bootstrap flow to use local gnulib checkout:
  - `bootstrap`: sets `use_git=false`
  - `GNULIB_SRCDIR=../../gnulib/repo`
- Modifies `bootstrap.conf` gnulib module list (removes `mkancesdirs`, `mkdir-p`).
- Edits `configure.ac` and `src/local.mk` to reduce/alter optional program set and documentation/man generation flow.
- Many source-level Amiga/clib2 guards in utilities (`cp`, `dd`, `fmt`, `install`, `kill`, `ls`, `od`, `ptx`, `stat`, `stdbuf`, `tee`, etc.).

Most significant technical debt in this patch:

- `src/sort.c` and `src/split.c` are heavily replaced with much older code lineage (headers indicate 2004-era base), i.e. not a minimal forward-port.
- `README.os4` explicitly states sort/split were replaced with old 5.2.1-9 code for porting reasons.

Also notable:

- `README.os4` text mentions “coreutils 8.29 ported to AmigaOS4”, while this stack is under `8.27` and targets tag `v8.27`; this is historical context mismatch and should be treated as a warning sign when rebasing.

### 0002

`0002-build-Remove-submodule-info.patch`

- Removes `.gitmodules` submodule entry and gitlink for `gnulib`.
- This aligns with adtools using external `gnulib/repo` + patched gnulib branch rather than nested submodule handling.

---

## 6) Gnulib patch stack for coreutils 8.27 (`gnulib/for-coreutils-8.27/patches`)

### 0001

- Changes `m4/ls-mntd-fs.m4`:
  - hard error → warning if mounted-fs detection fails
  - forces the success branch in `AS_IF` (explicit AmigaOS4 hack)

### 0002

- Removes `-Wmissing-include-dirs` from `m4/manywarnings.m4` to avoid warning noise/build friction.

---

## 7) Dependency relationship: coreutils 8.27 <-> gnulib stack

For the 8.27 flow, gnulib is not optional. The coreutils patch expects:

- a matching gnulib checkout at `../../gnulib/repo`
- gnulib patches for `for-coreutils-8.27`

Practical checkout/bootstrap order (recommended):

1. `gild/bin/gild checkout gnulib for-coreutils-8.27`
2. `gild/bin/gild checkout coreutils 8.27`
3. `cd coreutils/repo && ./bootstrap`

(Equivalent to commented intent in `build-gcc.sh`, but with gnulib first to avoid bootstrap mismatch.)

---

## 8) Why this matters for an upgrade now

If you want to move away from 5.2:

- The repo already contains an 8.27 attempt, but it is **not** a clean incremental port.
- It includes major historical substitutions (`sort`/`split`) and build-system surgery.
- It depends on a pinned gnulib revision + local gnulib patching.
- Native build scripts still default to 5.2.1, so build integration also needs updating.

In short:

- **5.2 stack** = old but integrated and currently wired into build.
- **8.27 stack** = partially modernized but carries substantial technical debt and cross-component coupling.

---

## 9) Suggested upgrade strategy (context guidance)

For a reliable upgrade path (e.g. newer than 8.27), use this sequence:

1. Keep existing stacks untouched as reference baselines.
2. Start from a clean upstream coreutils tag + matching gnulib baseline.
3. Re-apply only essential AmigaOS deltas first (path handling, environment/runtime, filesystem/mountlist behavior).
4. Avoid large source downgrades (especially `sort`/`split`) unless absolutely required.
5. Move optional utility disablement behind configure checks instead of invasive source replacement where possible.
6. Update `native-build/makefile` only after a validated patched branch exists.
7. Document runtime matrix explicitly (clib2/clib4/newlib support expectations).

---

## 10) Quick reference

- Coreutils series: `coreutils/series`
- Coreutils patches:
  - `coreutils/5.2/patches/`
  - `coreutils/8.27/patches/`
- Gnulib series: `gnulib/series`
- Gnulib patches:
  - `gnulib/for-coreutils-8.27/patches/`
- Build integration currently using 5.2:
  - `native-build/makefile`
  - `build-gcc.sh`