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