Document libstdc++.so versioning in manual
* doc/xml/manual/build_hacking.xml: New section on shared library versioning. From-SVN: r239572
This commit is contained in:
Jonathan Wakely
Jonathan Wakely
parent
a8107a983f
commit
409d55557b
|
|
@ -1,5 +1,8 @@
|
|||
2016-08-18 Jonathan Wakely <jwakely@redhat.com>
|
||||
|
||||
* 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".
|
||||
|
|
|
|||
|
|
@ -398,6 +398,121 @@ in the build directory starts the build process. The <literal>all</literal> targ
|
|||
and an error message.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section xml:id="build_hacking.configure.version"><info><title>Shared Library Versioning</title></info>
|
||||
|
||||
<para>
|
||||
The <filename class="library">libstdc++.so</filename> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Dependent on the target supporting it, the library uses <link
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xlink:href="https://www.akkadia.org/drepper/symbol-versioning">ELF
|
||||
symbol versioning</link> for all exported symbols. The symbol versions
|
||||
are defined by a <link xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xlink:href="https://sourceware.org/binutils/docs/ld/VERSION.html">linker
|
||||
script</link> 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.
|
||||
</para>
|
||||
|
||||
<para> 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:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem><para>
|
||||
Edit <filename>acinclude.m4</filename> to update the "revision" value of
|
||||
<varname>libtool_VERSION</varname>, e.g. from <literal>6:22:0</literal>
|
||||
to <literal>6:23:0</literal>, which will cause the shared library to be
|
||||
built as <filename class="library">libstdc++.so.6.0.23</filename>.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>
|
||||
Regenerate the <filename>configure</filename> script by running the
|
||||
<command>autoreconf</command> tool from the correct version of the Autoconf
|
||||
package (as dictated by the <link xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xlink:href="https://gcc.gnu.org/install/prerequisites.html">GCC
|
||||
prerequisites</link>).
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>
|
||||
Edit the file <filename>config/abi/pre/gnu.ver</filename> to
|
||||
add a new version node after the last new node. The node name should be
|
||||
<literal>GLIBCXX_3.4.X</literal> where <literal>X</literal> is the new
|
||||
revision set in <filename>acinclude.m4</filename>, and the node should
|
||||
depend on the previous version e.g.
|
||||
<programlisting>
|
||||
GLIBCXX_3.4.23 {
|
||||
|
||||
} GLIBCXX_3.4.22;
|
||||
</programlisting>
|
||||
For symbols in the ABI runtime, libsupc++, the symbol version naming uses
|
||||
<literal>CXXABI_1.3.Y</literal> where <literal>Y</literal> increases
|
||||
monotonically with each new version. Again, the new node must depend on the
|
||||
previous version node e.g.
|
||||
<programlisting>
|
||||
CXXABI_1.3.11 {
|
||||
|
||||
} CXXABI_1.3.10;
|
||||
</programlisting>
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>
|
||||
In order for the <link linkend="test.run.variations">check-abi</link> test
|
||||
target to pass the testsuite must be updated to know about the new symbol
|
||||
version(s). Edit the file <filename>testsuite/util/testsuite_abi.cc</filename>
|
||||
file to add the new versions to the <varname>known_versions</varname> list,
|
||||
and update the checks for the latest versions that set the
|
||||
<varname>latestp</varname> variable).
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>
|
||||
Once the new symbol version has been added you can add the names of your new
|
||||
symbols in the new version node:
|
||||
<programlisting>
|
||||
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;
|
||||
</programlisting>
|
||||
You can either use mangled names, or demangled names inside an
|
||||
<literal>extern "C++"</literal> block. You might find that the new symbol
|
||||
matches an existing pattern in an old symbol version (causing the
|
||||
<literal>check-abi</literal> 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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
For an example of these steps, including adjusting old patterns to be less
|
||||
greedy, see <link xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xlink:href="https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html">https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html</link>
|
||||
and the attached patch.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
If it wasn't done for the last release, you might also need to regenerate
|
||||
the <filename>baseline_symbols.txt</filename> file that defines the set
|
||||
of expected symbols for old symbol versions. A new baseline file can be
|
||||
generated by running <userinput>make new-abi-baseline</userinput> in the
|
||||
<filename class="directory"><replaceable>libbuildir</replaceable>/testsuite</filename>
|
||||
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.
|
||||
</para>
|
||||
|
||||
</section>
|
||||
</section> <!-- configure -->
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue