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

[Sam Handler]

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 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?

On a related note: are there plans to convert the analyzer documentation
(and other items in www/) from HTML to RST format? 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.




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/20121230/3620b211/attachment.html>