]>
Commit | Line | Data |
---|---|---|
2c00a5a8 XL |
1 | # Dependencies |
2 | ||
3 | Most programs have dependencies on some libraries. If you have ever managed | |
4 | dependencies by hand, you know how much of a pain this can be. Luckily, the Rust | |
5 | ecosystem comes standard with `cargo`! `cargo` can manage dependencies for a | |
6 | project. | |
7 | ||
8 | To create a new Rust project, | |
9 | ||
10 | ```sh | |
11 | # A binary | |
83c7162d | 12 | cargo new foo |
2c00a5a8 | 13 | |
2b03887a FG |
14 | # A library |
15 | cargo new --lib bar | |
2c00a5a8 XL |
16 | ``` |
17 | ||
e74abb32 | 18 | For the rest of this chapter, let's assume we are making a binary, rather than |
2c00a5a8 XL |
19 | a library, but all of the concepts are the same. |
20 | ||
e74abb32 | 21 | After the above commands, you should see a file hierarchy like this: |
2c00a5a8 XL |
22 | |
23 | ```txt | |
2b03887a FG |
24 | . |
25 | ├── bar | |
26 | │ ├── Cargo.toml | |
27 | │ └── src | |
28 | │ └── lib.rs | |
29 | └── foo | |
30 | ├── Cargo.toml | |
31 | └── src | |
32 | └── main.rs | |
2c00a5a8 XL |
33 | ``` |
34 | ||
2b03887a FG |
35 | The `main.rs` is the root source file for your new `foo` project -- nothing new there. |
36 | The `Cargo.toml` is the config file for `cargo` for this project. If you | |
2c00a5a8 XL |
37 | look inside it, you should see something like this: |
38 | ||
39 | ```toml | |
40 | [package] | |
41 | name = "foo" | |
42 | version = "0.1.0" | |
43 | authors = ["mark"] | |
44 | ||
45 | [dependencies] | |
46 | ``` | |
47 | ||
e74abb32 | 48 | The `name` field under `[package]` determines the name of the project. This is |
2c00a5a8 XL |
49 | used by `crates.io` if you publish the crate (more later). It is also the name |
50 | of the output binary when you compile. | |
51 | ||
52 | The `version` field is a crate version number using [Semantic | |
53 | Versioning](http://semver.org/). | |
54 | ||
55 | The `authors` field is a list of authors used when publishing the crate. | |
56 | ||
e74abb32 | 57 | The `[dependencies]` section lets you add dependencies for your project. |
2c00a5a8 | 58 | |
e74abb32 | 59 | For example, suppose that we want our program to have a great CLI. You can find |
2c00a5a8 XL |
60 | lots of great packages on [crates.io](https://crates.io) (the official Rust |
61 | package registry). One popular choice is [clap](https://crates.io/crates/clap). | |
62 | As of this writing, the most recent published version of `clap` is `2.27.1`. To | |
63 | add a dependency to our program, we can simply add the following to our | |
fc512014 | 64 | `Cargo.toml` under `[dependencies]`: `clap = "2.27.1"`. And that's it! You can start using |
2c00a5a8 XL |
65 | `clap` in your program. |
66 | ||
83c7162d XL |
67 | `cargo` also supports [other types of dependencies][dependencies]. Here is just |
68 | a small sampling: | |
2c00a5a8 XL |
69 | |
70 | ```toml | |
71 | [package] | |
72 | name = "foo" | |
73 | version = "0.1.0" | |
74 | authors = ["mark"] | |
75 | ||
76 | [dependencies] | |
77 | clap = "2.27.1" # from crates.io | |
78 | rand = { git = "https://github.com/rust-lang-nursery/rand" } # from online repo | |
79 | bar = { path = "../bar" } # from a path in the local filesystem | |
80 | ``` | |
81 | ||
83c7162d XL |
82 | `cargo` is more than a dependency manager. All of the available |
83 | configuration options are listed in the [format specification][manifest] of | |
84 | `Cargo.toml`. | |
85 | ||
2c00a5a8 XL |
86 | To build our project we can execute `cargo build` anywhere in the project |
87 | directory (including subdirectories!). We can also do `cargo run` to build and | |
88 | run. Notice that these commands will resolve all dependencies, download crates | |
89 | if needed, and build everything, including your crate. (Note that it only | |
90 | rebuilds what it has not already built, similar to `make`). | |
91 | ||
92 | Voila! That's all there is to it! | |
83c7162d XL |
93 | |
94 | ||
95 | [manifest]: https://doc.rust-lang.org/cargo/reference/manifest.html | |
96 | [dependencies]: https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html |