libstdc++-v3/README

   1 file: isolib/README
   2
   3 New users may wish to point their web browsers to the file index.html
   4 in the 'docs' subdirectory.  It contains brief building instructions
   5 and notes on how to configure the library in interesting ways.
   6
   7
   8 Instructions for configuring and building this snapshot appear
   9 in 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   bits
  17      Files included by standard headers and by other files in
  18      the bits directory.  Includes a set of files bits/std_xxxx.h
  19      that implement the standard headers <xxxx>.
  20
  21   std
  22      Files meant to be found by #include <name> directives in
  23      standard-conforming user programs.  These headers are not
  24      referred to by other headers, because such dependencies
  25      confuse Make (leading it to delete them, all too often).
  26      Installations may substitute symbolic links in place of
  27      these files.
  28
  29   ext
  30      Headers that define extensions to the standard library.  No
  31      standard header refers to any of them.
  32
  33   backward
  34      Headers provided for backward compatibility, such as <iostream.h>.
  35      They are not used in this library.
  36
  37   src
  38      Files that are used in constructing the library, but are not
  39      installed.
  40
  41   testsuites/17_* to 27_*
  42      Test programs are here, and may be used to begin to exercise the
  43      library.  Support for "make check" and "make check-install" is
  44      complete, and runs through all the subdirectories here when this
  45      command is issued from the build directory. Please note that
  46      "make check" calls the script mkcheck, which requires bash, and which
  47      may need the paths to bash adjusted to work properly, as /bin/bash is
  48      assumed.
  49
  50   shadow
  51      Headers intended to shadow standard C headers provided by an
  52      underlying OS or C library, and other headers depended on directly
  53      by C++ headers (e.g. unistd.h).  These are meant to wrap the names
  54      defined there into the _CSwamp namespace.
  55      [NB: this is still experimental, and is not currently used.]
  56
  57   cshadow
  58      The contents of this directory are constructed by scripts which
  59      examine the underlying C headers to discover other headers they
  60      depend on.  These headers are wrappers for them.
  61      [NB: this is still experimental, and is not currently used.]
  62
  63 Other subdirectories contain variant versions of certain files
  64 that are meant to be copied or linked by the configure script.
  65 Currently these are:
  66
  67   amm1 generic glibc math
  68
  69 Files needed only to construct the library, but not installed,
  70 are in src/.  Files to be copied as part of an installation are
  71 all found in the subdirectories mentioned above.  (A configure
  72 script may link files from another directory into one of these.)
  73
  74 In a normal installation the bits/ directory is copied
  75 under the std/ directory, and arranged to be searched only
  76 when an include directive specifies a filename of "bits/..."
  77 or <bits/...>.  When building the library, we use
  78
  79   -Istd -I. -Iconfig/* -Iconfig/cpu/*
  80
  81 to get the same effect.
  82
  83 Note that glibc also has a bits/ subdirectory.  We will either
  84 need to be careful not to collide with names in its bits/
  85 directory; or rename bits to (e.g.) cppbits/.
  86
  87 To install libstdc++ you need GNU make.  The makefiles do not work with
  88 any other make.
  89
  90 In files throughout the system, lines marked with an "XXX" indicate
  91 a bug or incompletely-implemented feature.  Lines marked "XXX MT"
  92 indicate a place that may require attention for multi-thread safety.
  93 (Warning: places that need an atomic read are not so marked yet.)
  94