[PATCH] libstdc++: Document P1642 and extensions

["Arsen Arsenović" <arsen@aarsen.me>]

libstdc++-v3/ChangeLog:

	* doc/xml/manual/using.xml: Document newly-freestanding
	headers and the effect of the -ffreestanding flag.
	* doc/xml/manual/status_cxx2023.xml: Document P1642R11 as
	completed.
	* doc/xml/manual/configure.xml: Document that hosted installs
	respect __STDC_HOSTED__.
	* doc/xml/manual/test.xml: Document how to run tests in
	freestanding mode.
---
Afternoon,

This patch documents the freestanding changes that are to be included in
GCC 13.  This revision assumes the changes submitted earlier about
building a nearly empty library in freestanding, and simplifies the
linking section a bit as a result.  Due to -ffreestanding now working on
hosted builds of libstdc++, however, it still includes the advice of
``gcc -lsupc++'' for those that are using hosted builds.

Thanks in advance, have a great day.

 libstdc++-v3/doc/xml/manual/configure.xml     |  5 +-
 .../doc/xml/manual/status_cxx2023.xml         | 11 ++++
 libstdc++-v3/doc/xml/manual/test.xml          | 14 ++++
 libstdc++-v3/doc/xml/manual/using.xml         | 66 +++++++++++++++++--
 4 files changed, 88 insertions(+), 8 deletions(-)

diff --git a/libstdc++-v3/doc/xml/manual/configure.xml b/libstdc++-v3/doc/xml/manual/configure.xml
index 8b3b8cab8c7..7ff07aea886 100644
--- a/libstdc++-v3/doc/xml/manual/configure.xml
+++ b/libstdc++-v3/doc/xml/manual/configure.xml
@@ -362,7 +362,10 @@
      built.  The C++ Standard also describes a
      <emphasis>freestanding</emphasis> environment, in which only a
      minimal set of headers are provided.  This option builds such an
-     environment.
+     environment.  Note that a hosted library installs headers that still can
+     be used in non hosted environments, as the library checks for
+     <code>__STDC_HOSTED__</code>, however, a library configured with
+     <code>--disable-hosted-libstdcxx</code> will not install unusable headers.
      </para>
  </listitem></varlistentry>
 
diff --git a/libstdc++-v3/doc/xml/manual/status_cxx2023.xml b/libstdc++-v3/doc/xml/manual/status_cxx2023.xml
index 365df505f54..f23c64d6a29 100644
--- a/libstdc++-v3/doc/xml/manual/status_cxx2023.xml
+++ b/libstdc++-v3/doc/xml/manual/status_cxx2023.xml
@@ -566,6 +566,17 @@ or any notes about the implementation.
       <entry />
     </row>
 
+    <row>
+      <entry> Easy [utilities], [ranges], and [iterators] </entry>
+      <entry>
+        <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p1642r11.html">
+        P1642R11
+        </link>
+      </entry>
+      <entry align="center"> 13.1 </entry>
+      <entry />
+    </row>
+
   </tbody>
 </tgroup>
 </table>
diff --git a/libstdc++-v3/doc/xml/manual/test.xml b/libstdc++-v3/doc/xml/manual/test.xml
index 7bc6e339723..964c53d2632 100644
--- a/libstdc++-v3/doc/xml/manual/test.xml
+++ b/libstdc++-v3/doc/xml/manual/test.xml
@@ -350,6 +350,20 @@ cat 27_io/objects/char/3_xin.in | a.out</programlisting>
 </programlisting>
     </para>
 
+    <para>
+      If you wish to run the testsuite in a freestanding configuration, you can
+      pass the <code>-ffreestanding</code> flag.  Doing so will run the tests
+      that do not require hosted features, and emit a
+      <literal>UNSUPPORTED</literal> for those that do.  To run tests in the
+      freestanding configuration, you still need to build for a target you can
+      run programs on, e.g. <code>x86_64-pc-linux-gnu</code>, as a few tests
+      still execute the code they build.  Here's an example of how to run the
+      testsuite with libstdc++ in freestanding mode:
+      <programlisting>
+    make check-target-libstdc++-v3 RUNTESTFLAGS='--target_board=unix/-ffreestanding'
+      </programlisting>
+    </para>
+
     <para>
       You can run the tests with a compiler and library that have
       already been installed.  Make sure that the compiler (e.g.,
diff --git a/libstdc++-v3/doc/xml/manual/using.xml b/libstdc++-v3/doc/xml/manual/using.xml
index 9c444dd2997..7f011a6d931 100644
--- a/libstdc++-v3/doc/xml/manual/using.xml
+++ b/libstdc++-v3/doc/xml/manual/using.xml
@@ -132,6 +132,17 @@
       </entry>
     </row>
 
+    <row>
+      <entry><literal>-ffreestanding</literal></entry>
+      <entry>
+	Limits the library to its freestanding subset.  Headers that are
+	not supported in freestanding will emit a "This header is not available
+	in freestanding mode" error.
+	Headers that are in the freestanding subset partially will not expose
+	functionality that is not part of the freestanding subset.
+      </entry>
+    </row>
+
   </tbody>
 
 </tgroup>
@@ -1523,19 +1534,60 @@ namespace gtk
 	</listitem>
       </itemizedlist>
 
-      <para> There exists a library that offers runtime support for
-	just these headers, and it is called
-	<filename class="libraryfile">libsupc++.a</filename>. To use it, compile with <command>gcc</command> instead of <command>g++</command>, like so:
+      <para>
+	As of GCC 13, libstdc++ implements P1642, which brings in many more
+	headers, as well a quite a few ones not covered by the paper.
+
+	In general, if a feature does not require traditionally libc-provided
+	facilities, or dynamic memory allocation, it's enabled in the
+	freestanding subset.  In addition, if only a subset of a header
+	requires such features, it is partially included.  Some examples
+	include:
+      </para>
+
+      <itemizedlist>
+	<listitem>
+	  <para>
+	  <filename class="headerfile">string_view</filename>
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	  <filename class="headerfile">tuple</filename>
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	  <filename class="headerfile">bitset</filename>
+	  </para>
+	</listitem>
+      </itemizedlist>
+
+      <para>
+	Currently, this subset includes all of the iterator APIs (including the
+	ranges APIs) that do not involve streams, the entire C++ algorithms
+	library, excluding parallel algorithms, and a large part of the
+	utilities library.  This is on top of the headers included in the lists
+	above.
+      </para>
+
+      <para>
+	If you're using a libstdc++ configured for hosted environments, and
+	would like to not involve the libraries libstdc++ would depend on in
+	your programs, you will need to use <command>gcc</command> to link your
+	application with only <filename class="libraryfile">libsupc++.a</filename>,
+	like so:
       </para>
 
       <para>
-	<command>gcc foo.cc -lsupc++</command>
+	<command>gcc -ffreestanding foo.cc -lsupc++</command>
       </para>
 
       <para>
-	No attempt is made to verify that only the minimal subset
-	identified above is actually used at compile time. Violations
-	are diagnosed as undefined symbols at link time.
+	If you configured libstdc++ with
+	<code>--disable-hosted-libstdcxx</code>, however, you can use the
+	normal <command>g++</command> command to link, as this configuration
+	provides a (nearly) empty <filename class="libraryfile">libstdc++.a</filename>.
       </para>
     </section>
 
-- 
2.39.1