* [PATCH] Update docs on libstdc++ source-code layout
@ 2016-10-10 18:57 Jonathan Wakely
2016-10-10 22:35 ` Jonathan Wakely
0 siblings, 1 reply; 2+ messages in thread
From: Jonathan Wakely @ 2016-10-10 18:57 UTC (permalink / raw)
To: libstdc++, gcc-patches
[-- Attachment #1: Type: text/plain, Size: 305 bytes --]
Self-explanatory updates to the docs, and regenerating after the
various recent changes.
* doc/xml/manual/appendix_contributing.xml (contrib.organization):
Describe other subdirectories and add markup. Remove outdated
reference to check-script target.
* doc/html/*: Regenerate.
Committed to trunk.
[-- Attachment #2: patch.txt --]
[-- Type: text/plain, Size: 6221 bytes --]
commit 40bed069fd9497174b398c683d684fc825867cb7
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Mon Oct 10 19:54:50 2016 +0100
Update docs on libstdc++ source-code layout
* doc/xml/manual/appendix_contributing.xml (contrib.organization):
Describe other subdirectories and add markup. Remove outdated
reference to check-script target.
* doc/html/*: Regenerate.
diff --git a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
index d7df13c..ee35dd9 100644
--- a/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
+++ b/libstdc++-v3/doc/xml/manual/appendix_contributing.xml
@@ -199,91 +199,104 @@
<para>
- The unpacked source directory of libstdc++ contains the files
- needed to create the GNU C++ Library.
+ The <filename class="directory">libstdc++-v3</filename> directory in the
+ GCC sources contains the files needed to create the GNU C++ Library.
</para>
<literallayout class="normal">
It has subdirectories:
- doc
+ <filename class="directory">doc</filename>
Files in HTML and text format that document usage, quirks of the
implementation, and contributor checklists.
- include
+ <filename class="directory">include</filename>
All header files for the C++ library are within this directory,
modulo specific runtime-related files that are in the libsupc++
directory.
- include/std
+ <filename class="directory">include/std</filename>
Files meant to be found by #include <name> directives in
standard-conforming user programs.
- include/c
+ <filename class="directory">include/c</filename>
Headers intended to directly include standard C headers.
- [NB: this can be enabled via --enable-cheaders=c]
+ [NB: this can be enabled via <option>--enable-cheaders=c</option>]
- include/c_global
+ <filename class="directory">include/c_global</filename>
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]
+ <option>--enable-cheaders=c_global</option>]
- include/c_std
+ <filename class="directory">include/c_std</filename>
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]
+ namespace. [NB: this is the same as
+ <option>--enable-cheaders=c_std</option>]
- include/bits
+ <filename class="directory">include/bits</filename>
Files included by standard headers and by other files in
the bits directory.
- include/backward
+ <filename class="directory">include/backward</filename>
Headers provided for backward compatibility, such as <iostream.h>.
They are not used in this library.
- include/ext
+ <filename class="directory">include/ext</filename>
Headers that define extensions to the standard library. No
standard header refers to any of them.
- scripts
+ <filename class="directory">scripts</filename>
Scripts that are used during the configure, build, make, or test
process.
- src
+ <filename class="directory">src</filename>
Files that are used in constructing the library, but are not
installed.
- testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]
+ <filename class="directory">src/c++98</filename>
+ Source files compiled using <option>-std=gnu++98</option>.
+
+ <filename class="directory">src/c++11</filename>
+ Source files compiled using <option>-std=gnu++11</option>.
+
+ <filename class="directory">src/filesystem</filename>
+ Source files for the Filesystem TS.
+
+ <filename class="directory">src/shared</filename>
+ Source code included by other files under both
+ <filename class="directory">src/c++98</filename> and
+ <filename class="directory">src/c++11</filename>
+
+ <filename class="directory">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</filename>
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. Please
- note that "make check-script" calls the script mkcheck, which
- requires bash, and which may need the paths to bash adjusted to
- work properly, as /bin/bash is assumed.
+ "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
+ <filename class="directory">config/abi</filename>
+ <filename class="directory">config/cpu</filename>
+ <filename class="directory">config/io</filename>
+ <filename class="directory">config/locale</filename>
+ <filename class="directory">config/os</filename>
In addition, a subdirectory holds the convenience library libsupc++.
- libsupc++
+ <filename class="directory">libsupc++</filename>
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/.
+Note that glibc also has a <filename class="directory">bits/</filename>
+subdirectory. We will either need to be careful not to collide with names
+in its <filename class="directory">bits/</filename>
+directory; or rename <filename class="directory">bits</filename> to (e.g.) <filename class="directory">cppbits</filename>.
In files throughout the system, lines marked with an "XXX" indicate
a bug or incompletely-implemented feature. Lines marked "XXX MT"
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: [PATCH] Update docs on libstdc++ source-code layout
2016-10-10 18:57 [PATCH] Update docs on libstdc++ source-code layout Jonathan Wakely
@ 2016-10-10 22:35 ` Jonathan Wakely
0 siblings, 0 replies; 2+ messages in thread
From: Jonathan Wakely @ 2016-10-10 22:35 UTC (permalink / raw)
To: libstdc++, gcc-patches
[-- Attachment #1: Type: text/plain, Size: 452 bytes --]
On 10/10/16 19:57 +0100, Jonathan Wakely wrote:
>Self-explanatory updates to the docs, and regenerating after the
>various recent changes.
>
> * doc/xml/manual/appendix_contributing.xml (contrib.organization):
> Describe other subdirectories and add markup. Remove outdated
> reference to check-script target.
> * doc/html/*: Regenerate.
>
>Committed to trunk.
Some further markup improvements and corrections for outdated text.
Committed to trunk.
[-- Attachment #2: patch.txt --]
[-- Type: text/x-patch, Size: 9170 bytes --]
commit ae505b77cef62a4ee79dd374e75d88c223e945ed
Author: Jonathan Wakely <jwakely@redhat.com>
Date: Mon Oct 10 23:33:15 2016 +0100
Improve docs on libstdc++ source-code layout
* doc/xml/manual/appendix_contributing.xml (contrib.organization):
Replace <literallayout> with nested <variablelist> elements. Update
some more outdated text.
* doc/html/*: Regenerate.
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.
</para>
- <literallayout class="normal">
+<para>
It has subdirectories:
+</para>
- <filename class="directory">doc</filename>
+<variablelist>
+ <varlistentry>
+ <term><filename class="directory">doc</filename></term>
+ <listitem>
Files in HTML and text format that document usage, quirks of the
implementation, and contributor checklists.
+ </listitem>
+ </varlistentry>
- <filename class="directory">include</filename>
+ <varlistentry>
+ <term><filename class="directory">include</filename></term>
+ <listitem>
All header files for the C++ library are within this directory,
modulo specific runtime-related files that are in the libsupc++
directory.
- <filename class="directory">include/std</filename>
- Files meant to be found by #include <name> directives in
- standard-conforming user programs.
+ <variablelist>
+ <varlistentry>
+ <term><filename class="directory">include/std</filename></term>
+ <listitem>
+ Files meant to be found by <code>#include <name></code> directives
+ in standard-conforming user programs.
+ </listitem>
+ </varlistentry>
- <filename class="directory">include/c</filename>
+ <varlistentry>
+ <term><filename class="directory">include/c</filename></term>
+ <listitem>
Headers intended to directly include standard C headers.
[NB: this can be enabled via <option>--enable-cheaders=c</option>]
+ </listitem>
+ </varlistentry>
- <filename class="directory">include/c_global</filename>
+ <varlistentry>
+ <term><filename class="directory">include/c_global</filename></term>
+ <listitem>
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 <code>std::</code>
namespace. [NB: this is the default, and is the same as
<option>--enable-cheaders=c_global</option>]
+ </listitem>
+ </varlistentry>
- <filename class="directory">include/c_std</filename>
+ <varlistentry>
+ <term><filename class="directory">include/c_std</filename></term>
+ <listitem>
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 <code>std::</code>
namespace. [NB: this is the same as
<option>--enable-cheaders=c_std</option>]
+ </listitem>
+ </varlistentry>
- <filename class="directory">include/bits</filename>
+ <varlistentry>
+ <term><filename class="directory">include/bits</filename></term>
+ <listitem>
Files included by standard headers and by other files in
the bits directory.
+ </listitem>
+ </varlistentry>
- <filename class="directory">include/backward</filename>
- Headers provided for backward compatibility, such as <iostream.h>.
+ <varlistentry>
+ <term><filename class="directory">include/backward</filename></term>
+ <listitem>
+ Headers provided for backward compatibility, such as
+ <filename class="headerfile"><backward/hash_map></filename>.
They are not used in this library.
+ </listitem>
+ </varlistentry>
- <filename class="directory">include/ext</filename>
+ <varlistentry>
+ <term><filename class="directory">include/ext</filename></term>
+ <listitem>
Headers that define extensions to the standard library. No
- standard header refers to any of them.
+ standard header refers to any of them, in theory (there are some
+ exceptions).
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
- <filename class="directory">scripts</filename>
+ <varlistentry>
+ <term><filename class="directory">scripts</filename></term>
+ <listitem>
Scripts that are used during the configure, build, make, or test
process.
+ </listitem>
+ </varlistentry>
- <filename class="directory">src</filename>
+ <varlistentry>
+ <term><filename class="directory">src</filename></term>
+ <listitem>
Files that are used in constructing the library, but are not
installed.
- <filename class="directory">src/c++98</filename>
+ <variablelist>
+ <varlistentry>
+ <term><filename class="directory">src/c++98</filename></term>
+ <listitem>
Source files compiled using <option>-std=gnu++98</option>.
+ </listitem>
+ </varlistentry>
- <filename class="directory">src/c++11</filename>
+ <varlistentry>
+ <term><filename class="directory">src/c++11</filename></term>
+ <listitem>
Source files compiled using <option>-std=gnu++11</option>.
+ </listitem>
+ </varlistentry>
- <filename class="directory">src/filesystem</filename>
+ <varlistentry>
+ <term><filename class="directory">src/filesystem</filename></term>
+ <listitem>
Source files for the Filesystem TS.
+ </listitem>
+ </varlistentry>
- <filename class="directory">src/shared</filename>
+ <varlistentry>
+ <term><filename class="directory">src/shared</filename></term>
+ <listitem>
Source code included by other files under both
<filename class="directory">src/c++98</filename> and
<filename class="directory">src/c++11</filename>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
- <filename class="directory">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</filename>
+ <varlistentry>
+ <term><filename class="directory">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</filename></term>
+ <listitem>
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.
+ </listitem>
+ </varlistentry>
+</variablelist>
+<para>
Other subdirectories contain variant versions of certain files
that are meant to be copied or linked by the configure script.
Currently these are:
+<literallayout><filename class="directory">config/abi</filename>
+<filename class="directory">config/allocator</filename>
+<filename class="directory">config/cpu</filename>
+<filename class="directory">config/io</filename>
+<filename class="directory">config/locale</filename>
+<filename class="directory">config/os</filename>
+</literallayout>
+</para>
- <filename class="directory">config/abi</filename>
- <filename class="directory">config/cpu</filename>
- <filename class="directory">config/io</filename>
- <filename class="directory">config/locale</filename>
- <filename class="directory">config/os</filename>
-
+<para>
In addition, a subdirectory holds the convenience library libsupc++.
+</para>
- <filename class="directory">libsupc++</filename>
+<variablelist>
+<varlistentry>
+ <term><filename class="directory">libsupc++</filename></term>
+ <listitem>
Contains the runtime library for C++, including exception
handling and memory allocation and deallocation, RTTI, terminate
handlers, etc.
+ </listitem>
+</varlistentry>
+</variablelist>
+<para>
Note that glibc also has a <filename class="directory">bits/</filename>
-subdirectory. We will either need to be careful not to collide with names
-in its <filename class="directory">bits/</filename>
-directory; or rename <filename class="directory">bits</filename> to (e.g.) <filename class="directory">cppbits</filename>.
+subdirectory. We need to be careful not to collide with names in its
+<filename class="directory">bits/</filename> directory. For example
+<filename class="headerfile"><bits/std_mutex.h></filename> has to be
+renamed from <filename class="headerfile"><bits/mutex.h></filename>.
+Another solution would be to rename <filename class="directory">bits</filename>
+to (e.g.) <filename class="directory">cppbits</filename>.
+</para>
+<para>
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.
- </literallayout>
+</para>
</section>
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2016-10-10 22:35 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-10-10 18:57 [PATCH] Update docs on libstdc++ source-code layout Jonathan Wakely
2016-10-10 22:35 ` Jonathan Wakely
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).