Daily bump.
[official-gcc.git] / libstdc++-v3 / README
blob67c390e981dcc09515f94a48d52a4d297088e779
1 file: libstdc++-v3/README
3 New users may wish to point their web browsers to the file
4 documentation.html in the 'docs/html' subdirectory.  It contains brief
5 building instructions and notes on how to configure the library in
6 interesting ways.
8 Instructions for configuring and building appear in
9 docs/html/install.html.
11 This directory contains the files needed to create an ISO Standard C++
12 Library.
14 It has subdirectories:
16   docs
17     Files in HTML and text format that document usage, quirks of the
18     implementation, and contributor checklists.
20   include
21     All header files for the C++ library are within this directory,
22     modulo specific runtime-related files that are in the libsupc++
23     directory.
25     include/std
26       Files meant to be found by #include <name> directives in
27       standard-conforming user programs.  
29     include/c
30       Headers intended to directly include standard C headers. 
31       [NB: this can be enabled via --enable-cheaders=c]
33     include/c_std
34       Headers intended to include standard C headers, and put select
35       names into the std:: namespace.
36       [NB: this is the default, and is the same as --enable-cheaders=c_std]
38     include/c_shadow
39       Headers intended to shadow standard C headers provided by an
40       underlying OS or C library, and other headers depended on directly
41       by C++ headers (e.g. unistd.h).  These are meant to wrap the names
42       defined there into the _C_legacy namespace.
43       [NB: this can be enabled via --enable-cheaders=c_shadow]
45     include/bits
46       Files included by standard headers and by other files in
47       the bits directory. 
49     include/backward
50       Headers provided for backward compatibility, such as <iostream.h>.
51       They are not used in this library.
53     include/ext
54       Headers that define extensions to the standard library.  No
55       standard header refers to any of them.
57   src
58     Files that are used in constructing the library, but are not
59     installed.
61   testsuites/[thread, 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.
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:
75   config/cpu
76   config/os
77   config/io
78   config/locale
80 In addition, three subdirectories are convenience libraries:
82   libio
83     Contains the subset of the GNU libio library needed for
84     C++. Currently not used.
86   libmath
87     Support routines needed for C++ math. Only needed if the
88     underlying "C" implementation is non-existent, in particular
89     required or optimal long double, long long, and C99 functionality.
91   libsupc++
92     Contains the runtime library for C++, including exception
93     handling and memory allocation and deallocation, RTTI, terminate
94     handlers, etc.
96 Note that glibc also has a bits/ subdirectory.  We will either
97 need to be careful not to collide with names in its bits/
98 directory; or rename bits to (e.g.) cppbits/.
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.