diff options
Diffstat (limited to 'libstdc++-v3/docs/html/faq/index.txt')
| -rw-r--r-- | libstdc++-v3/docs/html/faq/index.txt | 603 |
1 files changed, 603 insertions, 0 deletions
diff --git a/libstdc++-v3/docs/html/faq/index.txt b/libstdc++-v3/docs/html/faq/index.txt new file mode 100644 index 00000000000..b10d61c91ee --- /dev/null +++ b/libstdc++-v3/docs/html/faq/index.txt @@ -0,0 +1,603 @@ + + libstdc++ Frequently Asked Questions + + The latest version of this document is always available at + [1]http://gcc.gnu.org/onlinedocs/libstdc++/faq/. + + To the [2]libstdc++-v3 homepage. + _________________________________________________________________ + + Questions + + 1. [3]General Information + 1. [4]What is libstdc++-v3? + 2. [5]Why should I use libstdc++? + 3. [6]Who's in charge of it? + 4. [7]How do I get libstdc++? + 5. [8]When is libstdc++ going to be finished? + 6. [9]How do I contribute to the effort? + 7. [10]What happened to libg++? I need that! + 8. [11]What if I have more questions? + 2. [12]Installation + 1. [13]How do I install libstdc++-v3? + 2. [14]Is this a drop-in replacement for the libstdc++ that's + shipped with g++? + 3. [15]What is this CVS thing that you keep mentioning? + 4. [16]How do I know if it works? + 3. [17]Platform-Specific Issues + 1. [18]Can libstdc++-v3 be used with <my favorite compiler>? + 2. [19]Building under Cygwin hangs/explodes!? + 4. [20]Known Bugs and Non-Bugs + 1. [21]What works already? + 2. [22]Bugs in gcc/g++ (not libstdc++-v3) + 3. [23]Bugs in the C++ language/lib specification + 4. [24]Things in libstdc++ that look like bugs + [25]The g++-3 headers are not ours + 5. [26]Aw, that's easy to fix! + 5. [27]Miscellaneous + 1. [28]string::iterator is not char*; vector<T>::iterator is not + T* + 2. [29]What's next after libstdc++-v3? + 3. [30]What about the STL from SGI? + 4. [31]Extensions and Backward Compatibility + 5. [32]Compiling with "-fnew-abi" + 6. [33]Is libstdc++-v3 thread-safe? + 7. [34]How do I get a copy of the ISO C++ Standard? + _________________________________________________________________ + + 1.0 General Information + +1.1 What is libstdc++-v3? + + The GNU Standard C++ Library v3, or libstdc++-2.90.x/2.9x, is an + ongoing project to implement the ISO 14882 Standard C++ library as + described in chapters 17 through 27 and annex D. As the library + reaches stable plateaus, it is captured in a snapshot and released. + The current release is [35]the tenth snapshot. For those who want to + see exactly how far the project has come, or just want the latest + bleeding-edge code, the up-to-date source is available over anonymous + CVS, and can even be browsed over the Web (see below). + + A more formal description of the V3 goals can be found in the official + [36]design document. + _________________________________________________________________ + +1.2 Why should I use libstdc++? + + The completion of the ISO C++ standardization gave the C++ community a + powerful set of reuseable tools in the form of the C++ Standard + Library. However, all existing C++ implementations are (as the Draft + Standard used to say) "incomplet and incorrekt," and many suffer from + limitations of the compilers that use them. + + The GNU C/C++/FORTRAN/<pick-a-language> compiler (gcc, g++, etc) is + widely considered to be one of the leading compilers in the world. Its + development has recently been taken over by the [37]GCC team. All of + the rapid development and near-legendary [38]portability that are the + hallmarks of an open-source project are being applied to libstdc++. + + That means that all of the Standard classes and functions (such as + string, vector<>, iostreams, and algorithms) will be freely available + and fully compliant. Programmers will no longer need to "roll their + own" nor be worried about platform-specific incompatabilities. + _________________________________________________________________ + +1.3 Who's in charge of it? + + The libstdc++ project is contributed to by several developers all over + the world, in the same way as GCC or Linux. Benjamin Kosnik, Gabriel + Dos Reis, Phil Edwards, and Ulrich Drepper are the lead maintainers of + the CVS archive. + + Development and discussion is held on the libstdc++ mailing list. + Subscribing to the list, or searching the list archives, is open to + everyone. You can read instructions for doing so on the [39]homepage. + If you have questions, ideas, code, or are just curious, sign up! + _________________________________________________________________ + +1.4 How do I get libstdc++? + + The tenth (and latest) snapshot of libstdc++-v3 is [40]available via + ftp. + + The [41]homepage has instructions for retrieving the latest CVS + sources, and for browsing the CVS sources over the web. + + The subset commonly known as the Standard Template Library (chapters + 23 through 25, mostly) is adapted from the SGI STL, which is also an + ongoing work. + _________________________________________________________________ + +1.5 When is libstdc++ going to be finished? + + Nathan Myers gave the best of all possible answers, responding to a + Usenet article asking this question: Sooner, if you help. + _________________________________________________________________ + +1.6 How do I contribute to the effort? + + Here is [42]a page devoted to this topic. Subscribing to the mailing + list (see above, or the homepage) is a very good idea if you have + something to contribute, or if you have spare time and want to help. + Contributions don't have to be in the form of source code; anybody who + is willing to help write documentation, for example, or has found a + bug in code that we all thought was working, is more than welcome! + _________________________________________________________________ + +1.7 What happened to libg++? I need that! + + The most recent libg++ README states that libg++ is no longer being + actively maintained. It should not be used for new projects, and is + only being kicked along to support older code. + + The libg++ was designed and created when there was no Standard to + provide guidance. Classes like linked lists are now provided for by + list<T> and do not need to be created by genclass. (For that matter, + templates exist now and are well-supported, whereas genclass (mostly) + predates them.) + + There are other classes in libg++ that are not specified in the ISO + Standard (e.g., statistical analysis). While there are a lot of really + useful things that are used by a lot of people (e.g., statistics :-), + the Standards Committee couldn't include everything, and so a lot of + those "obvious" classes didn't get included. + + Since libstdc++ is an implementation of the Standard Library, we have + no plans at this time to include non-Standard utilities in the + implementation, however handy they are. (The extensions provided in + the SGI STL aren't maintained by us and don't get a lot of our + attention, because they don't require a lot of our time.) It is + entirely plausable that the "useful stuff" from libg++ might be + extracted into an updated utilities library, but nobody has stated + such a project yet. + + (The [43]Boost site houses free C++ libraries that do varying things, + and happened to be started by members of the Standards Committee. + Certain "useful stuff" classes will probably migrate there.) + + For the bold and/or desperate, the [44]GCC FAQ describes where to find + the last libg++ source. + _________________________________________________________________ + +1.8 What if I have more questions? + + If you have read the README and RELEASE-NOTES files, and your question + remains unanswered, then just ask the mailing list. At present, you do + not need to be subscribed to the list to send a message to it. More + information is available on the homepage (including how to browse the + list archives); to send to the list, use [45]libstdc++@gcc.gnu.org. + + If you have a question that you think should be included here, or if + you have a question about a question/answer here, contact [46]Phil + Edwards or [47]Gabriel Dos Reis. + _________________________________________________________________ + + 2.0 Installation + +2.1 How do I install libstdc++-v3? + + Complete instructions are not given here (this is a FAQ, not an + installation document), but the tools required are few: + * A release of libstdc++. + * A recent release of GCC (version 2.95 works). Note that building + GCC is much easier and more automated than building the GCC 2.[78] + series was. + * If you plan on hacking around with the makefiles, you will need + the tools [48]autoconfand [49]automake. + * GNU Make is the only make that supports these makefiles. + + The file [50]documentation.html provides a good overview of the steps + necessary to build, install, and use the library. Instructions for + configuring the library with new flags such as --enable-threads are + there also. + + The top-level install.html and [51]RELEASE-NOTES files contain the + exact build and installation instructions. You may wish to browse + those files over CVSweb ahead of time to get a feel for what's + required. RELEASE-NOTES is located in the ".../docs/17_intro/" + directory of the distribution. + _________________________________________________________________ + +2.2 Is this a drop-in replacement for the libstdc++ that's shipped with g++? + + Yes, as of 2.90.8, it is intended as such. And as of 2.91, + libstdc++-v3 is the library that's shipped with g++, so much of this + answer has become moot. + _________________________________________________________________ + +2.3 What is this CVS thing that you keep mentioning? + + The Concurrent Versions System is one of several revision control + packages. It was selected for GNU projects because it's free (speech), + free (beer), and very high quality. The [52]CVS entry in the GNU + software catalogue has a better description as well as a [53]link to + the makers of CVS. + + The "anonymous client checkout" feature of CVS is similar to anonymous + FTP in that it allows anyone to retrieve the latest libstdc++ sources. + + After the first of April, American users will have a "/pharmacy" + command-line option... + _________________________________________________________________ + +2.4 How do I know if it works? + + libstdc++-v3 comes with its own testsuite. You do not need to actually + install the library ("gmake install") to run the testsuite. Note that + 2.91 does not use DejaGNU yet. + + To run the testsuite on the library after building it, use "gmake + check" while in your build directory. To run the testsuite on the + library after building and installing it, use "gmake check-install" + instead. + + The testsuite subdirectory in your build directory will then contain + three files of the form YYYYMMDD-mkcheck*.txt. One of them + (-mkcheck.txt itself) contains the results of the tests; this can be + mailed to the list. The other files (-mkchecklog.txt and + -mkcheckfiles.txt) contain messages from the compiler while building + the test programs, and a list of the tests to be run, respectively. + + If you find bugs in the testsuite programs themselves, or if you think + of a new test program that should be added to the suite, please write + up your idea and send it to the list! + _________________________________________________________________ + + 3.0 Platform-Specific Issues + +3.1 Can libstdc++-v3 be used with <my favorite compiler>? + + Probably not. Yet. + + Because GCC advances so rapidly, development and testing of libstdc++ + is being done almost entirely under that compiler. If you are curious + about whether other, lesser compilers (*grin*) support libstdc++, you + are more than welcome to try. Configuring and building the library + (see above) will still require certain tools, however. Also keep in + mind that building libstdc++ does not imply that your compiler will be + able to use all of the features found in the C++ Standard Library. + + Since the goal of ISO Standardization is for all C++ implementations + to be able to share code, the final libstdc++ should, in theory, be + useable under any ISO-compliant compiler. It will still be targeted + and optimized for GCC/g++, however. + _________________________________________________________________ + +3.2 Building under Cygwin hangs/explodes!? + + Sometimes, yes. You're probably in the middle of generating the + numeric_limits specializations when it hangs, right? Thought so... + + The <limits> header and its associated library code are + platform-specific. These files get generated from scratch during + installation, and it is this generator that is hanging. More + specifically, the only sure way to determine what the + numeric_limits<T>::traps boolean should be is to actually divide by + zero and see if it is trapped or not. + + Under NT, this will occasionally just hang. On those occasions when + the test does not hang, the zero-division is in fact trapped. That + doesn't prevent hanging elsewhere. + + You have two options. You can get a newer cygwin1.dll (see the Cygwin + paragraph in the [54]installation instructions). Or you can get a + prebuilt set of bits/std_limits.h and src/limitsMEMBERS.cc files from + Mumit Khan's [55]Cygwin-related website. + _________________________________________________________________ + + 4.0 Known Bugs and Non-Bugs + + Note that this section can get rapdily outdated -- such is the nature + of an open-source project. For the latest information, join the + mailing list or look through recent archives. The RELEASE- NOTES and + BUGS files are generally kept up-to-date. + +4.1 What works already? + + This is a verbatim clip from the "Status" section of the RELEASE-NOTES + for the latest snapshot. +New: +- namespace std:: is now on by default. +- choice of "C" include strategies, including the shadow header work, + or generic global to std mapping of required "C" types. +- cpu/atomicity.h tweaks, additions of ia64 and arm support. +- abstraction of atomicity.h header to support notion of os/atomicity.h files. +- addition of backward header bits +- use of system_header pragma +- Conditional use of -Werror +- preliminary support for new g++ diagnostics capabilities, including + -fdiagnostics-show-location=once +- pedantic and shadow argument warning fixes +- Ugly, yet correct mechanism for dealing with "C" math adopted, + including the use of builtins. +- updates and configure/build work to support new libtool +- addition of strstream +- valarray work +- complex work +- update to SGI STL 3.3 +- libio sync between glibc/libstdc++-v3. Some divergence since initial + merge, but sources remain quite close. +- IO fixes for alpha +- wide character work for IO when using libio +- addition of c_io_stdio and "C" IO abstraction layer. +- auto_ptr fixes, testsuite additions +- Attempts to use -ffunction-sections -fdata-sections and + --gc-sections, depending on use of GNU ld and specific features. As of + late, --gc-sections has been disabled due to problems with it throwing + away initialization sections. This work is ongoing. +- long double support +- sub directory removal, coherent organization of cpu and os-specific + files, consolidation of include directories, integration of the C++ + support bits for operator new/delete,exceptions, etc. All includes + are now either in the include/* hierarchy or in libsupc++'s sub directory. +- Support for more platforms, including irix and bsd variants. +- filebuf tweaks to deal with variable-size buffers. +- filebuf implementation for putbackc, etc. al. +- ctype rewritten. Includes ctype, ctype, and others. +- codecvt rewritten. Includes codecvt, + codecvt. In addition, + implementation-defined conversions using iconv are now supported with + the __enc_traits partial-specialization of the State template + parameter of the codecvt class. In this manner, conversions between + encodings such as UCS4, USC2, UNICODE, UNICODEBIG, UNICODELITTLE, etc + can be performed. +- preliminary work on named locales +- preliminary documentation for locale implementation has been established. +- Many, many bug fixes. +- Many, many testsuite additions and consistent VERIFY usage. +- work on mkcheck to make it more flexible, use libtool, etc. + _________________________________________________________________ + +4.2 Bugs in gcc/g++ (not libstdc++-v3) + + This is by no means meant to be complete nor exhaustive, but mentions + some problems that users may encounter when building or using + libstdc++. If you are experiencing one of these problems, you can find + more information on the libstdc++ and the GCC mailing lists. + * As of 2.91, these bugs have all been fixed. We look forward to new + ones, well, not exactly... + _________________________________________________________________ + +4.3 Bugs in the C++ language/lib specification + + Yes, unfortunately, there are some. In a [56]message to the list, + Nathan Myers announced that he has started a list of problems in the + ISO C++ Standard itself, especially with regard to the chapters that + concern the library. The list itself is [57]posted on his website. + Developers who are having problems interpreting the Standard may wish + to consult his notes. + + For those people who are not part of the ISO Library Group (i.e., + nearly all of us needing to read this page in the first place :-), a + public list of the library defects is occasionally published [58]here. + _________________________________________________________________ + +4.4 Things in libstdc++ that look like bugs + + There are things which are not bugs in the compiler (4.2) nor the + language specification (4.3), but aren't really bugs in libstdc++, + either. Really! + + The biggest of these is the quadzillions of warnings about the library + headers emitted when -Weffc++ is used. Making libstdc++ + "-Weffc++-clean" is not a goal of the project, for a few reasons. + Mainly, that option tries to enforce object-oriented programming, + while the Standard Library isn't necessarily trying to be OO. There + are multiple solutions under discussion. + + The g++-3 headers are not ours + + If you have found an extremely broken header file which is causing + problems for you, look carefully before submitting a "high" priority + bug report (which you probably shouldn't do anyhow; see the last + paragraph of the page describing [59]the GCC bug database). + + If the headers are in ${prefix}/include/g++-3, then you are using the + old libstdc++-v2 library, which is nonstandard and unmaintained. Do + not report problems with -v2 to the -v3 mailing list. + + Currently our header files are installed in ${prefix}/include/g++-v3 + (see the 'v'?). This may change with the next release of GCC, as it + may be too confusing, but [60]the question has not yet been decided. + _________________________________________________________________ + +4.5 Aw, that's easy to fix! + + If you have found a bug in the library and you think you have a + working fix, then send it in! The main GCC site has a page on + [61]submitting patches that covers the procedure, but for libstdc++ + you should of course send the patch to our mailing list, not the GCC + mailing list. The libstdc++ [62]contributors' page also talks about + how to submit patches. + + In addition to the description, the patch, and the ChangeLog entry, it + is a Good Thing if you can additionally create a small test program to + test for the presence of the bug that your patch fixes. Bugs have a + way of being reintroduced; if an old bug creeps back in, it will be + caught immediately by the [63]testsuite -- but only if such a test + exists. + _________________________________________________________________ + + 5.0 Miscellaneous + +5.1 string::iterator is not char*; vector<T>::iterator is not T* + + If you have code that depends on container<T> iterators being + implemented as pointer-to-T, your code is broken. + + While there are arguments for iterators to be implemented in that + manner, A) they aren't very good ones in the long term, and B) they + were never guaranteed by the Standard anyway. The type-safety achieved + by making iterators a real class rather than a typedef for T* + outweighs nearly all opposing arguments. + _________________________________________________________________ + +5.2 What's next after libstdc++-v3? + + Hopefully, not much. The goal of libstdc++-v3 is to produce a + fully-compliant, fully-portable Standard Library. After that, we're + mostly done: there won't be any more compliance work to do. + + The ISO Committee will meet periodically to review Defect Reports in + the C++ Standard. Undoubtably some of these will result in changes to + the Standard, which will be reflected in patches to libstdc++. Some of + that is already happening, see 4.2. Some of those changes are being + predicted by the library maintainers, and we add code to the library + based on what the current proposed resolution specifies. + + The current libstdc++ contains extensions to the Library which must be + explicitly requested by client code (for example, the hash tables from + SGI). Other extensions may be added to libstdc++-v3 if they seem to be + "standard" enough. (For example, the "long long" type from C99.) + Bugfixes and rewrites (to improve or fix thread safety, for instance) + will of course be a continuing task. + + [64]This question about the next libstdc++ prompted some brief but + interesting [65]speculation. + _________________________________________________________________ + +5.3 What about the STL from SGI? + + The [66]STL from SGI is merged into libstdc++-v3 with changes as + necessary. Currently release 3.3 is being used. Changes in the STL + usually produce some weird bugs and lots of changes in the rest of the + libstd++ source as we scramble to keep up. :-) + + In particular, string is not from SGI and makes no use of their "rope" + class (which is included as an optional extension), nor is valarray + and some others. Classes like vector<> are, however. + + The FAQ for SGI's STL (one jump off of their main page) is recommended + reading. + _________________________________________________________________ + +5.4 Extensions and Backward Compatibility + + Although you can specify -I options to make the preprocessor search + the g++-v3/ext and /backward directories, it is better to refer to + files there by their path, as in: + #include <ext/hash_map> + + + Extensions to the library have [67]their own page. + _________________________________________________________________ + +5.5 Compiling with "-fnew-abi" + + Towards the end of July 1999, this subject was brought up again on the + mailing list under a different name. The related [68]thread (by the + name HOWTO-honor-std) is very instructive. More info is at the end of + RELEASE-NOTES. + + This functionality is now automated and turned on by default. + _________________________________________________________________ + +5.6 Is libstdc++-v3 thread-safe? + + Quick answer: no, as of 2.91 (tenth snapshot), the library is not + appropriate for multithreaded access. The string class is MT-safe. + + This is assuming that your idea of "multithreaded" is the same as + ours... The general question of multithreading and libstdc++-v3 is + addressed in the chapter-specific advice for [69]Library Introduction. + Threadsafe containers are covered in more detail in [70]the Received + Wisdom section on containers. + _________________________________________________________________ + +5.7 How do I get a copy of the ISO C++ Standard? + + Copies of the full ISO 14882 standard are available on line via the + ISO mirror site for committee members. Non-members, or those who have + not paid for the privilege of sitting on the committee and sustained + their two-meeting commitment for voting rights, may get a copy of the + standard from their respective national standards organization. In the + USA, this national standards organization is ANSI and their website is + right [71]here. (And if you've already registered with them, clicking + this link will take you to directly to the place where you can [72]buy + the standard on-line. + + Who is your country's member body? Visit the [73]ISO homepage and find + out! + _________________________________________________________________ + + Comments and suggestions are welcome, and may be sent to [74]Phil + Edwards or [75]Gabriel Dos Reis. + $Id: index.html,v 1.10 2000/12/03 23:47:49 jsm28 Exp $ + +References + + 1. http://gcc.gnu.org/onlinedocs/libstdc++/faq/ + 2. http://gcc.gnu.org/libstdc++/ + 3. ../faq/index.html#1_0 + 4. ../faq/index.html#1_1 + 5. ../faq/index.html#1_2 + 6. ../faq/index.html#1_3 + 7. ../faq/index.html#1_4 + 8. ../faq/index.html#1_5 + 9. ../faq/index.html#1_6 + 10. ../faq/index.html#1_7 + 11. ../faq/index.html#1_8 + 12. ../faq/index.html#2_0 + 13. ../faq/index.html#2_1 + 14. ../faq/index.html#2_2 + 15. ../faq/index.html#2_3 + 16. ../faq/index.html#2_4 + 17. ../faq/index.html#3_0 + 18. ../faq/index.html#3_1 + 19. ../faq/index.html#3_2 + 20. ../faq/index.html#4_0 + 21. ../faq/index.html#4_1 + 22. ../faq/index.html#4_2 + 23. ../faq/index.html#4_3 + 24. ../faq/index.html#4_4 + 25. ../faq/index.html#4_4_interface + 26. ../faq/index.html#4_5 + 27. ../faq/index.html#5_0 + 28. ../faq/index.html#5_1 + 29. ../faq/index.html#5_2 + 30. ../faq/index.html#5_3 + 31. ../faq/index.html#5_4 + 32. ../faq/index.html#5_5 + 33. ../faq/index.html#5_6 + 34. ../faq/index.html#5_7 + 35. ftp://gcc.gnu.org/pub/libstdc++/libstdc++-2.91.tar.gz + 36. ../17_intro/DESIGN + 37. http://gcc.gnu.org/ + 38. http://gcc.gnu.org/gcc-2.95/buildstat.html + 39. http://gcc.gnu.org/libstdc++/ + 40. ftp://gcc.gnu.org/pub/libstdc++/libstdc++-2.91.tar.gz + 41. http://gcc.gnu.org/libstdc++/ + 42. ../17_intro/contribute.html + 43. http://www.boost.org/ + 44. http://gcc.gnu.org/fom_serv/cache/33.html + 45. mailto:libstdc++@gcc.gnu.org + 46. mailto:pme@sources.redhat.com + 47. mailto:gdr@gcc.gnu.org + 48. http://sources.redhat.com/autoconf/ + 49. http://sources.redhat.com/automake/ + 50. ../documentation.html + 51. ../17_intro/RELEASE-NOTES + 52. http://www.gnu.org/software/cvs/cvs.html + 53. http://www.cyclic.com/ + 54. ../install.html + 55. http://www.xraylith.wisc.edu/~khan/software/gnu-win32/libstdc++-v3.html + 56. http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html + 57. http://www.cantrip.org/draft-bugs.txt + 58. http://anubis.dkuug.dk/jtc1/sc22/wg21/ + 59. http://gcc.gnu.org/gnatswrite.html + 60. http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html + 61. http://gcc.gnu.org/contribute.html + 62. ../17_intro/contribute.html + 63. ../faq/index.html#2_4 + 64. http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html + 65. http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html + 66. http://www.sgi.com/Technology/STL/ + 67. ../ext/howto.html + 68. http://gcc.gnu.org/ml/libstdc++/1999-q3/msg00066.html + 69. http://gcc.gnu.org/libstdc++/17_intro/howto.html#3 + 70. http://gcc.gnu.org/libstdc++/23_containers/howto.html + 71. http://www.ansi.org/ + 72. http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998 + 73. http://www.iso.ch/ + 74. mailto:pme@sources.redhat.com + 75. mailto:gdr@gcc.gnu.org |