README revision 132720
197403Sobrienfile: libstdc++-v3/README 297403Sobrien 397403SobrienNew users may wish to point their web browsers to the file 497403Sobriendocumentation.html in the 'docs/html' subdirectory. It contains brief 597403Sobrienbuilding instructions and notes on how to configure the library in 697403Sobrieninteresting ways. 797403Sobrien 897403SobrienInstructions for configuring and building appear in 997403Sobriendocs/html/install.html. 1097403Sobrien 1197403SobrienThis directory contains the files needed to create an ISO Standard C++ 1297403SobrienLibrary. 1397403Sobrien 1497403SobrienIt has subdirectories: 1597403Sobrien 1697403Sobrien docs 1797403Sobrien Files in HTML and text format that document usage, quirks of the 1897403Sobrien implementation, and contributor checklists. 1997403Sobrien 2097403Sobrien include 2197403Sobrien All header files for the C++ library are within this directory, 2297403Sobrien modulo specific runtime-related files that are in the libsupc++ 2397403Sobrien directory. 2497403Sobrien 2597403Sobrien include/std 2697403Sobrien Files meant to be found by #include <name> directives in 2797403Sobrien standard-conforming user programs. 2897403Sobrien 2997403Sobrien include/c 3097403Sobrien Headers intended to directly include standard C headers. 3197403Sobrien [NB: this can be enabled via --enable-cheaders=c] 3297403Sobrien 3397403Sobrien include/c_std 3497403Sobrien Headers intended to include standard C headers, and put select 3597403Sobrien names into the std:: namespace. 3697403Sobrien [NB: this is the default, and is the same as --enable-cheaders=c_std] 3797403Sobrien 3897403Sobrien include/c_shadow 3997403Sobrien Headers intended to shadow standard C headers provided by an 4097403Sobrien underlying OS or C library, and other headers depended on directly 4197403Sobrien by C++ headers (e.g. unistd.h). These are meant to wrap the names 4297403Sobrien defined there into the _C_legacy namespace. 4397403Sobrien [NB: this can be enabled via --enable-cheaders=c_shadow] 4497403Sobrien 4597403Sobrien include/bits 4697403Sobrien Files included by standard headers and by other files in 4797403Sobrien the bits directory. 4897403Sobrien 4997403Sobrien include/backward 5097403Sobrien Headers provided for backward compatibility, such as <iostream.h>. 5197403Sobrien They are not used in this library. 5297403Sobrien 5397403Sobrien include/ext 5497403Sobrien Headers that define extensions to the standard library. No 5597403Sobrien standard header refers to any of them. 5697403Sobrien 57132720Skan scripts 58132720Skan Scripts that are used during the configure, build, make, or test 59132720Skan process. 60132720Skan 6197403Sobrien src 6297403Sobrien Files that are used in constructing the library, but are not 6397403Sobrien installed. 6497403Sobrien 65132720Skan testsuites/[backward, demangle, ext, performance, thread, 17_* to 27_*] 6697403Sobrien Test programs are here, and may be used to begin to exercise the 6797403Sobrien library. Support for "make check" and "make check-install" is 6897403Sobrien complete, and runs through all the subdirectories here when this 6997403Sobrien command is issued from the build directory. Please note that 7097403Sobrien "make check" requires DejaGNU 1.4 or later to be installed. Please 7197403Sobrien note that "make check-script" calls the script mkcheck, which 7297403Sobrien requires bash, and which may need the paths to bash adjusted to 7397403Sobrien work properly, as /bin/bash is assumed. 7497403Sobrien 7597403SobrienOther subdirectories contain variant versions of certain files 7697403Sobrienthat are meant to be copied or linked by the configure script. 7797403SobrienCurrently these are: 7897403Sobrien 79132720Skan config/abi 8097403Sobrien config/cpu 8197403Sobrien config/io 8297403Sobrien config/locale 83132720Skan config/os 8497403Sobrien 85132720SkanIn addition, two subdirectories are convenience libraries: 8697403Sobrien 8797403Sobrien libmath 8897403Sobrien Support routines needed for C++ math. Only needed if the 8997403Sobrien underlying "C" implementation is non-existent, in particular 9097403Sobrien required or optimal long double, long long, and C99 functionality. 9197403Sobrien 9297403Sobrien libsupc++ 9397403Sobrien Contains the runtime library for C++, including exception 9497403Sobrien handling and memory allocation and deallocation, RTTI, terminate 9597403Sobrien handlers, etc. 9697403Sobrien 9797403SobrienNote that glibc also has a bits/ subdirectory. We will either 9897403Sobrienneed to be careful not to collide with names in its bits/ 9997403Sobriendirectory; or rename bits to (e.g.) cppbits/. 10097403Sobrien 10197403SobrienIn files throughout the system, lines marked with an "XXX" indicate 10297403Sobriena bug or incompletely-implemented feature. Lines marked "XXX MT" 10397403Sobrienindicate a place that may require attention for multi-thread safety. 104