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
   8 Instructions for configuring and building this snapshot appear
   9 in docs/html/install.html.
  10
  11 This directory contains the files needed to create [a still broken
  12 subset of] an ISO Standard C++ Library.
  13
  14 It has subdirectories:
  15
  16   docs
  17      Files in HTML and text format that document usage, quirks of the
  18      implementation, and contributor checklists.
  19
  20   include/bits
  21      Files included by standard headers and by other files in
  22      the bits directory.  Includes a set of files bits/std_xxxx.h
  23      that implement the standard headers <xxxx>.
  24
  25   include/std
  26      Files meant to be found by #include <name> directives in
  27      standard-conforming user programs.  These headers are not
  28      referred to by other headers, because such dependencies
  29      confuse Make (leading it to delete them, all too often).
  30      Installations may substitute symbolic links in place of
  31      these files.
  32
  33   include/ext
  34      Headers that define extensions to the standard library.  No
  35      standard header refers to any of them.
  36
  37   include/backward
  38      Headers provided for backward compatibility, such as <iostream.h>.
  39      They are not used in this library.
  40
  41   include/c_shadow
  42      Headers intended to shadow standard C headers provided by an
  43      underlying OS or C library, and other headers depended on directly
  44      by C++ headers (e.g. unistd.h).  These are meant to wrap the names
  45      defined there into the _C_legacy namespace.
  46      [NB: this can be enabled via --enable-cheaders=c_shadow]
  47
  48   include/c
  49      Headers intended to directly include standard C headers.
  50      [NB: this can be enabled via --enable-cheaders=c]
  51
  52   include/c_std
  53      Headers intended to include standard C headers, and put select
  54      names into the std:: namespace.
  55      [NB: this is the default, and is the same as --enable-cheaders=c_std]
  56
  57   src
  58      Files that are used in constructing the library, but are not
  59      installed.
  60
  61   testsuites/17_* to 27_*
  62      Test programs are here, and may be used to begin to exercise the
  63      library.  Support for "make check" and "make check-install" is
  64      complete, and runs through all the subdirectories here when this
  65      command is issued from the build directory.  Please note that
  66      "make check" requires DejaGNU 1.4 or later to be installed.  Please
  67      note that "make check-script" calls the script mkcheck, which
  68      requires bash, and which may need the paths to bash adjusted to
  69      work properly, as /bin/bash is assumed.
  70
  71 Other subdirectories contain variant versions of certain files
  72 that are meant to be copied or linked by the configure script.
  73 Currently these are:
  74
  75   config/cpu
  76   config/os
  77
  78 Files needed only to construct the library, but not installed,
  79 are in src/.  Files to be copied as part of an installation are
  80 all found in the subdirectories mentioned above.  (A configure
  81 script may link files from another directory into one of these.)
  82
  83 In a normal installation the bits/ directory is copied
  84 under the std/ directory, and arranged to be searched only
  85 when an include directive specifies a filename of "bits/..."
  86 or <bits/...>.  When building the library, we use
  87
  88   -I. -Iinclude/std -Iinclude -Iconfig/os/* -Iconfig/cpu/*
  89
  90 to get the same effect.
  91
  92 Note that glibc also has a bits/ subdirectory.  We will either
  93 need to be careful not to collide with names in its bits/
  94 directory; or rename bits to (e.g.) cppbits/.
  95
  96 To install libstdc++ you need GNU make.  The makefiles do not work with
  97 any other make.
  98
  99 In files throughout the system, lines marked with an "XXX" indicate
 100 a bug or incompletely-implemented feature.  Lines marked "XXX MT"
 101 indicate a place that may require attention for multi-thread safety.