[cfe-dev] [RFC] Tutorial for Clang Analyzer Plugins

[Anna Zaks]

On Dec 30, 2012, at 5:56 PM, Sam Handler <samuel.handler+cfedev at gmail.com> wrote:

> I have seen both of those. I actually started work on the tutorial before the talk was given. I now see the tutorial as being similar to the talk, but a bit more thorough (by virtue of not being confined to the format of a presentation).
> 
> I really like the idea of having a motivating example that ties all the information together and "drives" the concepts that are explained. At the same time, such an example limits what can be included. For example, the tutorial contains no discussion of value evaluation (SVals, etc.), because it not relevant to the example at hand. This limitation will always be true of a tutorial-like presentation.
> 
> I see three options:
> 
> 1) Put up the tutorial as is, and work on filling in the Checker Writer Manual (perhaps using some of the same content) as a separate effort.
> 2) Move most of the more technical content to the Checker Writer Manual, and have the tutorial as a separate page, referencing it as appropriate. I think that this would be too confusing for readers (too much back-and-forth between the two documents).
> 3) Integrate the two documents into one, with the tutorial (sans heavy technical details) at the end as an example of the concepts presented.
> 

I think this option is the best. Your tutorial explains many concepts in detail; the kind of info you would expect to see in the manual. We should not repeat the same info in two places (tutorial and manual), so the best option is to combine them. The current manual does use code snippets to explain some APIs; it would be good if those would come from a self-contained checker, presented at the end.

> I think option 3 would likely be the best long-term option, but am curious to hear what others think. Is having a completely self-contained tutorial useful?
> 

I view the presentation as a self-contained tutorial. 

However, I am also curious to see what others think.

> On a related note: are there plans to convert the analyzer documentation (and other items in www/) from HTML to RST format?

Would be great to have the analyzer documentation converted, but I don't know if anyone has committed to do the work.

> I put the tutorial in RST format because I saw that that is the format that Clang documentation is moving towards. If such a conversion is imminent, I would probably want to wait until it is complete before attempting to merge the two documents.
> 
> 
> 

Thanks fro working on this!
Anna.

> 
> On Sun, Dec 30, 2012 at 12:54 AM, Anna Zaks <ganna at apple.com> wrote:
> Hi Sam,
> 
> Thanks for writing this up!
> 
> We currently have the following as documentation for people writing their own checkers:
>  - "Building a checker in 24 hours" tutorial talk. See http://llvm.org/devmtg/2012-11/
>  - Checker Writer Manual, which is far from being finished: http://clang-analyzer.llvm.org/checker_dev_manual.html
> 
> Your tutorial is somewhere in between. It provides in depth info on some of the aspects of writing a checker as well as being a tutorial. For example, the section on bug reporting and adding checker state would be a good addition to the manual. Also, registering a checker as a plugin could also be a section in the manual. 
> 
> I am not 100% sure where your tutorial should go and how it compliments what's already there. (I am not sure if you were aware of the existence of the other two documents.) What do you think?
> 
> Cheers,
> Anna.
> 
> On Dec 29, 2012, at 3:52 PM, Sam Handler <samuel.handler+cfedev at gmail.com> wrote:
> 
>> All,
>> 
>> I have written a tutorial about how to create a plugin for the static analyzer. The target audience is developers who reasonably familiar with using Clang, but are unsure how they would go about extending Clang for custom analysis cases.
>> 
>> The tutorial describes a complete example of a plugin that checks for proper use of a trivial locking construct. This was the simplest example I could think of that requires the use of stored program state.
>> 
>> The tutorial covers in detail everything needed to write a plugin, including: the interface between Clang and the plugin, how to subclass Checker, defining and using custom program state data, reporting found bugs, and compilation. As such, it is relatively self-contained.
>> 
>> Any feedback would be greatly appreciated. I hope to get this integrated into the Clang documentation, but I am unsure about what the best way to do that would be; any suggestions about that would also be welcome.
>> 
>> 
>> -- 
>> ===============================================================================
>> All opinions expressed in posts from this account are entirely my own, and not
>> those of any present or former employer. Furthermore, I assert that all works
>> contributed to the Clang project (1) were developed using no equipment,
>> supplies, facility or trade secrets of any such employer, (2) were developed
>> entirely on my own time, and (3) do not result from any work performed for any
>> such employer.
>> 
>> <AnalyzerPlugin.rst>_______________________________________________
>> cfe-dev mailing list
>> cfe-dev at cs.uiuc.edu
>> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-dev
> 
> 
> 
> 
> -- 
> ===============================================================================
> All opinions expressed in posts from this account are entirely my own, and not
> those of any present or former employer. Furthermore, I assert that all works
> contributed to the Clang project (1) were developed using no equipment,
> supplies, facility or trade secrets of any such employer, (2) were developed
> entirely on my own time, and (3) do not result from any work performed for any
> such employer.
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20130102/2c050d94/attachment.html>