Imported from fxrobin/docker-m68k-compiler (AGENTS.md). Install upstream with npx skills add fxrobin/docker-m68k-compiler. Copyright stays with the author.

AGENTS.md — docker-m68k-compiler

Vue d'ensemble

Environnement Docker reproductible pour compiler du C en binaires Atari ST (TOS, CPU Motorola 68000). Chaîne : m68k-atari-mint-gcc (paquet cross-mint-essential, PPA vriviere/ppa) sous Ubuntu 20.04. Exemple actuel : src/hello.c → target/build/hello.tos.

Structure

• Dockerfile : image multi-stage (~136 Mo). Stage toolchain (Ubuntu 22.04 + build-essential + cross-mint-essential via PPA vriviere/ppa), stage runtime (Ubuntu 22.04 + make, libmpc3, libmpfr6, libgmp10 + closure mint copiée : /usr/bin/m68k-atari-mint-*, /usr/libexec/gcc/m68k-atari-mint, /usr/lib/gcc/m68k-atari-mint, /usr/m68k-atari-mint). WORKDIR /app, CMD ["/bin/bash"]. Le gcc natif x86_64 et Python (utile uniquement pour add-apt-repository) restent dans le stage builder.
• Makefile : compile tous les src/*.c avec m68k-atari-mint-gcc, objets dans target/obj/, édition de liens vers target/build/hello.tos.
• src/ : sources C à compiler (actuellement hello.c uniquement).
• target/ : artefacts générés (ignoré par git, voir .gitignore). Ne jamais committer.
• Pas de tests, pas de CI, pas de README pour l'instant.

Prérequis

• Docker (build + run).
• Binaire cible : TOS Atari ST sur m68k, pas d'exécution native possible sur l'hôte (émulateur type Hatari requis pour tester).

Commandes

# Construire l'image
docker build -t m68k-compiler .

# Compiler (depuis la racine du projet, monté sur /app)
docker run --rm -v "$PWD:/app" m68k-compiler make

# Compiler via make en local si la toolchain mint est installée sur l'hôte
make

# Nettoyer les artefacts
docker run --rm -v "$PWD:/app" m68k-compiler make clean
# ou en local : make clean

Conventions

• Ajouter un nouveau programme : déposer un .c dans src/. Attention, le TARGET du Makefile est fixe (hello.tos) : si tu ajoutes des sources, tous les .c sont linkés ensemble dans ce seul binaire. Pour des binaires multiples, faire évoluer le Makefile (une cible par source) plutôt que de contourner avec des compilations manuelles.
• Cible : C portable / compatible m68k-atari-mint-gcc. Rester sur du C standard simple (stdio.h vérifié : puts, getchar OK). Éviter les appels système POSIX/Linux (fork, sockets, unistd spécifique) qui n'existent pas sous TOS.
• main en int main(void) avec return 0.
• Binaires TOS : extension .tos, nom en 8.3 majuscules de préférence pour compatibilité (HELLO.TOS).
• Variables du Makefile respectées : CC=m68k-atari-mint-gcc, SRC_DIRECTORY, OBJ_DIRECTORY, BUILD_DIRECTORY, CFLAGS (transmis à la compilation, définissable depuis la ligne de commande).
• Ne pas modifier le Dockerfile sans raison (PPA vriviere/ppa requis pour cross-mint-essential). Historique : base montée de 20.04 à 22.04 car le PPA ne publie plus aucun paquet pour focal (vérifié 2026-09-08 : Packages focal vide, cross-mint-essential présent sur jammy). Toute autre montée de version Ubuntu doit être validée par un docker build complet + une compilation de test.
• Ne jamais committer target/.

Vérification

• Pas de suite de tests. Vérification minimale : make clean && make passe sans warning dans le conteneur.
• Tester l'exécution uniquement via émulateur Atari ST (Hatari) — hors périmètre de ce repo pour l'instant.
• Compiler avec -Wall -Wextra en vérification manuelle avant de livrer : docker run --rm -v "$PWD:/app" m68k-compiler make clean CFLAGS="-Wall -Wextra" all

Pièges connus

• Le TARGET est codé en dur (hello.tos) : renommer/ajouter des programmes exige une mise à jour du Makefile.
• SRCS = $(wildcard ...) : un make sans clean après ajout/suppression de fichier peut laisser des .o orphelins — préférer make clean && make en cas de doute.
• Chemins montés : toujours lancer le conteneur avec -v "$PWD:/app" depuis la racine, sinon make ne trouve pas src/.