From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: by sourceware.org (Postfix, from userid 2181) id BEE573858418; Tue, 19 Mar 2024 15:34:10 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org BEE573858418 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1710862450; bh=kyywkTo/SE88piyIFFYUJ6RK/sGKh1UPfIAVbhYCeJg=; h=From:To:Subject:Date:From; b=LFvEBEKMjRTXmtIKA16QwJDT+hka7iRYrJi3C7ibGHuVnN4NJa/LnMKUbvfwUlDdO 6/opDZ6HY0MlCVQRR5NWJAatQ1LLfY+7UCrF28MQT062wmxttuonGq+Oggj6nxD+Py fUd2lbIv54e6kHK2bNsIW23xP8JQkETWS5FYbiSo= MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain; charset="utf-8" From: Jonathan Wakely To: gcc-cvs@gcc.gnu.org, libstdc++-cvs@gcc.gnu.org Subject: [gcc r14-9548] libstdc++: Update docs on build process and generated files X-Act-Checkin: gcc X-Git-Author: Jonathan Wakely X-Git-Refname: refs/heads/master X-Git-Oldrev: ef2efc53fd89920a864fa076cabe03873b7f1bdc X-Git-Newrev: d1b8c2237d7c6a2d52ea5a852a9a11ad426496f3 Message-Id: <20240319153410.BEE573858418@sourceware.org> Date: Tue, 19 Mar 2024 15:34:10 +0000 (GMT) List-Id: https://gcc.gnu.org/g:d1b8c2237d7c6a2d52ea5a852a9a11ad426496f3 commit r14-9548-gd1b8c2237d7c6a2d52ea5a852a9a11ad426496f3 Author: Jonathan Wakely Date: Tue Mar 19 12:58:27 2024 +0000 libstdc++: Update docs on build process and generated files 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. Diff: --- libstdc++-v3/doc/html/index.html | 2 +- libstdc++-v3/doc/html/manual/appendix.html | 2 +- libstdc++-v3/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/html/index.html b/libstdc++-v3/doc/html/index.html index f9288e471f4..395908f17a1 100644 --- a/libstdc++-v3/doc/html/index.html +++ b/libstdc++-v3/doc/html/index.html @@ -135,7 +135,7 @@
Contributor Checklist
Reading
Assignment
Getting Sources
Submitting Patches
Directory Layout and Source Conventions
Coding Style
Bad Identifiers
By Example
Design Notes
B. Porting and Maintenance -
Configure and Build Hacking
Prerequisites
Overview
General Process
What Comes from Where
Configure
Storing Information in non-AC files (like configure.host)
Coding and Commenting Conventions
The acinclude.m4 layout
GLIBCXX_ENABLE, the --enable maker
Shared Library Versioning
Make
Writing and Generating Documentation
Introduction
Generating Documentation
Doxygen
Prerequisites
Generating the Doxygen Files
Debugging Generation
Markup
Docbook
Prerequisites
Generating the DocBook Files
Debugging Generation
Editing and Validation
File Organization and Basics
Markup By Example
Porting to New Hardware or Operating Systems
Operating System
CPU
Character Types
Thread Safety
Numeric Limits
Libtool
Testing
Test Organization
Directory Layout
Naming Conventions
Running the Testsuite
Basic
Variations
Permutations
Writing a new test case
Examples of Test Directives
Directives Specific to Libstdc++ Tests
Test Harness and Utilities
DejaGnu Harness Details
Utilities
Special Topics
+
Configure and Build Hacking
Prerequisites
Overview
General Process
What Comes from Where
Configure
Storing Information in non-AC files (like configure.host)
Coding and Commenting Conventions
The acinclude.m4 layout
GLIBCXX_ENABLE, the --enable maker
Shared Library Versioning
Make
Generated files
Writing and Generating Documentation
Introduction
Generating Documentation
Doxygen
Prerequisites
Generating the Doxygen Files
Debugging Generation
Markup
Docbook
Prerequisites
Generating the DocBook Files
Debugging Generation
Editing and Validation
File Organization and Basics
Markup By Example
Porting to New Hardware or Operating Systems
Operating System
CPU
Character Types
Thread Safety
Numeric Limits
Libtool
Testing
Test Organization
Directory Layout
Naming Conventions
Running the Testsuite
Basic
Variations
Permutations
Writing a new test case
Examples of Test Directives
Directives Specific to Libstdc++ Tests
Test Harness and Utilities
DejaGnu Harness Details
Utilities
Special Topics
Qualifying Exception Safety Guarantees
Overview
diff --git a/libstdc++-v3/doc/html/manual/appendix.html b/libstdc++-v3/doc/html/manual/appendix.html index 03746f90269..affd5839f43 100644 --- a/libstdc++-v3/doc/html/manual/appendix.html +++ b/libstdc++-v3/doc/html/manual/appendix.html @@ -9,7 +9,7 @@
Contributor Checklist
Reading
Assignment
Getting Sources
Submitting Patches
Directory Layout and Source Conventions
Coding Style
Bad Identifiers
By Example
Design Notes
B. Porting and Maintenance -
Configure and Build Hacking
Prerequisites
Overview
General Process
What Comes from Where
Configure
Storing Information in non-AC files (like configure.host)
Coding and Commenting Conventions
The acinclude.m4 layout
GLIBCXX_ENABLE, the --enable maker
Shared Library Versioning
Make
Writing and Generating Documentation
Introduction
Generating Documentation
Doxygen
Prerequisites
Generating the Doxygen Files
Debugging Generation
Markup
Docbook
Prerequisites
Generating the DocBook Files
Debugging Generation
Editing and Validation
File Organization and Basics
Markup By Example
Porting to New Hardware or Operating Systems
Operating System
CPU
Character Types
Thread Safety
Numeric Limits
Libtool
Testing
Test Organization
Directory Layout
Naming Conventions
Running the Testsuite
Basic
Variations
Permutations
Writing a new test case
Examples of Test Directives
Directives Specific to Libstdc++ Tests
Test Harness and Utilities
DejaGnu Harness Details
Utilities
Special Topics
+
Configure and Build Hacking
Prerequisites
Overview
General Process
What Comes from Where
Configure
Storing Information in non-AC files (like configure.host)
Coding and Commenting Conventions
The acinclude.m4 layout
GLIBCXX_ENABLE, the --enable maker
Shared Library Versioning
Make
Generated files
Writing and Generating Documentation
Introduction
Generating Documentation
Doxygen
Prerequisites
Generating the Doxygen Files
Debugging Generation
Markup
Docbook
Prerequisites
Generating the DocBook Files
Debugging Generation
Editing and Validation
File Organization and Basics
Markup By Example
Porting to New Hardware or Operating Systems
Operating System
CPU
Character Types
Thread Safety
Numeric Limits
Libtool
Testing
Test Organization
Directory Layout
Naming Conventions
Running the Testsuite
Basic
Variations
Permutations
Writing a new test case
Examples of Test Directives
Directives Specific to Libstdc++ Tests
Test Harness and Utilities
DejaGnu Harness Details
Utilities
Special Topics
Qualifying Exception Safety Guarantees
Overview
diff --git a/libstdc++-v3/doc/html/manual/appendix_porting.html b/libstdc++-v3/doc/html/manual/appendix_porting.html index 8f2824c44b0..5d8d5da0bf9 100644 --- a/libstdc++-v3/doc/html/manual/appendix_porting.html +++ b/libstdc++-v3/doc/html/manual/appendix_porting.html @@ -7,7 +7,7 @@  Next

Porting and Maintenance -

Table of Contents

Configure and Build Hacking
Prerequisites
Overview
General Process
What Comes from Where
Configure
Storing Information in non-AC files (like configure.host)
Coding and Commenting Conventions
The acinclude.m4 layout
GLIBCXX_ENABLE, the --enable maker
Shared Library Versioning
Make
Writing and Generating Documentation
Introduction
Generating Documentation
Doxygen
Prerequisites
Generating the Doxygen Files
Debugging Generation
Markup
Docbook
Prerequisites
Generating the DocBook Files
Debugging Generation
Editing and Validation
File Organization and Basics
Markup By Example
Porting to New Hardware or Operating Systems
Operating System
CPU
Character Types
Thread Safety
Numeric Limits
Libtool
Testing
Test Organization
Directory Layout
Naming Conventions
Running the Testsuite
Basic
Variations
Permutations
Writing a new test case
Examples of Test Directives
Directives Specific to Libstdc++ Tests
Test Harness and Utilities
DejaGnu Harness Details
Utilities
Special Topics
+

Table of Contents

Configure and Build Hacking
Prerequisites
Overview
General Process
What Comes from Where
Configure
Storing Information in non-AC files (like configure.host)
Coding and Commenting Conventions
The acinclude.m4 layout
GLIBCXX_ENABLE, the --enable maker
Shared Library Versioning
Make
Generated files
Writing and Generating Documentation
Introduction
Generating Documentation
Doxygen
Prerequisites
Generating the Doxygen Files
Debugging Generation
Markup
Docbook
Prerequisites
Generating the DocBook Files
Debugging Generation
Editing and Validation
File Organization and Basics
Markup By Example
Porting to New Hardware or Operating Systems
Operating System
CPU
Character Types
Thread Safety
Numeric Limits
Libtool
Testing
Test Organization
Directory Layout
Naming Conventions
Running the Testsuite
Basic
Variations
Permutations
Writing a new test case
Examples of Test Directives
Directives Specific to Libstdc++ Tests
Test Harness and Utilities
DejaGnu Harness Details
Utilities
Special Topics
Qualifying Exception Safety Guarantees
Overview
@@ -377,22 +377,74 @@ baseline file.

  • make src

    - 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.

    1. make src/c++98

      Generates a libtool convenience library, - libc++98convenience with language-support - routines. Uses the -std=gnu++98 dialect. + libc++98convenience with the library components + defined by C++98. Uses the -std=gnu++98 dialect.

    2. make src/c++11

      Generates a libtool convenience library, - libc++11convenience with language-support - routines. Uses the -std=gnu++11 dialect. + libc++11convenience with the library components + that were added or changed in C++11. + Uses the -std=gnu++11 dialect. +

    3. + make src/c++17 +

      + Generates a libtool convenience library, + libc++17convenience with the library components + that were added or changed in C++17. + Uses the -std=gnu++17 dialect. +

    4. + make src/c++20 +

      + Generates a libtool convenience library, + libc++20convenience with the library components + that were added or changed in C++20. + Uses the -std=gnu++20 dialect. +

    5. + make src/c++23 +

      + Generates a libtool convenience library, + libc++23convenience 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 libstdc++exp.a and not in the final + libstdc++ libraries. + Uses the -std=gnu++23 dialect. +

    6. + make src/filesystem +

      + Generates a libtool convenience library, + libstdc++fsconvenience, + and a standalone static library, + libstdc++fs.a. + These contain definitions of the Filesystem TS extensions. + Uses the -std=gnu++17 dialect. +

    7. + make src/libbacktrace +

      + Generates a libtool convenience library, + libstdc++_libbacktrace, + containing the libbacktrace definitions used by the C++23 + std::stacktrace feature. +

    8. + make src/experimental +

      + Generates a standalone static library, + libstdc++exp.a, containing the symbol definitions + for experimental features and extensions. This collects the convenience + libraries libstdc++fsconvenience, + libstdc++_libbacktrace, and + (at the time of writing) libc++23convenience + and combines them into one. + Uses the -std=gnu++17 dialect.

    9. make src

      @@ -400,8 +452,49 @@ baseline file. libraries. Shared-only code is seggregated at compile-time via the macro _GLIBCXX_SHARED.

      - Then, collects all the generated convenience libraries, adds in - any required compatibility objects, and creates the final shared - and static libraries: libstdc++.so and - libstdc++.a. -

    • Prev Up Next
    Design Notes Home Writing and Generating Documentation
    \ No newline at end of file + Then, collects all the generated convenience libraries that weren't + added to libstdc++exp.a, + adds in any required compatibility objects, + and creates the final shared and static libraries: + libstdc++.so and libstdc++.a. +

    Generated files

    + 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. +

    • + The header file + include/bits/version.h + is generated from version.def and + version.tpl in the same directory. + After editing those files, either run autogen version.def + in the include directory of the + source tree, or run make update-version in the + include directory of the build tree. +

    • + The header file + include/bits/unicode-data.h + is generated by the Python script + ../contrib/unicode/gen_libstdcxx_unicode_data.py + using data files in the same directory. The script contains information + on which data files it uses and how to update them. +

    • + The header file + include/bits/text_encoding-data.h + is generated by the Python script + scripts/gen_text_encoding_data.py + using the CSV file https://www.iana.org/assignments/character-sets/character-sets-1.csv + from the IANA Character Sets + registry. +

    • + The data file src/c++20/tzdata.zi is copied verbatim + from the + IANA Time Zone Database + (the latest version can be downloaded from + https://data.iana.org/time-zones/tzdb/tzdata.zi). + Libstdc++ uses this data file to populate a + std::chrono::tzdb object in case the system does not + provide a copy of the file. + See Configuring for the + --with-libstdcxx-zoneinfo option that determines whether + this file is used. +

    Prev Up Next
    Design Notes Home Writing and Generating Documentation
    \ No newline at end of file diff --git a/libstdc++-v3/doc/html/manual/index.html b/libstdc++-v3/doc/html/manual/index.html index ed2aee54cea..e961efef97b 100644 --- a/libstdc++-v3/doc/html/manual/index.html +++ b/libstdc++-v3/doc/html/manual/index.html @@ -116,7 +116,7 @@
    Contributor Checklist
    Reading
    Assignment
    Getting Sources
    Submitting Patches
    Directory Layout and Source Conventions
    Coding Style
    Bad Identifiers
    By Example
    Design Notes
    B. Porting and Maintenance -
    Configure and Build Hacking
    Prerequisites
    Overview
    General Process
    What Comes from Where
    Configure
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Shared Library Versioning
    Make
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Prerequisites
    Generating the Doxygen Files
    Debugging Generation
    Markup
    Docbook
    Prerequisites
    Generating the DocBook Files
    Debugging Generation
    Editing and Validation
    File Organization and Basics
    Markup By Example
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Testing
    Test Organization
    Directory Layout
    Naming Conventions
    Running the Testsuite
    Basic
    Variations
    Permutations
    Writing a new test case
    Examples of Test Directives
    Directives Specific to Libstdc++ Tests
    Test Harness and Utilities
    DejaGnu Harness Details
    Utilities
    Special Topics
    +
    Configure and Build Hacking
    Prerequisites
    Overview
    General Process
    What Comes from Where
    Configure
    Storing Information in non-AC files (like configure.host)
    Coding and Commenting Conventions
    The acinclude.m4 layout
    GLIBCXX_ENABLE, the --enable maker
    Shared Library Versioning
    Make
    Generated files
    Writing and Generating Documentation
    Introduction
    Generating Documentation
    Doxygen
    Prerequisites
    Generating the Doxygen Files
    Debugging Generation
    Markup
    Docbook
    Prerequisites
    Generating the DocBook Files
    Debugging Generation
    Editing and Validation
    File Organization and Basics
    Markup By Example
    Porting to New Hardware or Operating Systems
    Operating System
    CPU
    Character Types
    Thread Safety
    Numeric Limits
    Libtool
    Testing
    Test Organization
    Directory Layout
    Naming Conventions
    Running the Testsuite
    Basic
    Variations
    Permutations
    Writing a new test case
    Examples of Test Directives
    Directives Specific to Libstdc++ Tests
    Test Harness and Utilities
    DejaGnu Harness Details
    Utilities
    Special Topics
    Qualifying Exception Safety Guarantees
    Overview
    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 - 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. @@ -566,8 +566,8 @@ baseline file. Generates a libtool convenience library, - libc++98convenience with language-support - routines. Uses the dialect. + libc++98convenience with the library components + defined by C++98. Uses the dialect. @@ -576,8 +576,84 @@ baseline file. Generates a libtool convenience library, - libc++11convenience with language-support - routines. Uses the dialect. + libc++11convenience with the library components + that were added or changed in C++11. + Uses the dialect. + + + + + make src/c++17 + + + Generates a libtool convenience library, + libc++17convenience with the library components + that were added or changed in C++17. + Uses the dialect. + + + + + make src/c++20 + + + Generates a libtool convenience library, + libc++20convenience with the library components + that were added or changed in C++20. + Uses the dialect. + + + + + make src/c++23 + + + Generates a libtool convenience library, + libc++23convenience 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 libstdc++exp.a and not in the final + libstdc++ libraries. + Uses the dialect. + + + + + make src/filesystem + + + Generates a libtool convenience library, + libstdc++fsconvenience, + and a standalone static library, + libstdc++fs.a. + These contain definitions of the Filesystem TS extensions. + Uses the dialect. + + + + + make src/libbacktrace + + + Generates a libtool convenience library, + libstdc++_libbacktrace, + containing the libbacktrace definitions used by the C++23 + std::stacktrace feature. + + + + + make src/experimental + + + Generates a standalone static library, + libstdc++exp.a, containing the symbol definitions + for experimental features and extensions. This collects the convenience + libraries libstdc++fsconvenience, + libstdc++_libbacktrace, and + (at the time of writing) libc++23convenience + and combines them into one. + Uses the dialect. @@ -591,10 +667,11 @@ baseline file. - Then, collects all the generated convenience libraries, adds in - any required compatibility objects, and creates the final shared - and static libraries: libstdc++.so and - libstdc++.a. + Then, collects all the generated convenience libraries that weren't + added to libstdc++exp.a, + adds in any required compatibility objects, + and creates the final shared and static libraries: + libstdc++.so and libstdc++.a. @@ -604,4 +681,69 @@ baseline file. +
    Generated files + + + 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. + + + + + + The header file + include/bits/version.h + is generated from version.def and + version.tpl in the same directory. + After editing those files, either run autogen version.def + in the include directory of the + source tree, or run make update-version in the + include directory of the build tree. + + + + + The header file + include/bits/unicode-data.h + is generated by the Python script + ../contrib/unicode/gen_libstdcxx_unicode_data.py + using data files in the same directory. The script contains information + on which data files it uses and how to update them. + + + + + The header file + include/bits/text_encoding-data.h + is generated by the Python script + scripts/gen_text_encoding_data.py + using the CSV file + from the IANA Character Sets + registry. + + + + + The data file src/c++20/tzdata.zi is copied verbatim + from the + IANA Time Zone Database + (the latest version can be downloaded from + ). + Libstdc++ uses this data file to populate a + std::chrono::tzdb object in case the system does not + provide a copy of the file. + See for the + --with-libstdcxx-zoneinfo option that determines whether + this file is used. + + + + +
    +