diff options
Diffstat (limited to 'gcc-4.8.1/libstdc++-v3/doc/xml/manual/abi.xml')
-rw-r--r-- | gcc-4.8.1/libstdc++-v3/doc/xml/manual/abi.xml | 1191 |
1 files changed, 0 insertions, 1191 deletions
diff --git a/gcc-4.8.1/libstdc++-v3/doc/xml/manual/abi.xml b/gcc-4.8.1/libstdc++-v3/doc/xml/manual/abi.xml deleted file mode 100644 index 6cf79a119..000000000 --- a/gcc-4.8.1/libstdc++-v3/doc/xml/manual/abi.xml +++ /dev/null @@ -1,1191 +0,0 @@ -<section xmlns="http://docbook.org/ns/docbook" version="5.0" - xml:id="appendix.porting.abi" xreflabel="abi"> -<?dbhtml filename="abi.html"?> - -<info><title>ABI Policy and Guidelines</title> - <keywordset> - <keyword>C++</keyword> - <keyword>ABI</keyword> - <keyword>version</keyword> - <keyword>dynamic</keyword> - <keyword>shared</keyword> - <keyword>compatibility</keyword> - </keywordset> -</info> - - - -<para> -</para> - -<section xml:id="abi.cxx_interface"><info><title>The C++ Interface</title></info> - - -<para> - 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. -</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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://mentorembedded.github.com/cxx-abi/abi.html">ABI - specification</link>. -</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 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html#Code%20Gen%20Options">Options - for Code Generation Conventions</link>. -</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 -<link linkend="manual.intro.setup.configure">here</link>. -</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> - -</section> - -<section xml:id="abi.versioning"><info><title>Versioning</title></info> - - -<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> - - <section xml:id="abi.versioning.goals"><info><title>Goals</title></info> - - -<para>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. -</para> -<para> -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. -</para> - -<para>Allows multiple, incompatible ABIs to coexist at the same time. -</para> - </section> - - <section xml:id="abi.versioning.history"><info><title>History</title></info> - - -<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 - <constant>DT_SONAME</constant> mechanism (at least on ELF - systems). It is versioned as follows: - </para> - - <itemizedlist> - <listitem><para>GCC 3.x: libgcc_s.so.1</para></listitem> - <listitem><para>GCC 4.x: libgcc_s.so.1</para></listitem> - </itemizedlist> - - <para>For m68k-linux the versions differ as follows: </para> - - <itemizedlist> - <listitem><para>GCC 3.4, GCC 4.x: libgcc_s.so.1 - when configuring <code>--with-sjlj-exceptions</code>, or - libgcc_s.so.2 </para> </listitem> - </itemizedlist> - - <para>For hppa-linux the versions differ as follows: </para> - - <itemizedlist> - <listitem><para>GCC 3.4, GCC 4.[0-1]: either libgcc_s.so.1 - when configuring <code>--with-sjlj-exceptions</code>, or - libgcc_s.so.2 </para> </listitem> - <listitem><para>GCC 4.[2-7]: either libgcc_s.so.3 when configuring - <code>--with-sjlj-exceptions</code>) or libgcc_s.so.4 - </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> - <listitem><para>GCC 4.3.0: GCC_4.3.0</para></listitem> - <listitem><para>GCC 4.4.0: GCC_4.4.0</para></listitem> - <listitem><para>GCC 4.5.0: GCC_4.5.0</para></listitem> - <listitem><para>GCC 4.6.0: GCC_4.6.0</para></listitem> - <listitem><para>GCC 4.7.0: GCC_4.7.0</para></listitem> - </itemizedlist> - </listitem> - - <listitem> - <para> - Release versioning on the libstdc++.so binary, implemented in - the same way as the libgcc_s.so binary above. Listed is the - filename: <constant>DT_SONAME</constant> can be deduced from - the filename by removing the last two period-delimited numbers. For - example, filename <filename>libstdc++.so.5.0.4</filename> - corresponds to a <constant>DT_SONAME</constant> of - <constant>libstdc++.so.5</constant>. Binaries with equivalent - <constant>DT_SONAME</constant>s 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 <constant>DT_SONAME</constant> as the - preceding release. - </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 (See Note 1)</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 <emphasis>(Incompatible with previous)</emphasis></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 <emphasis>(Incompatible with previous)</emphasis></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 (See Note 2)</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.4.0: libstdc++.so.6.0.0 <emphasis>(Incompatible with previous)</emphasis></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 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.2.0: libstdc++.so.6.0.9</para></listitem> - <listitem><para>GCC 4.2.1: libstdc++.so.6.0.9 (See Note 3)</para></listitem> - <listitem><para>GCC 4.2.2: libstdc++.so.6.0.9</para></listitem> - <listitem><para>GCC 4.3.0: libstdc++.so.6.0.10</para></listitem> - <listitem><para>GCC 4.4.0: libstdc++.so.6.0.11</para></listitem> - <listitem><para>GCC 4.4.1: libstdc++.so.6.0.12</para></listitem> - <listitem><para>GCC 4.4.2: libstdc++.so.6.0.13</para></listitem> - <listitem><para>GCC 4.5.0: libstdc++.so.6.0.14</para></listitem> - <listitem><para>GCC 4.6.0: libstdc++.so.6.0.15</para></listitem> - <listitem><para>GCC 4.6.1: libstdc++.so.6.0.16</para></listitem> - <listitem><para>GCC 4.7.0: libstdc++.so.6.0.17</para></listitem> - <listitem><para>GCC 4.8.0: libstdc++.so.6.0.18</para></listitem> - </itemizedlist> - <para> - Note 1: Error should be libstdc++.so.3.0.3. - </para> - <para> - Note 2: Not strictly required. - </para> - <para> - Note 3: This release (but not previous or subsequent) has one - known incompatibility, see <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=33678">33678</link> - in the GCC bug database. - </para> - </listitem> - - <listitem><para>Symbol versioning on the libstdc++.so binary.</para> - - <para>mapfile: libstdc++-v3/config/abi/pre/gnu.ver</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 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. - </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> - <listitem><para>GCC 4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</para></listitem> - <listitem><para>GCC 4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</para></listitem> - <listitem><para>GCC 4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3</para></listitem> - <listitem><para>GCC 4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3</para></listitem> - <listitem><para>GCC 4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4</para></listitem> - <listitem><para>GCC 4.6.0: GLIBCXX_3.4.15, CXXABI_1.3.5</para></listitem> - <listitem><para>GCC 4.6.1: GLIBCXX_3.4.16, CXXABI_1.3.5</para></listitem> - <listitem><para>GCC 4.7.0: GLIBCXX_3.4.17, CXXABI_1.3.6</para></listitem> - <listitem><para>GCC 4.8.0: GLIBCXX_3.4.18, CXXABI_1.3.7</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 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: 100</para></listitem> - <listitem><para>GCC 3.1: 100 (Error, should be 101)</para></listitem> - <listitem><para>GCC 3.2: 102</para></listitem> - <listitem><para>GCC 3.3: 102</para></listitem> - <listitem><para>GCC 3.4, GCC 4.x: 102 (when n=1)</para></listitem> - <listitem><para>GCC 3.4, GCC 4.x: 1000 + n (when n>1) </para></listitem> - <listitem><para>GCC 3.4, GCC 4.x: 999999 (when n=0)</para></listitem> - </itemizedlist> - <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: (Error, not versioned) </para></listitem> - <listitem><para>GCC 3.1: (Error, not versioned) </para></listitem> - <listitem><para>GCC 3.2: <code>-fabi-version=1</code></para></listitem> - <listitem><para>GCC 3.3: <code>-fabi-version=1</code></para></listitem> - <listitem><para>GCC 3.4, GCC 4.x: <code>-fabi-version=2</code> <emphasis>(Incompatible with previous)</emphasis></para></listitem> - </itemizedlist> - <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++-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.) - </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> - <listitem><para>GCC 4.2.1: 20070719</para></listitem> - <listitem><para>GCC 4.2.2: 20071007</para></listitem> - <listitem><para>GCC 4.2.3: 20080201</para></listitem> - <listitem><para>GCC 4.2.4: 20080519</para></listitem> - <listitem><para>GCC 4.3.0: 20080306</para></listitem> - <listitem><para>GCC 4.3.1: 20080606</para></listitem> - <listitem><para>GCC 4.3.2: 20080827</para></listitem> - <listitem><para>GCC 4.3.3: 20090124</para></listitem> - <listitem><para>GCC 4.3.4: 20090804</para></listitem> - <listitem><para>GCC 4.3.5: 20100522</para></listitem> - <listitem><para>GCC 4.3.6: 20110627</para></listitem> - <listitem><para>GCC 4.4.0: 20090421</para></listitem> - <listitem><para>GCC 4.4.1: 20090722</para></listitem> - <listitem><para>GCC 4.4.2: 20091015</para></listitem> - <listitem><para>GCC 4.4.3: 20100121</para></listitem> - <listitem><para>GCC 4.4.4: 20100429</para></listitem> - <listitem><para>GCC 4.4.5: 20101001</para></listitem> - <listitem><para>GCC 4.4.6: 20110416</para></listitem> - <listitem><para>GCC 4.4.7: 20120313</para></listitem> - <listitem><para>GCC 4.5.0: 20100414</para></listitem> - <listitem><para>GCC 4.5.1: 20100731</para></listitem> - <listitem><para>GCC 4.5.2: 20101216</para></listitem> - <listitem><para>GCC 4.5.3: 20110428</para></listitem> - <listitem><para>GCC 4.5.4: 20120702</para></listitem> - <listitem><para>GCC 4.6.0: 20110325</para></listitem> - <listitem><para>GCC 4.6.1: 20110627</para></listitem> - <listitem><para>GCC 4.6.2: 20111026</para></listitem> - <listitem><para>GCC 4.6.3: 20120301</para></listitem> - <listitem><para>GCC 4.7.0: 20120322</para></listitem> - <listitem><para>GCC 4.7.1: 20120614</para></listitem> - <listitem><para>GCC 4.7.2: 20120920</para></listitem> - </itemizedlist> - <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++-v3/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: "version-unused"</para></listitem> - <listitem><para>GCC 4.x: "version-unused"</para></listitem> - </itemizedlist> - <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 - <filename class="directory">include/c++</filename>, 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). - </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.x: include/c++/3.4.x</para></listitem> - <listitem><para>GCC 4.x.y: include/c++/4.x.y</para></listitem> - </itemizedlist> - <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> - - - </section> - - <section xml:id="abi.versioning.prereq"><info><title>Prerequisites</title></info> - - <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) 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. - </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 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. - </para> - </section> - - <section xml:id="abi.versioning.config"><info><title>Configuring</title></info> - - - <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: - <link linkend="manual.intro.setup.configure">here</link> - </para> - - <para> - There is one flag that explicitly deals with symbol versioning: - --enable-symvers. - </para> - - <para> - 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. - </para> - </section> - - <section xml:id="abi.versioning.active"><info><title>Checking Active</title></info> - - - <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> - 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. -</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 <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 -</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> - -<para> -On Solaris 2, you can use <code>pvs -r</code> instead: -</para> - -<programlisting> -%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); -</programlisting> - -<para> -<code>ldd -v</code> works too, but is very verbose. -</para> - - </section> -</section> - -<section xml:id="abi.changes_allowed"><info><title>Allowed Changes</title></info> - - -<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> - -</section> - -<section xml:id="abi.changes_no"><info><title>Prohibited Changes</title></info> - - -<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 passing instances of this -class in registers, the compiler will be forced to use memory. See the -section on <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://mentorembedded.github.com/cxx-abi/abi.html#calls">Function -Calling Conventions and APIs</link> - of the C++ ABI documentation for further details. -</para></listitem> - -</orderedlist> - -</section> - - - -<section xml:id="abi.impl"><info><title>Implementation</title></info> - - -<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> - -</section> - -<section xml:id="abi.testing"><info><title>Testing</title></info> - - - <section xml:id="abi.testing.single"><info><title>Single ABI Testing</title></info> - - - <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. - </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 of 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 PR 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> - - </section> - <section xml:id="abi.testing.multi"><info><title>Multiple ABI Testing</title></info> - -<para> -A "C" application, dynamically linked to two shared libraries, liba, -libb. The dependent library liba is a C++ shared library compiled with -GCC 3.3, and uses io, exceptions, locale, etc. The dependent library -libb is a C++ shared library compiled with GCC 3.4, 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 => /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) -</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 => /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) -</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> - </section> -</section> - -<section xml:id="abi.issues"><info><title>Outstanding Issues</title></info> - - -<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> -<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</link> -</para> - -<para> -<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR19664">19664: libstdc++ headers should have pop/push of the visibility around the declarations</link> -</para> - -</section> - -<bibliography xml:id="abi.biblio"><info><title>Bibliography</title></info> - - <biblioentry xml:id="biblio.abicheck"> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://abicheck.sourceforge.net"> - ABIcheck - </link> - </title> - </biblioentry> - - <biblioentry xml:id="biblio.cxxabi"> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://www.codesourcery.com/cxx-abi/"> - C++ ABI Summary - </link> - </title> - </biblioentry> - - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://www.intel.com/cd/software/products/asmo-na/eng/284736.htm"> - Intel Compilers for Linux Compatibility with the GNU Compilers - </link> - </title> - </biblioentry> - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://download.oracle.com/docs/cd/E19963-01/html/819-0690/index.html"> - Linker and Libraries Guide (document 819-0690) - </link> - </title> - </biblioentry> - - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://download.oracle.com/docs/cd/E19422-01/819-3689/index.html"> - Sun Studio 11: C++ Migration Guide (document 819-3689) - </link> - </title> - </biblioentry> - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://www.akkadia.org/drepper/dsohowto.pdf"> - How to Write Shared Libraries - </link> - </title> - - <author> - <personname> - <firstname>Ulrich</firstname><surname>Drepper</surname> - </personname> - </author> - </biblioentry> - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://www.arm.com/miscPDFs/8033.pdf"> - C++ ABI for the ARM Architecture - </link> - </title> - </biblioentry> - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html"> - Dynamic Shared Objects: Survey and Issues - </link> - </title> - - <subtitle> - ISO C++ J16/06-0046 - </subtitle> - <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author> - </biblioentry> - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html"> - Versioning With Namespaces - </link> - </title> - <subtitle> - ISO C++ J16/06-0083 - </subtitle> - <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author> - </biblioentry> - - <biblioentry> - <title> - <link xmlns:xlink="http://www.w3.org/1999/xlink" - xlink:href="http://syrcose.ispras.ru/2009/files/SYRCoSE2009-CfP.pdf"> - Binary Compatibility of Shared Libraries Implemented in C++ - on GNU/Linux Systems - </link> - </title> - - <subtitle> - SYRCoSE 2009 - </subtitle> - <author><personname><firstname>Pavel</firstname><surname>Shved</surname></personname></author> - <author><personname><firstname>Denis</firstname><surname>Silakov</surname></personname></author> - </biblioentry> -</bibliography> - -</section> |