file: isolib/README

Instructions for configuring and building this snapshot appear
in RELEASE-NOTES.

This directory contains the files needed to create [a still broken
subset of] an ISO Standard C++ Library.

It has subdirectories:

  bits
     Files included by standard headers and by other files in
     the bits directory.  Includes a set of files bits/std_xxxx.h
     that implement the standard headers <xxxx>.

  std
     Files meant to be found by #include <name> directives in
     standard-conforming user programs.  These headers are not
     referred to by other headers, because such dependencies
     confuse Make (leading it to delete them, all too often).
     Installations may substitute symbolic links in place of
     these files.

  ext
     Headers that define extensions to the standard library.  No
     standard header refers to any of them.

  backward
     Headers provided for backward compatibility, such as <iostream.h>.
     They are not used in this library.

  src
     Files that are used in constructing the library, but are not
     installed.

  testsuites/21, 27
     Test programs are here, and may be used to begin to exercise the 
     library.  Support for "make test" based on these is not done yet.

  shadow
     Headers intended to shadow standard C headers provided by an
     underlying OS or C library, and other headers depended on directly
     by C++ headers (e.g. unistd.h).  These are meant to wrap the names
     defined there into the _CSwamp namespace.
     [note: this is still experimental, and is not currently used.]

  cshadow
     The contents of this directory are constructed by scripts which 
     examine the underlying C headers to discover other headers they
     depend on.  These headers are wrappers for them.
     [note: this is still experimental, and is not currently used.]

Another directory, stl, also contains directories bits, backward,
and ext.  These directories contain files which are not protected
under any GNU license.  For build purposes they are treated the same
as the top level directories, via (e.g.) the -I compiler option.  On
installation all files (e.g. under bits/ and stl/bits/) are copied
into a common target directory (e.g. $TARGET_INCLUDE/bits).

Other subdirectories contain variant versions of certain files
that are meant to be copied or linked by the configure script.
Currently these are:

  amm1 generic glibc math

Files needed only to construct the library, but not installed,
are in src/.  Files to be copied as part of an installation are
all found in the subdirectories mentioned above.  (A configure
script may link files from another directory into one of these.)

In a normal installation the bits/ directory is copied
under the std/ directory, and arranged to be searched only
when an include directive specifies a filename of "bits/..."
or <bits/...>.  When building the library, we use

  -Istd -I. -Istl

to get the same effect.

Note that glibc also has a bits/ subdirectory.  We will either
need to be careful not to collide with names in its bits/
directory; or rename bits to (e.g.) cppbits/.

To install libstdc++ you need GNU make.  The makefiles do not work with
any other make.

In files throughout the system, lines marked with an "XXX" indicate
a bug or incompletely-implemented feature.  Lines marked "XXX MT"
indicate a place that may require attention for multi-thread safety.
(Warning: places that need an atomic read are not so marked yet.)

Documentation:

BADNAMES
  A list of short uglified names that must not be used in code
  because they would collide with names build into the compilers, or used
  in C headers, of target systems.

BUGS
  Known bugs are logged here.  This file may be out of date; it certainly
  is always incomplete.  Omissions are not placed here, except for 
  components marked as finished in the CHECKLIST.

C++STYLE
  A minimalist example of the style guidelines which this library will 
  be held to.  Note that it differs significantly from the GNU "C" 
  coding style.  This is deliberate: this is a C++ library, not a
  C library.  Note that there is a significant amount of GNU-style
  use of "()" remaining in the library.  This will be combed out.

CHECKLIST
  A list of what is and is not implemented in each current snapshot.

ChangeLog
  Changes to the library are logged here.

HEADER_POLICY
  Describes the policy for use of headers in the library 
  implementation.  Failure to obey it strictly will break the library
  in subtle ways.

LICENSE.STD
  Terms of use.

PROBLEMS
  Portability and use issues.

README
  This file.

RELEASE-NOTES
  Notes about a particular snapshot or release.

TODO
  Cryptic notes about high-priority goals for the library.
