Improve documentation of libstdc++ test targets

	* doc/xml/manual/test.xml: Improve documentation of test targets.
	Document new-abi-baseline, check-debug, and check-parallel targets.

From-SVN: r239573

diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog
index b6628023cf527532199ff1a184c121376ee166ee..5acc88e029399ad1cb08eef1f969ea9f1c6cb194 100644 (file)
--- a/libstdc++-v3/ChangeLog
+++ b/libstdc++-v3/ChangeLog
@@ -1,5 +1,8 @@
 2016-08-18  Jonathan Wakely  <jwakely@redhat.com>
 
+       * doc/xml/manual/test.xml: Improve documentation of test targets.
+       Document new-abi-baseline, check-debug, and check-parallel targets.
+
        * doc/xml/manual/build_hacking.xml: New section on shared library
        versioning.
 

diff --git a/libstdc++-v3/doc/xml/manual/test.xml b/libstdc++-v3/doc/xml/manual/test.xml
index 740323ab57cb61a47a32d5023cd857d2a80392f8..cbba3894786c7eb5077408c903ab5ec52aa3be26 100644 (file)
--- a/libstdc++-v3/doc/xml/manual/test.xml
+++ b/libstdc++-v3/doc/xml/manual/test.xml
@@ -386,104 +386,163 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting>
       following:
     </para>
 
-   <programlisting>
+<variablelist>
+<varlistentry>
+   <term><userinput>
    make testsuite_files
-   </programlisting>
+   </userinput></term>>
 
+  <listitem>
   <para>
     Five files are generated that determine what test files
     are run. These files are:
-  </para>
 
-   <itemizedlist>
-     <listitem>
-       <para>
-        <emphasis>testsuite_files</emphasis>
-       </para>
-       <para>
+    <variablelist>
+    <varlistentry>
+      <term> <filename>testsuite_files</filename> </term>
+      <listitem>
         This is a list of all the test cases that will be run. Each
         test case is on a separate line, given with an absolute path
-        from the <emphasis>libsrcdir/testsuite</emphasis> directory.
-       </para>
-     </listitem>
-
-     <listitem>
-       <para>
-        <emphasis>testsuite_files_interactive</emphasis>
-       </para>
-       <para>
+        from the
+         <filename class="directory"><replaceable>libsrcdir</replaceable>/testsuite</filename>
+         directory.
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term> <filename>testsuite_files_interactive</filename> </term>
+      <listitem>
         This is a list of all the interactive test cases, using the
         same format as the file list above. These tests are not run
         by default.
-     </para>
-     </listitem>
+      </listitem>
+    </varlistentry>
 
-     <listitem>
-       <para>
-        <emphasis>testsuite_files_performance</emphasis>
-       </para>
-       <para>
+    <varlistentry>
+      <term> <filename>testsuite_files_performance</filename> </term>
+      <listitem>
         This is a list of all the performance test cases, using the
         same format as the file list above. These tests are not run
         by default.
-     </para>
-     </listitem>
+      </listitem>
+    </varlistentry>
 
-     <listitem>
-       <para>
-        <emphasis>testsuite_thread</emphasis>
-       </para>
-       <para>
+    <varlistentry>
+      <term> <filename>testsuite_thread</filename> </term>
+      <listitem>
         This file indicates that the host system can run tests which
         involved multiple threads.
-       </para>
-     </listitem>
-
-     <listitem>
-       <para>
-        <emphasis>testsuite_wchar_t</emphasis>
-       </para>
-       <para>
-        This file indicates that the host system can run the wchar_t
-        tests, and corresponds to the macro definition <code>
-        _GLIBCXX_USE_WCHAR_T</code> in the file c++config.h.
-       </para>
-     </listitem>
-    </itemizedlist>
+      </listitem>
+    </varlistentry>
+
+    <varlistentry>
+      <term> <filename>testsuite_wchar_t</filename> </term>
+      <listitem>
+        This file indicates that the host system can run the
+         <code>wchar_t</code> tests, and corresponds to the macro
+         definition <literal>_GLIBCXX_USE_WCHAR_T</literal> in the
+         file <filename>c++config.h</filename>.
+      </listitem>
+    </varlistentry>
+    </variablelist>
+  </para>
+  </listitem>
+</varlistentry>
 
-   <programlisting>
+<varlistentry>
+   <term><userinput>
    make check-abi
-   </programlisting>
+   </userinput></term>>
 
+   <listitem>
    <para>
      The library ABI can be tested. This involves testing the shared
-     library against an ABI-defining previous version of symbol
-     exports.
+     library against a baseline list of symbol exports that defines the
+     previous version of the ABI. The tests require that no exported
+     symbols are removed, no new symbols are added to the old symbol
+     versions, and any new symbols have the latest symbol version.
+     See <link linkend="abi.versioning">Versioning</link> for more details
+     of the ABI version history.
+   </para>
+   </listitem>
+</varlistentry>
+
+<varlistentry>
+   <term><userinput>
+   make new-abi-baseline
+   </userinput></term>>
+
+   <listitem>
+   <para>
+     Generate a new baseline set of symbols exported from the library
+     (written to a file under
+     <filename class="directory"><replaceable>libsrcdir</replaceable>/config/abi/post/<replaceable>target</replaceable>/</filename>).
+     A different baseline symbols file is needed for each architecture and
+     is used by the <literal>check-abi</literal> target described above.
+     The files are usually re-generated by target maintainers for releases.
    </para>
+   </listitem>
+</varlistentry>
 
-  <programlisting>
+<varlistentry>
+  <term><userinput>
    make check-compile
-  </programlisting>
+  </userinput></term>>
 
+   <listitem>
    <para>
      This rule compiles, but does not link or execute, the
-     <emphasis>testsuite_files</emphasis> test cases and displays the
+     <filename>testsuite_files</filename> test cases and displays the
      output on stdout.
    </para>
+   </listitem>
+</varlistentry>
 
-   <programlisting>
+<varlistentry>
+   <term><userinput>
    make check-performance
-   </programlisting>
+   </userinput></term>>
 
+   <listitem>
    <para>
      This rule runs through the
-     <emphasis>testsuite_files_performance</emphasis> test cases and
+     <filename>testsuite_files_performance</filename> test cases and
      collects information for performance analysis and can be used to
      spot performance regressions. Various timing information is
      collected, as well as number of hard page faults, and memory
      used. This is not run by default, and the implementation is in
      flux.
    </para>
+   </listitem>
+</varlistentry>
+
+<varlistentry>
+   <term><userinput>
+   make check-debug
+   </userinput></term>>
+
+   <listitem>
+   <para>
+     This rule runs through the test suite under the
+     <link linkend="manual.ext.debug_mode">debug mode</link>.
+   </para>
+   </listitem>
+</varlistentry>
+
+<varlistentry>
+   <term><userinput>
+   make check-parallel
+   </userinput></term>>
+
+   <listitem>
+   <para>
+     This rule runs through the test suite under the
+     <link linkend="manual.ext.parallel_mode">parallel mode</link>.
+   </para>
+   </listitem>
+</varlistentry>
+
+</variablelist>
 
    <para>
       We are interested in any strange failures of the testsuite;