]>
Commit | Line | Data |
---|---|---|
1a4d82fc JJ |
1 | % Hello, Cargo! |
2 | ||
9346a6ac AL |
3 | [Cargo][cratesio] is a tool that Rustaceans use to help manage their Rust |
4 | projects. Cargo is currently in a pre-1.0 state, and so it is still a work in | |
5 | progress. However, it is already good enough to use for many Rust projects, and | |
6 | so it is assumed that Rust projects will use Cargo from the beginning. | |
7 | ||
bd371182 | 8 | [cratesio]: http://doc.crates.io |
1a4d82fc JJ |
9 | |
10 | Cargo manages three things: building your code, downloading the dependencies | |
85aaf69f | 11 | your code needs, and building those dependencies. At first, your |
9346a6ac AL |
12 | program doesn’t have any dependencies, so we’ll only be using the first part of |
13 | its functionality. Eventually, we’ll add more. Since we started off by using | |
1a4d82fc JJ |
14 | Cargo, it'll be easy to add later. |
15 | ||
9346a6ac AL |
16 | If you installed Rust via the official installers you will also have Cargo. If |
17 | you installed Rust some other way, you may want to [check the Cargo | |
18 | README][cargoreadme] for specific instructions about installing it. | |
19 | ||
20 | [cargoreadme]: https://github.com/rust-lang/cargo#installing-cargo-from-nightlies | |
1a4d82fc | 21 | |
c34b1796 AL |
22 | ## Converting to Cargo |
23 | ||
9346a6ac | 24 | Let’s convert Hello World to Cargo. |
1a4d82fc JJ |
25 | |
26 | To Cargo-ify our project, we need to do two things: Make a `Cargo.toml` | |
27 | configuration file, and put our source file in the right place. Let's | |
28 | do that part first: | |
29 | ||
c34b1796 | 30 | ```bash |
1a4d82fc JJ |
31 | $ mkdir src |
32 | $ mv main.rs src/main.rs | |
33 | ``` | |
34 | ||
bd371182 | 35 | Note that since we're creating an executable, we used `main.rs`. If we |
62682a34 SL |
36 | want to make a library instead, we should use `lib.rs`. This convention is required |
37 | for Cargo to successfully compile our projects, but it can be overridden if we wish. | |
bd371182 | 38 | Custom file locations for the entry point can be specified |
62682a34 | 39 | with a [`[lib]` or `[[bin]]`][crates-custom] key in the TOML file. |
bd371182 AL |
40 | |
41 | [crates-custom]: http://doc.crates.io/manifest.html#configuring-a-target | |
42 | ||
1a4d82fc JJ |
43 | Cargo expects your source files to live inside a `src` directory. That leaves |
44 | the top level for other things, like READMEs, license information, and anything | |
45 | not related to your code. Cargo helps us keep our projects nice and tidy. A | |
46 | place for everything, and everything in its place. | |
47 | ||
48 | Next, our configuration file: | |
49 | ||
c34b1796 | 50 | ```bash |
1a4d82fc JJ |
51 | $ editor Cargo.toml |
52 | ``` | |
53 | ||
54 | Make sure to get this name right: you need the capital `C`! | |
55 | ||
56 | Put this inside: | |
57 | ||
58 | ```toml | |
59 | [package] | |
60 | ||
61 | name = "hello_world" | |
62 | version = "0.0.1" | |
63 | authors = [ "Your name <you@example.com>" ] | |
1a4d82fc JJ |
64 | ``` |
65 | ||
62682a34 SL |
66 | This file is in the [TOML][toml] format. TOML is similar to INI, but has some |
67 | extra goodies. According to the TOML docs, | |
1a4d82fc JJ |
68 | |
69 | > TOML aims to be a minimal configuration file format that's easy to read due | |
70 | > to obvious semantics. TOML is designed to map unambiguously to a hash table. | |
71 | > TOML should be easy to parse into data structures in a wide variety of | |
72 | > languages. | |
73 | ||
9346a6ac | 74 | [toml]: https://github.com/toml-lang/toml |
1a4d82fc | 75 | |
62682a34 | 76 | Once you have this file in place, we should be ready to build! To do so, run: |
1a4d82fc | 77 | |
c34b1796 | 78 | ```bash |
1a4d82fc JJ |
79 | $ cargo build |
80 | Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world) | |
c34b1796 | 81 | $ ./target/debug/hello_world |
1a4d82fc JJ |
82 | Hello, world! |
83 | ``` | |
84 | ||
62682a34 | 85 | Bam! We built our project with `cargo build`, and ran it with |
9346a6ac AL |
86 | `./target/debug/hello_world`. We can do both in one step with `cargo run`: |
87 | ||
88 | ```bash | |
89 | $ cargo run | |
90 | Running `target/debug/hello_world` | |
91 | Hello, world! | |
92 | ``` | |
93 | ||
94 | Notice that we didn’t re-build the project this time. Cargo figured out that | |
95 | we hadn’t changed the source file, and so it just ran the binary. If we had | |
96 | made a modification, we would have seen it do both: | |
97 | ||
98 | ```bash | |
bd371182 | 99 | $ cargo run |
9346a6ac AL |
100 | Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world) |
101 | Running `target/debug/hello_world` | |
102 | Hello, world! | |
103 | ``` | |
104 | ||
105 | This hasn’t bought us a whole lot over our simple use of `rustc`, but think | |
62682a34 | 106 | about the future: when our project gets more complex, we need to do more |
9346a6ac | 107 | things to get all of the parts to properly compile. With Cargo, as our project |
62682a34 | 108 | grows, we can just run `cargo build`, and it’ll work the right way. |
9346a6ac AL |
109 | |
110 | When your project is finally ready for release, you can use | |
111 | `cargo build --release` to compile your project with optimizations. | |
1a4d82fc JJ |
112 | |
113 | You'll also notice that Cargo has created a new file: `Cargo.lock`. | |
114 | ||
115 | ```toml | |
116 | [root] | |
117 | name = "hello_world" | |
118 | version = "0.0.1" | |
119 | ``` | |
120 | ||
62682a34 | 121 | The `Cargo.lock` file is used by Cargo to keep track of dependencies in your application. |
9346a6ac | 122 | Right now, we don’t have any, so it’s a bit sparse. You won't ever need |
1a4d82fc JJ |
123 | to touch this file yourself, just let Cargo handle it. |
124 | ||
9346a6ac AL |
125 | That’s it! We’ve successfully built `hello_world` with Cargo. Even though our |
126 | program is simple, it’s using much of the real tooling that you’ll use for the | |
127 | rest of your Rust career. You can expect to do this to get started with | |
128 | virtually all Rust projects: | |
129 | ||
130 | ```bash | |
131 | $ git clone someurl.com/foo | |
132 | $ cd foo | |
133 | $ cargo build | |
134 | ``` | |
1a4d82fc | 135 | |
c34b1796 AL |
136 | ## A New Project |
137 | ||
9346a6ac AL |
138 | You don’t have to go through this whole process every time you want to start a |
139 | new project! Cargo has the ability to make a bare-bones project directory in | |
140 | which you can start developing right away. | |
c34b1796 AL |
141 | |
142 | To start a new project with Cargo, use `cargo new`: | |
143 | ||
144 | ```bash | |
145 | $ cargo new hello_world --bin | |
146 | ``` | |
147 | ||
62682a34 | 148 | We’re passing `--bin` because our goal is to get straight to making an executable application, as opposed to a library. Executables are often called ‘binaries.’ (as in `/usr/bin`, if you’re on a Unix system) |
c34b1796 AL |
149 | |
150 | Let's check out what Cargo has generated for us: | |
151 | ||
152 | ```bash | |
153 | $ cd hello_world | |
154 | $ tree . | |
155 | . | |
156 | ├── Cargo.toml | |
157 | └── src | |
158 | └── main.rs | |
159 | ||
160 | 1 directory, 2 files | |
161 | ``` | |
162 | ||
9346a6ac AL |
163 | If you don't have the `tree` command, you can probably get it from your |
164 | distribution’s package manager. It’s not necessary, but it’s certainly useful. | |
c34b1796 | 165 | |
9346a6ac | 166 | This is all we need to get started. First, let’s check out `Cargo.toml`: |
c34b1796 AL |
167 | |
168 | ```toml | |
169 | [package] | |
170 | ||
171 | name = "hello_world" | |
62682a34 | 172 | version = "0.1.0" |
c34b1796 AL |
173 | authors = ["Your Name <you@example.com>"] |
174 | ``` | |
175 | ||
9346a6ac AL |
176 | Cargo has populated this file with reasonable defaults based off the arguments |
177 | you gave it and your `git` global configuration. You may notice that Cargo has | |
178 | also initialized the `hello_world` directory as a `git` repository. | |
c34b1796 | 179 | |
9346a6ac | 180 | Here’s what’s in `src/main.rs`: |
c34b1796 AL |
181 | |
182 | ```rust | |
183 | fn main() { | |
184 | println!("Hello, world!"); | |
185 | } | |
186 | ``` | |
187 | ||
9346a6ac AL |
188 | Cargo has generated a "Hello World!" for us, and you’re ready to start coding! Cargo |
189 | has its own [guide][guide] which covers Cargo’s features in much more depth. | |
c34b1796 | 190 | |
9346a6ac AL |
191 | [guide]: http://doc.crates.io/guide.html |
192 | ||
193 | Now that you’ve got the tools down, let’s actually learn more about the Rust | |
1a4d82fc JJ |
194 | language itself. These are the basics that will serve you well through the rest |
195 | of your time with Rust. | |
9346a6ac AL |
196 | |
197 | You have two options: Dive into a project with ‘[Learn Rust][learnrust]’, or | |
198 | start from the bottom and work your way up with ‘[Syntax and | |
199 | Semantics][syntax]’. More experienced systems programmers will probably prefer | |
200 | ‘Learn Rust’, while those from dynamic backgrounds may enjoy either. Different | |
201 | people learn differently! Choose whatever’s right for you. | |
202 | ||
203 | [learnrust]: learn-rust.html | |
204 | [syntax]: syntax-and-semantics.html |