<div dir="ltr">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.<div>
<br></div><div>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!).</div>
<div><br></div><div>So I think the best thing way to continue is as follows:</div><div><br></div><div> 1. I'll keep and maintain my LLVM documents outside of LLVM (<a href="http://llvm.lyngvig.org">http://llvm.lyngvig.org</a>).</div>
<div> 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.</div><div> 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.</div>
<div><br></div><div>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.</div>
<div><br></div><div><div>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.</div><div><br></div></div><div><br></div><div>
-- Mikael</div><div><br></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">2013/12/29 Sean Silva <span dir="ltr"><<a href="mailto:silvas@purdue.edu" target="_blank">silvas@purdue.edu</a>></span><br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Dec 28, 2013 at 9:47 PM, Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">Hi Sean,<div><br></div><div>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).</div>
<div><br></div><div>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.</div>
<div><br></div><div>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:</div>
<div><br></div><div> 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).</div>
<div> 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).</div></div></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr"><div><br></div><div>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.</div>
</div></blockquote><div><br></div><div>I think you misunderstood what I meant by "guide for frontend implementers". Hopefully my comments below clear up what I mean.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
<div dir="ltr">
<div><br></div><div>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.</div>
</div></blockquote><div><br></div><div>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).</div>
<div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">
<div><br></div><div>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.</div>
<div><br></div><div>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. </div>
<div><br></div><div>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.</div>
</div></blockquote><div><br></div><div>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.</div>
<div><br></div><div>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".</div>
<div><br></div><div>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).</div>
<div><br></div><div>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").</div>
<div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><br></div><div>-- Sean Silva</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">
<div><br></div><div>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!</div>
</div></blockquote><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><span><font color="#888888">
<div><br></div><div><br></div><div>-- Mikael</div></font></span></div><div><div><div class="gmail_extra"><br><br><div class="gmail_quote">2013/12/29 Sean Silva <span dir="ltr"><<a href="mailto:silvas@purdue.edu" target="_blank">silvas@purdue.edu</a>></span><br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">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.<div>
<br></div><div>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.</div>
<div><br></div><div>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.</div>
<div><div><br></div><div>-- Sean Silva</div></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sat, Dec 28, 2013 at 7:46 PM, Mikael Lyngvig <span dir="ltr"><<a href="mailto:mikael@lyngvig.org" target="_blank">mikael@lyngvig.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div>This document explains how to map various high-level language constructs to LLVM IR.</div>
<div><br>
</div>The document is now ready to go live (and to be reviewed) even if it is nowhere near complete. <div>
<br></div><div>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.<div>
<br></div><div>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.</div>
<div><br></div><div>Comments, critique, suggestions, enhancement requests, etc., are happily accepted!</div><div><br></div><div>Once the document has been made part of the LLVM website, I'll remove my Github copy of it.</div>
<span><font color="#888888">
<div><br></div><div><br></div><div>-- Mikael</div><div><div><br></div><div><br><div><br></div><div><br></div></div></div></font></span></div></div>
<br>_______________________________________________<br>
llvm-commits mailing list<br>
<a href="mailto:llvm-commits@cs.uiuc.edu" target="_blank">llvm-commits@cs.uiuc.edu</a><br>
<a href="http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits" target="_blank">http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits</a><br>
<br></blockquote></div><br></div>
</blockquote></div><br></div>
</div></div></blockquote></div><br></div></div>
</blockquote></div><br></div>