Cargo.toml, dependencias y SEMVER

Una dependencia en Rust no es una versión: es un rango. Cuando escribes serde = "1.0" no reclamas la versión 1.0.0, declaras que aceptas cualquier versión compatible según el versionado semántico y delegas en Cargo la elección concreta. Ese contrato de tres piezas —el manifiesto Cargo.toml, que fija rangos; el resolvedor, que elige dentro de ellos; y el Cargo.lock, que congela el resultado exacto con su checksum— es la maquinaria que vuelve reproducibles compilaciones que penden de miles de crates transitivos. Dominarla es jubilar el «en mi máquina compilaba» para siempre.

El manifiesto y el operador caret implícito

En [dependencies] cada valor de versión es un requisito, no una versión fija. Y el operador por defecto —el que actúa cuando no escribes ninguno— es el caret (^):

[dependencies]
serde = "1.0"                                    # equivale a ^1.0
rand  = { version = "0.9", default-features = false }
regex = { version = "1", features = ["unicode"] }
tokio = { version = "1", features = ["full"] }

La regla del caret cabe en una frase: preserva el dígito distinto de cero situado más a la izquierda. De ahí se deduce todo su comportamiento, que cambia de forma sutil según la versión sea mayor o menor que 1:

• ^1.2.3 equivale a >=1.2.3, <2.0.0: todo lo que comparta la mayor 1.
• ^0.2.3 equivale a >=0.2.3, <0.3.0: con mayor 0, la minor pasa a ser la barrera.
• ^0.0.3 equivale a >=0.0.3, <0.0.4: con dos ceros, solo ese patch exacto.

La lógica es que antes de la 1.0 la API se considera inestable, así que Cargo trata el primer dígito no nulo como si fuera la mayor. Junto al caret existen otros operadores para cuando necesitas control fino:

[dependencies]
a = "~1.2.3"          # tilde: >=1.2.3, <1.3.0, fija la minor
b = "1.2.*"           # comodin: >=1.2.0, <1.3.0
c = ">=1.2, <1.5"     # rango compuesto explicito
d = "=1.2.3"          # exacta: solo 1.2.3, casi siempre mala idea

Fijar con = una versión exacta parece prudente y casi siempre es un error: rompe la unificación —que veremos enseguida— y te aísla de los parches de seguridad. El rango es una virtud del diseño, no un riesgo que haya que neutralizar.

Clases y fuentes de dependencia

Una dependencia no tiene por qué venir de crates.io ni ser toda de la misma clase. Cargo distingue tres tablas según cuándo se usa la dependencia, y admite varias fuentes de dónde sale:

[dependencies]
serde = "1"                                   # de crates.io, el registro por defecto
local = { path = "../local" }                 # de una ruta del disco
axum  = { git = "https://github.com/tokio-rs/axum", tag = "v0.7.0" }

[dev-dependencies]
criterion = "0.5"     # solo para tests, benchmarks y ejemplos

[build-dependencies]
cc = "1"              # solo para el build.rs, se compila para tu maquina

Las [dev-dependencies] no entran en tu binario ni en el árbol de quien te consume: existen solo al probar. Las [build-dependencies] sirven al build script y se compilan para el host, no para el destino. Y una dependencia puede renombrarse con package, útil cuando dos crates chocan de nombre o quieres un alias local:

[dependencies]
serde1 = { package = "serde", version = "1" }

SEMVER: el contrato social de las versiones

El versionado semántico —MAJOR.MINOR.PATCH— es una promesa que el autor firma en cada publicación. Subir la PATCH promete solo correcciones; la MINOR, funcionalidad añadida sin romper lo anterior; la MAJOR, un cambio que puede romper a quien te usa. El caret de Cargo confía en esa promesa: misma mayor, presunción de compatibilidad.

Lo delicado es qué cuenta como «romper» en Rust, y la respuesta es más amplia de lo que intuyes. El capítulo de SemVer del libro de Cargo lo cataloga: añadir una variante a un enum público es un cambio mayor, porque invalida los match exhaustivos de tus usuarios; añadir un método puede romper por inferencia o por colisión con el de un trait. Para eso existe #[non_exhaustive]: marcar así un enum o un struct te reserva el derecho de crecer sin subir la mayor, a cambio de obligar a tus usuarios a un brazo comodín _ =>.

El resolvedor, el lockfile y la convivencia de mayores

Cuando dos crates de tu árbol dependen de rand, el resolvedor intenta unificar: busca una única versión que satisfaga ambos rangos y la comparte. Pero si uno exige ^0.8 y otro ^0.9 —dos mayores incompatibles—, Cargo no se rinde: enlaza las dos a la vez. Coexisten porque, para el compilador, rand 0.8::Rng y rand 0.9::Rng son tipos distintos. Esto disuelve el clásico «infierno de dependencias», pero tiene una arista: si pasas un valor de una a una función de la otra, verás el desconcertante «se esperaba Rng, se encontró Rng».

flowchart TD
APP[Tu binario] --> A[crate a pide rand 0.9]
APP --> B[crate b pide rand 0.9]
APP --> C[crate c pide rand 0.8]
A --> U1[rand 0.9.x unificada]
B --> U1
C --> U2[rand 0.8.x en paralelo]
style U1 fill:#a6e3a1,color:#11111b
style U2 fill:#f9e2af,color:#11111b

El resultado de esa resolución se escribe en Cargo.lock: versión exacta y checksum de cada crate del árbol transitivo. Con el lockfile presente, cargo build no vuelve a resolver, reproduce bit a bit el mismo grafo. La edición 2024 estrena el resolvedor 3, consciente del campo rust-version: nunca elige una versión de dependencia que exija un compilador más nuevo que el mínimo que declaras.

cargo update                              # recalcula el lock dentro de los rangos
cargo update -p serde --precise 1.0.150   # fija una version puntual
cargo tree -d                             # muestra duplicados: dos mayores del mismo crate