========
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:

.. code-block:: none

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

Example:

.. code-block:: 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:

.. code-block:: none

    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:

.. code-block:: 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.