git
/
gcc
mirror of git://gcc.gnu.org/git/gcc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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 2016-08-18 14:47:33 +01:00 committed by Jonathan Wakely
parent a8107a983f
commit 409d55557b
2 changed files with 118 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
libstdc++-v3/ChangeLog
View File

@ -1,5 +1,8 @@
2016-08-18 Jonathan Wakely <jwakely@redhat.com> 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/build_hacking.xml: Improve markup.
* doc/xml/manual/test.xml: Likewise. Change section title from "Test" * doc/xml/manual/test.xml: Likewise. Change section title from "Test"
to "Testing". to "Testing".

115
libstdc++-v3/doc/xml/manual/build_hacking.xml
View File

@ -398,6 +398,121 @@ in the build directory starts the build process. The <literal>all</literal> targ
and an error message. and an error message.
</para> </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&lt;C, T, A&gt;::_Alloc_hider::_Alloc_hider(C*, A&amp;&amp;)
_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>
</section> <!-- configure --> </section> <!-- configure -->