[LLVMdev] Slight troubles following "Getting Started" instructions

Tue Feb 26 17:16:19 PST 2008

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

> -----Original Message-----
> From: llvmdev-bounces at cs.uiuc.edu [mailto:llvmdev-bounces at cs.uiuc.edu]
> On Behalf Of Tanya M. Lattner
> Sent: Tuesday, February 26, 2008 4:32 PM
> To: LLVM Developers Mailing List
> Subject: Re: [LLVMdev] Slight troubles following "Getting Started"
> instructions
> 
> 
> On Tue, 26 Feb 2008, Ted Neward wrote:
> 
> > 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
> 
> >
> > Ted Neward
> > Java, .NET, XML Services
> > Consulting, Teaching, Speaking, Writing
> > http://www.tedneward.com
> >
> >
> >> -----Original Message-----
> >> From: llvmdev-bounces at cs.uiuc.edu [mailto:llvmdev-
> bounces at cs.uiuc.edu]
> >> On Behalf Of Tanya M. Lattner
> >> Sent: Tuesday, February 26, 2008 3:12 PM
> >> To: LLVM Developers Mailing List
> >> Subject: Re: [LLVMdev] Slight troubles following "Getting Started"
> >> instructions
> >>
> >>
> >>> 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
> >>
> >>>>> 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 :-)
> >>> 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 :-)
> >>>
> >>> Regards,
> >>> Jo
> >>>
> >>> _______________________________________________
> >>> LLVM Developers mailing list
> >>> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> >>> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
> >>>
> >> _______________________________________________
> >> LLVM Developers mailing list
> >> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> >> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
> >>
> >> No virus found in this incoming message.
> >> Checked by AVG Free Edition.
> >> Version: 7.5.516 / Virus Database: 269.21.1/1299 - Release Date:
> >> 2/26/2008 9:08 AM
> >>
> >
> > No virus found in this outgoing message.
> > Checked by AVG Free Edition.
> > Version: 7.5.516 / Virus Database: 269.21.1/1299 - Release Date:
> 2/26/2008
> > 9:08 AM
> >
> >
> > _______________________________________________
> > LLVM Developers mailing list
> > LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
> >
> _______________________________________________
> LLVM Developers mailing list
> LLVMdev at cs.uiuc.edu         http://llvm.cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev
> 
> No virus found in this incoming message.
> Checked by AVG Free Edition.
> Version: 7.5.516 / Virus Database: 269.21.1/1299 - Release Date:
> 2/26/2008 9:08 AM
> 

No virus found in this outgoing message.
Checked by AVG Free Edition. 
Version: 7.5.516 / Virus Database: 269.21.1/1299 - Release Date: 2/26/2008
9:08 AM