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?)

[vadimcn]

@DanielKeep, the wiki guide is horribly out-of date. I think we should dump it all, and start afresh with instructions in readme.md. I also think we should stop supporting msys/mingw and only support msys2/mingw-w64 going forward. According to @brson, this is what build bots run.

[vadimcn]

Actually, this page looks fine, but all that stuff about pre-0.8 Rust needs to go.

[mdinger]

Actually...I'm not sure if I should note this here, file a bug, or update the file as I'm suggesting...it depends I guess on if you are moving away from the wiki system or not. I'm kinda just trying to note it somewhere so it gets fixed eventually.

Here in Makefile.in, there are 2 links and the 1st doesn't exist. I think these pop up if you do make tips when building rust. I suspect it should point here.

[mingwandroid]

@DanielKeep : I'd actually rather we have a complete disassociation between the old mingw/msys and the new ones to be honest with you. If you can, just explicitly call them MSYS2/MinGW-w64, anything else muddies the waters for no gain, cf: http://www.reddit.com/r/rust/comments/2e62f6/compiling_rust_on_windows_aka_why_does_this_have/

[mingwandroid]

I'm in the process of adding a mingw-w64-rust-git PKGBUILD to MSYS2/MinGW-w64 at present:

https://github.com/Alexpux/MINGW-packages/tree/master/mingw-w64-rust-git

.. but I'm getting an error with the following (command line snagged via "PATH=/mingw64/bin:$PATH MSYSTEM=MINGW64 make VERBOSE=1"):

$ PATH="/c/repo/mingw-w64-rust-git/src/build-x86_64/x86_64-w64-mingw32/stage1/bin:/mingw64/bin:/usr/local/bin:/usr/bin:/bin:/opt/bin:/c/windows/system32:/c/windows:/c/windows/System32/WindowsPowerShell/v1.0:/usr/bin/vendor_perl:/usr/bin/core_perl:x86_64-w64-mingw32/stage1/bin"   x86_64-w64-mingw32/stage1/bin/rustc.exe --cfg stage1  -O --cfg rtopt --cfg debug -C prefer-dynamic --target=x86_64-w64-mingw32  -D warnings -L "x86_64-w64-mingw32/rt" -L "C:\msys64\mingw64/lib" -L ""  --out-dir x86_64-w64-mingw32/stage1/bin/rustlib/x86_64-w64-mingw32/lib -C extra-filename=-4e7c5e5c /c/repo/mingw-w64-rust-git/src/rust/src/libcore/lib.rs
LLVM ERROR: Segmented stacks not supported on this platform.
Segmentation fault

Anyone got any ideas about this? Should I open a bug report?

[mingwandroid]

From googling around, this seems to be related:

https://mail.mozilla.org/pipermail/rust-dev/2013-November/006314.html

[klutzy]

@mingwandroid The message means LLVM doesn't support segmented stack on your target (x86_64-w64-mingw32 if configure is correct).
The win64 segmented stack support has been added quite recently, so chances are you're using older version of LLVM. (We've used forked LLVM due to some local patches including this.)

[klutzy]

@DanielKeep as @vadimcn said, I also think MinGW should not be present in the guide. I think guide should recommend only one way (which is msys2 now).
However, I think your MinGW/MinGW-w64 description is useful for Windows dev FAQ document which doesn't exist now but should soon.

[steveklabnik]

Can anyone who uses Windows a lot comment on the state of this today?

[retep998]

I use Rust on Windows so much that I haven't read any documentation on how to build Rust on Windows in a while. However I do use MSYS2 like the README states, although I use x86_64 instead of i686. I'm not happy with using MSYS2, but it does work, mostly.

[mingwandroid]

@retep998 can you elaborate on the unhappiness with MSYS2? What can we do better?

[retep998]

@mingwandroid For example, Rust not detecting mintty as a console and thus not coloring output. Many MSYS2 utilities being broken or being unable to copy with Windows paths. I have to use an external Git because MSYS2's Git refuses to work with Windows paths, and the guis for Git refuse to open. Even putting aside faults with MSYS2, I don't like Rust's reliance on what is effectively shoving a posix world into Windows.

[steveklabnik]

Triage:

20:50 < WindowsBunny> steveklabnik: We 
                      don't mention how to 
                      setup 64-bit msys2
20:50 < WindowsBunny> steveklabnik: We need 
                      to mention 
                      mingw64_shell and the 
                      x86_64 toolchain

20:51 < WindowsBunny> steveklabnik: As well 
                      as pointing out that 
                      whether you install 
                      the 32-bit or 64-bit 
                      msys2 you'll have 
                      access to both 
                      toolchains (unless 
                      your computer only 
                      allows 32-bit)

[klutzy]

MSYS2 still provides posix-threaded gcc. Currently README.md suggests to install it (pacman -S mingw-w64-i686-toolchain) but we have to recommend manual mingw-w64 installation.

[klutzy]

(Or if there's no performance issue it would be fine? It only affects if you link to libstdc++.)

[steveklabnik]

This contains a whole ton of stuff that I think is all addressed today. If there are more things we should update with regards to Windows build instructions, please open new issues with specifics, thank you.