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