tools/¶

Host-side (Mac/PC) utilities for building images and managing disks.

Tool	Purpose
`fput.py`	The everyday transfer tool: copy host files into the standard disk image (`os/run-disk.img`) — several at once, replacing existing names. The emulator mounts that image directly, so a put is live on its next boot; `--board` then clones the image to the FPGA's card via `imgsend`.
`p8xfs.py`	P8XFS disk-image tool — create, boot, put/get/rm/ls/mkdir/tree, and `fsck` disk images (v2 hierarchical, the only format; `rm` tombstones like the on-target FDELETE). `fput.py` is the friendly front end for the transfer case.
`p8img.py`	Convert any image (PNG/JPEG/…) to P8I, the display's own RGB565 format, for BASIC's `IMAGE` statement. Floyd–Steinberg dither by default; `--preview` renders what the panel will show.
`build_rom.sh`	Build the full persistent burn set into `../rom/`: the four control-store EPROM images and the program ROM (the assembled monitor — BASIC is no longer ROM-resident), each as `.bin` + `.hex`. Wired up as `make rom`.
`p8cc_sizes.sh`	Compiler size benchmark: compile every `/bin` C command through the `run.sh` pipeline (`clib.py` → `p8cc.py` → `p8xasm.py`) and print bytes per command plus a TOTAL; `FAIL` rows expose a compiler regression. Save a baseline before a codegen change and `diff` after.
`tierA_rewrite.py`	Hand-asm Tier A pass: rewrites the old byte-by-byte 16-bit idioms in a hand-written source (word moves, word constants, `TAPnL/H` pointer loads, `LDA #</#>` pointer constants, `INC`/`ADD #k`/`DEC` carry chains) into single `MOVW`/`LDW`/`LPWn`/`LDPn`/`INCW`/`ADDW`/`DECW` instructions -- only where the next executed instruction cannot observe the A/flags the old sequence left (`--allow` names callees that ignore A). Dry run by default; `--apply` writes in place. Emits native-parseable shapes only, so byte-identity with the on-target assembler holds. Always run the module's tests after it.
`bin2hex.py`	Convert any binary to Intel HEX for an EEPROM programmer. Importable (`write(data, path, base=0)`) or CLI (`bin2hex.py in.bin out.hex [base]`).
`mkbacklogpdf.py`	Render `../BACKLOG.md` to `../BACKLOG.pdf` — a full, readable render of the live backlog: each section (NEXT/IDEAS/VERIFY/WONT-DO) on its own page, colour-coded `[ ]`/`[x]`/`[~]` markers (kept as bracket tokens so state survives B/W printing), nested items hang-indented, bold/`code`/links inline. Done work lives in `BACKLOG-DONE.md` and is excluded. Needs `reportlab`. The PDF is generated and git-ignored; re-run after the backlog changes.
`mkgitignorepdf.py`	Render `../GITIGNORE-TREE.pdf` — a printable reference of everything git ignores: a count table by location, all tracked `.gitignore` files verbatim, and the complete indented tree of currently-ignored files (runs `git` itself). Needs `reportlab`. The PDF is generated and git-ignored; re-run after the ignore set changes.

Typical use¶

# Build everything an EEPROM programmer needs
cd ../emulator && make rom

# Make a bootable hierarchical OS disk and check it
python3 p8xfs.py create disk.img
python3 p8xfs.py fsck disk.img

# Put files on the standard image (and optionally the real board)
./fput.py notes.txt game.bas          # -> / of os/run-disk.img, replacing
./fput.py photo.p8i --board           # ...then clone the image to the FPGA card

See p8xfs.py --help for the full subcommand list, and GLOSSARY.md for filesystem terms.