|
| 1 | +## Adding dependencies from crates.io |
| 2 | + |
| 3 | +[crates.io] is the Rust community's central repository that serves |
| 4 | +as a location to discover and download packages. `cargo` is configured to use |
| 5 | +it by default to find requested packages. |
| 6 | + |
| 7 | +To depend on a library hosted on [crates.io], add it to your `Cargo.toml`. |
| 8 | + |
| 9 | +[crates.io]: https://crates.io/ |
| 10 | + |
| 11 | +### Adding a dependency |
| 12 | + |
| 13 | +If your `Cargo.toml` doesn't already have a `[dependencies]` section, add that, |
| 14 | +then list the crate name and version that you would like to use. This example |
| 15 | +adds a dependency of the `time` crate: |
| 16 | + |
| 17 | +```toml |
| 18 | +[dependencies] |
| 19 | +time = "0.1.12" |
| 20 | +``` |
| 21 | + |
| 22 | +The version string is a [semver] version requirement. The [specifying |
| 23 | +dependencies](03-01-specifying-dependencies.html) docs have more information about |
| 24 | +the options you have here. |
| 25 | + |
| 26 | +[semver]: https://github.com/steveklabnik/semver#requirements |
| 27 | + |
| 28 | +If we also wanted to add a dependency on the `regex` crate, we would not need |
| 29 | +to add `[dependencies]` for each crate listed. Here's what your whole |
| 30 | +`Cargo.toml` file would look like with dependencies on the `time` and `regex` |
| 31 | +crates: |
| 32 | + |
| 33 | +```toml |
| 34 | +[package] |
| 35 | +name = "hello_world" |
| 36 | +version = "0.1.0" |
| 37 | +authors = [ "Your Name <[email protected]>"] |
| 38 | + |
| 39 | +[dependencies] |
| 40 | +time = "0.1.12" |
| 41 | +regex = "0.1.41" |
| 42 | +``` |
| 43 | + |
| 44 | +Re-run `cargo build`, and Cargo will fetch the new dependencies and all of |
| 45 | +their dependencies, compile them all, and update the `Cargo.lock`: |
| 46 | + |
| 47 | +```shell |
| 48 | +$ cargo build |
| 49 | + Updating registry `https://github.com/rust-lang/crates.io-index` |
| 50 | + Downloading memchr v0.1.5 |
| 51 | + Downloading libc v0.1.10 |
| 52 | + Downloading regex-syntax v0.2.1 |
| 53 | + Downloading memchr v0.1.5 |
| 54 | + Downloading aho-corasick v0.3.0 |
| 55 | + Downloading regex v0.1.41 |
| 56 | + Compiling memchr v0.1.5 |
| 57 | + Compiling libc v0.1.10 |
| 58 | + Compiling regex-syntax v0.2.1 |
| 59 | + Compiling memchr v0.1.5 |
| 60 | + Compiling aho-corasick v0.3.0 |
| 61 | + Compiling regex v0.1.41 |
| 62 | + Compiling hello_world v0.1.0 (file:///path/to/project/hello_world) |
| 63 | +``` |
| 64 | + |
| 65 | +Our `Cargo.lock` contains the exact information about which revision of all of |
| 66 | +these dependencies we used. |
| 67 | + |
| 68 | +Now, if `regex` gets updated, we will still build with the same revision until |
| 69 | +we choose to `cargo update`. |
| 70 | + |
| 71 | +You can now use the `regex` library using `extern crate` in `main.rs`. |
| 72 | + |
| 73 | +``` |
| 74 | +extern crate regex; |
| 75 | +
|
| 76 | +use regex::Regex; |
| 77 | +
|
| 78 | +fn main() { |
| 79 | + let re = Regex::new(r"^\d{4}-\d{2}-\d{2}$").unwrap(); |
| 80 | + println!("Did our date match? {}", re.is_match("2014-01-01")); |
| 81 | +} |
| 82 | +``` |
| 83 | + |
| 84 | +Running it will show: |
| 85 | + |
| 86 | +```shell |
| 87 | +$ cargo run |
| 88 | + Running `target/hello_world` |
| 89 | +Did our date match? true |
| 90 | +``` |
0 commit comments