<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div><blockquote type="cite" class=""><div class="">On May 17, 2017, at 8:29 AM, Gábor Horváth via cfe-dev <<a href="mailto:cfe-dev@lists.llvm.org" class="">cfe-dev@lists.llvm.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class=""><div class=""><div class=""><div class=""><div class="">Hi!<br class=""><br class=""></div>I wanted to revive the discussion on adding API notes feature to Clang. <br class=""></div></div></div></div></div></blockquote><div><br class=""></div>Thank you for bringing this up!</div><div><br class=""></div><div><blockquote type="cite" class=""><div class=""><div dir="ltr" class=""><div class=""><div class=""><b class="">The description of the feature from the original discussion</b><br class=""><br class="">"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’."</div><div class=""><br class="">The old discussion can be found here: <a href="http://lists.llvm.org/pipermail/cfe-dev/2015-December/046335.html" class="">http://lists.llvm.org/pipermail/cfe-dev/2015-December/046335.html</a><br class=""><br class=""></div><b class="">The summary of the discussion</b><br class=""><br class=""></div><div class="">* It would be useful for the static analyzer to attach additional info to the functions<br class="">* There were already other trials to get similar feature working, see <a href="https://reviews.llvm.org/D13731" class="">https://reviews.llvm.org/D13731</a><br class=""></div><div class="">* Anna has a nice summary what is the problem with augmented declarations: <a href="http://lists.llvm.org/pipermail/cfe-dev/2015-December/046378.html" class="">http://lists.llvm.org/pipermail/cfe-dev/2015-December/046378.html</a><br class=""></div><div class="">* C++ support is requested by the community, this is missing right now. <br class=""></div><div class="">* Wider range of annotation support is missing. It is also requested by the community. <br class=""></div><div class="">* Parameter annotations are supported<br class=""></div><div class="">* One of the concerns is the performance<br class=""><br class=""></div><div class=""><b class="">The case for adding API Notes</b><br class=""><br class=""></div><div class="">* Importing annotations from external source looks to be an interesting feature for the community<br class=""></div><div class="">* Sean presented some API checkers which works based on special annotations: <a href="http://llvm.org/devmtg/2017-03//2017/02/20/accepted-sessions.html#29" class="">http://llvm.org/devmtg/2017-03//2017/02/20/accepted-sessions.html#29</a><br class=""></div><div class="">* 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: <a href="https://www.google-melange.com/archive/gsoc/2014/orgs/llvm/projects/xazax.html" class="">https://www.google-melange.com/archive/gsoc/2014/orgs/llvm/projects/xazax.html</a><br class="">* 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<br class=""></div><div class="">* It would also be possible to import sanitizer/optimizer/codegen related annotations<br class=""></div></div></div></blockquote><div><br class=""></div><div>* 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.</div><br class=""><blockquote type="cite" class=""><div class=""><div dir="ltr" class=""><div class=""><b class="">Proposed roadmap</b><br class=""></div><div class=""><br class=""></div><div class="">* Commit the feature as is<br class=""></div><div class="">* Extend it with C++ support (namespaces, overloading, templates..)<br class=""></div><div class="">* Extend it with additional annotations, and attaching custom data (like fake function bodies)</div></div></div></blockquote><div><br class=""></div><div>I suggest considering</div><div><br class=""></div><div>* Generalize to work with all attributes</div><div><br class=""></div><div>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</div><div><br class=""></div><div> __attribute__((whatever))</div><div><br class=""></div><div>or</div><div><br class=""></div><div> [[whatever]]</div><div><br class=""></div><div>it would obviate the need to manually add more fields.</div><br class=""><blockquote type="cite" class=""><div class=""><div dir="ltr" class=""><div class="">What do you think? What are the main concerns with this feature?<br class=""></div></div></div></blockquote></div><div class=""><br class=""></div>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.<br class=""><div class=""><br class=""></div><div class="">I’m totally fine with this plan.</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>- Doug</div><div class=""><br class=""></div></body></html>