Document libstdc++.so versioning in manual

	* doc/xml/manual/build_hacking.xml: New section on shared library
	versioning.

From-SVN: r239572

libstdc++-v3/ChangeLog

 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".

libstdc++-v3/doc/xml/manual/build_hacking.xml

@@ -399,6 +399,121 @@ in the build directory starts the build process. The <literal>all</literal> targ
 </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> <!-- configure -->
 
 <section xml:id="build_hacking.make"><info><title>Make</title></info>