From 5c24897577586d3db2fad081083a1f18f59a579c Mon Sep 17 00:00:00 2001 From: Jonathan Wakely Date: Mon, 10 Oct 2016 23:34:17 +0100 Subject: [PATCH] Improve docs on libstdc++ source-code layout * doc/xml/manual/appendix_contributing.xml (contrib.organization): Replace with nested elements. Update some more outdated text. * doc/html/*: Regenerate. From-SVN: r240952 --- libstdc++-v3/ChangeLog | 7 + .../doc/html/manual/source_organization.html | 188 ++++++++++----------- .../doc/xml/manual/appendix_contributing.xml | 162 ++++++++++++++---- 3 files changed, 222 insertions(+), 135 deletions(-) diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 411474c..5016ca7 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,10 @@ +2016-10-10 Jonathan Wakely + + * doc/xml/manual/appendix_contributing.xml (contrib.organization): + Replace with nested elements. Update + some more outdated text. + * doc/html/*: Regenerate. + 2016-10-10 Ville Voutilainen Make any's copy assignment operator exception-safe, diff --git a/libstdc++-v3/doc/html/manual/source_organization.html b/libstdc++-v3/doc/html/manual/source_organization.html index ef1e4f4..a956b50 100644 --- a/libstdc++-v3/doc/html/manual/source_organization.html +++ b/libstdc++-v3/doc/html/manual/source_organization.html @@ -5,105 +5,95 @@  Next

Directory Layout and Source Conventions

The libstdc++-v3 directory in the GCC sources contains the files needed to create the GNU C++ Library. -


-It has subdirectories:
-
-  doc
-    Files in HTML and text format that document usage, quirks of the
-    implementation, and contributor checklists.
-
-  include
-    All header files for the C++ library are within this directory,
-    modulo specific runtime-related files that are in the libsupc++
-    directory.
-
-    include/std
-      Files meant to be found by #include <name> directives in
-      standard-conforming user programs.
-
-    include/c
-      Headers intended to directly include standard C headers.
-      [NB: this can be enabled via --enable-cheaders=c]
-
-    include/c_global
-      Headers intended to include standard C headers in
-      the global namespace, and put select names into the std::
-      namespace.  [NB: this is the default, and is the same as
-      --enable-cheaders=c_global]
-
-    include/c_std
-      Headers intended to include standard C headers
-      already in namespace std, and put select names into the std::
-      namespace.  [NB: this is the same as
-      --enable-cheaders=c_std]
-
-    include/bits
-      Files included by standard headers and by other files in
-      the bits directory.
-
-    include/backward
-      Headers provided for backward compatibility, such as <iostream.h>.
-      They are not used in this library.
-
-    include/ext
-      Headers that define extensions to the standard library.  No
-      standard header refers to any of them.
-
-  scripts
-    Scripts that are used during the configure, build, make, or test
-    process.
-
-  src
-    Files that are used in constructing the library, but are not
-    installed.
-
-    src/c++98
-    Source files compiled using -std=gnu++98.
-
-    src/c++11
-    Source files compiled using -std=gnu++11.
-
-    src/filesystem
-    Source files for the Filesystem TS.
-
-    src/shared
-    Source code included by other files under both
-    src/c++98 and
-    src/c++11
-
-  testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]
-    Test programs are here, and may be used to begin to exercise the
-    library.  Support for "make check" and "make check-install" is
-    complete, and runs through all the subdirectories here when this
-    command is issued from the build directory.  Please note that
-    "make check" requires DejaGNU 1.4 or later to be installed.
-
-Other subdirectories contain variant versions of certain files
-that are meant to be copied or linked by the configure script.
-Currently these are:
-
-  config/abi
-  config/cpu
-  config/io
-  config/locale
-  config/os
-
-In addition, a subdirectory holds the convenience library libsupc++.
-
-  libsupc++
-    Contains the runtime library for C++, including exception
-    handling and memory allocation and deallocation, RTTI, terminate
-    handlers, etc.
-
-Note that glibc also has a bits/
-subdirectory.  We will either need to be careful not to collide with names
-in its bits/
-directory; or rename bits to (e.g.) cppbits.
-
-In files throughout the system, lines marked with an "XXX" indicate
-a bug or incompletely-implemented feature.  Lines marked "XXX MT"
-indicate a place that may require attention for multi-thread safety.
-  

Prev Up Next
Appendix A.  +

+It has subdirectories: +

doc
+ Files in HTML and text format that document usage, quirks of the + implementation, and contributor checklists. +
include
+ All header files for the C++ library are within this directory, + modulo specific runtime-related files that are in the libsupc++ + directory. + +
include/std
+ Files meant to be found by #include <name> directives + in standard-conforming user programs. +
include/c
+ Headers intended to directly include standard C headers. + [NB: this can be enabled via --enable-cheaders=c] +
include/c_global
+ Headers intended to include standard C headers in + the global namespace, and put select names into the std:: + namespace. [NB: this is the default, and is the same as + --enable-cheaders=c_global] +
include/c_std
+ Headers intended to include standard C headers + already in namespace std, and put select names into the std:: + namespace. [NB: this is the same as + --enable-cheaders=c_std] +
include/bits
+ Files included by standard headers and by other files in + the bits directory. +
include/backward
+ Headers provided for backward compatibility, such as + <backward/hash_map>. + They are not used in this library. +
include/ext
+ Headers that define extensions to the standard library. No + standard header refers to any of them, in theory (there are some + exceptions). +
scripts
+ Scripts that are used during the configure, build, make, or test + process. +
src
+ Files that are used in constructing the library, but are not + installed. + +
src/c++98
+ Source files compiled using -std=gnu++98. +
src/c++11
+ Source files compiled using -std=gnu++11. +
src/filesystem
+ Source files for the Filesystem TS. +
src/shared
+ Source code included by other files under both + src/c++98 and + src/c++11
testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]
+ Test programs are here, and may be used to begin to exercise the + library. Support for "make check" and "make check-install" is + complete, and runs through all the subdirectories here when this + command is issued from the build directory. Please note that + "make check" requires DejaGNU 1.4 or later to be installed. +

+Other subdirectories contain variant versions of certain files +that are meant to be copied or linked by the configure script. +Currently these are: +

config/abi
+config/allocator
+config/cpu
+config/io
+config/locale
+config/os
+

+

+In addition, a subdirectory holds the convenience library libsupc++. +

libsupc++
+ Contains the runtime library for C++, including exception + handling and memory allocation and deallocation, RTTI, terminate + handlers, etc. +

+Note that glibc also has a bits/ +subdirectory. We need to be careful not to collide with names in its +bits/ directory. For example +<bits/std_mutex.h> has to be +renamed from <bits/mutex.h>. +Another solution would be to rename bits +to (e.g.) cppbits. +

+In files throughout the system, lines marked with an "XXX" indicate +a bug or incompletely-implemented feature. Lines marked "XXX MT" +indicate a place that may require attention for multi-thread safety. +

Prev Up Next
Appendix A.  Contributing  Home Coding Style
\ No newline at end of file diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml index ee35dd9..1ee848f 100644 --- a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml +++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml @@ -203,105 +203,195 @@ GCC sources contains the files needed to create the GNU C++ Library. - + It has subdirectories: + - doc + + + doc + Files in HTML and text format that document usage, quirks of the implementation, and contributor checklists. + + - include + + include + All header files for the C++ library are within this directory, modulo specific runtime-related files that are in the libsupc++ directory. - include/std - Files meant to be found by #include <name> directives in - standard-conforming user programs. + + + include/std + + Files meant to be found by #include <name> directives + in standard-conforming user programs. + + - include/c + + include/c + Headers intended to directly include standard C headers. [NB: this can be enabled via ] + + - include/c_global + + include/c_global + Headers intended to include standard C headers in - the global namespace, and put select names into the std:: + the global namespace, and put select names into the std:: namespace. [NB: this is the default, and is the same as ] + + - include/c_std + + include/c_std + Headers intended to include standard C headers - already in namespace std, and put select names into the std:: + already in namespace std, and put select names into the std:: namespace. [NB: this is the same as ] + + - include/bits + + include/bits + Files included by standard headers and by other files in the bits directory. + + - include/backward - Headers provided for backward compatibility, such as <iostream.h>. + + include/backward + + Headers provided for backward compatibility, such as + <backward/hash_map>. They are not used in this library. + + - include/ext + + include/ext + Headers that define extensions to the standard library. No - standard header refers to any of them. - - scripts + standard header refers to any of them, in theory (there are some + exceptions). + + + + + + + + scripts + Scripts that are used during the configure, build, make, or test process. + + - src + + src + Files that are used in constructing the library, but are not installed. - src/c++98 + + + src/c++98 + Source files compiled using . + + - src/c++11 + + src/c++11 + Source files compiled using . + + - src/filesystem + + src/filesystem + Source files for the Filesystem TS. + + - src/shared + + src/shared + Source code included by other files under both src/c++98 and src/c++11 - - testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*] + + + + + + + + testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*] + Test programs are here, and may be used to begin to exercise the library. Support for "make check" and "make check-install" is complete, and runs through all the subdirectories here when this command is issued from the build directory. Please note that "make check" requires DejaGNU 1.4 or later to be installed. + + + + Other subdirectories contain variant versions of certain files that are meant to be copied or linked by the configure script. Currently these are: +config/abi +config/allocator +config/cpu +config/io +config/locale +config/os + + - config/abi - config/cpu - config/io - config/locale - config/os - + In addition, a subdirectory holds the convenience library libsupc++. + - libsupc++ + + + libsupc++ + Contains the runtime library for C++, including exception handling and memory allocation and deallocation, RTTI, terminate handlers, etc. + + + + Note that glibc also has a bits/ -subdirectory. We will either need to be careful not to collide with names -in its bits/ -directory; or rename bits to (e.g.) cppbits. +subdirectory. We need to be careful not to collide with names in its +bits/ directory. For example +<bits/std_mutex.h> has to be +renamed from <bits/mutex.h>. +Another solution would be to rename bits +to (e.g.) cppbits. + + In files throughout the system, lines marked with an "XXX" indicate a bug or incompletely-implemented feature. Lines marked "XXX MT" indicate a place that may require attention for multi-thread safety. - + -- 2.7.4