Fichiers
ui/doc/adr/ADR-0001-socle-compilation.md
2026-10-11 01:55:22 +02:00

ADR-0001 — Socle de compilation : C++20 bride, absence de libc, double cible

  • Statut : accepte
  • Date : 2026-09-05
  • Portee : chantier 1 (structure du depot, chaine de compilation)

Contexte

Le projet vise un environnement graphique deterministe sur AArch64/Linux, avec trois piliers : determinisme de latence, budget memoire explicite, acces direct justifie. Aucune ligne de code fonctionnel n existe encore. Il faut fixer le socle avant d ecrire quoi que ce soit, sinon les choix se prendront par defaut et par accident.

Decision

1. C++20, bride

Compile avec -std=c++20 -nostdlib -fno-exceptions -fno-rtti -fno-threadsafe-statics -Wall -Wextra -O2.

  • -fno-exceptions : une exception est un chemin de sortie de latence non bornee (deroulement de pile, tables .eh_frame, allocation du bloc d exception). Incompatible avec le pilier 1.
  • -fno-rtti : dynamic_cast et typeid impliquent une comparaison de chaines ou une marche de hierarchie a l execution. Le projet n a aucun polymorphisme dynamique prevu.
  • -fno-threadsafe-statics : sans cette option, chaque variable statique locale non triviale genere un appel a __cxa_guard_acquire — donc une dependance libc et un branchement supplementaire a chaque acces. Le projet n a pas d initialisation statique dynamique (cf. ADR-0003 sur les arenes).
  • -O2 et non -O3 : -O3 active un deroulage et une vectorisation agressifs dont le gain est incertain et le cout en taille de code (donc en pression sur le cache d instructions, donc en variance) est reel. Le projet optimisera par des noyaux assembleur explicites, pas par des drapeaux.
  • -Wall -Wextra avec zero warning tolere. Aucun -Werror en local pour ne pas bloquer un debogage, mais la regle est contractuelle.

Ce qui reste autorise du C++ : constexpr, templates, <type_traits> et les autres en-tetes purement compile-time. Aucun conteneur, aucun std::string, aucun flux.

2. Aucune libc, point d entree maison

Le binaire final est lie avec -nostdlib -nostartfiles -static -Wl,-e,_start. _start est ecrit en assembleur (asm/start.S), appelle une fonction C++ unique, puis termine le processus par exit_group via svc #0.

Raison : le pilier 3. Une libc apporte un initialiseur (__libc_start_main), un allocateur (malloc), des tampons de flux, des gestionnaires TLS et une resolution de symboles dynamique — toutes choses dont le projet ne veut ni le comportement memoire ni la variance. Le cout assume est qu il faut ecrire soi-meme tout ce dont on a besoin : les wrappers syscall (chantier 2), les routines memoire, les conversions numeriques.

Consequence non evidente, notee ici pour memoire : sans crt1.o, il n y a aucun appel aux constructeurs statiques (.init_array). Le projet ne doit donc dependre d aucune initialisation statique non triviale, ou bien _start devra parcourir .init_array explicitement. Le choix actuel est le premier : pas d initialisation statique dynamique du tout.

3. Double cible, asymetrique

  • Cible embarquee aarch64-linux, freestanding : le produit.
  • Cible hote, la machine de developpement : l outillage seul (harnais d oracle du chantier 4, generateurs de references).

La cible hote a le droit d utiliser la libc de l hote. Elle ne produit jamais de binaire livre. Cette asymetrie est deliberee : le harnais doit pouvoir s executer sans telephone, sans affichage et sans emulateur, sinon il ne sera pas execute.

La frontiere est materialisee dans CMakeLists.txt par la liste proj3_portable_sources. Ces unites de compilation sont freestanding par construction et compilees a l identique par les deux cibles ; ce sont les seules partagees. Tout le reste est specifique a une cible et le nom du fichier le dit (page_source_linux.cpp / page_source_host.cpp).

Risque accepte et surveille : une divergence de comportement flottant ou d endianness entre hote x86-64 et cible AArch64 rendrait la comparaison du harnais trompeuse. Les hypotheses correspondantes sont listees dans doc/methode-oracle.md (mode d arrondi IEEE identique, little-endian des deux cotes, pas de x87 80 bits car x86-64 utilise SSE2 pour float/double).

Alternatives ecartees

  • Utiliser une libc minimale (musl, picolibc). Aurait fait gagner du temps au demarrage. Ecartee : elle reintroduit malloc et un initialiseur qu il faudrait ensuite neutraliser un par un, et elle brouille la frontiere que l ADR cherche precisement a etablir.
  • Cible unique aarch64, tests sous qemu-user. Ecartee : ajoute une dependance d emulation au chemin de test le plus frequent. Le harnais doit etre trivial a lancer, sinon il pourrit.
  • Meson ou Makefile a la main. Ecarte : CMake+Ninja donne la cross-compilation par fichier de toolchain et un graphe de dependances correct sans travail supplementaire. Aucun besoin exotique ici.

Consequences

  • Il faut ecrire des wrappers syscall avant tout code utile (chantier 2).
  • Il faut ecrire un allocateur avant tout code de rendu (chantier 3).
  • Toute tentation d appeler memcpy doit etre traitee : -ffreestanding autorise le compilateur a generer des appels a memcpy/memset/ memmove/memcmp meme sans libc. Le projet doit fournir ces quatre symboles lui-meme. C est note comme dette a traiter au moment ou un lien echoue dessus ; a ce jour aucun appel n a ete genere (verifie par llvm-nm -u sur le binaire, qui ne liste aucun symbole indefini).
  • L absence de -Werror repose sur la discipline. Si elle se relache, on l ajoutera.