Subversion Repositories openrisc

 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"

[ ]>

      2008

      FSF

      What is libstdc++?

     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.  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 SVN, and can even be browsed over

     the web.

      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 compiler collection

    (gcc, g++, etc) is widely

    considered to be one of the leading compilers in the world.  Its

    development is overseen by the

    GCC 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 will be

    freely available and fully compliant. (Such as

    string,

    vector<>, iostreams, and algorithms.)

    Programmers will no longer need to roll their own

    nor be worried about platform-specific incompatibilities.

      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, Ulrich Drepper,

     Loren James Rittle, and Paolo Carlini are the lead maintainers of

     the SVN 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!

      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.

      How do I contribute to the effort?

    Here is 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 and is

    willing to provide details, is more than welcome!

      What happened to the older 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.

    More information in the backwards compatibility documentation

      What if I have more questions?

    If you have read the README file, 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 a message to the list,

    use 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, please send email to the libstdc++ mailing list, as above.

      What are the license terms for libstdc++?

    See our license description

    for these and related questions.

      So any program which uses libstdc++ falls under the GPL?

     No. The special exception permits use of the library in

     proprietary applications.

      How is that different from the GNU {Lesser,Library} GPL?

      The LGPL requires that users be able to replace the LGPL code with a

     modified version; this is trivial if the library in question is a C

     shared library.  But there's no way to make that work with C++, where

     much of the library consists of inline functions and templates, which

     are expanded inside the code that uses the library.  So to allow people

     to replace the library code, someone using the library would have to

     distribute their own source, rendering the LGPL equivalent to the GPL.

      I see. So, what restrictions are there on programs that use the library?

      None.  We encourage such programs to be released as open source,

     but we won't punish you or sue you if you choose otherwise.

    How do I install libstdc++?

    Often libstdc++ comes pre-installed as an integral part of many

    existing Linux and Unix systems, as well as many embedded

    development tools. It may be necessary to install extra

    development packages to get the headers, or the documentation, or

    the source: please consult your vendor for details.

    To build and install from the GNU GCC sources, please consult the

    setup

    documentation for detailed

    instructions. You may wish to browse those files ahead

    of time to get a feel for what's required.

    How does one get current libstdc++ sources?

    Libstdc++ sources for all official releases can be obtained as

    part of the GCC sources, available from various sites and

    mirrors. A full list of

    download sites is provided on the main GCC site.

    Current libstdc++ sources can always be checked out of the main

    GCC source repository using the appropriate version control

    tool. At this time, that tool

    is Subversion.

    Subversion, or SVN, 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  Subversion

    home page has a better description.

    The anonymous client checkout feature of SVN is

    similar to anonymous FTP in that it allows anyone to retrieve

    the latest libstdc++ sources.

    For more information

    see SVN

    details.

    How do I know if it works?

    Libstdc++ comes with its own validation testsuite, which includes

    conformance testing, regression testing, ABI testing, and

    performance testing. Please consult the

    testing

    documentation for more details.

    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!

    How do I insure that the dynamically linked library will be found?

    Depending on your platform and library version, the error message might

    be similar to one of the following:

    ./a.out: error while loading shared libraries: libstdc++.so.6: cannot open shared object file: No such file or directory

    /usr/libexec/ld-elf.so.1: Shared object "libstdc++.so.6" not found

    This doesn't mean that the shared library isn't installed, only

    that the dynamic linker can't find it. When a dynamically-linked

    executable is run the linker finds and loads the required shared

    libraries by searching a pre-configured list of directories. If

    the directory where you've installed libstdc++ is not in this list

    then the libraries won't be found. The simplest way to fix this is

    to use the LD_LIBRARY_PATH environment variable,

    which is a colon-separated list of directories in which the linker

    will search for shared libraries:

    LD_LIBRARY_PATH=${prefix}/lib:$LD_LIBRARY_PATH

    export LD_LIBRARY_PATH

    The exact environment variable to use will depend on your

    platform, e.g. DYLD_LIBRARY_PATH for Darwin,

    LD_LIBRARY_PATH_32/LD_LIBRARY_PATH_64 for Solaris 32-/64-bit,

    LD_LIBRARYN32_PATH/LD_LIBRARY64_PATH for Irix N32/64-bit ABIs and

    SHLIB_PATH for HP-UX.

    See the man pages for ld, ldd

    and ldconfig for more information. The dynamic

    linker has different names on different platforms but the man page

    is usually called something such as ld.so/rtld/dld.so.

      What's libsupc++?

      If the only functions from libstdc++.a

      which you need are language support functions (those listed in

      clause 18 of the

      standard, e.g., new and

      delete), then try linking against

      libsupc++.a, which is a subset of

      libstdc++.a.  (Using gcc

      instead of g++ and explicitly linking in

      libsupc++.a via -lsupc++

      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

      libstdc++.a.

      This library is HUGE!

    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++ about this; it's just common behavior, given here

    for background reasons.)

    Some of the object files which make up libstdc++.a are rather large.

    If you create a statically-linked executable with

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

    On supported platforms, libstdc++ takes advantage of garbage

    collection in the GNU linker to get a result similar to separating

    each symbol into a separate source and object files. On these platforms,

    GNU ld 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.

      Can libstdc++ be used with non-GNU compilers?

    Perhaps.

    Since the goal of ISO Standardization is for all C++

    implementations to be able to share code, libstdc++ should be

    usable under any ISO-compliant compiler, at least in theory.

    However, the reality is that libstdc++ is targeted and optimized

    for GCC/g++. This means that often libstdc++ uses specific,

    non-standard features of g++ that are not present in older

    versions of proprietary compilers. It may take as much as a year or two

    after an official release of GCC that contains these features for

    proprietary tools support these constructs.

    In the near past, specific released versions of libstdc++ have

    been known to work with versions of the EDG C++ compiler, and

    vendor-specific proprietary C++ compilers such as the Intel ICC

    C++ compiler.

      No 'long long' type on Solaris?

    By default we try to support the C99 long long type.

    This requires that certain functions from your C library be present.

    Up through release 3.0.2 the platform-specific tests performed by

    libstdc++ were too general, resulting in a conservative approach

    to enabling the long long code paths. The most

    commonly reported platform affected was Solaris.

    This has been fixed for libstdc++ releases greater than 3.0.3.

      _XOPEN_SOURCE and _GNU_SOURCE are always defined?

      On Solaris, g++ (but not gcc) always defines the preprocessor

         macro _XOPEN_SOURCE.  On GNU/Linux, the same happens

         with _GNU_SOURCE.  (This is not an exhaustive list;

         other macros and other platforms are also affected.)

      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-compatibility reasons is often not the

         default for many vendors.

      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.

      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.

      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

         g++ -E -dM - < /dev/null" to display

         a list of predefined macros for any particular installation.

      This has been discussed on the mailing lists

         quite a bit.

      This method is something of a wart.  We'd like to find a cleaner

         solution, but nobody yet has contributed the time.

      Mac OS X ctype.h is broken! How can I fix it?

      This is a long-standing bug in the OS X support.  Fortunately,

         the patch is quite simple, and well-known.

          Here's a

         link to the solution.

      Threading is broken on i386?

      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.

      This is fixed in 3.2.2.

      MIPS atomic operations

    The atomic locking routines for MIPS targets requires MIPS II

    and later.  A patch went in just after the 3.3 release to

    make mips* use the generic implementation instead.  You can also

    configure for mipsel-elf as a workaround.

    The mips*-*-linux* port continues to use the MIPS II routines, and more

    work in this area is expected.

      Recent GNU/Linux glibc required?

      When running on GNU/Linux, libstdc++ 3.2.1 (shared library version

         5.0.1) and later uses localization and formatting code from the system

         C library (glibc) version 2.2.5.  That version of glibc is over a

         year old and contains necessary bugfixes.  Many GNU/Linux distros make

         glibc version 2.3.x available now.

      The guideline is simple:  the more recent the C++ library, the

         more recent the C library.  (This is also documented in the main

         GCC installation instructions.)

      Can't use wchar_t/wstring on FreeBSD

    Older versions of FreeBSD's C library do not have sufficient

    support for wide character functions, and as a result the

    libstdc++ configury decides that wchar_t support should be

    disabled. In addition, the libstdc++ platform checks that

    enabled wchar_t were quite strict, and not granular

    enough to detect when the minimal support to

    enable wchar_t and C++ library structures

    like wstring were present. This impacted Solaris,

    Darwin, and BSD variants, and is fixed in libstdc++ versions post 4.1.0.

      What works already?

    Short answer: Pretty much everything works

    except for some corner cases.  Support for localization

    in locale may be incomplete on non-GNU

    platforms. Also dependant on the underlying platform is support

    for wchar_t and long

    long specializations, and details of thread support.

    Long answer: See the implementation status pages for

    C++98,

    TR1, and

    C++0x.

      Bugs in the ISO C++ language or library specification

    Unfortunately, there are some.

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

    Some of these issues have resulted in code changes in libstdc++.

    If you think you've discovered a new bug that is not listed,

    please post a message describing your problem

    to libstdc++@gcc.gnu.org or the Usenet group

    comp.lang.c++.moderated.

      Bugs in the compiler (gcc/g++) and not libstdc++

    On occasion, the compiler is wrong. Please be advised that this

    happens much less often than one would think, and avoid jumping to

    conclusions.

    First, examine the ISO C++ standard. Second, try another compiler

    or an older version of the GNU compilers. Third, you can find more

    information on the libstdc++ and the GCC mailing lists: search

    these lists with terms describing your issue.

    Before reporting a bug, please examine the

    bugs database with the

    category set to g++.

      Reopening a stream fails

    One of the most-reported non-bug reports. Executing a sequence like:

    #include <fstream>

    ...

    std::fstream  fs(a_file);

    // .

    // . do things with fs...

    // .

    fs.close();

    fs.open(a_new_file);

    All operations on the re-opened fs will fail, or at

    least act very strangely.  Yes, they often will, especially if

    fs reached the EOF state on the previous file.  The

    reason is that the state flags are not cleared

    on a successful call to open().  The standard unfortunately did

    not specify behavior in this case, and to everybody's great sorrow,

    the proposed LWG resolution in

      DR #22 is to leave the flags unchanged.  You must insert a call

    to fs.clear() between the calls to close() and open(),

    and then everything will work like we all expect it to work.

    Update: for GCC 4.0 we implemented the resolution

    of DR #409 and open()

    now calls clear() on success!

      -Weffc++ complains too much

    Many warnings are 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.

    We do, however, try to have libstdc++ sources as clean as possible. If

    you see some simple changes that pacify -Weffc++

    without other drawbacks, send us a patch.

      Ambiguous overloads after including an old-style header

    Another problem is the rel_ops namespace and the template

    comparison operator functions contained therein.  If they become

    visible in the same namespace as other comparison functions

    (e.g., using 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

    sums

      things up here.  The collisions with vector/string iterator

    types have been fixed for 3.1.

      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 the GCC

        bug database).

        If the headers are in ${prefix}/include/g++-3, or

        if the installed library's name looks like

        libstdc++-2.10.a or

        libstdc++-libc6-2.10.so, 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.

        For GCC versions 3.0 and 3.1 the libstdc++ header files are

        installed in ${prefix}/include/g++-v3 (see the

        'v'?).  Starting with version 3.2 the headers are installed in

        ${prefix}/include/c++/${version} as this prevents

        headers from previous versions being found by mistake.

      Errors about *Concept and

      constraints in the STL

    If you see compilation errors containing messages about

    foo Concept and something to do with a

    constraints 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