From 39fcc9a984e2820e4ea0fa2ac4abd17d9f3a31df Mon Sep 17 00:00:00 2001 From: dim Date: Sun, 20 Feb 2011 13:06:31 +0000 Subject: Vendor import of clang trunk r126079: http://llvm.org/svn/llvm-project/cfe/trunk@126079 --- docs/InternalsManual.html | 125 +++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 113 insertions(+), 12 deletions(-) (limited to 'docs/InternalsManual.html') diff --git a/docs/InternalsManual.html b/docs/InternalsManual.html index 6df26db..813015e 100644 --- a/docs/InternalsManual.html +++ b/docs/InternalsManual.html @@ -25,6 +25,7 @@ td {
  • The Diagnostics Subsystem
  • The SourceLocation and SourceManager classes
    • +
  • SourceRange and CharSourceRange
  • The Driver Library @@ -68,6 +69,11 @@ td {
  • The Index Library
    • +
  • Howto guides + +
    • @@ -145,15 +151,14 @@ diagnostic :).

    pieces, this section describes them and talks about best practices when adding a new diagnostic.

    - -

    The Diagnostic*Kinds.def files

    - + +

    The Diagnostic*Kinds.td files

    +

    Diagnostics are created by adding an entry to one of the -clang/Basic/Diagnostic*Kinds.def files, depending on what library will -be using it. This file encodes the unique ID of the -diagnostic (as an enum, the first argument), the severity of the diagnostic -(second argument) and the English translation + format string.

    +clang/Basic/Diagnostic*Kinds.td files, depending on what library will +be using it. From this file, tblgen generates the unique ID of the diagnostic, +the severity of the diagnostic and the English translation + format string.

    There is little sanity with the naming of the unique ID's right now. Some start with err_, warn_, ext_ to encode the severity into the name. Since the @@ -237,7 +242,7 @@ are some simple format strings:

    + +

    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.

    -- cgit v1.1