+++ /dev/null
-<?xml version="1.0" encoding="ISO-8859-1"?>
-<!DOCTYPE html
- PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
- <meta name="KEYWORDS" content="libstdc++, libstdc++-v3, GCC, g++, libg++, STL" />
- <meta name="DESCRIPTION" content="FAQ for the GNU libstdc++ effort." />
- <title>libstdc++-v3 FAQ</title>
-<link rel="StyleSheet" href="../lib3styles.css" />
-<!--
- ** Locations of "the most recent snapshot is the Nth" text are
- ** answers 1_1, 1_4, 4_1.
--->
-</head>
-<body>
-
-<h1 class="centered">libstdc++ Frequently Asked Questions</h1>
-
-<p>The latest version of this document is always available at
- <a href="http://gcc.gnu.org/onlinedocs/libstdc++/faq/">
- http://gcc.gnu.org/onlinedocs/libstdc++/faq/</a>. The main documentation
- page is at
- <a href="http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html">
- http://gcc.gnu.org/onlinedocs/libstdc++/documentation.html</a>.
-</p>
-
-<p>To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</a>.
-</p>
-
-<!-- ####################################################### -->
-<hr />
-<h1>Questions</h1>
-<ol>
- <li><a href="#1_0">General Information</a>
- <!-- I suspect these will mostly be links to/into existing documents. -->
- <ol>
- <li><a href="#1_1">What is libstdc++-v3?</a> </li>
- <li><a href="#1_2">Why should I use libstdc++?</a> </li>
- <li><a href="#1_3">Who's in charge of it?</a> </li>
- <li><a href="#1_4">How do I get libstdc++?</a> </li>
- <li><a href="#1_5">When is libstdc++ going to be finished?</a> </li>
- <li><a href="#1_6">How do I contribute to the effort?</a> </li>
- <li><a href="#1_7">What happened to libg++? I need that!</a> </li>
- <li><a href="#1_8">What if I have more questions?</a> </li>
- <li><a href="#1_9">What are the license terms for libstdc++-v3?</a> </li>
- </ol>
- </li>
-
- <li><a href="#2_0">Installation</a>
- <ol>
- <li><a href="#2_1">How do I install libstdc++-v3?</a> </li>
- <li><a href="#2_2">[removed]</a> </li>
- <li><a href="#2_3">What is this CVS thing that you keep
- mentioning?</a> </li>
- <li><a href="#2_4">How do I know if it works?</a> </li>
- <li><a href="#2_5">This library is HUGE! And what's libsupc++?</a> </li>
- </ol>
- </li>
-
- <li><a href="#3_0">Platform-Specific Issues</a>
- <ol>
- <li><a href="#3_1">Can libstdc++-v3 be used with <my
- favorite compiler>?</a> </li>
- <li><a href="#3_2">[removed]</a> </li>
- <li><a href="#3_3">[removed]</a> </li>
- <li><a href="#3_4">I can't use 'long long' on Solaris</a> </li>
- <li><a href="#3_5"><code>_XOPEN_SOURCE</code> /
- <code>_GNU_SOURCE</code> / etc is always defined</a>
- </li>
- <li><a href="#3_6">OS X ctype.h is broken! How can I hack it?</a></li>
- <li><a href="#3_7">Threading is broken on i386</a></li>
- </ol>
- </li>
-
- <li><a href="#4_0">Known Bugs and Non-Bugs</a>
- <ol>
- <li><a href="#4_1">What works already?</a> </li>
- <li><a href="#4_2">Bugs in gcc/g++ (not libstdc++-v3)</a> </li>
- <li><a href="#4_3">Bugs in the C++ language/lib specification</a> </li>
- <li><a href="#4_4">Things in libstdc++ that only look like bugs</a><ul>
- <li><a href="#4_4_iostreamclear">reopening a stream fails</a> </li>
- <li><a href="#4_4_Weff">-Weffc++ complains too much</a> </li>
- <li><a href="#4_4_rel_ops">"ambiguous overloads"
- after including an old-style header</a> </li>
- <li><a href="#4_4_interface">The g++-3 headers are
- <strong>not ours</strong></a> </li>
- <li><a href="#4_4_glibc">compilation errors from streambuf.h</a> </li>
- <li><a href="#4_4_checks">errors about <em>*Concept</em> and
- <em>constraints</em> in the STL...</a> </li>
- <li><a href="#4_4_dlsym">program crashes when using library code
- in a dynamically-loaded library</a> </li>
- </ul>
- </li>
- <li><a href="#4_5">Aw, that's easy to fix!</a> </li>
- </ol>
- </li>
-
- <li><a href="#5_0">Miscellaneous</a>
- <ol>
- <li><a href="#5_1">string::iterator is not char*;
- vector<T>::iterator is not T*</a> </li>
- <li><a href="#5_2">What's next after libstdc++-v3?</a> </li>
- <li><a href="#5_3">What about the STL from SGI?</a> </li>
- <li><a href="#5_4">Extensions and Backward Compatibility</a> </li>
- <li><a href="#5_5">[removed]</a> </li>
- <li><a href="#5_6">Is libstdc++-v3 thread-safe?</a> </li>
- <li><a href="#5_7">How do I get a copy of the ISO C++ Standard?</a> </li>
- <li><a href="#5_8">What's an ABI and why is it so messy?</a> </li>
- </ol>
- </li>
-
-</ol>
-
-<hr />
-
-<!-- ####################################################### -->
-
-<h1><a name="1_0">1.0 General Information</a></h1>
-<!-- I suspect these will mostly be links to/into existing documents. -->
- <h2><a name="1_1">1.1 What is libstdc++-v3?</a></h2>
- <p>The GNU Standard C++ Library v3 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 latest release is
- <a href="http://gcc.gnu.org/libstdc++/index.html#download">the
- fourteenth snapshot</a> but newer versions have been included
- in recent GCC releases. 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
- <a href="#1_4">1.4</a> below).
- </p>
- <p>The older libstdc++-v2 project is no longer maintained; the code
- has been completely replaced and rewritten.
- <a href="#4_4_interface">If you are using V2</a>, then you need to
- report bugs to your system vendor, not to the V3 list.
- </p>
- <p>A more formal description of the V3 goals can be found in the
- official <a href="../17_intro/DESIGN">design document</a>.
- </p>
-
-<hr />
- <h2><a name="1_2">1.2 Why should I use libstdc++?</a></h2>
- <p>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.
- </p>
- <p>The GNU C/C++/FORTRAN/<pick-a-language> compiler
- (<code>gcc</code>, <code>g++</code>, etc) is widely considered to be
- one of the leading compilers in the world. Its development
- has recently been taken over by the
- <a href="http://gcc.gnu.org/">GCC team</a>. All of
- the rapid development and near-legendary
- <a href="http://gcc.gnu.org/gcc-3.0/buildstat.html">portability</a>
- that are the hallmarks of an open-source project are being
- applied to libstdc++.
- </p>
- <p>That means that all of the Standard classes and functions
- (such as <code>string</code>, <code>vector<></code>, 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 incompatibilities.
- </p>
-
-<hr />
- <h2><a name="1_3">1.3 Who's in charge of it?</a></h2>
- <p>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, Ulrich Drepper,
- Loren James Rittle, and Paolo Carlini are the lead maintainers of
- the CVS archive.
- </p>
- <p>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 <a href="http://gcc.gnu.org/libstdc++/">homepage</a>.
- If you have questions, ideas, code, or are just curious, sign up!
- </p>
-
-<hr />
- <h2><a name="1_4">1.4 How do I get libstdc++?</a></h2>
- <p>The fourteenth (and latest) snapshot of libstdc++-v3 is
- <a href="http://gcc.gnu.org/libstdc++/index.html#download">available
- via ftp</a>.
- </p>
- <p>The <a href="http://gcc.gnu.org/libstdc++/">homepage</a>
- has instructions for retrieving the latest CVS sources, and for
- browsing the CVS sources over the web.
- </p>
- <p>The subset commonly known as the Standard Template Library
- (chapters 23 through 25, mostly) is adapted from the final release
- of the SGI STL.
- </p>
-
-<hr />
- <h2><a name="1_5">1.5 When is libstdc++ going to be finished?</a></h2>
-<!-- <p>Nathan Myers gave the best of all possible answers in <a
- href="http://www.deja.com/getdoc.xp?AN=469581698&fmt=text">a
- Usenet article</a>.</p>
-which is no longer available, thanks deja...-->
- <p>Nathan Myers gave the best of all possible answers, responding to a
- Usenet article asking this question: <em>Sooner, if you help.</em>
- </p>
-
-<hr />
- <h2><a name="1_6">1.6 How do I contribute to the effort?</a></h2>
- <p>Here is <a href="../17_intro/contribute.html">a
- page devoted to this topic</a>. 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!
- </p>
-
-<hr />
- <h2><a name="1_7">1.7 What happened to libg++? I need that!</a></h2>
- <p>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.
- </p>
- <p>The libg++ was designed and created when there was no Standard
- to provide guidance. Classes like linked lists are now provided
- for by <code>list<T></code> and do not need to be created by
- <code>genclass</code>. (For that matter, templates exist now and
- are well-supported, whereas genclass (mostly) predates them.)
- </p>
- <p>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.
- </p>
- <p>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.
- </p>
- <!-- The advertisement, so to speak, might have to go. Hmmmmm. -->
- <p>(The <a href="http://www.boost.org/">Boost</a> 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.)
- </p>
- <p>For the bold and/or desperate, the
- <a href="http://gcc.gnu.org/fom_serv/cache/33.html">GCC FAQ</a>
- describes where to find the last libg++ source.
- </p>
-
-<hr />
- <h2><a name="1_8">1.8 What if I have more questions?</a></h2>
- <p>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 <a href="mailto:libstdc++@gcc.gnu.org">
- <code>libstdc++@gcc.gnu.org</code></a>.
- </p>
- <p>If you have a question that you think should be included here,
- or if you have a question <em>about</em> a question/answer here,
- contact <a href="mailto:pme@gcc.gnu.org">Phil Edwards</a>
- or <a href="mailto:gdr@gcc.gnu.org">Gabriel Dos Reis</a>.
- </p>
-
-<hr />
- <h2><a name="1_9">1.9 What are the license terms for libstdc++-v3?</a></h2>
- <p>See <a href="../17_intro/license.html">our license description</a>
- for these and related questions.
- </p>
-
-<hr />
-<h1><a name="2_0">2.0 Installation</a></h1>
- <h2><a name="2_1">2.1 How do I install libstdc++-v3?</a></h2>
- <p>Complete instructions are not given here (this is a FAQ, not
- an installation document), but the tools required are few:
- </p>
- <ul>
- <li> A 3.x release of GCC. Note that building GCC is much
- easier and more automated than building the GCC 2.[78]
- series was. If you are using GCC 2.95, you can still
- build earlier snapshots of libstdc++.
- </li>
- <li> GNU Make is recommended, but should not be required.
- </li>
- <li> The GNU Autotools are needed if you are messing with
- the configury or makefiles.
- </li>
- </ul>
- <p>The file <a href="../documentation.html">documentation.html</a>
- 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, as well as
- patches and instructions for working with GCC 2.95.
- </p>
- <p>The top-level install.html and
- <a href="../17_intro/RELEASE-NOTES">RELEASE-NOTES</a> 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.
- </p>
-
-<hr />
- <h2><a name="2_2">2.2 [removed]</a></h2>
- <p>This question has become moot and has been removed. The stub
- is here to preserve numbering (and hence links/bookmarks).
- </p>
-
-<hr />
- <h2><a name="2_3">2.3 What is this CVS thing that you
- keep mentioning?</a></h2>
- <p>The <em>Concurrent Versions System</em> 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 <a
- href="http://www.gnu.org/software/cvs/cvs.html">CVS entry in
- the GNU software catalogue</a> has a better description as
- well as a
- <a href="http://www.cvshome.org/">link to the makers of CVS</a>.
- </p>
- <p>The "anonymous client checkout" feature of CVS is
- similar to anonymous FTP in that it allows anyone to retrieve
- the latest libstdc++ sources.
- </p>
- <p>After the first of April, American users will have a
- "/pharmacy" command-line option...
- <!-- wonder how long that'll live -->
- </p>
-
-<hr />
- <h2><a name="2_4">2.4 How do I know if it works?</a></h2>
- <p>libstdc++-v3 comes with its own testsuite. You do not need
- to actually install the library ("<code>make
- install</code>") to run the testsuite.
- </p>
- <p>To run the testsuite on the library after building it, use
- "make check" while in your build directory. To run
- the testsuite on the library after building and installing it,
- use "make check-install" instead.
- </p>
- <p>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,
- <strong>please</strong> write up your idea and send it to the list!
- </p>
-
-<hr />
- <h2><a name="2_5">2.4 This library is HUGE! And what's libsupc++?</a></h2>
- <p>Usually the size of libraries on disk isn't noticeable. When a
- link editor (or simply "linker") pulls things from a
- static archive library, only the necessary object files are copied
- into your executable, not the entire library. Unfortunately, even
- if you only need a single function or variable from an object file,
- the entire object file is extracted. (There's nothing unique to C++
- or libstdc++-v3 about this; it's just common behavior, given here
- for background reasons.)
- </p>
- <p>Some of the object files which make up libstdc++.a are rather large.
- If you create a statically-linked executable with
- <code> -static</code>, those large object files are suddenly part
- of your executable. Historically the best way around this was to
- only place a very few functions (often only a single one) in each
- source/object file; then extracting a single function is the same
- as extracting a single .o file. For libstdc++-v3 this is only
- possible to a certain extent; the object files in question contain
- template classes and template functions, pre-instantiated, and
- splitting those up causes severe maintenance headaches.
- </p>
- <p>It's not a bug, and it's not really a problem. Nevertheless, some
- people don't like it, so here are two pseudo-solutions:
- </p>
- <p>If the only functions from libstdc++.a which you need are language
- support functions (those listed in
- <a href="../18_support/howto.html">clause 18</a> of the standard,
- e.g., <code>new</code> and <code>delete</code>), then try linking
- against <code>libsupc++.a</code> (usually specifying
- <code>-lsupc++</code> when calling g++ for the final link step will
- do it). This library contains only those support routines, one per
- object file. But if you are using anything from the rest of the
- library, such as IOStreams or vectors, then you'll still need
- pieces from <code>libstdc++.a</code>.
- </p>
- <p>The second method is one we hope to incorporate into the library
- build process. Some platforms can place each function and variable
- into its own section in a .o file. The GNU linker can then perform
- garbage collection on unused sections; this reduces the situation
- to only copying needed functions into the executable, as before,
- but all happens automatically.
- </p>
- <p>Unfortunately the garbage collection in GNU ld is buggy; sections
- (corresponding to functions and variables) which <em>are</em> used
- are mistakenly removed, leading to horrible crashes when your
- executable starts up. For the time being, this feature is not used
- when building the library.
- </p>
-
-<hr />
-<h1><a name="3_0">3.0 Platform-Specific Issues</a></h1>
- <h2><a name="3_1">3.1 Can libstdc++-v3 be used with <my
- favorite compiler>?</a></h2>
- <p>Probably not. Yet.</p>
- <p>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
- <em>building</em> libstdc++ does not imply that your compiler
- will be able to <em>use</em> all of the features found in the
- C++ Standard Library.
- </p>
- <p>Since the goal of ISO Standardization is for all C++
- implementations to be able to share code, the final libstdc++
- should, in theory, be usable under any ISO-compliant
- compiler. It will still be targeted and optimized for
- GCC/g++, however.
- </p>
-
-<hr />
- <h2><a name="3_2">3.2 [removed]</a></h2>
- <p>This question has become moot and has been removed. The stub
- is here to preserve numbering (and hence links/bookmarks).
- </p>
-
-<hr />
- <h2><a name="3_3">3.3 [removed]</a></h2>
- <p>This question has become moot and has been removed. The stub
- is here to preserve numbering (and hence links/bookmarks).
- </p>
-
-<hr />
- <h2><a name="3_4">3.4 I can't use 'long long' on Solaris</a></h2>
- <p>By default we try to support the C99 <code>long long</code> type.
- This requires that certain functions from your C library be present.
- </p>
- <p>Up through release 3.0.2 the tests performed were too general, and
- this feature was disabled when it did not need to be. The most
- commonly reported platform affected was Solaris.
- </p>
- <p>This has been fixed for 3.0.3 and onwards.
- </p>
-
-<hr />
- <h2><a name="3_5">3.5 <code>_XOPEN_SOURCE</code> / <code>_GNU_SOURCE</code>
- / etc is always defined</a></h2>
- <p>On Solaris, g++ (but not gcc) always defines the preprocessor
- macro <code>_XOPEN_SOURCE</code>. On GNU/Linux, the same happens
- with <code>_GNU_SOURCE</code>. (This is not an exhaustive list;
- other macros and other platforms are also affected.)
- </p>
- <p>These macros are typically used in C library headers, guarding new
- versions of functions from their older versions. The C++ standard
- library includes the C standard library, but it requires the C90
- version, which for backwards-compatability reasons is often not the
- default for many vendors.
- </p>
- <p>More to the point, the C++ standard requires behavior which is only
- available on certain platforms after certain symbols are defined.
- Usually the issue involves I/O-related typedefs. In order to
- ensure correctness, the compiler simply predefines those symbols.
- </p>
- <p>Note that it's not enough to #define them only when the library is
- being built (during installation). Since we don't have an 'export'
- keyword, much of the library exists as headers, which means that
- the symbols must also be defined as your programs are parsed and
- compiled.
- </p>
- <p>To see which symbols are defined, look for CPLUSPLUS_CPP_SPEC in
- the gcc config headers for your target (and try changing them to
- see what happens when building complicated code). You can also run
- <code>"g++ -E -dM - < /dev/null"</code> to display
- a list of predefined macros for any particular installation.
- </p>
- <p>This has been discussed on the mailing lists
- <a href="http://gcc.gnu.org/cgi-bin/htsearch?method=and&format=builtin-long&sort=score&words=_XOPEN_SOURCE+Solaris">quite a bit</a>.
- </p>
- <p>This method is something of a wart. We'd like to find a cleaner
- solution, but nobody yet has contributed the time.
- </p>
-
-<hr />
- <h2><a name="3_6">3.6 OS X ctype.h is broken! How can I hack it?</a></h2>
- <p>This is a long-standing bug in the OS X support. Fortunately,
- the patch is quite simple, and well-known.
- <a href="http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html"> Here's a
- link to the solution.</a>
- </p>
-
-<hr />
- <h2><a name="3_7">Threading is broken on i386</a></h2>
- <p>Support for atomic integer operations is/was broken on i386
- platforms. The assembly code accidentally used opcodes that are
- only available on the i486 and later. So if you configured GCC
- to target, for example, i386-linux, but actually used the programs
- on an i686, then you would encounter no problems. Only when
- actually running the code on a i386 will the problem appear.
- </p>
- <p>This is fixed in 3.2.2.
- </p>
-
-<hr />
-<h1><a name="4_0">4.0 Known Bugs and Non-Bugs</a></h1>
- <em>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.</em>
-
- <p>For 3.0.1, the most common "bug" is an apparently missing
- "<code>../</code>" in include/Makefile, resulting in files
- like gthr.h and gthr-single.h not being found. Please read
- <a href="http://gcc.gnu.org/install/configure.html">the configuration
- instructions for GCC</a>,
- specifically the part about configuring in a separate build directory,
- and how strongly recommended it is. Building in the source directory
- is fragile, is rarely tested, and tends to break, as in this case.
- This was fixed for 3.0.2.
- </p>
-
- <p>For 3.1, the most common "bug" is a parse error when using
- <code><fstream></code>, ending with a message,
- "<code>bits/basic_file.h:52: parse error before `{'
- token</code>." Please read
- <a href="http://gcc.gnu.org/install/">the installation instructions for
- GCC</a>, specifically the part about not installing newer versions on
- top of older versions. If you install 3.1 over a 3.0.x release, then
- the wrong basic_file.h header will be found (its location changed
- between releases).
- </p>
-
- <p><strong>Please do not report these as bugs. We know about them.</strong>
- Reporting this -- or any other problem that's already been fixed --
- hinders the development of GCC, because we have to take time to
- respond to your report. Thank you.
- </p>
-
- <h2><a name="4_1">4.1 What works already?</a></h2>
- <p>This is a verbatim clip from the "Status" section
- of the RELEASE-NOTES for the latest snapshot. For a list of
- fixed bugs, see that file.
- </p>
-
-<!-- Yeah, I meant that "verbatim clip" thing literally... :-) -->
-
-<pre>
-New:
----
-(post 3.0.97)
-- more doxygen documentation
-- more named locale fixups
-- stdio_filebuf that takes fd, FILE
-- io performance tuning
-- allocation tuning, valgrind fixups
-- __cxa_demangle now supported
-(3.0.97)
-- more doxygen documentation.
-- more named locale bug fixes
-- support for symbol versioning when using GNU ld >= 2.12
-- wide-io
-- tuning for executable size
-(3.0.96)
-- more doxygen documentation.
-- extensions moved out of namespace std
-- HPUX long long support
-- more string optimizations
-- support for NetBSD cross compiles
-- concept_check merge from boost
-- header simplification
-- named locale bug shakeout
-- thread testsuite
-(3.0.95)
-- add S390, m68k, x86-64 support.
-- doxygen documentation has been extended, including man pages.
-- verbose terminate handling has been added.
-- some libsupc++ tweaks
-- warnings for deprecated headers now active.
-- dejagnu testsuite preliminary documentation.
-- dejagnu testsuite default.
-- dejagnu testsuite cross compiler, multilib safe.
-- long long iostreams on by default, rework of ISO C99 support.
-- iterator re-write and testsuites.
-- container testsuites.
-- allocator revamp and testsuites.
-- more concept-checking work.
-- basic_string optimization and MT fixes.
-- new limits implementation.
-- update -fno-exceptions code, verify it works.
-- full named locale support fpr all facets, choice of gnu,
- ieee_1003.1-200x (POSIX 2), or generic models. Full support depends
- on target OS and underlying "C" library support.
-</pre>
-
-
-<hr />
- <h2><a name="4_2">4.2 Bugs in gcc/g++ (not libstdc++-v3)</a></h2>
- <p>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.
- </p>
- <p>Before reporting a bug, examine the
- <a href="http://gcc.gnu.org/bugs.html">bugs database</a> with the
- category set to "libstdc++". The BUGS file in the source
- tree also tracks known serious problems.
- </p>
- <ul>
- <li>Debugging is problematic, due to bugs in line-number generation
- (mostly fixed in the compiler) and gdb lagging behind the
- compiler (lack of personnel). We recommend configuring the
- compiler using <code>--with-dwarf2</code> if the DWARF2
- debugging format is not already the default on your platform.
- Also,
-<a href="http://gcc.gnu.org/ml/libstdc++/2002-02/msg00034.html">changing your
- GDB settings</a> can have a profound effect on your C++ debugging
- experiences. :-)</li>
- </ul>
-
-<hr />
- <h2><a name="4_3">4.3 Bugs in the C++ language/lib specification</a></h2>
- <p>Yes, unfortunately, there are some. In a
- <a href="http://gcc.gnu.org/ml/libstdc++/1998/msg00006.html">message
- to the list</a>, 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
- <a href="http://www.cantrip.org/draft-bugs.txt">posted on his
- website</a>. Developers who are having problems interpreting
- the Standard may wish to consult his notes.
- </p>
- <p>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 <a href="http://anubis.dkuug.dk/jtc1/sc22/wg21/">here</a>.
- Some of these have resulted in <a href="#5_2">code changes</a>.
- </p>
-
-<hr />
- <h2><a name="4_4">4.4 Things in libstdc++ that only look like bugs</a></h2>
- <p>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! Please do not report these as bugs.
- </p>
- <p><a name="4_4_Weff"><strong>-Weffc++</strong></a>
- The biggest of these is the quadzillions of warnings about the
- library headers emitted when <code>-Weffc++</code> 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.
- </p>
- <p><a name="4_4_iostreamclear"><strong>reopening a stream fails</strong>
- </a> Did I just say that -Weffc++ was our biggest false-bug report?
- I lied. (It used to be.) Today it seems to be reports that after
- executing a sequence like
- </p>
- <pre>
- #include <fstream>
- ...
- std::fstream fs("a_file");
- // .
- // . do things with fs...
- // .
- fs.close();
- fs.open("a_new_file");</pre>
- <p>all operations on the re-opened <code>fs</code> will fail, or at
- least act very strangely. Yes, they often will, especially if
- <code>fs</code> reached the EOF state on the previous file. The
- reason is that the state flags are <strong>not</strong> cleared
- on a successful call to open(). The standard unfortunately did
- not specify behavior in this case, and to everybody's great sorrow,
- the <a href="../ext/howto.html#5">proposed LWG resolution</a> (see
- DR #22) is to leave the flags unchanged. You must insert a call
- to <code>fs.clear()</code> between the calls to close() and open(),
- and then everything will work like we all expect it to work.
- </p>
- <p><a name="4_4_rel_ops"><strong>rel_ops</strong></a>
- Another is the <code>rel_ops</code> namespace and the template
- comparison operator functions contained therein. If they become
- visible in the same namespace as other comparison functions
- (e.g., '<code>using</code>' them and the <iterator> header),
- then you will suddenly be faced with huge numbers of ambiguity
- errors. This was discussed on the -v3 list; Nathan Myers
- <a href="http://gcc.gnu.org/ml/libstdc++/2001-01/msg00247.html">sums
- things up here</a>. The collisions with vector/string iterator
- types have been fixed for 3.1. <!-- more links to email here -->
- </p>
- <h3><a name="4_4_interface">The g++-3 headers are <em>not ours</em></a></h3>
- <p>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
- <a href="http://gcc.gnu.org/gnatswrite.html">the GCC bug database</a>).
- </p>
- <p>If the headers are in <code>${prefix}/include/g++-3</code>, or if
- the installed library's name looks like <code>libstdc++-2.10.a</code>
- or <code>libstdc++-libc6-2.10.so</code>,
- 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.
- </p>
- <p>Currently our header files are installed in
- <code>${prefix}/include/g++-v3</code> (see the 'v'?). This may
- change with the next release of GCC, as it may be too confusing,
- but <a href="http://gcc.gnu.org/ml/gcc/2000-10/msg00732.html">the
- question has not yet been decided</a>.
- </p>
- <p><a name="4_4_glibc"><strong>glibc</strong></a>
- If you're on a GNU/Linux system and have just upgraded to
- glibc 2.2, but are still using gcc 2.95.2, then you should have
- read the glibc FAQ, specifically 2.34:
- </p>
- <pre>
-2.34. When compiling C++ programs, I get a compilation error in streambuf.h.
-
-{BH} You are using g++ 2.95.2? After upgrading to glibc 2.2, you need to
-apply a patch to the include files in /usr/include/g++, because the fpos_t
-type has changed in glibc 2.2. The patch is at
-http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff
- </pre>
- <p>Note that 2.95.x shipped with the
- <a href="#4_4_interface">old v2 library</a> which is no longer
- maintained. Also note that gcc 2.95.3 fixes this problem, but
- requires a separate patch for libstdc++-v3.
- </p>
- <p><a name="4_4_checks"><strong>concept checks</strong></a>
- If you see compilation errors containing messages about
- <code> <em>foo</em>Concept </code>and a<code> constraints </code>
- member function, then most likely you have violated one of the
- requirements for types used during instantiation of template
- containers and functions. For example, EqualityComparableConcept
- appears if your types must be comparable with == and you have not
- provided this capability (a typo, or wrong visibility, or you
- just plain forgot, etc).
- </p>
- <p>More information, including how to optionally enable/disable the
- checks, is available
- <a href="../19_diagnostics/howto.html#3">here</a>.
- </p>
- <p><a name="4_4_dlsym"><strong>dlopen/dlsym</strong></a>
- If you are using the C++ library across dynamically-loaded
- objects, make certain that you are passing the correct options
- when compiling and linking:
- </p>
- <pre>
- // compile the library components
- g++ -fPIC -c a.cc
- g++ -fPIC -c b.cc
- ...
- g++ -fPIC -c z.cc
-
- // create the library
- g++ -fPIC -shared -rdynamic -o libfoo.so a.o b.o ... z.o
-
- // link the executable
- g++ -fPIC -rdynamic -o foo ... -L. -lfoo -ldl</pre>
-
-<hr />
- <h2><a name="4_5">4.5 Aw, that's easy to fix!</a></h2>
- <p>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 <a href="http://gcc.gnu.org/contribute.html">submitting
- patches</a> that covers the procedure, but for libstdc++ you
- should also send the patch to our mailing list in addition to
- the GCC patches mailing list. The libstdc++
- <a href="../17_intro/contribute.html">contributors' page</a>
- also talks about how to submit patches.
- </p>
- <p>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
- <a href="#2_4">testsuite</a> -- but only if such a test exists.
- </p>
-
-<hr />
-<h1><a name="5_0">5.0 Miscellaneous</a></h1>
- <h2><a name="5_1">5.1 string::iterator is not char*;
- vector<T>::iterator is not T*</a></h2>
- <p>If you have code that depends on container<T> iterators
- being implemented as pointer-to-T, your code is broken.
- </p>
- <p>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 <code>T*</code> outweighs nearly all opposing
- arguments.
- </p>
- <p>Code which does assume that a vector iterator <code> i </code>
- is a pointer can often be fixed by changing <code> i </code> in
- certain expressions to <code> &*i </code>. Future revisions
- of the Standard are expected to bless this usage for
- vector<> (but not for basic_string<>).
- </p>
-
-<hr />
- <h2><a name="5_2">5.2 What's next after libstdc++-v3?</a></h2>
- <p>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 <em>be</em> any more compliance
- work to do. However:
- </p>
- <ol>
- <li><p>The ISO Committee will meet periodically to review Defect Reports
- in the C++ Standard. Undoubtedly 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. Those additions are listed in
- <a href="../ext/howto.html#5">the extensions page</a>.
- </p></li>
- <li><p>Performance tuning. Lots of performance tuning. This too is
- already underway for post-3.0 releases, starting with memory
- expansion in container classes and buffer usage in synchronized
- stream objects.
- </p></li>
- <li><p>An ABI for libstdc++ is being developed, so that
- multiple binary-incompatible copies of the library can be replaced
- with a single backwards-compatible library, like libgcc_s.so is.
- </p></li>
- <li><p>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.
- </p></li>
- </ol>
- <p><a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00080.html">This
- question</a> about the next libstdc++ prompted some brief but
- interesting
- <a href="http://gcc.gnu.org/ml/libstdc++/1999/msg00084.html">speculation</a>.
- </p>
-
-<hr />
- <h2><a name="5_3">5.3 What about the STL from SGI?</a></h2>
- <p>The <a href="http://www.sgi.com/Technology/STL/">STL from SGI</a>,
- version 3.3, was the most recent merge of the STL codebase. The
- code in libstdc++ contains many fixes and changes, and it is
- very likely that the SGI code is no longer under active
- development. We expect that no future merges will take place.
- </p>
- <p>In particular, <code>string</code> is not from SGI and makes no
- use of their "rope" class (which is included as an
- optional extension), nor is <code>valarray</code> and some others.
- Classes like <code>vector<></code> are, however.
- </p>
- <p>The FAQ for SGI's STL (one jump off of their main page) is
- recommended reading.
- </p>
-
-<hr />
- <h2><a name="5_4">5.4 Extensions and Backward Compatibility</a></h2>
- <p>Headers in the <code>ext</code> and <code>backward</code>
- subdirectories should be referred to by their relative paths:
- <!-- Careful, the leading spaces in PRE show up directly. -->
- </p>
- <pre>
- #include <ext/hash_map> </pre>
- <p>rather than using <code>-I</code> or other options. This is more
- portable and forward-compatible. (The situation is the same as
- that of other headers whose directories are not searched directly,
- e.g., <code><sys/stat.h></code>, <code><X11/Xlib.h></code>.
- </p>
-
- <p>The extensions are no longer in the global or <code>std</code>
- namespaces, instead they are declared in the <code>__gnu_cxx</code>
- namespace. For maximum portability, consider defining a namespace
- alias to use to talk about extensions, e.g.:
- </p>
- <pre>
- #ifdef __GNUC__
- #if __GNUC__ < 3
- #include <hash_map.h>
- namespace Sgi { using ::hash_map; }; // inherit globals
- #else
- #include <ext/hash_map>
- #if __GNUC_MINOR__ == 0
- namespace Sgi = std; // GCC 3.0
- #else
- namespace Sgi = ::__gnu_cxx; // GCC 3.1 and later
- #endif
- #endif
- #else // ... there are other compilers, right?
- namespace Sgi = std;
- #endif
-
- Sgi::hash_map<int,int> my_map; </pre>
- <p>This is a bit cleaner than defining typedefs for all the
- instantiations you might need.
- </p>
-
- <p>Extensions to the library have
- <a href="../ext/howto.html">their own page</a>.
- </p>
-
-<hr />
- <h2><a name="5_5">5.5 [removed]</a></h2>
- <p>This question has become moot and has been removed. The stub
- is here to preserve numbering (and hence links/bookmarks).
- </p>
-
-<hr />
- <h2><a name="5_6">5.6 Is libstdc++-v3 thread-safe?</a></h2>
- <p>When the system's libc is itself thread-safe, a non-generic
- implementation of atomicity.h exists for the architecture, and gcc
- itself reports a thread model other than single; libstdc++-v3
- strives to be thread-safe. The user-code must guard against
- concurrent method calls which may access any particular library
- object's state. Typically, the application programmer may infer
- what object locks must be held based on the objects referenced in
- a method call. Without getting into great detail, here is an
- example which requires user-level locks:
- </p>
- <pre>
- library_class_a shared_object_a;
-
- thread_main () {
- library_class_b *object_b = new library_class_b;
- shared_object_a.add_b (object_b); // must hold lock for shared_object_a
- shared_object_a.mutate (); // must hold lock for shared_object_a
- }
-
- // Multiple copies of thread_main() are started in independent threads.</pre>
- <p>Under the assumption that object_a and object_b are never exposed to
- another thread, here is an example that should not require any
- user-level locks:
- </p>
- <pre>
- thread_main () {
- library_class_a object_a;
- library_class_b *object_b = new library_class_b;
- object_a.add_b (object_b);
- object_a.mutate ();
- } </pre>
- <p>All library objects are safe to use in a multithreaded program as
- long as each thread carefully locks out access by any other thread
- while it uses any object visible to another thread. In general,
- this requirement includes both read and write access to objects;
- unless otherwise documented as safe, do not assume that two
- threads may access a shared standard library object at the
- same time.
- </p>
- <p>See chapters <a href="../17_intro/howto.html#3">17</a> (library
- introduction), <a href="../23_containers/howto.html#3">23</a>
- (containers), and <a href="../27_io/howto.html#9">27</a> (I/O) for
- more information.
- </p>
-
-<hr />
- <h2><a name="5_7">5.7 How do I get a copy of the ISO C++ Standard?</a></h2>
- <p>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 <a href="http://www.ansi.org">here</a>.
- (And if you've already registered with them, clicking this link will
- take you to directly to the place where you can
-<a href="http://webstore.ansi.org/ansidocstore/product.asp?sku=ISO%2FIEC+14882%2D1998">buy
- the standard on-line</a>.
- </p>
- <p>Who is your country's member body? Visit the
- <a href="http://www.iso.ch/">ISO homepage</a> and find out!
- </p>
-
-<hr />
- <h2><a name="5_8">5.8 What's an ABI and why is it so messy?</a></h2>
- <p>"ABI" stands for "Application Binary Interface."
- Conventionally, it refers to a great mass of details about how
- arguments are arranged on the call stack and/or in registers, and
- how various types are arranged and padded in structs. A single CPU
- design may suffer multiple ABIs designed by different development
- tool vendors who made different choices, or even by the same vendor
- for different target applications or compiler versions. In ideal
- circumstances the CPU designer presents one ABI and all the OSes and
- compilers use it. In practice every ABI omits details that compiler
- implementers (consciously or accidentally) must choose for themselves.
- </p>
- <p>That ABI definition suffices for compilers to generate code so a
- program can interact safely with an OS and its lowest-level libraries.
- Users usually want an ABI to encompass more detail, allowing libraries
- built with different compilers (or different releases of the same
- compiler!) to be linked together. For C++, this includes many more
- details than for C, and CPU designers (for good reasons elaborated
- below) have not stepped up to publish C++ ABIs. The details include
- virtual function implementation, struct inheritance layout, name
- mangling, and exception handling. Such an ABI has been defined for
- GNU C++, and is immediately useful for embedded work relying only on
- a "free-standing implementation" that doesn't include (much
- of) the standard library. It is a good basis for the work to come.
- </p>
- <p>A useful C++ ABI must also incorporate many details of the standard
- library implementation. For a C ABI, the layouts of a few structs
- (such as FILE, stat, jmpbuf, and the like) and a few macros suffice.
- For C++, the details include the complete set of names of functions
- and types used, the offsets of class members and virtual functions,
- and the actual definitions of all inlines. C++ exposes many more
- library details to the caller than C does. It makes defining
- a complete ABI a much bigger undertaking, and requires not just
- documenting library implementation details, but carefully designing
- those details so that future bug fixes and optimizations don't
- force breaking the ABI.
- </p>
- <p>There are ways to help isolate library implementation details from the
- ABI, but they trade off against speed. Library details used in
- inner loops (e.g., getchar) must be exposed and frozen for all
- time, but many others may reasonably be kept hidden from user code,
- so they may later be changed. Deciding which, and implementing
- the decisions, must happen before you can reasonably document a
- candidate C++ ABI that encompasses the standard library.
- </p>
-
-<!-- ####################################################### -->
-
-<hr />
-<p class="fineprint"><em>
-See <a href="../17_intro/license.html">license.html</a> for copying conditions.
-Comments and suggestions are welcome, and may be sent to
-<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
-</em></p>
-
-
-</body>
-</html>
-
projects / msp430-gcc.git / blobdiff