Building LLVM/Clang: The Missing Manual

OK. Let’s follow that link. Let’s look at the available options. OK, there’s "Current" which is version "SVN". The bleeding edge alternative downloaded via SVN. Let’s not do that one. Next is "01 Sep 2015" which is version "3.7.0". That’s the one, right? Let’s follow it now.

Sure enough, that’s the one. Let’s start downloading the even dozen tarballs (not including documentation). Hmmm… While I’m waiting for the downloads I happen to see that this is not at the top of the download page. Scrolling up I find that there’s a version 3.7.1. You know, the one I probably should have been downloading in the first place. Woohoo! Time to kill the downloads and waste more bandwidth and time downloading the proper tarballs!

This degree of inaccuracy (albeit not specifically documentation alone involved) is the kind of thing that is maddening to a project newcomer. When you consider how little attention to detail it requires to link to the right places, just how good is the coding part that requires intense attention to detail?

Note that all the instructions are for people using SVN to download the bleeding edge. Quick show of hands here: how many of you, when faced with a new language or compiler or library automatically reach for the trunk of the source control system instead of the latest release? … That many, eh? What is that? Three hands showing? That’s two more than I was expecting.

Most newcomers are not going to reach for the bleeding edge. This is DOUBLY true when the newcomers have come to your documentation via a link from the very place they downloaded your stuff from in the first place. Here’s the work flow of a newcomer to LLVM:

Really, having the existing instructions is a bad way to communicate anything. They do not document anything that most users are actually going to do. Instead they act as a hurdle you have to jump to even use the project’s output.

Note that in the previous section I mentioned there are a dozen tarballs. Can you guess how many of those are represented (even indirectly) in the "getting started" docs? Five. Fewer than half. LLVM, Clang, CLang’s extra tools, the compiler runtime, and libcxx. Missing are any references to or explanations of:

It takes digging around a half-dozen different pages on the llvm.org site, along with some guesswork, to place these properly. (To be honest I’m not actually sure I have all of them in the right place.)

Of course some will say that these aren’t necessary. But … why not mention them?! Make a list of the packages (there’s only twelve for cryin' out loud!) and say "these are the necessary ones, these are the optional ones, these are the experimental ones, …" and so on. Your newcomers don’t know the damned project. Expecting them to suddenly become experts in which pieces are needed when is idiotic!