[PATCH] [DOC] [NEW] Mapping High-Level Constructs to LLVM IR

Sat Dec 28 20:47:56 PST 2013

Hi Sean,

Sorry, I don't recall that we discussed turning it into a guide as such.
We did discuss whether it should be an "LLVM User Guide" or not (and you
pointed out that it shouldn't to which I agreed).

I personally feel that the document has a clear purpose - to provide useful
examples of lowering high-level language constructs into LLVM IR - so that
newbies and language front-end developers may benefit from it.

It is quite possible that the document in a few years will answer most
questions that language front-end developers may ask, but I don't see it as
a guide as such.  A guide is, IMHO, something in between a tutorial and a
reference.  This document is what the title says: A list of examples of how
to map high-level language constructs into LLVM IR.  The purpose being
twofold:

  1. To answer the question "How do I express this thingy in LLVM IR?"
(this is very useful for those completely new to LLVM IR as many know that
a reference guide is simply not good for learning quickly).
  2. To answer the question "How do I implement this thingy using LLVM IR?"
(this is very useful for newbie language designers to making language
front-ends).

But I do not see it as part of this document's scope to explain to the
reader how to make a front-end.  A zillion books have already been written
on how to make a compiler front-end.

I guess the document is an expression of what I myself was and is looking
for when it comes to LLVM documentation.  Most of the existing
documentation is apparently tuned for LLVM developers, not for LLVM users.

As far as I am concerned, we should add the document to LLVM and then see
what direction it takes.  If you feel like spending 50, 100, or 200 hours
making a guide out of it, I guess that's where it will end up.  If not, it
will perhaps be extended with more elaborate examples (I know that the zero
cost exception handling examples are going to appeal to many, once I get
that part done), so that it stays on the course that I have laid down now.

I think you are wishing for a document that caters to the existing and
future LLVM front-end developers.  I think that's an entirely different
document than this.  It is a document that should take the reader by the
hand and walk him or her through the sequence of documents, possibly
including this document, that he or she needs to be familiar with to get up
to speed with respect to making a new LLVM front-end.

I am sort tired of having to battle a long, arduous battle whenever I try
to make a new document for LLVM.  I started out using LLVM because I wanted
to save time, not because I wanted to devote myself fully to the project.
 The net result, so far, has been that I have been working my butt off to
make new documents for LLVM (three or four, none accepted as of yet), and
that has cost my own project all my available time for months now.

I will be the first to state that this document is nowhere near where it
could be (I was thinking today, that if I put aside, say, four hours a day
five days a week, it may end up being a great document in another six
months or so).  But I am honestly very surprised by the general lack of
desire to contribute to the document.  My hope is that once it is formally
part of the LLVM documentation, more will feel like setting aside five or
ten hours to add some worthwhile examples of lowering high-level language
constructs into LLVM IR so that others may benefit from this.  I am no
compiler guru, I am myself in the learning phase and openly admit that the
current contents of the document is less than ideal.  But I am not going to
redesign, rewrite, redo, and resubmit an entirely different document.  Let
those who want it write it!

-- Mikael

2013/12/29 Sean Silva <silvas at purdue.edu>

> Didn't we discuss turning this into a guide for language frontend
> implementers? It seems to still be "mapping high level constructs" which
> isn't conducive to a well-organized document with a clear goal and clear
> directions for future improvement. Having the document as "mapping high
> level constructs" will only be result in this turning into a grab bag of
> "lowerings" that does not cater to any particular reader's information
> needs.
>
> You need to really think about the goal of this document and its audience
> (who are they? what are they trying to learn about? (please answer these
> questions in your reply)). The document seems to be conflating whether its
> audience is frontend implementers vs. LLVM newbies who just want some
> examples of the lowering of things to IR. The result is that neither of
> those audiences are served well. My general feeling for the document is
> that it not suited for newbies since it is too encyclopedic; on the other
> hand, it is too disorganized and does not discuss tradeoffs or go into
> enough detail (or goes into pointlessly too much detail because it is
> trying to cater to newbies) to be well-suited for frontend implementers.
>
> I wouldn't be against a "tour" of some IR lowerings to give newbies a feel
> for the IR. However, we much more direly need a guide for frontend
> implementers who already have some amount of experience with the IR. I
> strongly believe that this document should become a guide for frontend
> implementers.
>
> -- Sean Silva
>
>
> On Sat, Dec 28, 2013 at 7:46 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote:
>
>> This document explains how to map various high-level language constructs
>> to LLVM IR.
>>
>> The document is now ready to go live (and to be reviewed) even if it is
>> nowhere near complete.
>>
>> I must confess that many of the requested features (such as Itanium
>> exception handling) are well beyond the scope of my current knowledge so
>> I'll have to work on these over the coming months and years as only a
>> single person has volunteered to contribute material.
>>
>> I have linked the document into the index right after the Language
>> Reference as I believe most newcomers will be VERY interested in stumbling
>> across this document.  I know from my own experience that initially the
>> vast amount of documentation makes it difficult to determine what you
>> should look at and what you can ignore for the time being.
>>
>> Comments, critique, suggestions, enhancement requests, etc., are happily
>> accepted!
>>
>> Once the document has been made part of the LLVM website, I'll remove my
>> Github copy of it.
>>
>>
>> -- Mikael
>>
>>
>>
>>
>>
>> _______________________________________________
>> llvm-commits mailing list
>> llvm-commits at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20131229/ea9ecdf8/attachment.html>