On Mon, 23 Jan 2023 at 12:49, Arsen Arsenović via Libstdc++ <libstd...@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 >
