Skip to content

CARGO_LOCK.md

Latest commit

 

History

History
560 lines (406 loc) · 13.5 KB

CARGO_LOCK.md

File metadata and controls

560 lines (406 loc) · 13.5 KB

Cargo.lock - Guide Complet

📋 Table des Matières

  1. Introduction
  2. Qu'est-ce que Cargo.lock ?
  3. Différence avec Cargo.toml
  4. Structure du Fichier
  5. Génération et Mise à Jour
  6. Gestion dans Git
  7. Versions et Résolution de Dépendances
  8. Checksums et Sécurité
  9. FAQ

Introduction

Cargo.lock est un fichier généré automatiquement par Cargo qui verrouille les versions exactes de toutes les dépendances de votre projet. Il garantit que tous les développeurs et tous les environnements de build utilisent exactement les mêmes versions de toutes les bibliothèques.

Points Importants

  • ✅ Généré automatiquement : Cargo crée et met à jour ce fichier
  • ✅ Ne pas éditer manuellement : Le fichier contient un avertissement à ce sujet
  • ✅ Reproductibilité : Garantit des builds reproductibles
  • ✅ Sécurité : Contient des checksums pour vérifier l'intégrité

Qu'est-ce que Cargo.lock ?

Cargo.lock est un fichier de verrouillage des dépendances qui enregistre :

  1. Versions exactes de toutes les dépendances (directes et transitives)
  2. Checksums pour vérifier l'intégrité des téléchargements
  3. Sources des dépendances (crates.io, Git, chemin local, etc.)
  4. Arbre de dépendances complet avec toutes les relations

Exemple de Contenu

[[package]]
name = "egui"
version = "0.27.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "abc123def456..."
dependencies = [
 "egui_derive",
 "epaint",
]

Différence avec Cargo.toml

Cargo.toml (Déclaratif)

Rôle : Déclare les dépendances que vous voulez utiliser

Exemple :

[dependencies]
egui = "0.27"        # Version flexible (0.27.0 à <0.28.0)
serde = "1.0"        # Version flexible (1.0.0 à <2.0.0)

Caractéristiques :

  • ✅ Édité manuellement : Vous modifiez ce fichier
  • ✅ Versions flexibles : Spécifie une plage de versions acceptables
  • ✅ Dépendances directes : Seulement ce que vous déclarez explicitement
  • ✅ Commiter dans Git : Toujours commiter ce fichier

Cargo.lock (Verrouillé)

Rôle : Verrouille les versions exactes utilisées

Exemple :

[[package]]
name = "egui"
version = "0.27.2"   # Version exacte
checksum = "abc123..."

Caractéristiques :

  • ✅ Généré automatiquement : Cargo le crée et le met à jour
  • ✅ Versions exactes : Spécifie la version précise utilisée
  • ✅ Toutes les dépendances : Directes ET transitives (dépendances des dépendances)
  • ⚠️ Commiter selon le type de projet : Voir section "Gestion dans Git"

Structure du Fichier

En-tête

# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
  • Commentaire d'avertissement : Indique que le fichier est généré automatiquement
  • Version du format : Version 4 est le format actuel (depuis Rust 1.68)

Section Package

Chaque dépendance est décrite dans une section [[package]] :

[[package]]
name = "egui"                              # Nom du crate
version = "0.27.2"                        # Version exacte
source = "registry+https://github.com/rust-lang/crates.io-index"  # Source
checksum = "abc123def456..."              # Checksum SHA256
dependencies = [                          # Dépendances de ce package
 "egui_derive",
 "epaint",
]

Champs principaux :

Champ Description Exemple
name Nom du crate "egui"
version Version exacte "0.27.2"
source Source du package "registry+https://..."
checksum Hash SHA256 pour vérification "abc123..."
dependencies Liste des dépendances ["egui_derive"]

Types de Sources

1. Registry (crates.io) :

source = "registry+https://github.com/rust-lang/crates.io-index"

2. Git :

source = "git+https://github.com/user/repo.git#commit_hash"

3. Chemin local :

source = "path+file:///path/to/local/crate"

4. Workspace :

source = "workspace"

Exemple Complet

[[package]]
name = "mini_sheet"
version = "0.1.0"
dependencies = [
 "eframe",
 "egui",
 "serde",
 "serde_json",
 "rfd",
]

[[package]]
name = "eframe"
version = "0.27.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "def456..."
dependencies = [
 "egui",
 "winit",
]

[[package]]
name = "egui"
version = "0.27.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "abc123..."
dependencies = [
 "egui_derive",
 "epaint",
]

Génération et Mise à Jour

Génération Initiale

Cargo.lock est créé automatiquement lors de la première compilation :

cargo build        # Crée Cargo.lock si absent
cargo run          # Crée Cargo.lock si absent
cargo test         # Crée Cargo.lock si absent

Mise à Jour

Cargo met à jour Cargo.lock automatiquement quand :

  1. Vous modifiez Cargo.toml : Ajout/suppression/modification de dépendances
  2. Vous exécutez cargo update : Met à jour les dépendances dans les limites de Cargo.toml
  3. Les dépendances changent : Si une dépendance transitive est mise à jour

Commandes de Mise à Jour

Mettre à jour toutes les dépendances :

cargo update

Mettre à jour une dépendance spécifique :

cargo update -p egui

Mettre à jour uniquement les dépendances directes :

cargo update --precise 0.27.2 -p egui

Forcer la régénération :

rm Cargo.lock
cargo build

Gestion dans Git

Applications Binaires (à COMMITER)

Pour les applications binaires (exécutables, CLI tools) :

✅ COMMITER Cargo.lock

Pourquoi ?

  • Garantit que tous les builds utilisent les mêmes versions
  • Assure la reproductibilité
  • Évite les surprises lors des déploiements

Exemple : MiniSheet est une application, donc Cargo.lock doit être commité.

Bibliothèques (à IGNORER)

Pour les bibliothèques (crates publiées sur crates.io) :

❌ NE PAS COMMITER Cargo.lock

Pourquoi ?

  • Les utilisateurs de votre bibliothèque doivent pouvoir utiliser différentes versions
  • Le verrouillage est géré par les applications qui utilisent votre bibliothèque
  • Évite les conflits de versions

Exception : Si votre bibliothèque a un binaire (exécutable), vous pouvez commiter Cargo.lock pour cet exécutable.

Configuration .gitignore

Pour une application (à commiter) :

# Ne PAS ignorer Cargo.lock pour les applications
# Cargo.lock

Pour une bibliothèque (à ignorer) :

# Ignorer Cargo.lock pour les bibliothèques
Cargo.lock

Vérifier si Cargo.lock est suivi

git ls-files Cargo.lock    # Affiche le fichier s'il est suivi
git check-ignore Cargo.lock  # Affiche la règle si ignoré

Versions et Résolution de Dépendances

Résolution de Versions

Cargo résout les versions en suivant ces règles :

  1. Lire Cargo.toml : Détermine les plages de versions acceptables
  2. Lire Cargo.lock (si présent) : Utilise les versions verrouillées
  3. Résoudre les conflits : Trouve des versions compatibles pour toutes les dépendances
  4. Mettre à jour Cargo.lock : Enregistre les versions choisies

Exemple de Résolution

Cargo.toml :

[dependencies]
egui = "0.27"    # Accepte 0.27.0 à <0.28.0

Cargo résout :

  • egui = "0.27.2" (dernière version compatible)
  • Enregistre dans Cargo.lock

Si Cargo.lock existe déjà :

  • Utilise egui = "0.27.1" (version verrouillée)
  • Ne change pas sauf si vous exécutez cargo update

Gestion des Conflits

Si deux dépendances requièrent des versions incompatibles :

Exemple :

  • crate_a nécessite egui = "0.27"
  • crate_b nécessite egui = "0.28"

Cargo :

  1. Tente de trouver une version compatible
  2. Si impossible, affiche une erreur
  3. Vous devez mettre à jour les dépendances

Checksums et Sécurité

Qu'est-ce qu'un Checksum ?

Un checksum est un hash cryptographique (SHA256) qui vérifie l'intégrité d'un fichier téléchargé.

Rôle dans Cargo.lock

[[package]]
name = "egui"
version = "0.27.2"
checksum = "abc123def456789..."

Fonctions :

  1. Vérification d'intégrité : S'assure que le fichier n'a pas été corrompu
  2. Sécurité : Détecte les modifications malveillantes
  3. Reproductibilité : Garantit que le même contenu est téléchargé

Comment ça Fonctionne

  1. Premier téléchargement :

    • Cargo télécharge le crate depuis crates.io
    • Calcule le SHA256 du fichier
    • Enregistre le checksum dans Cargo.lock

  2. Téléchargements suivants :

    • Cargo télécharge le crate
    • Calcule le SHA256
    • Compare avec le checksum dans Cargo.lock
    • Si différent → erreur (fichier corrompu ou modifié)

Désactiver la Vérification (DÉCONSEILLÉ)

⚠️ Ne faites cela que si vous savez ce que vous faites !

[net]
offline = false

Ou dans ~/.cargo/config.toml :

[net]
git-fetch-with-cli = true

FAQ

Q: Puis-je éditer Cargo.lock manuellement ?

R: Techniquement oui, mais fortement déconseillé. Cargo le régénérera lors de la prochaine compilation et écrasera vos modifications. Utilisez plutôt cargo update ou modifiez Cargo.toml.

Q: Pourquoi Cargo.lock est-il si volumineux ?

R: Il contient :

  • Toutes les dépendances directes ET transitives
  • Les checksums de chaque package
  • Les métadonnées complètes

Pour MiniSheet avec 5 dépendances directes, Cargo.lock peut contenir 100+ dépendances transitives.

Q: Que faire si Cargo.lock est corrompu ?

R:

# Supprimer et régénérer
rm Cargo.lock
cargo build

Q: Dois-je commiter Cargo.lock pour une bibliothèque ?

R: Non, sauf si votre bibliothèque contient aussi un exécutable. Les bibliothèques ne doivent généralement pas commiter Cargo.lock.

Q: Comment forcer la mise à jour d'une dépendance ?

R:

# Mettre à jour une dépendance spécifique
cargo update -p egui

# Mettre à jour toutes les dépendances
cargo update

Q: Que signifie "checksum mismatch" ?

R: Cela signifie que le fichier téléchargé ne correspond pas au checksum enregistré. Causes possibles :

  • Fichier corrompu lors du téléchargement
  • Source compromise (rare)
  • Cache corrompu

Solution :

cargo clean
cargo update
cargo build

Q: Pourquoi y a-t-il plusieurs versions de la même dépendance ?

R: C'est normal ! Différentes dépendances peuvent nécessiter différentes versions d'une même bibliothèque. Cargo les compile séparément et les lie ensemble.

Exemple :

[[package]]
name = "crate_a"
dependencies = ["serde 1.0"]

[[package]]
name = "crate_b"
dependencies = ["serde 1.1"]

Cargo compile serde 1.0 et serde 1.1 séparément.

Q: Comment voir l'arbre de dépendances ?

R:

# Arbre complet
cargo tree

# Arbre pour une dépendance spécifique
cargo tree -p egui

# Arbre inversé (qui dépend de quoi)
cargo tree --invert -p egui

Q: Que faire si Cargo.lock et Cargo.toml sont en conflit ?

R: Cargo résoudra automatiquement lors de la prochaine compilation. Si vous voulez forcer la mise à jour :

cargo update

Q: Peut-on supprimer Cargo.lock ?

R: Oui, mais Cargo le recréera lors de la prochaine compilation. Utile pour :

  • Forcer la résolution des dépendances
  • Corriger un fichier corrompu
  • Réinitialiser les versions

Q: Pourquoi certaines dépendances n'ont pas de checksum ?

R: Les dépendances provenant de :

  • Chemins locaux (path = "...")
  • Workspaces
  • Git (dans certains cas)

N'ont pas de checksum car elles ne sont pas téléchargées depuis un registre.

Commandes Utiles

# Voir l'arbre de dépendances
cargo tree

# Mettre à jour toutes les dépendances
cargo update

# Mettre à jour une dépendance spécifique
cargo update -p egui

# Mettre à jour vers une version précise
cargo update --precise 0.27.2 -p egui

# Voir les dépendances obsolètes
cargo outdated

# Régénérer Cargo.lock
rm Cargo.lock
cargo build

# Vérifier sans compiler
cargo check

# Voir les métadonnées d'un package
cargo metadata

Résumé

Aspect Description
Génération Automatique lors de cargo build
Édition ❌ Ne pas éditer manuellement
Git (Application) ✅ Commiter
Git (Bibliothèque) ❌ Ignorer
Taille Variable (dépend du nombre de dépendances)
Format TOML avec sections [[package]]
Versions Versions exactes (pas de plages)
Sécurité Checksums SHA256 pour vérification

Exemple Pratique : MiniSheet

Pour le projet MiniSheet :

Cargo.toml :

[dependencies]
eframe = "0.27"
egui = "0.27"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
rfd = "0.14"

Cargo.lock contient :

  • Ces 5 dépendances directes
  • ~100+ dépendances transitives (toutes les dépendances de egui, serde, etc.)
  • Checksums pour toutes
  • Versions exactes verrouillées

Action : ✅ Commiter Cargo.lock car MiniSheet est une application binaire.

Dernière mise à jour : 2026-01-20