abi.xml revision 1.1.1.11
1<section xmlns="http://docbook.org/ns/docbook" version="5.0" 2 xml:id="appendix.porting.abi" xreflabel="abi"> 3<?dbhtml filename="abi.html"?> 4 5<info><title>ABI Policy and Guidelines</title> 6 <keywordset> 7 <keyword>C++</keyword> 8 <keyword>ABI</keyword> 9 <keyword>version</keyword> 10 <keyword>dynamic</keyword> 11 <keyword>shared</keyword> 12 <keyword>compatibility</keyword> 13 </keywordset> 14</info> 15 16 17 18<para> 19</para> 20 21<section xml:id="abi.cxx_interface"><info><title>The C++ Interface</title></info> 22 23 24<para> 25 C++ applications often depend on specific language support 26 routines, say for throwing exceptions, or catching exceptions, and 27 perhaps also depend on features in the C++ Standard Library. 28</para> 29 30<para> 31 The C++ Standard Library has many include files, types defined in 32 those include files, specific named functions, and other 33 behavior. The text of these behaviors, as written in source include 34 files, is called the Application Programing Interface, or API. 35</para> 36 37<para> 38 Furthermore, C++ source that is compiled into object files is 39 transformed by the compiler: it arranges objects with specific 40 alignment and in a particular layout, mangling names according to a 41 well-defined algorithm, has specific arrangements for the support of 42 virtual functions, etc. These details are defined as the compiler 43 Application Binary Interface, or ABI. From GCC version 3 onwards the 44 GNU C++ compiler uses an industry-standard C++ ABI, the 45 <link linkend="biblio.cxxabi">Itanium C++ ABI</link>. 46</para> 47 48<para> 49 The GNU C++ compiler, g++, has a compiler command line option to 50 switch between various different C++ ABIs. This explicit version 51 switch is the flag <code>-fabi-version</code>. In addition, some 52 g++ command line options may change the ABI as a side-effect of 53 use. Such flags include <code>-fpack-struct</code> and 54 <code>-fno-exceptions</code>, but include others: see the complete 55 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 56 for Code Generation Conventions</link>. 57</para> 58 59<para> 60 The configure options used when building a specific libstdc++ 61 version may also impact the resulting library ABI. The available 62 configure options, and their impact on the library ABI, are 63 documented 64<link linkend="manual.intro.setup.configure">here</link>. 65</para> 66 67<para> Putting all of these ideas together results in the C++ Standard 68Library ABI, which is the compilation of a given library API by a 69given compiler ABI. In a nutshell: 70</para> 71 72<para> 73 <quote> 74 library API + compiler ABI = library ABI 75 </quote> 76</para> 77 78<para> 79 The library ABI is mostly of interest for end-users who have 80 unresolved symbols and are linking dynamically to the C++ Standard 81 library, and who thus must be careful to compile their application 82 with a compiler that is compatible with the available C++ Standard 83 library binary. In this case, compatible is defined with the equation 84 above: given an application compiled with a given compiler ABI and 85 library API, it will work correctly with a Standard C++ Library 86 created with the same constraints. 87</para> 88 89<para> 90 To use a specific version of the C++ ABI, one must use a 91 corresponding GNU C++ toolchain (i.e., g++ and libstdc++) that 92 implements the C++ ABI in question. 93</para> 94 95</section> 96 97<section xml:id="abi.versioning"><info><title>Versioning</title></info> 98 99 100<para> The C++ interface has evolved throughout the history of the GNU 101C++ toolchain. With each release, various details have been changed so 102as to give distinct versions to the C++ interface. 103</para> 104 105 <section xml:id="abi.versioning.goals"><info><title>Goals</title></info> 106 107 108<para>Extending existing, stable ABIs. Versioning gives subsequent 109releases of library binaries the ability to add new symbols and add 110functionality, all the while retaining compatibility with the previous 111releases in the series. Thus, program binaries linked with the initial 112release of a library binary will still run correctly if the library 113binary is replaced by carefully-managed subsequent library 114binaries. This is called forward compatibility. 115</para> 116<para> 117The reverse (backwards compatibility) is not true. It is not possible 118to take program binaries linked with the latest version of a library 119binary in a release series (with additional symbols added), substitute 120in the initial release of the library binary, and remain link 121compatible. 122</para> 123 124<para>Allows multiple, incompatible ABIs to coexist at the same time. 125</para> 126 </section> 127 128 <section xml:id="abi.versioning.history"><info><title>History</title></info> 129 130 131<para> 132 How can this complexity be managed? What does C++ versioning mean? 133 Because library and compiler changes often make binaries compiled 134 with one version of the GNU tools incompatible with binaries 135 compiled with other (either newer or older) versions of the same GNU 136 tools, specific techniques are used to make managing this complexity 137 easier. 138</para> 139 140<para> 141 The following techniques are used: 142</para> 143 144 <orderedlist> 145 146 <listitem><para>Release versioning on the libgcc_s.so binary. </para> 147 148 <para>This is implemented via file names and the ELF 149 <constant>DT_SONAME</constant> mechanism (at least on ELF 150 systems). It is versioned as follows: 151 </para> 152 153 <itemizedlist> 154 <listitem><para>GCC 3.x: libgcc_s.so.1</para></listitem> 155 <listitem><para>GCC 4.x: libgcc_s.so.1</para></listitem> 156 </itemizedlist> 157 158 <para>For m68k-linux the versions differ as follows: </para> 159 160 <itemizedlist> 161 <listitem><para>GCC 3.4, GCC 4.x: libgcc_s.so.1 162 when configuring <code>--with-sjlj-exceptions</code>, or 163 libgcc_s.so.2 </para> </listitem> 164 </itemizedlist> 165 166 <para>For hppa-linux the versions differ as follows: </para> 167 168 <itemizedlist> 169 <listitem><para>GCC 3.4, GCC 4.[0-1]: either libgcc_s.so.1 170 when configuring <code>--with-sjlj-exceptions</code>, or 171 libgcc_s.so.2 </para> </listitem> 172 <listitem><para>GCC 4.[2-7]: either libgcc_s.so.3 when configuring 173 <code>--with-sjlj-exceptions</code>) or libgcc_s.so.4 174 </para> </listitem> 175 </itemizedlist> 176 177 </listitem> 178 179 <listitem><para>Symbol versioning on the libgcc_s.so binary.</para> 180 181 <para>It is versioned with the following labels and version 182 definitions, where the version definition is the maximum for a 183 particular release. Labels are cumulative. If a particular release 184 is not listed, it has the same version labels as the preceding 185 release.</para> 186 187 <para>This corresponds to the mapfile: gcc/libgcc-std.ver</para> 188 <itemizedlist> 189 <listitem><para>GCC 3.0.0: GCC_3.0</para></listitem> 190 <listitem><para>GCC 3.3.0: GCC_3.3</para></listitem> 191 <listitem><para>GCC 3.3.1: GCC_3.3.1</para></listitem> 192 <listitem><para>GCC 3.3.2: GCC_3.3.2</para></listitem> 193 <listitem><para>GCC 3.3.4: GCC_3.3.4</para></listitem> 194 <listitem><para>GCC 3.4.0: GCC_3.4</para></listitem> 195 <listitem><para>GCC 3.4.2: GCC_3.4.2</para></listitem> 196 <listitem><para>GCC 3.4.4: GCC_3.4.4</para></listitem> 197 <listitem><para>GCC 4.0.0: GCC_4.0.0</para></listitem> 198 <listitem><para>GCC 4.1.0: GCC_4.1.0</para></listitem> 199 <listitem><para>GCC 4.2.0: GCC_4.2.0</para></listitem> 200 <listitem><para>GCC 4.3.0: GCC_4.3.0</para></listitem> 201 <listitem><para>GCC 4.4.0: GCC_4.4.0</para></listitem> 202 <listitem><para>GCC 4.5.0: GCC_4.5.0</para></listitem> 203 <listitem><para>GCC 4.6.0: GCC_4.6.0</para></listitem> 204 <listitem><para>GCC 4.7.0: GCC_4.7.0</para></listitem> 205 <listitem><para>GCC 4.8.0: GCC_4.8.0</para></listitem> 206 </itemizedlist> 207 </listitem> 208 209 <listitem> 210 <para> 211 Release versioning on the libstdc++.so binary, implemented in 212 the same way as the libgcc_s.so binary above. Listed is the 213 filename: <constant>DT_SONAME</constant> can be deduced from 214 the filename by removing the last two period-delimited numbers. For 215 example, filename <filename>libstdc++.so.5.0.4</filename> 216 corresponds to a <constant>DT_SONAME</constant> of 217 <constant>libstdc++.so.5</constant>. Binaries with equivalent 218 <constant>DT_SONAME</constant>s are forward-compatibile: in 219 the table below, releases incompatible with the previous 220 one are explicitly noted. 221 If a particular release is not listed, its libstdc++.so binary 222 has the same filename and <constant>DT_SONAME</constant> as the 223 preceding release. 224 </para> 225 226 <para>It is versioned as follows: 227 </para> 228 <itemizedlist> 229 <listitem><para>GCC 3.0.0: libstdc++.so.3.0.0</para></listitem> 230 <listitem><para>GCC 3.0.1: libstdc++.so.3.0.1</para></listitem> 231 <listitem><para>GCC 3.0.2: libstdc++.so.3.0.2</para></listitem> 232 <listitem><para>GCC 3.0.3: libstdc++.so.3.0.2 (See Note 1)</para></listitem> 233 <listitem><para>GCC 3.0.4: libstdc++.so.3.0.4</para></listitem> 234 <listitem><para>GCC 3.1.0: libstdc++.so.4.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem> 235 <listitem><para>GCC 3.1.1: libstdc++.so.4.0.1</para></listitem> 236 <listitem><para>GCC 3.2.0: libstdc++.so.5.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem> 237 <listitem><para>GCC 3.2.1: libstdc++.so.5.0.1</para></listitem> 238 <listitem><para>GCC 3.2.2: libstdc++.so.5.0.2</para></listitem> 239 <listitem><para>GCC 3.2.3: libstdc++.so.5.0.3 (See Note 2)</para></listitem> 240 <listitem><para>GCC 3.3.0: libstdc++.so.5.0.4</para></listitem> 241 <listitem><para>GCC 3.3.1: libstdc++.so.5.0.5</para></listitem> 242 <listitem><para>GCC 3.4.0: libstdc++.so.6.0.0 <emphasis>(Incompatible with previous)</emphasis></para></listitem> 243 <listitem><para>GCC 3.4.1: libstdc++.so.6.0.1</para></listitem> 244 <listitem><para>GCC 3.4.2: libstdc++.so.6.0.2</para></listitem> 245 <listitem><para>GCC 3.4.3: libstdc++.so.6.0.3</para></listitem> 246 <listitem><para>GCC 4.0.0: libstdc++.so.6.0.4</para></listitem> 247 <listitem><para>GCC 4.0.1: libstdc++.so.6.0.5</para></listitem> 248 <listitem><para>GCC 4.0.2: libstdc++.so.6.0.6</para></listitem> 249 <listitem><para>GCC 4.0.3: libstdc++.so.6.0.7</para></listitem> 250 <listitem><para>GCC 4.1.0: libstdc++.so.6.0.7</para></listitem> 251 <listitem><para>GCC 4.1.1: libstdc++.so.6.0.8</para></listitem> 252 <listitem><para>GCC 4.2.0: libstdc++.so.6.0.9</para></listitem> 253 <listitem><para>GCC 4.2.1: libstdc++.so.6.0.9 (See Note 3)</para></listitem> 254 <listitem><para>GCC 4.2.2: libstdc++.so.6.0.9</para></listitem> 255 <listitem><para>GCC 4.3.0: libstdc++.so.6.0.10</para></listitem> 256 <listitem><para>GCC 4.4.0: libstdc++.so.6.0.11</para></listitem> 257 <listitem><para>GCC 4.4.1: libstdc++.so.6.0.12</para></listitem> 258 <listitem><para>GCC 4.4.2: libstdc++.so.6.0.13</para></listitem> 259 <listitem><para>GCC 4.5.0: libstdc++.so.6.0.14</para></listitem> 260 <listitem><para>GCC 4.6.0: libstdc++.so.6.0.15</para></listitem> 261 <listitem><para>GCC 4.6.1: libstdc++.so.6.0.16</para></listitem> 262 <listitem><para>GCC 4.7.0: libstdc++.so.6.0.17</para></listitem> 263 <listitem><para>GCC 4.8.0: libstdc++.so.6.0.18</para></listitem> 264 <listitem><para>GCC 4.8.3: libstdc++.so.6.0.19</para></listitem> 265 <listitem><para>GCC 4.9.0: libstdc++.so.6.0.20</para></listitem> 266 <listitem><para>GCC 5.1.0: libstdc++.so.6.0.21</para></listitem> 267 <listitem><para>GCC 6.1.0: libstdc++.so.6.0.22</para></listitem> 268 <listitem><para>GCC 7.1.0: libstdc++.so.6.0.23</para></listitem> 269 <listitem><para>GCC 7.2.0: libstdc++.so.6.0.24</para></listitem> 270 <listitem><para>GCC 8.0.0: libstdc++.so.6.0.25</para></listitem> 271 <listitem><para>GCC 9.1.0: libstdc++.so.6.0.26</para></listitem> 272 <listitem><para>GCC 9.2.0: libstdc++.so.6.0.27</para></listitem> 273 <listitem><para>GCC 9.3.0: libstdc++.so.6.0.28</para></listitem> 274 </itemizedlist> 275 <para> 276 Note 1: Error should be libstdc++.so.3.0.3. 277 </para> 278 <para> 279 Note 2: Not strictly required. 280 </para> 281 <para> 282 Note 3: This release (but not previous or subsequent) has one 283 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> 284 in the GCC bug database. 285 </para> 286 </listitem> 287 288 <listitem><para>Symbol versioning on the libstdc++.so binary.</para> 289 290 <para>mapfile: libstdc++-v3/config/abi/pre/gnu.ver</para> 291 <para>It is versioned with the following labels and version 292 definitions, where the version definition is the maximum for a 293 particular release. Note, only symbols which are newly introduced 294 will use the maximum version definition. Thus, for release series 295 with the same label, but incremented version definitions, the later 296 release has both versions. (An example of this would be the 297 GCC 3.2.1 release, which has GLIBCPP_3.2.1 for new symbols and 298 GLIBCPP_3.2 for symbols that were introduced in the GCC 3.2.0 299 release.) If a particular release is not listed, it has the same 300 version labels as the preceding release. 301 </para> 302 <itemizedlist> 303 <listitem><para>GCC 3.0.0: (Error, not versioned)</para></listitem> 304 <listitem><para>GCC 3.0.1: (Error, not versioned)</para></listitem> 305 <listitem><para>GCC 3.0.2: (Error, not versioned)</para></listitem> 306 <listitem><para>GCC 3.0.3: (Error, not versioned)</para></listitem> 307 <listitem><para>GCC 3.0.4: (Error, not versioned)</para></listitem> 308 <listitem><para>GCC 3.1.0: GLIBCPP_3.1, CXXABI_1</para></listitem> 309 <listitem><para>GCC 3.1.1: GLIBCPP_3.1, CXXABI_1</para></listitem> 310 <listitem><para>GCC 3.2.0: GLIBCPP_3.2, CXXABI_1.2</para></listitem> 311 <listitem><para>GCC 3.2.1: GLIBCPP_3.2.1, CXXABI_1.2</para></listitem> 312 <listitem><para>GCC 3.2.2: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem> 313 <listitem><para>GCC 3.2.3: GLIBCPP_3.2.2, CXXABI_1.2</para></listitem> 314 <listitem><para>GCC 3.3.0: GLIBCPP_3.2.2, CXXABI_1.2.1</para></listitem> 315 <listitem><para>GCC 3.3.1: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> 316 <listitem><para>GCC 3.3.2: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> 317 <listitem><para>GCC 3.3.3: GLIBCPP_3.2.3, CXXABI_1.2.1</para></listitem> 318 <listitem><para>GCC 3.4.0: GLIBCXX_3.4, CXXABI_1.3</para></listitem> 319 <listitem><para>GCC 3.4.1: GLIBCXX_3.4.1, CXXABI_1.3</para></listitem> 320 <listitem><para>GCC 3.4.2: GLIBCXX_3.4.2</para></listitem> 321 <listitem><para>GCC 3.4.3: GLIBCXX_3.4.3</para></listitem> 322 <listitem><para>GCC 4.0.0: GLIBCXX_3.4.4, CXXABI_1.3.1</para></listitem> 323 <listitem><para>GCC 4.0.1: GLIBCXX_3.4.5</para></listitem> 324 <listitem><para>GCC 4.0.2: GLIBCXX_3.4.6</para></listitem> 325 <listitem><para>GCC 4.0.3: GLIBCXX_3.4.7</para></listitem> 326 <listitem><para>GCC 4.1.1: GLIBCXX_3.4.8</para></listitem> 327 <listitem><para>GCC 4.2.0: GLIBCXX_3.4.9</para></listitem> 328 <listitem><para>GCC 4.3.0: GLIBCXX_3.4.10, CXXABI_1.3.2</para></listitem> 329 <listitem><para>GCC 4.4.0: GLIBCXX_3.4.11, CXXABI_1.3.3</para></listitem> 330 <listitem><para>GCC 4.4.1: GLIBCXX_3.4.12, CXXABI_1.3.3</para></listitem> 331 <listitem><para>GCC 4.4.2: GLIBCXX_3.4.13, CXXABI_1.3.3</para></listitem> 332 <listitem><para>GCC 4.5.0: GLIBCXX_3.4.14, CXXABI_1.3.4</para></listitem> 333 <listitem><para>GCC 4.6.0: GLIBCXX_3.4.15, CXXABI_1.3.5</para></listitem> 334 <listitem><para>GCC 4.6.1: GLIBCXX_3.4.16, CXXABI_1.3.5</para></listitem> 335 <listitem><para>GCC 4.7.0: GLIBCXX_3.4.17, CXXABI_1.3.6</para></listitem> 336 <listitem><para>GCC 4.8.0: GLIBCXX_3.4.18, CXXABI_1.3.7</para></listitem> 337 <listitem><para>GCC 4.8.3: GLIBCXX_3.4.19, CXXABI_1.3.7</para></listitem> 338 <listitem><para>GCC 4.9.0: GLIBCXX_3.4.20, CXXABI_1.3.8</para></listitem> 339 <listitem><para>GCC 5.1.0: GLIBCXX_3.4.21, CXXABI_1.3.9</para></listitem> 340 <listitem><para>GCC 6.1.0: GLIBCXX_3.4.22, CXXABI_1.3.10</para></listitem> 341 <listitem><para>GCC 7.1.0: GLIBCXX_3.4.23, CXXABI_1.3.11</para></listitem> 342 <listitem><para>GCC 7.2.0: GLIBCXX_3.4.24, CXXABI_1.3.11</para></listitem> 343 <listitem><para>GCC 8.0.0: GLIBCXX_3.4.25, CXXABI_1.3.11</para></listitem> 344 <listitem><para>GCC 9.0.0: GLIBCXX_3.4.26, CXXABI_1.3.11</para></listitem> 345 </itemizedlist> 346 </listitem> 347 348 <listitem> 349 <para>Incremental bumping of a compiler pre-defined macro, 350 __GXX_ABI_VERSION. This macro is defined as the version of the 351 compiler v3 ABI, with g++ 3.0 being version 100. This macro will 352 be automatically defined whenever g++ is used (the curious can 353 test this by invoking g++ with the '-v' flag.) 354 </para> 355 356 <para> 357 This macro was defined in the file "lang-specs.h" in the gcc/cp directory. 358 Later versions defined it in "c-common.c" in the gcc directory, and from 359 G++ 3.4 it is defined in c-cppbuiltin.c and its value determined by the 360 '-fabi-version' command line option. 361 </para> 362 363 <para> 364 It is versioned as follows, where 'n' is given by '-fabi-version=n': 365 </para> 366 <itemizedlist> 367 <listitem><para>GCC 3.0: 100</para></listitem> 368 <listitem><para>GCC 3.1: 100 (Error, should be 101)</para></listitem> 369 <listitem><para>GCC 3.2: 102</para></listitem> 370 <listitem><para>GCC 3.3: 102</para></listitem> 371 <listitem><para>GCC 3.4, GCC 4.x: 102 (when n=1)</para></listitem> 372 <listitem><para>GCC 3.4, GCC 4.x: 1000 + n (when n>1) </para></listitem> 373 <listitem><para>GCC 3.4, GCC 4.x: 999999 (when n=0)</para></listitem> 374 </itemizedlist> 375 <para/> 376 </listitem> 377 378 <listitem> 379 <para>Changes to the default compiler option for 380 <code>-fabi-version</code>. 381 </para> 382 <para> 383 It is versioned as follows: 384 </para> 385 <itemizedlist> 386 <listitem><para>GCC 3.0: (Error, not versioned) </para></listitem> 387 <listitem><para>GCC 3.1: (Error, not versioned) </para></listitem> 388 <listitem><para>GCC 3.2: <code>-fabi-version=1</code></para></listitem> 389 <listitem><para>GCC 3.3: <code>-fabi-version=1</code></para></listitem> 390 <listitem><para>GCC 3.4, GCC 4.x: <code>-fabi-version=2</code> <emphasis>(Incompatible with previous)</emphasis></para></listitem> 391 <listitem><para>GCC 5 and higher: <code>-fabi-version=0</code> <emphasis>(See GCC manual for meaning)</emphasis></para></listitem> 392 </itemizedlist> 393 <para/> 394 </listitem> 395 396 <listitem xml:id="abi.versioning.__GLIBCXX__"> 397 <para>Incremental bumping of a library pre-defined macro. For releases 398 before 3.4.0, the macro is <symbol>__GLIBCPP__</symbol>. For later 399 releases, it's <symbol>__GLIBCXX__</symbol>. (The libstdc++ project 400 generously changed from CPP to CXX throughout its source to allow the 401 "C" pre-processor the CPP macro namespace.) These macros are defined 402 as the date the library was released, in compressed ISO date format, 403 as an integer constant. 404 </para> 405 406 <para> 407 This macro is defined in the file 408 <filename class="headerfile">c++config</filename> in the 409 <filename class="directory">libstdc++-v3/include/bits</filename> 410 directory. Up to GCC 4.1.0, it was 411 changed every night by an automated script. Since GCC 4.1.0 it is set 412 during configuration to the same value as 413 <filename>gcc/DATESTAMP</filename>, so for an official release its value 414 is the same as the date of the release, which is given in the <link 415 xmlns:xlink="http://www.w3.org/1999/xlink" 416 xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC Release 417 Timeline</link>. 418 </para> 419 420 <para> 421 This macro can be used in code to detect whether the C++ Standard Library 422 implementation in use is libstdc++, but is not useful for detecting the 423 libstdc++ version, nor whether particular features are supported. 424 The macro value might be a date after a feature was added to the 425 development trunk, but the release could be from an older branch without 426 the feature. For example, in the 5.4.0 release the macro has the value 427 <literal>20160603</literal> which is greater than the 428 <literal>20160427</literal> value of the macro in the 6.1.0 release, 429 but there are features supported in the 6.1.0 release that are not 430 supported in the 5.4.0 release. 431 You also can't test for the exact values listed below to try and 432 identify a release, because a snapshot taken from the gcc-5-branch on 433 2016-04-27 would have the same value for the macro as the 6.1.0 release 434 despite being a different version. 435 Many GNU/Linux distributions build their GCC packages from snapshots, so 436 the macro can have dates that don't correspond to official releases. 437 </para> 438 439 <para> 440 It is versioned as follows: 441 </para> 442 <itemizedlist> 443 <listitem><para>GCC 3.0.0: <literal>20010615</literal></para></listitem> 444 <listitem><para>GCC 3.0.1: <literal>20010819</literal></para></listitem> 445 <listitem><para>GCC 3.0.2: <literal>20011023</literal></para></listitem> 446 <listitem><para>GCC 3.0.3: <literal>20011220</literal></para></listitem> 447 <listitem><para>GCC 3.0.4: <literal>20020220</literal></para></listitem> 448 <listitem><para>GCC 3.1.0: <literal>20020514</literal></para></listitem> 449 <listitem><para>GCC 3.1.1: <literal>20020725</literal></para></listitem> 450 <listitem><para>GCC 3.2.0: <literal>20020814</literal></para></listitem> 451 <listitem><para>GCC 3.2.1: <literal>20021119</literal></para></listitem> 452 <listitem><para>GCC 3.2.2: <literal>20030205</literal></para></listitem> 453 <listitem><para>GCC 3.2.3: <literal>20030422</literal></para></listitem> 454 <listitem><para>GCC 3.3.0: <literal>20030513</literal></para></listitem> 455 <listitem><para>GCC 3.3.1: <literal>20030804</literal></para></listitem> 456 <listitem><para>GCC 3.3.2: <literal>20031016</literal></para></listitem> 457 <listitem><para>GCC 3.3.3: <literal>20040214</literal></para></listitem> 458 <listitem><para>GCC 3.4.0: <literal>20040419</literal></para></listitem> 459 <listitem><para>GCC 3.4.1: <literal>20040701</literal></para></listitem> 460 <listitem><para>GCC 3.4.2: <literal>20040906</literal></para></listitem> 461 <listitem><para>GCC 3.4.3: <literal>20041105</literal></para></listitem> 462 <listitem><para>GCC 3.4.4: <literal>20050519</literal></para></listitem> 463 <listitem><para>GCC 3.4.5: <literal>20051201</literal></para></listitem> 464 <listitem><para>GCC 3.4.6: <literal>20060306</literal></para></listitem> 465 <listitem><para>GCC 4.0.0: <literal>20050421</literal></para></listitem> 466 <listitem><para>GCC 4.0.1: <literal>20050707</literal></para></listitem> 467 <listitem><para>GCC 4.0.2: <literal>20050921</literal></para></listitem> 468 <listitem><para>GCC 4.0.3: <literal>20060309</literal></para></listitem> 469 <listitem><para> 470 GCC 4.1.0 and later: the GCC release date, as shown in the 471 <link xmlns:xlink="http://www.w3.org/1999/xlink" 472 xlink:href="https://gcc.gnu.org/develop.html#timeline">GCC 473 Release Timeline</link> 474 </para></listitem> 475 </itemizedlist> 476 <para/> 477 </listitem> 478 479 <listitem> 480 <para> 481 Since GCC 7, incremental bumping of a library pre-defined macro, 482 <symbol>_GLIBCXX_RELEASE</symbol>. This macro is defined to the GCC 483 major version that the libstdc++ headers belong to, as an integer constant. 484 When compiling with GCC it has the same value as GCC's pre-defined 485 macro <symbol>__GNUC__</symbol>. 486 This macro can be used when libstdc++ is used with a non-GNU 487 compiler where <symbol>__GNUC__</symbol> is not defined, or has a 488 different value that doesn't correspond to the libstdc++ version. 489 </para> 490 491 <para> 492 This macro is defined in the file 493 <filename class="headerfile">c++config</filename> in the 494 <filename class="directory">libstdc++-v3/include/bits</filename> 495 directory and is generated automatically by autoconf as part of the 496 configure-time generation of 497 <filename class="headerfile">config.h</filename> and subsequently 498 <filename class="headerfile"><bits/c++config.h></filename>. 499 </para> 500 </listitem> 501 502 <listitem> 503 <para> 504 Historically, incremental bumping of a library pre-defined macro, 505 <symbol>_GLIBCPP_VERSION</symbol>. This macro was defined as the 506 released version of the library, as a string literal. This was only 507 implemented in GCC 3.1.0 releases and higher, and was deprecated in 508 3.4.x (where it was called <symbol>_GLIBCXX_VERSION</symbol>), 509 and is not defined in 4.0.0 and higher. 510 </para> 511 512 <para> 513 This macro is defined in the same file as 514 <symbol>_GLIBCXX_RELEASE</symbol>, described above. 515 </para> 516 517 <para> 518 It is versioned as follows: 519 </para> 520 <itemizedlist> 521 <listitem><para>GCC 3.0.0: <literal>"3.0.0"</literal></para></listitem> 522 <listitem><para>GCC 3.0.1: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.1"</literal>)</para></listitem> 523 <listitem><para>GCC 3.0.2: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.2"</literal>)</para></listitem> 524 <listitem><para>GCC 3.0.3: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.3"</literal>)</para></listitem> 525 <listitem><para>GCC 3.0.4: <literal>"3.0.0"</literal> (Error, should be <literal>"3.0.4"</literal>)</para></listitem> 526 <listitem><para>GCC 3.1.0: <literal>"3.1.0"</literal></para></listitem> 527 <listitem><para>GCC 3.1.1: <literal>"3.1.1"</literal></para></listitem> 528 <listitem><para>GCC 3.2.0: <literal>"3.2"</literal></para></listitem> 529 <listitem><para>GCC 3.2.1: <literal>"3.2.1"</literal></para></listitem> 530 <listitem><para>GCC 3.2.2: <literal>"3.2.2"</literal></para></listitem> 531 <listitem><para>GCC 3.2.3: <literal>"3.2.3"</literal></para></listitem> 532 <listitem><para>GCC 3.3.0: <literal>"3.3"</literal></para></listitem> 533 <listitem><para>GCC 3.3.1: <literal>"3.3.1"</literal></para></listitem> 534 <listitem><para>GCC 3.3.2: <literal>"3.3.2"</literal></para></listitem> 535 <listitem><para>GCC 3.3.3: <literal>"3.3.3"</literal></para></listitem> 536 <listitem><para>GCC 3.4: <literal>"version-unused"</literal></para></listitem> 537 <listitem><para>GCC 4 and later: not defined</para></listitem> 538 </itemizedlist> 539 <para/> 540 </listitem> 541 542 <listitem> 543 <para> 544 Matching each specific C++ compiler release to a specific set of 545 C++ include files. This is only implemented in GCC 3.1.1 releases 546 and higher. 547 </para> 548 <para> 549 All C++ includes are installed in 550 <filename class="directory">include/c++</filename>, then nested in a 551 directory hierarchy corresponding to the C++ compiler's released 552 version. This version corresponds to the variable "gcc_version" in 553 "libstdc++-v3/acinclude.m4," and more details can be found in that 554 file's macro GLIBCXX_CONFIGURE (GLIBCPP_CONFIGURE before GCC 3.4.0). 555 </para> 556 <para> 557 C++ includes are versioned as follows: 558 </para> 559 <itemizedlist> 560 <listitem><para>GCC 3.0.0: include/g++-v3</para></listitem> 561 <listitem><para>GCC 3.0.1: include/g++-v3</para></listitem> 562 <listitem><para>GCC 3.0.2: include/g++-v3</para></listitem> 563 <listitem><para>GCC 3.0.3: include/g++-v3</para></listitem> 564 <listitem><para>GCC 3.0.4: include/g++-v3</para></listitem> 565 <listitem><para>GCC 3.1.0: include/g++-v3</para></listitem> 566 <listitem><para>GCC 3.1.1: include/c++/3.1.1</para></listitem> 567 <listitem><para>GCC 3.2.0: include/c++/3.2</para></listitem> 568 <listitem><para>GCC 3.2.1: include/c++/3.2.1</para></listitem> 569 <listitem><para>GCC 3.2.2: include/c++/3.2.2</para></listitem> 570 <listitem><para>GCC 3.2.3: include/c++/3.2.3</para></listitem> 571 <listitem><para>GCC 3.3.0: include/c++/3.3</para></listitem> 572 <listitem><para>GCC 3.3.1: include/c++/3.3.1</para></listitem> 573 <listitem><para>GCC 3.3.2: include/c++/3.3.2</para></listitem> 574 <listitem><para>GCC 3.3.3: include/c++/3.3.3</para></listitem> 575 <listitem><para>GCC 3.4.x: include/c++/3.4.x</para></listitem> 576 <listitem><para>GCC 4.x.y: include/c++/4.x.y</para></listitem> 577 <listitem><para>GCC 5.x.0: include/c++/5.x.0</para></listitem> 578 <listitem><para>GCC 6.x.0: include/c++/6.x.0</para></listitem> 579 <listitem><para>GCC 7.x.0: include/c++/7.x.0</para></listitem> 580 <listitem><para>GCC 8.x.0: include/c++/8.x.0</para></listitem> 581 </itemizedlist> 582 <para/> 583 </listitem> 584 </orderedlist> 585 586<para> 587 Taken together, these techniques can accurately specify interface 588 and implementation changes in the GNU C++ tools themselves. Used 589 properly, they allow both the GNU C++ tools implementation, and 590 programs using them, an evolving yet controlled development that 591 maintains backward compatibility. 592</para> 593 594 595 </section> 596 597 <section xml:id="abi.versioning.prereq"><info><title>Prerequisites</title></info> 598 599 <para> 600 Minimum environment that supports a versioned ABI: A supported 601 dynamic linker, a GNU linker of sufficient vintage to understand 602 demangled C++ name globbing (ld) or the Sun linker, a shared 603 executable compiled 604 with g++, and shared libraries (libgcc_s, libstdc++) compiled by 605 a compiler (g++) with a compatible ABI. Phew. 606 </para> 607 608 <para> 609 On top of all that, an additional constraint: libstdc++ did not 610 attempt to version symbols (or age gracefully, really) until 611 version 3.1.0. 612 </para> 613 614 <para> 615 Most modern GNU/Linux and BSD versions, particularly ones using 616 GCC 3.1 and later, will meet the 617 requirements above, as does Solaris 2.5 and up. 618 </para> 619 </section> 620 621 <section xml:id="abi.versioning.config"><info><title>Configuring</title></info> 622 623 624 <para> 625 It turns out that most of the configure options that change 626 default behavior will impact the mangled names of exported 627 symbols, and thus impact versioning and compatibility. 628 </para> 629 630 <para> 631 For more information on configure options, including ABI 632 impacts, see: 633 <link linkend="manual.intro.setup.configure">here</link> 634 </para> 635 636 <para> 637 There is one flag that explicitly deals with symbol versioning: 638 --enable-symvers. 639 </para> 640 641 <para> 642 In particular, libstdc++-v3/acinclude.m4 has a macro called 643 GLIBCXX_ENABLE_SYMVERS that defaults to yes (or the argument 644 passed in via --enable-symvers=foo). At that point, the macro 645 attempts to make sure that all the requirement for symbol 646 versioning are in place. For more information, please consult 647 acinclude.m4. 648 </para> 649 </section> 650 651 <section xml:id="abi.versioning.active"><info><title>Checking Active</title></info> 652 653 654 <para> 655 When the GNU C++ library is being built with symbol versioning 656 on, you should see the following at configure time for 657 libstdc++ (showing either 'gnu' or another of the supported styles): 658 </para> 659 660<screen> 661<computeroutput> 662 checking versioning on shared library symbols... gnu 663</computeroutput> 664</screen> 665 666<para> 667 If you don't see this line in the configure output, or if this line 668 appears but the last word is 'no', then you are out of luck. 669</para> 670 671<para> 672 If the compiler is pre-installed, a quick way to test is to compile 673 the following (or any) simple C++ file and link it to the shared 674 libstdc++ library: 675</para> 676 677<programlisting> 678#include <iostream> 679 680int main() 681{ std::cout << "hello" << std::endl; return 0; } 682 683%g++ hello.cc -o hello.out 684 685%ldd hello.out 686 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) 687 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) 688 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40016000) 689 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) 690 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 691 692%nm hello.out 693</programlisting> 694 695<para> 696If you see symbols in the resulting output with "GLIBCXX_3" as part 697of the name, then the executable is versioned. Here's an example: 698</para> 699 700<para> 701 <code>U _ZNSt8ios_base4InitC1Ev@@GLIBCXX_3.4</code> 702</para> 703 704<para> 705On Solaris 2, you can use <code>pvs -r</code> instead: 706</para> 707 708<programlisting> 709%g++ hello.cc -o hello.out 710 711%pvs -r hello.out 712 libstdc++.so.6 (GLIBCXX_3.4, GLIBCXX_3.4.12); 713 libgcc_s.so.1 (GCC_3.0); 714 libc.so.1 (SUNWprivate_1.1, SYSVABI_1.3); 715</programlisting> 716 717<para> 718<code>ldd -v</code> works too, but is very verbose. 719</para> 720 721 </section> 722</section> 723 724<section xml:id="abi.changes_allowed"><info><title>Allowed Changes</title></info> 725 726 727<para> 728The following will cause the library minor version number to 729increase, say from "libstdc++.so.3.0.4" to "libstdc++.so.3.0.5". 730</para> 731<orderedlist> 732 <listitem><para>Adding an exported global or static data member</para></listitem> 733 <listitem><para>Adding an exported function, static or non-virtual member function</para></listitem> 734 <listitem><para>Adding an exported symbol or symbols by additional instantiations</para></listitem> 735</orderedlist> 736<para> 737Other allowed changes are possible. 738</para> 739 740</section> 741 742<section xml:id="abi.changes_no"><info><title>Prohibited Changes</title></info> 743 744 745<para> 746The following non-exhaustive list will cause the library major version 747number to increase, say from "libstdc++.so.3.0.4" to 748"libstdc++.so.4.0.0". 749</para> 750 751<orderedlist> 752 <listitem><para>Changes in the gcc/g++ compiler ABI</para></listitem> 753<listitem><para>Changing size of an exported symbol</para></listitem> 754<listitem><para>Changing alignment of an exported symbol</para></listitem> 755<listitem><para>Changing the layout of an exported symbol</para></listitem> 756<listitem><para>Changing mangling on an exported symbol</para></listitem> 757<listitem><para>Deleting an exported symbol</para></listitem> 758<listitem><para>Changing the inheritance properties of a type by adding or removing 759 base classes</para></listitem> 760<listitem><para> 761 Changing the size, alignment, or layout of types 762 specified in the C++ standard. These may not necessarily be 763 instantiated or otherwise exported in the library binary, and 764 include all the required locale facets, as well as things like 765 std::basic_streambuf, et al. 766</para></listitem> 767 768<listitem><para> Adding an explicit copy constructor or destructor to a 769class that would otherwise have implicit versions. This will change 770the way the compiler deals with this class in by-value return 771statements or parameters: instead of passing instances of this 772class in registers, the compiler will be forced to use memory. See the 773section on <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://itanium-cxx-abi.github.io/cxx-abi/abi.html#calls">Function 774Calling Conventions and APIs</link> 775 of the C++ ABI documentation for further details. 776</para></listitem> 777 778</orderedlist> 779 780</section> 781 782 783 784<section xml:id="abi.impl"><info><title>Implementation</title></info> 785 786 787<orderedlist> 788 <listitem> 789 <para> 790 Separation of interface and implementation 791 </para> 792 <para> 793 This is accomplished by two techniques that separate the API from 794 the ABI: forcing undefined references to link against a library 795 binary for definitions. 796 </para> 797 798<variablelist> 799 <varlistentry> 800 <term>Include files have declarations, source files have defines</term> 801 802 <listitem> 803 <para> 804 For non-templatized types, such as much of <code>class 805 locale</code>, the appropriate standard C++ include, say 806 <code>locale</code>, can contain full declarations, while 807 various source files (say <code> locale.cc, locale_init.cc, 808 localename.cc</code>) contain definitions. 809 </para> 810 </listitem> 811 </varlistentry> 812 813 <varlistentry> 814 <term>Extern template on required types</term> 815 816 <listitem> 817 <para> 818 For parts of the standard that have an explicit list of 819 required instantiations, the GNU extension syntax <code> extern 820 template </code> can be used to control where template 821 definitions reside. By marking required instantiations as 822 <code> extern template </code> in include files, and providing 823 explicit instantiations in the appropriate instantiation files, 824 non-inlined template functions can be versioned. This technique 825 is mostly used on parts of the standard that require <code> 826 char</code> and <code> wchar_t</code> instantiations, and 827 includes <code> basic_string</code>, the locale facets, and the 828 types in <code> iostreams</code>. 829 </para> 830 </listitem> 831 </varlistentry> 832 833 </variablelist> 834 835 <para> 836 In addition, these techniques have the additional benefit that they 837 reduce binary size, which can increase runtime performance. 838 </para> 839 </listitem> 840 841 <listitem> 842 <para> 843 Namespaces linking symbol definitions to export mapfiles 844 </para> 845 <para> 846 All symbols in the shared library binary are processed by a 847 linker script at build time that either allows or disallows 848 external linkage. Because of this, some symbols, regardless of 849 normal C/C++ linkage, are not visible. Symbols that are internal 850 have several appealing characteristics: by not exporting the 851 symbols, there are no relocations when the shared library is 852 started and thus this makes for faster runtime loading 853 performance by the underlying dynamic loading mechanism. In 854 addition, they have the possibility of changing without impacting 855 ABI compatibility. 856 </para> 857 858<para>The following namespaces are transformed by the mapfile:</para> 859 860<variablelist> 861 862 <varlistentry> 863<term><code>namespace std</code></term> 864<listitem><para> Defaults to exporting all symbols in label 865<code>GLIBCXX</code> that do not begin with an underscore, i.e., 866<code>__test_func</code> would not be exported by default. Select 867exceptional symbols are allowed to be visible.</para></listitem> 868 </varlistentry> 869 870 <varlistentry> 871<term><code>namespace __gnu_cxx</code></term> 872<listitem><para> Defaults to not exporting any symbols in label 873<code>GLIBCXX</code>, select items are allowed to be visible.</para></listitem> 874 </varlistentry> 875 876 <varlistentry> 877<term><code>namespace __gnu_internal</code></term> 878<listitem><para> Defaults to not exported, no items are allowed to be visible.</para></listitem> 879 </varlistentry> 880 881 <varlistentry> 882<term><code>namespace __cxxabiv1</code>, aliased to <code> namespace abi</code></term> 883<listitem><para> Defaults to not exporting any symbols in label 884<code>CXXABI</code>, select items are allowed to be visible.</para></listitem> 885 </varlistentry> 886 887</variablelist> 888<para> 889</para> 890</listitem> 891 892 <listitem><para>Freezing the API</para> 893 <para>Disallowed changes, as above, are not made on a stable release 894branch. Enforcement tends to be less strict with GNU extensions that 895standard includes.</para> 896</listitem> 897</orderedlist> 898 899</section> 900 901<section xml:id="abi.testing"><info><title>Testing</title></info> 902 903 904 <section xml:id="abi.testing.single"><info><title>Single ABI Testing</title></info> 905 906 907 <para> 908 Testing for GNU C++ ABI changes is composed of two distinct 909 areas: testing the C++ compiler (g++) for compiler changes, and 910 testing the C++ library (libstdc++) for library changes. 911 </para> 912 913 <para> 914 Testing the C++ compiler ABI can be done various ways. 915 </para> 916 917 <para> 918 One. Intel ABI checker. 919 </para> 920 921<para> 922Two. 923The second is yet unreleased, but has been announced on the gcc 924mailing list. It is yet unspecified if these tools will be freely 925available, and able to be included in a GNU project. Please contact 926Mark Mitchell (mark@codesourcery.com) for more details, and current 927status. 928</para> 929 930<para> 931Three. 932Involves using the vlad.consistency test framework. This has also been 933discussed on the gcc mailing lists. 934</para> 935 936<para> 937Testing the C++ library ABI can also be done various ways. 938</para> 939 940<para> 941One. 942(Brendan Kehoe, Jeff Law suggestion to run 'make check-c++' two ways, 943one with a new compiler and an old library, and the other with an old 944compiler and a new library, and look for testsuite regressions) 945</para> 946 947<para> 948Details on how to set this kind of test up can be found here: 949http://gcc.gnu.org/ml/gcc/2002-08/msg00142.html 950</para> 951 952<para> 953Two. 954Use the 'make check-abi' rule in the libstdc++ Makefile. 955</para> 956 957<para> 958This is a proactive check of the library ABI. Currently, exported symbol 959names that are either weak or defined are checked against a last known 960good baseline. Currently, this baseline is keyed off of 3.4.0 961binaries, as this was the last time the .so number was incremented. In 962addition, all exported names are demangled, and the exported objects 963are checked to make sure they are the same size as the same object in 964the baseline. 965 966Notice that each baseline is relative to a <emphasis>default</emphasis> 967configured library and compiler: in particular, if options such as 968--enable-clocale, or --with-cpu, in case of multilibs, are used at 969configure time, the check may fail, either because of substantive 970differences or because of limitations of the current checking 971machinery. 972</para> 973 974<para> 975This dataset is insufficient, yet a start. Also needed is a 976comprehensive check for all user-visible types part of the standard 977library for sizeof() and alignof() changes. 978</para> 979 980<para> 981Verifying compatible layouts of objects is not even attempted. It 982should be possible to use sizeof, alignof, and offsetof to compute 983offsets for each structure and type in the standard library, saving to 984another datafile. Then, compute this in a similar way for new 985binaries, and look for differences. 986</para> 987 988<para> 989Another approach might be to use the -fdump-class-hierarchy flag to 990get information. However, currently this approach gives insufficient 991data for use in library testing, as class data members, their offsets, 992and other detailed data is not displayed with this flag. 993(See PR g++/7470 on how this was used to find bugs.) 994</para> 995 996<para> 997Perhaps there are other C++ ABI checkers. If so, please notify 998us. We'd like to know about them! 999</para> 1000 1001 </section> 1002 <section xml:id="abi.testing.multi"><info><title>Multiple ABI Testing</title></info> 1003 1004<para> 1005A "C" application, dynamically linked to two shared libraries, liba, 1006libb. The dependent library liba is a C++ shared library compiled with 1007GCC 3.3, and uses io, exceptions, locale, etc. The dependent library 1008libb is a C++ shared library compiled with GCC 3.4, and also uses io, 1009exceptions, locale, etc. 1010</para> 1011 1012<para> As above, libone is constructed as follows: </para> 1013<programlisting> 1014%$bld/H-x86-gcc-3.4.0/bin/g++ -fPIC -DPIC -c a.cc 1015 1016%$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 1017 1018%ln -s libone.so.1.0.0 libone.so 1019 1020%$bld/H-x86-gcc-3.4.0/bin/g++ -c a.cc 1021 1022%ar cru libone.a a.o 1023</programlisting> 1024 1025<para> And, libtwo is constructed as follows: </para> 1026 1027<programlisting> 1028%$bld/H-x86-gcc-3.3.3/bin/g++ -fPIC -DPIC -c b.cc 1029 1030%$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 1031 1032%ln -s libtwo.so.1.0.0 libtwo.so 1033 1034%$bld/H-x86-gcc-3.3.3/bin/g++ -c b.cc 1035 1036%ar cru libtwo.a b.o 1037</programlisting> 1038 1039<para> ...with the resulting libraries looking like </para> 1040 1041<screen> 1042<computeroutput> 1043%ldd libone.so.1.0.0 1044 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40016000) 1045 libm.so.6 => /lib/tls/libm.so.6 (0x400fa000) 1046 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x4011c000) 1047 libc.so.6 => /lib/tls/libc.so.6 (0x40125000) 1048 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 1049 1050%ldd libtwo.so.1.0.0 1051 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x40027000) 1052 libm.so.6 => /lib/tls/libm.so.6 (0x400e1000) 1053 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x40103000) 1054 libc.so.6 => /lib/tls/libc.so.6 (0x4010c000) 1055 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 1056</computeroutput> 1057</screen> 1058 1059<para> 1060 Then, the "C" compiler is used to compile a source file that uses 1061 functions from each library. 1062</para> 1063<programlisting> 1064gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.6 1065</programlisting> 1066 1067<para> 1068 Which gives the expected: 1069</para> 1070 1071<screen> 1072<computeroutput> 1073%ldd a.out 1074 libstdc++.so.5 => /usr/lib/libstdc++.so.5 (0x00764000) 1075 libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x40015000) 1076 libc.so.6 => /lib/tls/libc.so.6 (0x0036d000) 1077 libm.so.6 => /lib/tls/libm.so.6 (0x004a8000) 1078 libgcc_s.so.1 => /mnt/hd/bld/gcc/gcc/libgcc_s.so.1 (0x400e5000) 1079 /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x00355000) 1080</computeroutput> 1081</screen> 1082 1083<para> 1084 This resulting binary, when executed, will be able to safely use 1085 code from both liba, and the dependent libstdc++.so.6, and libb, 1086 with the dependent libstdc++.so.5. 1087</para> 1088 </section> 1089</section> 1090 1091<section xml:id="abi.issues"><info><title>Outstanding Issues</title></info> 1092 1093 1094<para> 1095 Some features in the C++ language make versioning especially 1096 difficult. In particular, compiler generated constructs such as 1097 implicit instantiations for templates, typeinfo information, and 1098 virtual tables all may cause ABI leakage across shared library 1099 boundaries. Because of this, mixing C++ ABIs is not recommended at 1100 this time. 1101</para> 1102 1103<para> 1104 For more background on this issue, see these bugzilla entries: 1105</para> 1106 1107<para> 1108<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/PR24660">24660: versioning weak symbols in libstdc++</link> 1109</para> 1110 1111<para> 1112<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> 1113</para> 1114 1115</section> 1116 1117<bibliography xml:id="abi.biblio"><info><title>Bibliography</title></info> 1118 1119 <biblioentry xml:id="biblio.abicheck"> 1120 <title> 1121 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1122 xlink:href="http://abicheck.sourceforge.net"> 1123 ABIcheck 1124 </link> 1125 </title> 1126 </biblioentry> 1127 1128 <biblioentry xml:id="biblio.cxxabi"> 1129 <title> 1130 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1131 xlink:href="https://itanium-cxx-abi.github.io/cxx-abi/"> 1132 Itanium C++ ABI 1133 </link> 1134 </title> 1135 </biblioentry> 1136 1137 1138 <biblioentry> 1139 <title> 1140 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1141 xlink:href="https://software.intel.com/en-us/articles/intel-compilers-for-linux-compatibility-with-gnu-compilers"> 1142 Intel Compilers for Linux: Compatibility with GNU Compilers 1143 </link> 1144 </title> 1145 </biblioentry> 1146 1147 <biblioentry> 1148 <title> 1149 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1150 xlink:href="https://docs.oracle.com/cd/E23824_01/html/819-0690/index.html"> 1151 Linker and Libraries Guide (document 819-0690) 1152 </link> 1153 </title> 1154 </biblioentry> 1155 1156 1157 <biblioentry> 1158 <title> 1159 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1160 xlink:href="https://docs.oracle.com/cd/E19422-01/819-3689/"> 1161 Sun Studio 11: C++ Migration Guide (document 819-3689) 1162 </link> 1163 </title> 1164 </biblioentry> 1165 1166 <biblioentry> 1167 <title> 1168 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1169 xlink:href="https://www.akkadia.org/drepper/dsohowto.pdf"> 1170 How to Write Shared Libraries 1171 </link> 1172 </title> 1173 1174 <author> 1175 <personname> 1176 <firstname>Ulrich</firstname><surname>Drepper</surname> 1177 </personname> 1178 </author> 1179 </biblioentry> 1180 1181 <biblioentry> 1182 <title> 1183 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1184 xlink:href="http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ihi0036b/index.html"> 1185 C++ ABI for the ARM Architecture 1186 </link> 1187 </title> 1188 </biblioentry> 1189 1190 <biblioentry> 1191 <title> 1192 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1193 xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1976.html"> 1194 Dynamic Shared Objects: Survey and Issues 1195 </link> 1196 </title> 1197 1198 <subtitle> 1199 ISO C++ J16/06-0046 1200 </subtitle> 1201 <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author> 1202 </biblioentry> 1203 1204 <biblioentry> 1205 <title> 1206 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1207 xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2013.html"> 1208 Versioning With Namespaces 1209 </link> 1210 </title> 1211 <subtitle> 1212 ISO C++ J16/06-0083 1213 </subtitle> 1214 <author><personname><firstname>Benjamin</firstname><surname>Kosnik</surname></personname></author> 1215 </biblioentry> 1216 1217 <biblioentry> 1218 <title> 1219 <link xmlns:xlink="http://www.w3.org/1999/xlink" 1220 xlink:href="http://syrcose.ispras.ru/2009/files/02_paper.pdf"> 1221 Binary Compatibility of Shared Libraries Implemented in C++ 1222 on GNU/Linux Systems 1223 </link> 1224 </title> 1225 1226 <subtitle> 1227 SYRCoSE 2009 1228 </subtitle> 1229 <author><personname><firstname>Pavel</firstname><surname>Shved</surname></personname></author> 1230 <author><personname><firstname>Denis</firstname><surname>Silakov</surname></personname></author> 1231 </biblioentry> 1232</bibliography> 1233 1234</section> 1235