This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[patch] Backport libstdc++ documentation improvements


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 <jwakely@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">&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>
     </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 &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"?>

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]