From 8d64fa328839c4fcce43c1b01164090ac36edc13 Mon Sep 17 00:00:00 2001 From: Jack Moffitt Date: Thu, 18 Jul 2013 17:27:43 -0600 Subject: [PATCH] Reorganize README to make it more clear. This also adds a note about required memory usage and instructions for building from Git. --- README.md | 115 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 67 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index f01ed1958c6..30ad2bd112f 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,72 @@ This is a compiler for Rust, including standard libraries, tools and documentation. +## Quick Start -## Installation +### Windows -The Rust compiler currently must be built from a [tarball], unless you -are on Windows, in which case using the [installer][win-exe] is -recommended. +1. Download and use the [installer][win-exe]. +2. Read the [tutorial]. +2. Enjoy! -Since the Rust compiler is written in Rust, it must be built by -a precompiled "snapshot" version of itself (made in an earlier state -of development). As such, source builds require a connection to -the Internet, to fetch snapshots, and an OS that can execute the -available snapshot binaries. +> ***Note:*** Windows users should read the detailed +> [getting started][wiki-start] notes on the wiki. Even when using +> the binary installer the Windows build requires a MinGW installation, +> the precise details of which are not discussed here. + +[tutorial]: http://static.rust-lang.org/doc/tutorial.html +[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust +[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe + +### Linux / OS X + +1. Install the prerequisites (if not already installed) + * g++ 4.4 or clang++ 3.x + * python 2.6 or later (but not 3.x) + * perl 5.0 or later + * gnu make 3.81 or later + * curl +2. Download and build Rust + You can either download a [tarball] or build directly from the [repo]. + + To build from the [tarball] do: + + $ curl -O http://static.rust-lang.org/dist/rust-0.7.tar.gz + $ tar -xzf rust-0.7.tar.gz + $ cd rust-0.7 + + Or to build from the [repo] do: + + $ git clone https://github.com/mozilla/rust.git + $ cd rust + + Now that you have Rust's source code, you can configure and build it: + + $ ./configure + $ make && make install + + You may need to use `sudo make install` if you do not normally have + permission to modify the destination directory. The install locations can + be adjusted by passing a `--prefix` argument to `configure`. Various other + options are also supported, pass `--help` for more information on them. + + When complete, `make install` will place several programs into + `/usr/local/bin`: `rustc`, the Rust compiler; `rustdoc`, the + API-documentation tool, and `rustpkg`, the Rust package manager and build + system. +3. Read the [tutorial]. +4. Enjoy! + +[repo]: https://github.com/mozilla/rust +[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz +[tutorial]: http://static.rust-lang.org/doc/tutorial.html + +## Notes + +Since the Rust compiler is written in Rust, it must be built by a +precompiled "snapshot" version of itself (made in an earlier state of +development). As such, source builds require a connection to the Internet, to +fetch snapshots, and an OS that can execute the available snapshot binaries. Snapshot binaries are currently built and tested on several platforms: @@ -25,42 +79,12 @@ Snapshot binaries are currently built and tested on several platforms: You may find that other platforms work, but these are our "tier 1" supported build environments that are most likely to work. -> ***Note:*** Windows users should read the detailed -> [getting started][wiki-start] notes on the wiki. Even when using -> the binary installer the Windows build requires a MinGW installation, -> the precise details of which are not discussed here. +Rust currently needs about 1.8G of RAM to build without swapping; if it hits +swap, it will take a very long time to build. -To build from source you will also need the following prerequisite -packages: +There is lots more documentation in the [wiki]. -* g++ 4.4 or clang++ 3.x -* python 2.6 or later (but not 3.x) -* perl 5.0 or later -* gnu make 3.81 or later -* curl - -Assuming you're on a relatively modern *nix system and have met the -prerequisites, something along these lines should work. - - $ curl -O http://static.rust-lang.org/dist/rust-0.7.tar.gz - $ tar -xzf rust-0.7.tar.gz - $ cd rust-0.7 - $ ./configure - $ make && make install - -You may need to use `sudo make install` if you do not normally have -permission to modify the destination directory. The install locations -can be adjusted by passing a `--prefix` argument to -`configure`. Various other options are also supported, pass `--help` -for more information on them. - -When complete, `make install` will place several programs into -`/usr/local/bin`: `rustc`, the Rust compiler; `rustdoc`, the -API-documentation tool, and `rustpkg`, the Rust package manager and build system. - -[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust -[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz -[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe +[wiki]: https://github.com/mozilla/rust/wiki ## License @@ -71,8 +95,3 @@ BSD-like licenses. See LICENSE-APACHE, LICENSE-MIT, and COPYRIGHT for details. -## More help - -The [tutorial] is a good starting point. - -[tutorial]: http://static.rust-lang.org/doc/tutorial.html