1========
2ABI tags
3========
4
5Introduction
6============
7
8This text tries to describe gcc semantic for mangling "abi_tag" attributes
9described in https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html
10
11There is no guarantee the following rules are correct, complete or make sense
12in any way as they were determined empirically by experiments with gcc5.
13
14Declaration
15===========
16
17ABI tags are declared in an abi_tag attribute and can be applied to a
18function, variable, class or inline namespace declaration. The attribute takes
19one or more strings (called tags); the order does not matter.
20
21See https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html for
22details.
23
24Tags on an inline namespace are called "implicit tags", all other tags are
25"explicit tags".
26
27Mangling
28========
29
30All tags that are "active" on an <unqualified-name> are emitted after the
31<unqualified-name>, before <template-args> or <discriminator>, and are part of
32the same <substitution> the <unqualified-name> is.
33
34They are mangled as:
35
36.. code-block:: none
37
38    <abi-tags> ::= <abi-tag>*   # sort by name
39    <abi-tag> ::= B <tag source-name>
40
41Example:
42
43.. code-block:: c++
44
45    __attribute__((abi_tag("test")))
46    void Func();
47    // gets mangled as: _Z4FuncB4testv (prettified as `Func[abi:test]()`)
48
49Active tags
50===========
51
52A namespace does not have any active tags. For types (class / struct / union /
53enum), the explicit tags are the active tags.
54
55For variables and functions, the active tags are the explicit tags plus any
56"required tags" which are not in the "available tags" set:
57
58.. code-block:: none
59
60    derived-tags := (required-tags - available-tags)
61    active-tags := explicit-tags + derived-tags
62
63Required tags for a function
64============================
65
66If a function is used as a local scope for another name, and is part of
67another function as local scope, it doesn't have any required tags.
68
69If a function is used as a local scope for a guard variable name, it doesn't
70have any required tags.
71
72Otherwise the function requires any implicit or explicit tag used in the name
73for the return type.
74
75Example:
76
77.. code-block:: c++
78
79    namespace A {
80      inline namespace B __attribute__((abi_tag)) {
81        struct C { int x; };
82      }
83    }
84
85    A::C foo(); // gets mangled as: _Z3fooB1Bv (prettified as `foo[abi:B]()`)
86
87Required tags for a variable
88============================
89
90A variable requires any implicit or explicit tag used in its type.
91
92Available tags
93==============
94
95All tags used in the prefix and in the template arguments for a name are
96available. Also, for functions, all tags from the <bare-function-type>
97(which might include the return type for template functions) are available.
98
99For <local-name>s all active tags used in the local part (<function-
100encoding>) are available, but not implicit tags which were not active.
101
102Implicit and explicit tags used in the <unqualified-name> for a function (as
103in the type of a cast operator) are NOT available.
104
105Example: a cast operator to std::string (which is
106std::__cxx11::basic_string<...>) will use 'cxx11' as an active tag, as it is
107required from the return type `std::string` but not available.
108