<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><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><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><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><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><br></div><div><br></div><div>-- Mikael</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">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:0 0 0 .8ex;border-left:1px #ccc 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>