3 <div style="border: 2px solid red; padding:5px;">
4 This guide is a work in progress. Until it is ready, we highly recommend that
5 you read the <a href="tutorial.html">Tutorial</a> instead. This work-in-progress Guide is being
6 displayed here in line with Rust's open development policy. Please open any
7 issues you find as usual.
12 Hey there! Welcome to the Rust guide. This is the place to be if you'd like to
13 learn how to program in Rust. Rust is a systems programming language with a
14 focus on "high-level, bare-metal programming": the lowest level control a
15 programming language can give you, but with zero-cost, higher level
16 abstractions, because people aren't computers. We really think Rust is
17 something special, and we hope you do too.
19 To show you how to get going with Rust, we're going to write the traditional
20 "Hello, World!" program. Next, we'll introduce you to a tool that's useful for
21 writing real-world Rust programs and libraries: "Cargo." Then, we'll show off
22 Rust's features by writing a little program together.
28 The first step to using Rust is to install it! There are a number of ways to
29 install Rust, but the easiest is to use the the `rustup` script. If you're on
30 Linux or a Mac, all you need to do is this (note that you don't need to type
31 in the `$`s, they just indicate the start of each command):
34 $ curl -s http://www.rust-lang.org/rustup.sh | sudo sh
37 (If you're concerned about `curl | sudo sh`, please keep reading. Disclaimer
40 If you're on Windows, please [download this .exe and run
41 it](http://static.rust-lang.org/dist/rust-nightly-install.exe).
43 If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay.
44 Not every programming language is great for everyone. Just pass an argument to
48 $ curl -s http://www.rust-lang.org/rustup.sh | sudo sh -s -- --uninstall
51 If you used the Windows installer, just re-run the `.exe` and it will give you
54 You can re-run this script any time you want to update Rust. Which, at this
55 point, is often. Rust is still pre-1.0, and so people assume that you're using
58 This brings me to one other point: some people, and somewhat rightfully so, get
59 very upset when we tell you to `curl | sudo sh`. And they should be! Basically,
60 when you do this, you are trusting that the good people who maintain Rust
61 aren't going to hack your computer and do bad things. That's a good instinct!
62 If you're one of those people, please check out the documentation on [building
63 Rust from Source](https://github.com/rust-lang/rust#building-from-source), or
64 [the official binary downloads](http://www.rust-lang.org/install.html). And we
65 promise that this method will not be the way to install Rust forever: it's just
66 the easiest way to keep people updated while Rust is in its alpha state.
68 Oh, we should also mention the officially supported platforms:
70 * Windows (7, 8, Server 2008 R2), x86 only
71 * Linux (2.6.18 or later, various distributions), x86 and x86-64
72 * OSX 10.7 (Lion) or greater, x86 and x86-64
74 We extensively test Rust on these platforms, and a few others, too, like
75 Android. But these are the ones most likely to work, as they have the most
78 Finally, a comment about Windows. Rust considers Windows to be a first-class
79 platform upon release, but if we're honest, the Windows experience isn't as
80 integrated as the Linux/OS X experience is. We're working on it! If anything
81 does not work, it is a bug. Please let us know if that happens. Each and every
82 commit is tested against Windows just like any other platform.
84 If you've got Rust installed, you can open up a shell, and type this:
90 You should see some output that looks something like this:
93 rustc 0.11.0-pre (443a1cd 2014-06-08 14:56:52 -0700)
94 host: x86_64-unknown-linux-gnu
97 If you did, Rust has been installed successfully! Congrats!
99 If not, there are a number of places where you can get help. The easiest is
100 [the #rust IRC channel on irc.mozilla.org](irc://irc.mozilla.org/#rust), which
101 you can access through
102 [Mibbit](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust). Click
103 that link, and you'll be chatting with other Rustaceans (a silly nickname we
104 call ourselves), and we can help you out. Other great resources include [our
105 mailing list](https://mail.mozilla.org/listinfo/rust-dev), [the /r/rust
106 subreddit](http://www.reddit.com/r/rust), and [Stack
107 Overflow](http://stackoverflow.com/questions/tagged/rust).
111 Now that you have Rust installed, let's write your first Rust program. It's
112 traditional to make your first program in any new language one that prints the
113 text "Hello, world!" to the screen. The nice thing about starting with such a
114 simple program is that you can verify that your compiler isn't just installed,
115 but also working properly. And printing information to the screen is a pretty
118 The first thing that we need to do is make a file to put our code in. I like
119 to make a projects directory in my home directory, and keep all my projects
120 there. Rust does not care where your code lives.
122 This actually leads to one other concern we should address: this tutorial will
123 assume that you have basic familiarity with the command-line. Rust does not
124 require that you know a whole ton about the command line, but until the
125 language is in a more finished state, IDE support is spotty. Rust makes no
126 specific demands on your editing tooling, or where your code lives.
128 With that said, let's make a directory in our projects directory.
137 If you're on Windows and not using PowerShell, the `~` may not work. Consult
138 the documentation for your shell for more details.
140 Let's make a new source file next. I'm going to use the syntax `editor
141 filename` to represent editing a file in these examples, but you should use
142 whatever method you want. We'll call our file `hello_world.rs`:
145 $ editor hello_world.rs
148 Rust files always end in a `.rs` extension. If you're using more than one word
149 in your file name, use an underscore. `hello_world.rs` versus `goodbye.rs`.
151 Now that you've got your file open, type this in:
155 println!("Hello, world");
159 Save the file, and then type this into your terminal window:
162 $ rustc hello_world.rs
163 $ ./hello_world # or hello_world.exe on Windows
167 Success! Let's go over what just happened in detail.
175 These two lines define a **function** in Rust. The `main` function is special:
176 it's the beginning of every Rust program. The first line says "I'm declaring a
177 function named `main`, which takes no arguments and returns nothing." If there
178 were arguments, they would go inside the parentheses (`(` and `)`), and because
179 we aren't returning anything from this function, we've dropped that notation
180 entirely. We'll get to it later.
182 You'll also note that the function is wrapped in curly braces (`{` and `}`).
183 Rust requires these around all function bodies. It is also considered good
184 style to put the opening curly brace on the same line as the function
185 declaration, with one space in between.
187 Next up is this line:
190 println!("Hello, world");
193 This line does all of the work in our little program. There are a number of
194 details that are important here. The first is that it's indented with four
195 spaces, not tabs. Please configure your editor of choice to insert four spaces
196 with the tab key. We provide some sample configurations for various editors
197 [here](https://github.com/rust-lang/rust/tree/master/src/etc).
199 The second point is the `println!()` part. This is calling a Rust **macro**,
200 which is how metaprogramming is done in Rust. If it were a function instead, it
201 would look like this: `println()`. For our purposes, we don't need to worry
202 about this difference. Just know that sometimes, you'll see a `!`, and that
203 means that you're calling a macro instead of a normal function. One last thing
204 to mention: Rust's macros are significantly different than C macros, if you've
205 used those. Don't be scared of using macros. We'll get to the details
206 eventually, you'll just have to trust us for now.
208 Next, `"Hello, world"` is a **string**. Strings are a surprisingly complicated
209 topic in a systems programming language, and this is a **statically allocated**
210 string. We will talk more about different kinds of allocation later. We pass
211 this string as an argument to `println!`, which prints the string to the
214 Finally, the line ends with a semicolon (`;`). Rust is an **expression
215 oriented** language, which means that most things are expressions. The `;` is
216 used to indicate that this expression is over, and the next one is ready to
217 begin. Most lines of Rust code end with a `;`. We will cover this in-depth
218 later in the tutorial.
220 Finally, actually **compiling** and **running** our program. We can compile
221 with our compiler, `rustc`, by passing it the name of our source file:
224 $ rustc hello_world.rs
227 This is similar to `gcc` or `clang`, if you come from a C or C++ background. Rust
228 will output a binary executable. You can see it with `ls`:
232 hello_world hello_world.rs
239 hello_world.exe hello_world.rs
242 There are now two files: our source code, with the `.rs` extension, and the
243 executable (`hello_world.exe` on Windows, `hello_world` everywhere else)
246 $ ./hello_world # or hello_world.exe on Windows
249 This prints out our `Hello, world!` text to our terminal.
251 If you come from a dynamically typed language like Ruby, Python, or JavaScript,
252 you may not be used to these two steps being separate. Rust is an
253 **ahead-of-time compiled language**, which means that you can compile a
254 program, give it to someone else, and they don't need to have Rust installed.
255 If you give someone a `.rb` or `.py` or `.js` file, they need to have
256 Ruby/Python/JavaScript installed, but you just need one command to both compile
257 and run your program. Everything is a tradeoff in language design, and Rust has
260 Congratulations! You have officially written a Rust program. That makes you a
261 Rust programmer! Welcome.
263 Next, I'd like to introduce you to another tool, Cargo, which is used to write
264 real-world Rust programs. Just using `rustc` is nice for simple things, but as
265 your project grows, you'll want something to help you manage all of the options
266 that it has, and to make it easy to share your code with other people and
271 [Cargo](http://crates.io) is a tool that Rustaceans use to help manage their
272 Rust projects. Cargo is currently in an alpha state, just like Rust, and so it
273 is still a work in progress. However, it is already good enough to use for many
274 Rust projects, and so it is assumed that Rust projects will use Cargo from the
277 Programmers love car analogies, so I've got a good one for you to think about
278 the relationship between `cargo` and `rustc`: `rustc` is like a car, and
279 `cargo` is like a robotic driver. You can drive your car yourself, of course,
280 but isn't it just easier to let a computer drive it for you?
282 Anyway, Cargo manages three things: building your code, downloading the
283 dependencies your code needs, and building the dependencies your code needs.
284 At first, your program doesn't have any dependencies, so we'll only be using
285 the first part of its functionality. Eventually, we'll add more. Since we
286 started off by using Cargo, it'll be easy to add later.
288 Let's convert Hello World to Cargo. The first thing we need to do to begin using Cargo
289 is to install Cargo. To do this, we need to build it from source. There are no binaries
292 First, let's go back to our projects directory. We don't want Cargo to
299 Next, we need these commands:
302 $ git clone --recursive https://github.com/rust-lang/cargo
305 $ make install # may need sudo or admin permissions
308 The `--recursive` downloads Cargo's own dependencies. You can't use Cargo to
309 fetch dependencies until you have Cargo installed! Also, you will need to have
310 `git` installed. Much of the Rust world assumes `git` usage, so it's a good
311 thing to have around. Please check out [the git
312 documentation](http://git-scm.com/book/en/Getting-Started-Installing-Git) for
313 more on installing `git`.
315 We hope to give Cargo a binary installer, similar to Rust's own, so that
316 this will not be necessary in the future.
318 Let's see if that worked. Try this:
323 build # compile the current project
325 Options (for all commands):
331 If you see this output when you run `cargo`, congrats! Cargo is working. If
332 not, please [open an issue](https://github.com/rust-lang/cargo/issues/new) or
333 drop by the Rust IRC, and we can help you out.
335 Let's move back into our `hello_world` directory now:
338 $ cd .. # move back up into projects
339 $ cd hello_world # move into hello_world
342 To Cargo-ify our project, we need to do two things: Make a `Cargo.toml`
343 configuration file, and put our source file in the right place. Let's
348 $ mv hello_world.rs src/hello_world.rs
351 Cargo expects your source files to live inside a `src` directory. That leaves
352 the top level for other things, like READMEs, licence information, and anything
353 not related to your code. Cargo helps us keep our projects nice and tidy. A
354 place for everything, and everything in its place.
356 Next, our configuration file:
362 Make sure to get this name right: you need the capital `C`!
371 authors = [ "someone@example.com" ]
378 This file is in the [TOML](https://github.com/toml-lang/toml) format. Let's let
379 it explain itself to you:
381 > TOML aims to be a minimal configuration file format that's easy to read due
382 > to obvious semantics. TOML is designed to map unambiguously to a hash table.
383 > TOML should be easy to parse into data structures in a wide variety of
386 TOML is very similar to INI, but with some extra goodies.
388 Anyway, there are two **table**s in this file: `package` and `bin`. The first
389 tells Cargo metadata about your package. The second tells Cargo that we're
390 interested in building a binary, not a library (though we could do both!), as
391 well as what it is named.
393 Once you have this file in place, we should be ready to build! Try this:
397 Compiling hello_world v0.1.0 (file:/home/yourname/projects/hello_world)
398 $ ./target/hello_world
402 Bam! We build our project with `cargo build`, and run it with
403 `./target/hello_world`. This hasn't bought us a whole lot over our simple use
404 of `rustc`, but think about the future: when our project has more than one
405 file, we would need to call `rustc` twice, and pass it a bunch of options to
406 tell it to build everything together. With Cargo, as our project grows, we can
407 just `cargo build` and it'll work the right way.
409 That's it! We've successfully built `hello_world` with Cargo. Even though our
410 program is simple, it's using much of the real tooling that you'll use for the
411 rest of your Rust career.
413 Next, we'll learn more about Rust itself, by starting to write a more complicated
414 program. We hope you want to do more with Rust than just print "Hello, world!"
424 ## Compound Data Types
454 ## Crates and Modules
463 ## Operators and built-in Traits
465 ## Ownership and Lifetimes