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

[Anna Zaks]

On Jan 13, 2013, at 10:23 AM, Sam Handler <samuel.handler+cfedev at gmail.com> wrote:

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

My hope is that we have more resources and dedication to keep the main analyzer page up to date.

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

I've guessed that. We've added the macros as we were preparing the presentation.

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

Thanks!

I prefer the manual be in the same format as the rest of the site. I don't think anyone subscribed to translate the whole site to Sphinx yet, so it might be easier to go with HTML for now. If you can find a way to use RST but ensure that the style would match the rest of the page (should be doable), that would be good too.

> 
> 
> 
> -- 
> ===============================================================================
> 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/20130114/67358f6a/attachment.html>