From 409d55557baad029d590862b7958d34f18fb09a5 Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Thu, 18 Aug 2016 14:47:33 +0100 Subject: [PATCH] Document libstdc++.so versioning in manual * doc/xml/manual/build_hacking.xml: New section on shared library versioning. From-SVN: r239572 --- libstdc++-v3/ChangeLog | 3 + libstdc++-v3/doc/xml/manual/build_hacking.xml | 115 ++++++++++++++++++ 2 files changed, 118 insertions(+) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index a65d040e8c2..b6628023cf5 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,5 +1,8 @@ 2016-08-18 Jonathan Wakely + * doc/xml/manual/build_hacking.xml: New section on shared library + versioning. + * doc/xml/manual/build_hacking.xml: Improve markup. * doc/xml/manual/test.xml: Likewise. Change section title from "Test" to "Testing". diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml b/libstdc++-v3/doc/xml/manual/build_hacking.xml index 0bcd8791c6f..90489d18dd6 100644 --- a/libstdc++-v3/doc/xml/manual/build_hacking.xml +++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml @@ -398,6 +398,121 @@ in the build directory starts the build process. The all targ and an error message. + + +
Shared Library Versioning + + +The libstdc++.so shared library must +be carefully managed to maintain binary compatible with older versions +of the library. This ensures a new version of the library is still usable by +programs that were linked against an older version. + + + +Dependent on the target supporting it, the library uses ELF +symbol versioning for all exported symbols. The symbol versions +are defined by a linker +script that assigns a version to every symbol. +The set of symbols in each version is fixed when a GCC +release is made, and must not change after that. + + + When new symbols are added to the library they must be added +to a new symbol version, which must be created the first time new symbols +are added after a release. Adding a new symbol version involves the +following steps: + + + + +Edit acinclude.m4 to update the "revision" value of +libtool_VERSION, e.g. from 6:22:0 +to 6:23:0, which will cause the shared library to be +built as libstdc++.so.6.0.23. + + + +Regenerate the configure script by running the +autoreconf tool from the correct version of the Autoconf +package (as dictated by the GCC +prerequisites). + + + +Edit the file config/abi/pre/gnu.ver to +add a new version node after the last new node. The node name should be +GLIBCXX_3.4.X where X is the new +revision set in acinclude.m4, and the node should +depend on the previous version e.g. + + GLIBCXX_3.4.23 { + + } GLIBCXX_3.4.22; + +For symbols in the ABI runtime, libsupc++, the symbol version naming uses +CXXABI_1.3.Y where Y increases +monotonically with each new version. Again, the new node must depend on the +previous version node e.g. + + CXXABI_1.3.11 { + + } CXXABI_1.3.10; + + + + +In order for the check-abi test +target to pass the testsuite must be updated to know about the new symbol +version(s). Edit the file testsuite/util/testsuite_abi.cc +file to add the new versions to the known_versions list, +and update the checks for the latest versions that set the +latestp variable). + + + + + +Once the new symbol version has been added you can add the names of your new +symbols in the new version node: + + GLIBCXX_3.4.23 { + + # basic_string<C, T, A>::_Alloc_hider::_Alloc_hider(C*, A&&) + _ZNSt7__cxx1112basic_stringI[cw]St11char_traitsI[cw]ESaI[cw]EE12_Alloc_hiderC[12]EP[cw]OS3_; + + } GLIBCXX_3.4.22; + +You can either use mangled names, or demangled names inside an +extern "C++" block. You might find that the new symbol +matches an existing pattern in an old symbol version (causing the +check-abi test target to fail). If that happens then the +existing pattern must be adjusted to be more specific so that it doesn't +match the new symbol. + + + +For an example of these steps, including adjusting old patterns to be less +greedy, see https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html +and the attached patch. + + + +If it wasn't done for the last release, you might also need to regenerate +the baseline_symbols.txt file that defines the set +of expected symbols for old symbol versions. A new baseline file can be +generated by running make new-abi-baseline in the +libbuildir/testsuite +directory. Be sure to generate the baseline from a clean build using +unmodified sources, or you will incorporate your local changes into the +baseline file. + +
-- 2.30.2