Some tidying up
Improving the use of 2nd and 3rd person Adding a few contractions to make the text less formal Tidying up some notes Providing a little bit more clarification for Windows users
This commit is contained in:
Jonathan Hansford
Steve Klabnik
parent
f116ab58b2
commit
22fbbd4b5c
4 changed files with 86 additions and 83 deletions
|
|
@ -1,6 +1,6 @@
|
|||
% The Rust Programming Language
|
||||
|
||||
Welcome! This book will teach us about the [Rust Programming Language][rust].
|
||||
Welcome! This book will teach you about the [Rust Programming Language][rust].
|
||||
Rust is a systems programming language focused on three goals: safety, speed,
|
||||
and concurrency. It maintains these goals without having a garbage collector,
|
||||
making it a useful language for a number of use cases other languages aren’t
|
||||
|
|
@ -17,7 +17,7 @@ Even then, Rust still allows precise control like a low-level language would.
|
|||
“The Rust Programming Language” is split into eight sections. This introduction
|
||||
is the first. After this:
|
||||
|
||||
* [Getting started][gs] - Set up our computer for Rust development.
|
||||
* [Getting started][gs] - Set up your computer for Rust development.
|
||||
* [Learn Rust][lr] - Learn Rust programming through small projects.
|
||||
* [Effective Rust][er] - Higher-level concepts for writing excellent Rust code.
|
||||
* [Syntax and Semantics][ss] - Each bit of Rust, broken down into small chunks.
|
||||
|
|
@ -33,11 +33,11 @@ is the first. After this:
|
|||
[gl]: glossary.html
|
||||
[bi]: bibliography.html
|
||||
|
||||
After reading this introduction, we’ll want to dive into either ‘Learn Rust’ or
|
||||
‘Syntax and Semantics’, depending on our preference: ‘Learn Rust’ if we want to
|
||||
dive in with a project, or ‘Syntax and Semantics’ if we prefer to start small,
|
||||
and learn a single concept thoroughly before moving onto the next. Copious
|
||||
cross-linking connects these parts together.
|
||||
After reading this introduction, you’ll want to dive into either ‘Learn Rust’ or
|
||||
‘Syntax and Semantics’, depending on your preference: ‘Learn Rust’ if you want
|
||||
to dive in with a project, or ‘Syntax and Semantics’ if you prefer to start
|
||||
small, and learn a single concept thoroughly before moving onto the next.
|
||||
Copious cross-linking connects these parts together.
|
||||
|
||||
### Contributing
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ The source files from which this book is generated can be found on Github:
|
|||
|
||||
## A brief introduction to Rust
|
||||
|
||||
Is Rust a language we might be interested in? Let’s examine a few small code
|
||||
Is Rust a language you might be interested in? Let’s examine a few small code
|
||||
samples to show off a few of its strengths.
|
||||
|
||||
The main concept that makes Rust unique is called ‘ownership’. Consider this
|
||||
|
|
@ -76,7 +76,7 @@ annotating types.
|
|||
|
||||
Rust prefers stack allocation to heap allocation: `x` is placed directly on the
|
||||
stack. However, the `Vec<T>` type allocates space for the elements of the vector
|
||||
on the heap. If we’re not familiar with this distinction, we can ignore it for
|
||||
on the heap. If you’re not familiar with this distinction, you can ignore it for
|
||||
now, or check out [‘The Stack and the Heap’][heap]. As a systems programming
|
||||
language, Rust gives us the ability to control how our memory is allocated, but
|
||||
when we’re getting started, it’s less of a big deal.
|
||||
|
|
@ -104,13 +104,13 @@ fn main() {
|
|||
}
|
||||
```
|
||||
|
||||
We’ve introduced another binding, `y`. In this case, `y` is a ‘reference’ to
|
||||
the first element of the vector. Rust’s references are similar to pointers in
|
||||
other languages, but with additional compile-time safety checks. References
|
||||
interact with the ownership system by [‘borrowing’][borrowing] what they point
|
||||
to, rather than owning it. The difference is, when the reference goes out of
|
||||
scope, it will not deallocate the underlying memory. If it did, we’d
|
||||
de-allocate twice, which is bad!
|
||||
We’ve introduced another binding, `y`. In this case, `y` is a ‘reference’ to the
|
||||
first element of the vector. Rust’s references are similar to pointers in other
|
||||
languages, but with additional compile-time safety checks. References interact
|
||||
with the ownership system by [‘borrowing’][borrowing] what they point to, rather
|
||||
than owning it. The difference is, when the reference goes out of scope, it
|
||||
won't deallocate the underlying memory. If it did, we’d de-allocate twice, which
|
||||
is bad!
|
||||
|
||||
[borrowing]: references-and-borrowing.html
|
||||
|
||||
|
|
@ -146,7 +146,7 @@ fn main() {
|
|||
|
||||
Whew! The Rust compiler gives quite detailed errors at times, and this is one
|
||||
of those times. As the error explains, while we made our binding mutable, we
|
||||
still cannot call `push`. This is because we already have a reference to an
|
||||
still can't call `push`. This is because we already have a reference to an
|
||||
element of the vector, `y`. Mutating something while another reference exists
|
||||
is dangerous, because we may invalidate the reference. In this specific case,
|
||||
when we create the vector, we may have only allocated space for two elements.
|
||||
|
|
|
|||
|
|
@ -13,9 +13,10 @@ 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 we installed Rust via the official installers we will also have Cargo. If we
|
||||
installed Rust some other way, we may want to [check the Cargo
|
||||
README][cargoreadme] 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
|
||||
|
||||
|
|
@ -30,14 +31,14 @@ old executable (`main.exe` on Windows, `main` everywhere else). Let's do that pa
|
|||
```bash
|
||||
$ mkdir src
|
||||
$ mv main.rs src/main.rs
|
||||
$ rm main # or main.exe on Windows
|
||||
$ rm main # or 'rm main.exe' on Windows
|
||||
```
|
||||
|
||||
Note that since we're creating an executable, we retain `main.rs` as the source
|
||||
filename. If we want to make a library instead, we should use `lib.rs`. This
|
||||
convention is used by Cargo to successfully compile our projects, but it can be
|
||||
overridden if we wish. Custom file locations for the entry point can be
|
||||
specified with a [`[lib]` or `[[bin]]`][crates-custom] key in the TOML file.
|
||||
> Note: since we're creating an executable, we retain `main.rs` as the source
|
||||
> filename. If we want to make a library instead, we should use `lib.rs`. This
|
||||
> convention is used by Cargo to successfully compile our projects, but it can
|
||||
> be overridden if we wish. Custom file locations for the entry point can be
|
||||
> specified with a [`[lib]` or `[[bin]]`][crates-custom] key in the TOML file.
|
||||
|
||||
[crates-custom]: http://doc.crates.io/manifest.html#configuring-a-target
|
||||
|
||||
|
|
@ -49,7 +50,7 @@ everything, and everything in its place.
|
|||
Next, our configuration file:
|
||||
|
||||
```bash
|
||||
$ editor Cargo.toml
|
||||
$ editor Cargo.toml # or 'notepad Cargo.toml' on Windows
|
||||
```
|
||||
|
||||
Make sure to get this name right: we need the capital `C`!
|
||||
|
|
@ -112,7 +113,7 @@ grows, we can just run `cargo build`, and it’ll work the right way.
|
|||
When our project is finally ready for release, we can use `cargo build
|
||||
--release` to compile our project with optimizations.
|
||||
|
||||
We'll also notice that Cargo has created a new file: `Cargo.lock`.
|
||||
You'll also notice that Cargo has created a new file: `Cargo.lock`.
|
||||
|
||||
```toml
|
||||
[root]
|
||||
|
|
@ -141,7 +142,7 @@ We don’t have to go through this whole process every time we want to start a n
|
|||
project! Cargo has the ability to make a bare-bones project directory in which
|
||||
we can start developing right away.
|
||||
|
||||
To start a new project with Cargo, use `cargo new`:
|
||||
To start a new project with Cargo, we use `cargo new`:
|
||||
|
||||
```bash
|
||||
$ cargo new hello_world --bin
|
||||
|
|
@ -178,8 +179,8 @@ authors = ["Your Name <you@example.com>"]
|
|||
```
|
||||
|
||||
Cargo has populated this file with reasonable defaults based off the arguments
|
||||
we gave it and our `git` global configuration. We may notice that Cargo has also
|
||||
initialized the `hello_world` directory as a `git` repository.
|
||||
we gave it and our `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`:
|
||||
|
||||
|
|
@ -199,11 +200,11 @@ Now that we’ve got the tools down, let’s actually learn more about the Rust
|
|||
language itself. These are the basics that will serve us well through the rest
|
||||
of our time with Rust.
|
||||
|
||||
We have two options: Dive into a project with ‘[Learn Rust][learnrust]’, or
|
||||
start from the bottom and work our 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 us.
|
||||
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
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@ thing to do.
|
|||
|
||||
The first thing that we need to do is make a file to put our code in. I like to
|
||||
make a `projects` directory in my home directory, and keep all my projects
|
||||
there. Rust does not care where our code lives.
|
||||
there. Rust doesn't care where our code lives.
|
||||
|
||||
This actually leads to one other concern we should address: this guide will
|
||||
assume that we have basic familiarity with the command line. Rust itself makes
|
||||
|
|
@ -71,10 +71,10 @@ 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’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.
|
||||
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:
|
||||
|
||||
|
|
@ -84,29 +84,29 @@ Next up is this line:
|
|||
|
||||
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
|
||||
spaces, not tabs. Please configure our editor of choice to insert four spaces
|
||||
with the tab key. We provide some [sample configurations for various
|
||||
editors][configs].
|
||||
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][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, we’ll see a `!`,
|
||||
and that means that we’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 we’ve used those. Don’t be scared of
|
||||
using macros. We’ll get to the details eventually, we’ll just have to take it on
|
||||
trust for now.
|
||||
don’t need to worry about this difference. Just know that sometimes, we’ll see a
|
||||
`!`, and that means that we’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 take it
|
||||
on trust for now.
|
||||
|
||||
[macro]: macros.html
|
||||
|
||||
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 we want to read further about allocation, check out [the stack and
|
||||
the heap][allocation], but we don’t need to right now if we don’t want to. We
|
||||
string. If you want to read further about allocation, check out [the stack and
|
||||
the heap][allocation], 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!
|
||||
|
||||
|
|
@ -127,8 +127,8 @@ compiler, `rustc`, by passing it the name of our source file:
|
|||
$ rustc main.rs
|
||||
```
|
||||
|
||||
This is similar to `gcc` or `clang`, if we come from a C or C++ background. Rust
|
||||
will output a binary executable. We can see it with `ls`:
|
||||
This is similar to `gcc` or `clang`, if you come from a C or C++ background.
|
||||
Rust will output a binary executable. We can see it with `ls`:
|
||||
|
||||
```bash
|
||||
$ ls
|
||||
|
|
@ -151,18 +151,19 @@ $ ./main # or main.exe on Windows
|
|||
|
||||
This prints out our `Hello, world!` text to our terminal.
|
||||
|
||||
If we come from a dynamic language like Ruby, Python, or JavaScript, we may not
|
||||
be used to these two steps being separate. Rust is an ‘ahead-of-time compiled
|
||||
language’, which means that we can compile a program, give it to someone else,
|
||||
and they don't need to have Rust installed. If we give someone a `.rb` or `.py`
|
||||
or `.js` file, they need to have a Ruby/Python/JavaScript implementation
|
||||
installed, but we just need one command to both compile and run our program.
|
||||
Everything is a tradeoff in language design, and Rust has made its choice.
|
||||
If you come from a dynamic 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 we can compile a program, give it to
|
||||
someone else, and they don't need to have Rust installed. If we give someone a
|
||||
`.rb` or `.py` or `.js` file, they need to have a Ruby/Python/JavaScript
|
||||
implementation installed, but we just need one command to both compile and run
|
||||
our program. Everything is a tradeoff in language design, and Rust has made its
|
||||
choice.
|
||||
|
||||
Congratulations! We have officially written a Rust program. That makes us Rust
|
||||
programmers! Welcome. 🎊🎉👍
|
||||
Congratulations! You have officially written a Rust program. That makes you a
|
||||
Rust programmer! Welcome. 🎊🎉👍
|
||||
|
||||
Next, I'd like to introduce us to another tool, Cargo, which is used to write
|
||||
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
|
||||
our project grows, we'll want something to help us manage all of the options
|
||||
that it has, and to make it easy to share our code with other people and
|
||||
|
|
|
|||
|
|
@ -24,37 +24,38 @@ $ sh rustup.sh
|
|||
|
||||
[insecurity]: http://curlpipesh.tumblr.com
|
||||
|
||||
If we're on Windows, please download the appropriate [installer][install-page].
|
||||
**NOTE:** By default, the Windows installer will not add Rust to the %PATH%
|
||||
system variable. If this is the only version of Rust we are installing and we
|
||||
want to be able to run it from the command line, click on "Advanced" on the
|
||||
install dialog and on the "Product Features" page ensure "Add to PATH" is
|
||||
installed on the local hard drive.
|
||||
If you're on Windows, please download the appropriate [installer][install-page].
|
||||
|
||||
> Note: By default, the Windows installer won't add Rust to the %PATH% system
|
||||
> variable. If this is the only version of Rust we are installing and we want to
|
||||
> be able to run it from the command line, click on "Advanced" on the install
|
||||
> dialog and on the "Product Features" page ensure "Add to PATH" is installed on
|
||||
> the local hard drive.
|
||||
|
||||
|
||||
[install-page]: https://www.rust-lang.org/install.html
|
||||
|
||||
## Uninstalling
|
||||
|
||||
If we decide we 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
|
||||
script:
|
||||
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. We'll just run the
|
||||
uninstall script:
|
||||
|
||||
```bash
|
||||
$ sudo /usr/local/lib/rustlib/uninstall.sh
|
||||
```
|
||||
|
||||
If we used the Windows installer, just re-run the `.msi` and it will give us an
|
||||
uninstall option.
|
||||
If we used the Windows installer, we'll just re-run the `.msi` and it will give
|
||||
us an uninstall option.
|
||||
|
||||
## That disclaimer we promised
|
||||
|
||||
Some people, and somewhat rightfully so, get very upset when we tell them to
|
||||
`curl | sh`. Basically, when we do this, we are trusting that the good people
|
||||
who maintain Rust aren't going to hack our computer and do bad things. That's a
|
||||
good instinct! If we're one of those people, please check out the documentation
|
||||
on [building Rust from Source][from-source], or [the official binary
|
||||
downloads][install-page].
|
||||
`curl | sh`. Basically, when they do this, they are trusting that the good
|
||||
people who maintain Rust aren't going to hack their 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].
|
||||
|
||||
[from-source]: https://github.com/rust-lang/rust#building-from-source
|
||||
|
||||
|
|
@ -62,7 +63,7 @@ downloads][install-page].
|
|||
|
||||
Oh, we should also mention the officially supported platforms:
|
||||
|
||||
* Windows (7, 8, Server 2008 R2)
|
||||
* Windows (7 or later, Server 2008 R2)
|
||||
* Linux (2.6.18 or later, various distributions), x86 and x86-64
|
||||
* OSX 10.7 (Lion) or later, x86 and x86-64
|
||||
|
||||
|
|
@ -73,7 +74,7 @@ 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
|
||||
doesn't 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.
|
||||
|
||||
## After installation
|
||||
|
|
|
|||
Loading…
Reference in a new issue