Re: [patch] New libstdc++ docs on testing and library versioning
On 07/08/16 23:36 -0600, Sandra Loosemore wrote:
On 08/04/2016 06:37 PM, Jonathan Wakely wrote:
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. or instead of using 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.
[snip]
I tried to look over this patch and my eyes started glazing over
I suggest trying to separate the markup changes (possibly multiple
patches, for different kinds of changes) from the new content. From
my perspective, I think formatting cleanups and minor copy-editing can
go in under the obvious patch rule as long as you are satisfied with
the way it looks and have self-reviewed the patch to make sure you
didn't accidentally delete some chunk of text or introduce some other
unintended change.
The new material should be reviewed by someone knowledgeable enough to
catch problems with the content.
I've committed the changes as four patches, attached.
1 only changes markup.
Improve markup in libstdc++ manual
* doc/xml/manual/build_hacking.xml: Improve markup.
* doc/xml/manual/test.xml: Likewise. Change section title from "Test"
to "Testing".
* doc/xml/faq.xml: Change link text to "Testing".
2 adds the new section to the configure hacking docs.
Document libstdc++.so versioning in manual
* doc/xml/manual/build_hacking.xml: New section on shared library
versioning.
3 is mostly markup, but documents some more makefile targets from the
testsuite sub-dir.
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.
4 rewrites the docs on writing tests.
Expand libstdc++ docs on testing
* doc/xml/manual/test.xml (test.run.permutations): Expand section.
(test.new_tests): Rewrite section.
(tests.dg.directives): New section.
* doc/html/*: Regenerate.
The result of 2 is at:
https://gcc.gnu.org/onlinedocs/libstdc++/manual/appendix_porting.html#build_hacking.configure.version
And the result of 4 starts at:
https://gcc.gnu.org/onlinedocs/libstdc++/manual/test.html#test.run.permutations
The previous version was identical to:
https://gcc.gnu.org/onlinedocs/gcc-6.1.0/libstdc++/manual/manual/test.html#test.run.permutations
If anyone wants to review that content I'll happily make changes, but
I thought I'd go ahead and commit it. It's much easier to read the
HTML in a browser than to read patches against the Docbook XML.
commit 1305655217385a4b315236c83a0da7ba4e81ca3a
Author: Jonathan Wakely
Date: Thu Aug 18 14:04:24 2016 +0100
Improve markup in libstdc++ manual
* doc/xml/manual/build_hacking.xml: Improve markup.
* doc/xml/manual/test.xml: Likewise. Change section title from "Test"
to "Testing".
* doc/xml/faq.xml: Change link text to "Testing".
diff --git a/libstdc++-v3/doc/xml/faq.xml b/libstdc++-v3/doc/xml/faq.xml
index b24ee22..9466231 100644
--- a/libstdc++-v3/doc/xml/faq.xml
+++ b/libstdc++-v3/doc/xml/faq.xml
@@ -328,7 +328,7 @@
performance testing. Please consult the
http://www.w3.org/1999/xlink;
xlink:href="http://gcc.gnu.org/install/test.html;>testing
documentation for GCC and
-Test in the libstdc++
+Testing in the libstdc++
manual for more details.
diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml
b/libstdc++-v3/doc/xml/manual/build_hacking.xml
index 1b789d3..0bcd879 100644
--- a/libstdc++-v3/doc/xml/manual/build_hacking.xml
+++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml
@@ -93,7 +93,7 @@ in the build directory starts the build process. The
all targ
Regenerate all generated files by using the command
-autoreconf at the top level of the libstdc++ source
+autoreconf at the top level of the libstdc++ source
directory.
@@ -108,10 +108,10 @@ in the build directory starts the build process. The
all targ
-Until that glorious day when we can use AC_TRY_LINK with a
-cross-compiler, we have to hardcode the results of what the tests
+Until that glorious day when we can use AC_TRY_LINK
+with a cross-compiler, we have to hardcode the results of what the tests
would have shown if they could be run. So we have an inflexible
-mess like crossconfig.m4.
+mess like crossconfig.m4.
@@
Re: [patch] New libstdc++ docs on testing and library versioning
On 08/04/2016 06:37 PM, Jonathan Wakely wrote:
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. or instead of using 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.
[snip]
I tried to look over this patch and my eyes started glazing over
I suggest trying to separate the markup changes (possibly multiple
patches, for different kinds of changes) from the new content. From my
perspective, I think formatting cleanups and minor copy-editing can go
in under the obvious patch rule as long as you are satisfied with the
way it looks and have self-reviewed the patch to make sure you didn't
accidentally delete some chunk of text or introduce some other
unintended change.
The new material should be reviewed by someone knowledgeable enough to
catch problems with the content.
-Sandra
Re: [patch] New libstdc++ docs on testing and library versioning
On 05/08/16 01:37 +0100, Jonathan Wakely wrote:
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.
I forgot to say that this is the main reason for all the testsuite
work I've been doing for the last couple of weeks. We have hundreds of
tests using { dg-options "-std=gnu++11" } which means that we're not
testing huge chunks of the library with the default -std=gnu++14
option.
By using { dg-do what { target c++11 } } the default testsuite options
will run the test with the default -std setting, but we can optionally
also run them with -std=gnu++11, and -std=gnu++17, and other
variations (which I'm going to be doing nightly).
So I want the docs to describe how I think we should be writing tests.
[patch] New libstdc++ docs on testing and library versioning
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. or instead of using 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
commit 2315b0e19ce83875b1d8076b6faee74d4fc8bdbe
Author: Jonathan Wakely
Date: Thu Aug 4 22:08:42 2016 +0100
Improve libstdc++ docs on testing and library versioning
* doc/xml/manual/build_hacking.xml: Improve markup.
(build_hacking.configure.version):
New section on updating the library version.
* doc/xml/manual/test.xml: Improve markup.
(test.new_tests): Rewrite.
* doc/html/manual/*: Regenerate.
diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml b/libstdc++-v3/doc/xml/manual/build_hacking.xml
index 1b789d3..90489d1 100644
--- a/libstdc++-v3/doc/xml/manual/build_hacking.xml
+++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml
@@ -93,7 +93,7 @@ in the build directory starts the build process. The all targ
Regenerate all generated files by using the command
-autoreconf at the top level of the libstdc++ source
+autoreconf at the top level of the libstdc++ source
directory.
@@ -108,10 +108,10 @@ in the build directory starts the build process. The all targ
-Until that glorious day when we can use AC_TRY_LINK with a
-cross-compiler, we have to hardcode the results of what the tests
+Until that glorious day when we can use AC_TRY_LINK
+with a cross-compiler, we have to hardcode the results of what the tests
would have shown if they could be run. So we have an inflexible
-mess like crossconfig.m4.
+mess like crossconfig.m4.
@@ -119,8 +119,8 @@ in the build directory starts the build process. The all targ
like configure.host, which can be modified without needing to
regenerate anything, and can even be tweaked without really
knowing how the configury all works? Perhaps break the pieces of
-crossconfig.m4 out and place them in their appropriate
-config/{cpu,os} directory.
+crossconfig.m4 out and place them in their appropriate
+config/{cpu,os} directory.
@@ -141,33 +141,37 @@ in the build directory starts the build process. The all targ
Most comments should use {octothorpes,
