Guide ABI C — libair-base.so (vue d’ensemble)

Public : développeurs C (et, à terme, Swift / Python / Ruby via les bindings) qui consomment Air sans écrire de Rust. Ces pages expliquent comment utiliser la bibliothèque et quelles obligations pèsent sur l’appelant — pas seulement quoi appeler.

air-base-capi expose la couche 1 air-base-lib (Rust pur) en ABI C stable, produisant libair-base.so. C’est la première passe ABI C du projet : le banc d’essai de la méthodologie de toute la future « libc Air » (userland Rust, contrats redessinés, propriété mémoire explicite). Décisions de contrat :

• Source unique de vérité : la doc par-symbole naît des commentaires /// du code Rust, reportés par cbindgen dans le header committé include/air_base.h, puis rendus par Doxygen (HTML + pages man). Aucune doc C rédigée à la main, donc zéro dérive (ADR-027).
• Stabilité : le header est un contrat ABI garanti 10 ans, committé et diffé en CI (ADR-012).
• Erreurs : AirStatus in-band, sans errno, panic = "abort" (ADR-045).

Pourquoi une ABI C, et pas seulement du Rust

Le Rust est l’implémentation ; l’ABI C est le contrat universel. Tout langage sait appeler du C. En figeant la frontière en C — types #[repr(C)], statut in-band, propriété explicite — Air devient polyglotte dès le départ sans maintenir N documentations parallèles : un seul header, un seul jeu de garanties.

Les pages de ce guide

1. Mise en route — inclure le header, lier la lib, versionnement/ABI.
2. Modèle d’erreurs (AirStatus) — tester, lire, propager ; pourquoi aucune panic ne traverse l’ABI ; pourquoi pas d’errno.
3. Propriété mémoire & cycle de vie — LE point critique : qui alloue, qui libère, avec quelle fonction. Tableau par symbole.
4. Thread-safety par type — ce qui est appelable depuis quel thread, avec les pièges concrets.
5. Exemples C compilables — UUID, logging, mesure du temps, compilés contre le header committé.

Les trois règles à retenir avant tout

1. Tester chaque retour. Toute fonction rend un AirStatus (ou un pointeur non-NULL pour air_status_message). Un *out n’est écrit que sur AIR_STATUS_OK. Voir Modèle d’erreurs.
2. Règle de propriété uniforme : +1 au RETOUR, +0 en ARGUMENT. Un handle retourné (air_log_open, air_log_fields_new) est possédé par l’appelant → il doit le libérer. Un type passé en argument est emprunté → l’appelé ne le libère ni ne le conserve. Voir Propriété mémoire.
3. Les sorties chaînes utilisent VOTRE buffer. Aucune chaîne n’est allouée par Air en T1/T3 : vous fournissez le buffer (tailles AIR_UUID_HYPHENATED_LEN / AIR_ID128_HEX_LEN) ; trop petit ⇒ AIR_STATUS_BUFFER_TOO_SMALL (jamais de troncature silencieuse). Rien à libérer.

Version anglaise : voir C ABI — overview.