confusion about dependency versions

[eminence]

I am pretty sure cargo is working as intended, but I'm a bit confused by how Cargo handles dependency versions.

I started a new cargo project, and added regex as a dependency:

[package]
name = "demo"
version = "0.0.1"
authors = ["Andrew Chin <achin@eminence32.net>"]

[dependencies]
regex = "0.1.19"

I picked version 0.1.19 since at the time of this writing, that is the latest version on http://crates.io/

Trying to build (full errors omited for brevity)

achin@bigbox ~/devel/demo $ cargo build
    Updating registry `https://github.com/rust-lang/crates.io-index`
   Compiling regex v0.1.19
/storage/home/achin/.cargo/registry/src/github.com-1ecc6299db9ec823/regex-0.1.19/src/vm.rs:341:49: 341:55 error: type `char` does not implement any method in scope named `next`

error: aborting due to 5 previous errors
Could not compile `regex`.

To learn more, run the command again with --verbose.

I now think "Hm, I wonder if a different version of regex might work", so I make a change to Cargo.toml and try again:

achin@bigbox ~/devel/demo $ cat Cargo.toml 
[package]

name = "demo"
version = "0.0.1"
authors = ["Andrew Chin <achin@eminence32.net>"]

[dependencies]
regex = "0.1.18"

achin@bigbox ~/devel/demo $ cargo clean

achin@bigbox ~/devel/demo $ cargo update
    Updating registry `https://github.com/rust-lang/crates.io-index`
achin@bigbox ~/devel/demo $ cargo build
   Compiling regex v0.1.19

error: aborting due to 5 previous errors
Could not compile `regex`.

I wrote my dependency as 0.1.18, yet Cargo is still trying to build 0.1.19. Since 0.1.19 must be backwards compatible with 0.1.18, I'm guessing that Cargo is assuming that 0.1.19 will work, it automatically gets the latest version.

I discovered I can force a specific version with cargo update -p regex --precise 0.1.18:

achin@bigbox ~/devel/demo $ cargo update -p regex --precise 0.1.18
    Updating registry `https://github.com/rust-lang/crates.io-index`

achin@bigbox ~/devel/demo $ cargo build
   Compiling regex v0.1.18
   Compiling demo v0.0.1 (file:///storage/home/achin/devel/demo)

My first question is: is Cargo doing the expected thing?

My second question is: if Cargo is going to automatically upgrade dependencies to the latest compatible patch release, what would be the point in specifying a version like 0.1.19 instead of 0.1 ?

My third question is: If I'm writing a library with a dependency on a specific patch level, what do I put in my Cargo.toml file to get Cargo to use the specific version that I specified?

(Edit) Forth question: I couldn't find any of these details in any documentation. If I missed it, where should I look?

[eminence]

After poking around some more, I found http://doc.crates.io/crates-io.html which I think answers all my questions (I should use regex = "=0.1.18" in my Cargo.toml file). I admit I saw the document titled "Cargo and crates.io" but dismissed it because I thought "I'm not publishing anything to crates.io so I don't need this document". I was wrong, so this is all just a matter of simple user error, I think.

[dhardy]

Re-opening this because the documentation isn't clear. What I think it should say:

• Except where the major and minor versions are 0.0, the "patch" (third) number is normally ignored.
• Using an equals sign allows exact matching of the version: =0.1.0 will not match 0.1.1.