diff --git a/RELEASES.md b/RELEASES.md index 9b61ce0e05414..54fe87dc65816 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -1,3 +1,182 @@ +Version 1.4.0 (2015-10-29) +============================ + +* ~1200 changes, numerous bugfixes + +Highlights +---------- + +* Windows builds targeting the 64-bit MSVC ABI and linker (instead of + GNU) are now supported and recommended for use. + +Breaking Changes +---------------- + +* [Several changes have been made to fix type soundness and improve + the behavior of associated types][sound]. See [RFC 1214]. Although + we have mostly introduced these changes as warnings this release, to + become errors next release, there are still some scenarios that will + see immediate breakage. +* [The `str::lines` and `BufRead::lines` iterators treat `\r\n` as + line breaks in addition to `\n`][crlf]. +* [Loans of `'static` lifetime extend to the end of a function][stat]. +* [`str::parse` no longer introduces avoidable rounding error when + parsing floating point numbers. Together with earlier changes to + float formatting/output, "round trips" like f.to_string().parse() + now preserve the value of f exactly. Additionally, leading plus + signs are now accepted][fp3]. + + +Language +-------- + +* `use` statements that import multiple items [can now rename + them][i], as in `use foo::{bar as kitten, baz as puppy}`. +* [Binops work correctly on fat pointers][binfat]. +* `pub extern crate`, which does not behave as expected, [issues a + warning][pec] until a better solution is found. + +Libraries +--------- + +* [Many APIs were stabilized][stab]: `>::into_string`, + [`Arc::downgrade`], [`Arc::get_mut`], [`Arc::make_mut`], + [`Arc::try_unwrap`], [`Box::from_raw`], [`Box::into_raw`], [`CStr::to_str`], + [`CStr::to_string_lossy`], [`CString::from_raw`], [`CString::into_raw`], + [`IntoRawFd::into_raw_fd`], [`IntoRawFd`], + `IntoRawHandle::into_raw_handle`, `IntoRawHandle`, + `IntoRawSocket::into_raw_socket`, `IntoRawSocket`, [`Rc::downgrade`], + [`Rc::get_mut`], [`Rc::make_mut`], [`Rc::try_unwrap`], [`Result::expect`], + [`String::into_boxed_str`], [`TcpStream::read_timeout`], + [`TcpStream::set_read_timeout`], [`TcpStream::set_write_timeout`], + [`TcpStream::write_timeout`], [`UdpSocket::read_timeout`], + [`UdpSocket::set_read_timeout`], [`UdpSocket::set_write_timeout`], + [`UdpSocket::write_timeout`], `Vec::append`, `Vec::split_off`, + [`VecDeque::append`], [`VecDeque::retain`], [`VecDeque::split_off`], + [`rc::Weak::upgrade`], [`rc::Weak`], [`slice::Iter::as_slice`], + [`slice::IterMut::into_slice`], [`str::CharIndices::as_str`], + [`str::Chars::as_str`], [`str::split_at_mut`], [`str::split_at`], + [`sync::Weak::upgrade`], [`sync::Weak`], [`thread::park_timeout`], + [`thread::sleep`]. +* [Some APIs were deprecated][dep]: `BTreeMap::with_b`, + `BTreeSet::with_b`, `Option::as_mut_slice`, `Option::as_slice`, + `Result::as_mut_slice`, `Result::as_slice`, `f32::from_str_radix`, + `f64::from_str_radix`. +* [Reverse-searching strings is faster with the 'two-way' + algorithm][s]. +* [`std::io::copy` allows `?Sized` arguments][cc]. +* The `Windows`, `Chunks`, and `ChunksMut` iterators over slices all + [override `count`, `nth` and `last` with an O(1) + implementation][it]. +* [`Default` is implemented for arrays up to `[T; 32]`][d]. +* [`IntoRawFd` has been added to the Unix-specific prelude, + `IntoRawSocket` and `IntoRawHandle` to the Windows-specific + prelude][pr]. +* [`Extend` and `FromIterator` where `T: + Copy`][ext] as part of [RFC 839]. This will cause type inferance + breakage in rare situations. +* [`BinaryHeap` implements `Debug`][bh2]. +* [`Borrow` and `BorrowMut` are implemented for fixed-size + arrays][bm]. +* [`extern fn`s with the "Rust" and "C" ABIs implement common + traits including `Eq`, `Ord`, `Debug`, `Hash`][fp]. +* [String comparison is faster][faststr]. +* `&mut T` where `T: std::fmt::Write` [also implements + `std::fmt::Write`][mutw]. +* [A stable regression in `VecDeque::push_back` and other + capicity-altering methods that caused panics for zero-sized types + was fixed][vd]. +* [Function pointers implement traits for up to 12 parameters][fp2]. + +Miscellaneous +------------- + +* The compiler [no longer uses the 'morestack' feature to prevent + stack overflow][mm]. Instead it uses guard pages and stack + probes (though stack probes are not yet implemented on any platform + but Windows). +* [The compiler matches traits faster when projections are involved][p]. +* The 'improper_ctypes' lint [no longer warns about use of `isize` and + `usize`][ffi]. +* [Cargo now displays useful information about what its doing during + `cargo update`][cu]. + +[`Arc::downgrade`]: http://doc.rust-lang.org/nightly/alloc/arc/struct.Arc.html#method.downgrade +[`Arc::make_mut`]: http://doc.rust-lang.org/nightly/alloc/arc/struct.Arc.html#method.make_mut +[`Arc::get_mut`]: http://doc.rust-lang.org/nightly/alloc/arc/struct.Arc.html#method.get_mut +[`Arc::try_unwrap`]: http://doc.rust-lang.org/nightly/alloc/arc/struct.Arc.html#method.try_unwrap +[`Box::from_raw`]: http://doc.rust-lang.org/nightly/alloc/boxed/struct.Box.html#method.from_raw +[`Box::into_raw`]: http://doc.rust-lang.org/nightly/alloc/boxed/struct.Box.html#method.into_raw +[`CStr::to_str`]: http://doc.rust-lang.org/nightly/std/ffi/struct.CStr.html#method.to_str +[`CStr::to_string_lossy`]: http://doc.rust-lang.org/nightly/std/ffi/struct.CStr.html#method.to_string_lossy +[`CString::from_raw`]: http://doc.rust-lang.org/nightly/std/ffi/struct.CString.html#method.from_raw +[`CString::into_raw`]: http://doc.rust-lang.org/nightly/std/ffi/struct.CString.html#method.into_raw +[`IntoRawFd::into_raw_fd`]: http://doc.rust-lang.org/nightly/std/os/unix/io/trait.IntoRawFd.html#tymethod.into_raw_fd +[`IntoRawFd`]: http://doc.rust-lang.org/nightly/std/os/unix/io/trait.IntoRawFd.html +[`Rc::downgrade`]: http://doc.rust-lang.org/nightly/alloc/rc/struct.Rc.html#method.downgrade +[`Rc::get_mut`]: http://doc.rust-lang.org/nightly/alloc/rc/struct.Rc.html#method.get_mut +[`Rc::make_mut`]: http://doc.rust-lang.org/nightly/alloc/rc/struct.Rc.html#method.make_mut +[`Rc::try_unwrap`]: http://doc.rust-lang.org/nightly/alloc/rc/struct.Rc.html#method.try_unwrap +[`Result::expect`]: http://doc.rust-lang.org/nightly/core/result/enum.Result.html#method.expect +[`String::into_boxed_str`]: http://doc.rust-lang.org/nightly/collections/string/struct.String.html#method.into_boxed_str +[`TcpStream::read_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.read_timeout +[`TcpStream::set_read_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.set_read_timeout +[`TcpStream::write_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.write_timeout +[`TcpStream::set_write_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.set_write_timeout +[`UdpSocket::read_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.read_timeout +[`UdpSocket::set_read_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.set_read_timeout +[`UdpSocket::write_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.write_timeout +[`UdpSocket::set_write_timeout`]: http://doc.rust-lang.org/nightly/std/net/struct.TcpStream.html#method.set_write_timeout +[`VecDeque::append`]: http://doc.rust-lang.org/nightly/std/collections/struct.VecDeque.html#method.append +[`VecDeque::retain`]: http://doc.rust-lang.org/nightly/std/collections/struct.VecDeque.html#method.retain +[`VecDeque::split_off`]: http://doc.rust-lang.org/nightly/std/collections/struct.VecDeque.html#method.split_off +[`rc::Weak::upgrade`]: http://doc.rust-lang.org/nightly/std/rc/struct.Weak.html#method.upgrade +[`rc::Weak`]: http://doc.rust-lang.org/nightly/std/rc/struct.Weak.html +[`slice::Iter::as_slice`]: http://doc.rust-lang.org/nightly/std/slice/struct.Iter.html#method.as_slice +[`slice::IterMut::into_slice`]: http://doc.rust-lang.org/nightly/std/slice/struct.IterMut.html#method.into_slice +[`str::CharIndices::as_str`]: http://doc.rust-lang.org/nightly/std/str/struct.CharIndices.html#method.as_str +[`str::Chars::as_str`]: http://doc.rust-lang.org/nightly/std/str/struct.Chars.html#method.as_str +[`str::split_at_mut`]: http://doc.rust-lang.org/nightly/std/primitive.str.html#method.split_at_mut +[`str::split_at`]: http://doc.rust-lang.org/nightly/std/primitive.str.html#method.split_at +[`sync::Weak::upgrade`]: http://doc.rust-lang.org/nightly/std/sync/struct.Weak.html#method.upgrade +[`sync::Weak`]: http://doc.rust-lang.org/nightly/std/sync/struct.Weak.html +[`thread::park_timeout`]: http://doc.rust-lang.org/nightly/std/thread/fn.park_timeout.html +[`thread::sleep`]: http://doc.rust-lang.org/nightly/std/thread/fn.sleep.html +[bh2]: https://github.com/rust-lang/rust/pull/28156 +[binfat]: https://github.com/rust-lang/rust/pull/28270 +[bm]: https://github.com/rust-lang/rust/pull/28197 +[cc]: https://github.com/rust-lang/rust/pull/27531 +[crlf]: https://github.com/rust-lang/rust/pull/28034 +[cu]: https://github.com/rust-lang/cargo/pull/1931 +[d]: https://github.com/rust-lang/rust/pull/27825 +[dep]: https://github.com/rust-lang/rust/pull/28339 +[es]: https://github.com/rust-lang/rust/pull/27956 +[ext]: https://github.com/rust-lang/rust/pull/28094 +[faststr]: https://github.com/rust-lang/rust/pull/28338 +[ffi]: https://github.com/rust-lang/rust/pull/28779 +[fp]: https://github.com/rust-lang/rust/pull/28268 +[fp2]: https://github.com/rust-lang/rust/pull/28560 +[fp3]: https://github.com/rust-lang/rust/pull/27307 +[i]: https://github.com/rust-lang/rust/pull/27451 +[into2]: https://github.com/rust-lang/rust/pull/28039 +[it]: https://github.com/rust-lang/rust/pull/27652 +[mm]: https://github.com/rust-lang/rust/pull/27338 +[mutw]: https://github.com/rust-lang/rust/pull/28368 +[sound]: https://github.com/rust-lang/rust/pull/27641 +[p]: https://github.com/rust-lang/rust/pull/27866 +[pec]: https://github.com/rust-lang/rust/pull/28486 +[pr]: https://github.com/rust-lang/rust/pull/27896 +[RFC 839]: https://github.com/rust-lang/rfcs/blob/master/text/0839-embrace-extend-extinguish.md +[RFC 1214]: https://github.com/rust-lang/rfcs/blob/master/text/1214-projections-lifetimes-and-wf.md +[s]: https://github.com/rust-lang/rust/pull/27474 +[stab]: https://github.com/rust-lang/rust/pull/28339 +[stat]: https://github.com/rust-lang/rust/pull/28321 +[vd]: https://github.com/rust-lang/rust/pull/28494 + Version 1.3.0 (2015-09-17) ============================== diff --git a/src/doc/trpl/SUMMARY.md b/src/doc/trpl/SUMMARY.md index 2b5d1fa70aada..704bcf1587b8a 100644 --- a/src/doc/trpl/SUMMARY.md +++ b/src/doc/trpl/SUMMARY.md @@ -1,9 +1,6 @@ # Summary * [Getting Started](getting-started.md) - * [Installing Rust](installing-rust.md) - * [Hello, world!](hello-world.md) - * [Hello, Cargo!](hello-cargo.md) * [Learn Rust](learn-rust.md) * [Guessing Game](guessing-game.md) * [Dining Philosophers](dining-philosophers.md) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index b74aaef927d88..c693cceeac482 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -1605,14 +1605,11 @@ arguments. ## Writing the logic -We're all different in how we write code, but error handling is -usually the last thing we want to think about. This isn't very good -practice for good design, but it can be useful for rapidly -prototyping. In our case, because Rust forces us to be explicit about -error handling, it will also make it obvious what parts of our program -can cause errors. Why? Because Rust will make us call `unwrap`! This -can give us a nice bird's eye view of how we need to approach error -handling. +We all write code differently, but error handling is usually the last thing we +want to think about. This isn't great for the overall design of a program, but +it can be useful for rapid prototyping. Because Rust forces us to be explicit +about error handling (by making us call `unwrap`), it is easy to see which +parts of our program can cause errors. In this case study, the logic is really simple. All we need to do is parse the CSV data given to us and print out a field in matching rows. Let's do it. (Make diff --git a/src/doc/trpl/getting-started.md b/src/doc/trpl/getting-started.md index 549f8c3ca5724..5b1040dd05ee1 100644 --- a/src/doc/trpl/getting-started.md +++ b/src/doc/trpl/getting-started.md @@ -3,3 +3,608 @@ This first section of the book will get us 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. + +# Installing Rust + +The first step to using Rust is to install it. Generally speaking, you’ll need +an Internet connection to run the commands in this chapter, as we’ll be +downloading Rust from the internet. + +We’ll be showing off a number of commands using a terminal, and those lines all +start with `$`. We don't need to type in the `$`s, they are there to indicate +the start of each command. We’ll see many tutorials and examples around the web +that follow this convention: `$` for commands run as our regular user, and `#` +for commands we should be running as an administrator. + +## Platform support + +The Rust compiler runs on, and compiles to, a great number of platforms, though +not all platforms are equally supported. Rust's support levels are organized +into three tiers, each with a different set of guarantees. + +Platforms are identified by their "target triple" which is the string to inform +the compiler what kind of output should be produced. The columns below indicate +whether the corresponding component works on the specified platform. + +### Tier 1 + +Tier 1 platforms can be thought of as "guaranteed to build and work". +Specifically they will each satisfy the following requirements: + +* Automated testing is set up to run tests for the platform. +* Landing changes to the `rust-lang/rust` repository's master branch is gated on + tests passing. +* Official release artifacts are provided for the platform. +* Documentation for how to use and how to build the platform is available. + +| Target | std |rustc|cargo| notes | +|-------------------------------|-----|-----|-----|----------------------------| +| `x86_64-pc-windows-msvc` | ✓ | ✓ | ✓ | 64-bit MSVC (Windows 7+) | +| `i686-pc-windows-gnu` | ✓ | ✓ | ✓ | 32-bit MinGW (Windows 7+) | +| `x86_64-pc-windows-gnu` | ✓ | ✓ | ✓ | 64-bit MinGW (Windows 7+) | +| `i686-apple-darwin` | ✓ | ✓ | ✓ | 32-bit OSX (10.7+, Lion+) | +| `x86_64-apple-darwin` | ✓ | ✓ | ✓ | 64-bit OSX (10.7+, Lion+) | +| `i686-unknown-linux-gnu` | ✓ | ✓ | ✓ | 32-bit Linux (2.6.18+) | +| `x86_64-unknown-linux-gnu` | ✓ | ✓ | ✓ | 64-bit Linux (2.6.18+) | + +### Tier 2 + +Tier 2 platforms can be thought of as "guaranteed to build". Automated tests +are not run so it's not guaranteed to produce a working build, but platforms +often work to quite a good degree and patches are always welcome! Specifically, +these platforms are required to have each of the following: + +* Automated building is set up, but may not be running tests. +* Landing changes to the `rust-lang/rust` repository's master branch is gated on + platforms **building**. Note that this means for some platforms only the + standard library is compiled, but for others the full bootstrap is run. +* Official release artifacts are provided for the platform. + +| Target | std |rustc|cargo| notes | +|-------------------------------|-----|-----|-----|----------------------------| +| `i686-pc-windows-msvc` | ✓ | ✓ | ✓ | 32-bit MSVC (Windows 7+) | + +### Tier 3 + +Tier 3 platforms are those which Rust has support for, but landing changes is +not gated on the platform either building or passing tests. Working builds for +these platforms may be spotty as their reliability is often defined in terms of +community contributions. Additionally, release artifacts and installers are not +provided, but there may be community infrastructure producing these in +unofficial locations. + +| Target | std |rustc|cargo| notes | +|-------------------------------|-----|-----|-----|----------------------------| +| `x86_64-unknown-linux-musl` | ✓ | | | 64-bit Linux with MUSL | +| `arm-linux-androideabi` | ✓ | | | ARM Android | +| `i686-linux-android` | ✓ | | | 32-bit x86 Android | +| `aarch64-linux-android` | ✓ | | | ARM64 Android | +| `arm-unknown-linux-gnueabi` | ✓ | ✓ | | ARM Linux (2.6.18+) | +| `arm-unknown-linux-gnueabihf` | ✓ | ✓ | | ARM Linux (2.6.18+) | +| `aarch64-unknown-linux-gnu` | ✓ | | | ARM64 Linux (2.6.18+) | +| `mips-unknown-linux-gnu` | ✓ | | | MIPS Linux (2.6.18+) | +| `mipsel-unknown-linux-gnu` | ✓ | | | MIPS (LE) Linux (2.6.18+) | +| `powerpc-unknown-linux-gnu` | ✓ | | | PowerPC Linux (2.6.18+) | +| `i386-apple-ios` | ✓ | | | 32-bit x86 iOS | +| `x86_64-apple-ios` | ✓ | | | 64-bit x86 iOS | +| `armv7-apple-ios` | ✓ | | | ARM iOS | +| `armv7s-apple-ios` | ✓ | | | ARM iOS | +| `aarch64-apple-ios` | ✓ | | | ARM64 iOS | +| `i686-unknown-freebsd` | ✓ | ✓ | | 32-bit FreeBSD | +| `x86_64-unknown-freebsd` | ✓ | ✓ | | 64-bit FreeBSD | +| `x86_64-unknown-openbsd` | ✓ | ✓ | | 64-bit OpenBSD | +| `x86_64-unknown-netbsd` | ✓ | ✓ | | 64-bit NetBSD | +| `x86_64-unknown-bitrig` | ✓ | ✓ | | 64-bit Bitrig | +| `x86_64-unknown-dragonfly` | ✓ | ✓ | | 64-bit DragonFlyBSD | +| `x86_64-rumprun-netbsd` | ✓ | | | 64-bit NetBSD Rump Kernel | +| `i686-pc-windows-msvc` (XP) | ✓ | | | Windows XP support | +| `x86_64-pc-windows-msvc` (XP) | ✓ | | | Windows XP support | + +Note that this table can be expanded over time, this isn't the exhaustive set of +tier 3 platforms that will ever be! + +## Installing on Linux or Mac + +If we're on Linux or a Mac, all we need to do is open a terminal and type this: + +```bash +$ curl -sSf https://static.rust-lang.org/rustup.sh | sh +``` + +This will download a script, and stat the installation. If it all goes well, +you’ll see this appear: + +```text +Welcome to Rust. + +This script will download the Rust compiler and its package manager, Cargo, and +install them to /usr/local. You may install elsewhere by running this script +with the --prefix= option. + +The installer will run under ‘sudo’ and may ask you for your password. If you do +not want the script to run ‘sudo’ then pass it the --disable-sudo flag. + +You may uninstall later by running /usr/local/lib/rustlib/uninstall.sh, +or by running this script again with the --uninstall flag. + +Continue? (y/N) +``` + +From here, press `y` for ‘yes’, and then follow the rest of the prompts. + +## Installing on Windows + +If you're on Windows, please download the appropriate [installer][install-page]. + +[install-page]: https://www.rust-lang.org/install.html + +## Uninstalling + +Uninstalling Rust is as easy as installing it. On Linux or Mac, just run +the uninstall script: + +```bash +$ sudo /usr/local/lib/rustlib/uninstall.sh +``` + +If we used the Windows installer, we can re-run the `.msi` and it will give us +an uninstall option. + +## Troubleshooting + +If we've got Rust installed, we can open up a shell, and type this: + +```bash +$ rustc --version +``` + +You should see the version number, commit hash, and commit date. + +If you do, Rust has been installed successfully! Congrats! + +If you don't and you're on Windows, check that Rust is in your %PATH% system +variable. If it isn't, run the installer again, select "Change" on the "Change, +repair, or remove installation" page and ensure "Add to PATH" is installed on +the local hard drive. + +If not, there are a number of places where we can get help. The easiest is +[the #rust IRC channel on irc.mozilla.org][irc], which we can access through +[Mibbit][mibbit]. Click that link, and we'll be chatting with other Rustaceans +(a silly nickname we call ourselves) who can help us out. Other great resources +include [the user’s forum][users], and [Stack Overflow][stackoverflow]. + +[irc]: irc://irc.mozilla.org/#rust +[mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust +[users]: https://users.rust-lang.org/ +[stackoverflow]: http://stackoverflow.com/questions/tagged/rust + +This installer also installs a copy of the documentation locally, so we 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 the directory to which Rust +was installed. + +# Hello, world! + +Now that you have Rust installed, we'll help you write your first Rust program. +It's traditional when learning a new language to write a little program to +print the text “Hello, world!” to the screen, and in this section, we'll follow +that tradition. + +The nice thing about starting with such a simple program is that you can +quickly verify that your compiler is installed, and that it's working properly. +Printing information to the screen is also just a pretty common thing to do, so +practicing it early on is good. + +> Note: This book assumes basic familiarity with the command line. Rust itself +> makes no specific demands about your editing, tooling, or where your code +> lives, so if you prefer an IDE to the command line, that's an option. You may +> want to check out [SolidOak], which was built specifically with Rust in mind. +> There are a number of extensions in development by the community, and the +> Rust team ships plugins for [various editors]. Configuring your editor or +> IDE is out of the scope of this tutorial, so check the documentation for your +> specific setup. + +[SolidOak]: https://github.com/oakes/SolidOak +[various editors]: https://github.com/rust-lang/rust/blob/master/src/etc/CONFIGS.md + +## Creating a Project File + +First, make a file to put your Rust code in. Rust doesn't care where your code +lives, but for this book, I suggest making a *projects* directory in your home +directory, and keeping all your projects there. Open a terminal and enter the +following commands to make a directory for this particular project: + +```bash +$ mkdir ~/projects +$ cd ~/projects +$ mkdir hello_world +$ cd hello_world +``` + +> Note: If you’re on Windows and not using PowerShell, the `~` may not work. +> Consult the documentation for your shell for more details. + +## Writing and Running a Rust Program + +Next, make a new source file and call it *main.rs*. Rust files always end +in a *.rs* extension. If you’re using more than one word in your filename, use +an underscore to separate them; for example, you'd use *hello_world.rs* rather +than *helloworld.rs*. + +Now open the *main.rs* file you just created, and type the following code: + +```rust +fn main() { + println!("Hello, world!"); +} +``` + +Save the file, and go back to your terminal window. On Linux or OSX, enter the +following commands: + +```bash +$ rustc main.rs +$ ./main +Hello, world! +``` + +In Windows, just replace `main` with `main.exe`. Regardless of your operating +system, you should see the string `Hello, world!` print to the terminal. If you +did, then congratulations! You've officially written a Rust program. That makes +you a Rust programmer! Welcome. + +## Anatomy of a Rust Program + +Now, let’s go over what just happened in your "Hello, world!" program in +detail. Here's the first piece of the puzzle: + +```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` that 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. + +Also note that the function body is wrapped in curly braces (`{` and `}`). Rust +requires these around all function bodies. It's considered good style to put +the opening curly brace on the same line as the function declaration, with one +space in between. + +Inside the `main()` function: + +```rust + println!("Hello, world!"); +``` + +This line does all of the work in this little program: it prints text to the +screen. There are a number of details that are important here. The first is +that it’s indented with four spaces, not tabs. + +The second important part is the `println!()` line. This is calling a Rust +*[macro]*, which is how metaprogramming is done in Rust. If it were calling a +function instead, it would look like this: `println()` (without the !). We'll +discuss Rust macros in more detail later, but for now you just need to +know that when you see a `!` that means that you’re calling a macro instead of +a normal function. + + +[macro]: macros.html + +Next is `"Hello, world!"` which is a *string*. Strings are a surprisingly +complicated topic in a systems programming language, and this is a *[statically +allocated]* string. We pass this string as an argument to `println!`, which +prints the string to the screen. Easy enough! + +[statically allocated]: the-stack-and-the-heap.html + +The line ends with a semicolon (`;`). Rust is an *[expression oriented]* +language, which means that most things are expressions, rather than statements. +The `;` indicates that this expression is over, and the next one is ready to +begin. Most lines of Rust code end with a `;`. + +[expression-oriented language]: glossary.html#expression-oriented-language + +## Compiling and Running Are Separate Steps + +In "Writing and Running a Rust Program", we showed you how to run a newly +created program. We'll break that process down and examine each step now. + +Before running a Rust program, you have to compile it. You can use the Rust +compiler by entering the `rustc` command and passing it the name of your source +file, like this: + +```bash +$ rustc main.rs +``` + +If you come from a C or C++ background, you'll notice that this is similar to +`gcc` or `clang`. After compiling successfully, Rust should output a binary +executable, which you can see on Linux or OSX by entering the `ls` command in +your shell as follows: + +```bash +$ ls +main main.rs +``` + +On Windows, you'd enter: + +```bash +$ dir +main.exe main.rs +``` + +This shows we have two files: the source code, with an `.rs` extension, and the +executable (`main.exe` on Windows, `main` everywhere else). All that's left to +do from here is run the `main` or `main.exe` file, like this: + +```bash +$ ./main # or main.exe on Windows +``` + +If *main.rs* were your "Hello, world!" program, this would print `Hello, +world!` to your terminal. + +If you come from a dynamic language like Ruby, Python, or JavaScript, you may +not be used to compiling and running a program being separate steps. Rust is an +*ahead-of-time compiled* language, which means that you can compile a program, +give it to someone else, and they can run it even without Rust installed. If +you give someone a `.rb` or `.py` or `.js` file, on the other hand, they need +to have a Ruby, Python, or JavaScript implementation installed (respectively), +but you only need one command to both compile and run your program. Everything +is a tradeoff in language design. + +Just compiling with `rustc` is fine for simple programs, but as your project +grows, you'll want to be able to manage all of the options your project has, +and make it easy to share your code with other people and projects. Next, I'll +introduce you to a tool called Cargo, which will help you write real-world Rust +programs. + +# Hello, Cargo! + +Cargo is Rust’s build system and package manager, and Rustaceans use Cargo to +manage their Rust projects. Cargo manages three things: building your code, +downloading the libraries your code depends on, and building those libraries. +We call libraries your code needs ‘dependencies’ since your code depends on +them. + +The simplest Rust programs don’t have any dependencies, so right now, you'd +only use the first part of its functionality. As you write more complex Rust +programs, you’ll want to add dependencies, and if you start off using Cargo, +that will be a lot easier to do. + +As the vast, vast majority of Rust projects use Cargo, we will assume that +you’re using it for the rest of the book. Cargo comes installed with Rust +itself, if you used the official installers. If you installed Rust through some +other means, you can check if you have Cargo installed by typing: + +```bash +$ cargo --version +``` + +Into a terminal. If you see a version number, great! If you see an error like +‘`command not found`’, then you should look at the documentation for the system +in which you installed Rust, to determine if Cargo is separate. + +## Converting to Cargo + +Let’s convert the Hello World program to Cargo. To Cargo-fy a project, you need +to do three things: + +1. Put your source file in the right directory. +2. Get rid of the old executable (`main.exe` on Windows, `main` everywhere else) + and make a new one. +3. Make a Cargo configuration file. + +Let's get started! + +### Creating a new Executable and Source Directory + +First, go back to your terminal, move to your *hello_world* directory, and +enter the following commands: + +```bash +$ mkdir src +$ mv main.rs src/main.rs +$ rm main # or 'del main.exe' on Windows +``` + +Cargo expects your source files to live inside a *src* directory, so do that +first. This leaves the top-level project directory (in this case, +*hello_world*) for READMEs, license information, and anything else not related +to your code. In this way, using Cargo helps you keep your projects nice and +tidy. There's a place for everything, and everything is in its place. + +Now, copy *main.rs* to the *src* directory, and delete the compiled file you +created with `rustc`. As usual, replace `main` with `main.exe` if you're on +Windows. + +This example retains `main.rs` as the source filename because it's creating an +executable. If you wanted to make a library instead, you'd name the file +`lib.rs`. This convention is used by Cargo to successfully compile your +projects, but it can be overridden if you wish. + +### Creating a Configuration File + +Next, create a new file inside your *hello_world* directory, and call it +`Cargo.toml`. + +Make sure to capitalize the `C` in `Cargo.toml`, or Cargo won't know what to do +with the configuration file. + +This file is in the *[TOML]* (Tom's Obvious, Minimal Language) format. TOML is +similar to INI, but has some extra goodies, and is used as Cargo’s +configuration format. + +[TOML]: https://github.com/toml-lang/toml + +Inside this file, type the following information: + +```toml +[package] + +name = "hello_world" +version = "0.0.1" +authors = [ "Your name " ] +``` + +The first line, `[package]`, indicates that the following statements are +configuring a package. As we add more information to this file, we’ll add other +sections, but for now, we just have the package configuration. + +The other three lines set the three bits of configuration that Cargo needs to +know to compile your program: its name, what version it is, and who wrote it. + +Once you've added this information to the *Cargo.toml* file, save it to finish +creating the configuration file. + +## Building and Running a Cargo Project + +With your *Cargo.toml* file in place in your project's root directory, you +should be ready to build and run your Hello World program! To do so, enter the +following commands: + +```bash +$ cargo build + Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world) +$ ./target/debug/hello_world +Hello, world! +``` + +Bam! If all goes well, `Hello, world!` should print to the terminal once more. + +You just built a project with `cargo build` and ran it with +`./target/debug/hello_world`, but you can actually do both in one step with +`cargo run` as follows: + +```bash +$ cargo run + Running `target/debug/hello_world` +Hello, world! +``` + +Notice that this example didn’t re-build the project. Cargo figured out that +the file hasn’t changed, and so it just ran the binary. If you'd modified your +source code, Cargo would have rebuilt the project before running it, and you +would have seen something like this: + +```bash +$ cargo run + Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world) + Running `target/debug/hello_world` +Hello, world! +``` + +Cargo checks to see if any of your project’s files have been modified, and only +rebuilds your project if they’ve changed since the last time you built it. + +With simple projects, Cargo doesn't bring a whole lot over just using `rustc`, +but it will become useful in future. With complex projects composed of multiple +crates, it’s much easier to let Cargo coordinate the build. With Cargo, you can +just run `cargo build`, and it should work the right way. + +## Building for Release + +When your project is finally ready for release, you can use `cargo build +--release` to compile your project with optimizations. These optimizations make +your Rust code run faster, but turning them on makes your program take longer +to compile. This is why there are two different profiles, one for development, +and one for building the final program you’ll give to a user. + +Running this command also causes Cargo to create a new file called +*Cargo.lock*, which looks like this: + +```toml +[root] +name = "hello_world" +version = "0.0.1" +``` + +Cargo uses the *Cargo.lock* file to keep track of dependencies in your +application. This is the Hello World project's *Cargo.lock* file. This project +doesn't have dependencies, so the file is a bit sparse. Realistically, you +won't ever need to touch this file yourself; just let Cargo handle it. + +That’s it! If you've been following along, you should have successfully built +`hello_world` with Cargo. + +Even though the project is simple, it now uses much of the real tooling you’ll +use for the rest of your Rust career. In fact, you can expect to start +virtually all Rust projects with some variation on the following commands: + +```bash +$ git clone someurl.com/foo +$ cd foo +$ cargo build +``` + +## Making A New Cargo Project the Easy Way + +You don’t have to go through that previous process every time you want to start +a new project! Cargo can quickly make a bare-bones project directory that you +can start developing in right away. + +To start a new project with Cargo, enter `cargo new` at the command line: + +```bash +$ cargo new hello_world --bin +``` + +This command passes `--bin` because the 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). + +Cargo has generated two files and one directory for us: a `Cargo.toml` and a +*src* directory with a *main.rs* file inside. These should look familliar, +they’re exactly what we created by hand, above. + +This output is all you need to get started. First, open `Cargo.toml`. It should +look something like this: + +```toml +[package] + +name = "hello_world" +version = "0.1.0" +authors = ["Your Name "] +``` + +Cargo has populated *Cargo.toml* with reasonable defaults based on 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 should be in `src/main.rs`: + +```rust +fn main() { + println!("Hello, world!"); +} +``` + +Cargo has generated a "Hello World!" for you, and you’re ready to start coding! + +> Note: If you want to look at Cargo in more detail, check out the official [Cargo +guide], which covers all of its features. + +[Cargo guide]: http://doc.crates.io/guide.html + +# Closing Thoughts + +This chapter covered the basics that will serve you well through the rest of +this book, and the rest of your time with Rust. Now that you’ve got the tools +down, we'll cover more about the Rust language itself. + +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 diff --git a/src/doc/trpl/hello-cargo.md b/src/doc/trpl/hello-cargo.md deleted file mode 100644 index 97bc4575f81f7..0000000000000 --- a/src/doc/trpl/hello-cargo.md +++ /dev/null @@ -1,210 +0,0 @@ -% Hello, Cargo! - -[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]: http://doc.crates.io - -Cargo manages three things: building our code, downloading the dependencies our -code needs, and building those dependencies. At first, our 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][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. - -To Cargo-ify our project, we need to do three things: Make a `Cargo.toml` -configuration file, put our source file in the right place, and get rid of the -old executable (`main.exe` on Windows, `main` everywhere else). Let's do that part first: - -```bash -$ mkdir src -$ mv main.rs src/main.rs -$ rm main # or 'del main.exe' on Windows -``` - -> 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 - -Cargo expects our source files to live inside a `src` directory. That leaves the -top level for other things, like READMEs, license information, and anything not -related to our code. Cargo helps us keep our projects nice and tidy. A place for -everything, and everything in its place. - -Next, our configuration file: - -```bash -$ editor Cargo.toml # or 'notepad Cargo.toml' on Windows -``` - -Make sure to get this name right: we need the capital `C`! - -Put this inside: - -```toml -[package] - -name = "hello_world" -version = "0.0.1" -authors = [ "Your name " ] -``` - -This file is in the [TOML][toml] format. TOML is similar to INI, but has some -extra goodies. According to the TOML docs, - -> 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. -> TOML should be easy to parse into data structures in a wide variety of -> languages. - -[toml]: https://github.com/toml-lang/toml - -Once we have this file in place in our project's root directory, we should be -ready to build! To do so, run: - -```bash -$ cargo build - Compiling hello_world v0.0.1 (file:///home/yourname/projects/hello_world) -$ ./target/debug/hello_world -Hello, world! -``` - -Bam! We built our project with `cargo build`, and ran it with -`./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 run - 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 need to do more -things to get all of the parts to properly compile. With Cargo, as our project -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. - -You'll also notice that Cargo has created a new file: `Cargo.lock`. - -```toml -[root] -name = "hello_world" -version = "0.0.1" -``` - -The `Cargo.lock` file is used by Cargo to keep track of dependencies in our -application. Right now, we don’t have any, so it’s a bit sparse. We won't ever -need to touch this file ourselves, 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 we’ll use for the -rest of our Rust career. We 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 - -We don’t have to go through this whole process every time we want to start a new -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, we use `cargo new`: - -```bash -$ cargo new hello_world --bin -``` - -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 we’re on a Unix system) - -Let's check out what Cargo has generated for us: - -```bash -$ cd hello_world -$ tree . -. -├── Cargo.toml -└── src - └── main.rs - -1 directory, 2 files -``` - -If we don't have the `tree` command, we can probably get it from our -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`: - -```toml -[package] - -name = "hello_world" -version = "0.1.0" -authors = ["Your Name "] -``` - -Cargo has populated this file with reasonable defaults based off the arguments -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`: - -```rust -fn main() { - println!("Hello, world!"); -} -``` - -Cargo has generated a "Hello World!" for us, and we’re ready to start coding! -Cargo has its own [guide][guide] which covers Cargo’s features in much more -depth. - -[guide]: http://doc.crates.io/guide.html - -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. - -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 diff --git a/src/doc/trpl/hello-world.md b/src/doc/trpl/hello-world.md deleted file mode 100644 index 2f9166751d965..0000000000000 --- a/src/doc/trpl/hello-world.md +++ /dev/null @@ -1,171 +0,0 @@ -% Hello, world! - -Now that we have Rust installed, let’s write our first Rust program. It’s -traditional to make our 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 we can verify that our compiler isn’t just installed, but -also working properly. And printing information to the screen is a pretty common -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 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 -no specific demands on our editing tooling, or where our code lives. If we -prefer an IDE to the command line, we may want to check out -[SolidOak][solidoak], or wherever plugins are for our 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 our -editor or IDE is out of the scope of this tutorial, so check the documentation -for our setup, specifically. - -[solidoak]: https://github.com/oakes/SolidOak -[plugins]: https://github.com/rust-lang/rust/blob/master/src/etc/CONFIGS.md - -With that said, let’s make a directory in our projects directory. - -```bash -$ mkdir ~/projects -$ cd ~/projects -$ mkdir hello_world -$ cd hello_world -``` - -If we’re on Windows and not using PowerShell, the `~` may not work. Consult the -documentation for our shell for more details. - -Let’s make a new source file next. We’ll call our file `main.rs`. Rust files -always end in a `.rs` extension, and if we’re using more than one word in a -Rust filename, we use an underscore: for example, `linked_list.rs`, not -`linkedlist.rs` or `LinkedList.rs`. - -Now that we’ve got our file open, type this in: - -```rust -fn main() { - println!("Hello, world!"); -} -``` - -Save the file, and then type this into our terminal window: - -```bash -$ rustc main.rs -$ ./main # or main.exe on Windows -Hello, world! -``` - -Success! Let’s go over what just happened in detail. - -```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 -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. - -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 - 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 -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 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 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! - -[allocation]: the-stack-and-the-heap.html - -Finally, the line ends with a semicolon (`;`). Rust is an [‘expression oriented’ -language][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 `;`. - -[expression-oriented language]: glossary.html#expression-oriented-language - -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. We can see it with `ls`: - -```bash -$ ls -main main.rs -``` - -Or on Windows: - -```bash -$ dir -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 -$ ./main # or main.exe on Windows -``` - -This prints out our `Hello, world!` text to our terminal. - -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! You have officially written a Rust program. That makes you a -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 -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 -projects. diff --git a/src/doc/trpl/installing-rust.md b/src/doc/trpl/installing-rust.md deleted file mode 100644 index 49ee5317c7883..0000000000000 --- a/src/doc/trpl/installing-rust.md +++ /dev/null @@ -1,184 +0,0 @@ -% 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 we're on Linux -or a Mac, all we need to do is this: - -> Note: we don't need to type in the `$`s, they are there to indicate the start of -> each command. We’ll see many tutorials and examples around the web that -> follow this convention: `$` for commands run as our regular user, and `#` for -> commands we should be running as an administrator. - -```bash -$ curl -sf -L https://static.rust-lang.org/rustup.sh | sh -``` - -If we're concerned about the [potential insecurity][insecurity] of using `curl | -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 -$ sh rustup.sh -``` - -[insecurity]: http://curlpipesh.tumblr.com - -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 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 can run the -uninstall script: - -```bash -$ sudo /usr/local/lib/rustlib/uninstall.sh -``` - -If we used the Windows installer, we can 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`. Their concern is that `curl | sh` implicitly requires you to trust -that the good people who maintain Rust aren't going to hack your computer and -do bad things — and even having accepted that, there is still the possibility -that the Rust website has been hacked and the `rustup` script compromised. - -Being wary of such possibilities is a good instinct! If you're uncomfortable -using `curl | sh` for reasons like these, 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 - -## Platform support - -The Rust compiler runs on, and compiles to, a great number of platforms, though -not all platforms are equally supported. Rust's support levels are organized -into three tiers, each with a different set of guarantees. - -Platforms are identified by their "target triple" which is the string to inform -the compiler what kind of output should be produced. The columns below indicate -whether the corresponding component works on the specified platform. - -### Tier 1 - -Tier 1 platforms can be thought of as "guaranteed to build and work". -Specifically they will each satisfy the following requirements: - -* Automated testing is set up to run tests for the platform. -* Landing changes to the `rust-lang/rust` repository's master branch is gated on - tests passing. -* Official release artifacts are provided for the platform. -* Documentation for how to use and how to build the platform is available. - -| Target | std |rustc|cargo| notes | -|-------------------------------|-----|-----|-----|----------------------------| -| `x86_64-pc-windows-msvc` | ✓ | ✓ | ✓ | 64-bit MSVC (Windows 7+) | -| `i686-pc-windows-gnu` | ✓ | ✓ | ✓ | 32-bit MinGW (Windows 7+) | -| `x86_64-pc-windows-gnu` | ✓ | ✓ | ✓ | 64-bit MinGW (Windows 7+) | -| `i686-apple-darwin` | ✓ | ✓ | ✓ | 32-bit OSX (10.7+, Lion+) | -| `x86_64-apple-darwin` | ✓ | ✓ | ✓ | 64-bit OSX (10.7+, Lion+) | -| `i686-unknown-linux-gnu` | ✓ | ✓ | ✓ | 32-bit Linux (2.6.18+) | -| `x86_64-unknown-linux-gnu` | ✓ | ✓ | ✓ | 64-bit Linux (2.6.18+) | - -### Tier 2 - -Tier 2 platforms can be thought of as "guaranteed to build". Automated tests are -not run so it's not guaranteed to produce a working build, but platforms often -work to quite a good degree and patches are always welcome! Specifically, these -platforms are required to have each of the following: - -* Automated building is set up, but may not be running tests. -* Landing changes to the `rust-lang/rust` repository's master branch is gated on - platforms **building**. Note that this means for some platforms only the - standard library is compiled, but for others the full bootstrap is run. -* Official release artifacts are provided for the platform. - -| Target | std |rustc|cargo| notes | -|-------------------------------|-----|-----|-----|----------------------------| -| `i686-pc-windows-msvc` | ✓ | ✓ | ✓ | 32-bit MSVC (Windows 7+) | - -### Tier 3 - -Tier 3 platforms are those which Rust has support for, but landing changes is -not gated on the platform either building or passing tests. Working builds for -these platforms may be spotty as their reliability is often defined in terms of -community contributions. Additionally, release artifacts and installers are not -provided, but there may be community infrastructure producing these in -unofficial locations. - -| Target | std |rustc|cargo| notes | -|-------------------------------|-----|-----|-----|----------------------------| -| `x86_64-unknown-linux-musl` | ✓ | | | 64-bit Linux with MUSL | -| `arm-linux-androideabi` | ✓ | | | ARM Android | -| `i686-linux-android` | ✓ | | | 32-bit x86 Android | -| `aarch64-linux-android` | ✓ | | | ARM64 Android | -| `arm-unknown-linux-gnueabi` | ✓ | ✓ | | ARM Linux (2.6.18+) | -| `arm-unknown-linux-gnueabihf` | ✓ | ✓ | | ARM Linux (2.6.18+) | -| `aarch64-unknown-linux-gnu` | ✓ | | | ARM64 Linux (2.6.18+) | -| `mips-unknown-linux-gnu` | ✓ | | | MIPS Linux (2.6.18+) | -| `mipsel-unknown-linux-gnu` | ✓ | | | MIPS (LE) Linux (2.6.18+) | -| `powerpc-unknown-linux-gnu` | ✓ | | | PowerPC Linux (2.6.18+) | -| `i386-apple-ios` | ✓ | | | 32-bit x86 iOS | -| `x86_64-apple-ios` | ✓ | | | 64-bit x86 iOS | -| `armv7-apple-ios` | ✓ | | | ARM iOS | -| `armv7s-apple-ios` | ✓ | | | ARM iOS | -| `aarch64-apple-ios` | ✓ | | | ARM64 iOS | -| `i686-unknown-freebsd` | ✓ | ✓ | | 32-bit FreeBSD | -| `x86_64-unknown-freebsd` | ✓ | ✓ | | 64-bit FreeBSD | -| `x86_64-unknown-openbsd` | ✓ | ✓ | | 64-bit OpenBSD | -| `x86_64-unknown-netbsd` | ✓ | ✓ | | 64-bit NetBSD | -| `x86_64-unknown-bitrig` | ✓ | ✓ | | 64-bit Bitrig | -| `x86_64-unknown-dragonfly` | ✓ | ✓ | | 64-bit DragonFlyBSD | -| `x86_64-rumprun-netbsd` | ✓ | | | 64-bit NetBSD Rump Kernel | -| `i686-pc-windows-msvc` (XP) | ✓ | | | Windows XP support | -| `x86_64-pc-windows-msvc` (XP) | ✓ | | | Windows XP support | - -Note that this table can be expanded over time, this isn't the exhaustive set of -tier 3 platforms that will ever be! - -## After installation - -If we've got Rust installed, we can open up a shell, and type this: - -```bash -$ rustc --version -``` - -You should see the version number, commit hash, and commit date. - -If you do, Rust has been installed successfully! Congrats! - -If you don't and you're on Windows, check that Rust is in your %PATH% system -variable. If it isn't, run the installer again, select "Change" on the "Change, -repair, or remove installation" page and ensure "Add to PATH" is installed on -the local hard drive. - -This installer also installs a copy of the documentation locally, so we 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 the directory to which Rust was -installed. - -If not, there are a number of places where we can get help. The easiest is -[the #rust IRC channel on irc.mozilla.org][irc], which we can access through -[Mibbit][mibbit]. Click that link, and we'll be chatting with other Rustaceans -(a silly nickname we call ourselves) who can help us out. Other great resources -include [the user’s forum][users], and [Stack Overflow][stackoverflow]. - -[irc]: irc://irc.mozilla.org/#rust -[mibbit]: http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust -[users]: https://users.rust-lang.org/ -[stackoverflow]: http://stackoverflow.com/questions/tagged/rust diff --git a/src/doc/trpl/method-syntax.md b/src/doc/trpl/method-syntax.md index d31d823247082..41c134b29f3d1 100644 --- a/src/doc/trpl/method-syntax.md +++ b/src/doc/trpl/method-syntax.md @@ -43,8 +43,6 @@ fn main() { This will print `12.566371`. - - We’ve made a `struct` that represents a circle. We then write an `impl` block, and inside it, define a method, `area`. @@ -83,6 +81,35 @@ impl Circle { } ``` +You can use as many `impl` blocks as you’d like. The previous example could +have also been written like this: + +```rust +struct Circle { + x: f64, + y: f64, + radius: f64, +} + +impl Circle { + fn reference(&self) { + println!("taking self by reference!"); + } +} + +impl Circle { + fn mutable_reference(&mut self) { + println!("taking self by mutable reference!"); + } +} + +impl Circle { + fn takes_ownership(self) { + println!("taking ownership of self!"); + } +} +``` + # Chaining method calls So, now we know how to call a method, such as `foo.bar()`. But what about our diff --git a/src/libcollections/slice.rs b/src/libcollections/slice.rs index ea4830fc3e6ce..869e7a0b38393 100644 --- a/src/libcollections/slice.rs +++ b/src/libcollections/slice.rs @@ -732,6 +732,8 @@ impl [T] { /// /// This is equivalent to `self.sort_by(|a, b| a.cmp(b))`. /// + /// This is a stable sort. + /// /// # Examples /// /// ```rust diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index f1199919fcb0e..9b260b57099bb 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -1565,6 +1565,8 @@ pub trait Iterator { /// as soon as it finds a `false`, given that no matter what else happens, /// the result will also be `false`. /// + /// An empty iterator returns `true`. + /// /// # Examples /// /// Basic usage: @@ -1613,6 +1615,8 @@ pub trait Iterator { /// as soon as it finds a `true`, given that no matter what else happens, /// the result will also be `true`. /// + /// An empty iterator returns `false`. + /// /// # Examples /// /// Basic usage: @@ -2071,6 +2075,8 @@ pub trait Iterator { /// /// Takes each element, adds them together, and returns the result. /// + /// An empty iterator returns the zero value of the type. + /// /// # Examples /// /// Basic usage: @@ -2094,6 +2100,8 @@ pub trait Iterator { /// Iterates over the entire iterator, multiplying all the elements /// + /// An empty iterator returns the one value of the type. + /// /// # Examples /// /// ``` diff --git a/src/libstd/collections/hash/map.rs b/src/libstd/collections/hash/map.rs index 7c6add80337c0..965226f6355c2 100644 --- a/src/libstd/collections/hash/map.rs +++ b/src/libstd/collections/hash/map.rs @@ -601,6 +601,9 @@ impl HashMap /// Returns the number of elements the map can hold without reallocating. /// + /// This number is a lower bound; the `HashMap` might be able to hold + /// more, but is guaranteed to be able to hold at least this many. + /// /// # Examples /// /// ``` diff --git a/src/test/run-pass/issue-24954.rs b/src/test/run-pass/issue-24954.rs new file mode 100644 index 0000000000000..f525274a1dfca --- /dev/null +++ b/src/test/run-pass/issue-24954.rs @@ -0,0 +1,22 @@ +// Copyright 2015 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +macro_rules! foo { + ($y:expr) => ({ + $y = 2; + }) +} + +#[allow(unused_variables)] +#[allow(unused_assignments)] +fn main() { + let mut x = 1; + foo!(x); +}