RFC: "Building with MinGW on Windows" (DOC, 2ND TRY)

Hi all,

Here’s an updated version of my proposed “Building with MinGW on Windows” document. In summary, the document gives a step-by-step description of how to build LLVM + Clang on Windows WITHOUT having Microsoft Visual Studio installed. The high-level goal of the document is to make life pleasant for those wonderful Windows users who desire to try out LLVM and/or Clang. I believe the document makes it a piece of cake to get up and running with LLVM + Clang on Windows, and that’s exactly what I was hoping for.

Changes are many:

  1. The document has been made more slim and now contains less chattering.
  2. The document now uses Ninja instead of MinGW Makefiles. This solves a bunch of problems and also speeds up the build process substantially because of the broken “make -j” behavior seen with some or all GNU Makes on Windows.
  3. The document now covers 32-bit and 64-bit builds with MinGW tools (if anybody know of an alternate BINARY distribution of MinGW64 than Drangon’s release, please let me know so I can include it in the document).
  4. The document now does NOT mention anything about unit tests or test suites, etc. These things will be explained in another document, be it through patches to existing documents or through an entirely new document.
  5. The document is now much smaller because it only introduces what I deem to be the essential tools: CMake, Ninja, MinGWnn, Python, and Subversion.
  6. The document now has significantly few chapters and sections in it, making the overall experience much less confusing and overwhelming for the newbie LLVM and/or Clang user.
  7. The document no longer mentions my name because I personally prefer a documentation strategy where there is no author mentioned in the documents. If this is an unacceptable omission, just let me know, and I’ll add my name again.

To view the document as it will look on the website, make sure you have Sphinx installed and then copy the attached file to llvm/docs, and run “make html”, after which you’ll find the document in llvm\docs_build\html\Building…html.

The document has NOT been linked into the LLVM documentation tree because it seems that there is still some uncertainty as to whether this document is useful or not.

Any and all comments are greatly appreciated. I do think, however, that it is time that we settle on this being an atomic document that cannot be split up further.

Regards,
Mikael

– Disclaimer: I am not arrogant in real life, so if you perceive me as being arrogant, you are to blame :wink:

Building with MinGW on Windows.rst (17.6 KB)

Hi all,

Here’s an updated version of my proposed “Building with MinGW on Windows” document. In summary, the document gives a step-by-step description of how to build LLVM + Clang on Windows WITHOUT having Microsoft Visual Studio installed. The high-level goal of the document is to make life pleasant for those wonderful Windows users who desire to try out LLVM and/or Clang. I believe the document makes it a piece of cake to get up and running with LLVM + Clang on Windows, and that’s exactly what I was hoping for.

Changes are many:

  1. The document has been made more slim and now contains less chattering.
  2. The document now uses Ninja instead of MinGW Makefiles. This solves a bunch of problems and also speeds up the build process substantially because of the broken “make -j” behavior seen with some or all GNU Makes on Windows.
  3. The document now covers 32-bit and 64-bit builds with MinGW tools (if anybody know of an alternate BINARY distribution of MinGW64 than Drangon’s release, please let me know so I can include it in the document).
  4. The document now does NOT mention anything about unit tests or test suites, etc. These things will be explained in another document, be it through patches to existing documents or through an entirely new document.
  5. The document is now much smaller because it only introduces what I deem to be the essential tools: CMake, Ninja, MinGWnn, Python, and Subversion.
  6. The document now has significantly few chapters and sections in it, making the overall experience much less confusing and overwhelming for the newbie LLVM and/or Clang user.
  7. The document no longer mentions my name because I personally prefer a documentation strategy where there is no author mentioned in the documents. If this is an unacceptable omission, just let me know, and I’ll add my name again.

To view the document as it will look on the website, make sure you have Sphinx installed and then copy the attached file to llvm/docs, and run “make html”, after which you’ll find the document in llvm\docs_build\html\Building…html.

The document has NOT been linked into the LLVM documentation tree because it seems that there is still some uncertainty as to whether this document is useful or not.

Any and all comments are greatly appreciated. I do think, however, that it is time that we settle on this being an atomic document that cannot be split up further.

Generally, I think this looks very good! A few nit-picks:

  1. You should probably list the somewhat-more-popular mingw64 distributions available from: http://mingw-w64.sourceforge.net/
  2. You may want to mention TortoiseSVN as an alternative to SlikSVN, as that seems to be a popular choice
  3. As much as I like Ninja, I would add a section on mingw32-make as that is the only “official” build choice at the moment (“official” meaning supported by CMake developers)
    Thanks for working on this!

Thanks for your feedback!

I will include the official MinGW64 site - and then drop the Drangon site for now. I simply had trouble finding the executables because I was looking for a 64-bit build of MinGW64, but apparently it is only officially supported as a 32-bit build. Perhaps my problems with Clang++ and MinGW64 will go away once I try out the official channels :slight_smile:

Is it okay if we switch so I mention TortoiseSVN instead of SlikSVN then? I am desperately trying to keep the doc as simple as possible.

I used to have a section on that, but the annoying thing is that in MinGW32 it is called mingw32-make.exe and in MinGW64 it is called make.exe. Perhaps we should simply wait to check in the document until such a time that Ninja on Windows is officially supported by CMake? Kitware posted a note saying that CMake now supports Ninja on Windows in the CMake test suite so it will be part of the next release of CMake. I think it would be very sad to have to cover three different build tools because then the document ends up being almost as complex as it was before I split out the test and buildbot slave stuff. And GNU Make seems to have a problem with that it is not utilizing the CPU 100 percent (even when -jN is specified, where N is the number of cores or twice that number), whereas Ninja has no problems with this.

No problem, it is the least I can do since I don’t feel knowledgable enough about LLVM and Clang to actually code on them. I plan to spend quite some time converting existing HTML documents verbatim into Sphinx later on.

As was once explained to me by Ruben Van Boxem, what you call mingw32
should probably be called mingw.org (or maybe only mingw). The other
one should be called MinGW-w64. Also note that MinGW-w64 can target
both 32-bit and 64-bit windows!

I was also informed that nightly builds of mingw-w64 are rock solid,
so here's a link to toolchain targeting Win64
http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/rubenvb/release/

As for the rest of the document I have only one complaint that's more
a matter of style and taste. The document sounds like tutorial and is
very different from say "getting started" which is more to the point.
I'll try to be more concrete:

"Building LLVM on Windows using the MinGW32 or MinGW64 toolchains can seem
daunting at first."

I never had this impression, you just checkout clang, unpack mingw,
run cmake, run ming32-make. Also note that I knew next to nothing
about mingw when I first did this.

Mingw vs VS issues

I think it would be fair to say that mingw is better supported without
having to list every feature that doesn't work with VS (who will
remember to change this page when the features get implemented?). I'm
also assuming the person already knows why he wants to use mingw.

Reference to "Getting Started"
I think that Getting Started page should have a link to your document
as the official Clang+Mingw information. You don't really need to
refer back to Getting started, infinite loop anyone :slight_smile:

As Justin said, I would concentrate more on the official tools like ming32-make.

The way I imagine this is:
- explain how to choose mingw flavor
- checkout llvm/clang
- how to use cmake to generate makefiles
- how to build using ming32-make
- how to debug
- how to run tests (python, gnuwin32, subversion)
- mention alternative tools like ninja build

As I said, this is just my personal preference, I just had the
impression that your document was too long and covered a lot of ground
that it didn't really have to.

Hi Nikola,

Thank you very much for your feedback!

I am beginning to feel slightly dizzy from all the suggestions that go against each other :slight_smile:

I’ll fix the documentation so that it uses MinGW and MinGW-W64. I’ll ignore that the 64-bit version targets both 32-bit and 64-bit Windows, so as to keep things simple.

I’ll use your link, thank you for that.

It is intended to be a brief, conscise, and precise tutorial on how to build LLVM and Clang using the MinGW tools. I believe that those who know more can easily skip parts whereas those who know less cannot easily figure out the missing parts. So I try to spell it out from A to Z. That way, anybody can read and use the document: The newbie as a safe guide and the expert as a checklist.

As for VS, well, I feel that it is of URGENT importance to inform the newbie that he or she cannot expect to get usable results with Microsoft Visual Studio (i.e. using Clang as the frontend and attempt to link a somewhat advanced C++ program).

Well, people are different. I do suffer from a very poor memory, which is what makes me so reluctant to actually code on LLVM or Clang, but I felt very confused and overwhelmed by the whole ordeal when I first entered the world of LLVM - even though I’ve used computers for three decades, Unix for 5+ years full-time, worked on other compiler projects, and so on, and so on. So just because you felt it was straightforward does not mean everybody will do so (emotional makeups are as different as people are). And I am trying to be gentle towards ever imaginable newbie. I know that it took me days to set up the first build slave because there were so many loose ends all over the place. And this document actually started out as a document on how to set up a Windows buildbot slave. Then it got chopped into two, now three documents.

I have to teach you a small verse here: ASS-U-ME is to make an ASS of U and ME. In other words: Every assumption in every document, line of code, space shuttle, whatever is going to cost dearly at some point later on. I am intentionally NOT assuming anything about the level of the user (actually, I am: I assume they know how to open up a console window on Windows, this assumption was introduced to shorten the document).

Well, the initial version WAS too long and covered lots of ground that ultimately only served to confuse the newbie. Thanks to the readers of these lists, those issues got sorted.

I hope I don’t sound obtuse, hostile, or unfriendly. I think your points are generally very good and useful (and I will incorate most of them into the document), but I strongly disagree on the tutorial thingy :slight_smile:

– Disclaimer: I am not arrogant in real life, so if you perceive me as being arrogant, you are to blame :wink:

2012/6/18 Nikola Smiljanic <popizdeh@gmail.com>

Now this is interesting:

Revision: 158653
Author: mspencer
Message:
[MSExtensions] Add support for __forceinline.

__forceinline is a combination of the inline keyword and
__attribute__((always_inline))

Yup, that’s great news! I’ll fix the documentation right away :slight_smile:

2012/6/18 Nikola Smiljanic <popizdeh@gmail.com>

Hi Nikola,

I finally found a way to incorporate your complaint regarding the tutorial-like nature of the document: I simply erased the sentence that talks about it being daunting at first. It served no purpose and now its gone :slight_smile:

Cheers,
Mikael

– Disclaimer: I am not arrogant in real life, so if you perceive me as being arrogant, you are to blame :wink:

2012/6/18 Nikola Smiljanic <popizdeh@gmail.com>