libstdc++ Frequently Asked Questions

The latest version of this document is always available at http://sourceware.cygnus.com/libstdc++/faq/.

Questions

  1. General Information
    1. What is libstdc++-v3?
    2. Why should I use libstdc++?
    3. Who's in charge of it?
    4. How do I get libstdc++?
    5. When is libstdc++ going to be finished?
    6. How do I contribute to the effort?
    7. What if I have more questions?
  2. Installation
    1. How do I install libstdc++-v3?
    2. Is this a drop-in replacement for the libstdc++ that's shipped with EGCS?
    3. What is this CVS thing that you keep mentioning?
  3. Platform-Specific Issues
    1. Can libstdc++-v3 be used with <my favorite compiler>?
  4. Known Bugs and Non-Bugs
    1. What works already?
    2. Bugs in EGCS (not libstdc++-v3)
    3. Bugs in the C++ language/lib specification
  5. Miscellaneous
    1. string::iterator is not char*; vector<T>::iterator is not T*
    2. What's next after libstdc++-v3?
    3. What about the STL from SGI?
    4. Extensions and Backward Compatibility
    5. Compiling with "-fnew-abi"
  6. Received Wisdom, Notes, and HOWTOs
    1. What's this section for?
    2. Chapter 17 (Intro)
    3. Chapter 18 (Library Support)
    4. Chapter 19 (Diagnostics)
    5. Chapter 20 (Utilities)
    6. Chapter 21 (Strings)
    7. Chapter 22 (Localization)
    8. Chapter 23 (Containers)
    9. Chapter 24 (Iterators)
    10. Chapter 25 (Algorithms)
    11. Chapter 26 (Numerics)
    12. Chapter 27 (I/O)

1.0 General Information

1.1 What is libstdc++-v3?

The EGCS Standard C++ Library v3, or libstdc++-2.90.x, 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 the sixth 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 design document.


1.2 Why should I use libstdc++?

The recent 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 EGCS team. All of the rapid development and near-legendary 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 EGCS (gcc) or Linux. Benjamin Kosnik, Gabriel Dos Reis, Nathan Myers, 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 homepage. If you have questions, ideas, code, or are just curious, sign up!


1.4 How do I get libstdc++?

The fifth (and latest) snapshot of libstdc++-v3 is available via ftp.

The 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 in a recent Usenet article.


1.6 How do I contribute to the effort?

Cygnus has 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 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 libstdc++@sourceware.cygnus.com.

If you have a question that you think should be included here, or if you have a question about a question/answer here, contact Phil Edwards or 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:

The README and 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.


2.2 Is this a drop-in replacement for the libstdc++ that's shipped with EGCS?

Not in the sense that you're probably thinking.

Probably the easiest way to "replace" the older libstdc++-v2 is to do the following:

  1. Build EGCS as usual.
  2. Build libstdc++-v3 as usual.
  3. Build your code using -I and -L options so that EGCS finds the libstdc++-v3 headers and library before the older headers in the EGCS include tree.

If you configured libstdc++-v3 to install under a directory called /lib3, for example, the command line would look something like

      g++ -Wall -I/lib3/include/g++-v3 -L/lib3/lib foo.cc -o foo
         
More information (such as using SGI or GNU extensions, and setting the runtime library path) can be found in the RELEASE-NOTES.

The libstdc++-v3 releases cannot easily be used to overwrite the egcs-1.1.*/libstdc++/ directory directly. If you wish to build a version of EGCS with libstdc++-v3 "built in" like that, you should join the mailing list and review the list archives. (Among other things, libstdc++-v3 needs to be built with certain compiler options that v2 (shipped with EGCS) is not, so you will have to edit a number of Makefiles.)


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 and very high quality. The CVS entry in the GNU software catalogue has a better description as well as a 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.


3.0 Platform-Specific Issues

3.1 Can libstdc++-v3 be used with <my favorite compiler>?

Probably not.

Because EGCS 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 EGCS/g++, however.


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.

4.1 What works already?

This is a verbatim clip from the "Status" section of the homepage and RELEASE-NOTES for the latest snapshot.

New:

What works: (noted with the chapter # of the ISO-14882 standard)

What doesn't:


4.2 Bugs in EGCS (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 EGCS mailing lists.


4.2 Bugs in the C++ language/lib specification

Yes, unfortunately, there are some. In a 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 posted on his website. Developers who are having problems interpreting the Standard may wish to consult his notes.


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++.

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. Bugfixes and rewrites (to improve or fix thread safety, for instance) will of course be a continuing task.

This question about the next libstdc++ prompted some brief but interesting speculation.


5.3 What about the STL from SGI?

The STL from SGI is merged into libstdc++-v3 with changes as necessary. Currently release 3.2 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).

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>
         


5.5 Compiling with "-fnew-abi"

The library mostly works if you compile it (and programs you link with it) using "-fnew-abi -fno-honor-std" on a vanilla EGCS compiler. However, some features, such as RTTI and error handlers, might not link properly with a vanilla libgcc built in EGCS under the old ABI. If you rebuild libgcc using the "-f" flags above, you can get both complete language support and full benefits of -fnew-abi -- short mangled symbol names, far more efficient exception handling, and empty base optimization, to name a few. (Note that the new ABI may change from one EGCS snapshot to the next, so you would have to rebuild all your libraries each time you get a new compiler snapshot.)


6.0 Received Wisdom, Notes, and HOWTOs

6.1 What's this section for?

We will be the first to say that the C++ Standard Library is somewhat new and unusual. Both beginners and seasoned veterans can get confused when writing new code or porting older code from other implementations.

The libstdc++-v3 team is assembling a collection of useful tips and notes on how to do common tasks with the classes and functions offered by the Library. This section is broken up by the chapters of the ISO Standard which concern the Library.


Comments and suggestions are welcome, and may be sent to Phil Edwards or Gabriel Dos Reis.