Skip to content

Phase 38 readme plan

Jump to bottom
Simon Dick edited this page Jun 20, 2026 · 3 revisions

Phase 38 — ports/amiga/README.md

Part of the Amiga port design log.

A ports/amiga/README.md that matches the style of the other port READMEs (rp2, stm32, esp32, unix, ...) and is suitable for merging into upstream. The existing Amiga design log is a phase log plus design notes -- valuable for in-port iteration, not the right shape for a casual visitor opening ports/amiga/.

The goal is an upstream-quality ports/amiga/README.md: same shape as the other port READMEs (rp2, stm32, esp32, unix), suitable for a first-time visitor to land in ports/amiga/ and understand what they're looking at. The phase log, testing runbook, and architecture notes live on the wiki rather than in the README.

Design and rationale

Surface

Per the upstream-README convention:

  • Heading — MicroPython port to AmigaOS 3.x with an ==== underline.
  • Intro paragraph — what the port is (AmigaOS 3.x / 3.1+, 68020+, bebbo gcc 6.5 toolchain) and how to think about it (it produces a regular AmigaDOS executable; runs from Shell or Workbench).
  • Supported features — bullet list covering REPL line editing, frozen modules, 68k native code emitter, dynamic heap, Pythonic VFS file I/O, AmigaOS APIs (amiga.library, ARexx, Intuition / ASL / icon / catalog wrappers, env-var integration, volume / assign / pattern primitives, persistent REPL history), networking (bsdsocket.library), TLS (AmiSSL v5), urequests.
  • Build instructions — bebbo install pointer, mpy-cross prerequisite, the three variants (standard, 68020fpu, 68040), CI parity via tools/amiga-build.sh.
  • Running / accessing — drop the binary on a real Amiga or Amiberry image, invoke from Shell. Brief Workbench-launch note.
  • Testing — pointer to vamos / Amiberry harness with one-paragraph summaries; full runbook stays on the testing wiki page.
  • Further reading — links to the design / phase-status and testing wiki pages.

Target length is ~150–200 lines (matches stm32's 176, esp8266's 251 -- not as short as rp2's 109, because the AmigaOS surface is broader).

Out of scope

  • Phase-by-phase history (lives in the design log).
  • Detailed test runbook / known-good failures (lives on the testing wiki page).
  • Architecture deep-dives (the trampoline, FD parser, native emitter internals).
  • Build matrix per board — there's only one board (any AmigaOS 3.x machine), so no boards/ subdirectory.
  • Examples directory (examples/amiga/) — separate work if a caller asks. Other ports don't always have one.
  • A "What's new" / changelog — git log is authoritative.
  • Phase plan summaries — the design log already does this.

Status — done

Shipped ports/amiga/README.md (233 lines, within the 150-200 target ±15% once tables and the icon / tooltype reference grew). Sections, in order:

  1. Heading + intro paragraph (AmigaOS 3.x / V37+, 68020+, bebbo gcc, produces a regular AmigaDOS executable).
  2. Supported features — bullet list grouped by area (REPL, native emitter, frozen modules, dynamic heap, VFS file I/O with the standard os surface, os.path, amiga.* API wrappers — library proxy, intuition, asl, icon, catalog — ARexx in/out, volume/assign/match, env-vars, timer.device time, socket, AmiSSL, urequests, platform).
  3. Build variants — table covering standard, 68020fpu, 68040, all three TLS-enabled.
  4. Building — make -C mpy-cross prereq, bebbo install pointer, make, VARIANT= selection, tools/amiga-build.sh Docker mirror, AmiSSL SDK note.
  5. Deploying — C: install, protect rwed, Workbench icons (micropython.info, python_script.info), tooltype reference (SCRIPT= / HEAP= / MAXHEAP= / CON=), emulation note.
  6. Running — Shell invocation, script-as-arg, PROGDIR: on sys.path, Workbench SCRIPT= tooltype.
  7. Testing — vamos + Amiberry one-paragraph each, pointer to the testing wiki page for the full runbook.
  8. Limitations — the native + viper emitter is complete; viper holds only one local in a register (MAX_REGS_FOR_LOCAL_VARS = 1, a perf limit) and ptr16/ptr32 accesses are big-endian like the rest of the machine; AmiSSL runtime requirement; 68000 not supported.
  9. Further reading — links to the design and testing wiki pages.

Verified against the live phase status table: no planned-phase features leaked into the "Supported features" list. Phase 37 (amiga.datatypes) and Phase 39 (extmod opt-ins like time.time(), hashlib.md5/sha1, btree, deflate compress, marshal, websocket/webrepl) all stay off the README — listed under "Limitations" where relevant or simply absent.

Verified against the upstream port-README shape: each port has its own section layout reflecting its platform (unix is shortest at "Building" only; esp32 longest with hardware-setup sections). The Amiga port's Building / Deploying / Running / Testing / Limitations / Further reading shape stays in keeping with the convention; "Deploying" carries the Amiga-specific icon / tooltype / emulation content that doesn't fit elsewhere.

Verified link resolution: all wiki page links and the bebbo gcc external link return HTTP 200.

Deviations from the original step plan (call-outs for the upstream PR moment):

  • The original plan instructed "no sidick/micropython references" in the README. As of the docs migration (the design log and testing runbook moved off-tree to the fork wiki), the "Testing" and "Further reading" sections carry fork-specific URLs (github.com/sidick/micropython/wiki/...). These will need rewriting at the upstream PR moment to whatever the upstream wiki location becomes (or to a generic "the project wiki" reference if a permanent home isn't established).
  • The original plan listed the in-tree files docs/amiga.md and docs/amiga-testing.md as the "Further reading" targets. Those files no longer exist in-tree; they were migrated to the fork wiki (Amiga port design and Amiga port testing), which are the canonical home now.

Implementation / step plan

This is the step-by-step ship plan — how to chunk the work into landable PRs. The sections above answer what and why.

The in-port phase log, testing runbook, and architecture notes live on the wiki (Amiga port design, Amiga port testing) rather than in the README. (The original plan referred to in-tree docs/amiga.md and docs/amiga-testing.md; those files were migrated to the wiki during the docs migration.)

Phasing overview

Step 1: Draft README + cross-link from the design log
                        ↓
                Step 2: Polish + close
# Step Output
1 Initial ports/amiga/README.md draft covering heading, intro, supported-features list, build instructions, deployment, accessing the REPL, and a brief testing pointer. Cross-link from the top of the design log so the in-port doc points new readers at the README first. New README file + one-line link addition.
2 Polish pass: verify the supported-features list against the current phase status table; check every link resolves; align the section headings with the most common other-port shape (Building, Running, Testing); flip Phase 38 → ✅. Final README + status flip.

Step 1 — Draft

Deliverables

A ports/amiga/README.md with the following sections, in order:

  1. MicroPython port to AmigaOS 3.x (heading, ==== underline)
  2. Intro paragraph(s) — what the port is, AmigaOS 3.x / 3.1+ minimum, 68020+ CPU target, what binary it produces, how it launches (Shell or Workbench).
  3. Supported features — bullet list. Group roughly:
    • Core language: dynamic heap, 68k native code emitter, frozen modules, persistent REPL history, line editing, Ctrl+C handling.
    • File system: Pythonic VFS, AmigaDOS path semantics.
    • AmigaOS APIs: amiga.library (proxy + .fd trampoline), amiga.intuition, amiga.asl, amiga.icon, amiga.catalog, ARexx (in / out / RexxClient), env-var integration, volume / assign introspection, AmigaDOS pattern matching, timer.device -backed time.
    • Networking: socket via bsdsocket.library.
    • TLS: AmiSSL v5 (variant-gated).
    • urequests frozen HTTP/HTTPS client.
    • platform.amiga_info() and platform.* identity.
    • os / os.path: standard surface plus chmod / getprotect / FIBF_* / makedirs / walk / AmigaOS-aware path helpers.
  4. Building — bebbo gcc 6.5 toolchain pointer (link to bebbo's GitHub), make -C mpy-cross prerequisite, cd ports/amiga && make, the three variants and how to select via VARIANT=. Mention tools/amiga-build.sh as the CI-mirror Docker route for portability.
  5. Deploying — copy the binary to an Amiga drive; protect the bits; on Amiberry, drop into a hard-file mount. One paragraph each.
  6. Accessing the REPL — invoke from Shell (micropython or micropython script.py); brief Workbench-launch note (double-click; output via tooltype SCRIPT=).
  7. Testing — vamos (host, headless) and Amiberry (full emulation) one-paragraph each, pointing to the testing wiki page for the full runbook.
  8. Further reading — short link list: the design log (design and phase status), the testing runbook.

Implementation notes

  • Match the style of ports/rp2/README.md and ports/stm32/README.md: setext-style ==== underline for the H1, ---- for H2, plain markdown otherwise. Code blocks use ``` fences; shell prompts as $.
  • Don't reference Phase numbers in the README -- those are internal to the design log. The README describes the port as it exists now, not the path that got us there.
  • Don't repeat what the testing runbook already covers; point to it instead.
  • A "Limitations" subsection is welcome but should be terse and factual (e.g. "No @micropython.native try/except; no @micropython.viper multi-register locals — both bounded by the 68k emitter rework"). Detail belongs in the design log.

Verification

Open the file in a Markdown renderer; check every link resolves; read it top-to-bottom from the perspective of someone who has never seen the port before and ask "could I build this in 30 minutes?"

Step 2 — Polish + close

Deliverables

  • Re-check the supported-features list against the live phase status table in the design log (anything still planned should stay off the README's "what it has today" list).
  • Cross-link from the design log's Overview to ports/amiga/README.md so the in-port doc points new readers at the README first.
  • Phase 38 status → ✅.

Verification

  • grep -rn "ports/amiga/README.md" across the docs and ports/amiga/ confirms cross-references are in place.
  • Open both the design log and the new README; the README is the entry point, the design log is the depth.

Cross-cutting concerns

  • No emoji. Other-port READMEs are plain markdown; we match.
  • AmigaShell prompts. When showing a sample, use 1> as the prompt to mirror AmigaDOS conventions (not $).
  • No fork-specific URLs. The README should read as if it's already in upstream -- no sidick/micropython references, no work-in-flight planning-doc links (those are not user-facing). Reference the design log and testing runbook only.
  • Length budget. ~150–200 lines. If a section grows past 30 lines, consider whether it belongs in the design log instead.

Architectural deep-dives — out of scope

  • Architectural deep-dives (trampoline ABI, FD parser, native emitter codegen) — too much for a README.

Files

ports/amiga/README.md                   — the README itself (shipped)

No variant-size impact (documentation only). The step plan that was originally tracked as an in-tree docs/phase38-readme-plan.md lives on this wiki page instead.

Clone this wiki locally