# ABI tags

## Introduction

This text tries to describe gcc semantic for mangling "abi_tag" attributes
described in <https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html>

There is no guarantee the following rules are correct, complete or make sense
in any way as they were determined empirically by experiments with gcc5.

## Declaration

ABI tags are declared in an abi_tag attribute and can be applied to a
function, variable, class or inline namespace declaration. The attribute takes
one or more strings (called tags); the order does not matter.

See <https://gcc.gnu.org/onlinedocs/gcc/C_002b_002b-Attributes.html> for
details.

Tags on an inline namespace are called "implicit tags", all other tags are
"explicit tags".

## Mangling

All tags that are "active" on an `<unqualified-name>` are emitted after the
`<unqualified-name>`, before `<template-args>` or `<discriminator>`, and are
part of the same `<substitution>` the `<unqualified-name>` is.

They are mangled as:

```bnf
<abi-tags> ::= <abi-tag>*   # sort by name
<abi-tag> ::= B <tag source-name>
```

Example:

```c++
__attribute__((abi_tag("test")))
void Func();
// gets mangled as: _Z4FuncB4testv (prettified as `Func[abi:test]()`)
```

## Active tags

A namespace does not have any active tags. For types (class / struct / union /
enum), the explicit tags are the active tags.

For variables and functions, the active tags are the explicit tags plus any
"required tags" which are not in the "available tags" set:

```bnf
derived-tags := (required-tags - available-tags)
active-tags := explicit-tags + derived-tags
```

## Required tags for a function

If a function is used as a local scope for another name, and is part of
another function as local scope, it doesn't have any required tags.

If a function is used as a local scope for a guard variable name, it doesn't
have any required tags.

Otherwise the function requires any implicit or explicit tag used in the name
for the return type.

Example:

```c++
namespace A {
  inline namespace B __attribute__((abi_tag)) {
    struct C { int x; };
  }
}

A::C foo(); // gets mangled as: _Z3fooB1Bv (prettified as `foo[abi:B]()`)
```

## Required tags for a variable

A variable requires any implicit or explicit tag used in its type.

## Available tags

All tags used in the prefix and in the template arguments for a name are
available. Also, for functions, all tags from the `<bare-function-type>`
(which might include the return type for template functions) are available.

For `<local-name>`s all active tags used in the local part
(`<function-encoding>`) are available, but not implicit tags which were not
active.

Implicit and explicit tags used in the `<unqualified-name>` for a function (as
in the type of a cast operator) are NOT available.

Example: a cast operator to std::string (which is
`std::__cxx11::basic_string<...>`) will use 'cxx11' as an active tag, as it is
required from the return type `std::string` but not available.
