libstdc++-v3/README

   1 file: libstdc++-v3/README
   2
   3 New users may wish to point their web browsers to the file documentation.html
   4 in the 'docs/html' subdirectory.  It contains brief building instructions and
   5 notes on how to configure the library in interesting ways.
   6
   7 Instructions for configuring and building appear in
   8 docs/html/install.html.
   9
  10 This directory contains the files needed to create an ISO Standard C++
  11 Library.
  12
  13 It has subdirectories:
  14
  15   docs
  16      Files in HTML and text format that document usage, quirks of the
  17      implementation, and contributor checklists.
  18
  19   include/std
  20      Files meant to be found by #include <name> directives in
  21      standard-conforming user programs.
  22
  23   include/c
  24      Headers intended to directly include standard C headers.
  25      [NB: this can be enabled via --enable-cheaders=c]
  26
  27   include/c_std
  28      Headers intended to include standard C headers, and put select
  29      names into the std:: namespace.
  30      [NB: this is the default, and is the same as --enable-cheaders=c_std]
  31
  32   include/c_shadow
  33      Headers intended to shadow standard C headers provided by an
  34      underlying OS or C library, and other headers depended on directly
  35      by C++ headers (e.g. unistd.h).  These are meant to wrap the names
  36      defined there into the _C_legacy namespace.
  37      [NB: this can be enabled via --enable-cheaders=c_shadow]
  38
  39   include/bits
  40      Files included by standard headers and by other files in
  41      the bits directory.  Includes a set of files bits/std_xxxx.h
  42      that implement the standard headers <xxxx>.
  43
  44   include/backward
  45      Headers provided for backward compatibility, such as <iostream.h>.
  46      They are not used in this library.
  47
  48   include/ext
  49      Headers that define extensions to the standard library.  No
  50      standard header refers to any of them.
  51
  52   src
  53      Files that are used in constructing the library, but are not
  54      installed.
  55
  56   testsuites/17_* to 27_*
  57      Test programs are here, and may be used to begin to exercise the
  58      library.  Support for "make check" and "make check-install" is
  59      complete, and runs through all the subdirectories here when this
  60      command is issued from the build directory.  Please note that
  61      "make check" requires DejaGNU 1.4 or later to be installed.  Please
  62      note that "make check-script" calls the script mkcheck, which
  63      requires bash, and which may need the paths to bash adjusted to
  64      work properly, as /bin/bash is assumed.
  65
  66 Other subdirectories contain variant versions of certain files
  67 that are meant to be copied or linked by the configure script.
  68 Currently these are:
  69
  70   config/cpu
  71   config/os
  72   config/io
  73   config/locale
  74
  75 In addition, three subdirectories are convenience libraries:
  76
  77   libio
  78      Contains the subset of the GNU libio library needed for
  79      C++. Currently not used.
  80
  81   libmath
  82      Support routines needed for C++ math. Only needed if the
  83      underlying "C" implementation is weak or looses.
  84
  85   libsupc++
  86      Contains the runtime library for C++, including exception
  87      handling and memory allocation and deallocation, RTTI, terminate
  88      handlers, etc.
  89
  90 Note that glibc also has a bits/ subdirectory.  We will either
  91 need to be careful not to collide with names in its bits/
  92 directory; or rename bits to (e.g.) cppbits/.
  93
  94 In files throughout the system, lines marked with an "XXX" indicate
  95 a bug or incompletely-implemented feature.  Lines marked "XXX MT"
  96 indicate a place that may require attention for multi-thread safety.