Subversion Repositories openrisc

         xml:id="appendix.porting.abi" xreflabel="abi">

      C++

      ABI

      version

      dynamic

      shared

      compatibility

  C++ applications often depend on specific language support

  routines, say for throwing exceptions, or catching exceptions, and

  perhaps also depend on features in the C++ Standard Library.

  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.

  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 ABI

  specification.

 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 -fabi-version. In addition, some

  g++ command line options may change the ABI as a side-effect of

  use. Such flags include -fpack-struct and

  -fno-exceptions, but include others: see the complete

  list in the GCC manual under the heading Options

  for Code Generation Conventions.

  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

here.

 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:

    library API + compiler ABI = library ABI

 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.

  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.

 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.

Extending existing, stable ABIs. Versioning gives subsequent

releases of library binaries the ability to add new symbols and add

functionality, all the while retaining compatibility with the previous

releases in the series. Thus, program binaries linked with the initial

release of a library binary will still run correctly if the library

binary is replaced by carefully-managed subsequent library

binaries. This is called forward compatibility.

The reverse (backwards compatibility) is not true. It is not possible

to take program binaries linked with the latest version of a library

binary in a release series (with additional symbols added), substitute

in the initial release of the library binary, and remain link

compatible.

Allows multiple, incompatible ABIs to coexist at the same time.

 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.

  The following techniques are used:

    Release versioning on the libgcc_s.so binary. 

    This is implemented via file names and the ELF

    DT_SONAME mechanism (at least on ELF

    systems). It is versioned as follows:

    GCC 3.x: libgcc_s.so.1

    GCC 4.x: libgcc_s.so.1

    For m68k-linux the versions differ as follows: 

    GCC 3.4, GCC 4.x: libgcc_s.so.1

    when configuring --with-sjlj-exceptions, or

    libgcc_s.so.2  

    For hppa-linux the versions differ as follows: 

    GCC 3.4, GCC 4.[0-1]: either libgcc_s.so.1

    when configuring --with-sjlj-exceptions, or

    libgcc_s.so.2  

    GCC 4.[2-7]: either libgcc_s.so.3 when configuring

    --with-sjlj-exceptions) or libgcc_s.so.4

    Symbol versioning on the libgcc_s.so binary.

    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.

    This corresponds to the mapfile: gcc/libgcc-std.ver

    GCC 3.0.0: GCC_3.0

    GCC 3.3.0: GCC_3.3

    GCC 3.3.1: GCC_3.3.1

    GCC 3.3.2: GCC_3.3.2

    GCC 3.3.4: GCC_3.3.4

    GCC 3.4.0: GCC_3.4

    GCC 3.4.2: GCC_3.4.2

    GCC 3.4.4: GCC_3.4.4

    GCC 4.0.0: GCC_4.0.0

    GCC 4.1.0: GCC_4.1.0

    GCC 4.2.0: GCC_4.2.0

    GCC 4.3.0: GCC_4.3.0

    GCC 4.4.0: GCC_4.4.0

    GCC 4.5.0: GCC_4.5.0

    GCC 4.6.0: GCC_4.6.0

    GCC 4.7.0: GCC_4.7.0

        Release versioning on the libstdc++.so binary, implemented in

        the same way as the libgcc_s.so binary above. Listed is the

        filename: DT_SONAME can be deduced from

        the filename by removing the last two period-delimited numbers. For

        example, filename libstdc++.so.5.0.4

        corresponds to a DT_SONAME of

        libstdc++.so.5. Binaries with equivalent

        DT_SONAMEs are forward-compatibile: in

        the table below, releases incompatible with the previous

        one are explicitly noted.

        If a particular release is not listed, its libstdc++.so binary

        has the same filename and DT_SONAME as the

        preceding release.

    It is versioned as follows:

    GCC 3.0.0: libstdc++.so.3.0.0

    GCC 3.0.1: libstdc++.so.3.0.1

    GCC 3.0.2: libstdc++.so.3.0.2

    GCC 3.0.3: libstdc++.so.3.0.2 (See Note 1)

    GCC 3.0.4: libstdc++.so.3.0.4

    GCC 3.1.0: libstdc++.so.4.0.0 (Incompatible with previous)

    GCC 3.1.1: libstdc++.so.4.0.1

    GCC 3.2.0: libstdc++.so.5.0.0 (Incompatible with previous)

    GCC 3.2.1: libstdc++.so.5.0.1

    GCC 3.2.2: libstdc++.so.5.0.2

    GCC 3.2.3: libstdc++.so.5.0.3 (See Note 2)

    GCC 3.3.0: libstdc++.so.5.0.4

    GCC 3.3.1: libstdc++.so.5.0.5

    GCC 3.4.0: libstdc++.so.6.0.0 (Incompatible with previous)

    GCC 3.4.1: libstdc++.so.6.0.1

    GCC 3.4.2: libstdc++.so.6.0.2

    GCC 3.4.3: libstdc++.so.6.0.3

    GCC 4.0.0: libstdc++.so.6.0.4

    GCC 4.0.1: libstdc++.so.6.0.5

    GCC 4.0.2: libstdc++.so.6.0.6

    GCC 4.0.3: libstdc++.so.6.0.7

    GCC 4.1.0: libstdc++.so.6.0.7

    GCC 4.1.1: libstdc++.so.6.0.8

    GCC 4.2.0: libstdc++.so.6.0.9

    GCC 4.2.1: libstdc++.so.6.0.9 (See Note 3)

    GCC 4.2.2: libstdc++.so.6.0.9

    GCC 4.3.0: libstdc++.so.6.0.10

    GCC 4.4.0: libstdc++.so.6.0.11

    GCC 4.4.1: libstdc++.so.6.0.12

    GCC 4.4.2: libstdc++.so.6.0.13

    GCC 4.5.0: libstdc++.so.6.0.14

    GCC 4.6.0: libstdc++.so.6.0.15

    GCC 4.6.1: libstdc++.so.6.0.16

      Note 1: Error should be libstdc++.so.3.0.3.

      Note 2: Not strictly required.

      Note 3: This release (but not previous or subsequent) has one

      known incompatibility, see 33678

      in the GCC bug database.

    Symbol versioning on the libstdc++.so binary.

    mapfile: libstdc++-v3/config/abi/pre/gnu.ver

    It is versioned with the following labels and version

   definitions, where the version definition is the maximum for a

   particular release. Note, only symbols 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.

    GCC 3.0.0: (Error, not versioned)

    GCC 3.0.1: (Error, not versioned)

    GCC 3.0.2: (Error, not versioned)

    GCC 3.0.3: (Error, not versioned)

    GCC 3.0.4: (Error, not versioned)

    GCC 3.1.0: GLIBCPP_3.1, CXXABI_1

    GCC 3.1.1: GLIBCPP_3.1, CXXABI_1

    GCC 3.2.0: GLIBCPP_3.2, CXXABI_1.2

    GCC 3.2.1: GLIBCPP_3.2.1, CXXABI_1.2

    GCC 3.2.2: GLIBCPP_3.2.2, CXXABI_1.2

    GCC 3.2.3: GLIBCPP_3.2.2, CXXABI_1.2

    GCC 3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1

    GCC 3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1

    GCC 3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1

    GCC 3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1

    GCC 3.4.0: GLIBCXX_3.4, CXXABI_1.3

    GCC 3.4.1: GLIBCXX_3.4.1, CXXABI_1.3

    GCC 3.4.2: GLIBCXX_3.4.2

    GCC 3.4.3: GLIBCXX_3.4.3

    GCC 4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1

    GCC 4.0.1: GLIBCXX_3.4.5

    GCC 4.0.2: GLIBCXX_3.4.6

    GCC 4.0.3: GLIBCXX_3.4.7

    GCC 4.1.1: GLIBCXX_3.4.8

    GCC 4.2.0: GLIBCXX_3.4.9

    GCC 4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2

    GCC 4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3

    GCC 4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3

    GCC 4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3

    GCC 4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4

    GCC 4.6.0: GLIBCXX_3.4.15, CXXABI_1.3.5

    GCC 4.6.1: GLIBCXX_3.4.16, CXXABI_1.3.5

    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 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.)

    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.

    It is versioned as follows, where 'n' is given by '-fabi-version=n':

    GCC 3.0: 100

    GCC 3.1: 100 (Error, should be 101)

    GCC 3.2: 102

    GCC 3.3: 102

    GCC 3.4, GCC 4.x: 102 (when n=1)

    GCC 3.4, GCC 4.x: 1000 + n (when n>1) 

    GCC 3.4, GCC 4.x: 999999 (when n=0)

    Changes to the default compiler option for

    -fabi-version.

    It is versioned as follows:

    GCC 3.0: (Error, not versioned) 

    GCC 3.1: (Error, not versioned) 

    GCC 3.2: -fabi-version=1

    GCC 3.3: -fabi-version=1

    GCC 3.4, GCC 4.x: -fabi-version=2 (Incompatible with previous)

    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.

    This macro is defined in the file "c++config" in the

    "libstdc++-v3/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.)

    It is versioned as follows:

    GCC 3.0.0: 20010615

    GCC 3.0.1: 20010819

    GCC 3.0.2: 20011023

    GCC 3.0.3: 20011220

    GCC 3.0.4: 20020220

    GCC 3.1.0: 20020514

    GCC 3.1.1: 20020725

    GCC 3.2.0: 20020814

    GCC 3.2.1: 20021119

    GCC 3.2.2: 20030205

    GCC 3.2.3: 20030422

    GCC 3.3.0: 20030513

    GCC 3.3.1: 20030804

    GCC 3.3.2: 20031016

    GCC 3.3.3: 20040214

    GCC 3.4.0: 20040419

    GCC 3.4.1: 20040701

    GCC 3.4.2: 20040906

    GCC 3.4.3: 20041105

    GCC 3.4.4: 20050519

    GCC 3.4.5: 20051201

    GCC 3.4.6: 20060306

    GCC 4.0.0: 20050421

    GCC 4.0.1: 20050707

    GCC 4.0.2: 20050921

    GCC 4.0.3: 20060309

    GCC 4.1.0: 20060228

    GCC 4.1.1: 20060524

    GCC 4.1.2: 20070214

    GCC 4.2.0: 20070514

    GCC 4.2.1: 20070719

    GCC 4.2.2: 20071007

    GCC 4.2.3: 20080201

    GCC 4.2.4: 20080519

    GCC 4.3.0: 20080306

    GCC 4.3.1: 20080606

    GCC 4.3.2: 20080827

    GCC 4.3.3: 20090124

    GCC 4.3.4: 20090804

    GCC 4.3.5: 20100522

    GCC 4.3.6: 20110627

    GCC 4.4.0: 20090421

    GCC 4.4.1: 20090722

    GCC 4.4.2: 20091015

    GCC 4.4.3: 20100121

    GCC 4.4.4: 20100429

    GCC 4.4.5: 20101001

    GCC 4.4.6: 20110416

    GCC 4.5.0: 20100414

    GCC 4.5.1: 20100731

    GCC 4.5.2: 20101216

    GCC 4.5.3: 20110428

    GCC 4.6.0: 20110325

    GCC 4.6.1: 20110627

    GCC 4.6.2: 20111026

    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).

    This macro is defined in the file "c++config" in the

    "libstdc++-v3/include/bits" directory and is generated

    automatically by autoconf as part of the configure-time generation

    of config.h.

    It is versioned as follows:

    GCC 3.0.0: "3.0.0"

    GCC 3.0.1: "3.0.0" (Error, should be "3.0.1")

    GCC 3.0.2: "3.0.0" (Error, should be "3.0.2")

    GCC 3.0.3: "3.0.0" (Error, should be "3.0.3")

    GCC 3.0.4: "3.0.0" (Error, should be "3.0.4")

    GCC 3.1.0: "3.1.0"

    GCC 3.1.1: "3.1.1"

    GCC 3.2.0: "3.2"

    GCC 3.2.1: "3.2.1"

    GCC 3.2.2: "3.2.2"

    GCC 3.2.3: "3.2.3"

    GCC 3.3.0: "3.3"

    GCC 3.3.1: "3.3.1"

    GCC 3.3.2: "3.3.2"

    GCC 3.3.3: "3.3.3"

    GCC 3.4: "version-unused"

    GCC 4.x: "version-unused"

    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.

    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++-v3/acinclude.m4," and more details can be found in that

    file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before GCC 3.4.0).

    C++ includes are versioned as follows:

    GCC 3.0.0: include/g++-v3

    GCC 3.0.1: include/g++-v3

    GCC 3.0.2: include/g++-v3

    GCC 3.0.3: include/g++-v3

    GCC 3.0.4: include/g++-v3

    GCC 3.1.0: include/g++-v3

    GCC 3.1.1: include/c++/3.1.1

    GCC 3.2.0: include/c++/3.2

    GCC 3.2.1: include/c++/3.2.1

    GCC 3.2.2: include/c++/3.2.2

    GCC 3.2.3: include/c++/3.2.3

    GCC 3.3.0: include/c++/3.3

    GCC 3.3.1: include/c++/3.3.1

    GCC 3.3.2: include/c++/3.3.2

    GCC 3.3.3: include/c++/3.3.3

    GCC 3.4.x: include/c++/3.4.x

    GCC 4.x.y: include/c++/4.x.y

  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.

      Minimum environment that supports a versioned ABI: A supported

      dynamic linker, a GNU linker of sufficient vintage to understand

      demangled C++ name globbing (ld) or the Sun linker, a shared

      executable compiled

      with g++, and shared libraries (libgcc_s, libstdc++) compiled by

      a compiler (g++) with a compatible ABI. Phew.

      On top of all that, an additional constraint: libstdc++ did not

      attempt to version symbols (or age gracefully, really) until

      version 3.1.0.

      Most modern GNU/Linux and BSD versions, particularly ones using

      GCC 3.1 and later, will meet the

      requirements above, as does Solaris 2.5 and up.

      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.

      For more information on configure options, including ABI

      impacts, see:

      here

      There is one flag that explicitly deals with symbol versioning:

      --enable-symvers.

      In particular, libstdc++-v3/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.

      When the GNU C++ library is being built with symbol versioning

      on, you should see the following at configure time for

      libstdc++:

  checking versioning on shared library symbols... gnu

  or another of the supported styles.

  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.

  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:

#include <iostream>

int main()

{ std::cout << "hello" << std::endl; return 0; }

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

%ldd hello.out

        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000)

        libm.so.6 => /lib/tls/libm.so.6 (0x004a8000)

        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000)

        libc.so.6 => /lib/tls/libc.so.6 (0x0036d000)

        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)

%nm hello.out

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:

   U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4

On Solaris 2, you can use pvs -r instead:

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

%pvs -r hello.out

        libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12);

        libgcc_s.so.1 (GCC_3.0);

        libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3);

ldd -v works too, but is very verbose.

The following will cause the library minor version number to

increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5".

 Adding an exported global or static data member

 Adding an exported function, static or non-virtual member function

 Adding an exported symbol or symbols by additional instantiations

Other allowed changes are possible.

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".

 Changes in the gcc/g++ compiler ABI

Changing size of an exported symbol

Changing alignment of an exported symbol

Changing the layout of an exported symbol

Changing mangling on an exported symbol

Deleting an exported symbol

Changing the inheritance properties of a type by adding or removing

    base classes

  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.

 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 passing instances of this

class in registers, the compiler will be forced to use memory. See the

section on Function

Calling Conventions and APIs

 of the C++ ABI documentation for further details.

     Separation of interface and implementation

     This is accomplished by two techniques that separate the API from

     the ABI: forcing undefined references to link against a library

     binary for definitions.

    Include files have declarations, source files have defines

        For non-templatized types, such as much of class

        locale, the appropriate standard C++ include, say

        locale, can contain full declarations, while

        various source files (say  locale.cc, locale_init.cc,

        localename.cc) contain definitions.

  Extern template on required types

       For parts of the standard that have an explicit list of

       required instantiations, the GNU extension syntax  extern

       template  can be used to control where template

       definitions reside. By marking required instantiations as

        extern template  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 

       char and  wchar_t instantiations, and

       includes  basic_string, the locale facets, and the

       types in  iostreams.

   In addition, these techniques have the additional benefit that they

   reduce binary size, which can increase runtime performance.

     Namespaces linking symbol definitions to export mapfiles

     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.

The following namespaces are transformed by the mapfile:

namespace std

 Defaults to exporting all symbols in label

GLIBCXX that do not begin with an underscore, i.e.,

__test_func would not be exported by default. Select

exceptional symbols are allowed to be visible.

namespace __gnu_cxx

 Defaults to not exporting any symbols in label

GLIBCXX, select items are allowed to be visible.

namespace __gnu_internal

 Defaults to not exported, no items are allowed to be visible.

namespace __cxxabiv1, aliased to  namespace abi

 Defaults to not exporting any symbols in label

CXXABI, select items are allowed to be visible.