Re: [PATCH] libstdc++: Document P1642 and extensions

[Jonathan Wakely <jwakely@redhat.com>]

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
>