Mise en route (ABI C)

Cette page montre comment inclure, lier et versionner libair-base.so depuis un programme C. Pour le modèle d’erreurs, voir Modèle d’erreurs ; pour la propriété mémoire, Propriété mémoire.

1. Inclure le header

Un seul header, committé et faisant autorité :

#include "air_base.h"

Le header est généré depuis le code Rust par cbindgen et committé dans le dépôt (crates/air-base-capi/include/air_base.h). Il porte un avertissement « NE PAS ÉDITER À LA MAIN » : c’est un artefact de contrat, pas un fichier à retoucher. Toute la documentation par-symbole (clauses de propriété, thread-safety, valeurs de retour) y vit déjà en commentaires /// ; Doxygen la rend en HTML + pages man.

Il est #pragma once et compatible C++ (gardes extern "C") : utilisable tel quel depuis un .c comme depuis un .cpp.

2. Lier la bibliothèque

La crate air-base-capi produit une cdylib nommée libair_base.so (artefact de build), liée par -lair_base :

# Depuis la racine du dépôt, après avoir bâti la cdylib :
cargo build -p air-base-capi          # → target/debug/libair_base.so

cc mon_programme.c \
   -I crates/air-base-capi/include \
   -L target/debug -lair_base \
   -Wl,-rpath,target/debug \
   -o mon_programme

-I …/include : pour que #include "air_base.h" soit trouvé.
-L … -lair_base : -lair_base résout libair_base.so à l’édition de liens.
-Wl,-rpath,… : pour qu’à l’exécution le chargeur trouve la lib sans LD_LIBRARY_PATH (pratique en développement ; en production, la lib est installée dans un répertoire standard et porte le soname libair-base.so).

Note de nommage. L’artefact de build est libair_base.so (souligné, ⇒ -lair_base). Le soname installé visé est libair-base.so (tiret), forme publique du projet. Les deux désignent la même bibliothèque ; ne mélangez pas les deux à l’édition de liens (utilisez -lair_base sur l’arbre de build).

3. Versionnement & ABI (ADR-012)

Cette ABI est un contrat stable, garanti 10 ans :

Les discriminants d’enum (AirStatus, AirLogLevel) sont explicites et committés : AIR_STATUS_OK == 0 aujourd’hui le restera. Vous pouvez câbler ces valeurs en dur en confiance.
Le header committé est diffé en CI : aucune dérive d’ABI ne peut passer silencieusement (outillage air-abi-check / air-symver). Un changement incompatible exigerait une nouvelle version majeure de soname.
Les tailles de buffer sont des constantes du header (AIR_UUID_HYPHENATED_LEN, AIR_ID128_HEX_LEN) : utilisez toujours la constante, jamais un littéral, pour rester correct si le format évoluait.

4. Surface disponible (T1 → T3)

Domaine	Fonctions	Détail
Identifiants	`air_uuid_new_v7/v4`, `air_uuid_to_hyphenated`, `air_uuid_parse`, `air_id128_machine_id`, `air_id128_to_hex`, `air_monotonic_id_next`	POD + buffers appelant
Statut	`air_status_message`	chaîne statique (ne pas libérer)
Logging	`air_log_open`/`close`, `air_log_emit`, `air_log_lost_count`, `air_log_fields_new`/`free`/`add`/`add_bytes`	handles opaques (+1 au retour)
Temps	`air_instant_now`, `air_instant_elapsed`, `air_instant_duration_since`, `air_duration_from_secs/millis/nanos`, `air_duration_as_secs_f64`	POD, réentrant

Prochaine étape

Avant d’écrire la moindre ligne « réelle », lisez les deux pages qui conditionnent la correction de votre code :

Modèle d’erreurs — comment tester chaque appel.
Propriété mémoire & cycle de vie — quoi libérer, et avec quelle fonction.

English version: Getting started.