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

[Mikael Lyngvig]

As for the "any serious LLVM user must be an LLVM developer" view, I still
disagree.  I disagreed about 1.5 years ago and I still disagree now.  I am
an LLVM user.  I use "llc", "opt", and perhaps some day "lld" from C#,
intentionally avoiding the LLVM API.  I don't care about who wrote what and
how it is written.  I intentionally keep a black box view of LLVM because I
know I am going to get a double cerebral haemorrhage if I look closely at
the C++ code.  So I opt to view LLVM black box with as little information
about it as at all possible.  Should I run into defects or short-comings
later on, I plan to submit a defect report and move on to other parts of my
project while I wait for the bug to be fixed.  And nothing you say or argue
can change my view of that.  Even if you are probably correct in some sense
or other - that I somehow "should" be an LLVM developer.  Had LLVM been
developed in, say, C#, I'd be the first to plunge head first into the code
and fix bugs and all that.  But as it is, I prefer to keep a black box view
of LLVM.

I think all of your other points are valid.  Just so we are clear about
that.  But I have been thinking it over for a few hours now and I simply
don't think that _I_ am suited for peer-review processes.  I've worked
alone for the better part of my career and I strongly dislike the feeling
of being slowed down by a peer review (although I much value the feeling of
being sped up by it too!).

So I think the best thing way to continue is as follows:

   1. I'll keep and maintain my LLVM documents outside of LLVM (
http://llvm.lyngvig.org).
   2. I suggest you add your ideas for a front-end guide to the global
project wish list so that others out there may see it and think "Wow, I'd
like to do that!" about that sub-project.
   3. I suggest you list the to-do items in the bottom of the Mappings
document as part of the scope for the future front-end guide doc.  There
were many good suggestions, but most are outside the scope of what I have
in mind.

Also, to be fair, I think that my writing style is probably not well suited
for the formal environment of LLVM.  I like it concrete, hands-on, and
step-by-step, not abstract, theoretical, and somewhat diffuse.  I keep
banging my head against the requirement that there may be no redundancy in
the documentation, even if most writers intentionally use a certain amount
of redundancy to more seamlessly transfer the message to the reader.  Even
if most step-by-step guides necessarily have to repeat things that are said
in other documents.

So, given the above, I'd say that LLVM and I are simply not a good match
for each other.  With no hard feelings, no anger, and no offense intended.


-- Mikael



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

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