From d7f30833549aa0378f41f8cdb132cff5826847fe Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 13 May 2004 16:50:02 +0100 Subject: [PATCH] abi.html: Document effect of -fabi-version on value of __GXX_ABI_VERSION... 2004-05-13 Jonathan Wakely * docs/html/abi.html: Document effect of -fabi-version on value of __GXX_ABI_VERSION, and that it's defined in c-cppbuiltin.c. Fix markup. From-SVN: r81794 --- libstdc++-v3/ChangeLog | 6 ++ libstdc++-v3/docs/html/abi.html | 175 ++++++++++++++++++-------------- 2 files changed, 105 insertions(+), 76 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 4412daa8d90..8e8ad9adec6 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,9 @@ +2004-05-13 Jonathan Wakely + + * docs/html/abi.html: Document effect of -fabi-version on value + of __GXX_ABI_VERSION, and that it's defined in c-cppbuiltin.c. + Fix markup. + 2004-05-13 Benjamin Kosnik PR libstdc++/15074 diff --git a/libstdc++-v3/docs/html/abi.html b/libstdc++-v3/docs/html/abi.html index fcb84e91793..421c1706cea 100644 --- a/libstdc++-v3/docs/html/abi.html +++ b/libstdc++-v3/docs/html/abi.html @@ -32,7 +32,7 @@

- The C++ interface + The C++ interface

C++ applications often dependent on specific language support @@ -101,7 +101,7 @@ given compiler ABI. In a nutshell:

- Versioning + Versioning

The C++ interface has evolved throughout the history of the GNU @@ -170,8 +170,8 @@ on ELF systems).

  • gcc-3.3.3: libgcc_s.so.1
  • gcc-3.4.0: libgcc_s.so.1
    • -

    +
  • Release versioning on the libstdc++.so binary, implemented in the same was as the libgcc_s.so binary, above. @@ -195,8 +195,8 @@ on ELF systems).

  • gcc-3.3.3: libstdc++.so.5.0.5
  • gcc-3.4.0: libstdc++.so.6.0.0
    • -

    +
  • Symbol versioning on the libgcc_s.so binary.

    mapfile: gcc/libgcc-std.ver

    @@ -220,8 +220,8 @@ on ELF systems).

  • gcc-3.3.3: GCC_3.0
  • gcc-3.4.0: GCC_3.0
    • -

    +
  • Symbol versioning on the libstdc++.so binary. @@ -254,8 +254,8 @@ on ELF systems).

  • gcc-3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1
  • gcc-3.4.0: GLIBCXX_3.4, CXXABI_1.3
    • -

    +

  • Incremental bumping of a compiler pre-defined macro, @@ -266,22 +266,26 @@ on ELF systems).

    - This macro is defined in the file "lang-specs.h" in the gcc/cp directory. - Later versions define it in "c-common.c" in the gcc directory. + 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: + It is versioned as follows, where 'n' is given by '-fabi-version=n':

    • gcc-3.0.x: 100
    • gcc-3.1.x: 100 (Error, should be 101)
    • gcc-3.2.x: 102
    • gcc-3.3.x: 102
      • -
    • gcc-3.4.x: 1002
      • +
    • gcc-3.4.x: 102 (when n=1)
      • +
    • gcc-3.4.x: 1000+n (when n>1)
      • +
    • gcc-3.4.x: 999999 (when n=0)
    -

    • +

  • Changes to the default compiler option for @@ -297,8 +301,8 @@ on ELF systems).

  • gcc-3.3.x: -fabi-version=1
  • gcc-3.4.x: -fabi-version=2
    • -

    +

  • Incremental bumping of a library pre-defined macro. For releases @@ -335,8 +339,8 @@ on ELF systems).

  • gcc-3.3.3: 20040214
  • gcc-3.4.0: 20040419
    • -

    +
  • @@ -344,7 +348,8 @@ on ELF systems).

    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. + gcc-3.1.0 releases and higher, and is deprecated in 3.4 (where it + is called _GLIBCXX_VERSION).

    @@ -375,8 +380,8 @@ on ELF systems).

  • gcc-3.3.3: "3.3.3"
  • gcc-3.4.0: "version-unused"
    • -

    +

  • @@ -389,7 +394,7 @@ on ELF systems).

    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 GLIBCPP_CONFIGURE. + file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before gcc-3.4.0).

    C++ includes are versioned as follows: @@ -412,8 +417,8 @@ on ELF systems).

  • gcc-3.3.3: include/c++/3.3.3
  • gcc-3.4.0: include/c++/3.4.0
    • -

    +

    Taken together, these techniques can accurately specify interface @@ -457,7 +462,7 @@ on ELF systems).

    impact versioning and compatibility.

    -

    +

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

    @@ -507,11 +512,11 @@ int main() %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) + 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 @@ -524,7 +529,7 @@ of the name, then the executable is versioned. Here's an example: U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4

    - Library allowed ABI changes + Library allowed ABI changes

    The following will cause the library minor version number to @@ -543,7 +548,7 @@ Other allowed changes are possible.

    - Library disallowed ABI changes + Library disallowed ABI changes

    @@ -574,24 +579,24 @@ number to increase, say from "libstdc++.so.3.0.4" to

      -
    • Separation of interface and implementation
      • +
    • 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
        • +
        +
        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.

        +
        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
        • +
        Extern template on required types
        -

        For parts of the standard that have an explicit list of required +

        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 @@ -601,14 +606,15 @@ localename.cc) contain definitions.

        on parts of the standard that require char and wchar_t instantiations, and includes basic_string, the locale facets, and the types in - iostreams.

        + 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
      • +
    • 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 @@ -623,34 +629,37 @@ impacting ABI compatibility.

      The following namespaces are transformed by the mapfile:

      -
        -
      • namespace std
        • -

        Defaults to exporting all symbols in label +

        +
        namespace std
        +
        Defaults to exporting all symbols in label GLIBCXX that do not begin with an underscore, ie __test_func would not be exported by default. Select -exceptional symbols are allowed to be visible.

        +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_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 __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.

        -
      +
      namespace __cxxabiv1, aliased to namespace abi
      +
      Defaults to not exporting any symbols in label +CXXABI, select items are allowed to be visible.
      +

      +
      • -
    • Freezing the API
      • +
    • Freezing the API

      Disallowed changes, as above, are not made on a stable release branch. Enforcement tends to be less strict with GNU extensions that -standard includes.

    +standard includes.

    + +

    - Testing ABI changes + Testing ABI changes

    @@ -743,7 +752,7 @@ us. We'd like to know about them!

    - Testing Multi-ABI binaries + Testing Multi-ABI binaries

    @@ -784,18 +793,18 @@ exceptions, locale, etc.

    ...with the resulting libraries looking like 

     %ldd libone.so.1.0.0
-        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
+        libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000)
+        libm.so.6 => /lib/tls/libm.so.6 (0x400fa000)
+        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000)
+        libc.so.6 => /lib/tls/libc.so.6 (0x40125000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
 
 %ldd libtwo.so.1.0.0
-        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
-        libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
-        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
-        libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
-        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
+        libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000)
+        libm.so.6 => /lib/tls/libm.so.6 (0x400e1000)
+        libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000)
+        libc.so.6 => /lib/tls/libc.so.6 (0x4010c000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000)
    @@ -810,12 +819,12 @@ Which gives the expected: 

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

    @@ -830,28 +839,42 @@ dependent libstdc++.so.5.

    ABIcheck, a vague idea of checking ABI compatibility -http://abicheck.sourceforge.net/ +
    +http://abicheck.sourceforge.net/ +

    C++ ABI reference -http://www.codesourcery.com/cxx-abi/ +
    +http://www.codesourcery.com/cxx-abi/

    Intel ABI documentation +
    "Intel® Compilers for Linux* -Compatibility with the GNU Compilers" +
    (included in icc 6.0)

    Sun Solaris 2.9 docs +
    Linker and Libraries Guide (document 816-1386) +
    C++ Migration Guide (document 816-2459) -http://docs.sun.com/db/prod/solaris.9 -http://docs.sun.com/?p=/doc/816-1386&a=load +
    +http://docs.sun.com/db/prod/solaris.9 +
    +http://docs.sun.com/?p=/doc/816-1386&a=load

    Ulrich Drepper, "ELF Symbol Versioning" -http://people.redhat.com/drepper/symbol-versioning +
    +http://people.redhat.com/drepper/symbol-versioning

    + + + +