rustrust-cargosemantic-versioning

What are the semantics of an underspecified exact version pin in Cargo?


Consider an entry in the [dependencies] section of Cargo.toml file as follows:

[dependencies]
thingy = "=1.2"

So, this is a comparison requirement, and it is an "equals" requirement with regards to SemVer, but it is in a way "underspecified", since it lacks a patch version, so it isn't exactly specifying anything though it looks like it does.

So far, with what I've read in the docs, there isn't a clear interpretation. Hypothetically, I could see it being equivalent to any of:

thingy = "1.2.*"

or

thingy = "~1.2"

or maybe even

thingy = "=1.2.0"

In practice, it appears to work like thingy = "~1.2", since in the case of the codebase where I'm seeing this written, the Cargo.lock file shows that the project is using 1.2.1.

Does an underspecified equality comparison requirement in Cargo.toml have well defined semantics? If so, what are they and where are they documented?

I expect that the intention here was to write a tilde requirement, and I plan to replace this unclear entry with a tilde requirement, unless there is some subtle (undocumented?) difference I'm overlooking that gives this syntax a real meaning.


Solution

  • Although it does not seem to be properly documented in the referenced pages, we can look at the semver crate (which the current cargo implementation depends on) implementation, specifically of the Op::Exact operator. It states:

    • =I.J.K — exactly the version I.J.K
    • =I.J — equivalent to >=I.J.0, <I.(J+1).0
    • =I — equivalent to >=I.0.0, <(I+1).0.0

    Update: As said, since Cargo does not document this behavior, one shouldn't rely on it and better use well-formed documented version requirements.