Slight troubles following "Getting Started" instructions

Just for whoever it maintaining the "Getting Started" instructions at
http://llvm.org/docs/GettingStarted.html :

The page is missing a link to the download section. Returning to the
main page at http://llvm.org/ , I found the Site Map, checked it - and
didn't see the download link (well, it's sitting right below, but
there's so much text on that page that I simply overlooked it).

The download page was the next challenge.It gave me source code at the
beginning, source code at the end, and lots of keywords about Mingw32,
MacOS, Red Hat, and another bunch of source code.
Only now that I'm writing up my experience I see there's an inner
structure to the list: LLVM, then LLVM-GCC 4.2, then LLVM-GCC 4.0. LLVM
starts with sources, LLVM-GCC (inconsistently) starts with binaries and
gives sources later.
Suggestion 1: Strukture the download list, like so:
* LLVM
  * LLVM source code (5.4M)
  * LLVM Test Suite (53M)
  * LLVM Binaries for Minw32/x86 (14M)
* LLVM-GCC 4.2 Front End
  * Binaries for MacOS X/x86 (50M)
  * Binaries for Red Hat Enterprise Linux4/x86 (42M)
  ...
  * Source Code (49M)
* LLVM-GCC 4.0 Front End
  * ...
Oh, and possibly a note why one would want LLVM, LLVM-GCC 4.2, and
LLVM-GCC 4.0, respectively. People usually know what OS they use and
whether they want binaries or sources, but those who're new to LLVM
won't know whether they will need LLVM or LLVM-GCC (and if they need
LLVM-GCC, they can't decide whether they need 4.2 or 4.0).

Suggestion 2: make the layout wider so the links don't wrap.

Oh, and please don't label the Linux binaries "Red Hat Linux". Anything
with a primary label of "Red Hat" gets filtered out for me on an almost
subconscious level since I'm running an Ubuntu box, so the primary
labels that I look for are "Linux" and "Ubuntu". "Red Hat Enterprise
Linux" is quite a moutful, and the trigger keyword is almost last on
that line (and wrapped, too).
I'd rephrase that as "Binaries for Linux (tested for Red Hat Enterprise
Linux)" or something. (Heck, I'm not even sure whether it will run on
any Linux other than RHEL. I have no idea what differences there might
be between RHEL and Ubuntu; I surely hope none that affect LLVM-GCC.)

Just my 2c, in the hopes that it's useful to somebody.

Regards,
Jo

The page is missing a link to the download section. Returning to the
main page at http://llvm.org/ , I found the Site Map, checked it - and
didn't see the download link (well, it's sitting right below, but
there's so much text on that page that I simply overlooked it).

You are right that its missing from the getting started guide. I'll add it.

The download page was the next challenge.It gave me source code at the
beginning, source code at the end, and lots of keywords about Mingw32,
MacOS, Red Hat, and another bunch of source code.
Only now that I'm writing up my experience I see there's an inner
structure to the list: LLVM, then LLVM-GCC 4.2, then LLVM-GCC 4.0. LLVM
starts with sources, LLVM-GCC (inconsistently) starts with binaries and
gives sources later.
Suggestion 1: Strukture the download list, like so:
* LLVM
* LLVM source code (5.4M)
* LLVM Test Suite (53M)
* LLVM Binaries for Minw32/x86 (14M)
* LLVM-GCC 4.2 Front End
* Binaries for MacOS X/x86 (50M)
* Binaries for Red Hat Enterprise Linux4/x86 (42M)
...
* Source Code (49M)
* LLVM-GCC 4.0 Front End
* ...

First, from 2.0 and beyond the list has been pretty much llvm, llvm-test, llvm binaries (if any), llvm-gcc binaries, and then llvm-gcc source. The reason it is in that order is that we are trying to encourage people to download the llvm-gcc binaries versus compiling it themselves.

I can move the llvm-gcc4.2 source code up in the list if people think this is better... but the binaries will still be first and should be.

Oh, and possibly a note why one would want LLVM, LLVM-GCC 4.2, and
LLVM-GCC 4.0, respectively. People usually know what OS they use and
whether they want binaries or sources, but those who're new to LLVM
won't know whether they will need LLVM or LLVM-GCC (and if they need
LLVM-GCC, they can't decide whether they need 4.2 or 4.0).

True. 2.3 will solve this problem since we will drop llvm-gcc-4.0. Otherwise, we expect people to read the getting started guide to understand what parts of llvm they need and what they are. The download page should not be cluttered with this information.

Suggestion 2: make the layout wider so the links don't wrap.

This will be fixed with the website overhaul.

Oh, and please don't label the Linux binaries "Red Hat Linux". Anything
with a primary label of "Red Hat" gets filtered out for me on an almost
subconscious level since I'm running an Ubuntu box, so the primary
labels that I look for are "Linux" and "Ubuntu". "Red Hat Enterprise
Linux" is quite a moutful, and the trigger keyword is almost last on
that line (and wrapped, too).
I'd rephrase that as "Binaries for Linux (tested for Red Hat Enterprise
Linux)" or something. (Heck, I'm not even sure whether it will run on
any Linux other than RHEL. I have no idea what differences there might
be between RHEL and Ubuntu; I surely hope none that affect LLVM-GCC.)

The reason its labaled RHEL is because I'm not positive it will work on another Linux distribution. I don't see why its different to have a label versus having it in the name. Its just more words....

I appreciate the feedback.

-Tanya

Hi,

I can move the llvm-gcc4.2 source code up in the list if people think this
is better... but the binaries will still be first and should be.

Just make it consistent so people who don't know their way around yet
can quickly find what they're looking for.

I agree that binaries should be first if they should be encouraged.

I plan to run the test suite, just to establish a known baseline (this
is an amd64 machine, and things tend to be a bit less well-polished than
on stock x86 installations).
Does it make sense to
* first run the test suite with the binaries,
* compile llvm-gcc from sources,
* run the test suite again with the recompiled binaries?

> Oh, and possibly a note why one would want LLVM, LLVM-GCC 4.2, and
> LLVM-GCC 4.0, respectively. People usually know what OS they use and
> whether they want binaries or sources, but those who're new to LLVM
> won't know whether they will need LLVM or LLVM-GCC (and if they need
> LLVM-GCC, they can't decide whether they need 4.2 or 4.0).

True. 2.3 will solve this problem since we will drop llvm-gcc-4.0.
Otherwise, we expect people to read the getting started guide to
understand what parts of llvm they need and what they are. The download
page should not be cluttered with this information.

That's a bit of a catch-22 situation for me. I'm still in the "Getting
Started" phase, so by definition, I haven't read everything yet, much
less understood what I need.
I agree that cluttering the download page with such information isn't
optimal.

> Oh, and please don't label the Linux binaries "Red Hat Linux". Anything
> with a primary label of "Red Hat" gets filtered out for me on an almost
> subconscious level since I'm running an Ubuntu box, so the primary
> labels that I look for are "Linux" and "Ubuntu". "Red Hat Enterprise
> Linux" is quite a moutful, and the trigger keyword is almost last on
> that line (and wrapped, too).
> I'd rephrase that as "Binaries for Linux (tested for Red Hat Enterprise
> Linux)" or something. (Heck, I'm not even sure whether it will run on
> any Linux other than RHEL. I have no idea what differences there might
> be between RHEL and Ubuntu; I surely hope none that affect LLVM-GCC.)

The reason its labaled RHEL is because I'm not positive it will work on
another Linux distribution. I don't see why its different to have a label
versus having it in the name. Its just more words....

Just to help people who're under brainwave overload :slight_smile:
The key rule here is: important keywords first, less important ones to
the right. In the case of Linux binaries, it's "Linux", then RHEL. (I
agree it's silly.)

Thanks for the apprecation :slight_smile:

Regards,
Jo

I plan to run the test suite, just to establish a known baseline (this
is an amd64 machine, and things tend to be a bit less well-polished than
on stock x86 installations).
Does it make sense to
* first run the test suite with the binaries,
* compile llvm-gcc from sources,
* run the test suite again with the recompiled binaries?

What do you plan to use this baseline for? You shouldn't see a difference in results if you are using llvm-gcc you compiled from 2.2 source and 2.2 binaries.

Oh, and possibly a note why one would want LLVM, LLVM-GCC 4.2, and
LLVM-GCC 4.0, respectively. People usually know what OS they use and
whether they want binaries or sources, but those who're new to LLVM
won't know whether they will need LLVM or LLVM-GCC (and if they need
LLVM-GCC, they can't decide whether they need 4.2 or 4.0).

True. 2.3 will solve this problem since we will drop llvm-gcc-4.0.
Otherwise, we expect people to read the getting started guide to
understand what parts of llvm they need and what they are. The download
page should not be cluttered with this information.

That's a bit of a catch-22 situation for me. I'm still in the "Getting
Started" phase, so by definition, I haven't read everything yet, much
less understood what I need.
I agree that cluttering the download page with such information isn't
optimal.

I agree. The web pages could be better. We'll try to figure out how to incorporate some sort of compromise.

Thanks again,
Tanya

As a suggestion, what about having "Common Uses for LLVM" that list out what
the LLVM n00b needs if he wants to...

(*) Get hello.c to compile and run in LLVM bitcode (This is the "what's the
absolute minimum I need to do to see this thing in action?" question.)
(*) Use LLVM as a back-end for a custom language or interpreter (This is the
"OK now that I've seen the minimum, I want to start playing with it as a
black box" question.)
(*) Explore the LLVM compilation process (This is the "I'm interested in
exploring the guts of JIT compilers and such" question.)

... and so on--I'm sure you guys can cook up better common use cases here
than I.

I'm sympathetic to Joachim's problems, having gone to the website and seen
all this info and finding it difficult to wade through. I couldn't figure
out that I needed *both* the llvm-gcc binaries and the llvm binaries, for
example, until I downloaded llvm, unzipped it, went to compile something and
said, "Oh, I get it--I need their special gcc compiler to get the bitcode
that llvm wants to work from." It took me a while to figure out what was
what, and even then, without Anton's help getting MinGW and msys installed
and in the right place, this ol' Windows-head would probably still be lost
trying to get LLVM up and working on my system.

Ted Neward
Java, .NET, XML Services
Consulting, Teaching, Speaking, Writing
http://www.tedneward.com

As a suggestion, what about having "Common Uses for LLVM" that list out what
the LLVM n00b needs if he wants to...

(*) Get hello.c to compile and run in LLVM bitcode (This is the "what's the
absolute minimum I need to do to see this thing in action?" question.)
(*) Use LLVM as a back-end for a custom language or interpreter (This is the
"OK now that I've seen the minimum, I want to start playing with it as a
black box" question.)
(*) Explore the LLVM compilation process (This is the "I'm interested in
exploring the guts of JIT compilers and such" question.)

... and so on--I'm sure you guys can cook up better common use cases here
than I.

I'm sympathetic to Joachim's problems, having gone to the website and seen
all this info and finding it difficult to wade through. I couldn't figure
out that I needed *both* the llvm-gcc binaries and the llvm binaries, for
example, until I downloaded llvm, unzipped it, went to compile something and
said, "Oh, I get it--I need their special gcc compiler to get the bitcode
that llvm wants to work from." It took me a while to figure out what was
what, and even then, without Anton's help getting MinGW and msys installed
and in the right place, this ol' Windows-head would probably still be lost
trying to get LLVM up and working on my system.

While I am not disagreeing that there is a lot of documentation and it may not be as easy to figure out which document you want at first glance, I do think that the getting started guide has the two biggest things.

1) http://llvm.org/docs/GettingStarted.html#quickstart
This tells you what exactly you need to get started (llvm and llvm-gcc)

2) http://llvm.org/docs/GettingStarted.html#tutorial
This gives you an example of how to use llvm/llvm-gcc.

The document is called "Getting Started Guide", so I don't think it can get more clear. It should probably be moved higher up in the docs list.

Exploring the guts of compilation and hooking up to the llvm backend are more difficult topics. Documentation could be improved.

-Tanya

OK, counter-examples. I am channeling Joe, an average C/C++/C#/Java
developer who's heard about LLVM and is curious to know what it is.

Joe thinks....

I surf to http://llvm.org/docs/GettingStarted.html#quickstart because I am
interested in this LLVM stuff.

1, 2, 3. What documentation? What am I supposed to read? Aaah! This is
scary!
4. Install either 4.0 or 4.2. Which one do I want? Which is stable? Which is
just a test platform?
5. Get the LLVM Source code. I can't work with precompiled binaries? I have
to build this from source? Wow, that's a lot more work than I'd hoped for a
quick look.
6. Whatever, I don't care about testing it. Skipped.
7. OK, pretty normal stuff. Done.
8. Building.... OK, now what? (Where's that link to the tutorial again?)

I read at the bottom....
"Consult the Getting Started with LLVM section for detailed information on
configuring and compiling LLVM." OK, but I should be good to go, right?
"See Setting Up Your Environment for tips that simplify working with the GCC
front end and LLVM tools." OK, once I'm done building, got it.
"Go to Program Layout to learn about the layout of the source code tree."
Why do I care about this if I'm just taking a quick look?

Wow, the rest of this page is big... Isn't there an easier way to get into
all this?

Tanya, I'm not arguing that the documentation sucks or is incorrect or
whatnot. I'm simply suggesting that there may be a better way to structure
the documentation for people with specific purposes. At the end of the day,
as with all suggestions, if you don't like it, just use the Microsoft
time-honored response, "Thank you for your feedback", and toss it in the
round file. But I do remember trying to get started with this and facing a
lot of these same questions, so I'm offering this up merely as a
counterpoint to what I perceive to be the implied response of "The
documentation is fine, you just didn't read it right".

Ted Neward
Java, .NET, XML Services
Consulting, Teaching, Speaking, Writing
http://www.tedneward.com

The document is called "Getting Started Guide", so I don't think it can
get more clear. It should probably be moved higher up in the docs list.

Actually finding the docs wasn't difficult. The challenge was following
the docs, deciding what's relevant and what isn't, deciding what to
install and what to leave out. Being unsure, one usually ends up trying
to install everything. That's good if you want to get a heads-up for all
the remaining warts of the software, but bad for attracting the unwashed
masses :wink:

How about adding a "who needs this" paragraph at the start of every
section of the Getting Started Guide? That way, everybody could easily
skip those parts that are irrelevant to him.

In the hope that it will help you laying out a plan for documentation
improvements, I prepared a list of groups that I see may be looking for
answers in the getting started guide:
1) People who use llvm as a tool. Subgroups are:
1a) Junior compiler writers wanting to install llvm and compile
something (in fact, anything), just to get a baseline in case things go
wrong later.
1b) Alpha testers for a compiler. The first step of their installation
instructions read "get and install llvm".
1c) Compiler writers who finally get around to writing something more
foolproof than "get and install llvm" for their beta testers. They will
probably copy the relevant parts of llvm installation instructions,
tailored towards the specific needs of their compilers.
1d) Distribution package maintainers who need to convert the
installation instructions into an automated installation script.
2) Compiler writers joining a project that uses llvm as a backend (these
will usually just get the "get and install llvm" line).
3) People who want to join the llvm project and hack on llvm.

Groups 1a-1d probably want the install instructions for the same package
sets, possibly with minor variations for each group.
Groups 1, 2, and 3 will probably want to install different parts of the
system.
Oh, and group 1d is probably too small to warrant any extra work for the
docs. Answering their questions in the mailing list might be less work
than keeping their special instructions up-to-date in the docs.

HTH.

Exploring the guts of compilation and hooking up to the llvm backend are
more difficult topics. Documentation could be improved.

There's always room for incremental improvement.

Don't worry, I don't see the docs as bad (in fact I've seen much worse).
The docs just aren't polished to perfection yet :slight_smile:
(And I'm happy to see that there's interest in perfecting them!)

Regards,
Jo

Tanya, I'm not arguing that the documentation sucks or is incorrect or
whatnot. I'm simply suggesting that there may be a better way to structure
the documentation for people with specific purposes. At the end of the day,
as with all suggestions, if you don't like it, just use the Microsoft
time-honored response, "Thank you for your feedback", and toss it in the
round file. But I do remember trying to get started with this and facing a
lot of these same questions, so I'm offering this up merely as a
counterpoint to what I perceive to be the implied response of "The
documentation is fine, you just didn't read it right".

Ted, thanks for your feedback.

Just kidding. :wink:

I was not saying our documentation was totally fine. I simply was saying that I felt that the getting started quickly section was a simple as you could get and be able to generate a bitcode file. I do think our documenation needs a serious overhaul in general, but those two sections I pointed out were pretty easily to follow in my opinion. However, I appreciate you pointing out another viewpoint and I do agree with many of your suggestions. I hope to encorporate this into our documentation soon.

Thanks,
Tanya

Hi Tanya,

I was not saying our documentation was totally fine. I simply was saying
that I felt that the getting started quickly section was a simple as you
could get and be able to generate a bitcode file.

I also found "Getting Started" kind of obscure when I first read it.
Because of that I tried to take a different, complementary, approach
in the instructions for building the Ada f-e: the copy-and-paste recipe.
See http://llvm.org/docs/GCCFEBuildInstrs.html

Ciao,

Duncan.