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

[Sean Silva]

On Sat, Dec 28, 2013 at 9:47 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:

> 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 think you misunderstood what I meant by "guide for frontend
implementers". Hopefully my comments below clear up what I mean.


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

FYI, all serious LLVM users have to be LLVM developers to some extent (I'd
be glad to explain this but this isn't the right moment). I think what you
mean by "LLVM users" is "people playing around with LLVM" (indeed, the
reason I focus so much on LLVM's documentation is because when I was just
"playing around" with it, I had a *really* hard time due to lack of docs,
so trust me, I've been there and the experience still strongly influences
my work on LLVM).


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

As David Blaikie pointed out in an earlier review, with LLVM an incremental
approach is highly recommended. Creating a large monolithic piece of
code/documentation for LLVM that will satisfy reviewers is very difficult,
and each reviewer has a cutoff in "number of things that I want you to
change" that essentially results in them giving up on your patch.

It's *much* easier to get a general direction approved and get a foundation
for future work committed and then incrementally improve upon that. The
reviewer feedback is then spread over a long series of incremental patches
and you never risk running into their "give up on the patch" limit of
changes for a single patch, and it's no biggie completely rework a patch
from scratch since it is fairly small. If you are keeping a large amount of
work out-of-tree, usually you will have to keep a clean, incremental
history in order to upstream it; in many cases (including the present one),
"keep" in that sentence will need to be replaced with "retroactively forge".

In the present case, there are about a bazillion things that I can pick at
in the currently proposed patch. However, that's not what concerns me
(though those things will need to be addressed eventually, but will
probably fix themselves with a more incremental approach).

I am most concerned about the general direction of the document. You seem
highly focused on the examples as being the "meat" of this document, but if
you look back at the thread `[LLVMdev] "Mapping High-Level Constructs to
LLVM IR" Github URL`, you will see that almost all of the feedback was for
things that can't be treated by just exhibiting an example, and for many
(most?) of them an example is "nice to have" but not essential (e.g.
Chris's first suggestion was ended by "You could even include an example").

The best way I can think to summarize the type of content that people are
interested in is "approaches and tradeoffs" for effectively using LLVM as a
backend for your language frontend.

I get the impression that this document is currently just a grab-bag of
examples of IR lowerings, and I really don't think that approach has a
future. A document that tries to help familiarize newbies with LLVM IR by
means of exhibiting LLVM IR equivalents of familiar high-level language
operations seems like a great idea. I'd support a patch for that. The
present patch doesn't seem to be aiming for that goal though (at a minimum,
it's way too "encyclopedic"), even though that goal seems closer to your
own description of the document's goal than "approaches and tradeoffs" for
frontend implementers.

To be clear, while I would support both an "approaches and tradeoffs for
effectively using LLVM as a backend for your language frontend" document
and a "familiarize newbies with LLVM IR by means of exhibiting LLVM IR
equivalents of familiar high-level language operations" document, do
realize that almost all the positive feedback that you received in the
other thread (and there was lots of it!) was aimed at the former document.

-- Sean Silva


> 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/396f95d0/attachment.html>