Windows build instructions are inconsistent

[brson]

There are multiple instructions for building on Windows, and they are not in agreement, as described here: http://www.reddit.com/r/rust/comments/2e62f6/compiling_rust_on_windows_aka_why_does_this_have/

[retep998]

Here are the steps I follow on Windows. Feel free to use what I say here in the windows build instructions.

1. Install mingw64 from http://sourceforge.net/projects/mingw-w64/files/latest/download.
   Make sure to specify threads=win32 architecture=i686 and exceptions=dwarf.
   If you're trying to build using x64 rust then architecture=x86_64 and exceptions=seh.
2. If you're trying to bootstrap rustc itself to work on the compiler/standard libraries, then install just the msys base system using mingw-get from http://sourceforge.net/projects/mingw/files/Installer/mingw-get-setup.exe/download.
3. If you don't already have Git, then get it from http://msysgit.github.io/.
4. If you're just using Rust then install Rust from http://static.rust-lang.org/dist/rust-nightly-install.exe and then download Cargo from http://static.rust-lang.org/cargo-dist/cargo-nightly-i686-pc-mingw32.tar.gz and extract it to where you installed Rust because it is just easier that way.
5. When using Rust, open up cmd.exe, set your PATH to <Rust>\bin\;<MinGW-w64>\mingw32\bin\;<Git>\bin\;<other stuff>, and use cargo and rustc to your heart's content.
6. When building Rust, open up cmd.exe, set your PATH to <MinGW>\msys\1.0\bin\;<MinGW-w64>\mingw32\bin\;<MinGW-w64>\mingw32\opt\bin\;<Git>\bin\;<other stuff>, followed by sh configure and then use make as you see fit. For x86_64 replace mingw32 in the PATH with mingw64 and do sh configure --target=x86_64-w64-mingw32 --build=x86_64-w64-mingw32 --host=x86_64-w64-mingw32.

[klutzy]

There are three (popular) ways to get build system:

• Download msys2 and run pacman as README.md suggests.
• Download mingw-builds installer (step 1 of @retep998's description above) and also download msys separately (step 2, 5/6 above).
• Download mingw installer and set msys.

I think msys2/pacman is the easiest option for Rust developers.
mingw-builds might be favorable for Rust users who don't need msys. It is described in https://github.com/rust-lang/rust/wiki/Using-Rust-on-Windows. However when you need msys it will confuse you. (It's also possible to use msys2 + mingw-builds binary.)
Also, it seems bad to suggest two different packages depending on use. Should be suggest msys2 for Rust users as well?

mingw is not recommended now, but Note-getting-started-developing-Rust is not updated.
(Wiki also contains historical documents: this and this).

[klutzy]

We may also have to maintain FAQ about this topic:

• What is mingw? mingw-w64? msys? Why do I need msys too? (to run configure and make)
• Differences between mingw and mingw-w64? Should I install mingw-w64 instead of mingw? What is expected if I try to use mingw? (I guess compilation error somewhere due to missing parts on mingw)
• msys1 or msys2? (msys1 also works but has make -j2 bug)
• There are three options on mingw-builds. What should be chosen and why?
• Can I use rustc.exe without msys? (yes if your PATH contains gcc)

[DanielKeep]

(Note: I was the ungrateful bastard who complained on Reddit.)

Edit: I realise there are various pages on contributing to Rust. I haven't gone through these yet; I just wanted to make sure I put a note in this issue that I'm working on some changes to the docs to avoid anyone duplicating the effort.

I've cloned the wiki and modified the information there to be unified and consistent. I'm not sure what to pull on or whatever the process is. If preferred, I can just copy+paste the changes into the wiki directly (it looks like I can edit it). I did want to check in this issue first.

Currently, the changes redirect people visiting both "Building Rust before 0.8 on Windows Systems" and "How to install an unofficial nightly for Windows" to the current pages. I removed the instructions on using Chocolatey, on the basis that there are official nightly builds. I intend to see if there is still a way to do this, and will update accordingly.

The "Using Rust on Windows" page now explains the distinction between MinGW, MinGW-w64, MSYS, MSYS2 and Cygwin, why they are needed, what combinations are possible and how to make this all work. The bolded recommendation on the page is "MSYS2 with MinGW-w64", with separate instructions on installing MinGW-w64 outside of MSYS2. There are also up-to-date instructions on installing and using MinGW and MSYS, since until I tried to compile Rust itself, I wasn't aware there was a problem.

I will check the other official docs as well. Should I put a note in README.md in the source noting the presence of a more thorough set of instructions on the wiki? The wiki instructions are basically just more verbose and explicit than the README.md ones.

[klutzy]

Updated Note getting started developing Rust, since it is directly linked by README.md and it can be primary source of confusion.

@DanielKeep could you upload your work on gist or somewhere? I'd like to see the improvements!

[DanielKeep]

@klutzy I've made a gist out of the changes so far.

I've also noted that the Rust guide doesn't mention Rust's dependence on MinGW at all. Nor does the download page about it, or the installer. Not sure whether something should be done about that, or how.

I've removed the instructions for installing through Chocolatey since there's now a Rust package in the default repository based on actual releases (if someone is using a package manager, presumably they have the wherewithal to check and see if a package is there), and the "nightly" package hasn't been updated in a while.

Finally, I noticed a few minor things in the guide that could be improved on Windows. I know that's in the main source repository, so I'll do a pull request for those separately.

Edit: incidentally, the only change to the "Building pre-0.8 Rust" page was to include a link to more recent instructions.

[mingwandroid]

It's important not to refer to MinGW-w64 as mingw or MinGW, they are entirely different projects by different sets of developers. The same goes for MSYS and MSYS2:

http://stackoverflow.com/questions/25019057/how-are-msys-msys2-and-msysgit-related-to-each-other

[klutzy]

I've just found msys2's mingw-w64-{i386,x86_64}-toolchain is configured as "Thread model: posix". This was known to affect performance (#13501) so we should investigate if it is possible to avoid, or just recommend mingw-builds package instead of pacman...

[mingwandroid]

We will try to build a new MSYS2/MinGW-w64 llvm/clang 3.5 package without POSIX threads in the next few days (i.e. as soon as 3.5 is out).

[vadimcn]

FWIW, I use msys2 + "win32" mingw64 from mingw-builds.
I've installed mingw separately, because msys2's package manager downloads the "posix" flavor of mingw64, which brings in dependency on posix emulation library (libwinpthread). For someone who just wants to play with Rust locally, this may be fine, though.

[mingwandroid]

Well, winpthread may be an issue, seems no one's entirely sure if it's avoidable (and if so, can it be avoided when using --std=c++11, my guess is no). Maybe speeding up the winpthread mutexes is the best course of action; I guess at some point llvm/clang itself may start wanting to "#include " and at that time our hands will be forced.

[DanielKeep]

@mingwandroid I tried to be clear about the difference in the changes I made. I might have used "MinGW" to refer collectively to MinGW and MinGW-w64 in a few places; would "MinGW_" and "MSYS_" as collective terms be reasonable? :)

@klutzy Any comments on my version of the "Using Rust on Windows" page? I don't know if it's too overbearing, or whether there are any procedures for making changes to the Wiki's contents (can you even pull request a GitHub wiki?)