ABI Policy and Guidelines

Configure

Storing Information in non-AC files (like configure.host)

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

Wouldn't it be nice if we could store that information in files 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.

Alas, writing macros like "AC_DEFINE(HAVE_A_NICE_DAY)" can only be done inside @@ -89,32 +89,37 @@ in the build directory starts the build process. The all

`Coding and Commenting Conventions`

Most comments should use {octothorpes, shibboleths, hash marks, - pound signs, whatever} rather than "dnl". Nearly all comments in - configure.ac should. Comments inside macros written in ancillary - .m4 files should. About the only comments which should - not use #, but use dnl instead, are comments - outside our own macros in the ancillary - files. The difference is that # comments show up in - configure (which is most helpful for debugging), - while dnl'd lines just vanish. Since the macros in ancillary - files generate code which appears in odd places, their "outside" - comments tend to not be useful while reading - configure. + pound signs, whatever} rather than "dnl". + Nearly all comments in configure.ac should. + Comments inside macros written in ancillary + .m4 files should. + About the only comments which should not + use #, but use dnl instead, + are comments outside our own macros in the ancillary + files. The difference is that # comments show up in + configure (which is most helpful for debugging), + while dnl'd lines just vanish. Since the macros + in ancillary files generate code which appears in odd places, + their "outside" comments tend to not be useful while reading + configure.

Do not use any $target* variables, such as - $target_alias. The single exception is in - configure.ac, for automake+dejagnu's sake. + $target_alias. The single exception is in + configure.ac, for automake+dejagnu's sake.

`The acinclude.m4 layout`

- The nice thing about acinclude.m4/aclocal.m4 is that macros aren't + The nice thing about + acinclude.m4/aclocal.m4 + is that macros aren't actually performed/called/expanded/whatever here, just loaded. So we can arrange the contents however we like. As of this writing, - acinclude.m4 is arranged as follows: + acinclude.m4 is arranged as follows:

     GLIBCXX_CHECK_HOST
     GLIBCXX_TOPREL_CONFIGURE
     GLIBCXX_CONFIGURE

- All the major variable "discovery" is done here. CXX, multilibs, + All the major variable "discovery" is done here. + CXX, multilibs, etc.

     fragments included from elsewhere
@@ -179,7 +184,8 @@ in the build directory starts the build process. The allGLIBCXX_ENABLE.  (You don't have to use
     it, but it's easy.)  The helper does two things for us:
   

-     Builds the call to the AC_ARG_ENABLE macro, with --help text
+     Builds the call to the AC_ARG_ENABLE macro, with
+     --help text
      properly quoted and aligned.  (Death to changequote!)
    

      Checks the result against a list of allowed possibilities, and
@@ -204,28 +210,32 @@ in the build directory starts the build process. The all

-     FEATURE is the string that follows --enable.  The results of the
-     test (such as it is) will be in the variable $enable_FEATURE,
-     where FEATURE has been squashed.  Example:
-     [extra-foo], controlled by the --enable-extra-foo
-     option and stored in $enable_extra_foo.
+     FEATURE is the string that follows
+     --enable.  The results of the
+     test (such as it is) will be in the variable
+     $enable_FEATURE,
+     where FEATURE has been squashed.  Example:
+     [extra-foo], controlled by the
+     --enable-extra-foo
+     option and stored in $enable_extra_foo.
    

-     DEFAULT is the value to store in $enable_FEATURE if the user does
-     not pass --enable/--disable.  It should be one of the permitted
-     values passed later.  Examples: [yes], or
-     [bar], or [$1] (which passes the
-     argument given to the GLIBCXX_ENABLE_FOO macro
-     as the default).
+     DEFAULT is the value to store in
+     $enable_FEATURE if the user does
+     not pass --enable/--disable.
+     It should be one of the permitted values passed later.
+     Examples: [yes], or [bar], or
+     [$1] (which passes the argument given to the
+     GLIBCXX_ENABLE_FOO macro as the default).
    

      For cases where we need to probe for particular models of things,
      it is useful to have an undocumented "auto" value here (see
      GLIBCXX_ENABLE_CLOCALE for an example).
    

-     HELP-ARG is any text to append to the option string itself in the
-     --help output.  Examples: [] (i.e., an empty string,
-     which appends nothing), [=BAR], which produces
-     --enable-extra-foo=BAR, and
-     [@<:@=BAR@:>@], which produces
+     HELP-ARG is any text to append to the option string
+     itself in the --help output.  Examples:
+     [] (i.e., an empty string, which appends nothing),
+     [=BAR], which produces --enable-extra-foo=BAR,
+     and [@<:@=BAR@:>@], which produces
      --enable-extra-foo[=BAR].  See the difference?  See
      what it implies to the user?
    

@@ -233,25 +243,29 @@ in the build directory starts the build process. The allquadrigraphs
      and you should use them whenever necessary.
- 
HELP-STRING is what you think it is.  Do not include the
+ 
HELP-STRING is what you think it is.  Do not include the
    "default" text like we used to do; it will be done for you by
-   GLIBCXX_ENABLE.  By convention, these are not full English
-   sentences.  Example: [turn on extra foo]
+   GLIBCXX_ENABLE.  By convention, these are not full English
+   sentences.  Example: [turn on extra foo]
    

   With no other arguments, only the standard autoconf patterns are
-  allowed: "--{enable,disable}-foo[={yes,no}]" The
-  $enable_FEATURE variable is guaranteed to equal either "yes" or "no"
+  allowed: "--{enable,disable}-foo[={yes,no}]" The
+  $enable_FEATURE variable is guaranteed to equal
+  either "yes" or "no"
   after the macro.  If the user tries to pass something else, an
   explanatory error message will be given, and configure will halt.
 

   The second signature takes a fifth argument, "[permit
   a | b | c | ...]"
   This allows a or b or
-  ... after the equals sign in the option, and $enable_FEATURE is
+  ... after the equals sign in the option, and
+  $enable_FEATURE is
   guaranteed to equal one of them after the macro.  Note that if you
-  want to allow plain --enable/--disable with no "=whatever", you must
-  include "yes" and "no" in the list of permitted values.  Also note
-  that whatever you passed as DEFAULT must be in the list.  If the
+  want to allow plain --enable/--disable
+  with no "=whatever", you must
+  include "yes" and "no" in the
+  list of permitted values.  Also note that whatever you passed as
+  DEFAULT must be in the list.  If the
   user tries to pass something not on the list, a semi-explanatory
   error message will be given, and configure will halt.  Example:
   [permit generic|gnu|ieee_1003.1-2001|yes|no|auto]
@@ -260,8 +274,91 @@ in the build directory starts the build process. The allGLIBCXX_ENABLE_CXX_FLAGS for an example of handling,
+  and an error message.
+
Shared Library Versioning

+The libstdc++.so 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.
+

+Dependent on the target supporting it, the library uses ELF
+symbol versioning for all exported symbols. The symbol versions
+are defined by a linker
+script 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.
+
 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:
+

+Edit acinclude.m4 to update the "revision" value of
+libtool_VERSION, e.g. from 6:22:0
+to 6:23:0, which will cause the shared library to be
+built as libstdc++.so.6.0.23.
+

+Regenerate the configure script by running the
+autoreconf tool from the correct version of the Autoconf
+package (as dictated by the GCC
+prerequisites).
+

+Edit the file config/abi/pre/gnu.ver to
+add a new version node after the last new node. The node name should be
+GLIBCXX_3.4.X where X is the new
+revision set in acinclude.m4, and the node should
+depend on the previous version e.g.
+
+    GLIBCXX_3.4.23 {
+
+    } GLIBCXX_3.4.22;
+

+For symbols in the ABI runtime, libsupc++, the symbol version naming uses
+CXXABI_1.3.Y where Y increases
+monotonically with each new version. Again, the new node must depend on the
+previous version node e.g.
+
+    CXXABI_1.3.11 {
+
+    } CXXABI_1.3.10;
+

+

+In order for the check-abi test
+target to pass the testsuite must be updated to know about the new symbol
+version(s). Edit the file testsuite/util/testsuite_abi.cc
+file to add the new versions to the known_versions list,
+and update the checks for the latest versions that set the
+latestp variable).
+

+Once the new symbol version has been added you can add the names of your new
+symbols in the new version node:
+
+    GLIBCXX_3.4.23 {
+
+      # basic_string<C, T, A>::_Alloc_hider::_Alloc_hider(C*, A&&)
+      _ZNSt7__cxx1112basic_stringI[cw]St11char_traitsI[cw]ESaI[cw]EE12_Alloc_hiderC[12]EP[cw]OS3_;
+
+    } GLIBCXX_3.4.22;
+

+You can either use mangled names, or demangled names inside an
+extern "C++" block. You might find that the new symbol
+matches an existing pattern in an old symbol version (causing the
+check-abi 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.
+

+For an example of these steps, including adjusting old patterns to be less
+greedy, see https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html
+and the attached patch.
+

+If it wasn't done for the last release, you might also need to regenerate
+the baseline_symbols.txt file that defines the set
+of expected symbols for old symbol versions. A new baseline file can be
+generated by running make new-abi-baseline in the
+libbuildir/testsuite
+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.

`Make`

The build process has to make all of object files needed for static or shared libraries, but first it has to generate some @@ -287,13 +384,13 @@ in the build directory starts the build process. The all

Generates a libtool convenience library, libc++98convenience with language-support - routines. Uses the -std=gnu++98 dialect. + routines. Uses the -std=gnu++98 dialect.

make src/c++11

Generates a libtool convenience library, libc++11convenience with language-support - routines. Uses the -std=gnu++11 dialect. + routines. Uses the -std=gnu++11 dialect.

make src

diff --git a/libstdc++-v3/doc/html/manual/index.html b/libstdc++-v3/doc/html/manual/index.html index 38d3ac3547e..8ce0b4b54b8 100644 --- a/libstdc++-v3/doc/html/manual/index.html +++ b/libstdc++-v3/doc/html/manual/index.html @@ -116,7 +116,7 @@

Porting to New Hardware or Operating Systems

PrevÂ

AppendixÂ B.Â +Porting to New Hardware or Operating Systems

Porting to New Hardware or Operating Systems
PrevÂ	AppendixÂ B.Â Porting and Maintenance	Â Next

Porting to New Hardware or Operating Systems

@@ -371,4 +371,4 @@ do this is to build the library using gcc -shared. ltcf-c.sh in the top-level directory. Find the switch statement that sets archive_cmds. Here, adjust the setting for your operating system. -

PrevÂ	Up	Â Next
Writing and Generating DocumentationÂ	Home	Â Test

\ No newline at end of file +

PrevÂ	Up	Â Next
Writing and Generating DocumentationÂ	Home	Â Testing

\ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/test.html b/libstdc++-v3/doc/html/manual/test.html index 893cf7242e3..9e5b64fa151 100644 --- a/libstdc++-v3/doc/html/manual/test.html +++ b/libstdc++-v3/doc/html/manual/test.html @@ -1,62 +1,62 @@ -Test

Test

PrevÂ

AppendixÂ B.Â +Testing

Testing
PrevÂ	AppendixÂ B.Â Porting and Maintenance -	Â Next

Test

Â Next

Testing

The libstdc++ testsuite includes testing for standard conformance, regressions, ABI, and performance. -

Organization

Directory Layout

- The directory libsrcdir/testsuite contains the - individual test cases organized in sub-directories corresponding to - clauses of the C++ standard (detailed below), the dejagnu test - harness support files, and sources to various testsuite utilities - that are packaged in a separate testing library. +

Test Organization

Directory Layout

+ The directory + gccsrcdir/libstdc++-v3/testsuite + contains the individual test cases organized in sub-directories + corresponding to clauses of the C++ standard (detailed below), + the DejaGnu test harness support files, and sources to various + testsuite utilities that are packaged in a separate testing library.

All test cases for functionality required by the runtime components of the C++ standard (ISO 14882) are files within the following - directories. -

-17_intro
-18_support
-19_diagnostics
-20_util
-21_strings
-22_locale
-23_containers
-25_algorithms
-26_numerics
-27_io
-28_regex
-29_atomics
-30_threads
-

- In addition, the following directories include test files: + directories: +

-tr1		  Tests for components as described by the Technical Report on Standard Library Extensions (TR1).
-backward	  Tests for backwards compatibility and deprecated features.
-demangle	  Tests for __cxa_demangle, the IA 64 C++ ABI demangler
-ext		  Tests for extensions.
-performance	  Tests for performance analysis, and performance regressions.
+    17_intro
+    18_support
+    19_diagnostics
+    20_util
+    21_strings
+    22_locale
+    23_containers
+    24_iterators
+    25_algorithms
+    26_numerics
+    27_io
+    28_regex
+    29_atomics
+    30_threads

+ In addition, the following directories include test files: + +

tr1: Tests for components as described by the Technical Report + on Standard Library Extensions (TR1). +
backward: Tests for backwards compatibility and deprecated features. +
demangle: Tests for __cxa_demangle, the IA-64 C++ ABI + demangler. +
ext: Tests for extensions.
performance: Tests for performance analysis, and performance regressions. +

Some directories don't have test files, but instead contain auxiliary information: -

-config		  Files for the dejagnu test harness.
-lib		  Files for the dejagnu test harness.
-libstdc++*     	  Files for the dejagnu test harness.
-data		  Sample text files for testing input and output.
-util		  Files for libtestc++, utilities and testing routines.
-

+ +

config: Files for the DejaGnu test harness.
lib: Files for the DejaGnu test harness.
libstdc++*: Files for the DejaGnu test harness.
data: Sample text files for testing input and output.
util: Files for libtestc++, utilities and testing routines.

Within a directory that includes test files, there may be additional subdirectories, or files. Originally, test cases were appended to one file that represented a particular section of the chapter under test, and was named accordingly. For instance, to test items related to 21.3.6.1 - - basic_string::find [lib.string::find] in the standard, - the following was used: -

-21_strings/find.cc
-

+ basic_string::find [lib.string::find] + in the standard, the following was used: +

    21_strings/find.cc

However, that practice soon became a liability as the test cases became huge and unwieldy, and testing new or extended functionality (like wide characters or named locales) became @@ -66,83 +66,77 @@ util Files for libtestc++, utilities and testing routines. above issues and gives finer grained results and more manageable error debugging. As an example, the test case quoted above becomes: -

-21_strings/basic_string/find/char/1.cc
-21_strings/basic_string/find/char/2.cc
-21_strings/basic_string/find/char/3.cc
-21_strings/basic_string/find/wchar_t/1.cc
-21_strings/basic_string/find/wchar_t/2.cc
-21_strings/basic_string/find/wchar_t/3.cc
-

- All new tests should be written with the policy of one test - case, one file in mind. +

    21_strings/basic_string/find/char/1.cc
+    21_strings/basic_string/find/char/2.cc
+    21_strings/basic_string/find/char/3.cc
+    21_strings/basic_string/find/wchar_t/1.cc
+    21_strings/basic_string/find/wchar_t/2.cc
+    21_strings/basic_string/find/wchar_t/3.cc

+ All new tests should be written with the policy of "one test + case, one file" in mind.

Naming Conventions

In addition, there are some special names and suffixes that are used within the testsuite to designate particular kinds of tests. -

- _xin.cc -

_xin.cc

This test case expects some kind of interactive input in order to finish or pass. At the moment, the interactive tests are not run by default. Instead, they are run by hand, like: -

+       g++ 27_io/objects/char/3_xin.cc
-cat 27_io/objects/char/3_xin.in | a.out
-

- .in -
+cat 27_io/objects/char/3_xin.in | a.out
.in
This file contains the expected input for the corresponding _xin.cc test case. -
- _neg.cc -
+
_neg.cc
This test case is expected to fail: it's a negative test. At the moment, these are almost always compile time errors. -
- char -
+
char
This can either be a directory name or part of a longer file name, and indicates that this file, or the files within this directory are testing the char instantiation of a template. -
- wchar_t -
+
wchar_t
This can either be a directory name or part of a longer file name, and indicates that this file, or the files within this directory are testing the wchar_t instantiation of a template. Some hosts do not support wchar_t functionality, so for these targets, all of these tests will not be run. -
- thread -
+
thread
This can either be a directory name or part of a longer file name, and indicates that this file, or the files within this directory are testing situations where multiple threads are being used. -
- performance -
+
performance
This can either be an enclosing directory name or part of a specific file name. This indicates a test that is used to analyze runtime performance, for performance regression testing, or for other optimization related analysis. At the moment, these test cases are not run by default. -

Running the Testsuite

Basic

Running the Testsuite

Basic

You can check the status of the build without installing it - using the dejagnu harness, much like the rest of the gcc - tools.

 make check

in the libbuilddir directory.

 make check-target-libstdc++-v3

in the gccbuilddir directory. -

+ using the DejaGnu harness, much like the rest of the gcc + tools, i.e. + make check + in the + libbuilddir + directory, or + make check-target-libstdc++-v3 + in the + gccbuilddir + directory. +

These commands are functionally equivalent and will create a - 'testsuite' directory underneath - libbuilddir containing the results of the - tests. Two results files will be generated: - libstdc++.sum, which is a PASS/FAIL summary for each - test, and libstdc++.log which is a log of - the exact command line passed to the compiler, the compiler - output, and the executable output (if any). + 'testsuite' directory underneath + libbuilddir + containing the results of the + tests. Two results files will be generated: + libstdc++.sum, which is a PASS/FAIL summary + for each test, and + libstdc++.log which is a log of + the exact command-line passed to the compiler, the compiler + output, and the executable output (if any) for each test.

Archives of test results for various versions and platforms are available on the GCC website in the build @@ -157,60 +151,74 @@ cat 27_io/objects/char/3_xin.in | a.out installed tools, etc. In addition, there is a special rule for checking the exported symbols of the shared library.

- To debug the dejagnu test harness during runs, try invoking with a - specific argument to the variable RUNTESTFLAGS, as below. -

-make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
+      To debug the DejaGnu test harness during runs, try invoking with a
+      specific argument to the variable RUNTESTFLAGS,
+      like so:
+
+    make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
 

       or
-    -make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
+
+    make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
 

+    

       To run a subset of the library tests, you can either generate the
-      testsuite_files file (described below) by running
-      make testsuite_files in the
-      libbuilddir/testsuite directory, then edit the
+      testsuite_files file (described below) by running
+      make testsuite_files in the
+      libbuilddir/testsuite
+      directory, then edit the
       file to remove the tests you don't want and then run the testsuite as
       normal, or you can specify a testsuite and a subset of tests in the
-      RUNTESTFLAGS variable.
+      RUNTESTFLAGS variable.
     

       For example, to run only the tests for containers you could use:
-    -make check-target-libstdc++-v3 RUNTESTFLAGS="conformance.exp=23_containers/*"
+
+
+    make check-target-libstdc++-v3 RUNTESTFLAGS="conformance.exp=23_containers/*"
 

-      When combining this with other options in RUNTESTFLAGS the
-      testsuite.exp=testfiles options must come first.
     

-      There are two ways to run on a simulator: set up DEJAGNU to point to a
-      specially crafted site.exp, or pass down --target_board flags.
+      When combining this with other options in RUNTESTFLAGS
+      the testsuite.exp=testfiles options must come first.
+    

+      There are two ways to run on a simulator: set up DEJAGNU
+      to point to a specially crafted site.exp,
+      or pass down --target_board flags.
     

     Example flags to pass down for various embedded builds are as follows:
-    -      --target=powerpc-eabism (libgloss/sim)
-make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
 
---target=calmrisc32 (libgloss/sid)
-make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
+
+  --target=powerpc-eabisim (libgloss/sim)
+  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
+
+  --target=calmrisc32 (libgloss/sid)
+  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
 
---target=xscale-elf (newlib/sim)
-make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
+  --target=xscale-elf (newlib/sim)
+  make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
 

+    

       Also, here is an example of how to run the libstdc++ testsuite
       for a multilibed build directory with different ABI settings:
-    -make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
+
+ 
+    make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board \"unix{-mabi=32,,-mabi=64}\"'
 

+    

       You can run the tests with a compiler and library that have
       already been installed.  Make sure that the compiler (e.g.,
-      g++) is in your PATH.  If you are
+      g++) is in your PATH.  If you are
       using shared libraries, then you must also ensure that the
       directory containing the shared version of libstdc++ is in your
-      LD_LIBRARY_PATH, or equivalent.  If your GCC source
-      tree is at /path/to/gcc, then you can run the tests
-      as follows:
-    -runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
+      LD_LIBRARY_PATH, or
+      equivalent.
+      If your GCC source tree is at
+      /path/to/gcc,
+      then you can run the tests as follows:
+
+
+    runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
 

+    

       The testsuite will create a number of files in the directory in
       which you run this command,.  Some of those files might use the
       same name as files created by other testsuites (like the ones
@@ -219,91 +227,142 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
     

       In addition, there are some testing options that are mostly of
       interest to library maintainers and system integrators. As such,
-      these tests may not work on all cpu and host combinations, and
+      these tests may not work on all CPU and host combinations, and
       may need to be executed in the
-      libbuilddir/testsuite directory.  These
+      libbuilddir/testsuite
+      directory.  These
       options include, but are not necessarily limited to, the
       following:
-   
+    

    make testsuite_files
-   

+   

     Five files are generated that determine what test files
     are run. These files are:
-  

-	 testsuite_files
-       

+
+    
 testsuite_files 

 	 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 libsrcdir/testsuite directory.
-       

-	 testsuite_files_interactive
-       

+	 from the
+         libsrcdir/testsuite
+         directory.
+      
 testsuite_files_interactive 

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

-	 testsuite_files_performance
-       

+      
 testsuite_files_performance 

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

-	 testsuite_thread
-       

+      
 testsuite_thread 

 	 This file indicates that the host system can run tests which
 	 involved multiple threads.
-       

-	 testsuite_wchar_t
-       

-	 This file indicates that the host system can run the wchar_t
-	 tests, and corresponds to the macro definition 
-	 _GLIBCXX_USE_WCHAR_T in the file c++config.h.
-

+       testsuite_wchar_t 

+	 This file indicates that the host system can run the
+         wchar_t tests, and corresponds to the macro
+         definition _GLIBCXX_USE_WCHAR_T in the
+         file c++config.h.
+

make check-abi -

+

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 Versioning for more details + of the ABI version history. +

+ make new-abi-baseline +

+ Generate a new baseline set of symbols exported from the library + (written to a file under + libsrcdir/config/abi/post/target/). + A different baseline symbols file is needed for each architecture and + is used by the check-abi target described above. + The files are usually re-generated by target maintainers for releases. +

make check-compile -

+

This rule compiles, but does not link or execute, the - testsuite_files test cases and displays the + testsuite_files test cases and displays the output on stdout. -

make check-performance -

+

This rule runs through the - testsuite_files_performance test cases and + testsuite_files_performance 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. -

+ make check-debug +

+ This rule runs through the test suite under the + debug mode. +

+ make check-parallel +

+ This rule runs through the test suite under the + parallel mode. +

We are interested in any strange failures of the testsuite; please email the main libstdc++ mailing list if you see something odd or have questions.

Permutations

- To run the libstdc++ test suite under the debug mode, edit - libstdc++-v3/scripts/testsuite_flags to add the - compile-time flag -D_GLIBCXX_DEBUG to the - result printed by the --build-cxx + The tests will be compiled with a set of default compiler flags defined + by the + libbuildir/scripts/testsuite_flags + file, as well as options specified in individual tests. You can run + the tests with different options by adding them to the output of + the --cxxflags option of that script, or by setting + the CXXFLAGS variable when running + make, or via options for the DejaGnu test framework + (described below). The latter approach uses the + --target_board option that was shown earlier. + For example, to run the tests with -O1 -D_GLIBCXX_ASSERT + you could use: +

    make RUNTESTFLAGS=--target_board=unix/-O1/-D_GLIBCXX_ASSERTIONS

+ The --target_board option can also be used to run the + tests multiple times in different variations. For example, to run the + entire testsuite three times using -O3 but with + different -std options: +

    make 'RUNTESTFLAGS=--target_board=unix/-O3\"{-std=gnu++98,-std=gnu++11,-std=gnu++14}\"'

+ N.B. that set of variations could also be written as + unix/-O3\"{-std=gnu++98,-std=gnu++11,}\" so that + the third variation would use the default for -std + (which is -std=gnu++14 as of GCC 6). +

+ To run the libstdc++ test suite under the + debug mode, use + make check-debug. Alternatively, edit + libbuildir/scripts/testsuite_flags + to add the compile-time flag -D_GLIBCXX_DEBUG to the + result printed by the --cxxflags option. Additionally, add the - -D_GLIBCXX_DEBUG_PEDANTIC flag to turn on + -D_GLIBCXX_DEBUG_PEDANTIC flag to turn on pedantic checking. The libstdc++ test suite should produce - precisely the same results under debug mode that it does under - release mode: any deviation indicates an error in either the - library or the test suite. + the same results under debug mode that it does under release mode: + any deviation indicates an error in either the library or the test suite. + Note, however, that the number of tests that PASS may change, because + some test cases are skipped in normal mode, and some are skipped in + debug mode, as determined by the + dg-require-support + directives described below.

The parallel - mode can be tested in much the same manner, substituting - -D_GLIBCXX_PARALLEL for - -D_GLIBCXX_DEBUG in the previous paragraph. + mode can be tested using + make check-parallel, or in much the same manner + as the debug mode, substituting + -D_GLIBCXX_PARALLEL for + -D_GLIBCXX_DEBUG in the previous paragraph.

- Or, just run the testsuites with CXXFLAGS - set to -D_GLIBCXX_DEBUG or - -D_GLIBCXX_PARALLEL. + Or, just run the testsuite + -D_GLIBCXX_DEBUG or -D_GLIBCXX_PARALLEL + in CXXFLAGS or RUNTESTFLAGS.

Writing a new test case

The first step in making a new test case is to choose the correct directory and file name, given the organization as previously @@ -311,10 +370,15 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite

All files are copyright the FSF, and GPL'd: this is very important. The first copyright year should correspond to the date - the file was checked in to SVN. + the file was checked in to version control. If a test is copied from + an existing file it should retain the copyright years from the + original file.

- As per the dejagnu instructions, always return 0 from main to - indicate success. + The DejaGnu instructions say to always return 0 + from main to indicate success. Strictly speaking + this is redundant in C++, since returning from main + is defined to return 0. Most tests still have an + explicit return.

A bunch of utility functions and classes have already been abstracted out into the testsuite utility library, @@ -322,108 +386,165 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite appropriate header file: the library or specific object files will automatically be linked in as part of the testsuite run.

- For a test that needs to take advantage of the dejagnu test - harness, what follows below is a list of special keyword that - harness uses. Basically, a test case contains dg-keywords (see - dg.exp) indicating what to do and what kinds of behavior are to be - expected. New test cases should be written with the new style - DejaGnu framework in mind. + Tests that need to perform runtime checks should use the + VERIFY macro, defined in the + <testsuite_hooks.h> header. + This usually expands to the standard assert macro, but + allows targets to define it to something different. In order to support + the alternative expansions of VERIFY, before any + use of the macro there must be a variable called test + in scope, which is usually defined like so (the attribute avoids + warnings about an unused variable): +

+    bool test __attribute__((unused)) = true;
+

- To ease transition, here is the list of dg-keyword documentation - lifted from dg.exp. -

-# The currently supported options are:
-#
-# dg-prms-id N
-#	set prms_id to N
-#
-# dg-options "options ..." [{ target selector }]
-#	specify special options to pass to the tool (eg: compiler)
-#
-# dg-do do-what-keyword [{ target/xfail selector }]
-#	`do-what-keyword' is tool specific and is passed unchanged to
-#	${tool}-dg-test.  An example is gcc where `keyword' can be any of:
-#	preprocess|compile|assemble|link|run
-#	and will do one of: produce a .i, produce a .s, produce a .o,
-#	produce an a.out, or produce an a.out and run it (the default is
-#	compile).
-#
-# dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate an error message <regexp> is expected on this line
-#	(the test fails if it doesn't occur)
-#	Linenum=0 for general tool messages (eg: -V arg missing).
-#	"." means the current line.
-#
-# dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate a warning message <regexp> is expected on this line
-#	(the test fails if it doesn't occur)
-#
-# dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate a bogus error message <regexp> use to occur here
-#	(the test fails if it does occur)
-#
-# dg-build regexp comment [{ target/xfail selector }]
-#	indicate the build use to fail for some reason
-#	(errors covered here include bad assembler generated, tool crashes,
-#	and link failures)
-#	(the test fails if it does occur)
-#
-# dg-excess-errors comment [{ target/xfail selector }]
-#	indicate excess errors are expected (any line)
-#	(this should only be used sparingly and temporarily)
-#
-# dg-output regexp [{ target selector }]
-#	indicate the expected output of the program is <regexp>
-#	(there may be multiple occurrences of this, they are concatenated)
-#
-# dg-final { tcl code }
-#	add some tcl code to be run at the end
-#	(there may be multiple occurrences of this, they are concatenated)
-#	(unbalanced braces must be \-escaped)
-#
-# "{ target selector }" is a list of expressions that determine whether the
-# test succeeds or fails for a particular target, or in some cases whether the
-# option applies for a particular target.  If the case of `dg-do' it specifies
-# whether the test case is even attempted on the specified target.
-#
-# The target selector is always optional.  The format is one of:
-#
-# { xfail *-*-* ... } - the test is expected to fail for the given targets
-# { target *-*-* ... } - the option only applies to the given targets
-#
-# At least one target must be specified, use *-*-* for "all targets".
-# At present it is not possible to specify both `xfail' and `target'.
-# "native" may be used in place of "*-*-*".
+    The testsuite uses the DejaGnu framework to compile and run the tests.
+    Test cases are normal C++ files which contain special directives in
+    comments.  These directives look like { dg-* ... }
+    and tell DejaGnu what to do and what kinds of behavior are to be expected
+    for a test.  The core DejaGnu directives are documented in the
+    dg.exp file installed by DejaGnu.
+    The GCC testsuites support additional directives
+    as described in the GCC internals documentation, see Syntax
+    and Descriptions of test directives. GCC also defines many 
+    Keywords describing target attributes (a.k.a effective targets)
+    which can be used where a target selector can
+    appear.
+  

+  Some directives commonly used in the libstdc++ testsuite are:
 
-Example 1: Testing compilation only
+
{ dg-do do-what-keyword [{ target/xfail selector }] }
Where do-what-keyword is usually
+    one of run (which is the default),
+    compile, or link,
+    and typical selectors are targets such as *-*-gnu*
+    or an effective target such as c++11.
+  
{ dg-require-support args }
Skip the test if the target does not provide the required support.
+    See below for values of support.
+  
{ dg-options options [{ target selector }] }
{ dg-error regexp [ comment [{ target/xfail selector } [line] ]] }
{ dg-excess-errors comment [{ target/xfail selector }] }

+  For full details of these and other directives see the main GCC DejaGnu
+  documentation in the internals manual.
+  

+    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" }

+  
Examples of Test Directives

+Example 1: Testing compilation only:
+
 // { dg-do compile }
+

 
-Example 2: Testing for expected warnings on line 36, which all targets fail
+Example 2: Testing for expected warnings on line 36, which all targets fail:
+
 // { dg-warning "string literals" "" { xfail *-*-* } 36 }
+

 
-Example 3: Testing for expected warnings on line 36
+Example 3: Testing for expected warnings on line 36:
+
 // { dg-warning "string literals" "" { target *-*-* } 36 }
+

 
-Example 4: Testing for compilation errors on line 41
+Example 4: Testing for compilation errors on line 41:
+
 // { dg-do compile }
 // { dg-error "no match for" "" { target *-*-* } 41 }
+

 
 Example 5: Testing with special command line settings, or without the
-use of pre-compiled headers, in particular the stdc++.h.gch file. Any
-options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set
-up in the normal.exp file.
+use of pre-compiled headers, in particular the
+stdc++.h.gch file. Any
+options here will override the DEFAULT_CXXFLAGS and
+PCH_CXXFLAGS set up in the normal.exp
+file:
+
 // { dg-options "-O0" { target *-*-* } }
 

-    More examples can be found in the libstdc++-v3/testsuite/*/*.cc files.
-   
Test Harness and Utilities
Dejagnu Harness Details

+
+Example 6: Compiling and linking a test only for C++14 and later, and only
+if Debug Mode is active:
+
+// { dg-do link { target c++14 } }
+// { dg-require-debug-mode "" }
+

+
+Example 7: Running a test only on x86 targets, and only for C++11 and later,
+with specific options, and additional options for 32-bit x86:
+
+// { dg-options "-fstrict-enums" }
+// { dg-additional-options "-march=i486" { target ia32 } }
+// { dg-do run { target { ia32 || x86_64-*-* } } }
+// { dg-require-effective-target "c++11" }
+

+   

+    More examples can be found in the
+    libstdc++-v3/testsuite/*/*.cc files.
+   
Directives Specific to Libstdc++ Tests

+    In addition to the usual Variants
+    of dg-require-support
+    several more directives are available for use in libstdc++ tests,
+    including the following:
+   
dg-require-namedlocale name
The named locale must be available.
+      
dg-require-debug-mode ""
Skip the test if the Debug Mode is not active
+	(as determined by the _GLIBCXX_DEBUG macro).
+      
dg-require-parallel-mode ""
Skip the test if the Parallel Mode is not active
+	(as determined by the _GLIBCXX_PARALLEL macro).
+      
dg-require-profile-mode ""
Skip the test if the Profile Mode is not active
+	(as determined by the _GLIBCXX_PROFILE macro).
+      
dg-require-normal-mode ""
Skip the test if any of Debug, Parallel or Profile
+	Mode is active.
+      
dg-require-atomic-builtins ""
Skip the test if atomic operations on bool
+      and int are not lock-free.
+      
dg-require-gthreads ""
Skip the test if the C++11 thread library is not
+      supported, as determined by the _GLIBCXX_HAS_GTHREADS
+      macro.
+      
dg-require-gthreads-timed ""
Skip the test if C++11 timed mutexes are not supported,
+      as determined by the _GLIBCXX_HAS_GTHREADS and
+      _GTHREAD_USE_MUTEX_TIMEDLOCK macros.
+      
dg-require-string-conversions ""
Skip the test if the C++11 to_string
+      and stoi, stod etc. functions
+      are not fully supported (including wide character versions).
+      
dg-require-filesystem-ts ""
Skip the test if the Filesystem TS is not supported.
+      
Test Harness and Utilities
DejaGnu Harness Details

     Underlying details of testing for conformance and regressions are
-    abstracted via the GNU Dejagnu package. This is similar to the
+    abstracted via the GNU DejaGnu package. This is similar to the
     rest of GCC.
   
This is information for those looking at making changes to the testsuite
-structure, and/or needing to trace dejagnu's actions with --verbose.  This
-will not be useful to people who are "merely" adding new tests to the existing
-structure.
-
The first key point when working with dejagnu is the idea of a "tool".
+structure, and/or needing to trace DejaGnu's actions with
+--verbose.
+This will not be useful to people who are "merely" adding new tests
+to the existing structure.
+
The first key point when working with DejaGnu is the idea of a "tool".
 Files, directories, and functions are all implicitly used when they are
 named after the tool in use.  Here, the tool will always be "libstdc++".
 
The lib subdir contains support routines.  The
@@ -433,7 +554,7 @@ be copied from the core compiler's support directory into lib
 
Some routines in lib/libstdc++.exp are callbacks, some are
 our own.  Callbacks must be prefixed with the name of the tool.  To easily
 distinguish the others, by convention our own routines are named "v3-*".
-
The next key point when working with dejagnu is "test files".  Any
+
The next key point when working with DejaGnu is "test files".  Any
 directory whose name starts with the tool name will be searched for test files.
 (We have only one.)  In those directories, any .exp file is
 considered a test file, and will be run in turn.  Our main test file is called
diff --git a/libstdc++-v3/doc/xml/manual/test.xml b/libstdc++-v3/doc/xml/manual/test.xml
index cbba3894786..39a67a1f6e2 100644
--- a/libstdc++-v3/doc/xml/manual/test.xml
+++ b/libstdc++-v3/doc/xml/manual/test.xml
@@ -554,29 +554,65 @@ cat 27_io/objects/char/3_xin.in | a.out
   
Permutations
     
     
-      To run the libstdc++ test suite under the debug mode, edit
-      libstdc++-v3/scripts/testsuite_flags to add the
-      compile-time flag -D_GLIBCXX_DEBUG to the
-      result printed by the --build-cxx
+      The tests will be compiled with a set of default compiler flags defined
+      by the
+      libbuildir/scripts/testsuite_flags
+      file, as well as options specified in individual tests. You can run
+      the tests with different options by adding them to the output of
+      the  option of that script, or by setting
+      the CXXFLAGS variable when running
+      make, or via options for the DejaGnu test framework
+      (described below). The latter approach uses the
+       option that was shown earlier.
+      For example, to run the tests with 
+      you could use:
+    make RUNTESTFLAGS=--target_board=unix/-O1/-D_GLIBCXX_ASSERTIONS
+    
+
+    
+      The  option can also be used to run the
+      tests multiple times in different variations. For example, to run the
+      entire testsuite three times using  but with
+      different  options:
+    make 'RUNTESTFLAGS=--target_board=unix/-O3\"{-std=gnu++98,-std=gnu++11,-std=gnu++14}\"'
+      N.B. that set of variations could also be written as
+      unix/-O3\"{-std=gnu++98,-std=gnu++11,}\" so that
+      the third variation would use the default for 
+      (which is  as of GCC 6).
+    
+
+    
+      To run the libstdc++ test suite under the
+      debug mode, use
+      make check-debug. Alternatively, edit
+      libbuildir/scripts/testsuite_flags
+      to add the compile-time flag  to the
+      result printed by the 
       option. Additionally, add the
-      -D_GLIBCXX_DEBUG_PEDANTIC flag to turn on
+       flag to turn on
       pedantic checking. The libstdc++ test suite should produce
-      precisely the same results under debug mode that it does under
-      release mode: any deviation indicates an error in either the
-      library or the test suite.
+      the same results under debug mode that it does under release mode:
+      any deviation indicates an error in either the library or the test suite.
+      Note, however, that the number of tests that PASS may change, because
+      some test cases are skipped in normal mode, and some are skipped in
+      debug mode, as determined by the
+      dg-require-support
+      directives described below.
     
 
     
       The parallel
-      mode can be tested in much the same manner, substituting
-      -D_GLIBCXX_PARALLEL for
-      -D_GLIBCXX_DEBUG in the previous paragraph.
+      mode can be tested using
+      make check-parallel, or in much the same manner
+      as the debug mode, substituting
+       for
+       in the previous paragraph.
     
 
     
-      Or, just run the testsuites with CXXFLAGS
-      set to -D_GLIBCXX_DEBUG or
-      -D_GLIBCXX_PARALLEL.
+      Or, just run the testsuite
+       or 
+      in CXXFLAGS or RUNTESTFLAGS.
     
   

 
@@ -593,12 +629,17 @@ cat 27_io/objects/char/3_xin.in | a.out
    
     All files are copyright the FSF, and GPL'd: this is very
     important.  The first copyright year should correspond to the date
-    the file was checked in to SVN.
+    the file was checked in to version control. If a test is copied from
+    an existing file it should retain the copyright years from the
+    original file.
    
 
    
-     As per the dejagnu instructions, always return 0 from main to
-     indicate success.
+     The DejaGnu instructions say to always return 0
+     from main to indicate success. Strictly speaking
+     this is redundant in C++, since returning from main
+     is defined to return 0. Most tests still have an
+     explicit return.
    
 
    
@@ -610,109 +651,238 @@ cat 27_io/objects/char/3_xin.in | a.out
    
 
    
-   For a test that needs to take advantage of the dejagnu test
-   harness, what follows below is a list of special keyword that
-   harness uses. Basically, a test case contains dg-keywords (see
-   dg.exp) indicating what to do and what kinds of behavior are to be
-   expected.  New test cases should be written with the new style
-   DejaGnu framework in mind.
+    Tests that need to perform runtime checks should use the
+    VERIFY macro, defined in the
+    <testsuite_hooks.h> header.
+    This usually expands to the standard assert macro, but
+    allows targets to define it to something different. In order to support
+    the alternative expansions of VERIFY, before any
+    use of the macro there must be a variable called test
+    in scope, which is usually defined like so (the attribute avoids
+    warnings about an unused variable):
+    
+    bool test __attribute__((unused)) = true;
+    
    
 
    
-    To ease transition, here is the list of dg-keyword documentation
-    lifted from dg.exp.
-   
+    The testsuite uses the DejaGnu framework to compile and run the tests.
+    Test cases are normal C++ files which contain special directives in
+    comments.  These directives look like { dg-* ... }
+    and tell DejaGnu what to do and what kinds of behavior are to be expected
+    for a test.  The core DejaGnu directives are documented in the
+    dg.exp file installed by DejaGnu.
+    The GCC testsuites support additional directives
+    as described in the GCC internals documentation, see Syntax
+    and Descriptions of test directives. GCC also defines many 
+    Keywords describing target attributes (a.k.a effective targets)
+    which can be used where a target selector can
+    appear.
+  
+
+  
+  Some directives commonly used in the libstdc++ testsuite are:
+
+
+
+  { dg-do do-what-keyword [{ target/xfail selector }] }
+  Where do-what-keyword is usually
+    one of run (which is the default),
+    compile, or link,
+    and typical selectors are targets such as *-*-gnu*
+    or an effective target such as c++11.
+  
+
+
+  { dg-require-support args }
+  Skip the test if the target does not provide the required support.
+    See below for values of support.
+  
+
+
+  { dg-options options [{ target selector }] }
+
+
+  { dg-error regexp [ comment [{ target/xfail selector } [line] ]] }
+
+
+  { dg-excess-errors comment [{ target/xfail selector }] }
+
+
+  For full details of these and other directives see the main GCC DejaGnu
+  documentation in the internals manual.
+  
+
+  
+    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
+    .
+  
+
+  
+    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
+     or  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" }
+  
 
+Examples of Test Directives
+
+   
+Example 1: Testing compilation only:
 
-# The currently supported options are:
-#
-# dg-prms-id N
-#	set prms_id to N
-#
-# dg-options "options ..." [{ target selector }]
-#	specify special options to pass to the tool (eg: compiler)
-#
-# dg-do do-what-keyword [{ target/xfail selector }]
-#	`do-what-keyword' is tool specific and is passed unchanged to
-#	${tool}-dg-test.  An example is gcc where `keyword' can be any of:
-#	preprocess|compile|assemble|link|run
-#	and will do one of: produce a .i, produce a .s, produce a .o,
-#	produce an a.out, or produce an a.out and run it (the default is
-#	compile).
-#
-# dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate an error message <regexp> is expected on this line
-#	(the test fails if it doesn't occur)
-#	Linenum=0 for general tool messages (eg: -V arg missing).
-#	"." means the current line.
-#
-# dg-warning regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate a warning message <regexp> is expected on this line
-#	(the test fails if it doesn't occur)
-#
-# dg-bogus regexp comment [{ target/xfail selector } [{.|0|linenum}]]
-#	indicate a bogus error message <regexp> use to occur here
-#	(the test fails if it does occur)
-#
-# dg-build regexp comment [{ target/xfail selector }]
-#	indicate the build use to fail for some reason
-#	(errors covered here include bad assembler generated, tool crashes,
-#	and link failures)
-#	(the test fails if it does occur)
-#
-# dg-excess-errors comment [{ target/xfail selector }]
-#	indicate excess errors are expected (any line)
-#	(this should only be used sparingly and temporarily)
-#
-# dg-output regexp [{ target selector }]
-#	indicate the expected output of the program is <regexp>
-#	(there may be multiple occurrences of this, they are concatenated)
-#
-# dg-final { tcl code }
-#	add some tcl code to be run at the end
-#	(there may be multiple occurrences of this, they are concatenated)
-#	(unbalanced braces must be \-escaped)
-#
-# "{ target selector }" is a list of expressions that determine whether the
-# test succeeds or fails for a particular target, or in some cases whether the
-# option applies for a particular target.  If the case of `dg-do' it specifies
-# whether the test case is even attempted on the specified target.
-#
-# The target selector is always optional.  The format is one of:
-#
-# { xfail *-*-* ... } - the test is expected to fail for the given targets
-# { target *-*-* ... } - the option only applies to the given targets
-#
-# At least one target must be specified, use *-*-* for "all targets".
-# At present it is not possible to specify both `xfail' and `target'.
-# "native" may be used in place of "*-*-*".
-
-Example 1: Testing compilation only
 // { dg-do compile }
+
 
-Example 2: Testing for expected warnings on line 36, which all targets fail
+Example 2: Testing for expected warnings on line 36, which all targets fail:
+
 // { dg-warning "string literals" "" { xfail *-*-* } 36 }
+
 
-Example 3: Testing for expected warnings on line 36
+Example 3: Testing for expected warnings on line 36:
+
 // { dg-warning "string literals" "" { target *-*-* } 36 }
+
 
-Example 4: Testing for compilation errors on line 41
+Example 4: Testing for compilation errors on line 41:
+
 // { dg-do compile }
 // { dg-error "no match for" "" { target *-*-* } 41 }
+
 
 Example 5: Testing with special command line settings, or without the
-use of pre-compiled headers, in particular the stdc++.h.gch file. Any
-options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set
-up in the normal.exp file.
+use of pre-compiled headers, in particular the
+stdc++.h.gch file. Any
+options here will override the DEFAULT_CXXFLAGS and
+PCH_CXXFLAGS set up in the normal.exp
+file:
+
 // { dg-options "-O0" { target *-*-* } }
 
 
+Example 6: Compiling and linking a test only for C++14 and later, and only
+if Debug Mode is active:
+
+// { dg-do link { target c++14 } }
+// { dg-require-debug-mode "" }
+
+
+Example 7: Running a test only on x86 targets, and only for C++11 and later,
+with specific options, and additional options for 32-bit x86:
+
+// { dg-options "-fstrict-enums" }
+// { dg-additional-options "-march=i486" { target ia32 } }
+// { dg-do run { target { ia32 || x86_64-*-* } } }
+// { dg-require-effective-target "c++11" }
+
+   
+
    
     More examples can be found in the
     libstdc++-v3/testsuite/*/*.cc files.
    
 
 
+Directives Specific to Libstdc++ Tests
+
+  
+    In addition to the usual Variants
+    of dg-require-support
+    several more directives are available for use in libstdc++ tests,
+    including the following:
+   
+
+  
+    dg-require-namedlocale name
+      The named locale must be available.
+      
+    
+    dg-require-debug-mode ""
+      Skip the test if the Debug Mode is not active
+	(as determined by the _GLIBCXX_DEBUG macro).
+      
+    
+    dg-require-parallel-mode ""
+      Skip the test if the Parallel Mode is not active
+	(as determined by the _GLIBCXX_PARALLEL macro).
+      
+    
+    dg-require-profile-mode ""
+      Skip the test if the Profile Mode is not active
+	(as determined by the _GLIBCXX_PROFILE macro).
+      
+    
+    dg-require-normal-mode ""
+      Skip the test if any of Debug, Parallel or Profile
+	Mode is active.
+      
+    
+    dg-require-atomic-builtins ""
+      Skip the test if atomic operations on bool
+      and int are not lock-free.
+      
+    
+    dg-require-gthreads ""
+      Skip the test if the C++11 thread library is not
+      supported, as determined by the _GLIBCXX_HAS_GTHREADS
+      macro.
+      
+    
+    dg-require-gthreads-timed ""
+      Skip the test if C++11 timed mutexes are not supported,
+      as determined by the _GLIBCXX_HAS_GTHREADS and
+      _GTHREAD_USE_MUTEX_TIMEDLOCK macros.
+      
+    
+    dg-require-string-conversions ""
+      Skip the test if the C++11 to_string
+      and stoi, stod etc. functions
+      are not fully supported (including wide character versions).
+      
+    
+    dg-require-filesystem-ts ""
+      Skip the test if the Filesystem TS is not supported.
+      
+    
+  
+
+
+
+
 
 Test Harness and Utilities
 
-- 
2.30.2