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

[Sam Handler]

We've discussed this internally and decided that we should not advertise
> "the checker as a plugin" capability until we are ready to support it.
> Currently, we have not tested it on any platforms other than OS X, so we
> are not sure, for example, if the plugins are going to work on Windows. We
> also do not know if the compilers shipped on various platforms have their
> symbols stripped or not. In addition, there is no effort to guarantee a
> rigid checker API. The compiler and the plugins are expected to use the
> same headers. Due to this, the plugins will only work with the compiler
> they are written for. With the second restriction, in most cases, just
> adding the checker to the source code of the compiler would be a good
> option.
>

Good points. As I recall, the MSVC compiler produces completely stripped
binaries by default.


> Said that, it would be too bad to loose all the content you've added to
> explain how the plugins could be used. Maybe we could make it an internal
> document in the docs directory (not exposed on the website) with a
> disclaimer that it is an experimental feature.
>

 I would be okay with this. That part should split out rather easily.


> The second issue is that the LockUnlockChecker checker is rather weak. It
> does not solve a real problem (ex: assumes that all the locking/unlocking
> happen in one function, which is not realistic); in addition, it does not
> showcase a lot of topics we would want to explain (ex: symbols). How about
> using the SimpleStreamChecker checker that we've presented in the talk?
> It's not too easy and not too complicated. The source code is available in
> the repository.
>

I freely admit that the LockUnlockChecker does not solve a real problem; it
was created to be the absolute simplest possible example of something that
requires tracking of state.

I think that the SimpleStreamChecker is the simplest possible checker that
solves a "real-world" problem. In addition, the concept is simpler to
explain, as the functions used are part of a standard API, instead of being
contrived solely for the example. And like you said, it shows the use of
symbols, which are a big part of the analyzer.

So overall, I agree that the SimpleStreamChecker would be a better example.

- We should assume that the reader works with TOT, not the latest released
> clang version. We'll try to do our best to keep the manual up to date.
>

If the examples can be kept up to date, this is fine. My primary reason for
given a specific version was that I have encountered older Clang tutorials
on the web that will not compile with TOT.


> Manually defining classes:
> We should not expose it in the Manual. We have a lot to talk about, so the
> shorter we keep it the better. We could create a separate internal-use doc
> (in the docs folder) about it and link to it.
>

I had written the early version of that section before the "convenience
macros" for state definition were added. Given that the macros should cover
the vast majority of use cases, I see no issue just describing those, and
offering additional details in a separate document for those who really
need/want to know.



(All of your other comments - I will try to address these in future
versions).

Thanks for taking the time to read it though.

To summarize, I think the manual would benefit from the content presented
> in the following sections:
>  - The Structure of a Checker
>  - Program States - An Example
>  - Extending Program States
>  - Reporting Bugs
>  - Missing info on testing and additional sources of information
>

I will try to find time to create an extended version of the Checker
Developer Manual with additional material from the tutorial. Which format
(HTML or RST) would be better for this?




-- 
===============================================================================
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/20130113/17f2780b/attachment.html>