Pour réaliser notre projet nous devons pouvoir nous interfacer en Rust avec la bibliothèque C ZBoss. Le C étant beaucoup plus dangereux que le Rust, et différent, de nombreuses précautions sont à prendre. Cet article recense les outils et les bonnes pratiques à suivre pour interagir avec du code étranger dans notre projet.
Caisses intéressantes
cty
Fournit les types C de base (on ne peut pas utiliser libc pour notre cible).
On a les correspondances suivantes :
| C | cty | Rust (ARM) |
|---|---|---|
| char | c_char | i8 |
| signed char | c_schar | i8 |
| unsigned char | c_uchar | u8 |
| short | c_short | i16 |
| unsigned short | c_ushort | u16 |
| int | c_int | i32 |
| unsigned (int) | c_uint | u32 |
| long | c_long | i32 |
| unsigned long | c_ulong | u32 |
| long long | c_longlong | i64 |
| unsigned long long | c_ulonglong | u64 |
| float | c_float | f32 |
| double | c_double | f64 |
| X | X | bool |
| T * | X | *mut T |
| const T * | X | *const T |
| void * | *mut c_void | *mut c_void |
| const void * | *const c_void | *const c_void |
| size_t | size_t | usize |
| ptrdiff_t | ptrdiff_t | isize |
Bien entendu les types de taille fixe de stdint peuvent être utilisés :
| C (stdint.h) | cty | Rust |
|---|---|---|
| int8_t | int8_t | i8 |
| uint8_t | uint8_t | u8 |
| int16_t | int16_t | i16 |
| uint16_t | uint16_t | u16 |
| uint32_t | uint32_t | u32 |
| int32_t | int32_t | i32 |
| int64_t | int64_t | i64 |
| uint64_t | uint64_t | u64 |
cstr_core
Les chaînes de caractères en Rust ne sont pas construites de la même manière qu’en C : il n’y a pas de caractère nul à la fin, et les caractères nuls sont admis au sein de la chaîne.
cstr_core fourni CStr (et CString si l’allocation est activée) comme chaîne se comportant comme en C.
rust-bindgen
A partir des entêtes C (éventuellement C++) d’une bibliothèque, génère les prototypes et les structures de données à l’interface adaptés à Rust.
Note : la caisse peut être utilisée pour la génération (build script, donc utilisé comme dépendance dans Cargo sous [build.dependencies]), puis enlevée des dépendances pour alléger le projet, ou encore utilisée dans une caisse à part du projet dédiée aux bindings.
Attributs utiles
#[link(name = « ext_library »)]
Indique au compilateur que les fonctions d’un bloc extern sont à lier à la bibliothèque donnée.
Exemple :
#[link(name = "git2")]
extern "C" {
pub fn git_libgit2_init() -> c_int;
pub fn git_libgit2_shutdown() -> c_int;
. . .
}#[repr(C)]
Force l’agencement en mémoire d’une structure à suivre les règles du C (ordre des champs, espacement entre les champs, alignement)
#[repr(C)]
pub struct git_error {
pub message: *const c_char,
pub klass: c_int,
}#repr(align(n))
Force l’alignement sur n bytes, n doit être une puissance de 2.
#[no_mangle]
Empêche le mangling par défaut du symbole, utile pour aider le linker à retrouver les symboles en multi-langage.
Techniques et bonnes pratiques
Unsafe et contrat
Lorsqu’une fonction ou un trait sont déclarés comme unsafe il est impératif de documenter le contrat d’utilisation, c’est-à-dire de préciser le cadre d’utilisation pour ne pas avoir de comportement indéfini.
Exemple dans la bibliothèque standard : la fonction Vec::get_unchecked :
pub unsafe fn get_unchecked<I>(&self, index: I) -> &I::Output
where
I: SliceIndex<Self>,
{
// SAFETY: the caller must uphold most of the safety requirements for `get_unchecked`;
// the slice is dereferencable because `self` is a safe reference.
// The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is.
unsafe { &*index.get_unchecked(self) }
}Ce contrat est essentiel car s’il est violé, cela peut introduire des comportements indéfinis dans du code Rust supposé sûr.
Utiliser une variable globale externe en Rust
Utiliser static dans le bloc extern lié à la bibliothèque externe :
#[link(name = "readline")]
extern {
static rl_readline_version: libc::c_int;
}Utiliser une fonction C en Rust
On déclare la fonction dans un bloc extern "C". Tous les appels à celle-ci sont nécessairement unsafe.
La déclaration en C :
// header.h
int git_libgit2_init();Le code Rust :
// main.rs
extern "C" {
pub fn git_libgit2_init() -> c_int;
}
fn main() {
unsafe {
git_libgit2_init();
};
}Fonctions variadiques
On peut utiliser les fonctions variadiques du C en Rust :
extern {
fn foo(x: i32, ...);
}
fn main() {
unsafe {
foo(10, 20, 30, 40, 50);
}
}Utiliser une fonction Rust en C
On utilise #[no_mangle] et extern "C" comme vu précédemment.
#[no_mangle]
pub extern "C" fn magic_number() -> c_int {
42
}Et on ajoute bien évidemment du côté C :
extern int magic_number();Panique
A l’extérieur de Rust, les paniques causent un comportement indéfini, il faut donc les éviter. S’il faut quand même paniquer, utiliser catch_unwind.
Pointeur nul
Beaucoup de types Rust ne peuvent pas être nuls, notamment les références et les pointeurs de fonction. Ce n’est en revanche pas le cas en C. Le langage Rust donne une approche simple pour s’interfacer avec le C dans cette situation : pour faire simple, utiliser une Option. La structure sera bien optimisée avec None correspondant à la valeur nulle et Some correspondant à la valeur non-nulle.
| C | Rust |
|---|---|
int (*)(int) | Option<extern "C" fn(c_int) -> c_int> |
| data_t * | Option<*mut data_t> |
Libération de la mémoire
On utilise le trait Drop pour appeler les fonctions étrangères qui conviennent à la libération de la mémoire.
Exemple :
impl Drop for Repository {
fn drop(&mut self) {
unsafe {
raw::git_repository_free(self.raw);
}
}
}Structure opaque
Si les entêtes en C décrivent un type opaque :
typedef struct Foo Foo;Ou bien en argument de fonction :
void bar(void *foo);Alors on utilise dans le code Rust :
#[repr(C)] pub struct Foo { _private: [u8; 0] }
extern "C" {
pub fn bar(arg: *mut Foo);
}On manipulera donc uniquement ces structures avec des pointeurs bruts.