[committed] libstdc++: Update docs on build process and generated files

[Jonathan Wakely <jwakely@redhat.com>]

Pushed to trunk.

-- >8 --

There are several more sub-directories below 'src' now, with lots more
conveience libraries. Document them all as of GCC 14.

Also document how to regenerate the generated headers under include/bits
and how to update the tzdata.zi file.

libstdc++-v3/ChangeLog:

	* doc/xml/manual/build_hacking.xml: Document generated files.
	Update list of convenience libraries and sub-directories under
	the src directory.
	* doc/html/*: Regenerate.
---
 libstdc++-v3/doc/html/index.html              |   2 +-
 libstdc++-v3/doc/html/manual/appendix.html    |   2 +-
 .../doc/html/manual/appendix_porting.html     | 119 +++++++++++--
 libstdc++-v3/doc/html/manual/index.html       |   2 +-
 libstdc++-v3/doc/xml/manual/build_hacking.xml | 164 ++++++++++++++++--
 5 files changed, 262 insertions(+), 27 deletions(-)

diff --git a/libstdc++-v3/doc/xml/manual/build_hacking.xml b/libstdc++-v3/doc/xml/manual/build_hacking.xml
index 36f659cea4b..077c0632a79 100644
--- a/libstdc++-v3/doc/xml/manual/build_hacking.xml
+++ b/libstdc++-v3/doc/xml/manual/build_hacking.xml
@@ -554,9 +554,9 @@ baseline file.
      make src
    </para>
    <para>
-     Generates two convenience libraries, one for C++98 and one for
-     C++11, various compatibility files for shared and static
-     libraries, and then collects all the generated bits and creates
+     Generates several convenience libraries,
+     various compatibility files for shared and static libraries,
+     and then collects all the generated bits and creates
      the final libstdc++ libraries.
   </para>
 <orderedlist>
@@ -566,8 +566,8 @@ baseline file.
    </para>
    <para>
      Generates a libtool convenience library,
-     <filename>libc++98convenience</filename> with language-support
-     routines. Uses the <option>-std=gnu++98</option> dialect.
+     <filename>libc++98convenience</filename> with the library components
+     defined by C++98. Uses the <option>-std=gnu++98</option> dialect.
    </para>
  </listitem>
  <listitem>
@@ -576,8 +576,84 @@ baseline file.
    </para>
    <para>
      Generates a libtool convenience library,
-     <filename>libc++11convenience</filename> with language-support
-     routines. Uses the <option>-std=gnu++11</option> dialect.
+     <filename>libc++11convenience</filename> with the library components
+     that were added or changed in C++11.
+     Uses the <option>-std=gnu++11</option> dialect.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+     make src/c++17
+   </para>
+   <para>
+     Generates a libtool convenience library,
+     <filename>libc++17convenience</filename> with the library components
+     that were added or changed in C++17.
+     Uses the <option>-std=gnu++17</option> dialect.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+     make src/c++20
+   </para>
+   <para>
+     Generates a libtool convenience library,
+     <filename>libc++20convenience</filename> with the library components
+     that were added or changed in C++20.
+     Uses the <option>-std=gnu++20</option> dialect.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+     make src/c++23
+   </para>
+   <para>
+     Generates a libtool convenience library,
+     <filename>libc++23convenience</filename> with the library components
+     that were added or changed in C++23.
+     At the time of writing (GCC 14) this convenience library is included
+     in <filename>libstdc++exp.a</filename> and not in the final
+     <filename>libstdc++</filename> libraries.
+     Uses the <option>-std=gnu++23</option> dialect.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+     make src/filesystem
+   </para>
+   <para>
+     Generates a libtool convenience library,
+     <filename>libstdc++fsconvenience</filename>,
+     and a standalone static library,
+     <filename>libstdc++fs.a</filename>.
+     These contain definitions of the Filesystem TS extensions.
+     Uses the <option>-std=gnu++17</option> dialect.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+     make src/libbacktrace
+   </para>
+   <para>
+     Generates a libtool convenience library,
+     <filename>libstdc++_libbacktrace</filename>,
+     containing the libbacktrace definitions used by the C++23
+     <classname>std::stacktrace</classname> feature.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+     make src/experimental
+   </para>
+   <para>
+     Generates a standalone static library,
+     <filename>libstdc++exp.a</filename>, containing the symbol definitions
+     for experimental features and extensions. This collects the convenience
+     libraries <filename>libstdc++fsconvenience</filename>,
+     <filename>libstdc++_libbacktrace</filename>, and
+     (at the time of writing) <filename>libc++23convenience</filename>
+     and combines them into one.
+     Uses the <option>-std=gnu++17</option> dialect.
    </para>
  </listitem>
  <listitem>
@@ -591,10 +667,11 @@ baseline file.
    </para>
 
    <para>
-     Then, collects all the generated convenience libraries, adds in
-     any required compatibility objects, and creates the final shared
-     and static libraries: <filename>libstdc++.so</filename> and
-     <filename>libstdc++.a</filename>.
+     Then, collects all the generated convenience libraries that weren't
+     added to <filename>libstdc++exp.a</filename>,
+     adds in any required compatibility objects,
+     and creates the final shared and static libraries:
+     <filename>libstdc++.so</filename> and <filename>libstdc++.a</filename>.
    </para>
 
  </listitem>
@@ -604,4 +681,69 @@ baseline file.
 
 </section> <!-- make -->
 
+<section xml:id="build_hacking.generated"><info><title>Generated files</title></info>
+
+<para>
+  Some files in the libstdc++ source tree are auto-generated from other files.
+  In general, these are not regenerated automatically, so it must be done
+  manually when the files they depend on are updated.
+</para>
+
+<itemizedlist>
+ <listitem>
+   <para>
+   The header file
+   <filename class="headerfile">include/bits/version.h</filename>
+   is generated from <filename>version.def</filename> and
+   <filename>version.tpl</filename> in the same directory.
+   After editing those files, either run <command>autogen version.def</command>
+   in the <filename class="directory">include</filename> directory of the
+   source tree, or run <command>make update-version</command> in the
+   <filename class="directory">include</filename> directory of the build tree.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+   The header file
+   <filename class="headerfile">include/bits/unicode-data.h</filename>
+   is generated by the Python script
+   <filename>../contrib/unicode/gen_libstdcxx_unicode_data.py</filename>
+   using data files in the same directory. The script contains information
+   on which data files it uses and how to update them.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+   The header file
+   <filename class="headerfile">include/bits/text_encoding-data.h</filename>
+   is generated by the Python script
+   <filename>scripts/gen_text_encoding_data.py</filename>
+   using the CSV file <link xmlns:xlink="http://www.w3.org/1999/xlink"
+     xlink:href="https://www.iana.org/assignments/character-sets/character-sets-1.csv"/>
+   from the <link xmlns:xlink="http://www.w3.org/1999/xlink"
+     xlink:href="https://www.iana.org/time-zones">IANA Character Sets</link>
+   registry.
+   </para>
+ </listitem>
+ <listitem>
+   <para>
+   The data file <filename>src/c++20/tzdata.zi</filename> is copied verbatim
+   from the
+   <link xmlns:xlink="http://www.w3.org/1999/xlink"
+     xlink:href="https://www.iana.org/time-zones">IANA Time Zone Database</link>
+   (the latest version can be downloaded from
+   <link xmlns:xlink="http://www.w3.org/1999/xlink"
+     xlink:href="https://data.iana.org/time-zones/tzdb/tzdata.zi"/>).
+   Libstdc++ uses this data file to populate a
+   <classname>std::chrono::tzdb</classname> object in case the system does not
+   provide a copy of the file.
+   See <xref linkend="manual.intro.setup.configure"/> for the
+   <code>--with-libstdcxx-zoneinfo</code> option that determines whether
+   this file is used.
+   </para>
+ </listitem>
+</itemizedlist>
+
+</section> <!-- Generated files -->
+
 </section>
-- 
2.44.0