Modules

mod geometrie {
    pub fn aire_carre(cote: f64) -> f64 {
        cote * cote
    }

    fn aide_interne() {}          // privé : invisible hors de geometrie

    pub mod cercle {
        pub fn aire(rayon: f64) -> f64 {
            std::f64::consts::PI * rayon * rayon
        }
    }
}

fn main() {
    println!("{}", geometrie::aire_carre(2.0));
    println!("{}", geometrie::cercle::aire(1.0));
    // geometrie::aide_interne();   // ERREUR : function `aide_interne` is private
}

// src/main.rs
mod geometrie;     // dit au compilateur : le module est dans geometrie.rs

fn main() {
    geometrie::aire_carre(2.0);
}

// src/geometrie.rs — pas de `mod geometrie { }` autour : le fichier EST le module
pub fn aire_carre(cote: f64) -> f64 {
    cote * cote
}

Un fichier .rs qui n'est déclaré par aucun mod n'est pas compilé du tout : ses erreurs n'apparaissent même pas.

Disposition 1 (édition 2018+, conseillée)     Disposition 2 (historique)
src/                                          src/
├── main.rs                                   ├── main.rs
├── geometrie.rs        ← mod cercle;         └── geometrie/
└── geometrie/                                    ├── mod.rs      ← mod cercle;
    └── cercle.rs                                 └── cercle.rs

Les deux sont équivalentes pour le compilateur. La première évite d'avoir dix onglets mod.rs ouverts dans l'éditeur ; la seconde garde tout le module dans un seul dossier. Choisis-en une et garde-la dans tout le projet (on ne peut pas avoir à la fois geometrie.rs et geometrie/mod.rs).

#[path = "outils/vieux_code.rs"]
mod compat;

À réserver aux cas particuliers (code généré, fichier partagé entre plusieurs crates).

src/
├── lib.rs
├── auth.rs
├── auth/
│   ├── login.rs
│   └── session.rs
└── forms.rs

// src/lib.rs
pub mod auth;
pub mod forms;

// src/auth.rs
pub mod login;
mod session;          // privé : utilisable dans auth et ses sous-modules seulement

crate
├── auth
│   ├── login
│   └── session   (privé)
└── forms

// src/lib.rs
mod utils;            // déclaration : une seule fois

// src/forms.rs
use crate::utils::nettoyer;   // import : dans chaque fichier qui s'en sert
// mod utils;                 // ERREUR fréquente : chercherait src/forms/utils.rs

// Ces déclarations se trouvent dans un sous-module de crate::auth
// (pub(in ...) doit nommer un ancêtre du module courant).
pub fn partout() {}                 // visible par tous, y compris les autres crates
pub(crate) fn dans_la_crate() {}    // visible dans toute la crate, pas au-dehors
pub(super) fn chez_le_parent() {}   // visible dans le module parent
pub(in crate::auth) fn dans_auth() {}   // visible dans crate::auth et ses descendants
pub(self) fn ici() {}               // équivaut à privé
fn prive() {}

mod interne {
    pub fn outil() {}
}

outil est pub, mais interne est privé : hors de la crate, on ne peut pas l'atteindre (interne::outil n'est pas accessible). La visibilité effective est la plus restrictive sur le chemin. Le compilateur ne se plaint pas : pub sert ici aux autres modules de la crate.

pub mod banque {
    pub struct Compte {
        pub titulaire: String,   // public
        solde: i64,              // privé
    }

    impl Compte {
        pub fn new(titulaire: String) -> Self {
            Self { titulaire, solde: 0 }
        }
        pub fn solde(&self) -> i64 {
            self.solde
        }
    }
}

fn main() {
    let c = banque::Compte::new("Ada".into());
    println!("{}", c.titulaire);     // OK
    println!("{}", c.solde());       // OK par la méthode
    // c.solde = 1_000;              // ERREUR : champ privé
    // banque::Compte { titulaire: "x".into(), solde: 5 };   // ERREUR : impossible à construire hors du module
}

Rendre Compte public ne rend pas ses champs publics. Un seul champ privé oblige les autres modules à passer par un constructeur.

pub mod reseau {
    pub enum Etat {
        Connecte,       // les variantes d'une enum pub sont toutes publiques
        Deconnecte,
    }
}

let e = reseau::Etat::Connecte;

Une enum publique expose toutes ses variantes et toutes leurs données. Pour cacher une représentation, on l'enveloppe dans une struct à champ privé.

// Absolu : depuis la racine de la crate
crate::auth::login::verifier();

// Relatif : depuis le module courant
login::verifier();          // un sous-module du module courant
self::login::verifier();    // idem, explicite

// Relatif au parent
super::forms::valider();
super::super::config();     // deux niveaux plus haut

// Autre crate (dépendance)
serde_json::to_string(&x);
::serde_json::to_string(&x);  // :: force une crate externe en cas d'ambiguïté avec un module local

use std::collections::HashMap;                     // un nom
use std::collections::{HashMap, HashSet};          // plusieurs noms
use std::io::{self, Read, Write};                  // le module lui-même + des éléments
use std::{fmt, collections::BTreeMap};             // imbriqué
use std::fmt::Result as FmtResult;                 // renommer
use std::io::Result as IoResult;
use std::collections::*;                           // tout (glob) : à éviter hors tests et préludes
use crate::auth::login;                            // un module de sa propre crate
use super::Config;                                 // depuis le parent
use self::interne::outil;                          // depuis un sous-module

use std::fmt;
use std::io;

// Écriture 1 : garder le module en préfixe
fn a() -> fmt::Result { Ok(()) }
fn b() -> io::Result<()> { Ok(()) }

// Écriture 2 : renommer à l'import
use std::fmt::Result as FmtResult;
fn c() -> FmtResult { Ok(()) }

use std::io::Write;     // sans cet import, .write_all() n'existe pas

fn ecrire(f: &mut std::fs::File) -> std::io::Result<()> {
    f.write_all(b"bonjour")
}

use std::fmt::Write as _;   // importer le trait sans réserver son nom

Les méthodes d'un trait ne sont appelables que si le trait est en portée. as _ sert quand un autre élément s'appelle déjà Write (par exemple std::io::Write et std::fmt::Write dans le même fichier).

// src/lib.rs
mod forms;
mod auth;

pub use forms::fields::TextField;      // les utilisateurs écrivent ma_lib::TextField
pub use auth::login::{login, logout};

L'organisation interne (forms::fields::...) peut changer sans casser personne : seul le chemin re-exporté fait partie de l'API.

// src/prelude.rs
pub use crate::forms::{Form, TextField};
pub use crate::auth::{login, logout};
pub use crate::Request;

// src/lib.rs
pub mod prelude;

// Chez l'utilisateur
use ma_lib::prelude::*;

C'est ce que fait runique::prelude : un seul import donne accès aux types courants. Réserve le prélude aux éléments vraiment utilisés partout, sinon il entre en conflit avec les noms de l'utilisateur.

// src/lib.rs
pub use sea_orm;          // les utilisateurs écrivent ma_lib::sea_orm::...

À quoi ça sert : l'utilisateur n'a pas à déclarer la dépendance lui-même, et il utilise exactement la version que ta bibliothèque utilise. Sans cela, s'il déclare une autre version, les types de l'une ne sont pas ceux de l'autre.

#[doc(hidden)]
pub mod __interne {
    pub fn utilise_par_les_macros() {}
}

Un élément doit parfois être pub parce qu'une macro l'appelle depuis la crate de l'utilisateur. #[doc(hidden)] le retire de la documentation et signale qu'il n'est pas une API stable.

#[cfg(test)]
mod tests;                   // compilé uniquement pour cargo test

#[cfg(feature = "admin")]
pub mod admin;               // compilé uniquement avec la feature admin

#[cfg(unix)]
mod unix;
#[cfg(windows)]
mod windows;

pub fn additionner(a: i32, b: i32) -> i32 {
    a + b
}

fn interne(x: i32) -> i32 { x * 2 }

#[cfg(test)]
mod tests {
    use super::*;          // importe tout le module parent, y compris le privé

    #[test]
    fn additionne() {
        assert_eq!(additionner(2, 3), 5);
        assert_eq!(interne(2), 4);     // les tests unitaires voient le privé
    }
}

mon_projet/
├── Cargo.toml
└── src/
    ├── lib.rs          ← crate bibliothèque `mon_projet`
    ├── main.rs         ← binaire `mon_projet`
    └── bin/
        ├── import.rs   ← binaire `import`
        └── outil/
            └── main.rs ← binaire `outil` (avec ses propres modules)

cargo run                  # lance main.rs
cargo run --bin import

// src/main.rs
use mon_projet::config::charger;     // on passe par le nom de la crate, pas par crate::

fn main() {
    let c = charger();
}

Un binaire est une crate à part : il ne voit de la bibliothèque que ce qui est pub. Un élément pub(crate) de lib.rs est invisible depuis main.rs ou src/bin/. Pour qu'un outil en ligne de commande l'utilise, il doit être pub.

// Écriture 1 : tout dans main.rs — impossible à tester par les tests d'intégration
// Écriture 2 : logique dans lib.rs, main.rs ne fait que lire les arguments et appeler

// src/main.rs
fn main() {
    let args: Vec<String> = std::env::args().collect();
    if let Err(e) = mon_projet::lancer(&args) {
        eprintln!("{e}");
        std::process::exit(1);
    }
}

La seconde forme permet aux tests (tests/*.rs), aux autres binaires et aux autres projets de réutiliser la logique.

mon_api/
├── Cargo.toml
└── src/
    ├── lib.rs
    ├── main.rs
    ├── models.rs
    ├── models/
    │   ├── user.rs
    │   └── post.rs
    ├── api.rs
    ├── api/
    │   └── routes.rs
    └── database.rs

// src/lib.rs
pub mod models;
pub mod api;
mod database;                         // privé : détail d'implémentation

pub use models::{Post, User};         // API courte
pub use api::routes::configurer;

// src/models.rs
mod post;
mod user;

pub use post::Post;                   // les sous-modules restent privés,
pub use user::User;                   // seuls les types sont exposés

// src/models/user.rs
#[derive(Debug)]
pub struct User {
    pub id: u32,
    pub nom: String,
}

impl User {
    pub fn new(id: u32, nom: impl Into<String>) -> Self {
        Self { id, nom: nom.into() }
    }
}

// src/database.rs
use crate::models::User;

pub(crate) fn sauver(u: &User) {
    println!("sauvegarde de {}", u.nom);
}

// src/api/routes.rs
use crate::database;
use crate::models::User;

pub fn configurer() {
    let u = User::new(1, "Alice");
    database::sauver(&u);
}

// src/main.rs
use mon_api::{configurer, User};

fn main() {
    configurer();
    println!("{:?}", User::new(2, "Bob"));
}

mod a;                    // déclare a (a.rs ou a/mod.rs), une seule fois, dans le parent
mod b { }                 // module en ligne
pub mod c;                // module public

use crate::a::X;          // chemin absolu
use super::Y;             // parent
use self::b::Z;           // sous-module
use std::io::{self, Read};
use std::fmt::Result as FmtResult;
use std::io::Write as _;  // trait en portée, sans réserver le nom
pub use a::X;             // re-export

pub            pub(crate)            pub(super)            pub(in crate::a)
#[cfg(test)] mod tests { use super::*; }
#[cfg(feature = "x")] pub mod x;