This syncs the gcc-5-branch docs with those on trunk (which I should
have done before the 5.3 release, sorry).
Committed to gcc-5-branch.
commit 677f6293e1c961ba75fba97509b613f28b4afc33
Author: Jonathan Wakely <jwak...@redhat.com>
Date: Tue Dec 8 13:41:50 2015 +0000
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.
diff --git a/libstdc++-v3/doc/xml/manual/abi.xml b/libstdc++-v3/doc/xml/manual/abi.xml
index b399f71..a2ed57b 100644
--- a/libstdc++-v3/doc/xml/manual/abi.xml
+++ b/libstdc++-v3/doc/xml/manual/abi.xml
@@ -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>
diff --git a/libstdc++-v3/doc/xml/manual/configure.xml b/libstdc++-v3/doc/xml/manual/configure.xml
index f6a5551..7b09d01 100644
--- a/libstdc++-v3/doc/xml/manual/configure.xml
+++ b/libstdc++-v3/doc/xml/manual/configure.xml
@@ -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>
diff --git a/libstdc++-v3/doc/xml/manual/diagnostics.xml b/libstdc++-v3/doc/xml/manual/diagnostics.xml
index 99206e9..88ed2e2 100644
--- a/libstdc++-v3/doc/xml/manual/diagnostics.xml
+++ b/libstdc++-v3/doc/xml/manual/diagnostics.xml
@@ -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.
diff --git a/libstdc++-v3/doc/xml/manual/extensions.xml b/libstdc++-v3/doc/xml/manual/extensions.xml
index c4120c9..41b1a80 100644
--- a/libstdc++-v3/doc/xml/manual/extensions.xml
+++ b/libstdc++-v3/doc/xml/manual/extensions.xml
@@ -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>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
index 965df13..16ea8c4 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2011.xml
@@ -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>
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2014.xml b/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
index fc32995..6f1fbe5 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2014.xml
@@ -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>
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index ba90666..6228a86 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -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>
@@ -52,6 +57,16 @@
</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>
</row>
@@ -80,6 +95,14 @@
</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"><experimental/filesystem></filename>.
+ </entry>
+ </row>
+
+ <row>
<entry><literal>-fopenmp</literal></entry>
<entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry>
</row>
@@ -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 <stdtr1c++.h>, 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
+<stdtr1c++.h>).
</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"><experimental/filesystem></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"><experimental/xxx></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"?>
