Skip to content

R
riscv-gcc-1
Commit 5c248975 by Jonathan Wakely Committed by Jonathan Wakely
Options

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
parent 1725d05d
Showing with 221 additions and 133 deletions
libstdc++-v3/ChangeLog
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> 2016-10-10 Ville Voutilainen <ville.voutilainen@gmail.com>
Make any's copy assignment operator exception-safe, Make any's copy assignment operator exception-safe,
......
libstdc++-v3/doc/html/manual/source_organization.html
...@@ -5,105 +5,95 @@ ...@@ -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> </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 The <code class="filename">libstdc++-v3</code> directory in the
GCC sources contains the files needed to create the GNU C++ Library. GCC sources contains the files needed to create the GNU C++ Library.
</p><div class="literallayout"><p><br /> </p><p>
It has subdirectories:<br /> It has subdirectories:
<br /> </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">doc</code></span></dt><dd>
  <code class="filename">doc</code><br /> Files in HTML and text format that document usage, quirks of the
    Files in HTML and text format that document usage, quirks of the<br /> implementation, and contributor checklists.
    implementation, and contributor checklists.<br /> </dd><dt><span class="term"><code class="filename">include</code></span></dt><dd>
<br /> All header files for the C++ library are within this directory,
  <code class="filename">include</code><br /> modulo specific runtime-related files that are in the libsupc++
    All header files for the C++ library are within this directory,<br /> directory.
    modulo specific runtime-related files that are in the libsupc++<br />
    directory.<br /> <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">include/std</code></span></dt><dd>
<br /> Files meant to be found by <code class="code">#include &lt;name&gt;</code> directives
    <code class="filename">include/std</code><br /> in standard-conforming user programs.
      Files meant to be found by #include &lt;name&gt; directives in<br /> </dd><dt><span class="term"><code class="filename">include/c</code></span></dt><dd>
      standard-conforming user programs.<br /> Headers intended to directly include standard C headers.
<br /> [NB: this can be enabled via <code class="option">--enable-cheaders=c</code>]
    <code class="filename">include/c</code><br /> </dd><dt><span class="term"><code class="filename">include/c_global</code></span></dt><dd>
      Headers intended to directly include standard C headers.<br /> Headers intended to include standard C headers in
      [NB: this can be enabled via <code class="option">--enable-cheaders=c</code>]<br /> the global namespace, and put select names into the <code class="code">std::</code>
<br /> namespace. [NB: this is the default, and is the same as
    <code class="filename">include/c_global</code><br /> <code class="option">--enable-cheaders=c_global</code>]
      Headers intended to include standard C headers in<br /> </dd><dt><span class="term"><code class="filename">include/c_std</code></span></dt><dd>
      the global namespace, and put select names into the std::<br /> Headers intended to include standard C headers
      namespace.  [NB: this is the default, and is the same as<br /> already in namespace std, and put select names into the <code class="code">std::</code>
      <code class="option">--enable-cheaders=c_global</code>]<br /> namespace. [NB: this is the same as
<br /> <code class="option">--enable-cheaders=c_std</code>]
    <code class="filename">include/c_std</code><br /> </dd><dt><span class="term"><code class="filename">include/bits</code></span></dt><dd>
      Headers intended to include standard C headers<br /> Files included by standard headers and by other files in
      already in namespace std, and put select names into the std::<br /> the bits directory.
      namespace.  [NB: this is the same as<br /> </dd><dt><span class="term"><code class="filename">include/backward</code></span></dt><dd>
      <code class="option">--enable-cheaders=c_std</code>]<br /> Headers provided for backward compatibility, such as
<br /> <code class="filename">&lt;backward/hash_map&gt;</code>.
    <code class="filename">include/bits</code><br /> They are not used in this library.
      Files included by standard headers and by other files in<br /> </dd><dt><span class="term"><code class="filename">include/ext</code></span></dt><dd>
      the bits directory.<br /> Headers that define extensions to the standard library. No
<br /> standard header refers to any of them, in theory (there are some
    <code class="filename">include/backward</code><br /> exceptions).
      Headers provided for backward compatibility, such as &lt;iostream.h&gt;.<br /> </dd></dl></div></dd><dt><span class="term"><code class="filename">scripts</code></span></dt><dd>
      They are not used in this library.<br /> Scripts that are used during the configure, build, make, or test
<br /> process.
    <code class="filename">include/ext</code><br /> </dd><dt><span class="term"><code class="filename">src</code></span></dt><dd>
      Headers that define extensions to the standard library.  No<br /> Files that are used in constructing the library, but are not
      standard header refers to any of them.<br /> installed.
<br />
  <code class="filename">scripts</code><br /> <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">src/c++98</code></span></dt><dd>
    Scripts that are used during the configure, build, make, or test<br /> Source files compiled using <code class="option">-std=gnu++98</code>.
    process.<br /> </dd><dt><span class="term"><code class="filename">src/c++11</code></span></dt><dd>
<br /> Source files compiled using <code class="option">-std=gnu++11</code>.
  <code class="filename">src</code><br /> </dd><dt><span class="term"><code class="filename">src/filesystem</code></span></dt><dd>
    Files that are used in constructing the library, but are not<br /> Source files for the Filesystem TS.
    installed.<br /> </dd><dt><span class="term"><code class="filename">src/shared</code></span></dt><dd>
<br /> Source code included by other files under both
    <code class="filename">src/c++98</code><br /> <code class="filename">src/c++98</code> and
    Source files compiled using <code class="option">-std=gnu++98</code>.<br /> <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>
<br /> Test programs are here, and may be used to begin to exercise the
    <code class="filename">src/c++11</code><br /> library. Support for "make check" and "make check-install" is
    Source files compiled using <code class="option">-std=gnu++11</code>.<br /> complete, and runs through all the subdirectories here when this
<br /> command is issued from the build directory. Please note that
    <code class="filename">src/filesystem</code><br /> "make check" requires DejaGNU 1.4 or later to be installed.
    Source files for the Filesystem TS.<br /> </dd></dl></div><p>
<br /> Other subdirectories contain variant versions of certain files
    <code class="filename">src/shared</code><br /> that are meant to be copied or linked by the configure script.
    Source code included by other files under both<br /> Currently these are:
    <code class="filename">src/c++98</code> and<br /> </p><div class="literallayout"><p><code class="filename">config/abi</code><br />
    <code class="filename">src/c++11</code><br /> <code class="filename">config/allocator</code><br />
<br /> <code class="filename">config/cpu</code><br />
  <code class="filename">testsuites/[backward, demangle, ext, performance, thread, 17_* to 30_*]</code><br /> <code class="filename">config/io</code><br />
    Test programs are here, and may be used to begin to exercise the<br /> <code class="filename">config/locale</code><br />
    library.  Support for "make check" and "make check-install" is<br /> <code class="filename">config/os</code><br />
    complete, and runs through all the subdirectories here when this<br /> </p></div><p>
    command is issued from the build directory.  Please note that<br /> </p><p>
    "make check" requires DejaGNU 1.4 or later to be installed.<br /> In addition, a subdirectory holds the convenience library libsupc++.
<br /> </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">libsupc++</code></span></dt><dd>
Other subdirectories contain variant versions of certain files<br /> Contains the runtime library for C++, including exception
that are meant to be copied or linked by the configure script.<br /> handling and memory allocation and deallocation, RTTI, terminate
Currently these are:<br /> handlers, etc.
<br /> </dd></dl></div><p>
  <code class="filename">config/abi</code><br /> Note that glibc also has a <code class="filename">bits/</code>
  <code class="filename">config/cpu</code><br /> subdirectory. We need to be careful not to collide with names in its
  <code class="filename">config/io</code><br /> <code class="filename">bits/</code> directory. For example
  <code class="filename">config/locale</code><br /> <code class="filename">&lt;bits/std_mutex.h&gt;</code> has to be
  <code class="filename">config/os</code><br /> renamed from <code class="filename">&lt;bits/mutex.h&gt;</code>.
<br /> Another solution would be to rename <code class="filename">bits</code>
In addition, a subdirectory holds the convenience library libsupc++.<br /> to (e.g.) <code class="filename">cppbits</code>.
<br /> </p><p>
  <code class="filename">libsupc++</code><br /> In files throughout the system, lines marked with an "XXX" indicate
    Contains the runtime library for C++, including exception<br /> a bug or incompletely-implemented feature. Lines marked "XXX MT"
    handling and memory allocation and deallocation, RTTI, terminate<br /> indicate a place that may require attention for multi-thread safety.
    handlers, etc.<br /> </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. 
<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. 
Contributing 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>  </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
libstdc++-v3/doc/xml/manual/appendix_contributing.xml
...@@ -203,105 +203,195 @@ ...@@ -203,105 +203,195 @@
GCC sources contains the files needed to create the GNU C++ Library. GCC sources contains the files needed to create the GNU C++ Library.
</para> </para>
<literallayout class="normal"> <para>
It has subdirectories: 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 Files in HTML and text format that document usage, quirks of the
implementation, and contributor checklists. 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, All header files for the C++ library are within this directory,
modulo specific runtime-related files that are in the libsupc++ modulo specific runtime-related files that are in the libsupc++
directory. directory.
<filename class="directory">include/std</filename> <variablelist>
Files meant to be found by #include &lt;name&gt; directives in <varlistentry>
standard-conforming user programs. <term><filename class="directory">include/std</filename></term>
<listitem>
Files meant to be found by <code>#include &lt;name&gt;</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. Headers intended to directly include standard C headers.
[NB: this can be enabled via <option>--enable-cheaders=c</option>] [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 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 namespace. [NB: this is the default, and is the same as
<option>--enable-cheaders=c_global</option>] <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 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 namespace. [NB: this is the same as
<option>--enable-cheaders=c_std</option>] <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 Files included by standard headers and by other files in
the bits directory. the bits directory.
</listitem>
</varlistentry>
<filename class="directory">include/backward</filename> <varlistentry>
Headers provided for backward compatibility, such as &lt;iostream.h&gt;. <term><filename class="directory">include/backward</filename></term>
<listitem>
Headers provided for backward compatibility, such as
<filename class="headerfile">&lt;backward/hash_map&gt;</filename>.
They are not used in this library. 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 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 Scripts that are used during the configure, build, make, or test
process. 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 Files that are used in constructing the library, but are not
installed. 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>. 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>. 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. 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 Source code included by other files under both
<filename class="directory">src/c++98</filename> and <filename class="directory">src/c++98</filename> and
<filename class="directory">src/c++11</filename> <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 Test programs are here, and may be used to begin to exercise the
library. Support for "make check" and "make check-install" is library. Support for "make check" and "make check-install" is
complete, and runs through all the subdirectories here when this complete, and runs through all the subdirectories here when this
command is issued from the build directory. Please note that command is issued from the build directory. Please note that
"make check" requires DejaGNU 1.4 or later to be installed. "make check" requires DejaGNU 1.4 or later to be installed.
</listitem>
</varlistentry>
</variablelist>
<para>
Other subdirectories contain variant versions of certain files Other subdirectories contain variant versions of certain files
that are meant to be copied or linked by the configure script. that are meant to be copied or linked by the configure script.
Currently these are: 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> <para>
<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++. 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 Contains the runtime library for C++, including exception
handling and memory allocation and deallocation, RTTI, terminate handling and memory allocation and deallocation, RTTI, terminate
handlers, etc. handlers, etc.
</listitem>
</varlistentry>
</variablelist>
<para>
Note that glibc also has a <filename class="directory">bits/</filename> Note that glibc also has a <filename class="directory">bits/</filename>
subdirectory. We will either need to be careful not to collide with names subdirectory. We need to be careful not to collide with names in its
in its <filename class="directory">bits/</filename> <filename class="directory">bits/</filename> directory. For example
directory; or rename <filename class="directory">bits</filename> to (e.g.) <filename class="directory">cppbits</filename>. <filename class="headerfile">&lt;bits/std_mutex.h&gt;</filename> has to be
renamed from <filename class="headerfile">&lt;bits/mutex.h&gt;</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 In files throughout the system, lines marked with an "XXX" indicate
a bug or incompletely-implemented feature. Lines marked "XXX MT" a bug or incompletely-implemented feature. Lines marked "XXX MT"
indicate a place that may require attention for multi-thread safety. indicate a place that may require attention for multi-thread safety.
</literallayout> </para>
</section> </section>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment