From: Jeffrey Yasskin Date: Fri, 28 Jan 2011 23:41:54 +0000 (+0000) Subject: Document how to add an attribute to clang. This should be reviewed by someone X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=28dadd6c88e0b93b1b99edd460548625359786b7;p=clang Document how to add an attribute to clang. This should be reviewed by someone who actually knows how it works. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@124506 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index 0720329cbd..596c1b2f12 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -69,6 +69,11 @@ td {
  • The Index Library
    • +
  • Howto guides + +
    • @@ -1711,7 +1716,78 @@ interacts with constant evaluation:

    + +

    How to change Clang

    + + + +

    How to add an attribute

    + +

    To add an attribute, you'll have to add it to the list of attributes, add it +to the parsing phase, and look for it in the AST scan. +r124217 +has a good example of adding a warning attribute.

    + +

    (Beware that this hasn't been reviewed/fixed by the people who designed the +attributes system yet.)

    + +

    include/clang/Basic/Attr.td

    + +

    Each attribute gets a def inheriting from Attr or one of +its subclasses. InheritableAttr means that the attribute also applies +to subsequent declarations of the same name.

    + +

    Spellings lists the strings that can appear in +__attribute__((here)) or [[here]]. All such strings +will be synonymous. If you want to allow the [[]] C++0x +syntax, you have to define a list of Namespaces, which will +let users write [[namespace:spelling]]. Using the empty +string for a namespace will allow users to write just the spelling +with no ":".

    + +

    Subjects restricts what kinds of AST node to which this attribute +can appertain (roughly, attach).

    + +

    Args names the arguments the attribute takes, in order. If +Args is [StringArgument<"Arg1">, IntArgument<"Arg2">] +then __attribute__((myattribute("Hello", 3))) will be a valid use.

    + +

    Boilerplate

    + +

    Add an element to the AttributeList::Kind enum in include/clang/Sema/AttributeList.h +named AT_lower_with_underscores. That is, a CamelCased +AttributeName in Attr.td name should become +AT_attribute_name.

    + +

    Add a case to the StringSwitch in AttributeList::getKind() +in lib/Sema/AttributeList.cpp +for each spelling of your attribute. Less common attributes should come toward +the end of that list.

    + +

    Write a new HandleYourAttr() function in lib/Sema/SemaDeclAttr.cpp, +and add a case to the switch in ProcessNonInheritableDeclAttr() or +ProcessInheritableDeclAttr() forwarding to it.

    + +

    If your attribute causes extra warnings to fire, define a DiagGroup +in include/clang/Basic/DiagnosticGroups.td +named after the attribute's Spelling with "_"s replaced by "-"s. If +you're only defining one diagnostic, you can skip DiagnosticGroups.td +and use InGroup<DiagGroup<"your-attribute">> directly in DiagnosticSemaKinds.td

    + +

    The meat of your attribute

    + +

    Find an appropriate place in Clang to do whatever your attribute needs to do. +Check for the attribute's presence using Decl::getAttr<YourAttr>().

    + +

    Update the Clang Language Extensions +document to describe your new attribute.