Skip to content

R
riscv-gcc-1
Commit 0b224dcf by Jonathan Wakely Committed by Jonathan Wakely
Options

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.

From-SVN: r239574
parent b56d48ef
Showing with 804 additions and 411 deletions
libstdc++-v3/ChangeLog
2016-08-18 Jonathan Wakely <jwakely@redhat.com> 2016-08-18 Jonathan Wakely <jwakely@redhat.com>
* doc/xml/manual/test.xml (test.run.permutations): Expand section.
(test.new_tests): Rewrite section.
(tests.dg.directives): New section.
* doc/html/*: Regenerate.
* doc/xml/manual/test.xml: Improve documentation of test targets. * doc/xml/manual/test.xml: Improve documentation of test targets.
Document new-abi-baseline, check-debug, and check-parallel targets. Document new-abi-baseline, check-debug, and check-parallel targets.
......
libstdc++-v3/doc/html/faq.html
...@@ -281,7 +281,7 @@ ...@@ -281,7 +281,7 @@
performance testing. Please consult the performance testing. Please consult the
<a class="link" href="http://gcc.gnu.org/install/test.html" target="_top">testing <a class="link" href="http://gcc.gnu.org/install/test.html" target="_top">testing
documentation</a> for GCC and documentation</a> for GCC and
<a class="link" href="manual/test.html" title="Test">Test</a> in the libstdc++ <a class="link" href="manual/test.html" title="Testing">Testing</a> in the libstdc++
manual for more details. manual for more details.
</p><p> </p><p>
If you find bugs in the testsuite programs themselves, or if you If you find bugs in the testsuite programs themselves, or if you
......
libstdc++-v3/doc/html/index.html
...@@ -135,7 +135,7 @@ ...@@ -135,7 +135,7 @@
</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="manual/appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="manual/appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="manual/appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="manual/source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="manual/source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="manual/source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="manual/source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="manual/source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="manual/appendix_porting.html">B. </a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="manual/appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="manual/appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="manual/appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="manual/source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="manual/source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="manual/source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="manual/source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="manual/source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="manual/appendix_porting.html">B.
Porting and Maintenance Porting and Maintenance
</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="manual/documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="manual/documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="manual/documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="manual/internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="manual/internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html">Test</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.organization">Organization</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="manual/test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="manual/test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="manual/test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="section"><a href="manual/test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.harness.dejagnu">Dejagnu Harness Details</a></span></dt><dt><span class="section"><a href="manual/test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.exception.safety"> </a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.configure.version">Shared Library Versioning</a></span></dt></dl></dd><dt><span class="section"><a href="manual/appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="manual/documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="manual/documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="manual/documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="manual/documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="manual/internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="manual/internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="manual/internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html">Testing</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.organization">Test Organization</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="manual/test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="manual/test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="manual/test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html#test.new_tests">Writing a new test case</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#tests.dg.examples">Examples of Test Directives</a></span></dt><dt><span class="section"><a href="manual/test.html#tests.dg.directives">Directives Specific to Libstdc++ Tests</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.harness.dejagnu">DejaGnu Harness Details</a></span></dt><dt><span class="section"><a href="manual/test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="manual/test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.exception.safety">
Qualifying Exception Safety Guarantees Qualifying Exception Safety Guarantees
</a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="manual/test.html#test.exception.safety.status"> </a></span></dt><dd><dl><dt><span class="section"><a href="manual/test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="manual/test.html#test.exception.safety.status">
......
libstdc++-v3/doc/html/manual/abi.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ABI Policy and Guidelines</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="C++, ABI, version, dynamic, shared, compatibility" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="test.html" title="Test" /><link rel="next" href="api.html" title="API Evolution and Deprecation History" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ABI Policy and Guidelines</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="test.html">Prev</a> </td><th width="60%" align="center">Appendix B.  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>ABI Policy and Guidelines</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="C++, ABI, version, dynamic, shared, compatibility" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="test.html" title="Testing" /><link rel="next" href="api.html" title="API Evolution and Deprecation History" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">ABI Policy and Guidelines</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="test.html">Prev</a> </td><th width="60%" align="center">Appendix B. 
Porting and Maintenance Porting and Maintenance
</th><td width="20%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.abi"></a>ABI Policy and Guidelines</h2></div></div></div><p> </th><td width="20%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.abi"></a>ABI Policy and Guidelines</h2></div></div></div><p>
...@@ -532,4 +532,4 @@ gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so. ...@@ -532,4 +532,4 @@ gcc test.c -g -O2 -L. -lone -ltwo /usr/lib/libstdc++.so.5 /usr/lib/libstdc++.so.
</a> </a>
</em>. </span><span class="subtitle"> </em>. </span><span class="subtitle">
SYRCoSE 2009 SYRCoSE 2009
. </span><span class="author"><span class="firstname">Pavel</span> <span class="surname">Shved</span>. </span><span class="author"><span class="firstname">Denis</span> <span class="surname">Silakov</span>. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="test.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Test </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html> . </span><span class="author"><span class="firstname">Pavel</span> <span class="surname">Shved</span>. </span><span class="author"><span class="firstname">Denis</span> <span class="surname">Silakov</span>. </span></p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="test.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="api.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Testing </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> API Evolution and Deprecation History</td></tr></table></div></body></html>
\ No newline at end of file \ No newline at end of file
libstdc++-v3/doc/html/manual/appendix.html
...@@ -9,7 +9,7 @@ ...@@ -9,7 +9,7 @@
</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix_porting.html">B. </a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix_porting.html">B.
Porting and Maintenance Porting and Maintenance
</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Organization</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.harness.dejagnu">Dejagnu Harness Details</a></span></dt><dt><span class="section"><a href="test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety"> </a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.version">Shared Library Versioning</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Testing</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Test Organization</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#tests.dg.examples">Examples of Test Directives</a></span></dt><dt><span class="section"><a href="test.html#tests.dg.directives">Directives Specific to Libstdc++ Tests</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.harness.dejagnu">DejaGnu Harness Details</a></span></dt><dt><span class="section"><a href="test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety">
Qualifying Exception Safety Guarantees Qualifying Exception Safety Guarantees
</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.status"> </a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.status">
......
libstdc++-v3/doc/html/manual/appendix_porting.html
...@@ -7,7 +7,7 @@ ...@@ -7,7 +7,7 @@
</th><td width="20%" align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr></table><hr /></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.porting"></a> </th><td width="20%" align="right"> <a accesskey="n" href="documentation_hacking.html">Next</a></td></tr></table><hr /></div><div class="appendix"><div class="titlepage"><div><div><h1 class="title"><a id="appendix.porting"></a>
Porting and Maintenance Porting and Maintenance
<a id="id-1.3.6.3.1.1.1" class="indexterm"></a> <a id="id-1.3.6.3.1.1.1" class="indexterm"></a>
</h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Organization</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.harness.dejagnu">Dejagnu Harness Details</a></span></dt><dt><span class="section"><a href="test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety"> </h1></div></div></div><div class="toc"><p><strong>Table of Contents</strong></p><dl class="toc"><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.version">Shared Library Versioning</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Testing</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Test Organization</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#tests.dg.examples">Examples of Test Directives</a></span></dt><dt><span class="section"><a href="test.html#tests.dg.directives">Directives Specific to Libstdc++ Tests</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.harness.dejagnu">DejaGnu Harness Details</a></span></dt><dt><span class="section"><a href="test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety">
Qualifying Exception Safety Guarantees Qualifying Exception Safety Guarantees
</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.status"> </a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.status">
...@@ -63,20 +63,20 @@ in the build directory starts the build process. The <code class="literal">all</ ...@@ -63,20 +63,20 @@ in the build directory starts the build process. The <code class="literal">all</
<code class="filename">Makefile.am</code>. <code class="filename">Makefile.am</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.overview.map"></a>What Comes from Where</h4></div></div></div><div class="figure"><a id="fig.build_hacking.deps"></a><p class="title"><strong>Figure B.1. Configure and Build File Dependencies</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="../images/confdeps.png" align="middle" alt="Dependency Graph for Configure and Build Files" /></div></div></div><br class="figure-break" /><p> </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.overview.map"></a>What Comes from Where</h4></div></div></div><div class="figure"><a id="fig.build_hacking.deps"></a><p class="title"><strong>Figure B.1. Configure and Build File Dependencies</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="../images/confdeps.png" align="middle" alt="Dependency Graph for Configure and Build Files" /></div></div></div><br class="figure-break" /><p>
Regenerate all generated files by using the command Regenerate all generated files by using the command
<code class="code">autoreconf</code> at the top level of the libstdc++ source <span class="command"><strong>autoreconf</strong></span> at the top level of the libstdc++ source
directory. directory.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.configure"></a>Configure</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.scripts"></a>Storing Information in non-AC files (like configure.host)</h4></div></div></div><p> </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.configure"></a>Configure</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.scripts"></a>Storing Information in non-AC files (like configure.host)</h4></div></div></div><p>
Until that glorious day when we can use AC_TRY_LINK with a Until that glorious day when we can use <code class="literal">AC_TRY_LINK</code>
cross-compiler, we have to hardcode the results of what the tests 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 would have shown if they could be run. So we have an inflexible
mess like crossconfig.m4. mess like <code class="filename">crossconfig.m4</code>.
</p><p> </p><p>
Wouldn't it be nice if we could store that information in files Wouldn't it be nice if we could store that information in files
like configure.host, which can be modified without needing to like configure.host, which can be modified without needing to
regenerate anything, and can even be tweaked without really regenerate anything, and can even be tweaked without really
knowing how the configury all works? Perhaps break the pieces of knowing how the configury all works? Perhaps break the pieces of
crossconfig.m4 out and place them in their appropriate <code class="filename">crossconfig.m4</code> out and place them in their appropriate
config/{cpu,os} directory. <code class="filename">config/{cpu,os}</code> directory.
</p><p> </p><p>
Alas, writing macros like Alas, writing macros like
"<code class="code">AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside "<code class="code">AC_DEFINE(HAVE_A_NICE_DAY)</code>" can only be done inside
...@@ -89,32 +89,37 @@ in the build directory starts the build process. The <code class="literal">all</ ...@@ -89,32 +89,37 @@ in the build directory starts the build process. The <code class="literal">all</
discourage that. discourage that.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.conventions"></a>Coding and Commenting Conventions</h4></div></div></div><p> </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.conventions"></a>Coding and Commenting Conventions</h4></div></div></div><p>
Most comments should use {octothorpes, shibboleths, hash marks, Most comments should use {octothorpes, shibboleths, hash marks,
pound signs, whatever} rather than "dnl". Nearly all comments in pound signs, whatever} rather than "<code class="literal">dnl</code>".
configure.ac should. Comments inside macros written in ancillary Nearly all comments in <code class="filename">configure.ac</code> should.
.m4 files should. About the only comments which should Comments inside macros written in ancillary
<span class="emphasis"><em>not</em></span> use #, but use dnl instead, are comments <code class="filename">.m4</code> files should.
<span class="emphasis"><em>outside</em></span> our own macros in the ancillary About the only comments which should <span class="emphasis"><em>not</em></span>
files. The difference is that # comments show up in use <code class="literal">#</code>, but use <code class="literal">dnl</code> instead,
<code class="code">configure</code> (which is most helpful for debugging), are comments <span class="emphasis"><em>outside</em></span> our own macros in the ancillary
while dnl'd lines just vanish. Since the macros in ancillary files. The difference is that <code class="literal">#</code> comments show up in
files generate code which appears in odd places, their "outside" <code class="filename">configure</code> (which is most helpful for debugging),
comments tend to not be useful while reading while <code class="literal">dnl</code>'d lines just vanish. Since the macros
<code class="code">configure</code>. in ancillary files generate code which appears in odd places,
their "outside" comments tend to not be useful while reading
<code class="filename">configure</code>.
</p><p> </p><p>
Do not use any <code class="code">$target*</code> variables, such as Do not use any <code class="code">$target*</code> variables, such as
<code class="code">$target_alias</code>. The single exception is in <code class="varname">$target_alias</code>. The single exception is in
configure.ac, for automake+dejagnu's sake. <code class="filename">configure.ac</code>, for automake+dejagnu's sake.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.acinclude"></a>The acinclude.m4 layout</h4></div></div></div><p> </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.acinclude"></a>The acinclude.m4 layout</h4></div></div></div><p>
The nice thing about acinclude.m4/aclocal.m4 is that macros aren't The nice thing about
<code class="filename">acinclude.m4</code>/<code class="filename">aclocal.m4</code>
is that macros aren't
actually performed/called/expanded/whatever here, just loaded. So actually performed/called/expanded/whatever here, just loaded. So
we can arrange the contents however we like. As of this writing, we can arrange the contents however we like. As of this writing,
acinclude.m4 is arranged as follows: <code class="filename">acinclude.m4</code> is arranged as follows:
</p><pre class="programlisting"> </p><pre class="programlisting">
GLIBCXX_CHECK_HOST GLIBCXX_CHECK_HOST
GLIBCXX_TOPREL_CONFIGURE GLIBCXX_TOPREL_CONFIGURE
GLIBCXX_CONFIGURE GLIBCXX_CONFIGURE
</pre><p> </pre><p>
All the major variable "discovery" is done here. CXX, multilibs, All the major variable "discovery" is done here.
<code class="varname">CXX</code>, multilibs,
etc. etc.
</p><pre class="programlisting"> </p><pre class="programlisting">
fragments included from elsewhere fragments included from elsewhere
...@@ -179,7 +184,8 @@ in the build directory starts the build process. The <code class="literal">all</ ...@@ -179,7 +184,8 @@ in the build directory starts the build process. The <code class="literal">all</
helper, <code class="literal">GLIBCXX_ENABLE</code>. (You don't have to use helper, <code class="literal">GLIBCXX_ENABLE</code>. (You don't have to use
it, but it's easy.) The helper does two things for us: it, but it's easy.) The helper does two things for us:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Builds the call to the <code class="literal">AC_ARG_ENABLE</code> macro, with --help text Builds the call to the <code class="literal">AC_ARG_ENABLE</code> macro, with
<code class="option">--help</code> text
properly quoted and aligned. (Death to changequote!) properly quoted and aligned. (Death to changequote!)
</p></li><li class="listitem"><p> </p></li><li class="listitem"><p>
Checks the result against a list of allowed possibilities, and Checks the result against a list of allowed possibilities, and
...@@ -204,28 +210,32 @@ in the build directory starts the build process. The <code class="literal">all</ ...@@ -204,28 +210,32 @@ in the build directory starts the build process. The <code class="literal">all</
GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c) GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, permit a|b|c)
GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER) GLIBCXX_ENABLE (FEATURE, DEFAULT, HELP-ARG, HELP-STRING, SHELL-CODE-HANDLER)
</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> </pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
FEATURE is the string that follows --enable. The results of the <code class="literal">FEATURE</code> is the string that follows
test (such as it is) will be in the variable $enable_FEATURE, <code class="option">--enable</code>. The results of the
where FEATURE has been squashed. Example: test (such as it is) will be in the variable
<code class="code">[extra-foo]</code>, controlled by the --enable-extra-foo <code class="varname">$enable_FEATURE</code>,
option and stored in $enable_extra_foo. where <code class="literal">FEATURE</code> has been squashed. Example:
<code class="code">[extra-foo]</code>, controlled by the
<code class="option">--enable-extra-foo</code>
option and stored in <code class="varname">$enable_extra_foo</code>.
</p></li><li class="listitem"><p> </p></li><li class="listitem"><p>
DEFAULT is the value to store in $enable_FEATURE if the user does <code class="literal">DEFAULT</code> is the value to store in
not pass --enable/--disable. It should be one of the permitted <code class="varname">$enable_FEATURE</code> if the user does
values passed later. Examples: <code class="code">[yes]</code>, or not pass <code class="option">--enable</code>/<code class="option">--disable</code>.
<code class="code">[bar]</code>, or <code class="code">[$1]</code> (which passes the It should be one of the permitted values passed later.
argument given to the <code class="literal">GLIBCXX_ENABLE_FOO</code> macro Examples: <code class="code">[yes]</code>, or <code class="code">[bar]</code>, or
as the default). <code class="code">[$1]</code> (which passes the argument given to the
<code class="literal">GLIBCXX_ENABLE_FOO</code> macro as the default).
</p><p> </p><p>
For cases where we need to probe for particular models of things, For cases where we need to probe for particular models of things,
it is useful to have an undocumented "auto" value here (see it is useful to have an undocumented "auto" value here (see
<code class="literal">GLIBCXX_ENABLE_CLOCALE</code> for an example). <code class="literal">GLIBCXX_ENABLE_CLOCALE</code> for an example).
</p></li><li class="listitem"><p> </p></li><li class="listitem"><p>
HELP-ARG is any text to append to the option string itself in the <code class="literal">HELP-ARG</code> is any text to append to the option string
--help output. Examples: <code class="code">[]</code> (i.e., an empty string, itself in the <code class="option">--help</code> output. Examples:
which appends nothing), <code class="code">[=BAR]</code>, which produces <code class="code">[]</code> (i.e., an empty string, which appends nothing),
<code class="code">--enable-extra-foo=BAR</code>, and <code class="code">[=BAR]</code>, which produces <code class="code">--enable-extra-foo=BAR</code>,
<code class="code">[@&lt;:@=BAR@:&gt;@]</code>, which produces and <code class="code">[@&lt;:@=BAR@:&gt;@]</code>, which produces
<code class="code">--enable-extra-foo[=BAR]</code>. See the difference? See <code class="code">--enable-extra-foo[=BAR]</code>. See the difference? See
what it implies to the user? what it implies to the user?
</p><p> </p><p>
...@@ -233,25 +243,29 @@ in the build directory starts the build process. The <code class="literal">all</ ...@@ -233,25 +243,29 @@ in the build directory starts the build process. The <code class="literal">all</
that's how you embed autoconf special characters in output text. that's how you embed autoconf special characters in output text.
They're called <a class="link" href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs" target="_top"><span class="emphasis"><em>quadrigraphs</em></span></a> They're called <a class="link" href="http://www.gnu.org/software/autoconf/manual/autoconf.html#Quadrigraphs" target="_top"><span class="emphasis"><em>quadrigraphs</em></span></a>
and you should use them whenever necessary. and you should use them whenever necessary.
</p></li><li class="listitem"><p>HELP-STRING is what you think it is. Do not include the </p></li><li class="listitem"><p><code class="literal">HELP-STRING</code> is what you think it is. Do not include the
"default" text like we used to do; it will be done for you by "default" text like we used to do; it will be done for you by
GLIBCXX_ENABLE. By convention, these are not full English <code class="literal">GLIBCXX_ENABLE</code>. By convention, these are not full English
sentences. Example: [turn on extra foo] sentences. Example: <code class="literal">[turn on extra foo]</code>
</p></li></ul></div><p> </p></li></ul></div><p>
With no other arguments, only the standard autoconf patterns are With no other arguments, only the standard autoconf patterns are
allowed: "<code class="code">--{enable,disable}-foo[={yes,no}]</code>" The allowed: "<code class="option">--{enable,disable}-foo[={yes,no}]</code>" The
$enable_FEATURE variable is guaranteed to equal either "yes" or "no" <code class="varname">$enable_FEATURE</code> variable is guaranteed to equal
either "<code class="literal">yes</code>" or "<code class="literal">no</code>"
after the macro. If the user tries to pass something else, an after the macro. If the user tries to pass something else, an
explanatory error message will be given, and configure will halt. explanatory error message will be given, and configure will halt.
</p><p> </p><p>
The second signature takes a fifth argument, "<code class="code">[permit The second signature takes a fifth argument, "<code class="code">[permit
a | b | c | ...]</code>" a | b | c | ...]</code>"
This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or This allows <span class="emphasis"><em>a</em></span> or <span class="emphasis"><em>b</em></span> or
... after the equals sign in the option, and $enable_FEATURE is ... after the equals sign in the option, and
<code class="varname">$enable_FEATURE</code> is
guaranteed to equal one of them after the macro. Note that if you guaranteed to equal one of them after the macro. Note that if you
want to allow plain --enable/--disable with no "=whatever", you must want to allow plain <code class="option">--enable</code>/<code class="option">--disable</code>
include "yes" and "no" in the list of permitted values. Also note with no "<code class="literal">=whatever</code>", you must
that whatever you passed as DEFAULT must be in the list. If the include "<code class="literal">yes</code>" and "<code class="literal">no</code>" in the
list of permitted values. Also note that whatever you passed as
<code class="literal">DEFAULT</code> must be in the list. If the
user tries to pass something not on the list, a semi-explanatory user tries to pass something not on the list, a semi-explanatory
error message will be given, and configure will halt. Example: error message will be given, and configure will halt. Example:
<code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code> <code class="code">[permit generic|gnu|ieee_1003.1-2001|yes|no|auto]</code>
...@@ -260,8 +274,91 @@ in the build directory starts the build process. The <code class="literal">all</ ...@@ -260,8 +274,91 @@ in the build directory starts the build process. The <code class="literal">all</
code to execute if the user actually passes the enable/disable code to execute if the user actually passes the enable/disable
option. (If the user does not, the default is used. Duh.) No option. (If the user does not, the default is used. Duh.) No
argument checking at all is done in this signature. See argument checking at all is done in this signature. See
GLIBCXX_ENABLE_CXX_FLAGS for an example of handling, and an error <code class="literal">GLIBCXX_ENABLE_CXX_FLAGS</code> for an example of handling,
message. and an error message.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="build_hacking.configure.version"></a>Shared Library Versioning</h4></div></div></div><p>
The <code class="filename">libstdc++.so</code> 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.
</p><p>
Dependent on the target supporting it, the library uses <a class="link" href="https://www.akkadia.org/drepper/symbol-versioning" target="_top">ELF
symbol versioning</a> for all exported symbols. The symbol versions
are defined by a <a class="link" href="https://sourceware.org/binutils/docs/ld/VERSION.html" target="_top">linker
script</a> 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.
</p><p> 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:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Edit <code class="filename">acinclude.m4</code> to update the "revision" value of
<code class="varname">libtool_VERSION</code>, e.g. from <code class="literal">6:22:0</code>
to <code class="literal">6:23:0</code>, which will cause the shared library to be
built as <code class="filename">libstdc++.so.6.0.23</code>.
</p></li><li class="listitem"><p>
Regenerate the <code class="filename">configure</code> script by running the
<span class="command"><strong>autoreconf</strong></span> tool from the correct version of the Autoconf
package (as dictated by the <a class="link" href="https://gcc.gnu.org/install/prerequisites.html" target="_top">GCC
prerequisites</a>).
</p></li><li class="listitem"><p>
Edit the file <code class="filename">config/abi/pre/gnu.ver</code> to
add a new version node after the last new node. The node name should be
<code class="literal">GLIBCXX_3.4.X</code> where <code class="literal">X</code> is the new
revision set in <code class="filename">acinclude.m4</code>, and the node should
depend on the previous version e.g.
</p><pre class="programlisting">
GLIBCXX_3.4.23 {
} GLIBCXX_3.4.22;
</pre><p>
For symbols in the ABI runtime, libsupc++, the symbol version naming uses
<code class="literal">CXXABI_1.3.Y</code> where <code class="literal">Y</code> increases
monotonically with each new version. Again, the new node must depend on the
previous version node e.g.
</p><pre class="programlisting">
CXXABI_1.3.11 {
} CXXABI_1.3.10;
</pre><p>
</p></li><li class="listitem"><p>
In order for the <a class="link" href="test.html#test.run.variations" title="Variations">check-abi</a> test
target to pass the testsuite must be updated to know about the new symbol
version(s). Edit the file <code class="filename">testsuite/util/testsuite_abi.cc</code>
file to add the new versions to the <code class="varname">known_versions</code> list,
and update the checks for the latest versions that set the
<code class="varname">latestp</code> variable).
</p></li></ul></div><p>
Once the new symbol version has been added you can add the names of your new
symbols in the new version node:
</p><pre class="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;
</pre><p>
You can either use mangled names, or demangled names inside an
<code class="literal">extern "C++"</code> block. You might find that the new symbol
matches an existing pattern in an old symbol version (causing the
<code class="literal">check-abi</code> 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.
</p><p>
For an example of these steps, including adjusting old patterns to be less
greedy, see <a class="link" href="https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html" target="_top">https://gcc.gnu.org/ml/gcc-patches/2016-07/msg01926.html</a>
and the attached patch.
</p><p>
If it wasn't done for the last release, you might also need to regenerate
the <code class="filename">baseline_symbols.txt</code> file that defines the set
of expected symbols for old symbol versions. A new baseline file can be
generated by running <strong class="userinput"><code>make new-abi-baseline</code></strong> in the
<code class="filename"><em class="replaceable"><code>libbuildir</code></em>/testsuite</code>
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.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.make"></a>Make</h3></div></div></div><p> </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="build_hacking.make"></a>Make</h3></div></div></div><p>
The build process has to make all of object files needed for The build process has to make all of object files needed for
static or shared libraries, but first it has to generate some static or shared libraries, but first it has to generate some
...@@ -287,13 +384,13 @@ in the build directory starts the build process. The <code class="literal">all</ ...@@ -287,13 +384,13 @@ in the build directory starts the build process. The <code class="literal">all</
</p><p> </p><p>
Generates a libtool convenience library, Generates a libtool convenience library,
<code class="filename">libc++98convenience</code> with language-support <code class="filename">libc++98convenience</code> with language-support
routines. Uses the <code class="literal">-std=gnu++98</code> dialect. routines. Uses the <code class="option">-std=gnu++98</code> dialect.
</p></li><li class="listitem"><p> </p></li><li class="listitem"><p>
make src/c++11 make src/c++11
</p><p> </p><p>
Generates a libtool convenience library, Generates a libtool convenience library,
<code class="filename">libc++11convenience</code> with language-support <code class="filename">libc++11convenience</code> with language-support
routines. Uses the <code class="literal">-std=gnu++11</code> dialect. routines. Uses the <code class="option">-std=gnu++11</code> dialect.
</p></li><li class="listitem"><p> </p></li><li class="listitem"><p>
make src make src
</p><p> </p><p>
......
libstdc++-v3/doc/html/manual/index.html
...@@ -116,7 +116,7 @@ ...@@ -116,7 +116,7 @@
</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix_porting.html">B. </a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#contrib.list">Contributor Checklist</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_contributing.html#list.reading">Reading</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.copyright">Assignment</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.getting">Getting Sources</a></span></dt><dt><span class="section"><a href="appendix_contributing.html#list.patches">Submitting Patches</a></span></dt></dl></dd><dt><span class="section"><a href="source_organization.html">Directory Layout and Source Conventions</a></span></dt><dt><span class="section"><a href="source_code_style.html">Coding Style</a></span></dt><dd><dl><dt><span class="section"><a href="source_code_style.html#coding_style.bad_identifiers">Bad Identifiers</a></span></dt><dt><span class="section"><a href="source_code_style.html#coding_style.example">By Example</a></span></dt></dl></dd><dt><span class="section"><a href="source_design_notes.html">Design Notes</a></span></dt></dl></dd><dt><span class="appendix"><a href="appendix_porting.html">B.
Porting and Maintenance Porting and Maintenance
</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Test</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Organization</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.harness.dejagnu">Dejagnu Harness Details</a></span></dt><dt><span class="section"><a href="test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety"> </a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#appendix.porting.build_hacking">Configure and Build Hacking</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview">Overview</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.basic">General Process</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.overview.map">What Comes from Where</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure">Configure</a></span></dt><dd><dl><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.scripts">Storing Information in non-AC files (like configure.host)</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.conventions">Coding and Commenting Conventions</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.acinclude">The acinclude.m4 layout</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.enable"><code class="constant">GLIBCXX_ENABLE</code>, the <code class="literal">--enable</code> maker</a></span></dt><dt><span class="section"><a href="appendix_porting.html#build_hacking.configure.version">Shared Library Versioning</a></span></dt></dl></dd><dt><span class="section"><a href="appendix_porting.html#build_hacking.make">Make</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html">Writing and Generating Documentation</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doc.intro">Introduction</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.generation">Generating Documentation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doc.doxygen">Doxygen</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#doxygen.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.rules">Generating the Doxygen Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#doxygen.markup">Markup</a></span></dt></dl></dd><dt><span class="section"><a href="documentation_hacking.html#doc.docbook">Docbook</a></span></dt><dd><dl><dt><span class="section"><a href="documentation_hacking.html#docbook.prereq">Prerequisites</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.rules">Generating the DocBook Files</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.debug">Debugging Generation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.validation">Editing and Validation</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.examples">File Organization and Basics</a></span></dt><dt><span class="section"><a href="documentation_hacking.html#docbook.markup">Markup By Example</a></span></dt></dl></dd></dl></dd><dt><span class="section"><a href="internals.html">Porting to New Hardware or Operating Systems</a></span></dt><dd><dl><dt><span class="section"><a href="internals.html#internals.os">Operating System</a></span></dt><dt><span class="section"><a href="internals.html#internals.cpu">CPU</a></span></dt><dt><span class="section"><a href="internals.html#internals.char_types">Character Types</a></span></dt><dt><span class="section"><a href="internals.html#internals.thread_safety">Thread Safety</a></span></dt><dt><span class="section"><a href="internals.html#internals.numeric_limits">Numeric Limits</a></span></dt><dt><span class="section"><a href="internals.html#internals.libtool">Libtool</a></span></dt></dl></dd><dt><span class="section"><a href="test.html">Testing</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization">Test Organization</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.organization.layout">Directory Layout</a></span></dt><dt><span class="section"><a href="test.html#test.organization.naming">Naming Conventions</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.run">Running the Testsuite</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.run.basic">Basic</a></span></dt><dt><span class="section"><a href="test.html#test.run.variations">Variations</a></span></dt><dt><span class="section"><a href="test.html#test.run.permutations">Permutations</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.new_tests">Writing a new test case</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#tests.dg.examples">Examples of Test Directives</a></span></dt><dt><span class="section"><a href="test.html#tests.dg.directives">Directives Specific to Libstdc++ Tests</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.harness">Test Harness and Utilities</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.harness.dejagnu">DejaGnu Harness Details</a></span></dt><dt><span class="section"><a href="test.html#test.harness.utils">Utilities</a></span></dt></dl></dd><dt><span class="section"><a href="test.html#test.special">Special Topics</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety">
Qualifying Exception Safety Guarantees Qualifying Exception Safety Guarantees
</a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.status"> </a></span></dt><dd><dl><dt><span class="section"><a href="test.html#test.exception.safety.overview">Overview</a></span></dt><dt><span class="section"><a href="test.html#test.exception.safety.status">
......
libstdc++-v3/doc/html/manual/internals.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Porting to New Hardware or Operating Systems</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, internals" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="documentation_hacking.html" title="Writing and Generating Documentation" /><link rel="next" href="test.html" title="Test" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Porting to New Hardware or Operating Systems</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="documentation_hacking.html">Prev</a> </td><th width="60%" align="center">Appendix B.  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Porting to New Hardware or Operating Systems</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, internals" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="documentation_hacking.html" title="Writing and Generating Documentation" /><link rel="next" href="test.html" title="Testing" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Porting to New Hardware or Operating Systems</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="documentation_hacking.html">Prev</a> </td><th width="60%" align="center">Appendix B. 
Porting and Maintenance Porting and Maintenance
</th><td width="20%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.internals"></a>Porting to New Hardware or Operating Systems</h2></div></div></div><p> </th><td width="20%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="appendix.porting.internals"></a>Porting to New Hardware or Operating Systems</h2></div></div></div><p>
...@@ -371,4 +371,4 @@ do this is to build the library using <code class="code">gcc -shared</code>. ...@@ -371,4 +371,4 @@ do this is to build the library using <code class="code">gcc -shared</code>.
<code class="code">ltcf-c.sh</code> in the top-level directory. Find the switch statement <code class="code">ltcf-c.sh</code> in the top-level directory. Find the switch statement
that sets <code class="code">archive_cmds</code>. Here, adjust the setting for your that sets <code class="code">archive_cmds</code>. Here, adjust the setting for your
operating system. operating system.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="documentation_hacking.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Writing and Generating Documentation </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Test</td></tr></table></div></body></html> </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="documentation_hacking.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_porting.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="test.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Writing and Generating Documentation </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Testing</td></tr></table></div></body></html>
\ No newline at end of file \ No newline at end of file
libstdc++-v3/doc/html/manual/test.html
<?xml version="1.0" encoding="UTF-8" standalone="no"?> <?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Test</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, test, testsuite, performance, conformance, ABI, exception safety" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="internals.html" title="Porting to New Hardware or Operating Systems" /><link rel="next" href="abi.html" title="ABI Policy and Guidelines" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Test</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="internals.html">Prev</a> </td><th width="60%" align="center">Appendix B.  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Testing</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, test, testsuite, performance, conformance, ABI, exception safety" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_porting.html" title="Appendix B.  Porting and Maintenance" /><link rel="prev" href="internals.html" title="Porting to New Hardware or Operating Systems" /><link rel="next" href="abi.html" title="ABI Policy and Guidelines" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Testing</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="internals.html">Prev</a> </td><th width="60%" align="center">Appendix B. 
Porting and Maintenance Porting and Maintenance
</th><td width="20%" align="right"> <a accesskey="n" href="abi.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.setup.test"></a>Test</h2></div></div></div><p> </th><td width="20%" align="right"> <a accesskey="n" href="abi.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="manual.intro.setup.test"></a>Testing</h2></div></div></div><p>
The libstdc++ testsuite includes testing for standard conformance, The libstdc++ testsuite includes testing for standard conformance,
regressions, ABI, and performance. regressions, ABI, and performance.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.organization"></a>Organization</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.organization.layout"></a>Directory Layout</h4></div></div></div><p> </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.organization"></a>Test Organization</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.organization.layout"></a>Directory Layout</h4></div></div></div><p>
The directory <span class="emphasis"><em>libsrcdir/testsuite</em></span> contains the The directory
individual test cases organized in sub-directories corresponding to <code class="filename"><em class="replaceable"><code>gccsrcdir</code></em>/libstdc++-v3/testsuite</code>
clauses of the C++ standard (detailed below), the dejagnu test contains the individual test cases organized in sub-directories
harness support files, and sources to various testsuite utilities corresponding to clauses of the C++ standard (detailed below),
that are packaged in a separate testing library. the DejaGnu test harness support files, and sources to various
testsuite utilities that are packaged in a separate testing library.
</p><p> </p><p>
All test cases for functionality required by the runtime components All test cases for functionality required by the runtime components
of the C++ standard (ISO 14882) are files within the following of the C++ standard (ISO 14882) are files within the following
directories. directories:
</p><pre class="programlisting">
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
</pre><p>
In addition, the following directories include test files:
</p><pre class="programlisting"> </p><pre class="programlisting">
tr1 Tests for components as described by the Technical Report on Standard Library Extensions (TR1). 17_intro
backward Tests for backwards compatibility and deprecated features. 18_support
demangle Tests for __cxa_demangle, the IA 64 C++ ABI demangler 19_diagnostics
ext Tests for extensions. 20_util
performance Tests for performance analysis, and performance regressions. 21_strings
22_locale
23_containers
24_iterators
25_algorithms
26_numerics
27_io
28_regex
29_atomics
30_threads
</pre><p> </pre><p>
</p><p>
In addition, the following directories include test files:
</p><div class="variablelist"><dl class="variablelist compact"><dt><span class="term"><code class="filename">tr1</code></span></dt><dd>Tests for components as described by the Technical Report
on Standard Library Extensions (TR1).
</dd><dt><span class="term"><code class="filename">backward</code></span></dt><dd>Tests for backwards compatibility and deprecated features.
</dd><dt><span class="term"><code class="filename">demangle</code></span></dt><dd>Tests for <code class="function">__cxa_demangle</code>, the IA-64 C++ ABI
demangler.
</dd><dt><span class="term"><code class="filename">ext</code></span></dt><dd>Tests for extensions.</dd><dt><span class="term"><code class="filename">performance</code></span></dt><dd>Tests for performance analysis, and performance regressions.
</dd></dl></div><p>
</p><p>
Some directories don't have test files, but instead contain Some directories don't have test files, but instead contain
auxiliary information: auxiliary information:
</p><pre class="programlisting">
config Files for the dejagnu test harness. </p><div class="variablelist"><dl class="variablelist compact"><dt><span class="term"><code class="filename">config</code></span></dt><dd>Files for the DejaGnu test harness.</dd><dt><span class="term"><code class="filename">lib</code></span></dt><dd>Files for the DejaGnu test harness.</dd><dt><span class="term"><code class="filename">libstdc++*</code></span></dt><dd>Files for the DejaGnu test harness.</dd><dt><span class="term"><code class="filename">data</code></span></dt><dd>Sample text files for testing input and output.</dd><dt><span class="term"><code class="filename">util</code></span></dt><dd>Files for libtestc++, utilities and testing routines.</dd></dl></div><p>
lib Files for the dejagnu test harness. </p><p>
libstdc++* Files for the dejagnu test harness.
data Sample text files for testing input and output.
util Files for libtestc++, utilities and testing routines.
</pre><p>
Within a directory that includes test files, there may be Within a directory that includes test files, there may be
additional subdirectories, or files. Originally, test cases additional subdirectories, or files. Originally, test cases
were appended to one file that represented a particular section were appended to one file that represented a particular section
of the chapter under test, and was named accordingly. For of the chapter under test, and was named accordingly. For
instance, to test items related to <code class="code"> 21.3.6.1 - instance, to test items related to <code class="code"> 21.3.6.1 -
basic_string::find [lib.string::find]</code> in the standard, <code class="function">basic_string::find</code> [lib.string::find]</code>
the following was used: in the standard, the following was used:
</p><pre class="programlisting"> </p><pre class="programlisting"> 21_strings/find.cc </pre><p>
21_strings/find.cc
</pre><p>
However, that practice soon became a liability as the test cases However, that practice soon became a liability as the test cases
became huge and unwieldy, and testing new or extended became huge and unwieldy, and testing new or extended
functionality (like wide characters or named locales) became functionality (like wide characters or named locales) became
...@@ -66,83 +66,77 @@ util Files for libtestc++, utilities and testing routines. ...@@ -66,83 +66,77 @@ util Files for libtestc++, utilities and testing routines.
above issues and gives finer grained results and more manageable above issues and gives finer grained results and more manageable
error debugging. As an example, the test case quoted above error debugging. As an example, the test case quoted above
becomes: becomes:
</p><pre class="programlisting"> </p><pre class="programlisting"> 21_strings/basic_string/find/char/1.cc
21_strings/basic_string/find/char/1.cc 21_strings/basic_string/find/char/2.cc
21_strings/basic_string/find/char/2.cc 21_strings/basic_string/find/char/3.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/1.cc 21_strings/basic_string/find/wchar_t/2.cc
21_strings/basic_string/find/wchar_t/2.cc 21_strings/basic_string/find/wchar_t/3.cc</pre><p>
21_strings/basic_string/find/wchar_t/3.cc </p><p>
</pre><p> All new tests should be written with the policy of "one test
All new tests should be written with the policy of one test case, one file" in mind.
case, one file in mind.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.organization.naming"></a>Naming Conventions</h4></div></div></div><p> </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.organization.naming"></a>Naming Conventions</h4></div></div></div><p>
In addition, there are some special names and suffixes that are In addition, there are some special names and suffixes that are
used within the testsuite to designate particular kinds of used within the testsuite to designate particular kinds of
tests. tests.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">_xin.cc</code></span></dt><dd>
<span class="emphasis"><em>_xin.cc</em></span>
</p><p>
This test case expects some kind of interactive input in order This test case expects some kind of interactive input in order
to finish or pass. At the moment, the interactive tests are not to finish or pass. At the moment, the interactive tests are not
run by default. Instead, they are run by hand, like: run by default. Instead, they are run by hand, like:
</p><pre class="programlisting"> <pre class="programlisting">
g++ 27_io/objects/char/3_xin.cc g++ 27_io/objects/char/3_xin.cc
cat 27_io/objects/char/3_xin.in | a.out cat 27_io/objects/char/3_xin.in | a.out</pre></dd><dt><span class="term"><code class="filename">.in</code></span></dt><dd>
</pre></li><li class="listitem"><p>
<span class="emphasis"><em>.in</em></span>
</p><p>
This file contains the expected input for the corresponding <span class="emphasis"><em> This file contains the expected input for the corresponding <span class="emphasis"><em>
_xin.cc</em></span> test case. _xin.cc</em></span> test case.
</p></li><li class="listitem"><p> </dd><dt><span class="term"><code class="filename">_neg.cc</code></span></dt><dd>
<span class="emphasis"><em>_neg.cc</em></span>
</p><p>
This test case is expected to fail: it's a negative test. At the This test case is expected to fail: it's a negative test. At the
moment, these are almost always compile time errors. moment, these are almost always compile time errors.
</p></li><li class="listitem"><p> </dd><dt><span class="term"><code class="filename">char</code></span></dt><dd>
<span class="emphasis"><em>char</em></span>
</p><p>
This can either be a directory name or part of a longer file This can either be a directory name or part of a longer file
name, and indicates that this file, or the files within this name, and indicates that this file, or the files within this
directory are testing the <code class="code">char</code> instantiation of a directory are testing the <code class="code">char</code> instantiation of a
template. template.
</p></li><li class="listitem"><p> </dd><dt><span class="term"><code class="filename">wchar_t</code></span></dt><dd>
<span class="emphasis"><em>wchar_t</em></span>
</p><p>
This can either be a directory name or part of a longer file This can either be a directory name or part of a longer file
name, and indicates that this file, or the files within this name, and indicates that this file, or the files within this
directory are testing the <code class="code">wchar_t</code> instantiation of directory are testing the <code class="code">wchar_t</code> instantiation of
a template. Some hosts do not support <code class="code">wchar_t</code> a template. Some hosts do not support <code class="code">wchar_t</code>
functionality, so for these targets, all of these tests will not functionality, so for these targets, all of these tests will not
be run. be run.
</p></li><li class="listitem"><p> </dd><dt><span class="term"><code class="filename">thread</code></span></dt><dd>
<span class="emphasis"><em>thread</em></span>
</p><p>
This can either be a directory name or part of a longer file This can either be a directory name or part of a longer file
name, and indicates that this file, or the files within this name, and indicates that this file, or the files within this
directory are testing situations where multiple threads are directory are testing situations where multiple threads are
being used. being used.
</p></li><li class="listitem"><p> </dd><dt><span class="term"><code class="filename">performance</code></span></dt><dd>
<span class="emphasis"><em>performance</em></span>
</p><p>
This can either be an enclosing directory name or part of a This can either be an enclosing directory name or part of a
specific file name. This indicates a test that is used to specific file name. This indicates a test that is used to
analyze runtime performance, for performance regression testing, analyze runtime performance, for performance regression testing,
or for other optimization related analysis. At the moment, these or for other optimization related analysis. At the moment, these
test cases are not run by default. test cases are not run by default.
</p></li></ul></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.run"></a>Running the Testsuite</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.run.basic"></a>Basic</h4></div></div></div><p> </dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.run"></a>Running the Testsuite</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.run.basic"></a>Basic</h4></div></div></div><p>
You can check the status of the build without installing it You can check the status of the build without installing it
using the dejagnu harness, much like the rest of the gcc using the DejaGnu harness, much like the rest of the gcc
tools.</p><pre class="programlisting"> make check</pre><p>in the <span class="emphasis"><em>libbuilddir</em></span> directory.</p><p>or</p><pre class="programlisting"> make check-target-libstdc++-v3</pre><p>in the <span class="emphasis"><em>gccbuilddir</em></span> directory. tools, i.e.
<strong class="userinput"><code>make check</code></strong>
in the
<code class="filename"><em class="replaceable"><code>libbuilddir</code></em></code>
directory, or
<strong class="userinput"><code>make check-target-libstdc++-v3</code></strong>
in the
<code class="filename"><em class="replaceable"><code>gccbuilddir</code></em></code>
directory.
</p><p> </p><p>
These commands are functionally equivalent and will create a These commands are functionally equivalent and will create a
'testsuite' directory underneath '<code class="filename">testsuite</code>' directory underneath
<span class="emphasis"><em>libbuilddir</em></span> containing the results of the <code class="filename"><em class="replaceable"><code>libbuilddir</code></em></code>
tests. Two results files will be generated: <span class="emphasis"><em> containing the results of the
libstdc++.sum</em></span>, which is a PASS/FAIL summary for each tests. Two results files will be generated:
test, and <span class="emphasis"><em>libstdc++.log</em></span> which is a log of <code class="filename">libstdc++.sum</code>, which is a PASS/FAIL summary
the exact command line passed to the compiler, the compiler for each test, and
output, and the executable output (if any). <code class="filename">libstdc++.log</code> 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.
</p><p> </p><p>
Archives of test results for various versions and platforms are Archives of test results for various versions and platforms are
available on the GCC website in the <a class="link" href="http://gcc.gnu.org/gcc-4.3/buildstat.html" target="_top">build available on the GCC website in the <a class="link" href="http://gcc.gnu.org/gcc-4.3/buildstat.html" target="_top">build
...@@ -157,60 +151,74 @@ cat 27_io/objects/char/3_xin.in | a.out ...@@ -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 installed tools, etc. In addition, there is a special rule for
checking the exported symbols of the shared library. checking the exported symbols of the shared library.
</p><p> </p><p>
To debug the dejagnu test harness during runs, try invoking with a To debug the DejaGnu test harness during runs, try invoking with a
specific argument to the variable RUNTESTFLAGS, as below. specific argument to the variable <code class="varname">RUNTESTFLAGS</code>,
</p><pre class="programlisting"> like so:
make check-target-libstdc++-v3 RUNTESTFLAGS="-v" </p><pre class="programlisting">
make check-target-libstdc++-v3 RUNTESTFLAGS="-v"
</pre><p> </pre><p>
or or
</p><pre class="programlisting"> </p><pre class="programlisting">
make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v" make check-target-libstdc++-v3 RUNTESTFLAGS="-v -v"
</pre><p> </pre><p>
</p><p>
To run a subset of the library tests, you can either generate the To run a subset of the library tests, you can either generate the
<span class="emphasis"><em>testsuite_files</em></span> file (described below) by running <code class="filename">testsuite_files</code> file (described below) by running
<span class="command"><strong>make testsuite_files</strong></span> in the <strong class="userinput"><code>make testsuite_files</code></strong> in the
<span class="emphasis"><em>libbuilddir/testsuite</em></span> directory, then edit the <code class="filename"><em class="replaceable"><code>libbuilddir</code></em>/testsuite</code>
directory, then edit the
file to remove the tests you don't want and then run the testsuite as 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 normal, or you can specify a testsuite and a subset of tests in the
RUNTESTFLAGS variable. <code class="varname">RUNTESTFLAGS</code> variable.
</p><p> </p><p>
For example, to run only the tests for containers you could use: For example, to run only the tests for containers you could use:
</p><pre class="programlisting">
make check-target-libstdc++-v3 RUNTESTFLAGS="conformance.exp=23_containers/*" </p><pre class="programlisting">
make check-target-libstdc++-v3 RUNTESTFLAGS="conformance.exp=23_containers/*"
</pre><p> </pre><p>
When combining this with other options in RUNTESTFLAGS the
<span class="emphasis"><em>testsuite.exp=testfiles</em></span> options must come first.
</p><p> </p><p>
There are two ways to run on a simulator: set up DEJAGNU to point to a When combining this with other options in <code class="varname">RUNTESTFLAGS</code>
specially crafted site.exp, or pass down --target_board flags. the <code class="option">testsuite.exp=testfiles</code> options must come first.
</p><p>
There are two ways to run on a simulator: set up <code class="envar">DEJAGNU</code>
to point to a specially crafted <code class="filename">site.exp</code>,
or pass down <code class="option">--target_board</code> flags.
</p><p> </p><p>
Example flags to pass down for various embedded builds are as follows: Example flags to pass down for various embedded builds are as follows:
</p><pre class="programlisting">
--target=powerpc-eabism (libgloss/sim)
make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
--target=calmrisc32 (libgloss/sid) </p><pre class="programlisting">
make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid" --target=powerpc-eabisim <span class="emphasis"><em>(libgloss/sim)</em></span>
make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=powerpc-sim"
--target=calmrisc32 <span class="emphasis"><em>(libgloss/sid)</em></span>
make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=calmrisc32-sid"
--target=xscale-elf (newlib/sim) --target=xscale-elf <span class="emphasis"><em>(newlib/sim)</em></span>
make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim" make check-target-libstdc++-v3 RUNTESTFLAGS="--target_board=arm-sim"
</pre><p> </pre><p>
</p><p>
Also, here is an example of how to run the libstdc++ testsuite Also, here is an example of how to run the libstdc++ testsuite
for a multilibed build directory with different ABI settings: for a multilibed build directory with different ABI settings:
</p><pre class="programlisting"> </p><pre class="programlisting">
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}\"'
</pre><p> </pre><p>
</p><p>
You can run the tests with a compiler and library that have You can run the tests with a compiler and library that have
already been installed. Make sure that the compiler (e.g., already been installed. Make sure that the compiler (e.g.,
<code class="code">g++</code>) is in your <code class="code">PATH</code>. If you are <span class="command"><strong>g++</strong></span>) is in your <code class="envar">PATH</code>. If you are
using shared libraries, then you must also ensure that the using shared libraries, then you must also ensure that the
directory containing the shared version of libstdc++ is in your directory containing the shared version of libstdc++ is in your
<code class="code">LD_LIBRARY_PATH</code>, or equivalent. If your GCC source <code class="envar">LD_LIBRARY_PATH</code>, or
tree is at <code class="code">/path/to/gcc</code>, then you can run the tests <a class="link" href="using_dynamic_or_shared.html#manual.intro.using.linkage.dynamic" title="Finding Dynamic or Shared Libraries">equivalent</a>.
as follows: If your GCC source tree is at
</p><pre class="programlisting"> <code class="filename">/path/to/gcc</code>,
runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite then you can run the tests as follows:
</p><pre class="programlisting">
runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
</pre><p> </pre><p>
</p><p>
The testsuite will create a number of files in the directory in The testsuite will create a number of files in the directory in
which you run this command,. Some of those files might use the which you run this command,. Some of those files might use the
same name as files created by other testsuites (like the ones 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 ...@@ -219,91 +227,142 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
</p><p> </p><p>
In addition, there are some testing options that are mostly of In addition, there are some testing options that are mostly of
interest to library maintainers and system integrators. As such, 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 may need to be executed in the
<span class="emphasis"><em>libbuilddir/testsuite</em></span> directory. These <code class="filename"><em class="replaceable"><code>libbuilddir</code></em>/testsuite</code>
directory. These
options include, but are not necessarily limited to, the options include, but are not necessarily limited to, the
following: following:
</p><pre class="programlisting"> </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><strong class="userinput"><code>
make testsuite_files make testsuite_files
</pre><p> </code></strong></span></dt><dd><p>
Five files are generated that determine what test files Five files are generated that determine what test files
are run. These files are: are run. These files are:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
<span class="emphasis"><em>testsuite_files</em></span> </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> <code class="filename">testsuite_files</code> </span></dt><dd>
</p><p>
This is a list of all the test cases that will be run. Each 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 test case is on a separate line, given with an absolute path
from the <span class="emphasis"><em>libsrcdir/testsuite</em></span> directory. from the
</p></li><li class="listitem"><p> <code class="filename"><em class="replaceable"><code>libsrcdir</code></em>/testsuite</code>
<span class="emphasis"><em>testsuite_files_interactive</em></span> directory.
</p><p> </dd><dt><span class="term"> <code class="filename">testsuite_files_interactive</code> </span></dt><dd>
This is a list of all the interactive test cases, using the This is a list of all the interactive test cases, using the
same format as the file list above. These tests are not run same format as the file list above. These tests are not run
by default. by default.
</p></li><li class="listitem"><p> </dd><dt><span class="term"> <code class="filename">testsuite_files_performance</code> </span></dt><dd>
<span class="emphasis"><em>testsuite_files_performance</em></span>
</p><p>
This is a list of all the performance test cases, using the This is a list of all the performance test cases, using the
same format as the file list above. These tests are not run same format as the file list above. These tests are not run
by default. by default.
</p></li><li class="listitem"><p> </dd><dt><span class="term"> <code class="filename">testsuite_thread</code> </span></dt><dd>
<span class="emphasis"><em>testsuite_thread</em></span>
</p><p>
This file indicates that the host system can run tests which This file indicates that the host system can run tests which
involved multiple threads. involved multiple threads.
</p></li><li class="listitem"><p> </dd><dt><span class="term"> <code class="filename">testsuite_wchar_t</code> </span></dt><dd>
<span class="emphasis"><em>testsuite_wchar_t</em></span> This file indicates that the host system can run the
</p><p> <code class="code">wchar_t</code> tests, and corresponds to the macro
This file indicates that the host system can run the wchar_t definition <code class="literal">_GLIBCXX_USE_WCHAR_T</code> in the
tests, and corresponds to the macro definition <code class="code"> file <code class="filename">c++config.h</code>.
_GLIBCXX_USE_WCHAR_T</code> in the file c++config.h. </dd></dl></div><p>
</p></li></ul></div><pre class="programlisting"> </p></dd><dt><span class="term"><strong class="userinput"><code>
make check-abi make check-abi
</pre><p> </code></strong></span></dt><dd><p>
The library ABI can be tested. This involves testing the shared The library ABI can be tested. This involves testing the shared
library against an ABI-defining previous version of symbol library against a baseline list of symbol exports that defines the
exports. previous version of the ABI. The tests require that no exported
</p><pre class="programlisting"> symbols are removed, no new symbols are added to the old symbol
versions, and any new symbols have the latest symbol version.
See <a class="link" href="abi.html#abi.versioning" title="Versioning">Versioning</a> for more details
of the ABI version history.
</p></dd><dt><span class="term"><strong class="userinput"><code>
make new-abi-baseline
</code></strong></span></dt><dd><p>
Generate a new baseline set of symbols exported from the library
(written to a file under
<code class="filename"><em class="replaceable"><code>libsrcdir</code></em>/config/abi/post/<em class="replaceable"><code>target</code></em>/</code>).
A different baseline symbols file is needed for each architecture and
is used by the <code class="literal">check-abi</code> target described above.
The files are usually re-generated by target maintainers for releases.
</p></dd><dt><span class="term"><strong class="userinput"><code>
make check-compile make check-compile
</pre><p> </code></strong></span></dt><dd><p>
This rule compiles, but does not link or execute, the This rule compiles, but does not link or execute, the
<span class="emphasis"><em>testsuite_files</em></span> test cases and displays the <code class="filename">testsuite_files</code> test cases and displays the
output on stdout. output on stdout.
</p><pre class="programlisting"> </p></dd><dt><span class="term"><strong class="userinput"><code>
make check-performance make check-performance
</pre><p> </code></strong></span></dt><dd><p>
This rule runs through the This rule runs through the
<span class="emphasis"><em>testsuite_files_performance</em></span> test cases and <code class="filename">testsuite_files_performance</code> test cases and
collects information for performance analysis and can be used to collects information for performance analysis and can be used to
spot performance regressions. Various timing information is spot performance regressions. Various timing information is
collected, as well as number of hard page faults, and memory collected, as well as number of hard page faults, and memory
used. This is not run by default, and the implementation is in used. This is not run by default, and the implementation is in
flux. flux.
</p><p> </p></dd><dt><span class="term"><strong class="userinput"><code>
make check-debug
</code></strong></span></dt><dd><p>
This rule runs through the test suite under the
<a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>.
</p></dd><dt><span class="term"><strong class="userinput"><code>
make check-parallel
</code></strong></span></dt><dd><p>
This rule runs through the test suite under the
<a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel mode</a>.
</p></dd></dl></div><p>
We are interested in any strange failures of the testsuite; We are interested in any strange failures of the testsuite;
please email the main libstdc++ mailing list if you see please email the main libstdc++ mailing list if you see
something odd or have questions. something odd or have questions.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.run.permutations"></a>Permutations</h4></div></div></div><p> </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.run.permutations"></a>Permutations</h4></div></div></div><p>
To run the libstdc++ test suite under the <a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>, edit The tests will be compiled with a set of default compiler flags defined
<code class="filename">libstdc++-v3/scripts/testsuite_flags</code> to add the by the
compile-time flag <code class="constant">-D_GLIBCXX_DEBUG</code> to the <code class="filename"><em class="replaceable"><code>libbuildir</code></em>/scripts/testsuite_flags</code>
result printed by the <code class="literal">--build-cxx</code> 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 <code class="option">--cxxflags</code> option of that script, or by setting
the <code class="varname">CXXFLAGS</code> variable when running
<span class="command"><strong>make</strong></span>, or via options for the DejaGnu test framework
(described below). The latter approach uses the
<code class="option">--target_board</code> option that was shown earlier.
For example, to run the tests with <code class="option">-O1 -D_GLIBCXX_ASSERT</code>
you could use:
</p><pre class="programlisting"> make RUNTESTFLAGS=--target_board=unix/-O1/-D_GLIBCXX_ASSERTIONS</pre><p>
</p><p>
The <code class="option">--target_board</code> option can also be used to run the
tests multiple times in different variations. For example, to run the
entire testsuite three times using <code class="option">-O3</code> but with
different <code class="option">-std</code> options:
</p><pre class="programlisting"> make 'RUNTESTFLAGS=--target_board=unix/-O3\"{-std=gnu++98,-std=gnu++11,-std=gnu++14}\"'</pre><p>
N.B. that set of variations could also be written as
<code class="literal">unix/-O3\"{-std=gnu++98,-std=gnu++11,}\"</code> so that
the third variation would use the default for <code class="option">-std</code>
(which is <code class="option">-std=gnu++14</code> as of GCC 6).
</p><p>
To run the libstdc++ test suite under the
<a class="link" href="debug_mode.html" title="Chapter 17. Debug Mode">debug mode</a>, use
<strong class="userinput"><code>make check-debug</code></strong>. Alternatively, edit
<code class="filename"><em class="replaceable"><code>libbuildir</code></em>/scripts/testsuite_flags</code>
to add the compile-time flag <code class="option">-D_GLIBCXX_DEBUG</code> to the
result printed by the <code class="option">--cxxflags</code>
option. Additionally, add the option. Additionally, add the
<code class="constant">-D_GLIBCXX_DEBUG_PEDANTIC</code> flag to turn on <code class="option">-D_GLIBCXX_DEBUG_PEDANTIC</code> flag to turn on
pedantic checking. The libstdc++ test suite should produce pedantic checking. The libstdc++ test suite should produce
precisely the same results under debug mode that it does under the same results under debug mode that it does under release mode:
release mode: any deviation indicates an error in either the any deviation indicates an error in either the library or the test suite.
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
<code class="literal">dg-require-<em class="replaceable"><code>support</code></em></code>
directives described below.
</p><p> </p><p>
The <a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel The <a class="link" href="parallel_mode.html" title="Chapter 18. Parallel Mode">parallel
mode</a> can be tested in much the same manner, substituting mode</a> can be tested using
<code class="constant">-D_GLIBCXX_PARALLEL</code> for <strong class="userinput"><code>make check-parallel</code></strong>, or in much the same manner
<code class="constant">-D_GLIBCXX_DEBUG</code> in the previous paragraph. as the debug mode, substituting
</p><p> <code class="option">-D_GLIBCXX_PARALLEL</code> for
Or, just run the testsuites with <code class="constant">CXXFLAGS</code> <code class="option">-D_GLIBCXX_DEBUG</code> in the previous paragraph.
set to <code class="constant">-D_GLIBCXX_DEBUG</code> or </p><p>
<code class="constant">-D_GLIBCXX_PARALLEL</code>. Or, just run the testsuite
<code class="option">-D_GLIBCXX_DEBUG</code> or <code class="option">-D_GLIBCXX_PARALLEL</code>
in <code class="varname">CXXFLAGS</code> or <code class="varname">RUNTESTFLAGS</code>.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.new_tests"></a>Writing a new test case</h3></div></div></div><p> </p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.new_tests"></a>Writing a new test case</h3></div></div></div><p>
The first step in making a new test case is to choose the correct The first step in making a new test case is to choose the correct
directory and file name, given the organization as previously directory and file name, given the organization as previously
...@@ -311,10 +370,15 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite ...@@ -311,10 +370,15 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
</p><p> </p><p>
All files are copyright the FSF, and GPL'd: this is very All files are copyright the FSF, and GPL'd: this is very
important. The first copyright year should correspond to the date 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.
</p><p> </p><p>
As per the dejagnu instructions, always return 0 from main to The DejaGnu instructions say to always return <code class="literal">0</code>
indicate success. from <code class="function">main</code> to indicate success. Strictly speaking
this is redundant in C++, since returning from <code class="function">main</code>
is defined to return <code class="literal">0</code>. Most tests still have an
explicit return.
</p><p> </p><p>
A bunch of utility functions and classes have already been A bunch of utility functions and classes have already been
abstracted out into the testsuite utility library, <code class="code"> abstracted out into the testsuite utility library, <code class="code">
...@@ -322,108 +386,165 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite ...@@ -322,108 +386,165 @@ runtest --tool libstdc++ --srcdir=/path/to/gcc/libstdc++-v3/testsuite
appropriate header file: the library or specific object files will appropriate header file: the library or specific object files will
automatically be linked in as part of the testsuite run. automatically be linked in as part of the testsuite run.
</p><p> </p><p>
For a test that needs to take advantage of the dejagnu test Tests that need to perform runtime checks should use the
harness, what follows below is a list of special keyword that <code class="literal">VERIFY</code> macro, defined in the
harness uses. Basically, a test case contains dg-keywords (see <code class="filename">&lt;testsuite_hooks.h&gt;</code> header.
dg.exp) indicating what to do and what kinds of behavior are to be This usually expands to the standard <code class="literal">assert</code> macro, but
expected. New test cases should be written with the new style allows targets to define it to something different. In order to support
DejaGnu framework in mind. the alternative expansions of <code class="literal">VERIFY</code>, before any
</p><p> use of the macro there must be a variable called <code class="varname">test</code>
To ease transition, here is the list of dg-keyword documentation in scope, which is usually defined like so (the attribute avoids
lifted from dg.exp. warnings about an unused variable):
</p><pre class="programlisting"> </p><pre class="programlisting">
# The currently supported options are: bool test __attribute__((unused)) = true;
# </pre><p>
# dg-prms-id N </p><p>
# set prms_id to N The testsuite uses the DejaGnu framework to compile and run the tests.
# Test cases are normal C++ files which contain special directives in
# dg-options "options ..." [{ target selector }] comments. These directives look like <code class="literal">{ dg-* ... }</code>
# specify special options to pass to the tool (eg: compiler) 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-do do-what-keyword [{ target/xfail selector }] <code class="filename">dg.exp</code> file installed by DejaGnu.
# `do-what-keyword' is tool specific and is passed unchanged to The GCC testsuites support additional directives
# ${tool}-dg-test. An example is gcc where `keyword' can be any of: as described in the GCC internals documentation, see <a class="link" href="https://gcc.gnu.org/onlinedocs/gccint/Directives.html" target="_top">Syntax
# preprocess|compile|assemble|link|run and Descriptions of test directives</a>. GCC also defines many <a class="link" href="https://gcc.gnu.org/onlinedocs/gccint/Effective-Target-Keywords.html" target="_top">
# and will do one of: produce a .i, produce a .s, produce a .o, Keywords describing target attributes</a> (a.k.a effective targets)
# produce an a.out, or produce an a.out and run it (the default is which can be used where a target <em class="replaceable"><code>selector</code></em> can
# compile). appear.
# </p><p>
# dg-error regexp comment [{ target/xfail selector } [{.|0|linenum}]] Some directives commonly used in the libstdc++ testsuite are:
# indicate an error message &lt;regexp&gt; 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 &lt;regexp&gt; 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 &lt;regexp&gt; 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 &lt;regexp&gt;
# (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 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">{ dg-do <em class="replaceable"><code>do-what-keyword</code></em> [{ target/xfail <em class="replaceable"><code>selector</code></em> }] }</code></span></dt><dd>Where <em class="replaceable"><code>do-what-keyword</code></em> is usually
one of <code class="literal">run</code> (which is the default),
<code class="literal">compile</code>, or <code class="literal">link</code>,
and typical selectors are targets such as <code class="literal">*-*-gnu*</code>
or an effective target such as <code class="literal">c++11</code>.
</dd><dt><span class="term"><code class="literal">{ dg-require-<em class="replaceable"><code>support</code></em> args }</code></span></dt><dd>Skip the test if the target does not provide the required support.
See below for values of <em class="replaceable"><code>support</code></em>.
</dd><dt><span class="term"><code class="literal">{ dg-options <em class="replaceable"><code>options</code></em> [{ target <em class="replaceable"><code>selector</code></em> }] }</code></span></dt><dd></dd><dt><span class="term"><code class="literal">{ dg-error <em class="replaceable"><code>regexp</code></em> [ <em class="replaceable"><code>comment</code></em> [{ target/xfail <em class="replaceable"><code>selector</code></em> } [<em class="replaceable"><code>line</code></em>] ]] }</code></span></dt><dd></dd><dt><span class="term"><code class="literal">{ dg-excess-errors <em class="replaceable"><code>comment</code></em> [{ target/xfail <em class="replaceable"><code>selector</code></em> }] }</code></span></dt><dd></dd></dl></div><p>
For full details of these and other directives see the main GCC DejaGnu
documentation in the internals manual.
</p><p>
Test cases that use features of a particular C++ standard should specify
the minimum required standard as an effective target:
</p><pre class="programlisting"> // { dg-do run { target c++11 } }</pre><p>
or
</p><pre class="programlisting"> // { dg-require-effective-target c++11 }</pre><p>
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
<code class="option">RUNTESTFLAGS=--target_board=unix/-std=gnu++98</code>.
</p><p>
It is possible to indicate that a test should <span class="emphasis"><em>only</em></span>
be run for a specific standard (and not later standards) using an
effective target like <code class="literal">c++11_only</code>. However, this means
the test will be skipped by default (because the default mode is
<code class="literal">gnu++14</code>), and so will only run when
<code class="option">-std=gnu++11</code> or <code class="option">-std=c++11</code> is used
explicitly. For tests that require a specific standard it is better to
use a <code class="literal">dg-options</code> directive:
</p><pre class="programlisting"> // { dg-options "-std=gnu++11" }</pre><p>
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.
</p><p>
Similarly, tests which depend on a newer standard than the default
should use <code class="literal">dg-options</code> instead of an effective target,
so that they are not skipped by default.
For example, tests for C++17 features should use
</p><pre class="programlisting"> // { dg-options "-std=gnu++17" }</pre><p>
and not
</p><pre class="programlisting"> // { dg-do run "c++1z" }</pre><p>
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="tests.dg.examples"></a>Examples of Test Directives</h4></div></div></div><p>
Example 1: Testing compilation only:
</p><pre class="programlisting">
// { dg-do compile } // { dg-do compile }
</pre><p>
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:
</p><pre class="programlisting">
// { dg-warning "string literals" "" { xfail *-*-* } 36 } // { dg-warning "string literals" "" { xfail *-*-* } 36 }
</pre><p>
Example 3: Testing for expected warnings on line 36 Example 3: Testing for expected warnings on line 36:
</p><pre class="programlisting">
// { dg-warning "string literals" "" { target *-*-* } 36 } // { dg-warning "string literals" "" { target *-*-* } 36 }
</pre><p>
Example 4: Testing for compilation errors on line 41 Example 4: Testing for compilation errors on line 41:
</p><pre class="programlisting">
// { dg-do compile } // { dg-do compile }
// { dg-error "no match for" "" { target *-*-* } 41 } // { dg-error "no match for" "" { target *-*-* } 41 }
</pre><p>
Example 5: Testing with special command line settings, or without the Example 5: Testing with special command line settings, or without the
use of pre-compiled headers, in particular the stdc++.h.gch file. Any use of pre-compiled headers, in particular the
options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set <code class="filename">stdc++.h.gch</code> file. Any
up in the normal.exp file. options here will override the <code class="varname">DEFAULT_CXXFLAGS</code> and
<code class="varname">PCH_CXXFLAGS</code> set up in the <code class="filename">normal.exp</code>
file:
</p><pre class="programlisting">
// { dg-options "-O0" { target *-*-* } } // { dg-options "-O0" { target *-*-* } }
</pre><p> </pre><p>
More examples can be found in the libstdc++-v3/testsuite/*/*.cc files.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.harness"></a>Test Harness and Utilities</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.harness.dejagnu"></a>Dejagnu Harness Details</h4></div></div></div><p> Example 6: Compiling and linking a test only for C++14 and later, and only
if Debug Mode is active:
</p><pre class="programlisting">
// { dg-do link { target c++14 } }
// { dg-require-debug-mode "" }
</pre><p>
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:
</p><pre class="programlisting">
// { dg-options "-fstrict-enums" }
// { dg-additional-options "-march=i486" { target ia32 } }
// { dg-do run { target { ia32 || x86_64-*-* } } }
// { dg-require-effective-target "c++11" }
</pre><p>
</p><p>
More examples can be found in the
<code class="filename">libstdc++-v3/testsuite/*/*.cc</code> files.
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="tests.dg.directives"></a>Directives Specific to Libstdc++ Tests</h4></div></div></div><p>
In addition to the usual <a class="link" href="https://gcc.gnu.org/onlinedocs/gccint/Require-support.html" target="_top">Variants
of <code class="literal">dg-require-<em class="replaceable"><code>support</code></em></code></a>
several more directives are available for use in libstdc++ tests,
including the following:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">dg-require-namedlocale</code> <em class="replaceable"><code>name</code></em></span></dt><dd><p>The named locale must be available.
</p></dd><dt><span class="term"><code class="literal">dg-require-debug-mode ""</code></span></dt><dd><p>Skip the test if the Debug Mode is not active
(as determined by the <code class="literal">_GLIBCXX_DEBUG</code> macro).
</p></dd><dt><span class="term"><code class="literal">dg-require-parallel-mode ""</code></span></dt><dd><p>Skip the test if the Parallel Mode is not active
(as determined by the <code class="literal">_GLIBCXX_PARALLEL</code> macro).
</p></dd><dt><span class="term"><code class="literal">dg-require-profile-mode ""</code></span></dt><dd><p>Skip the test if the Profile Mode is not active
(as determined by the <code class="literal">_GLIBCXX_PROFILE</code> macro).
</p></dd><dt><span class="term"><code class="literal">dg-require-normal-mode ""</code></span></dt><dd><p>Skip the test if any of Debug, Parallel or Profile
Mode is active.
</p></dd><dt><span class="term"><code class="literal">dg-require-atomic-builtins ""</code></span></dt><dd><p>Skip the test if atomic operations on <span class="type">bool</span>
and <span class="type">int</span> are not lock-free.
</p></dd><dt><span class="term"><code class="literal">dg-require-gthreads ""</code></span></dt><dd><p>Skip the test if the C++11 thread library is not
supported, as determined by the <code class="literal">_GLIBCXX_HAS_GTHREADS</code>
macro.
</p></dd><dt><span class="term"><code class="literal">dg-require-gthreads-timed ""</code></span></dt><dd><p>Skip the test if C++11 timed mutexes are not supported,
as determined by the <code class="literal">_GLIBCXX_HAS_GTHREADS</code> and
<code class="literal">_GTHREAD_USE_MUTEX_TIMEDLOCK</code> macros.
</p></dd><dt><span class="term"><code class="literal">dg-require-string-conversions ""</code></span></dt><dd><p>Skip the test if the C++11 <code class="function">to_string</code>
and <code class="function">stoi</code>, <code class="function">stod</code> etc. functions
are not fully supported (including wide character versions).
</p></dd><dt><span class="term"><code class="literal">dg-require-filesystem-ts ""</code></span></dt><dd><p>Skip the test if the Filesystem TS is not supported.
</p></dd></dl></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="test.harness"></a>Test Harness and Utilities</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="test.harness.dejagnu"></a>DejaGnu Harness Details</h4></div></div></div><p>
Underlying details of testing for conformance and regressions are 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. rest of GCC.
</p><p>This is information for those looking at making changes to the testsuite </p><p>This is information for those looking at making changes to the testsuite
structure, and/or needing to trace dejagnu's actions with --verbose. This structure, and/or needing to trace DejaGnu's actions with
will not be useful to people who are "merely" adding new tests to the existing <code class="option">--verbose</code>.
structure. This will not be useful to people who are "merely" adding new tests
</p><p>The first key point when working with dejagnu is the idea of a "tool". to the existing structure.
</p><p>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 Files, directories, and functions are all implicitly used when they are
named after the tool in use. Here, the tool will always be "libstdc++". named after the tool in use. Here, the tool will always be "libstdc++".
</p><p>The <code class="code">lib</code> subdir contains support routines. The </p><p>The <code class="code">lib</code> subdir contains support routines. The
...@@ -433,7 +554,7 @@ be copied from the core compiler's support directory into <code class="code">lib ...@@ -433,7 +554,7 @@ be copied from the core compiler's support directory into <code class="code">lib
</p><p>Some routines in <code class="code">lib/libstdc++.exp</code> are callbacks, some are </p><p>Some routines in <code class="code">lib/libstdc++.exp</code> are callbacks, some are
our own. Callbacks must be prefixed with the name of the tool. To easily 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-*". distinguish the others, by convention our own routines are named "v3-*".
</p><p>The next key point when working with dejagnu is "test files". Any </p><p>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. directory whose name starts with the tool name will be searched for test files.
(We have only one.) In those directories, any <code class="code">.exp</code> file is (We have only one.) In those directories, any <code class="code">.exp</code> file is
considered a test file, and will be run in turn. Our main test file is called considered a test file, and will be run in turn. Our main test file is called
......
libstdc++-v3/doc/xml/manual/test.xml
...@@ -554,29 +554,65 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting> ...@@ -554,29 +554,65 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting>
<section xml:id="test.run.permutations"><info><title>Permutations</title></info> <section xml:id="test.run.permutations"><info><title>Permutations</title></info>
<para> <para>
To run the libstdc++ test suite under the <link linkend="manual.ext.debug_mode">debug mode</link>, edit The tests will be compiled with a set of default compiler flags defined
<filename>libstdc++-v3/scripts/testsuite_flags</filename> to add the by the
compile-time flag <constant>-D_GLIBCXX_DEBUG</constant> to the <filename><replaceable>libbuildir</replaceable>/scripts/testsuite_flags</filename>
result printed by the <literal>--build-cxx</literal> 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>--cxxflags</option> option of that script, or by setting
the <varname>CXXFLAGS</varname> variable when running
<command>make</command>, or via options for the DejaGnu test framework
(described below). The latter approach uses the
<option>--target_board</option> option that was shown earlier.
For example, to run the tests with <option>-O1 -D_GLIBCXX_ASSERT</option>
you could use:
<programlisting> make RUNTESTFLAGS=--target_board=unix/-O1/-D_GLIBCXX_ASSERTIONS</programlisting>
</para>
<para>
The <option>--target_board</option> option can also be used to run the
tests multiple times in different variations. For example, to run the
entire testsuite three times using <option>-O3</option> but with
different <option>-std</option> options:
<programlisting> make 'RUNTESTFLAGS=--target_board=unix/-O3\"{-std=gnu++98,-std=gnu++11,-std=gnu++14}\"'</programlisting>
N.B. that set of variations could also be written as
<literal>unix/-O3\"{-std=gnu++98,-std=gnu++11,}\"</literal> so that
the third variation would use the default for <option>-std</option>
(which is <option>-std=gnu++14</option> as of GCC 6).
</para>
<para>
To run the libstdc++ test suite under the
<link linkend="manual.ext.debug_mode">debug mode</link>, use
<userinput>make check-debug</userinput>. Alternatively, edit
<filename><replaceable>libbuildir</replaceable>/scripts/testsuite_flags</filename>
to add the compile-time flag <option>-D_GLIBCXX_DEBUG</option> to the
result printed by the <option>--cxxflags</option>
option. Additionally, add the option. Additionally, add the
<constant>-D_GLIBCXX_DEBUG_PEDANTIC</constant> flag to turn on <option>-D_GLIBCXX_DEBUG_PEDANTIC</option> flag to turn on
pedantic checking. The libstdc++ test suite should produce pedantic checking. The libstdc++ test suite should produce
precisely the same results under debug mode that it does under the same results under debug mode that it does under release mode:
release mode: any deviation indicates an error in either the any deviation indicates an error in either the library or the test suite.
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
<literal>dg-require-<replaceable>support</replaceable></literal>
directives described below.
</para> </para>
<para> <para>
The <link linkend="manual.ext.parallel_mode">parallel The <link linkend="manual.ext.parallel_mode">parallel
mode</link> can be tested in much the same manner, substituting mode</link> can be tested using
<constant>-D_GLIBCXX_PARALLEL</constant> for <userinput>make check-parallel</userinput>, or in much the same manner
<constant>-D_GLIBCXX_DEBUG</constant> in the previous paragraph. as the debug mode, substituting
<option>-D_GLIBCXX_PARALLEL</option> for
<option>-D_GLIBCXX_DEBUG</option> in the previous paragraph.
</para> </para>
<para> <para>
Or, just run the testsuites with <constant>CXXFLAGS</constant> Or, just run the testsuite
set to <constant>-D_GLIBCXX_DEBUG</constant> or <option>-D_GLIBCXX_DEBUG</option> or <option>-D_GLIBCXX_PARALLEL</option>
<constant>-D_GLIBCXX_PARALLEL</constant>. in <varname>CXXFLAGS</varname> or <varname>RUNTESTFLAGS</varname>.
</para> </para>
</section> </section>
</section> </section>
...@@ -593,12 +629,17 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting> ...@@ -593,12 +629,17 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting>
<para> <para>
All files are copyright the FSF, and GPL'd: this is very All files are copyright the FSF, and GPL'd: this is very
important. The first copyright year should correspond to the date 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.
</para> </para>
<para> <para>
As per the dejagnu instructions, always return 0 from main to The DejaGnu instructions say to always return <literal>0</literal>
indicate success. from <function>main</function> to indicate success. Strictly speaking
this is redundant in C++, since returning from <function>main</function>
is defined to return <literal>0</literal>. Most tests still have an
explicit return.
</para> </para>
<para> <para>
...@@ -610,109 +651,238 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting> ...@@ -610,109 +651,238 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting>
</para> </para>
<para> <para>
For a test that needs to take advantage of the dejagnu test Tests that need to perform runtime checks should use the
harness, what follows below is a list of special keyword that <literal>VERIFY</literal> macro, defined in the
harness uses. Basically, a test case contains dg-keywords (see <filename class="headerfile">&lt;testsuite_hooks.h&gt;</filename> header.
dg.exp) indicating what to do and what kinds of behavior are to be This usually expands to the standard <literal>assert</literal> macro, but
expected. New test cases should be written with the new style allows targets to define it to something different. In order to support
DejaGnu framework in mind. the alternative expansions of <literal>VERIFY</literal>, before any
use of the macro there must be a variable called <varname>test</varname>
in scope, which is usually defined like so (the attribute avoids
warnings about an unused variable):
<programlisting>
bool test __attribute__((unused)) = true;
</programlisting>
</para>
<para>
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 <literal>{ dg-* ... }</literal>
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
<filename>dg.exp</filename> file installed by DejaGnu.
The GCC testsuites support additional directives
as described in the GCC internals documentation, see <link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Directives.html">Syntax
and Descriptions of test directives</link>. GCC also defines many <link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Effective-Target-Keywords.html">
Keywords describing target attributes</link> (a.k.a effective targets)
which can be used where a target <replaceable>selector</replaceable> can
appear.
</para>
<para>
Some directives commonly used in the libstdc++ testsuite are:
<variablelist>
<varlistentry>
<term><literal>{ dg-do <replaceable>do-what-keyword</replaceable> [{ target/xfail <replaceable>selector</replaceable> }] }</literal></term>
<listitem>Where <replaceable>do-what-keyword</replaceable> is usually
one of <literal>run</literal> (which is the default),
<literal>compile</literal>, or <literal>link</literal>,
and typical selectors are targets such as <literal>*-*-gnu*</literal>
or an effective target such as <literal>c++11</literal>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>{ dg-require-<replaceable>support</replaceable> args }</literal></term>
<listitem>Skip the test if the target does not provide the required support.
See below for values of <replaceable>support</replaceable>.
</listitem>
</varlistentry>
<varlistentry>
<term><literal>{ dg-options <replaceable>options</replaceable> [{ target <replaceable>selector</replaceable> }] }</literal></term>
</varlistentry>
<varlistentry>
<term><literal>{ dg-error <replaceable>regexp</replaceable> [ <replaceable>comment</replaceable> [{ target/xfail <replaceable>selector</replaceable> } [<replaceable>line</replaceable>] ]] }</literal></term>
</varlistentry>
<varlistentry>
<term><literal>{ dg-excess-errors <replaceable>comment</replaceable> [{ target/xfail <replaceable>selector</replaceable> }] }</literal></term>
</varlistentry>
</variablelist>
For full details of these and other directives see the main GCC DejaGnu
documentation in the internals manual.
</para> </para>
<para> <para>
To ease transition, here is the list of dg-keyword documentation Test cases that use features of a particular C++ standard should specify
lifted from dg.exp. the minimum required standard as an effective target:
<programlisting> // { dg-do run { target c++11 } }</programlisting>
or
<programlisting> // { dg-require-effective-target c++11 }</programlisting>
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
<option>RUNTESTFLAGS=--target_board=unix/-std=gnu++98</option>.
</para> </para>
<para>
It is possible to indicate that a test should <emphasis>only</emphasis>
be run for a specific standard (and not later standards) using an
effective target like <literal>c++11_only</literal>. However, this means
the test will be skipped by default (because the default mode is
<literal>gnu++14</literal>), and so will only run when
<option>-std=gnu++11</option> or <option>-std=c++11</option> is used
explicitly. For tests that require a specific standard it is better to
use a <literal>dg-options</literal> directive:
<programlisting> // { dg-options "-std=gnu++11" }</programlisting>
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.
</para>
<para>
Similarly, tests which depend on a newer standard than the default
should use <literal>dg-options</literal> instead of an effective target,
so that they are not skipped by default.
For example, tests for C++17 features should use
<programlisting> // { dg-options "-std=gnu++17" }</programlisting>
and not
<programlisting> // { dg-do run "c++1z" }</programlisting>
</para>
<section xml:id="tests.dg.examples"><info><title>Examples of Test Directives</title></info>
<para>
Example 1: Testing compilation only:
<programlisting> <programlisting>
# 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 &lt;regexp&gt; 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 &lt;regexp&gt; 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 &lt;regexp&gt; 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 &lt;regexp&gt;
# (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 } // { dg-do compile }
</programlisting>
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:
<programlisting>
// { dg-warning "string literals" "" { xfail *-*-* } 36 } // { dg-warning "string literals" "" { xfail *-*-* } 36 }
</programlisting>
Example 3: Testing for expected warnings on line 36 Example 3: Testing for expected warnings on line 36:
<programlisting>
// { dg-warning "string literals" "" { target *-*-* } 36 } // { dg-warning "string literals" "" { target *-*-* } 36 }
</programlisting>
Example 4: Testing for compilation errors on line 41 Example 4: Testing for compilation errors on line 41:
<programlisting>
// { dg-do compile } // { dg-do compile }
// { dg-error "no match for" "" { target *-*-* } 41 } // { dg-error "no match for" "" { target *-*-* } 41 }
</programlisting>
Example 5: Testing with special command line settings, or without the Example 5: Testing with special command line settings, or without the
use of pre-compiled headers, in particular the stdc++.h.gch file. Any use of pre-compiled headers, in particular the
options here will override the DEFAULT_CXXFLAGS and PCH_CXXFLAGS set <filename class="headerfile">stdc++.h.gch</filename> file. Any
up in the normal.exp file. options here will override the <varname>DEFAULT_CXXFLAGS</varname> and
<varname>PCH_CXXFLAGS</varname> set up in the <filename>normal.exp</filename>
file:
<programlisting>
// { dg-options "-O0" { target *-*-* } } // { dg-options "-O0" { target *-*-* } }
</programlisting> </programlisting>
Example 6: Compiling and linking a test only for C++14 and later, and only
if Debug Mode is active:
<programlisting>
// { dg-do link { target c++14 } }
// { dg-require-debug-mode "" }
</programlisting>
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:
<programlisting>
// { dg-options "-fstrict-enums" }
// { dg-additional-options "-march=i486" { target ia32 } }
// { dg-do run { target { ia32 || x86_64-*-* } } }
// { dg-require-effective-target "c++11" }
</programlisting>
</para>
<para> <para>
More examples can be found in the More examples can be found in the
<filename>libstdc++-v3/testsuite/*/*.cc</filename> files. <filename>libstdc++-v3/testsuite/*/*.cc</filename> files.
</para> </para>
</section> </section>
<section xml:id="tests.dg.directives"><info><title>Directives Specific to Libstdc++ Tests</title></info>
<para>
In addition to the usual <link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="https://gcc.gnu.org/onlinedocs/gccint/Require-support.html">Variants
of <literal>dg-require-<replaceable>support</replaceable></literal></link>
several more directives are available for use in libstdc++ tests,
including the following:
</para>
<variablelist>
<varlistentry><term><literal>dg-require-namedlocale</literal> <replaceable>name</replaceable></term>
<listitem><para>The named locale must be available.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-debug-mode ""</literal></term>
<listitem><para>Skip the test if the Debug Mode is not active
(as determined by the <literal>_GLIBCXX_DEBUG</literal> macro).
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-parallel-mode ""</literal></term>
<listitem><para>Skip the test if the Parallel Mode is not active
(as determined by the <literal>_GLIBCXX_PARALLEL</literal> macro).
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-profile-mode ""</literal></term>
<listitem><para>Skip the test if the Profile Mode is not active
(as determined by the <literal>_GLIBCXX_PROFILE</literal> macro).
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-normal-mode ""</literal></term>
<listitem><para>Skip the test if any of Debug, Parallel or Profile
Mode is active.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-atomic-builtins ""</literal></term>
<listitem><para>Skip the test if atomic operations on <type>bool</type>
and <type>int</type> are not lock-free.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-gthreads ""</literal></term>
<listitem><para>Skip the test if the C++11 thread library is not
supported, as determined by the <literal>_GLIBCXX_HAS_GTHREADS</literal>
macro.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-gthreads-timed ""</literal></term>
<listitem><para>Skip the test if C++11 timed mutexes are not supported,
as determined by the <literal>_GLIBCXX_HAS_GTHREADS</literal> and
<literal>_GTHREAD_USE_MUTEX_TIMEDLOCK</literal> macros.
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-string-conversions ""</literal></term>
<listitem><para>Skip the test if the C++11 <function>to_string</function>
and <function>stoi</function>, <function>stod</function> etc. functions
are not fully supported (including wide character versions).
</para></listitem>
</varlistentry>
<varlistentry><term><literal>dg-require-filesystem-ts ""</literal></term>
<listitem><para>Skip the test if the Filesystem TS is not supported.
</para></listitem>
</varlistentry>
</variablelist>
</section>
</section>
<section xml:id="test.harness" xreflabel="Test Harness and Utilities"><info><title>Test Harness and Utilities</title></info> <section xml:id="test.harness" xreflabel="Test Harness and Utilities"><info><title>Test Harness and Utilities</title></info>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment