[multiple changes]

[gcc.git] / libstdc++-v3 / doc / xml / manual / abi.xml

<sect1 id="appendix.porting.abi" xreflabel="abi">
<?dbhtml filename="abi.html"?>
 
<sect1info>
  <keywordset>
    <keyword>
      C++
    </keyword>
    <keyword>
      ABI
    </keyword>
    <keyword>
      version
    </keyword>
    <keyword>
      dynamic
    </keyword>
    <keyword>
      shared
    </keyword>
  </keywordset>
</sect1info>

<title>ABI Policy and Guidelines</title>

<para>
</para>

<sect2 id="abi.cxx_interface" xreflabel="abi.cxx_interface">
<title>The C++ Interface</title>

<para>
  C++ applications often dependent on specific language support
  routines, say for throwing exceptions, or catching exceptions, and
  perhaps also dependent on features in the C++ Standard Library.
</para>

<para> 
  The C++ Standard Library has many include files, types defined in
  those include files, specific named functions, and other
  behavior. The text of these behaviors, as written in source include
  files, is called the Application Programing Interface, or API.
</para>

<para> 
  Furthermore, C++ source that is compiled into object files is
  transformed by the compiler: it arranges objects with specific
  alignment and in a particular layout, mangling names according to a
  well-defined algorithm, has specific arrangements for the support of
  virtual functions, etc. These details are defined as the compiler
  Application Binary Interface, or ABI. The GNU C++ compiler uses an
  industry-standard C++ ABI starting with version 3. Details can be
  found in the <ulink
  url="http://www.codesourcery.com/cxx-abi/abi.html"> ABI
  specification</ulink>.
</para>

<para>
 The GNU C++ compiler, g++, has a compiler command line option to
  switch between various different C++ ABIs. This explicit version
  switch is the flag <code>-fabi-version</code>. In addition, some
  g++ command line options may change the ABI as a side-effect of
  use. Such flags include <code>-fpack-struct</code> and
  <code>-fno-exceptions</code>, but include others: see the complete
  list in the GCC manual under the heading <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options
  for Code Generation Conventions</ulink>.
</para>

<para> 
  The configure options used when building a specific libstdc++
  version may also impact the resulting library ABI. The available
  configure options, and their impact on the library ABI, are
  documented
<ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html">
here</ulink>.
</para>

<para> Putting all of these ideas together results in the C++ Standard
library ABI, which is the compilation of a given library API by a
given compiler ABI. In a nutshell:
</para>

<para>
  <quote>
    library API + compiler ABI = library ABI
  </quote>
</para>

<para>
 The library ABI is mostly of interest for end-users who have
 unresolved symbols and are linking dynamically to the C++ Standard
 library, and who thus must be careful to compile their application
 with a compiler that is compatible with the available C++ Standard
 library binary. In this case, compatible is defined with the equation
 above: given an application compiled with a given compiler ABI and
 library API, it will work correctly with a Standard C++ Library
 created with the same constraints.
</para>

<para>
  To use a specific version of the C++ ABI, one must use a
  corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that
  implements the C++ ABI in question.
</para>

</sect2>

<sect2 id="abi.versioning" xreflabel="abi.versioning">
<title>Versioning</title>

<para> The C++ interface has evolved throughout the history of the GNU
C++ toolchain. With each release, various details have been changed so
as to give distinct versions to the C++ interface.
</para>
  
  <sect3 id="abi.versioning.goals" xreflabel="abi.versioning.goals">
    <title>Goals</title>

<para>Extending existing, stable ABIs. Versioning gives subsequent stable
releases series libraries the ability to add new symbols and add
functionality, all the while retaining backwards compatibility with
the previous releases in the series. Note: the reverse is not true. It
is not possible to take binaries linked with the latest version of a
release series (if symbols have been added) and expect the initial
release of the series to remain link compatible.
</para>

<para>Allows multiple, incompatible ABIs to coexist at the same time.
</para>
  </sect3>

  <sect3 id="abi.versioning.history" xreflabel="abi.versioning.history">
    <title>History</title>

<para>
 How can this complexity be managed? What does C++ versioning mean?
  Because library and compiler changes often make binaries compiled
  with one version of the GNU tools incompatible with binaries
  compiled with other (either newer or older) versions of the same GNU
  tools, specific techniques are used to make managing this complexity
  easier.
</para>

<para>
  The following techniques are used:
</para>

  <orderedlist>

    <listitem><para>Release versioning on the libgcc_s.so binary. </para>

    <para>This is implemented via file names and the ELF DT_SONAME
    mechanism (at least on ELF systems). It is versioned as follows:
    </para>

    <itemizedlist>
    <listitem><para>gcc-3.0.0: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.0.1: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.0.2: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.0.3: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.0.4: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.1.0: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.1.1: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.2.0: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.2.1: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.2.2: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.2.3: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.3.0: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.3.1: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.3.2: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.3.3: libgcc_s.so.1</para></listitem>
    <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: on m68k-linux and
    hppa-linux this is either libgcc_s.so.1 (when configuring
    <code>--with-sjlj-exceptions</code>) or libgcc_s.so.2. For all
    others, this is libgcc_s.so.1.  </para>
    </listitem> 
    </itemizedlist>
    
  </listitem>

    <listitem><para>Symbol versioning on the libgcc_s.so binary.</para>

    <para>It is versioned with the following labels and version
   definitions, where the version definition is the maximum for a
   particular release. Labels are cumulative. If a particular release
   is not listed, it has the same version labels as the preceding
   release.</para>

    <para>This corresponds to the mapfile: gcc/libgcc-std.ver</para>
    <itemizedlist>
    <listitem><para>gcc-3.0.0: GCC_3.0</para></listitem>
    <listitem><para>gcc-3.3.0: GCC_3.3</para></listitem>
    <listitem><para>gcc-3.3.1: GCC_3.3.1</para></listitem>
    <listitem><para>gcc-3.3.2: GCC_3.3.2</para></listitem>
    <listitem><para>gcc-3.3.4: GCC_3.3.4</para></listitem>
    <listitem><para>gcc-3.4.0: GCC_3.4</para></listitem>
    <listitem><para>gcc-3.4.2: GCC_3.4.2</para></listitem>
    <listitem><para>gcc-3.4.4: GCC_3.4.4</para></listitem>
    <listitem><para>gcc-4.0.0: GCC_4.0.0</para></listitem>
    <listitem><para>gcc-4.1.0: GCC_4.1.0</para></listitem>
    <listitem><para>gcc-4.2.0: GCC_4.2.0</para></listitem>
    </itemizedlist>
    </listitem>

    <listitem><para>Release versioning on the libstdc++.so binary, implemented in the same was as the libgcc_s.so binary, above.</para>

    <para>It is versioned as follows:
    </para>
    <itemizedlist>
    <listitem><para>gcc-3.0.0: libstdc++.so.3.0.0</para></listitem>
    <listitem><para>gcc-3.0.1: libstdc++.so.3.0.1</para></listitem>
    <listitem><para>gcc-3.0.2: libstdc++.so.3.0.2</para></listitem>
    <listitem><para>gcc-3.0.3: libstdc++.so.3.0.2 (Error should be libstdc++.so.3.0.3)</para></listitem>
    <listitem><para>gcc-3.0.4: libstdc++.so.3.0.4</para></listitem>
    <listitem><para>gcc-3.1.0: libstdc++.so.4.0.0</para></listitem>
    <listitem><para>gcc-3.1.1: libstdc++.so.4.0.1</para></listitem>
    <listitem><para>gcc-3.2.0: libstdc++.so.5.0.0</para></listitem>
    <listitem><para>gcc-3.2.1: libstdc++.so.5.0.1</para></listitem>
    <listitem><para>gcc-3.2.2: libstdc++.so.5.0.2</para></listitem>
    <listitem><para>gcc-3.2.3: libstdc++.so.5.0.3 (Not strictly required)</para></listitem>
    <listitem><para>gcc-3.3.0: libstdc++.so.5.0.4</para></listitem>
    <listitem><para>gcc-3.3.1: libstdc++.so.5.0.5</para></listitem>
    <listitem><para>gcc-3.3.2: libstdc++.so.5.0.5</para></listitem>
    <listitem><para>gcc-3.3.3: libstdc++.so.5.0.5</para></listitem>
    <listitem><para>gcc-3.4.0: libstdc++.so.6.0.0</para></listitem>
    <listitem><para>gcc-3.4.1: libstdc++.so.6.0.1</para></listitem>
    <listitem><para>gcc-3.4.2: libstdc++.so.6.0.2</para></listitem>
    <listitem><para>gcc-3.4.3: libstdc++.so.6.0.3</para></listitem>
    <listitem><para>gcc-3.4.4: libstdc++.so.6.0.3</para></listitem>
    <listitem><para>gcc-3.4.5: libstdc++.so.6.0.3</para></listitem>
    <listitem><para>gcc-3.4.6: libstdc++.so.6.0.3</para></listitem>
    <listitem><para>gcc-4.0.0: libstdc++.so.6.0.4</para></listitem>
    <listitem><para>gcc-4.0.1: libstdc++.so.6.0.5</para></listitem>
    <listitem><para>gcc-4.0.2: libstdc++.so.6.0.6</para></listitem>
    <listitem><para>gcc-4.0.3: libstdc++.so.6.0.7</para></listitem>
    <listitem><para>gcc-4.1.0: libstdc++.so.6.0.7</para></listitem>
    <listitem><para>gcc-4.1.1: libstdc++.so.6.0.8</para></listitem>
    <listitem><para>gcc-4.1.2: libstdc++.so.6.0.8</para></listitem>
    <listitem><para>gcc-4.2.0: libstdc++.so.6.0.9</para></listitem>
    </itemizedlist>
    </listitem>

    <listitem><para>Symbol versioning on the libstdc++.so binary.</para>

    <para>mapfile: libstdc++/config/linker-map.gnu</para>
    <para>It is versioned with the following labels and version
   definitions, where the version definition is the maximum for a
   particular release. Note, only symbol which are newly introduced
   will use the maximum version definition. Thus, for release series
   with the same label, but incremented version definitions, the later
   release has both versions. (An example of this would be the
   gcc-3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and
   GLIBCPP_3.2 for symbols that were introduced in the gcc-3.2.0
   release.) If a particular release is not listed, it has the same
   version labels as the preceding release.
   </para>
    <itemizedlist>
    <listitem><para>gcc-3.0.0: (Error, not versioned)</para></listitem>
    <listitem><para>gcc-3.0.1: (Error, not versioned)</para></listitem>
    <listitem><para>gcc-3.0.2: (Error, not versioned)</para></listitem>
    <listitem><para>gcc-3.0.3: (Error, not versioned)</para></listitem>
    <listitem><para>gcc-3.0.4: (Error, not versioned)</para></listitem>
    <listitem><para>gcc-3.1.0: GLIBCPP_3.1, CXXABI_1</para></listitem>
    <listitem><para>gcc-3.1.1: GLIBCPP_3.1, CXXABI_1</para></listitem>
    <listitem><para>gcc-3.2.0: GLIBCPP_3.2, CXXABI_1.2</para></listitem>
    <listitem><para>gcc-3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</para></listitem>
    <listitem><para>gcc-3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem>
    <listitem><para>gcc-3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem>
    <listitem><para>gcc-3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</para></listitem>
    <listitem><para>gcc-3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
    <listitem><para>gcc-3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
    <listitem><para>gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem>
    <listitem><para>gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3</para></listitem>
    <listitem><para>gcc-3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</para></listitem>
    <listitem><para>gcc-3.4.2: GLIBCXX_3.4.2</para></listitem>
    <listitem><para>gcc-3.4.3: GLIBCXX_3.4.3</para></listitem>
    <listitem><para>gcc-4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</para></listitem>
    <listitem><para>gcc-4.0.1: GLIBCXX_3.4.5</para></listitem>
    <listitem><para>gcc-4.0.2: GLIBCXX_3.4.6</para></listitem>
    <listitem><para>gcc-4.0.3: GLIBCXX_3.4.7</para></listitem>
    <listitem><para>gcc-4.1.1: GLIBCXX_3.4.8</para></listitem>
    <listitem><para>gcc-4.2.0: GLIBCXX_3.4.9</para></listitem>
    </itemizedlist>
    </listitem>
  
    <listitem>
    <para>Incremental bumping of a compiler pre-defined macro,
    __GXX_ABI_VERSION. This macro is defined as the version of the
    compiler v3 ABI, with g++ 3.0.x being version 100. This macro will
    be automatically defined whenever g++ is used (the curious can
    test this by invoking g++ with the '-v' flag.)
    </para>
    
    <para>
    This macro was defined in the file "lang-specs.h" in the gcc/cp directory.
    Later versions defined it in "c-common.c" in the gcc directory, and from
    G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the
    '-fabi-version' command line option.
    </para>

    <para>
    It is versioned as follows, where 'n' is given by '-fabi-version=n':
    </para>
    <itemizedlist>
    <listitem><para>gcc-3.0.x: 100</para></listitem>
    <listitem><para>gcc-3.1.x: 100 (Error, should be 101)</para></listitem>
    <listitem><para>gcc-3.2.x: 102</para></listitem>
    <listitem><para>gcc-3.3.x: 102</para></listitem>
    <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 102 (when n=1)</para></listitem>
    <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 1000 + n (when n&gt;1)</para></listitem>
    <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: 999999 (when n=0)</para></listitem>
    </itemizedlist>
    <para></para>
    </listitem>

    <listitem>
    <para>Changes to the default compiler option for
    <code>-fabi-version</code>.
    </para>
   <para>
    It is versioned as follows:
    </para>
    <itemizedlist>
    <listitem><para>gcc-3.0.x: (Error, not versioned) </para></listitem>
    <listitem><para>gcc-3.1.x: (Error, not versioned) </para></listitem>
    <listitem><para>gcc-3.2.x: <code>-fabi-version=1</code></para></listitem>
    <listitem><para>gcc-3.3.x: <code>-fabi-version=1</code></para></listitem>
    <listitem><para>gcc-3.4.x, gcc-4.0.x, gcc-4.1.x, gcc-4.2.x: <code>-fabi-version=2</code></para></listitem>
    </itemizedlist>
    <para></para>
    </listitem>

   <listitem>
    <para>Incremental bumping of a library pre-defined macro. For releases
    before 3.4.0, the macro is __GLIBCPP__. For later releases, it's
    __GLIBCXX__. (The libstdc++ project generously changed from CPP to
    CXX throughout its source to allow the "C" pre-processor the CPP
    macro namespace.) These macros are defined as the date the library
    was released, in compressed ISO date format, as an unsigned long.
    </para>

    <para>
    This macro is defined in the file "c++config" in the
    "libstdc++/include/bits" directory. (Up to gcc-4.1.0, it was
    changed every night by an automated script. Since gcc-4.1.0, it is
    the same value as gcc/DATESTAMP.)
    </para>
    <para>
    It is versioned as follows:
    </para>
    <itemizedlist>
    <listitem><para>gcc-3.0.0: 20010615</para></listitem>
    <listitem><para>gcc-3.0.1: 20010819</para></listitem>
    <listitem><para>gcc-3.0.2: 20011023</para></listitem>
    <listitem><para>gcc-3.0.3: 20011220</para></listitem>
    <listitem><para>gcc-3.0.4: 20020220</para></listitem>
    <listitem><para>gcc-3.1.0: 20020514</para></listitem>
    <listitem><para>gcc-3.1.1: 20020725</para></listitem>
    <listitem><para>gcc-3.2.0: 20020814</para></listitem>
    <listitem><para>gcc-3.2.1: 20021119</para></listitem>
    <listitem><para>gcc-3.2.2: 20030205</para></listitem>
    <listitem><para>gcc-3.2.3: 20030422</para></listitem>
    <listitem><para>gcc-3.3.0: 20030513</para></listitem>
    <listitem><para>gcc-3.3.1: 20030804</para></listitem>
    <listitem><para>gcc-3.3.2: 20031016</para></listitem>
    <listitem><para>gcc-3.3.3: 20040214</para></listitem>
    <listitem><para>gcc-3.4.0: 20040419</para></listitem>
    <listitem><para>gcc-3.4.1: 20040701</para></listitem>
    <listitem><para>gcc-3.4.2: 20040906</para></listitem>
    <listitem><para>gcc-3.4.3: 20041105</para></listitem>
    <listitem><para>gcc-3.4.4: 20050519</para></listitem>
    <listitem><para>gcc-3.4.5: 20051201</para></listitem>
    <listitem><para>gcc-3.4.6: 20060306</para></listitem>
    <listitem><para>gcc-4.0.0: 20050421</para></listitem>
    <listitem><para>gcc-4.0.1: 20050707</para></listitem>
    <listitem><para>gcc-4.0.2: 20050921</para></listitem>
    <listitem><para>gcc-4.0.3: 20060309</para></listitem>
    <listitem><para>gcc-4.1.0: 20060228</para></listitem>
    <listitem><para>gcc-4.1.1: 20060524</para></listitem>
    <listitem><para>gcc-4.1.2: 20070214</para></listitem>
    <listitem><para>gcc-4.2.0: 20070514</para></listitem>
    </itemizedlist>
    <para></para>
    </listitem>

    <listitem>
    <para>
    Incremental bumping of a library pre-defined macro,
    _GLIBCPP_VERSION. This macro is defined as the released version of
    the library, as a string literal. This is only implemented in
    gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it
    is called _GLIBCXX_VERSION).
    </para>

    <para>
    This macro is defined in the file "c++config" in the
    "libstdc++/include/bits" directory and is generated
    automatically by autoconf as part of the configure-time generation
    of config.h.
    </para>

    <para>
    It is versioned as follows:
    </para>
    <itemizedlist>
    <listitem><para>gcc-3.0.0: "3.0.0"</para></listitem>
    <listitem><para>gcc-3.0.1: "3.0.0" (Error, should be "3.0.1")</para></listitem>
    <listitem><para>gcc-3.0.2: "3.0.0" (Error, should be "3.0.2")</para></listitem>
    <listitem><para>gcc-3.0.3: "3.0.0" (Error, should be "3.0.3")</para></listitem>
    <listitem><para>gcc-3.0.4: "3.0.0" (Error, should be "3.0.4")</para></listitem>
    <listitem><para>gcc-3.1.0: "3.1.0"</para></listitem>
    <listitem><para>gcc-3.1.1: "3.1.1"</para></listitem>
    <listitem><para>gcc-3.2.0: "3.2"</para></listitem>
    <listitem><para>gcc-3.2.1: "3.2.1"</para></listitem>
    <listitem><para>gcc-3.2.2: "3.2.2"</para></listitem>
    <listitem><para>gcc-3.2.3: "3.2.3"</para></listitem>
    <listitem><para>gcc-3.3.0: "3.3"</para></listitem>
    <listitem><para>gcc-3.3.1: "3.3.1"</para></listitem>
    <listitem><para>gcc-3.3.2: "3.3.2"</para></listitem>
    <listitem><para>gcc-3.3.3: "3.3.3"</para></listitem>
    <listitem><para>gcc-3.4.x: "version-unused"</para></listitem>
    <listitem><para>gcc-4.0.x: "version-unused"</para></listitem>
    <listitem><para>gcc-4.1.x: "version-unused"</para></listitem>
    <listitem><para>gcc-4.2.x: "version-unused"</para></listitem>
    </itemizedlist>
    <para></para>
    </listitem>

    <listitem>
    <para>
    Matching each specific C++ compiler release to a specific set of
    C++ include files. This is only implemented in gcc-3.1.1 releases
    and higher.
    </para>
    <para>
    All C++ includes are installed in include/c++, then nest in a
    directory hierarchy corresponding to the C++ compiler's released
    version. This version corresponds to the variable "gcc_version" in
    "libstdc++/acinclude.m4," and more details can be found in that
    file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).
    </para>
    <para>
    C++ includes are versioned as follows:
    </para>
    <itemizedlist>
    <listitem><para>gcc-3.0.0: include/g++-v3</para></listitem>
    <listitem><para>gcc-3.0.1: include/g++-v3</para></listitem>
    <listitem><para>gcc-3.0.2: include/g++-v3</para></listitem>
    <listitem><para>gcc-3.0.3: include/g++-v3</para></listitem>
    <listitem><para>gcc-3.0.4: include/g++-v3</para></listitem>
    <listitem><para>gcc-3.1.0: include/g++-v3</para></listitem>
    <listitem><para>gcc-3.1.1: include/c++/3.1.1</para></listitem>
    <listitem><para>gcc-3.2.0: include/c++/3.2</para></listitem>
    <listitem><para>gcc-3.2.1: include/c++/3.2.1</para></listitem>
    <listitem><para>gcc-3.2.2: include/c++/3.2.2</para></listitem>
    <listitem><para>gcc-3.2.3: include/c++/3.2.3</para></listitem>
    <listitem><para>gcc-3.3.0: include/c++/3.3</para></listitem>
    <listitem><para>gcc-3.3.1: include/c++/3.3.1</para></listitem>
    <listitem><para>gcc-3.3.2: include/c++/3.3.2</para></listitem>
    <listitem><para>gcc-3.3.3: include/c++/3.3.3</para></listitem>
    <listitem><para>gcc-3.4.0: include/c++/3.4.0</para></listitem>
    <listitem><para>gcc-3.4.1: include/c++/3.4.1</para></listitem>
    <listitem><para>gcc-3.4.2: include/c++/3.4.2</para></listitem>
    <listitem><para>gcc-3.4.3: include/c++/3.4.3</para></listitem>
    <listitem><para>gcc-3.4.4: include/c++/3.4.4</para></listitem>
    <listitem><para>gcc-3.4.5: include/c++/3.4.5</para></listitem>
    <listitem><para>gcc-3.4.6: include/c++/3.4.6</para></listitem>
    <listitem><para>gcc-4.0.0: include/c++/4.0.0</para></listitem>
    <listitem><para>gcc-4.0.1: include/c++/4.0.1</para></listitem>
    <listitem><para>gcc-4.0.2: include/c++/4.0.2</para></listitem>
    <listitem><para>gcc-4.0.3: include/c++/4.0.3</para></listitem>
    <listitem><para>gcc-4.1.0: include/c++/4.1.0</para></listitem>
    <listitem><para>gcc-4.1.1: include/c++/4.1.1</para></listitem>
    <listitem><para>gcc-4.1.2: include/c++/4.1.2</para></listitem>
    <listitem><para>gcc-4.2.0: include/c++/4.2.0</para></listitem>
    </itemizedlist>
    <para></para>
    </listitem>
  </orderedlist>

<para>
  Taken together, these techniques can accurately specify interface
  and implementation changes in the GNU C++ tools themselves. Used
  properly, they allow both the GNU C++ tools implementation, and
  programs using them, an evolving yet controlled development that
  maintains backward compatibility.
</para>


  </sect3>

  <sect3 id="abi.versioning.prereq" xreflabel="abi.versioning.prereq">
    <title>Prerequisites</title>
    <para>
      Minimum environment that supports a versioned ABI: A supported
      dynamic linker, a GNU linker of sufficient vintage to understand
      demangled C++ name globbing (ld), a shared executable compiled
      with g++, and shared libraries (libgcc_s, libstdc++) compiled by
      a compiler (g++) with a compatible ABI. Phew.
    </para>

    <para>
      On top of all that, an additional constraint: libstdc++ did not
      attempt to version symbols (or age gracefully, really) until
      version 3.1.0.
    </para>

    <para>
      Most modern Linux and BSD versions, particularly ones using
      gcc-3.1.x tools and more recent vintages, will meet the
      requirements above.
    </para>
  </sect3>

  <sect3 id="abi.versioning.config" xreflabel="abi.versioning.config">
    <title>Configuring</title>

    <para>
      It turns out that most of the configure options that change
      default behavior will impact the mangled names of exported
      symbols, and thus impact versioning and compatibility.
    </para>

    <para>
      For more information on configure options, including ABI
      impacts, see:
      http://gcc.gnu.org/onlinedocs/libstdc++/configopts.html
    </para>

    <para>
      There is one flag that explicitly deals with symbol versioning:
      --enable-symvers.
    </para>

    <para>
      In particular, libstdc++/acinclude.m4 has a macro called
      GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument
      passed in via --enable-symvers=foo). At that point, the macro
      attempts to make sure that all the requirement for symbol
      versioning are in place. For more information, please consult
      acinclude.m4.
    </para>
  </sect3>

  <sect3 id="abi.versioning.active" xreflabel="abi.versioning.active">
    <title>Checking Active</title>

    <para>
      When the GNU C++ library is being built with symbol versioning
      on, you should see the following at configure time for
      libstdc++:
    </para>

<screen>
<computeroutput>
  checking versioning on shared library symbols... gnu
</computeroutput>
</screen>

<para>
  If you don't see this line in the configure output, or if this line
  appears but the last word is 'no', then you are out of luck.
</para>

<para>
  If the compiler is pre-installed, a quick way to test is to compile
  the following (or any) simple C++ file and link it to the shared
  libstdc++ library:
</para>

<programlisting>
#include &lt;iostream&gt;

int main()
{ std::cout &lt;&lt; "hello" &lt;&lt; std::endl; return 0; }

%g++ hello.cc -o hello.out

%ldd hello.out
        libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
        libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
        libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)
        libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
        /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)

%nm hello.out
</programlisting>

<para>
If you see symbols in the resulting output with "GLIBCXX_3" as part
of the name, then the executable is versioned. Here's an example:
</para>

<para>
   <code>U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code>
</para>

  </sect3>
</sect2>

<sect2 id="abi.changes_allowed" xreflabel="abi.changes_allowed">
<title>Allowed Changes</title>

<para>
The following will cause the library minor version number to
increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".
</para>
<orderedlist>
 <listitem><para>Adding an exported global or static data member</para></listitem>
 <listitem><para>Adding an exported function, static or non-virtual member function</para></listitem>
 <listitem><para>Adding an exported symbol or symbols by additional instantiations</para></listitem>
</orderedlist>
<para>
Other allowed changes are possible.
</para>

</sect2>

<sect2 id="abi.changes_no" xreflabel="abi.changes_no">
<title>Prohibited Changes</title>

<para>
The following non-exhaustive list will cause the library major version
number to increase, say from "libstdc++.so.3.0.4" to
"libstdc++.so.4.0.0".
</para>

<orderedlist>
 <listitem><para>Changes in the gcc/g++ compiler ABI</para></listitem>
<listitem><para>Changing size of an exported symbol</para></listitem>
<listitem><para>Changing alignment of an exported symbol</para></listitem>
<listitem><para>Changing the layout of an exported symbol</para></listitem>
<listitem><para>Changing mangling on an exported symbol</para></listitem>
<listitem><para>Deleting an exported symbol</para></listitem>
<listitem><para>Changing the inheritance properties of a type by adding or removing
    base classes</para></listitem>
<listitem><para>
  Changing the size, alignment, or layout of types
  specified in the C++ standard. These may not necessarily be
  instantiated or otherwise exported in the library binary, and
  include all the required locale facets, as well as things like
  std::basic_streambuf, et al.
</para></listitem>

<listitem><para> Adding an explicit copy constructor or destructor to a
class that would otherwise have implicit versions. This will change
the way the compiler deals with this class in by-value return
statements or parameters: instead of being passing instances of this
class in registers, the compiler will be forced to use memory. See <ulink url="http://www.codesourcery.com/cxx-abi/abi.html#calls"> this part</ulink>
 of the C++ ABI documentation for further details. 
 </para></listitem>

</orderedlist>

</sect2>



<sect2 id="abi.impl" xreflabel="abi.impl">
<title>Implementation</title>

<orderedlist>
 <listitem>
   <para>
     Separation of interface and implementation
   </para>
   <para>
     This is accomplished by two techniques that separate the API from
     the ABI: forcing undefined references to link against a library
     binary for definitions.
   </para>

<variablelist>
  <varlistentry>
    <term>Include files have declarations, source files have defines</term>
    
    <listitem>
      <para>
	For non-templatized types, such as much of <code>class
	locale</code>, the appropriate standard C++ include, say
	<code>locale</code>, can contain full declarations, while
	various source files (say <code> locale.cc, locale_init.cc,
	localename.cc</code>) contain definitions.
      </para>
    </listitem>
  </varlistentry>
  
  <varlistentry>
  <term>Extern template on required types</term>

   <listitem>
     <para>
       For parts of the standard that have an explicit list of
       required instantiations, the GNU extension syntax <code> extern
       template </code> can be used to control where template
       definitions reside. By marking required instantiations as
       <code> extern template </code> in include files, and providing
       explicit instantiations in the appropriate instantiation files,
       non-inlined template functions can be versioned. This technique
       is mostly used on parts of the standard that require <code>
       char</code> and <code> wchar_t</code> instantiations, and
       includes <code> basic_string</code>, the locale facets, and the
       types in <code> iostreams</code>.
     </para>
   </listitem>
  </varlistentry>

 </variablelist>

 <para> 
   In addition, these techniques have the additional benefit that they
   reduce binary size, which can increase runtime performance.
 </para>
 </listitem>

 <listitem>
   <para>
     Namespaces linking symbol definitions to export mapfiles
   </para>
   <para>
     All symbols in the shared library binary are processed by a
     linker script at build time that either allows or disallows
     external linkage. Because of this, some symbols, regardless of
     normal C/C++ linkage, are not visible. Symbols that are internal
     have several appealing characteristics: by not exporting the
     symbols, there are no relocations when the shared library is
     started and thus this makes for faster runtime loading
     performance by the underlying dynamic loading mechanism. In
     addition, they have the possibility of changing without impacting
     ABI compatibility.
   </para>

<para>The following namespaces are transformed by the mapfile:</para>

<variablelist>

  <varlistentry>
<term><code>namespace std</code></term>
<listitem><para> Defaults to exporting all symbols in label
<code>GLIBCXX</code> that do not begin with an underscore, i.e.,
<code>__test_func</code> would not be exported by default. Select
exceptional symbols are allowed to be visible.</para></listitem>
  </varlistentry>

  <varlistentry>
<term><code>namespace __gnu_cxx</code></term>
<listitem><para> Defaults to not exporting any symbols in label
<code>GLIBCXX</code>, select items are allowed to be visible.</para></listitem>
  </varlistentry>

  <varlistentry>
<term><code>namespace __gnu_internal</code></term>
<listitem><para> Defaults to not exported, no items are allowed to be visible.</para></listitem>
  </varlistentry>

  <varlistentry>
<term><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></term>
<listitem><para> Defaults to not exporting any symbols in label
<code>CXXABI</code>, select items are allowed to be visible.</para></listitem>
  </varlistentry>

</variablelist>
<para>
</para>
</listitem>

 <listitem><para>Freezing the API</para>
 <para>Disallowed changes, as above, are not made on a stable release
branch. Enforcement tends to be less strict with GNU extensions that
standard includes.</para>
</listitem>
</orderedlist>

</sect2>

<sect2 id="abi.testing" xreflabel="abi.testing">
<title>Testing</title>

  <sect3 id="abi.testing.single" xreflabel="abi.testing.single">
    <title>Single ABI Testing</title>

    <para>
      Testing for GNU C++ ABI changes is composed of two distinct
      areas: testing the C++ compiler (g++) for compiler changes, and
      testing the C++ library (libstdc++) for library changes.
    </para>

    <para>
      Testing the C++ compiler ABI can be done various ways.
    </para>

    <para>
      One.  Intel ABI checker. More information can be obtained <ulink
      url="http://developer.intel.com/software/products/opensource/">here.</ulink>
    </para>

<para>
Two.
The second is yet unreleased, but has been announced on the gcc
mailing list. It is yet unspecified if these tools will be freely
available, and able to be included in a GNU project. Please contact
Mark Mitchell (mark@codesourcery.com) for more details, and current
status.
</para>

<para>
Three.
Involves using the vlad.consistency test framework. This has also been
discussed on the gcc mailing lists.
</para>

<para>
Testing the C++ library ABI can also be done various ways.
</para>

<para>
One. 
(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, 
one with a new compiler and an old library, and the other with an old
compiler and a new library, and look for testsuite regressions)
</para>

<para>
Details on how to set this kind of test up can be found here:
http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html
</para>

<para>
Two.  
Use the 'make check-abi' rule in the libstdc++ Makefile. 
</para>

<para>
This is a proactive check the library ABI. Currently, exported symbol
names that are either weak or defined are checked against a last known
good baseline. Currently, this baseline is keyed off of 3.4.0
binaries, as this was the last time the .so number was incremented. In
addition, all exported names are demangled, and the exported objects
are checked to make sure they are the same size as the same object in
the baseline.

Notice that each baseline is relative to a <emphasis>default</emphasis>
configured library and compiler: in particular, if options such as
--enable-clocale, or --with-cpu, in case of multilibs, are used at
configure time, the check may fail, either because of substantive
differences or because of limitations of the current checking
machinery.
</para>

<para>
This dataset is insufficient, yet a start. Also needed is a
comprehensive check for all user-visible types part of the standard
library for sizeof() and alignof() changes. 
</para>

<para>
Verifying compatible layouts of objects is not even attempted.  It
should be possible to use sizeof, alignof, and offsetof to compute
offsets for each structure and type in the standard library, saving to
another datafile. Then, compute this in a similar way for new
binaries, and look for differences.
</para>

<para>
Another approach might be to use the -fdump-class-hierarchy flag to
get information. However, currently this approach gives insufficient
data for use in library testing, as class data members, their offsets,
and other detailed data is not displayed with this flag.
(See g++/7470 on how this was used to find bugs.)
</para>

<para>
Perhaps there are other C++ ABI checkers. If so, please notify
us. We'd like to know about them!
</para>

  </sect3>
  <sect3 id="abi.testing.multi" xreflabel="abi.testing.multi">
    <title>Multiple ABI Testing</title>
<para>
A "C" application, dynamically linked to two shared libraries, liba,
libb. The dependent library liba is C++ shared library compiled with
gcc-3.3.x, and uses io, exceptions, locale, etc. The dependent library
libb is a C++ shared library compiled with gcc-3.4.x, and also uses io,
exceptions, locale, etc.
</para>

<para> As above, libone is constructed as follows: </para>
<programlisting>
%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc

%$bld/H-x86-gcc-3.4.0/bin/g++ -shared -Wl,-soname -Wl,libone.so.1 -Wl,-O1 -Wl,-z,defs a.o -o libone.so.1.0.0

%ln -s libone.so.1.0.0 libone.so

%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc

%ar cru libone.a a.o 
</programlisting>

<para> And, libtwo is constructed as follows: </para>

<programlisting>
%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc

%$bld/H-x86-gcc-3.3.3/bin/g++ -shared -Wl,-soname -Wl,libtwo.so.1 -Wl,-O1 -Wl,-z,defs b.o -o libtwo.so.1.0.0

%ln -s libtwo.so.1.0.0 libtwo.so

%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc

%ar cru libtwo.a b.o 
</programlisting>

<para> ...with the resulting libraries looking like </para>

<screen>
<computeroutput>
%ldd libone.so.1.0.0
        libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40016000)
        libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400fa000)
        libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
        libc.so.6 =&gt; /lib/tls/libc.so.6 (0x40125000)
        /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)

%ldd libtwo.so.1.0.0
        libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x40027000)
        libm.so.6 =&gt; /lib/tls/libm.so.6 (0x400e1000)
        libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
        libc.so.6 =&gt; /lib/tls/libc.so.6 (0x4010c000)
        /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
</computeroutput>
</screen>

<para> 
  Then, the "C" compiler is used to compile a source file that uses
  functions from each library.
</para>
<programlisting>
gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6
</programlisting>

<para>
  Which gives the expected:
</para>

<screen>
<computeroutput>
%ldd a.out
        libstdc++.so.5 =&gt; /usr/lib/libstdc++.so.5 (0x00764000)
        libstdc++.so.6 =&gt; /usr/lib/libstdc++.so.6 (0x40015000)
        libc.so.6 =&gt; /lib/tls/libc.so.6 (0x0036d000)
        libm.so.6 =&gt; /lib/tls/libm.so.6 (0x004a8000)
        libgcc_s.so.1 =&gt; /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000)
        /lib/ld-linux.so.2 =&gt; /lib/ld-linux.so.2 (0x00355000)
</computeroutput>
</screen>

<para>
  This resulting binary, when executed, will be able to safely use
  code from both liba, and the dependent libstdc++.so.6, and libb,
  with the dependent libstdc++.so.5.
</para>
  </sect3>
</sect2>

<sect2 id="abi.issues" xreflabel="abi.issues">
<title>Outstanding Issues</title>

<para> 
  Some features in the C++ language make versioning especially
  difficult. In particular, compiler generated constructs such as
  implicit instantiations for templates, typeinfo information, and
  virtual tables all may cause ABI leakage across shared library
  boundaries. Because of this, mixing C++ ABIs is not recommended at
  this time.
</para>

<para>
  For more background on this issue, see these bugzilla entries:
</para>

<para>
<ulink url="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</ulink>
</para>

<para>
<ulink url="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</ulink>
</para>

</sect2>

<bibliography id="abi.biblio" xreflabel="abi.biblio">
<title>Bibliography</title>

  <biblioentry>
    <title>
      ABIcheck, a vague idea of checking ABI compatibility
    </title>

    <biblioid>
      <ulink url="http://abicheck.sourceforge.net/">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      C++ ABI Reference
    </title>

    <biblioid>
      <ulink url="http://www.codesourcery.com/cxx-abi">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      Intel® Compilers for Linux* -Compatibility with the GNU Compilers
    </title>

    <biblioid>
      <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      Intel® Compilers for Linux* -Compatibility with the GNU Compilers
    </title>

    <biblioid>
      <ulink url="http://developer.intel.com/software/products/compilers/techtopics/LinuxCompilersCompatibility.htm">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      Sun Solaris 2.9 : Linker and Libraries Guide (document 816-1386)
    </title>

    <biblioid>
      <ulink url="http://docs.sun.com/?p=/doc/816-1386&amp;a=load">
      </ulink>
    </biblioid>
  </biblioentry> 


  <biblioentry>
    <title>
      Sun Solaris 2.9 : C++ Migration Guide (document 816-2459)
    </title>

    <biblioid>
      <ulink url="http://docs.sun.com/db/prod/solaris.9">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      ELF Symbol Versioning
    </title>

    <author>
      <firstname>Ulrich</firstname>
      <surname>Drepper</surname>
    </author>
 
    <biblioid>
      <ulink url="http://people.redhat.com/drepper/symbol-versioning">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      C++ ABI for the ARM Architecture
    </title>

    <biblioid>
      <ulink url="http://www.arm.com/miscPDFs/8033.pdf">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      Dynamic Shared Objects: Survey and Issues
    </title>
    <subtitle>
      ISO C++ J16/06-0046
    </subtitle>

    <author>
      <firstname>Benjamin</firstname>
      <surname>Kosnik</surname>
    </author>
 
    <biblioid>
      <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html">
      </ulink>
    </biblioid>
  </biblioentry> 

  <biblioentry>
    <title>
      Versioning With Namespaces
    </title>
    <subtitle>
      ISO C++ J16/06-0083
    </subtitle>

    <author>
      <firstname>Benjamin</firstname>
      <surname>Kosnik</surname>
    </author>
 
    <biblioid>
      <ulink url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html">
      </ulink>
    </biblioid>
  </biblioentry> 

</bibliography>

</sect1>