[patch] New libstdc++ docs on testing and library versioning

[Jonathan Wakely]

I've been working on some changes to the libstdc++ manual recently.

A lot of the changes are just using DocBook markup with more semantic
meaning (e.g. <option> or <filename> instead of using <code> for
everything that should use a monospace font) but there are some
changes to content too.

I've added a new subsection documenting the steps needed to bump the
library version when adding new symbols, and rewritten the section on
writing testcases. The main reason for the latter is to encourage the
use of { dg-do run { target c++11 } } rather than the { dg-options
"-std=gnu++11" } approach used until now. I've also started
documenting the libstdc++-specific dg-require-SUPPORT directives
available for our tests.

The core of the new guidelines for writing tests is this:

[begin]
  Test cases that use features of a particular C++ standard should
  specify the minimum required standard as an effective target:

    // { dg-do run { target c++11 } }

  or

    // { dg-require-effective-target c++11 }

  Specifying the minimum required standard for a test allows it to be
  run using later standards, so that we can verify that C++11
  components still work correctly when compiled as C++14 or later.
  Specifying a minimum also means the test will be skipped if the test
  is compiled using an older standard, e.g. using
  RUNTESTFLAGS=--target_board=unix/-std=gnu++98. 

  It is possible to indicate that a test should /only/ be run for a
  specific standard (and not later standards) using an effective
  target like c++11_only. However, this means the test will be skipped
  by default (because the default mode is gnu++14), and so will only
  run when -std=gnu++11 or -std=c++11 is used explicitly. For tests
  that require a specific standard it is better to use a dg-options
  directive:

    // { dg-options "-std=gnu++11" }

  This means the test will not get skipped by default, and will always
  use the specific standard dialect that the test requires. This isn't
  needed often, and most tests should use an effective target to
  specify a minimum standard instead, to allow them to be tested for
  all possible variations.

  Similarly, tests which depend on a newer standard than the default
  should use dg-options instead of an effective target, so that they
  are not skipped by default. For example, tests for C++17 features
  should use

    // { dg-options "-std=gnu++17" }

  and not

    // { dg-do run "c++1z" }
[end]


I'd like to get feedback on this proposed change to how we write
tests, and any comments on the other doc changes are also welcome.

To make it easier to read them I've uploaded the generated HTML pages
to http://kayari.org/tmp/test.html and
http://kayari.org/tmp/appendix_porting.html#build_hacking.configure.version

The current versions of those pages are
https://gcc.gnu.org/onlinedocs/libstdc++/manual/test.html and
https://gcc.gnu.org/onlinedocs/libstdc++/manual/appendix_porting.html


-------------- next part --------------
A non-text attachment was scrubbed...
Name: patch.txt
Type: text/x-patch
Size: 63102 bytes
Desc: not available
URL: <http://gcc.gnu.org/pipermail/libstdc++/attachments/20160805/b17b94ef/attachment.bin>