llvm dev - Feb 2008 - [LLVMdev] Slight troubles following "Getting Started" instructions

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

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
>

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

Am Dienstag, den 26.02.2008, 16:32 -0800 schrieb Tanya M.
Lattner:
> 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 ;-)


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 :-)
(And I'm happy to see that there's interest in perfecting them!)

Regards,
Jo