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