git
/
gcc
mirror of git://gcc.gnu.org/git/gcc.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Backport libstdc++ documentation improvements 

* doc/xml/manual/abi.xml: Backport documentation improvements from
	mainline.
	* doc/xml/manual/configure.xml: Likewise.
	* doc/xml/manual/diagnostics.xml: Likewise.
	* doc/xml/manual/extensions.xml: Likewise.
	* doc/xml/manual/status_cxx2011.xml: Likewise.
	* doc/xml/manual/status_cxx2014.xml: Likewise.
	* doc/xml/manual/using.xml: Likewise.
	* doc/html/*: Regenerate.

From-SVN: r231409
This commit is contained in:
Jonathan Wakely 2015-12-08 14:00:31 +00:00 committed by Jonathan Wakely
parent 55b67ecd98
commit 5d8674c4eb
20 changed files with 184 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
libstdc++-v3/ChangeLog
View File

@ -1,3 +1,15 @@
2015-12-08 Jonathan Wakely <jwakely@redhat.com>
* doc/xml/manual/abi.xml: Backport documentation improvements from
mainline.
* doc/xml/manual/configure.xml: Likewise.
* doc/xml/manual/diagnostics.xml: Likewise.
* doc/xml/manual/extensions.xml: Likewise.
* doc/xml/manual/status_cxx2011.xml: Likewise.
* doc/xml/manual/status_cxx2014.xml: Likewise.
* doc/xml/manual/using.xml: Likewise.
* doc/html/*: Regenerate.
2015-12-04 Jonathan Wakely <jwakely@redhat.com>
PR libstdc++/56383

2
libstdc++-v3/doc/html/index.html
View File

File diff suppressed because one or more lines are too long

2
libstdc++-v3/doc/html/manual/abi.html
View File

@ -38,7 +38,7 @@
documented
<a class="link" href="configure.html" title="Configure">here</a>.
</p><p> Putting all of these ideas together results in the C++ Standard
library ABI, which is the compilation of a given library API by a
Library ABI, which is the compilation of a given library API by a
given compiler ABI. In a nutshell:
</p><p>
<span class="quote">“<span class="quote">

5
libstdc++-v3/doc/html/manual/concept_checking.html
View File

@ -35,8 +35,9 @@
<code class="literal">-D_GLIBCXX_CONCEPT_CHECKS</code>.
</p><p>
Please note that the checks are based on the requirements in the original
C++ standard, some of which have changed in the new C++11 revision.
Additionally, some correct code might be rejected by the concept checks,
C++ standard, many of which were relaxed in the C++11 standard and so valid
C++11 code may be incorrectly rejected by the concept checks. Additionally,
some correct C++03 code might be rejected by the concept checks,
for example template argument types may need to be complete when used in
a template definition, rather than at the point of instantiation.
There are no plans to address these shortcomings.

17
libstdc++-v3/doc/html/manual/configure.html
View File

@ -174,10 +174,12 @@
Mostly useful together with shared memory allocators, see PR
libstdc++/16612 for details.
</p></dd><dt><span class="term"><code class="code">--enable-concept-checks</code></span></dt><dd><p>This turns on additional compile-time checks for instantiated
library templates, in the form of specialized templates,
<a class="link" href="concept_checking.html" title="Concept Checking">described here</a>. They
library templates, in the form of specialized templates described in
the <a class="link" href="concept_checking.html" title="Concept Checking">Concept
Checking</a> section. They
can help users discover when they break the rules of the STL, before
their programs run.
their programs run. These checks are based on C++03 rules and some of
them are not compatible with correct C++11 code.
</p></dd><dt><span class="term"><code class="code">--enable-symvers[=style]</code></span></dt><dd><p>In 3.1 and later, tries to turn on symbol versioning in the
shared library (if a shared library has been
requested). Values for 'style' that are currently supported
@ -236,9 +238,10 @@
</p></dd><dt><span class="term"><code class="code">--with-default-libstdcxx-abi=</code><em class="replaceable"><code>OPTION</code></em></span></dt><dd><p>
Set the default value for the <span class="symbol">_GLIBCXX_USE_CXX11_ABI</span>
macro (see <a class="xref" href="using_macros.html" title="Macros">Macros</a>).
The default is <code class="option">OPTION=c++11</code> which sets the macro to
The default is <code class="option">OPTION=new</code> which sets the macro to
<code class="literal">1</code>,
use <code class="option">OPTION=c++98</code> to set it to <code class="literal">0</code>.
use <code class="option">OPTION=gcc4-compatible</code> to set it to
<code class="literal">0</code>.
This option does not change the library ABI.
</p></dd><dt><span class="term"><code class="code">--enable-vtable-verify</code>[default]</span></dt><dd><p>Use <code class="code">-fvtable-verify=std</code> to compile the C++
runtime with instrumentation for vtable verification. All virtual
@ -247,4 +250,8 @@
<code class="classname">iostream</code>, and others. Disabling means that
the C++ runtime is compiled without support for vtable
verification. By default, this option is off.
</p></dd><dt><span class="term"><code class="code">--enable-libstdcxx-filesystem-ts</code>[default]</span></dt><dd><p>Build <code class="filename">libstdc++fs.a</code> as well
as the usual libstdc++ and libsupc++ libraries. This is enabled by
default on select POSIX targets where it is known to work and disabled
otherwise.
</p></dd></dl></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="setup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="setup.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="make.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Setup </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Make</td></tr></table></div></body></html>

3
libstdc++-v3/doc/html/manual/ext_compile_checks.html
View File

@ -29,7 +29,8 @@
They can be enabled at configure time with
<a class="link" href="configure.html" title="Configure"><code class="literal">--enable-concept-checks</code></a>.
You can enable them on a per-translation-unit basis with
<code class="code">#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
<a class="link" href="using_macros.html" title="Macros"><code class="code">#define
_GLIBCXX_CONCEPT_CHECKS</code></a> for GCC 3.4 and higher
(or with <code class="code">#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
3.1, 3.2 and 3.3).
</p><p>Please note that the concept checks only validate the requirements

2
libstdc++-v3/doc/html/manual/index.html
View File

File diff suppressed because one or more lines are too long

2
libstdc++-v3/doc/html/manual/intro.html
View File

File diff suppressed because one or more lines are too long

29
libstdc++-v3/doc/html/manual/status.html
View File

File diff suppressed because one or more lines are too long

14
libstdc++-v3/doc/html/manual/using.html
View File

File diff suppressed because one or more lines are too long

17
libstdc++-v3/doc/html/manual/using_dynamic_or_shared.html
View File

@ -102,4 +102,21 @@ A quick read of the relevant part of the GCC
also installed, for use with Libtool. If you use Libtool to
create your executables, these details are taken care of for
you.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.linkage.experimental"></a>Experimental Library Extensions</h3></div></div></div><p>
GCC 5.3 includes an implementation of the Filesystem library defined
by the technical specification ISO/IEC TS 18822:2015. Because this is
an experimental library extension, not part of the C++ standard, it
is implemented in a separate library,
<code class="filename">libstdc++fs.a</code>, and there is
no shared library for it. To use the library you should include
<code class="filename">&lt;experimental/filesystem&gt;</code>
and link with <code class="option">-lstdc++fs</code>. The library implementation
is incomplete on non-POSIX platforms, specifically Windows support is
rudimentary.
</p><p>
Due to the experimental nature of the Filesystem library the usual
guarantees about ABI stability and backwards compatibility do not apply
to it. There is no guarantee that the components in any
<code class="filename">&lt;experimental/xxx&gt;</code>
header will remain compatible between different GCC releases.
</p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="using_namespaces.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="using.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="using_concurrency.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Namespaces </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Concurrency</td></tr></table></div></body></html>

11
libstdc++-v3/doc/html/manual/using_headers.html
View File

@ -74,12 +74,15 @@ of <code class="code">std::sinf</code>, <code class="code">std::sin</code>,
and <code class="code">std::sinl</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.headers.pre"></a>Precompiled Headers</h3></div></div></div><p>There are three base header files that are provided. They can be
used to precompile the standard headers and extensions into binary
files that may the be used to speed compiles that use these headers.
files that may then be used to speed up compilations that use these headers.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>stdc++.h</p><p>Includes all standard headers. Actual content varies depending on
language dialect.
<a class="link" href="using.html#manual.intro.using.flags" title="Command Options">language dialect</a>.
</p></li><li class="listitem"><p>stdtr1c++.h</p><p>Includes all of &lt;stdc++.h&gt;, and adds all the TR1 headers.
</p></li><li class="listitem"><p>extc++.h</p><p>Includes all of &lt;stdtr1c++.h&gt;, and adds all the Extension headers.
</p></li></ul></div><p>How to construct a .gch file from one of these base header files.</p><p>First, find the include directory for the compiler. One way to do
</p></li><li class="listitem"><p>extc++.h</p><p>Includes all of the Extension headers
(and in C++98 mode also adds all the TR1 headers by including all of
&lt;stdtr1c++.h&gt;).
</p></li></ul></div><p>To construct a .gch file from one of these base header files,
first find the include directory for the compiler. One way to do
this is:</p><pre class="programlisting">
g++ -v hello.cc

4
libstdc++-v3/doc/html/manual/using_namespaces.html
View File

@ -2,8 +2,8 @@
<!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>Namespaces</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><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="using.html" title="Chapter 3. Using" /><link rel="prev" href="using_dual_abi.html" title="Dual ABI" /><link rel="next" href="using_dynamic_or_shared.html" title="Linking" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Namespaces</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="using_dual_abi.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Using</th><td width="20%" align="right"> <a accesskey="n" href="using_dynamic_or_shared.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.using.namespaces"></a>Namespaces</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a id="manual.intro.using.namespaces.all"></a>Available Namespaces</h3></div></div></div><p> There are three main namespaces.
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>std</p><p>The ISO C++ standards specify that "all library entities are defined
within namespace std." This includes namespaces nested
within <code class="code">namespace std</code>, such as <code class="code">namespace
std::tr1</code>.
within namespace <code class="code">std</code>, such as namespace
<code class="code">std::chrono</code>.
</p></li><li class="listitem"><p>abi</p><p>Specified by the C++ ABI. This ABI specifies a number of type and
function APIs supplemental to those required by the ISO C++ Standard,
but necessary for interoperability.

2
libstdc++-v3/doc/xml/manual/abi.xml
View File

@ -66,7 +66,7 @@
</para>
<para> Putting all of these ideas together results in the C++ Standard
library ABI, which is the compilation of a given library API by a
Library ABI, which is the compilation of a given library API by a
given compiler ABI. In a nutshell:
</para>

17
libstdc++-v3/doc/xml/manual/configure.xml
View File

@ -297,10 +297,12 @@
<varlistentry><term><code>--enable-concept-checks</code></term>
<listitem><para>This turns on additional compile-time checks for instantiated
library templates, in the form of specialized templates,
<link linkend="std.diagnostics.concept_checking">described here</link>. They
library templates, in the form of specialized templates described in
the <link linkend="std.diagnostics.concept_checking">Concept
Checking</link> section. They
can help users discover when they break the rules of the STL, before
their programs run.
their programs run. These checks are based on C++03 rules and some of
them are not compatible with correct C++11 code.
</para>
</listitem></varlistentry>
@ -418,6 +420,15 @@
</para>
</listitem></varlistentry>
<varlistentry><term><code>--enable-libstdcxx-filesystem-ts</code>[default]</term>
<listitem>
<para>Build <filename class="libraryfile">libstdc++fs.a</filename> as well
as the usual libstdc++ and libsupc++ libraries. This is enabled by
default on select POSIX targets where it is known to work and disabled
otherwise.
</para>
</listitem></varlistentry>
</variablelist>
</section>

5
libstdc++-v3/doc/xml/manual/diagnostics.xml
View File

@ -114,8 +114,9 @@
<para>
Please note that the checks are based on the requirements in the original
C++ standard, some of which have changed in the new C++11 revision.
Additionally, some correct code might be rejected by the concept checks,
C++ standard, many of which were relaxed in the C++11 standard and so valid
C++11 code may be incorrectly rejected by the concept checks. Additionally,
some correct C++03 code might be rejected by the concept checks,
for example template argument types may need to be complete when used in
a template definition, rather than at the point of instantiation.
There are no plans to address these shortcomings.

3
libstdc++-v3/doc/xml/manual/extensions.xml
View File

@ -82,7 +82,8 @@ extensions, be aware of two things:
They can be enabled at configure time with
<link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
You can enable them on a per-translation-unit basis with
<code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
<link linkend="manual.intro.using.macros"><code>#define
_GLIBCXX_CONCEPT_CHECKS</code></link> for GCC 3.4 and higher
(or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
3.1, 3.2 and 3.3).
</para>

11
libstdc++-v3/doc/xml/manual/status_cxx2011.xml
View File

@ -17,8 +17,8 @@ Final Draft International Standard, Standard for Programming Language C++
</para>
<para>
In this implementation <literal>-std=gnu++11</literal> or
<literal>-std=c++11</literal> flags must be used to enable language
In this implementation the <literal>-std=gnu++11</literal> or
<literal>-std=c++11</literal> flag must be used to enable language
and library
features. See <link linkend="manual.intro.using.flags">dialect</link>
options. The pre-defined symbol
@ -642,10 +642,8 @@ particular release.
<entry>Class template <code>shared_ptr</code></entry>
<entry>Y</entry>
<entry>
<para>
Uses code from
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/smart_ptr/shared_ptr.htm">boost::shared_ptr</link>.
</para>
</entry>
</row>
<row>
@ -2673,7 +2671,10 @@ particular release.
<emphasis>30.2.3 [thread.req.native]/1</emphasis>
<classname>native_handle_type</classname> and
<methodname>native_handle</methodname> are provided. The handle types
are defined in terms of the Gthreads abstraction layer.
are defined in terms of the Gthreads abstraction layer, although this
is subject to change at any time. Any use of
<classname>native_handle</classname> is inherently non-portable and
not guaranteed to work between major releases of GCC.
<itemizedlist>
<listitem><para><classname>thread</classname>: The native handle type is
a typedef for <code>__gthread_t</code> i.e. <code>pthread_t</code>

19
libstdc++-v3/doc/xml/manual/status_cxx2014.xml
View File

@ -10,8 +10,8 @@
</info>
<para>
In this implementation <literal>-std=gnu++1y</literal> or
<literal>-std=c++1y</literal> flags must be used to enable language
In this implementation the <literal>-std=gnu++14</literal> or
<literal>-std=c++14</literal> flag must be used to enable language
and library
features. See <link linkend="manual.intro.using.flags">dialect</link>
options. The pre-defined symbol
@ -196,7 +196,7 @@ not in any particular release.
</entry>
<entry>Shared Locking in C++</entry>
<entry>Y</entry>
<entry>Need tests</entry>
<entry/>
</row>
@ -395,15 +395,18 @@ not in any particular release.
</row>
<row>
<?dbhtml bgcolor="#C8C8B0" ?>
<entry>
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n3932.htm">
N3940
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4100.pdf">
N4100
</link>
</entry>
<entry>File System</entry>
<entry>WIP</entry>
<entry></entry>
<entry>Y</entry>
<entry>
Link with
<link linkend="manual.intro.using.linkage.experimental">
<option>-lstdc++fs</option></link>
</entry>
</row>

71
libstdc++-v3/doc/xml/manual/using.xml
View File

@ -13,7 +13,10 @@
</para>
<para>
By default, <command>g++</command> is equivalent to <command>g++ -std=gnu++98</command>. The standard library also defaults to this dialect.
The standard library conforms to the dialect of C++ specified by the
<option>-std</option> option passed to the compiler.
By default, <command>g++</command> is equivalent to
<command>g++ -std=gnu++98</command> for GCC 5 and older releases.
</para>
<table frame="all" xml:id="table.cmd_options">
@ -32,12 +35,14 @@
<tbody>
<row>
<entry><literal>-std=c++98</literal></entry>
<entry><literal>-std=c++98</literal> or <literal>-std=c++03</literal>
</entry>
<entry>Use the 1998 ISO C++ standard plus amendments.</entry>
</row>
<row>
<entry><literal>-std=gnu++98</literal></entry>
<entry><literal>-std=gnu++98</literal> or <literal>-std=gnu++03</literal>
</entry>
<entry>As directly above, with GNU extensions.</entry>
</row>
@ -51,6 +56,16 @@
<entry>As directly above, with GNU extensions.</entry>
</row>
<row>
<entry><literal>-std=c++14</literal></entry>
<entry>Use the 2014 ISO C++ standard.</entry>
</row>
<row>
<entry><literal>-std=gnu++14</literal></entry>
<entry>As directly above, with GNU extensions.</entry>
</row>
<row>
<entry><literal>-fexceptions</literal></entry>
<entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry>
@ -79,6 +94,14 @@
</entry>
</row>
<row>
<entry><literal>-lstdc++fs</literal></entry>
<entry>Linking to <filename class="libraryfile">libstdc++fs</filename>
is required for use of the Filesystem library extensions in
<filename class="headerfile">&lt;experimental/filesystem&gt;</filename>.
</entry>
</row>
<row>
<entry><literal>-fopenmp</literal></entry>
<entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
@ -703,7 +726,7 @@ and <code>std::sinl</code>.
<para>There are three base header files that are provided. They can be
used to precompile the standard headers and extensions into binary
files that may the be used to speed compiles that use these headers.
files that may then be used to speed up compilations that use these headers.
</para>
@ -711,7 +734,7 @@ files that may the be used to speed compiles that use these headers.
<listitem>
<para>stdc++.h</para>
<para>Includes all standard headers. Actual content varies depending on
language dialect.
<link linkend="manual.intro.using.flags">language dialect</link>.
</para>
</listitem>
@ -722,13 +745,14 @@ language dialect.
</listitem>
<listitem><para>extc++.h</para>
<para>Includes all of &lt;stdtr1c++.h&gt;, and adds all the Extension headers.
<para>Includes all of the Extension headers
(and in C++98 mode also adds all the TR1 headers by including all of
&lt;stdtr1c++.h&gt;).
</para></listitem>
</itemizedlist>
<para>How to construct a .gch file from one of these base header files.</para>
<para>First, find the include directory for the compiler. One way to do
<para>To construct a .gch file from one of these base header files,
first find the include directory for the compiler. One way to do
this is:</para>
<programlisting>
@ -1027,8 +1051,8 @@ g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe
<listitem><para>std</para>
<para>The ISO C++ standards specify that "all library entities are defined
within namespace std." This includes namespaces nested
within <code>namespace std</code>, such as <code>namespace
std::tr1</code>.
within namespace <code>std</code>, such as namespace
<code>std::chrono</code>.
</para>
</listitem>
<listitem><para>abi</para>
@ -1333,8 +1357,31 @@ A quick read of the relevant part of the GCC
you.
</para>
</section>
</section>
<section xml:id="manual.intro.using.linkage.experimental" xreflabel="Library Extensions"><info><title>Experimental Library Extensions</title></info>
<para>
GCC 5.3 includes an implementation of the Filesystem library defined
by the technical specification ISO/IEC TS 18822:2015. Because this is
an experimental library extension, not part of the C++ standard, it
is implemented in a separate library,
<filename class="libraryfile">libstdc++fs.a</filename>, and there is
no shared library for it. To use the library you should include
<filename class="headerfile">&lt;experimental/filesystem&gt;</filename>
and link with <option>-lstdc++fs</option>. The library implementation
is incomplete on non-POSIX platforms, specifically Windows support is
rudimentary.
</para>
<para>
Due to the experimental nature of the Filesystem library the usual
guarantees about ABI stability and backwards compatibility do not apply
to it. There is no guarantee that the components in any
<filename class="headerfile">&lt;experimental/xxx&gt;</filename>
header will remain compatible between different GCC releases.
</para>
</section>
</section>
<section xml:id="manual.intro.using.concurrency" xreflabel="Concurrency"><info><title>Concurrency</title></info>
<?dbhtml filename="using_concurrency.html"?>