Auto merge of #30295 - jseyfried:fix_extern_crate_duplicate, r=nrc

[rust.git] / README.md

diff --git a/README.md b/README.md
index 5e208a76e0315eece69a710b50b6daa94758f1cf..7558065831ace3e52982e76bf9f849d6f7232ff2 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,13 +1,9 @@
 # The Rust Programming Language
 
-Rust is a fast systems programming language that guarantees
-memory safety and offers painless concurrency ([no data races]).
-It does not employ a garbage collector and has minimal runtime overhead.
+This is the main source code repository for [Rust]. It contains the compiler, standard library,
+and documentation.
 
-This repo contains the code for the compiler (`rustc`), as well
-as standard libraries, tools and documentation for Rust.
-
-[no data races]: http://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html
+[Rust]: https://www.rust-lang.org
 
 ## Quick Start
 
@@ -57,6 +53,16 @@ Read ["Installing Rust"] from [The Book].
 
 ### Building on Windows
 
+There are two prominent ABIs in use on Windows: the native (MSVC) ABI used by
+Visual Studio, and the GNU ABI used by the GCC toolchain. Which version of Rust
+you need depends largely on what C/C++ libraries you want to interoperate with:
+for interop with software produced by Visual Studio use the MSVC build of Rust;
+for interop with GNU software built using the MinGW/MSYS2 toolchain use the GNU
+build.
+
+
+#### MinGW
+
 [MSYS2](http://msys2.github.io/) can be used to easily build Rust on Windows:
 
 1. Grab the latest MSYS2 installer and go through the installer.
@@ -67,12 +73,15 @@ Read ["Installing Rust"] from [The Book].
    ```sh
    # Update package mirrors (may be needed if you have a fresh install of MSYS2)
    $ pacman -Sy pacman-mirrors
+   ```
 
-   # Choose one based on platform: 
-   # *** see the note below ***
-   $ pacman -S mingw-w64-i686-toolchain
-   $ pacman -S mingw-w64-x86_64-toolchain
+Download [MinGW from
+here](http://mingw-w64.org/doku.php/download/mingw-builds), and choose the
+`threads=win32,exceptions=dwarf/seh` flavor when installing. After installing,
+add its `bin` directory to your `PATH`. This is due to #28260, in the future,
+installing from pacman should be just fine.
 
+   ```
    # Make git available in MSYS2 (if not already available on path)
    $ pacman -S git
 
@@ -88,16 +97,19 @@ Read ["Installing Rust"] from [The Book].
    $ ./configure
    $ make && make install
    ```
-> ***Note:*** gcc versions >= 5 currently have issues building LLVM on Windows
-> resulting in a segmentation fault when building Rust. In order to avoid this
-> it may be necessary to obtain an earlier version of gcc such as 4.9.x.  
-> Msys's `pacman` will install the latest version, so for the time being it is
-> recommended to skip gcc toolchain installation step above and use [Mingw-Builds]
-> project's installer instead.  Be sure to add gcc `bin` directory to the path
-> before running `configure`.  
-> For more information on this see issue #28260.
 
-[Mingw-Builds]: http://sourceforge.net/projects/mingw-w64/
+#### MSVC
+
+MSVC builds of Rust additionally require an installation of Visual Studio 2013
+(or later) so `rustc` can use its linker. Make sure to check the “C++ tools”
+option. In addition, `cmake` needs to be installed to build LLVM.
+
+With these dependencies installed, the build takes two steps:
+
+```sh
+$ ./configure
+$ make && make install
+```
 
 ## Building Documentation
 
@@ -139,7 +151,7 @@ Snapshot binaries are currently built and tested on several platforms:
 You may find that other platforms work, but these are our officially
 supported build environments that are most likely to work.
 
-Rust currently needs about 1.5 GiB of RAM to build without swapping; if it hits
+Rust currently needs between 600MiB and 1.5GiB to build, depending on platform. If it hits
 swap, it will take a very long time to build.
 
 There is more advice about hacking on Rust in [CONTRIBUTING.md].