mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #24244 - steveklabnik:more_editing, r=steveklabnik

Browse Source 
Fill out blank section headers. Copy edit the entire first section.
This commit is contained in:
Manish Goregaokar 2015-04-11 19:04:15 +05:30
commit 8c20c20ef4
8 changed files with 278 additions and 168 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
src/doc/trpl/effective-rust.md
View File

@ -1 +1,8 @@
% Effective Rust
So you’ve learned how to write some Rust code. But there’s a difference between
writing *any* Rust code and writing *good* Rust code.
This section consists of relatively independent tutorials which show you how to
take your Rust to the next level. Common patterns and standard library features
will be introduced. Read these sections in any order of your choosing.

4
src/doc/trpl/getting-started.md
View File

@ -1 +1,5 @@
% Getting Started
This first section of the book will get you going with Rust and its tooling.
First, we’ll install Rust. Then: the classic ‘Hello World’ program. Finally,
we’ll talk about Cargo, Rust’s build system and package manager.

128
src/doc/trpl/hello-cargo.md
View File

@ -1,26 +1,27 @@
% Hello, Cargo!
[Cargo](http://crates.io) is a tool that Rustaceans use to help manage their
Rust projects. Cargo is currently in a pre-1.0 state, just like Rust, and so it
is still a work in progress. However, it is already good enough to use for many
Rust projects, and so it is assumed that Rust projects will use Cargo from the
beginning.
[Cargo][cratesio] is a tool that Rustaceans use to help manage their Rust
projects. Cargo is currently in a pre-1.0 state, and so it is still a work in
progress. However, it is already good enough to use for many Rust projects, and
so it is assumed that Rust projects will use Cargo from the beginning.
[cratesio]: https://doc.crates.io
Cargo manages three things: building your code, downloading the dependencies
your code needs, and building those dependencies. At first, your
program doesn't have any dependencies, so we'll only be using the first part of
its functionality. Eventually, we'll add more. Since we started off by using
program doesn’t have any dependencies, so we’ll only be using the first part of
its functionality. Eventually, we’ll add more. Since we started off by using
Cargo, it'll be easy to add later.
If you installed Rust via the official installers you will also have
Cargo. If you installed Rust some other way, you may want to [check
the Cargo
README](https://github.com/rust-lang/cargo#installing-cargo-from-nightlies)
for specific instructions about installing it.
If you installed Rust via the official installers you will also have Cargo. If
you installed Rust some other way, you may want to [check the Cargo
README][cargoreadme] for specific instructions about installing it.
[cargoreadme]: https://github.com/rust-lang/cargo#installing-cargo-from-nightlies
## Converting to Cargo
Let's convert Hello World to Cargo.
Let’s convert Hello World to Cargo.
To Cargo-ify our project, we need to do two things: Make a `Cargo.toml`
configuration file, and put our source file in the right place. Let's
@ -52,14 +53,9 @@ Put this inside:
name = "hello_world"
version = "0.0.1"
authors = [ "Your name <you@example.com>" ]
[[bin]]
name = "hello_world"
```
This file is in the [TOML](https://github.com/toml-lang/toml) format. Let's let
it explain itself to you:
This file is in the [TOML][toml] format. Let’s let it explain itself to you:
> TOML aims to be a minimal configuration file format that's easy to read due
> to obvious semantics. TOML is designed to map unambiguously to a hash table.
@ -68,10 +64,7 @@ it explain itself to you:
TOML is very similar to INI, but with some extra goodies.
Anyway, there are two *tables* in this file: `package` and `bin`. The first
tells Cargo metadata about your package. The second tells Cargo that we're
interested in building a binary, not a library (though we could do both!), as
well as what it is named.
[toml]: https://github.com/toml-lang/toml
Once you have this file in place, we should be ready to build! Try this:
@ -83,13 +76,32 @@ Hello, world!
```
Bam! We build our project with `cargo build`, and run it with
`./target/debug/hello_world`. This hasn't bought us a whole lot over our simple use
of `rustc`, but think about the future: when our project has more than one
file, we would need to call `rustc` more than once and pass it a bunch of options to
tell it to build everything together. With Cargo, as our project grows, we can
just `cargo build`, and it'll work the right way. When your project is finally
ready for release, you can use `cargo build --release` to compile your crates with
optimizations.
`./target/debug/hello_world`. We can do both in one step with `cargo run`:
```bash
$ cargo run
Running `target/debug/hello_world`
Hello, world!
```
Notice that we didn’t re-build the project this time. Cargo figured out that
we hadn’t changed the source file, and so it just ran the binary. If we had
made a modification, we would have seen it do both:
```bash
$ cargo build
Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world)
Running `target/debug/hello_world`
Hello, world!
```
This hasn’t bought us a whole lot over our simple use of `rustc`, but think
about the future: when our project gets more complex, we would need to do more
things to get all of the parts to properly compile. With Cargo, as our project
grows, we can just `cargo build`, and it’ll work the right way.
When your project is finally ready for release, you can use
`cargo build --release` to compile your project with optimizations.
You'll also notice that Cargo has created a new file: `Cargo.lock`.
@ -100,18 +112,25 @@ version = "0.0.1"
```
This file is used by Cargo to keep track of dependencies in your application.
Right now, we don't have any, so it's a bit sparse. You won't ever need
Right now, we don’t have any, so it’s a bit sparse. You won't ever need
to touch this file yourself, just let Cargo handle it.
That's it! We've successfully built `hello_world` with Cargo. Even though our
program is simple, it's using much of the real tooling that you'll use for the
rest of your Rust career.
That’s it! We’ve successfully built `hello_world` with Cargo. Even though our
program is simple, it’s using much of the real tooling that you’ll use for the
rest of your Rust career. You can expect to do this to get started with
virtually all Rust projects:
```bash
$ git clone someurl.com/foo
$ cd foo
$ cargo build
```
## A New Project
You don't have to go through this whole process every time you want to start a new
project! Cargo has the ability to make a bare-bones project directory in which you
can start developing right away.
You don’t have to go through this whole process every time you want to start a
new project! Cargo has the ability to make a bare-bones project directory in
which you can start developing right away.
To start a new project with Cargo, use `cargo new`:
@ -119,8 +138,8 @@ To start a new project with Cargo, use `cargo new`:
$ cargo new hello_world --bin
```
We're passing `--bin` because we're making a binary program: if we
were making a library, we'd leave it off.
We’re passing `--bin` because we're making a binary program: if we were making
a library, we'd leave it off.
Let's check out what Cargo has generated for us:
@ -135,10 +154,10 @@ $ tree .
1 directory, 2 files
```
If you don't have the `tree` command, you can probably get it from your distro's package
manager. It's not necessary, but it's certainly useful.
If you don't have the `tree` command, you can probably get it from your
distribution’s package manager. It’s not necessary, but it’s certainly useful.
This is all we need to get started. First, let's check out `Cargo.toml`:
This is all we need to get started. First, let’s check out `Cargo.toml`:
```toml
[package]
@ -148,11 +167,11 @@ version = "0.0.1"
authors = ["Your Name <you@example.com>"]
```
Cargo has populated this file with reasonable defaults based off the arguments you gave
it and your `git` global configuration. You may notice that Cargo has also initialized
the `hello_world` directory as a `git` repository.
Cargo has populated this file with reasonable defaults based off the arguments
you gave it and your `git` global configuration. You may notice that Cargo has
also initialized the `hello_world` directory as a `git` repository.
Here's what's in `src/main.rs`:
Here’s what’s in `src/main.rs`:
```rust
fn main() {
@ -160,9 +179,20 @@ fn main() {
}
```
Cargo has generated a "Hello World!" for us, and you're ready to start coding! A
much more in-depth guide to Cargo can be found [here](http://doc.crates.io/guide.html).
Cargo has generated a "Hello World!" for us, and you’re ready to start coding! Cargo
has its own [guide][guide] which covers Cargo’s features in much more depth.
Now that you've got the tools down, let's actually learn more about the Rust
[guide]: http://doc.crates.io/guide.html
Now that you’ve got the tools down, let’s actually learn more about the Rust
language itself. These are the basics that will serve you well through the rest
of your time with Rust.
You have two options: Dive into a project with ‘[Learn Rust][learnrust]’, or
start from the bottom and work your way up with ‘[Syntax and
Semantics][syntax]’. More experienced systems programmers will probably prefer
‘Learn Rust’, while those from dynamic backgrounds may enjoy either. Different
people learn differently! Choose whatever’s right for you.
[learnrust]: learn-rust.html
[syntax]: syntax-and-semantics.html

132
src/doc/trpl/hello-world.md
View File

@ -1,9 +1,9 @@
% Hello, world!
Now that you have Rust installed, let's write your first Rust program. It's
Now that you have Rust installed, let’s write your first Rust program. It’s
traditional to make your first program in any new language one that prints the
text "Hello, world!" to the screen. The nice thing about starting with such a
simple program is that you can verify that your compiler isn't just installed,
text “Hello, world!” to the screen. The nice thing about starting with such a
simple program is that you can verify that your compiler isn’t just installed,
but also working properly. And printing information to the screen is a pretty
common thing to do.
@ -12,38 +12,37 @@ to make a `projects` directory in my home directory, and keep all my projects
there. Rust does not care where your code lives.
This actually leads to one other concern we should address: this guide will
assume that you have basic familiarity with the command line. Rust does not
require that you know a whole ton about the command line, but until the
language is in a more finished state, IDE support is spotty. Rust makes no
specific demands on your editing tooling, or where your code lives.
assume that you have basic familiarity with the command line. Rust itself makes
no specific demands on your editing tooling, or where your code lives. If you
prefer an IDE to the command line, you may want to check out
[SolidOak][solidoak], or wherever plugins are for your favorite IDE. There are
a number of extensions of varying quality in development by the community. The
Rust team also ships [plugins for various editors][plugins]. Configuring your
editor or IDE is out of the scope of this tutorial, so check the documentation
for your setup, specifically.
With that said, let's make a directory in our projects directory.
[solidoak]: https://github.com/oakes/SolidOak
[plugins]: https://github.com/rust-lang/rust/blob/master/src/etc/CONFIGS.md
```{bash}
With that said, let’s make a directory in our projects directory.
```bash
$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world
```
If you're on Windows and not using PowerShell, the `~` may not work. Consult
If you’re on Windows and not using PowerShell, the `~` may not work. Consult
the documentation for your shell for more details.
Let's make a new source file next. I'm going to use the syntax `editor
filename` to represent editing a file in these examples, but you should use
whatever method you want. We'll call our file `main.rs`:
Let’s make a new source file next. We’ll call our file `main.rs`. Rust files
always end in a `.rs` extension. If you’re using more than one word in your
filename, use an underscore: `hello_world.rs` rather than `helloworld.rs`.
```{bash}
$ editor main.rs
```
Now that you’ve got your file open, type this in:
Rust files always end in a `.rs` extension. If you're using more than one word
in your filename, use an underscore. `hello_world.rs` rather than
`helloworld.rs`.
Now that you've got your file open, type this in:
```{rust}
```rust
fn main() {
println!("Hello, world!");
}
@ -51,89 +50,90 @@ fn main() {
Save the file, and then type this into your terminal window:
```{bash}
```bash
$ rustc main.rs
$ ./main # or main.exe on Windows
Hello, world!
```
You can also run these examples on [play.rust-lang.org](http://play.rust-lang.org/) by clicking on the arrow that appears in the upper right of the example when you mouse over the code.
Success! Let’s go over what just happened in detail.
Success! Let's go over what just happened in detail.
```{rust}
```rust
fn main() {
}
```
These lines define a *function* in Rust. The `main` function is special:
it's the beginning of every Rust program. The first line says "I'm declaring a
function named `main`, which takes no arguments and returns nothing." If there
it's the beginning of every Rust program. The first line says "I’m declaring a
function named `main` which takes no arguments and returns nothing." If there
were arguments, they would go inside the parentheses (`(` and `)`), and because
we aren't returning anything from this function, we can omit the return type
entirely. We'll get to it later.
we aren’t returning anything from this function, we can omit the return type
entirely. We’ll get to it later.
You'll also note that the function is wrapped in curly braces (`{` and `}`).
You’ll also note that the function is wrapped in curly braces (`{` and `}`).
Rust requires these around all function bodies. It is also considered good
style to put the opening curly brace on the same line as the function
declaration, with one space in between.
Next up is this line:
```{rust}
```rust
println!("Hello, world!");
```
This line does all of the work in our little program. There are a number of
details that are important here. The first is that it's indented with four
details that are important here. The first is that it’s indented with four
spaces, not tabs. Please configure your editor of choice to insert four spaces
with the tab key. We provide some [sample configurations for various
editors][configs].
[configs]: https://github.com/rust-lang/rust/tree/master/src/etc/CONFIGS.md
The second point is the `println!()` part. This is calling a Rust *macro*,
The second point is the `println!()` part. This is calling a Rust [macro][macro],
which is how metaprogramming is done in Rust. If it were a function instead, it
would look like this: `println()`. For our purposes, we don't need to worry
about this difference. Just know that sometimes, you'll see a `!`, and that
means that you're calling a macro instead of a normal function. Rust implements
`println!` as a macro rather than a function for good reasons, but that's a
very advanced topic. You'll learn more when we talk about macros later. One
last thing to mention: Rust's macros are significantly different from C macros,
if you've used those. Don't be scared of using macros. We'll get to the details
eventually, you'll just have to trust us for now.
would look like this: `println()`. For our purposes, we don’t need to worry
about this difference. Just know that sometimes, you’ll see a `!`, and that
means that you’re calling a macro instead of a normal function. Rust implements
`println!` as a macro rather than a function for good reasons, but that's an
advanced topic. One last thing to mention: Rust’s macros are significantly
different from C macros, if you’ve used those. Don’t be scared of using macros.
We’ll get to the details eventually, you’ll just have to trust us for now.
Next, `"Hello, world!"` is a *string*. Strings are a surprisingly complicated
topic in a systems programming language, and this is a *statically allocated*
string. We will talk more about different kinds of allocation later. We pass
this string as an argument to `println!`, which prints the string to the
screen. Easy enough!
[macro]: macros.html
Finally, the line ends with a semicolon (`;`). Rust is an *expression
oriented* language, which means that most things are expressions. The `;` is
used to indicate that this expression is over, and the next one is ready to
begin. Most lines of Rust code end with a `;`. We will cover this in-depth
later in the guide.
Next, `"Hello, world!"` is a ‘string’. Strings are a surprisingly complicated
topic in a systems programming language, and this is a ‘statically allocated’
string. If you want to read further about allocation, check out [the stack and
the heap], but you don’t need to right now if you don’t want to. We pass this
string as an argument to `println!`, which prints the string to the screen.
Easy enough!
Finally, actually *compiling* and *running* our program. We can compile
with our compiler, `rustc`, by passing it the name of our source file:
[allocation]: the-stack-and-the-heap.html
```{bash}
Finally, the line ends with a semicolon (`;`). Rust is an ‘expression oriented’
language, which means that most things are expressions, rather than statements.
The `;` is used to indicate that this expression is over, and the next one is
ready to begin. Most lines of Rust code end with a `;`.
Finally, actually compiling and running our program. We can compile with our
compiler, `rustc`, by passing it the name of our source file:
```bash
$ rustc main.rs
```
This is similar to `gcc` or `clang`, if you come from a C or C++ background. Rust
will output a binary executable. You can see it with `ls`:
```{bash}
```bash
$ ls
main main.rs
```
Or on Windows:
```{bash}
```bash
$ dir
main.exe main.rs
```
@ -141,7 +141,7 @@ main.exe main.rs
There are now two files: our source code, with the `.rs` extension, and the
executable (`main.exe` on Windows, `main` everywhere else)
```{bash}
```bash
$ ./main # or main.exe on Windows
```
@ -149,15 +149,15 @@ This prints out our `Hello, world!` text to our terminal.
If you come from a dynamically typed language like Ruby, Python, or JavaScript,
you may not be used to these two steps being separate. Rust is an
*ahead-of-time compiled language*, which means that you can compile a
program, give it to someone else, and they don't need to have Rust installed.
If you give someone a `.rb` or `.py` or `.js` file, they need to have a
‘ahead-of-time compiled language’, which means that you can compile a program,
give it to someone else, and they don't need to have Rust installed. If you
give someone a `.rb` or `.py` or `.js` file, they need to have a
Ruby/Python/JavaScript implementation installed, but you just need one command
to both compile and run your program. Everything is a tradeoff in language design,
and Rust has made its choice.
to both compile and run your program. Everything is a tradeoff in language
design, and Rust has made its choice.
Congratulations! You have officially written a Rust program. That makes you a
Rust programmer! Welcome.
Rust programmer! Welcome. 🎊🎉👍
Next, I'd like to introduce you to another tool, Cargo, which is used to write
real-world Rust programs. Just using `rustc` is nice for simple things, but as

68
src/doc/trpl/installing-rust.md
View File

@ -1,27 +1,32 @@
% Installing Rust
The first step to using Rust is to install it! There are a number of ways to
install Rust, but the easiest is to use the `rustup` script. If you're on
Linux or a Mac, all you need to do is this (note that you don't need to type
in the `$`s, they just indicate the start of each command):
install Rust, but the easiest is to use the `rustup` script. If you're on Linux
or a Mac, all you need to do is this (note that you don't need to type in the
`$`s, they just indicate the start of each command):
```bash
$ curl -sf -L https://static.rust-lang.org/rustup.sh | sudo sh
```
If you're concerned about the [potential insecurity](http://curlpipesh.tumblr.com/) of using `curl | sudo sh`,
please keep reading and see our disclaimer below. And feel free to use a two-step version of the installation and examine our installation script:
If you're concerned about the [potential insecurity][insecurity] of using `curl
| sudo sh`, please keep reading and see our disclaimer below. And feel free to
use a two-step version of the installation and examine our installation script:
```bash
$ curl -f -L https://static.rust-lang.org/rustup.sh -O
$ sudo sh rustup.sh
```
If you're on Windows, please download either the [32-bit
installer](https://static.rust-lang.org/dist/rust-1.0.0-beta-i686-pc-windows-gnu.exe)
or the [64-bit
installer](https://static.rust-lang.org/dist/rust-1.0.0-beta-x86_64-pc-windows-gnu.exe)
and run it.
[insecurity]: http://curlpipesh.tumblr.com
If you're on Windows, please download either the [32-bit installer][win32] or
the [64-bit installer][win64] and run it.
[win32]: https://static.rust-lang.org/dist/rust-1.0.0-beta-i686-pc-windows-gnu.msi
[win64]: https://static.rust-lang.org/dist/rust-1.0.0-beta-x86_64-pc-windows-gnu.msi
## Uninstalling
If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay.
Not every programming language is great for everyone. Just run the uninstall
@ -31,22 +36,20 @@ script:
$ sudo /usr/local/lib/rustlib/uninstall.sh
```
If you used the Windows installer, just re-run the `.exe` and it will give you
If you used the Windows installer, just re-run the `.msi` and it will give you
an uninstall option.
You can re-run this script any time you want to update Rust. Which, at this
point, is often. Rust is still pre-1.0, and so people assume that you're using
a very recent Rust.
Some people, and somewhat rightfully so, get very upset when we tell you to
`curl | sudo sh`. Basically, when you do this, you are trusting that the good
people who maintain Rust aren't going to hack your computer and do bad things.
That's a good instinct! If you're one of those people, please check out the
documentation on [building Rust from Source][from source], or [the official
binary downloads][install page]. And we promise that this method will not be
the way to install Rust forever: it's just the easiest way to keep people
updated while Rust is in its alpha state.
This brings me to one other point: some people, and somewhat rightfully so, get
very upset when we tell you to `curl | sudo sh`. And they should be! Basically,
when you do this, you are trusting that the good people who maintain Rust
aren't going to hack your computer and do bad things. That's a good instinct!
If you're one of those people, please check out the documentation on [building
Rust from Source](https://github.com/rust-lang/rust#building-from-source), or
[the official binary downloads](http://www.rust-lang.org/install.html). And we
promise that this method will not be the way to install Rust forever: it's just
the easiest way to keep people updated while Rust is in its alpha state.
[from source]: https://github.com/rust-lang/rust#building-from-source
[install page]: http://www.rust-lang.org/install.html
Oh, we should also mention the officially supported platforms:
@ -73,7 +76,7 @@ $ rustc --version
You should see the version number, commit hash, commit date and build date:
```bash
rustc 1.0.0-nightly (f11f3e7ba 2015-01-04) (built 2015-01-06)
rustc 1.0.0-beta (9854143cb 2015-04-02) (built 2015-04-02)
```
If you did, Rust has been installed successfully! Congrats!
@ -84,10 +87,13 @@ On Windows, it's in a `share/doc` directory, inside wherever you installed Rust
to.
If not, there are a number of places where you can get help. The easiest is
[the #rust IRC channel on irc.mozilla.org](irc://irc.mozilla.org/#rust), which
you can access through
[Mibbit](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust). Click
that link, and you'll be chatting with other Rustaceans (a silly nickname we
call ourselves), and we can help you out. Other great resources include [the
/r/rust subreddit](http://www.reddit.com/r/rust), and [Stack
Overflow](http://stackoverflow.com/questions/tagged/rust).
[the #rust IRC channel on irc.mozilla.org][irc], which you can access through
[Mibbit][mibbit]. Click that link, and you'll be chatting with other Rustaceans
(a silly nickname we call ourselves), and we can help you out. Other great
resources include [the user’s forum][users], and [Stack Overflow][stack
overflow].
[irc]: irc://irc.mozilla.org/#rust
[mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
[users]: http://users.rust-lang.org/
[stack overflow]: http://stackoverflow.com/questions/tagged/rust

3
src/doc/trpl/learn-rust.md
View File

@ -1 +1,4 @@
% Learn Rust
This section is coming soon! It will eventually have a few tutorials with
building real Rust projects, but they are under development.

95
src/doc/trpl/nightly-rust.md
View File

@ -2,7 +2,9 @@
Rust provides three distribution channels for Rust: nightly, beta, and stable.
Unstable features are only available on nightly Rust. For more details on this
process, see [this post](http://blog.rust-lang.org/2014/10/30/Stability.html).
process, see ‘[Stability as a deliverable][stability]’.
[stability]: http://blog.rust-lang.org/2014/10/30/Stability.html
To install nightly Rust, you can use `rustup.sh`:
@ -10,19 +12,24 @@ To install nightly Rust, you can use `rustup.sh`:
$ curl -s https://static.rust-lang.org/rustup.sh | sudo sh -s -- --channel=nightly
```
If you're concerned about the [potential insecurity](http://curlpipesh.tumblr.com/) of using `curl | sudo sh`,
please keep reading and see our disclaimer below. And feel free to use a two-step version of the installation and examine our installation script:
If you're concerned about the [potential insecurity][insecurity] of using `curl
| sudo sh`, please keep reading and see our disclaimer below. And feel free to
use a two-step version of the installation and examine our installation script:
```bash
$ curl -f -L https://static.rust-lang.org/rustup.sh -O
$ sudo sh rustup.sh --channel=nightly
$ sudo sh rustup.sh
```
If you're on Windows, please download either the [32-bit
installer](https://static.rust-lang.org/dist/rust-nightly-i686-pc-windows-gnu.exe)
or the [64-bit
installer](https://static.rust-lang.org/dist/rust-nightly-x86_64-pc-windows-gnu.exe)
and run it.
[insecurity]: http://curlpipesh.tumblr.com
If you're on Windows, please download either the [32-bit installer][win32] or
the [64-bit installer][win64] and run it.
[win32]: https://static.rust-lang.org/dist/rust-1.0.0-beta-i686-pc-windows-gnu.msi
[win64]: https://static.rust-lang.org/dist/rust-1.0.0-beta-x86_64-pc-windows-gnu.msi
## Uninstalling
If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay.
Not every programming language is great for everyone. Just run the uninstall
@ -32,20 +39,64 @@ script:
$ sudo /usr/local/lib/rustlib/uninstall.sh
```
If you used the Windows installer, just re-run the `.exe` and it will give you
If you used the Windows installer, just re-run the `.msi` and it will give you
an uninstall option.
You can re-run this script any time you want to update Rust. Which, at this
point, is often. Rust is still pre-1.0, and so people assume that you're using
a very recent Rust.
Some people, and somewhat rightfully so, get very upset when we tell you to
`curl | sudo sh`. Basically, when you do this, you are trusting that the good
people who maintain Rust aren't going to hack your computer and do bad things.
That's a good instinct! If you're one of those people, please check out the
documentation on [building Rust from Source][from source], or [the official
binary downloads][install page]. And we promise that this method will not be
the way to install Rust forever: it's just the easiest way to keep people
updated while Rust is in its alpha state.
This brings me to one other point: some people, and somewhat rightfully so, get
very upset when we tell you to `curl | sudo sh`. And they should be! Basically,
when you do this, you are trusting that the good people who maintain Rust
aren't going to hack your computer and do bad things. That's a good instinct!
If you're one of those people, please check out the documentation on [building
Rust from Source](https://github.com/rust-lang/rust#building-from-source), or
[the official binary downloads](http://www.rust-lang.org/install.html). And we
promise that this method will not be the way to install Rust forever: it's just
the easiest way to keep people updated while Rust is in its alpha state.
[from source]: https://github.com/rust-lang/rust#building-from-source
[install page]: http://www.rust-lang.org/install.html
Oh, we should also mention the officially supported platforms:
* Windows (7, 8, Server 2008 R2)
* Linux (2.6.18 or later, various distributions), x86 and x86-64
* OSX 10.7 (Lion) or greater, x86 and x86-64
We extensively test Rust on these platforms, and a few others, too, like
Android. But these are the ones most likely to work, as they have the most
testing.
Finally, a comment about Windows. Rust considers Windows to be a first-class
platform upon release, but if we're honest, the Windows experience isn't as
integrated as the Linux/OS X experience is. We're working on it! If anything
does not work, it is a bug. Please let us know if that happens. Each and every
commit is tested against Windows just like any other platform.
If you've got Rust installed, you can open up a shell, and type this:
```bash
$ rustc --version
```
You should see the version number, commit hash, commit date and build date:
```bash
rustc 1.0.0-nightly (f11f3e7ba 2015-01-04) (built 2015-01-06)
```
If you did, Rust has been installed successfully! Congrats!
This installer also installs a copy of the documentation locally, so you can
read it offline. On UNIX systems, `/usr/local/share/doc/rust` is the location.
On Windows, it's in a `share/doc` directory, inside wherever you installed Rust
to.
If not, there are a number of places where you can get help. The easiest is
[the #rust IRC channel on irc.mozilla.org][irc], which you can access through
[Mibbit][mibbit]. Click that link, and you'll be chatting with other Rustaceans
(a silly nickname we call ourselves), and we can help you out. Other great
resources include [the user’s forum][users], and [Stack Overflow][stack
overflow].
[irc]: irc://irc.mozilla.org/#rust
[mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust
[users]: http://users.rust-lang.org/
[stack overflow]: http://stackoverflow.com/questions/tagged/rust

9
src/doc/trpl/syntax-and-semantics.md
View File

@ -1 +1,10 @@
% Syntax and Semantics
This section breaks Rust down into small chunks, one for each concept.
If you’d like to learn Rust from the bottom up, reading this in order is a
great way to do that.
These sections also form a reference for each concept, so if you’re reading
another tutorial and find something confusing, you can find it explained
somewhere in here.