[cfe-dev] [RFC] Adding API Notes

[Douglas Gregor via cfe-dev]

> On May 17, 2017, at 8:29 AM, Gábor Horváth via cfe-dev <cfe-dev at lists.llvm.org> wrote:
> 
> Hi!
> 
> I wanted to revive the discussion on adding API notes feature to Clang. 

Thank you for bringing this up!

> The description of the feature from the original discussion
> 
> "API notes solve a not-uncommon problem: we invent some new Clang attribute that would be beneficial to add to some declarations in system headers (e.g., adding a ‘noreturn’ attribute to the C ‘exit’ function), but we can’t go around and fix all of the system headers everywhere. With API notes, we can write a separate YAML file that states that we want to add ‘noreturn’ to the ‘exit’ function: when we feed that YAML file into Clang as part of normal compilation (via a command-line option), Clang will add ‘noreturn’ to the ‘exit’ function when it parses the declaration of ‘exit’."
> 
> The old discussion can be found here: http://lists.llvm.org/pipermail/cfe-dev/2015-December/046335.html <http://lists.llvm.org/pipermail/cfe-dev/2015-December/046335.html>
> 
> The summary of the discussion
> 
> * It would be useful for the static analyzer to attach additional info to the functions
> * There were already other trials to get similar feature working, see https://reviews.llvm.org/D13731 <https://reviews.llvm.org/D13731>
> * Anna has a nice summary what is the problem with augmented declarations: http://lists.llvm.org/pipermail/cfe-dev/2015-December/046378.html <http://lists.llvm.org/pipermail/cfe-dev/2015-December/046378.html>
> * C++ support is requested by the community, this is missing right now. 
> * Wider range of annotation support is missing. It is also requested by the community. 
> * Parameter annotations are supported
> * One of the concerns is the performance
> 
> The case for adding API Notes
> 
> * Importing annotations from external source looks to be an interesting feature for the community
> * Sean presented some API checkers which works based on special annotations: http://llvm.org/devmtg/2017-03//2017/02/20/accepted-sessions.html#29 <http://llvm.org/devmtg/2017-03//2017/02/20/accepted-sessions.html#29>
> * Similar feature can be used to provide fake implementations for functions. It could help to finish a half done feature of the Static Analyzer that was implemented during a GSoC project: https://www.google-melange.com/archive/gsoc/2014/orgs/llvm/projects/xazax.html <https://www.google-melange.com/archive/gsoc/2014/orgs/llvm/projects/xazax.html>
> * Performance might be crucial for regular compilation, but less of a problem for the Clang Static Analyzer which tends to be slower than compilations, so it is less likely to be bottlenecked by this phase
> * It would also be possible to import sanitizer/optimizer/codegen related annotations

* It’s the biggest difference between LLVM Clang and Swift’s downstream fork. Apple might be the only major client that cares about this, but I think smaller divergence here would be great.

> Proposed roadmap
> 
> * Commit the feature as is
> * Extend it with C++ support (namespaces, overloading, templates..)
> * Extend it with additional annotations, and attaching custom data (like fake function bodies)

I suggest considering

* Generalize to work with all attributes

Most of the fields in API notes are hard-coded to produce a particular attribute. If instead we had a general “Attributes” field where one could spell out

  __attribute__((whatever))

or

  [[whatever]]

it would obviate the need to manually add more fields.

> What do you think? What are the main concerns with this feature?


From my perspective, I’ve changed my mind from “this should never go into upstream Clang” to “yeah, it probably makes sense”. When we built API notes originally, we viewed it as a stop-gap solution and had hoped to phase it out. However, in the years since, we’ve found it to be *really* useful and are constantly fielding requests to make it more widely applicable. The simple reality of the C languages is that you cannot control the headers you’re working with, and there are a plethora of use cases where adding application-specific information to those headers can improve a product.

I’m totally fine with this plan.

	- Doug

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