libstdc++-v3/doc/html/manual/source_organization.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Directory Layout and Source Conventions</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.78.1" /><meta name="keywords" content="ISO C++, library" /><meta name="keywords" content="ISO C++, runtime, library" /><link rel="home" href="../index.html" title="The GNU C++ Library" /><link rel="up" href="appendix_contributing.html" title="Appendix A.  Contributing" /><link rel="prev" href="appendix_contributing.html" title="Appendix A.  Contributing" /><link rel="next" href="source_code_style.html" title="Coding Style" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Directory Layout and Source Conventions</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="appendix_contributing.html">Prev</a> </td><th width="60%" align="center">Appendix A.
   3   Contributing
   4
   5 </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>
   6     The <code class="filename">libstdc++-v3</code> directory in the
   7     GCC sources contains the files needed to create the GNU C++ Library.
   8   </p><p>
   9 It has subdirectories:
  10 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">doc</code></span></dt><dd>
  11     Files in HTML and text format that document usage, quirks of the
  12     implementation, and contributor checklists.
  13     </dd><dt><span class="term"><code class="filename">include</code></span></dt><dd>
  14     All header files for the C++ library are within this directory,
  15     modulo specific runtime-related files that are in the libsupc++
  16     directory.
  17
  18     <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">include/std</code></span></dt><dd>
  19       Files meant to be found by <code class="code">#include &lt;name&gt;</code> directives
  20       in standard-conforming user programs.
  21       </dd><dt><span class="term"><code class="filename">include/c</code></span></dt><dd>
  22       Headers intended to directly include standard C headers.
  23       [NB: this can be enabled via <code class="option">--enable-cheaders=c</code>]
  24       </dd><dt><span class="term"><code class="filename">include/c_global</code></span></dt><dd>
  25       Headers intended to include standard C headers in
  26       the global namespace, and put select names into the <code class="code">std::</code>
  27       namespace.  [NB: this is the default, and is the same as
  28       <code class="option">--enable-cheaders=c_global</code>]
  29       </dd><dt><span class="term"><code class="filename">include/c_std</code></span></dt><dd>
  30       Headers intended to include standard C headers
  31       already in namespace std, and put select names into the <code class="code">std::</code>
  32       namespace.  [NB: this is the same as
  33       <code class="option">--enable-cheaders=c_std</code>]
  34       </dd><dt><span class="term"><code class="filename">include/bits</code></span></dt><dd>
  35       Files included by standard headers and by other files in
  36       the bits directory.
  37       </dd><dt><span class="term"><code class="filename">include/backward</code></span></dt><dd>
  38       Headers provided for backward compatibility, such as
  39       <code class="filename">&lt;backward/hash_map&gt;</code>.
  40       They are not used in this library.
  41     </dd><dt><span class="term"><code class="filename">include/ext</code></span></dt><dd>
  42       Headers that define extensions to the standard library.  No
  43       standard header refers to any of them, in theory (there are some
  44       exceptions).
  45     </dd><dt><span class="term">
  46       <code class="filename">include/debug</code>,
  47       <code class="filename">include/parallel</code>, and
  48       <code class="filename">include/profile</code>
  49     </span></dt><dd>
  50       Headers that implement the Debug Mode, Parallel Mode, and Profile Mode
  51       extensions.
  52     </dd></dl></div></dd><dt><span class="term"><code class="filename">scripts</code></span></dt><dd>
  53     Scripts that are used during the configure, build, make, or test
  54     process.
  55     </dd><dt><span class="term"><code class="filename">src</code></span></dt><dd>
  56     Files that are used in constructing the library, but are not
  57     installed.
  58
  59     <div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">src/c++98</code></span></dt><dd>
  60     Source files compiled using <code class="option">-std=gnu++98</code>.
  61       </dd><dt><span class="term"><code class="filename">src/c++11</code></span></dt><dd>
  62     Source files compiled using <code class="option">-std=gnu++11</code>.
  63       </dd><dt><span class="term"><code class="filename">src/filesystem</code></span></dt><dd>
  64     Source files for the Filesystem TS.
  65       </dd><dt><span class="term"><code class="filename">src/shared</code></span></dt><dd>
  66     Source code included by other files under both
  67     <code class="filename">src/c++98</code> and
  68     <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>
  69     Test programs are here, and may be used to begin to exercise the
  70     library.  Support for "make check" and "make check-install" is
  71     complete, and runs through all the subdirectories here when this
  72     command is issued from the build directory.  Please note that
  73     "make check" requires DejaGNU 1.4 or later to be installed.
  74     </dd></dl></div><p>
  75 Other subdirectories contain variant versions of certain files
  76 that are meant to be copied or linked by the configure script.
  77 Currently these are:
  78 </p><div class="literallayout"><p><code class="filename">config/abi</code><br />
  79 <code class="filename">config/allocator</code><br />
  80 <code class="filename">config/cpu</code><br />
  81 <code class="filename">config/io</code><br />
  82 <code class="filename">config/locale</code><br />
  83 <code class="filename">config/os</code><br />
  84 </p></div><p>
  85 </p><p>
  86 In addition, a subdirectory holds the convenience library libsupc++.
  87 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="filename">libsupc++</code></span></dt><dd>
  88     Contains the runtime library for C++, including exception
  89     handling and memory allocation and deallocation, RTTI, terminate
  90     handlers, etc.
  91   </dd></dl></div><p>
  92 Note that glibc also has a <code class="filename">bits/</code>
  93 subdirectory.  We need to be careful not to collide with names in its
  94 <code class="filename">bits/</code> directory. For example
  95 <code class="filename">&lt;bits/std_mutex.h&gt;</code> has to be
  96 renamed from <code class="filename">&lt;bits/mutex.h&gt;</code>.
  97 Another solution would be to rename <code class="filename">bits</code>
  98 to (e.g.) <code class="filename">cppbits</code>.
  99 </p><p>
 100 In files throughout the system, lines marked with an "XXX" indicate
 101 a bug or incompletely-implemented feature.  Lines marked "XXX MT"
 102 indicate a place that may require attention for multi-thread safety.
 103 </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.
 104   Contributing
 105
 106  </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>