libstdc++: Document P1642 and extensions
Commit Message
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(-)
Comments
On Mon, 23 Jan 2023 at 12:49, Arsen Arsenović via Libstdc++
<libstdc++@gcc.gnu.org> wrote:
>
> 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.
Pushed to trunk, thanks!
>
> 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
>
@@ -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>
@@ -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>
@@ -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.,
@@ -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>