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