diff options
author | Jonathan Wakely <jwakely@redhat.com> | 2016-10-10 23:34:17 +0100 |
---|---|---|
committer | Jonathan Wakely <redi@gcc.gnu.org> | 2016-10-10 23:34:17 +0100 |
commit | 5c24897577586d3db2fad081083a1f18f59a579c (patch) | |
tree | 7a50e971e295a5791ed698504617f40bf7cd9ad3 | |
parent | 1725d05d199fc256844040d2900d5ee206c9d289 (diff) | |
download | gcc-5c24897577586d3db2fad081083a1f18f59a579c.zip gcc-5c24897577586d3db2fad081083a1f18f59a579c.tar.gz gcc-5c24897577586d3db2fad081083a1f18f59a579c.tar.bz2 |
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.
From-SVN: r240952
-rw-r--r-- | libstdc++-v3/ChangeLog | 7 | ||||
-rw-r--r-- | libstdc++-v3/doc/html/manual/source_organization.html | 188 | ||||
-rw-r--r-- | libstdc++-v3/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 <jwakely@redhat.com> + + * doc/xml/manual/appendix_contributing.xml (contrib.organization): + Replace <literallayout> with nested <variablelist> elements. Update + some more outdated text. + * doc/html/*: Regenerate. + 2016-10-10 Ville Voutilainen <ville.voutilainen@gmail.com> 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 @@ </th><td width="20%" align="right"> <a accesskey="n" href="source_code_style.html">Next</a></td></tr></table><hr /></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="contrib.organization"></a>Directory Layout and Source Conventions</h2></div></div></div><p> The <code class="filename">libstdc++-v3</code> directory in the GCC sources contains the files needed to create the GNU C++ Library. - </p><div class="literallayout"><p><br /> -It has subdirectories:<br /> -<br /> - <code class="filename">doc</code><br /> - Files in HTML and text format that document usage, quirks of the<br /> - implementation, and contributor checklists.<br /> -<br /> - <code class="filename">include</code><br /> - All header files for the C++ library are within this directory,<br /> - modulo specific runtime-related files that are in the libsupc++<br /> - directory.<br /> -<br /> - <code class="filename">include/std</code><br /> - Files meant to be found by #include <name> directives in<br /> - standard-conforming user programs.<br /> -<br /> - <code class="filename">include/c</code><br /> - Headers intended to directly include standard C headers.<br /> - [NB: this can be enabled via <code class="option">--enable-cheaders=c</code>]<br /> -<br /> - <code class="filename">include/c_global</code><br /> - Headers intended to include standard C headers in<br /> - the global namespace, and put select names into the std::<br /> - namespace. [NB: this is the default, and is the same as<br /> - <code class="option">--enable-cheaders=c_global</code>]<br /> -<br /> - <code class="filename">include/c_std</code><br /> - Headers intended to include standard C headers<br /> - already in namespace std, and put select names into the std::<br /> - namespace. [NB: this is the same as<br /> - <code class="option">--enable-cheaders=c_std</code>]<br /> -<br /> - <code class="filename">include/bits</code><br /> - Files included by standard headers and by other files in<br /> - the bits directory.<br /> -<br /> - <code class="filename">include/backward</code><br /> - Headers provided for backward compatibility, such as <iostream.h>.<br /> - They are not used in this library.<br /> -<br /> - <code class="filename">include/ext</code><br /> - Headers that define extensions to the standard library. No<br /> - standard header refers to any of them.<br /> -<br /> - <code class="filename">scripts</code><br /> - Scripts that are used during the configure, build, make, or test<br /> - process.<br /> -<br /> - <code class="filename">src</code><br /> - Files that are used in constructing the library, but are not<br /> - installed.<br /> -<br /> - <code class="filename">src/c++98</code><br /> - Source files compiled using <code class="option">-std=gnu++98</code>.<br /> -<br /> - <code class="filename">src/c++11</code><br /> - Source files compiled using <code class="option">-std=gnu++11</code>.<br /> -<br /> - <code class="filename">src/filesystem</code><br /> - Source files for the Filesystem TS.<br /> -<br /> - <code class="filename">src/shared</code><br /> - Source code included by other files under both<br /> - <code class="filename">src/c++98</code> and<br /> - <code class="filename">src/c++11</code><br /> -<br /> - <code class="filename">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</code><br /> - Test programs are here, and may be used to begin to exercise the<br /> - library. Support for "make check" and "make check-install" is<br /> - complete, and runs through all the subdirectories here when this<br /> - command is issued from the build directory. Please note that<br /> - "make check" requires DejaGNU 1.4 or later to be installed.<br /> -<br /> -Other subdirectories contain variant versions of certain files<br /> -that are meant to be copied or linked by the configure script.<br /> -Currently these are:<br /> -<br /> - <code class="filename">config/abi</code><br /> - <code class="filename">config/cpu</code><br /> - <code class="filename">config/io</code><br /> - <code class="filename">config/locale</code><br /> - <code class="filename">config/os</code><br /> -<br /> -In addition, a subdirectory holds the convenience library libsupc++.<br /> -<br /> - <code class="filename">libsupc++</code><br /> - Contains the runtime library for C++, including exception<br /> - handling and memory allocation and deallocation, RTTI, terminate<br /> - handlers, etc.<br /> -<br /> -Note that glibc also has a <code class="filename">bits/</code><br /> -subdirectory. We will either need to be careful not to collide with names<br /> -in its <code class="filename">bits/</code><br /> -directory; or rename <code class="filename">bits</code> to (e.g.) <code class="filename">cppbits</code>.<br /> -<br /> -In files throughout the system, lines marked with an "XXX" indicate<br /> -a bug or incompletely-implemented feature. Lines marked "XXX MT"<br /> -indicate a place that may require attention for multi-thread safety.<br /> - </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source_code_style.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix A. + </p><p> +It has subdirectories: +</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">doc</code></span></dt><dd> + Files in HTML and text format that document usage, quirks of the + implementation, and contributor checklists. + </dd><dt><span class="term"><code class="filename">include</code></span></dt><dd> + All header files for the C++ library are within this directory, + modulo specific runtime-related files that are in the libsupc++ + directory. + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">include/std</code></span></dt><dd> + Files meant to be found by <code class="code">#include <name></code> directives + in standard-conforming user programs. + </dd><dt><span class="term"><code class="filename">include/c</code></span></dt><dd> + Headers intended to directly include standard C headers. + [NB: this can be enabled via <code class="option">--enable-cheaders=c</code>] + </dd><dt><span class="term"><code class="filename">include/c_global</code></span></dt><dd> + Headers intended to include standard C headers in + the global namespace, and put select names into the <code class="code">std::</code> + namespace. [NB: this is the default, and is the same as + <code class="option">--enable-cheaders=c_global</code>] + </dd><dt><span class="term"><code class="filename">include/c_std</code></span></dt><dd> + Headers intended to include standard C headers + already in namespace std, and put select names into the <code class="code">std::</code> + namespace. [NB: this is the same as + <code class="option">--enable-cheaders=c_std</code>] + </dd><dt><span class="term"><code class="filename">include/bits</code></span></dt><dd> + Files included by standard headers and by other files in + the bits directory. + </dd><dt><span class="term"><code class="filename">include/backward</code></span></dt><dd> + Headers provided for backward compatibility, such as + <code class="filename"><backward/hash_map></code>. + They are not used in this library. + </dd><dt><span class="term"><code class="filename">include/ext</code></span></dt><dd> + Headers that define extensions to the standard library. No + standard header refers to any of them, in theory (there are some + exceptions). + </dd></dl></div></dd><dt><span class="term"><code class="filename">scripts</code></span></dt><dd> + Scripts that are used during the configure, build, make, or test + process. + </dd><dt><span class="term"><code class="filename">src</code></span></dt><dd> + Files that are used in constructing the library, but are not + installed. + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">src/c++98</code></span></dt><dd> + Source files compiled using <code class="option">-std=gnu++98</code>. + </dd><dt><span class="term"><code class="filename">src/c++11</code></span></dt><dd> + Source files compiled using <code class="option">-std=gnu++11</code>. + </dd><dt><span class="term"><code class="filename">src/filesystem</code></span></dt><dd> + Source files for the Filesystem TS. + </dd><dt><span class="term"><code class="filename">src/shared</code></span></dt><dd> + Source code included by other files under both + <code class="filename">src/c++98</code> and + <code class="filename">src/c++11</code></dd></dl></div></dd><dt><span class="term"><code class="filename">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</code></span></dt><dd> + 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. + </dd></dl></div><p> +Other subdirectories contain variant versions of certain files +that are meant to be copied or linked by the configure script. +Currently these are: +</p><div class="literallayout"><p><code class="filename">config/abi</code><br /> +<code class="filename">config/allocator</code><br /> +<code class="filename">config/cpu</code><br /> +<code class="filename">config/io</code><br /> +<code class="filename">config/locale</code><br /> +<code class="filename">config/os</code><br /> +</p></div><p> +</p><p> +In addition, a subdirectory holds the convenience library libsupc++. +</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">libsupc++</code></span></dt><dd> + Contains the runtime library for C++, including exception + handling and memory allocation and deallocation, RTTI, terminate + handlers, etc. + </dd></dl></div><p> +Note that glibc also has a <code class="filename">bits/</code> +subdirectory. We need to be careful not to collide with names in its +<code class="filename">bits/</code> directory. For example +<code class="filename"><bits/std_mutex.h></code> has to be +renamed from <code class="filename"><bits/mutex.h></code>. +Another solution would be to rename <code class="filename">bits</code> +to (e.g.) <code class="filename">cppbits</code>. +</p><p> +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. +</p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="appendix_contributing.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="source_code_style.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Appendix A. Contributing </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Coding Style</td></tr></table></div></body></html>
\ 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. </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. - - <filename class="directory">scripts</filename> + standard header refers to any of them, in theory (there are some + exceptions). + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <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> - - <filename class="directory">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</filename> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <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> |