[LLVMdev] request for tutorial

[Sean Silva]

On Thu, Sep 26, 2013 at 12:22 PM, Preston Briggs
<preston.briggs at gmail.com>wrote:

> I think y'all underestimate how important documentation can be.
>

I'm a strong proponent for good documentation, and whenever I get a solid
understanding of a specific part of LLVM I will usually write documentation
for it. (I'm pretty clueless about backend stuff, which is why I haven't
produced any documentation there!)

I think it's largely an issue with LLVM's culture. If somebody commits
something without tests, they will rapidly receive code review feedback
asking for tests; if someone adds a diagnostic to clang that has a really
bad user experience, they will be flagged for it and asked to improve it.

On the other hand, if somebody commits something without documentation (or
with poor documentation), usually I'm the only one that will flag them for
it and ask them to improve it.


> There are, after all, documents out there that purport to be guides to
> writing a back end for LLVM. I know of 2 other experienced & motivated
> compiler writers who read the available documentation, wrote some code,
> foundered, gave up, and wrote their own back end from scratch. So there's
> three of us that I know about, and I don't get around much.
>

This makes me kind of depressed. I had always surmised that most of the
reason that I had a hard time grokking the backend code was due to simply
not having any formal compiler education (e.g. never taken a course or read
a book about it), so last weekend I read Cooper & Torczon's "Engineering a
Compiler" in an attempt to gain a better understanding of the subject. If
you're having a hard time grokking the LLVM backend stuff (and you're the
most cited author (excluding self-citations) in EaC), then I'm not sure
what my prospects are...


> A friend in the newspaper business said they had a rule of thumb that said
> approximately: "One letter from a reader implies another hundred readers
> out there who had the same opinion."
>
> Preston
>
>
>
>
> On Wed, Sep 25, 2013 at 2:22 PM, Renato Golin <renato.golin at linaro.org>wrote:
>
>> On 25 September 2013 22:13, Preston Briggs <preston.briggs at gmail.com>wrote:
>>
>>>  A lot of my difficulty in reading other examples is that it's not clear
>>> what matters and what doesn't. It's what I hope to get by sitting next to
>>> someone and asking questions. Some of this could be addressed in a guide.
>>> I'd start with a chapter on planning.
>>>
>>
>> Another approach, a mix between a dummy back end and Karen's proposal, is
>> to not only write documents on how things piece together, but also add
>> comments to the code on how important this file/function is, how it fits
>> with the rest, and how generic/specific it is.
>>
>> Documentations get outdated more often than comments in the code, and
>> LLVM is particularly good at generic comments, but not so much at teaching
>> how to use the code.
>>
>> Patches adding comments are also a good way to learn how something works.
>> You send a comment, people say how wrong that is, and in the end, you learn
>> by teaching others via your comments.
>>
>> cheers,
>> --renato
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20130926/0aebfd0b/attachment.html>