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