FAQ for g++ and libg++, by Joe Buck (jbuck@synopsys.com)
********************************************************

This is a list of frequently asked questions (FAQ) for g++ users; thanks to all those who sent suggestions for improvements.  Thanks to Marcus Speh for doing the index.  A hypertext version is available on the World Wide Web at http://www.cygnus.com/misc/g++FAQ_toc.html.

News flash: gcc 2.8.0 has finally been released! This FAQ still has much material that refers to older releases; it will take some time before it is completely "modernized".

Please send updates and corrections to the FAQ to jbuck@synopsys.com.  Please do not use me as a resource to get your questions answered; that's what gnu.g++.help is for and I don't have the time to support the net's use of g++.  If you ignore this request your message to me may be deleted without a reply.  Sorry.

Many FAQs, including this one, are available on the archive site ``rtfm.mit.edu''; see

ftp://rtfm.mit.edu/pub/usenet/news.answers. This FAQ may be found in the subdirectory g++-FAQ.

This FAQ is intended to supplement, not replace, Marshall Cline's excellent FAQ for the C++ language and for the newsgroup comp.lang.c++.  Especially if g++ is the first C++ compiler you've ever used, the question ``How do I do <X> with g++?'' is probably really ``How do I do <X> in C++?''. You can find this FAQ at ftp://rtfm.mit.edu/pub/usenet/comp.lang.c++, or in HTML form at http://www.cerfnet.com/~mpcline/On-Line-C++-FAQs/.

The basics: what is g++?
************************

g++ is the traditional nickname of GNU C++, a freely redistributable C++ compiler produced by the Free Software Foundation plus dozens of skilled volunteers.  I say ``traditional nickname'' because the GNU compiler suite, gcc, bundles together compilers for C, Objective-C, and C++ in one package.

While the source code to gcc/g++ can be downloaded for free, it is not public domain, but is protected by the GNU Public License, or GPL (see legalities).

What is the latest version of gcc, g++, and libg++?
===================================================

The egcs project (on the Web: http://www.cygnus.com/egcs/) has released a bug-fix version, egcs-1.0.1, on January 6, 1998.  Folks using egcs-1.0 should upgrade, as it has some important bug fixes.

The current version of gcc/g++ is 2.8.0 (!), released January 14, 1998. It is a huge improvement over the 2.7.x releases, and thanks to extensive testing in the egcs framework, is perhaps the least buggy .0 gcc release anyone can remember (though there are definitely a few).

The current version of libg++ is 2.8.0, released January 19, 1998. However, libg++ is being deprecated; libstdc++-2.8.0 contains just the standard C++ classes and is a subset of libg++ 2.8.0.  The libstdc++ library is identical to the one included in egcs-1.0.1.

I would strongly recommend that anyone using a g++ version earlier than 2.7.2 should upgrade if at all possible (see version 2.7.x). Folks who need modern C++ features should upgrade to 2.8.0 or egcs.

For some non-Unix platforms, the latest port of gcc may be an earlier version (2.6.3, say).  You'll need to use a version of libg++ that has the same first two digits as the compiler version, e.g. use libg++ 2.6.x (for the latest x you can find) with gcc version 2.6.3.

The latest "1.x" version of gcc is 1.42, and the latest "1.x" version of g++ is 1.42.0. While gcc 1.42 is quite usable for C programs, I recommend against using g++ 1.x except in special circumstances (and I can't think of any such circumstances).

How do I get a copy of g++ for Unix?
====================================

First, you may already have it if you have gcc for your platform; g++ and gcc are combined now (as of gcc version 2.0).

You can get g++ from a friend who has a copy, by anonymous FTP or UUCP, or by ordering a tape or CD-ROM from the Free Software Foundation.

The Free Software Foundation is a nonprofit organization that distributes software and manuals to raise funds for more GNU development.  Getting your copy from the FSF contributes directly to paying staff to develop GNU software.  CD-ROMs cost $400 if an organization is buying, or $100 if an individual is buying.  Tapes cost around $200 depending on media type.  I recommend asking for version 2, not version 1, of g++.

For more information about ordering from the FSF, contact gnu@prep.ai.mit.edu, phone (617) 542-5942 or anonymous ftp file ftp://prep.ai.mit.edu/pub/gnu/GNUinfo/ORDERS (you can also use one of the sites listed below if you can't get into ``prep'').

Here is a list of anonymous FTP archive sites for GNU software. If no directory is given, look in /pub/gnu.

     ASIA: ftp.cs.titech.ac.jp, tron.um.u-tokyo.ac.jp:/pub/GNU/prep
     cair-archive.kaist.ac.kr, ftp.nectec.or.th:/pub/mirrors/gnu

     AUSTRALIA: archie.au:/gnu (archie.oz or archie.oz.au for ACSnet)

     AFRICA: ftp.sun.ac.za

     MIDDLE-EAST: ftp.technion.ac.il:/pub/unsupported/gnu

     EUROPE: irisa.irisa.fr, ftp.univ-lyon1.fr,
     ftp.mcc.ac.uk, unix.hensa.ac.uk:/mirrors/uunet/systems/gnu,
     src.doc.ic.ac.uk:/gnu, ftp.ieunet.ie, ftp.eunet.ch,
     nic.switch.ch:/mirror/gnu, ftp.informatik.rwth-aachen.de,
     ftp.informatik.tu-muenchen.de, ftp.win.tue.nl, ftp.nl.net,
     ftp.etsimo.uniovi.es, ftp.funet.fi, ftp.denet.dk,
     ftp.stacken.kth.se, isy.liu.se, ftp.luth.se:/pub/unix/gnu,
     ftp.sunet.se, archive.eu.net

     SOUTH AMERICA: ftp.inf.utfsm.cl, ftp.unicamp.br

     WESTERN CANADA: ftp.cs.ubc.ca:/mirror2/gnu

     USA: wuarchive.wustl.edu:/systems/gnu, labrea.stanford.edu,
     ftp.digex.net, ftp.kpc.com:/pub/mirror/gnu, f.ms.uky.edu:/pub3/gnu,
     jaguar.utah.edu:/gnustuff, ftp.hawaii.edu:/mirrors/gnu,
     uiarchive.cso.uiuc.edu, ftp.cs.columbia.edu:/archives/gnu/prep,
     gatekeeper.dec.com:/pub/GNU, ftp.uu.net:/systems/gnu

The ``official site'' is prep.ai.mit.edu, but your transfer will probably go faster if you use one of the above machines.

Most GNU utilities are compressed with ``gzip'', the GNU compression utility.  All GNU archive sites should have a copy of this program, which you will need to uncompress the distributions.

Don't forget to retrieve libg++ as well!

Getting gcc/g++ for the HP Precision Architecture
=================================================

If you use the HP Precision Architecture (HP-9000/7xx and HP-9000/8xx) and you want to use debugging, you'll need to use the GNU assembler, GAS (version 2.3 or later).  If you build from source, you must tell the configure program that you are using GAS or you won't get debugging support.  A non-standard debug format is used, since until recently HP considered their debug format a trade secret.  Thanks to the work of lots of good folks both inside and outside HP, the company has seen the error of its ways and has now released the required information.  The team at the University of Utah that did the gcc port now has code that understands the native HP format.

There are binaries for GNU tools in ftp://jaguar.cs.utah.edu/dist/, but these are older versions.

Jeff Law has left the University of Utah, so the Utah prebuilt binaries may be discontinued.

Getting gcc/g++ binaries for Solaris 2.x
========================================

``Sun took the C compiler out of Solaris 2.x.  Am I stuck?''

You'll need to get prebuilt binaries from someone.

It used to be that you could get GCC binaries from prep.ai.mit.edu; these are no longer there.

The WWW site http://smc.vnet.net/solaris_2.5.html contains various GNU and freeware programs for Solaris2.5 running on the sparc. These are packaged to enable easy installation using the Solaris ``pkgadd'' utility. These include GNU emacs, gcc, gdb, perl, and others.  These versions are more recent than the binaries at ``prep'' (gcc 2.7.2 and libg++ 2.7.1 are there).

How do I get a copy of g++ for (some other platform)?
=====================================================

As of gcc-2.7.x, there is Windows NT support in gcc.  Some special utilities are required.  See the INSTALL file from the distribution. If you're interested in GNU tools on Windows NT, see http://www.cygnus.com/misc/gnu-win32/ on the WWW, or the anonymous FTP directory ftp://ftp.cygnus.com/pub/gnu-win32/.

The standard gcc/g++ distribution includes VMS support for the Vax. Since the FSF people don't use VMS, it's likely to be somewhat less solid than the Unix version.  Precompiled copies of g++ and libg++ in VMS-installable form for the Vax are available by FTP from ftp://mango.rsmas.miami.edu/pub/VMS-gcc/.

Klaus Kaempf (kkaempf@progis.de) has done a port to OpenVMS for the Alpha; this is not yet a part of the official gcc/g++. The port includes g++ and all libraries from the libg++ distribution.  See http://www.progis.de for more details.

There are two different versions of gcc/g++ for MS-DOS: EMX and DJGPP. EMX also works for OS/2 and is described later. DJGPP is DJ Delorie's port.  It can be found on many FTP archive sites; try ftp://ftp.coast.net/SimTel/vendors/djgpp/ or, for a complete list, see http://www.delorie.com/djgpp/getting.html.

The latest version of DJGPP is 2.00.  See http://www.delorie.com/djgpp/v2/ for information on this version.

FSF sells floppies with DJGPP on them; see above for ordering software from the FSF.

DJGPP has its own newsgroup: comp.os.msdos.djgpp.

Development and porting efforts for GNU tools, including gcc/g++, for the Amiga are maintained by an initiative named ADE (Amiga Developers Environment.  More information about ADE is available at http://www.ninemoons.com/.

For more information on Amiga ports of gcc/g++, retrieve the file ftp://prep.ai.mit.edu/pub/gnu/MicrosPorts/Amiga.

A port of gcc to the Atari ST can be found at

ftp://atari.archive.umich.edu/atari/Gnustuff/Tos along with many other GNU programs.  This version is usually the same as the latest FSF release.  See the ``Software FAQ'' for the Usenet group comp.sys.atari.st for more information.

EMX is a port of gcc to OS/2; it can also be used on MS-DOS.  In addition to the compiler port, the EMX port's C library attempts to provide a Unix-like environment.  For more information ask around on comp.os.os2.programmer.porting.  Version 0.9c, based on gcc-2.7.2.1, was released in November 1996.  It is available by FTP and the WWW from, among other places

     http://www.os2ss.com/unix/emx09c/
     ftp://ftp.cdrom.com/pub/os2/emx09c/ (US)
     ftp://ftp.leo.org/pub/comp/os/os2/leo/devtools/emx+gcc/ (Germany)

Eberhard Mattes did the EMX port.  His address is mattes@azu.informatik.uni-stuttgart.de. Read the FAQ file included with the distribution before harrassing the author.

I'm looking for more information on gcc/g++ support on the Apple Macintosh.  Until recently, this FAQ did not provide such information, but FSF is no longer boycotting Apple as the League for Programming Freedom boycott has been dropped.

Versions 1.37.1 and 2.3.3 of gcc were ported by Stan Shebs and are available at

ftp://ftp.cygnus.com/pub/mac

They are both interfaced to MPW. Stan is working on a version using the current (post-2.7) sources, contact him directly (shebs@cygnus.com) for more information.

But I can only find g++-1.42!
=============================

``I keep hearing people talking about g++ 2.8.0 (or some other number starting with 2), but the latest version I can find is g++ 1.42. Where is it?''

As of gcc 2.0, C, C++, and Objective-C as well are all combined into a single distribution called gcc.  If you get gcc you already have g++.  The standard installation procedure for any gcc version 2 compiler will install the C++ compiler as well.

One could argue that we shouldn't even refer to "g++-2.x.y" but it's a convention.  It means ``the C++ compiler included with gcc-2.x.y.''

The Next Generation(s) of g++
*****************************

What's new in gcc/g++ 2.8.0?
============================

After a two-year wait, gcc 2.8.0 was released in January 1998, along with libstdc++-2.8.0 and libg++-2.8.0.  Note that the latter (libg++) contains the former (libstdc++) so there is no reason to install both library packages, but libstdc++ is required.

For those familiar with egcs, the most obvious difference between gcc-2.8.0 and egcs-1.0 or 1.0.1 is the packaging: egcs is bundled with libstdc++, and gcc-2.8.0 does not contain the class library.  Otherwise, except for the lack of the -frepo option and some bug fixes that have not yet made it into gcc-2.8.0, C++ users will find the two compilers to be almost the same at this stage, other than that 2.8.0 users may get more bogus warnings with -Wall and optimization because some fixes to flow analysis in the presence of exceptions that egcs made are not yet present in gcc 2.8.0.

Because the new feature lists for egcs and gcc 2.8 are almost the same, please see egcs-whats-new for a list of new features.  It is a fairly long list.

What is egcs?
=============

egcs is the Experimental GNU compiler system (see http://www.cygnus.com/egcs on the Web).  It is an effort to accelerate development of new gcc features by providing a more open development model than gcc has traditionally used.

The first egcs release, egcs-1.0, came out on December 3, 1997. The current release is egcs-1.0.1, released January 6, 1998. Questions not addressed here may be answered in the egcs FAQ (http://www.cygnus.com/egcs/faq.html).

What new C++ features are in egcs?
==================================

Note: unless indicated otherwise, these features are also present in g++ 2.8.0.

  * The standard C++ classes are integrated with the egcs release (but not for gcc-2.8.0, which does not include the class libraries). libg++ is not being supported, though an add-on version that will work with egcs can be found at ftp://ftp.yggdrasil.com/private/hjl/libg++-2.8.0b6.6.tar.gz, thanks to H.J. Lu.  The compiler and library are configured and built in one step.

  * A completely new template implementation, much closer to the draft standard.  Limitations in 2.7.2.x concerning inlining template functions are eliminated.  Static template data members, template class member functions, partial specification, and default template arguments are supported.  An instantiation method resembling that used in Borland C++ (instantiating functions possibly in multiple .o files and using weak symbols to link correctly) is provided, in addition to other options.  The SGI version of STL is shipped verbatim with libstdc++ (libstdc++ is included with egcs, separate with gcc-2.8.0).

  * On ELF platforms (Linux/ELF, Solaris, SVR4), if the GNU linker is used, duplicated template functions and virtual function tables are eliminated at link time.

  * The -frepo flag is supported in egcs (it is not in 2.8.0). However, because of the previous item, I don't recommend its use on ELF systems, as the default method is better.

  * Exception handling has been re-worked; exceptions will work together with optimization. Actually, there are two separate implementations: one based on setjmp/longjmp and designed to be highly portable, and one designed to be more efficient but requiring more processor-specific support (getting exceptions right has proven to be extremely difficult and has been the chief obstacle to getting a new release out).

  * RTTI has been re-done to work correctly and is on by default.

  * Overloading has been re-worked to conform to the latest draft of the standard.

  * There are many more changes: see http://www.cygnus.com/egcs/c++features.html for a list.

Features that are still missing include namespaces and templates as template arguments.

What was fixed in egcs-1.0.1?
=============================

  * Add support for Red Hat 5.0 Linux and better support for Linux systems using glibc2.

  * Compatibility with both egcs-1.0 and gcc-2.8 libgcc exception handling interfaces (see below).

  * Various bugfixes in the x86, hppa, mips, and rs6000/ppc backends.

  * A few machine independent bugfixes, mostly to fix code generation bugs when building Linux kernels or glibc.

  * Fix a few critical exception handling and template bugs in the C++ compiler.

  * Fix build problems on x86-solaris systems.

To avoid future compatibility problems, we strongly urge anyone who is planning on distributing shared libraries that contain C++ code to upgrade to egcs-1.0.1 first.  See http://www.cygnus.com/egcs/egcs-1.0.1.html for details about the compatibility issues as well as additional information about the bugfixes since the egcs-1.0 release.

If I install egcs on Linux, will it overwrite my libraries?
===========================================================

No.  If you build from sources, by default, egcs installs executables in /usr/local/bin and libraries in /usr/local/lib, and you can change this default if desired (see next section).

If, however, you install a package (e.g. Debian or Red Hat) that wants to put egcs in /usr/bin and /usr/lib, then yes, you are replacing your system compiler and C++ library (I don't know if anyone has provided such packages yet -- proceed with caution).

How can I run both egcs and an FSF release of g++ on the same machine?
======================================================================

The recommended approach is to provide a different argument to the --prefix flag when you configure egcs.  For example, say --prefix=/usr/local/egcs and then, after installation, you can make symbolic links from /usr/local/egcs/bin to whereever you want, for example

     ln -s /usr/local/egcs/bin/gcc /usr/local/bin/egcc
     ln -s /usr/local/egcs/bin/g++ /usr/local/bin/eg++

What about 2.8.0? How does egcs affect the 2.8.x development?
=============================================================

2.8.0 has now been released, with essentially the same C++ front end as egcs.

Bug fixes generated in egcs will be passed to the 2.8.x releases for inclusion; the reverse is also taking place, though a bug fix may appear in one before it does in the other.  egcs development is expected to proceed more quickly.

How robust is egcs?
===================

While the 'e' stands for 'experimental', egcs has been tested thoroughly and should be of high quality.  A few glitches in the initial release were fixed in 1.0.1.  egcs-1.0 users should upgrade.

Some memory bloat problems with deeply nested templates were fixed in 1.0.1 (though it appears that there are still a few cases where excessive memory requirements occur).

Installation Issues and Problems
********************************

I can't build g++ 1.x.y with gcc-2.x.y!
=======================================

``I obtained gcc-2.x.y and g++ 1.x.y and I'm trying to build it, but I'm having major problems.  What's going on?''

If you wish to build g++-1.42, you must obtain gcc-1.42 first.  The installation instructions for g++ version 1 leave a lot to be desired, unfortunately, and I would recommend that, unless you have a special reason for needing the 1.x compiler, that C++ users use the latest g++-2.x version, as it is the version that is being actively maintained.

There is no template support in g++-1.x, and it is generally much further away from the ANSI draft standard than g++-2.x is.

OK, I've obtained gcc; what else do I need?
===========================================

First off, you'll want libg++ as you can do almost nothing without it (unless you replace it with some other class library).

Second, depending on your platform, you may need "GAS", the GNU assembler, or the GNU linker (see next question).

Finally, while it is not required, you'll almost certainly want the GNU debugger, gdb.  The latest version is 4.16, released April 22, 1996. Other debuggers (like dbx, for example) will normally not be able to understand at least some of the debug information produced by g++.

Should I use the GNU linker, or should I use "collect"?
=======================================================

First off, for novices: special measures must be taken with C++ to arrange for the calling of constructors for global or static objects before the execution of your program, and for the calling of destructors at the end. (Exception: System VR3 and System VR4 linkers, Linux/ELF, and some other systems support user-defined segments; g++ on these systems requires neither the GNU linker nor collect.  So if you have such a system, the answer is that you don't need either one, though using GNU ld does have some advantages over the native linker in some cases).

If you have experience with AT&T's "cfront", this function is performed there by programs named "patch" or "munch".  With GNU C++, it is performed either by the GNU linker or by a program known as "collect".  The collect program is part of the gcc-2.x distribution; you can obtain the GNU linker separately as part of the "binutils" package.  The latest version of binutils is 2.7, released July 10, 1996; 2.6 is in common use and works well.

(To be technical, it's "collect2"; there were originally several alternative versions of collect, and this is the one that survived).

There are advantages and disadvantages to either choice.

Advantages of the GNU linker:

It's faster than using collect -- collect basically runs the standard Unix linker on your program twice, inserting some extra code after the first pass to call the constructors.  This is a sizable time penalty for large programs.  The GNU linker does not require this extra pass.

GNU ld reports undefined symbols using their true names, not the mangled names (but as of 2.7.0 so does collect).

If there are undefined symbols, GNU ld reports which object file(s) refer to the undefined symbol(s).  On some OSes (e.g. SunOS, Solaris) the native linker does not do this, so you have to track down who's referring to the missing symbols yourself.

As of binutils version 2.2, on systems that use the so-called "a.out" debug format (e.g. Suns running SunOS 4.x), the GNU linker compresses the debug symbol table considerably.  The 2.7 version adds some symbol table compression for ELF and Solaris targets.

Users of egcs or 2.8.0 on ELF systems should definitely use GNU ld (2.8 or later), as it will automatically remove duplicate instantiations of templates, virtual function tables, or ``outlined'' copies of inline functions.

Advantages of collect:

If your native linker supports shared libraries, you can use shared libraries with collect.  This used to be a strong reason not to use the GNU linker, but recent versions of GNU ld support linking with shared libraries on many platforms, and creating shared libraries on a few (such as Intel x86 systems that use ELF object format as well as SunOS and Solaris).

See shared libraries

The GNU linker has not been ported to as many platforms as g++ has, so you may be forced to use collect.

If you use collect, you don't need to get something extra and figure out how to install it; the standard gcc installation procedure will do it for you.

I used to say at this point that I don't see a clear win for either linking alternative, but with all the improvements in the GNU linker I think that it is now the better choice.  Take your pick.

If you run Linux, the only available linker is the GNU linker.

Should I use the GNU assembler, or my vendor's assembler?
=========================================================

This depends on your platform and your decision about the GNU linker.  For most platforms, you'll need to use GAS if you use the GNU linker.  For some platforms, you have no choice; check the gcc installation notes to see whether you must use GAS.  But you can usually use the vendor's assembler if you don't use the GNU linker.

The GNU assembler assembles faster than many native assemblers; however, on many platforms it cannot support the local debugging format.

It used to be that the GNU assembler couldn't handle position-independent code on SunOS.  This is no longer true if you have version 2.6 or newer.

On HPUX or IRIX, you must use GAS (and configure gcc with the --with-gnu-as option) to debug your programs.  GAS is strongly recommended particularly on the HP platform because of limitations in the HP assembler.

The GNU assembler has been merged with the binutils distribution, so the GNU assembler and linker are now together in this package (as of binutils version 2.5.1).

On Linux the assembler is the GNU assembler.

How do I build shared libraries with g++?
=========================================

For gcc-2.7.0 and later, building C++ shared libraries should work fine on supported platforms (HPUX 9+, IRIX 5+, DEC UNIX (formerly OSF/1), SGI/IRIX, AIX, SunOS 4, Linux/ELF and all targets using SVR4-style ELF shared libraries).  There are two separate issues: building libg++ as a shared library, and making your own shared libraries.  For libg++ it is simply a matter of giving the --enable-shared option to the configure program.  When compiling your own code for shared libraries you generally must use the -fPIC flag to get position-independent code.

If your shared library contains global or static objects with constructors, then make sure to use gcc -shared, not ld, to create the shared library.  This will make sure that any processor-specific magic needed to execute the constructors is included.

In theory, constructors for objects in your shared library should be called when the library is opened (by dlopen or equivalent).  This does not work on some platforms (e.g. SunOS4; it does work on Solaris and ELF systems such as Linux): on the broken platforms, the constructors are not called correctly.

David Nilsen has suggested the following workaround:

The thing to realize is that if you link your dynamic module with the -shared flag, the collect program nicely groups all the static ctors/dtors for you into a list and sets up a function that will call them (Note: this means that this trick won't work if you use the GNU linker without collect (see use GNU linker?).

The magic is knowing these function names.  Currently, they're called:

     _GLOBAL__DI   <-- calls all module constructors
     _GLOBAL__DD   <-- calls all module destructors

[ possibly the leading underscore will differ between platforms: jbuck ]

Therefore, if you make a wrapper around dlopen that looks up the symbol _GLOBAL__DI (or __GLOBAL__DI on SunOS4 machines), and calls it, you'll simulate getting the constructors called.

You also need to set up the destructors to be called as well, so you need to put a wrapper around dlclose, which will call the _GLOBAL__DD function in the module when/if it's unloaded.

Lastly, to get things 100% correct, you need to set up the destructors to also be called if the module is not unloaded, but the main program exits.  I do this by registering a single function with atexit() that calls all the destructors left in dynamically loaded modules.

Check the file README.SHLIB from the libg++ distribution for more about making and using shared libraries.

A patch is needed to build shared versions of version 2.7.2 of libg++ and libstdc++ on the HP-PA architecture.  You can find the patch at ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix.

How do I use the new repository code?
=====================================

Because there is some disagreement about the details of the template repository mechanism, you'll need to obtain a patch from Cygnus Support to enable the 2.7.2 repository code.  You can obtain the patch by anonymous FTP: ftp://ftp.cygnus.com/pub/g++/gcc-2.7.2-repo.gz.

There are patches for 2.7.0 and 2.7.1 in the same directory, though if you're going to rebuild the compiler you should use the latest one.

If you're running NetBSD or BSDI, the Cygnus repo patch is not quite correct.  Tim Liddelow has made an alternate version available at ftp://ftp.cst.com.au/pub/gcc-2.7.2-repo-bsd.gz.

After you've applied the patch, the -frepo flag will enable the repository mechanism.  The flag works much like the existing -fno-implicit-templates flag, except that auxiliary files, with an .rpo extension, are built that specify what template expansions are needed.  At link time, the (patched) collect program detects missing templates and recompiles some of the object files so that the required templates are expanded.

Note that the mechanism differs from that of cfront in that template definitions still must be visible at the point where they are to be expanded.  No assumption is made that foo.C contains template definitions corresponding to template declarations in foo.h.

Jason Merrill writes: ``To perform closure on a set of objects, just try to link them together.  It will fail, but as a side effect all needed instances will be generated in the objects.''

Known bugs and problems with the repo patch
===========================================

``The -frepo won't expand templated friend functions!''

This is a known bug; currently you'll have to explicitly instantiate friend functions when using -frepo due to this bug (in 2.7.0 through 2.7.2 at least).

With earlier versions of the repo patch, there was a bug that happens when you have given a quoted command line switch, something like

     -D'MESSAGE="hello there"'

The repo code tries to recompile files using the same flags you originally specified, but doesn't quote arguments that need quoting, resulting in failures in some cases.  This is no longer a problem with the 2.7.2 patch.

Should I use the GNU C library?
===============================

At this point in time, no (unless you are running Linux or the GNU Hurd system).  The GNU C library is still very young, and libg++ still conflicts with it in some places.  Use your native C library unless you know a lot about the gory details of libg++ and gnu-libc.  This will probably change in the future.

Global constructors aren't being called
=======================================

``I've installed gcc and it almost works, but constructors and destructors for global objects and objects at file scope aren't being called.  What did I do wrong?''

It appears that you are running on a platform that requires you to install either "collect2" or the GNU linker, and you have done neither. For more information, see the section discussing the GNU linker (see use GNU linker?).

On Solaris 2.x, you shouldn't need a collect program and GNU ld doesn't run. If your global constructors aren't being called, you may need to install a patch, available from Sun, to fix your linker.  The number of the ``jumbo patch'' that applies is 101409-03.  Thanks to Russell Street (r.street@auckland.ac.nz) for this info.

It appears that on IRIX, the collect2 program is not being installed by default during the installation process, though it is required; you can install it manually by executing

     make install-collect2

from the gcc source directory after installing the compiler.  (I'm not certain for which versions of gcc this problem occurs, and whether it is still present).

Strange assembler errors when linking C++ programs
==================================================

``I've installed gcc and it seemed to go OK, but when I attempt to link any C++ program, I'm getting strange errors from the assembler!  How can that be?''

The messages in question might look something like

     as: "/usr/tmp/cca14605.s", line 8: error: statement syntax
     as: "/usr/tmp/cca14605.s", line 14: error: statement syntax

(on a Sun, different on other platforms).  The important thing is that the errors come out at the link step, not when a C++ file is being compiled.

Here's what's going on: the collect2 program uses the Unix ``nm'' program to obtain a list of symbols for the global constructors and destructors, and it builds a little assembly language module that will permit them all to be called.  If you're seeing this symptom, you have an old version of GNU nm somewhere on your path.  This old version prints out symbol names in a format that the collect2 program does not expect, so bad assembly code is generated.

The solution is either to remove the old version of GNU nm from your path (and that of everyone else who uses g++), or to install a newer version (it is part of the GNU "binutils" package).  Recent versions of GNU nm do not have this problem.

Other problems building libg++
==============================

``I am having trouble building libg++.  Help!''

On some platforms (for example, Ultrix), you may see errors complaining about being unable to open dummy.o.  On other platforms (for example, SunOS), you may see problems having to do with the type of size_t. The fix for these problems is to make libg++ by saying "make CC=gcc". According to Per Bothner, it should no longer be necessary to specify "CC=gcc" for libg++-2.3.1 or later.

``I built and installed libg++, but g++ can't find it.  Help!''

The string given to configure that identifies your system must be the same when you install libg++ as it was when you installed gcc. Also, if you used the --prefix option to install gcc somewhere other than /usr/local, you must use the same value for --prefix when installing libg++, or else g++ will not be able to find libg++.

The toplevel Makefile in the libg++ 2.6.2 distribution is broken, which along with a bug in g++ 2.6.3 causes problems linking programs that use the libstdc++ complex classes.  A patch for this is available from ftp://ftp.cygnus.com//pub/g++/libg++-2.6.2-fix.gz.

But I'm still having problems with size_t!
==========================================

``I did all that, and I'm still having problems with disagreeing definitions of size_t, SIZE_TYPE, and the type of functions like strlen.''

The problem may be that you have an old version of _G_config.h lying around.  As of libg++ version 2.4, _G_config.h, since it is platform-specific, is inserted into a different directory; most include files are in $prefix/lib/g++-include, but this file now lives in $prefix/$arch/include.  If, after upgrading your libg++, you find that there is an old copy of _G_config.h left around, remove it, otherwise g++ will find the old one first.

Do I need to rebuild libg++ to go with my new g++?
==================================================

``After I upgraded g++ to the latest version, I'm seeing undefined symbols.''

or

``If I upgrade to a new version of g++, do I need to reinstall libg++?''

As a rule, the first two digits of your g++ and libg++ should be the same.  Normally when you do an upgrade in the ``minor version number'' (2.5.7 to 2.5.8, say) there isn't a need to rebuild libg++, but there have been a couple of exceptions in the past.

I want several versions of g++ and libg++ to co-exist.
======================================================

I recommend against using the -V flag to make multiple versions of gcc/g++ co-exist, unless they are different minor releases that can use the same compiled version of libg++.  The reason is that all these versions will try to use the same libg++ version, which usually will not work.

Instead, use the --prefix flag when configuring gcc.  Use a different value of --prefix for each gcc version.  Use the same value of --prefix when configuring libg++.  You can then have any number of co-existing gcc/libg++ pairs.  Symbolic links can be used so that users don't need to put all these different directories on their paths.

One possible system to use is to set --prefix to /usr/local/gcc-2.x.y for version 2.x.y of gcc, and to link whichever version of gcc you wish to be the default into /usr/local/bin/gcc and /usr/local/bin/g++.

Trouble installing g++ and libg++ on Linux
==========================================

``I've downloaded the latest g++ and libg++ and I'm trying to install them on Linux, and I'm having lots of problems.''

FSF releases of libg++ won't install on Linux unchanged, since Linux uses are part of the libio library from libg++ for its standard C library, only this is changed in a way that it clashes with libg++. This means that you'll need a patched version of libg++ for it to work.

If you want to upgrade to a new gcc/libg++ combination, the easiest thing to do is to grab the prebuilt versions of gcc and libg++ for Linux from ftp://tsx-11.mit.edu/pub/linux/packages/GCC.  Follow the directions carefully.  If you want to build from source, you'll need a patch for libg++; the Linux developers have named the patched libg++ version libg++-2.7.1.3 and there is a patch file in the above-named directory.

See http://sunsite.unc.edu/LDP/HOWTO/GCC-HOWTO.html, the Linux GCC HOWTO, for more on gcc/g++ and Linux.

Linux is in the process of switching over to the GNU C library, version 2, which will become Linux libc version 6.  Once this process is complete, there's a good chance that the installation process on Linux will be smoother, but only experts should try making this new library work at this point.

Problems with g++ on Linux Slackware 3.0
========================================

``When I try to compile the traditional Hello, world program on Linux, the compiler can't find iostream.h.  What's the deal?''

You probably have the Slackware 3.0 release.  There's an error in the setup.  It's easy to fix, though; log in as root, and make a symbolic link:

     ln -s /usr/lib/g++-include /usr/include/g++

The Evolution of g++
********************

This chapter discusses the evolution of g++ and describes what can be expected in the future.

What's new in version 2.7.x of gcc/g++
======================================

[ This section is old now, since 2.8.0/egcs is the new stuff ] The latest 2.7.x version was 2.7.2.2, released February 10, 1997.  The only change between 2.7.2.1 and 2.7.2.2 is that support was added for using the GNU C library, version 2, on Linux; users not interested in that functionality have no reason to upgrade.  The previous version of gcc/g++ was 2.7.2.1, released August 14, 1996.  The libg++ version that should be used with any 2.7.x gcc/g++ is 2.7.2, released July 4, 1996.

Note that gcc 2.7.2.1 just consists of several small patches to gcc-2.7.2.  The release is mainly intended to fix platform-specific bugs and does not affect the C++ ``front end'' of the compiler (the part that parses your C++ code).

The 2.7.x releases represent a great deal of work on the part of the g++ maintainers to fix outstanding bugs and move the compiler closer to the current ANSI/ISO standards committee's working paper, including supporting many of the new features that have been added to the language.  I recommend that everyone read the NEWS file contained in the distribution (and that system administrators make the file available to their users).  I've borrowed liberally from this file here.

If any features seem unfamiliar, you will probably want to look at the recently-released public review copy of the C++ Working Paper.  A new draft, dated 2 December 1996, has been released for public comment.  You can find it on the web at http://www.cygnus.com/misc/wp/ or http://www.maths.warwick.ac.uk/c++/pub/wp/html/cd2/. See http://www.setech.com/x3.html or http://www.maths.warwick.ac.uk/c++/pub/ to download the document in PostScript, PDF (Adobe Acrobat), HTML, or ASCII form.

Here are the main points:

  * As described above, the scope of variables declared in the initialization part of a for statement has been changed; such variables are now visible only in the loop body.  Use -fno-for-scope to get the old behavior.  You'll need this flag to build groff version 1.09, Ptolemy, and many other free software packages.

  * Code that does not use #pragma interface/implementation will most likely shrink dramatically, as g++ now only emits the vtable for a class in the translation unit where its first non-inline, non-abstract virtual function is defined.

  * Support for automatic template instantiation has not been enabled in the official distribution, due to a disagreement over design philosophies. But you can get a patch from Cygnus to turn it on; retrieve the patch from ftp://ftp.cygnus.com/pub/g++/gcc-2.7.2-repo.gz to patch gcc-2.7.2 (there are also patches for earlier gcc versions).

  * See exceptions

  * Support for Run-Time Type Identification has been added with -frtti. This support is still in alpha; one major restriction is that any file compiled with -frtti must include <typeinfo> (not typeinfo.h as the NEWS file says). Also, all C++ code you link with (including libg++) has to be built with -frtti, so it's still tricky to use.

  * Synthesis of compiler-generated constructors, destructors and assignment operators is now deferred until the functions are used.

  * The parsing of expressions such as a ? b : c = 1 has changed from (a ? b : c) = 1 to a ? b : (c = 1).  This is a new C/C++ incompatibility brought to you by the ANSI/ISO standards committee.

  * The operator keywords and, and_eq, bitand, bitor, compl, not, not_eq, or, or_eq, xor and xor_eq are now supported.  Use -ansi or -foperator-names to enable them.

  * The explicit keyword is now supported.  explicit is used to mark constructors and type conversion operators that should not be used implicitly.

  * Handling of user-defined type conversion has been improved.

  * Explicit instantiation of template methods is now supported.  Also, inline template class foo<int>; can be used to emit only the vtable for a template class.

  * With -fcheck-new, g++ will check the return value of all calls to operator new, and not attempt to modify a returned null pointer.

  * collect2 now demangles linker output, and c++filt has become part of the gcc distribution.

  * Improvements to template instantiation: only members actually used are instantiated.  (Actually this is not quite true: some inline templates that are not successfully inlined may be expanded even though they are not needed).

The GNU Standard C++ Library
============================

The GNU Standard C++ Library (also called the ``GNU ANSI C++ Library'' in places in the code) is not libg++, though it is included in the libg++ distribution.  Rather, it contains classes and functions required by the ANSI/ISO standard.  The copyright conditions are the same as those for for the iostreams classes; the LGPL is not used (see legalities).

This library, libstdc++, is in the libg++ distribution in versions 2.6.2 and later.  It requires at least gcc 2.6.3 to build the libg++-2.6.2 version; use at least gcc 2.7.0 to build the libg++ 2.7.0 version.  It contains a hacked-up version of HP's implementation of the Standard Template Library (see Standard Template Library).  I've successfully used this Standard Template Library version to build a number of the demos you'll see on various web pages.

As of version 2.7.0, the streams classes are now in libstdc++ instead of libg++, and libiostream is being phased out (don't use it).  The g++ program searches this library.

The maintainers of libg++ have de-emphasized work on the older libg++ classes in favor of enhancing libstdc++ to cover the full language, so while libg++ will always be available, enhancements to it should not be expected.

User Problems
*************

Linker complains about missing virtual table
============================================

``I'm getting a message complaining about an undefined virtual table.  Is this a compiler bug?''

(On platforms that run neither collect nor the GNU linker, like Solaris, you may see an odd undefined symbol like "_vt.3foo", where foo is a class name).

This is probably because you are missing a definition for the first (non-inline) virtual function of the class.  Since gcc-2.7.0, g++ uses a trick borrowed from cfront: the .o file containing the definition for the first non-inline virtual function for the class will also contain the virtual function table.

gcc-2.7.0 breaks declarations in "for" statements!
==================================================

gcc-2.7.0 implements the new ANSI/ISO rule on the scope of variables declared in for loops.

     for (int i = 1; i <= 10; i++) {
             // do something here
     }
     foo(i);

In the above example, most existing C++ compilers would pass the value 11 to the function foo.  In gcc 2.7 and in the ANSI/ISO working paper, the scope of i is only the for loop body, so this is an error.  So that old code can be compiled, the new gcc has a flag -fno-for-scope that causes the old rule to be used.

As of 2.7.1, the compiler attempts to issue warnings about code that has different meanings under the two sets of rules, but the code is not perfect: the intent was that code that has valid, but different, meanings under the ARM rules and the working paper rules would give warnings but have the new behavior, and this doesn't seem to happen.

The -ffor-scope flag under 2.7.1 and 2.7.2 gives the 2.7.0 behavior.

g++ seems to want a const constructor. What's that?
===================================================

gcc-2.7.1 introduced a bug that causes the compiler to ask for a const constructor (there's no such thing in C++) in certain situations where a const object appears in a template class.  Most cases have been fixed in gcc-2.7.2, but unfortunately not all.  Still, if you're running gcc-2.7.1 and have this problem, upgrade to 2.7.2; it is a vast improvement.

The default constructor for the template pair in ObjectSpace's implementation of STL triggers the bug in one place, for gcc 2.7.2.  If you're using ObjectSpace<STL> and having this problem, simply change the default constructor from

     os_pair () : first (T1 ()), second (T2 ()) {}

to just

     os_pair () {}

Once this is done, ObjectSpace<STL> works fairly well.

How to silence ``unused parameter'' warnings
============================================

``When I use -Wall (or -Wunused), g++ warns about unused parameters.  But the parameters have to be there, for use in derived class functions.  How do I get g++ to stop complaining?''

The answer is to simply omit the names of the unused parameters when defining the function.  This makes clear, both to g++ and to readers of your code, that the parameter is unused.  For example:

     int Foo::bar(int arg) { return 0; }

will give a warning for the unused parameter arg.  To suppress the warning write

     int Foo::bar(int) { return 0; }

g++ objects to a declaration in a case statement
================================================

``The compiler objects to my declaring a variable in one of the branches of a case statement.  Earlier versions used to accept this code.  Why?''

The draft standard does not allow a goto or a jump to a case label to skip over an initialization of a variable or a class object.  For example:

     switch ( i ) {
       case 1:
         Object obj(0);
             ...
         break;
       case 2:
     	...
         break;
     }

The reason is that obj is also in scope in the rest of the switch statement.

As of version 2.7.0, the compiler will object that the jump to the second case level crosses the initialization of obj.  Older compiler versions would object only if class Object has a destructor. In either case, the solution is to add a set of curly braces around the case branch:

       case 1:
         {
            Object obj(0);
             ...
            break;
         }

Where can I find a demangler?
=============================

A g++-compatible demangler named c++filt can be found in the binutils distribution.  This distribution (which also contains the GNU linker) can be found at any GNU archive site.

As of version 2.7.0, c++filt is included with gcc and is installed automatically.  Even better, it is used by the collect linker, so you don't see mangled symbols anymore (except on platforms that use neither collect nor the GNU linker, like Solaris).

Linker reports undefined symbols for static data members
========================================================

``g++ reports undefined symbols for all my static data members when I link, even though the program works correctly for compiler XYZ.  What's going on?''

The problem is almost certainly that you don't give definitions for your static data members.  If you have

     class Foo {
     	...
     	void method();
     	static int bar;
     };

you have only declared that there is an int named Foo::bar and a member function named Foo::method that is defined somewhere.  You still need to define both method() and bar in some source file.  According to the draft ANSI standard, you must supply an initializer, such as

     int Foo::bar = 0;

in one (and only one) source file.

What does ``Internal compiler error'' mean?
===========================================

It means that the compiler has detected a bug in itself.  Unfortunately, g++ still has many bugs, though it is a lot better than it used to be. If you see this message, please send in a complete bug report (see next section).

I think I have found a bug in g++.
==================================

``I think I have found a bug in g++, but I'm not sure.  How do I know, and who should I tell?''

First, see the excellent section on bugs and bug reports in the gcc manual (which is included in the gcc distribution).  As a short summary of that section: if the compiler gets a fatal signal, for any input, it's a bug (newer versions of g++ will ask you to send in a bug report when they detect an error in themselves).  Same thing for producing invalid assembly code.

When you report a bug, make sure to describe your platform (the type of computer, and the version of the operating system it is running) and the version of the compiler that you are running.  See the output of the command g++ -v if you aren't sure.  Also provide enough code so that the g++ maintainers can duplicate your bug.  Remember that the maintainers won't have your header files; one possibility is to send the output of the preprocessor (use g++ -E to get this).  This is what a ``complete bug report'' means.

I will add some extra notes that are C++-specific, since the notes from the gcc documentation are generally C-specific.

First, mail your bug report to "bug-g++@prep.ai.mit.edu".  You may also post to gnu.g++.bug, but it's better to use mail, particularly if you have any doubt as to whether your news software generates correct reply addresses.  Don't mail C++ bugs to bug-gcc@prep.ai.mit.edu.

News: as I write this (late February 1996) the gateway connecting the bug-g++ mailing list and the gnu.g++.bug newsgroup is (temporarily?) broken.  Please mail, do not post bug reports.

If your bug involves libg++ rather than the compiler, mail to bug-lib-g++@prep.ai.mit.edu.  If you're not sure, choose one, and if you guessed wrong, the maintainers will forward it to the other list.

Second, if your program does one thing, and you think it should do something else, it is best to consult a good reference if in doubt. The standard reference is the draft working paper from the ANSI/ISO C++ standardization committee, which you can get on the net. For PostScript and PDF (Adobe Acrobat) versions, see the archive at ftp://research.att.com/dist/stdc++/WP.  For HTML and ASCII versions, see ftp://ftp.cygnus.com/pub/g++.  On the World Wide Web, see http://www.cygnus.com/misc/wp/.

An older standard reference is "The Annotated C++ Reference Manual", by Ellis and Stroustrup (copyright 1990, ISBN #0-201-51459-1).  This is what they're talking about on the net when they refer to ``the ARM''.  But you should know that changes have been made to the language since then.

The ANSI/ISO C++ standards committee have adopted some changes to the C++ language since the publication of the original ARM, and newer versions of g++ (2.5.x and later) support some of these changes, notably the mutable keyword (added in 2.5.0), the bool type (added in 2.6.0), and changes in the scope of variables defined in for statements (added in 2.7.0). You can obtain an addendum to the ARM explaining many of these changes by FTP from ftp://ftp.std.com/AW/stroustrup2e/new_iso.ps.

Note that the behavior of (any version of) AT&T's "cfront" compiler is NOT the standard for the language.

Porting programs from other compilers to g++
============================================

``I have a program that runs on <some other C++ compiler>, and I want to get it running under g++.  Is there anything I should watch out for?''

Note that g++ supports many of the newer keywords that have recently been added to the language.  Your other C++ compiler may not support them, so you may need to rename variables and members that conflict with these keywords.

There are two other reasons why a program that worked under one compiler might fail under another: your program may depend on the order of evaluation of side effects in an expression, or it may depend on the lifetime of a temporary (you may be assuming that a temporary object "lives" longer than the standard guarantees).  As an example of the first:

     void func(int,int);

     int i = 3;
     func(i++,i++);

Novice programmers think that the increments will be evaluated in strict left-to-right order.  Neither C nor C++ guarantees this; the second increment might happen first, for example.  func might get 3,4, or it might get 4,3.

The second problem often happens with classes like the libg++ String class.  Let's say I have

     String func1();
     void func2(const char*);

and I say

     func2(func1());

because I know that class String has an "operator const char*".  So what really happens is

     func2(func1().convert());

where I'm pretending I have a convert() method that is the same as the cast.  This is unsafe in g++ versions before 2.6.0, because the temporary String object may be deleted after its last use (the call to the conversion function), leaving the pointer pointing to garbage, so by the time func2 is called, it gets an invalid argument.

Both the cfront and the old g++ behaviors are legal according to the ARM, but the powers that be have decided that compiler writers were given too much freedom here.

The ANSI C++ committee has now come to a resolution of the lifetime of temporaries problem: they specify that temporaries should be deleted at end-of-statement (and at a couple of other points).  This means that g++ versions before 2.6.0 now delete temporaries too early, and cfront deletes temporaries too late.  As of version 2.6.0, g++ does things according to the new standard.

For now, the safe way to write such code is to give the temporary a name, which forces it to live until the end of the scope of the name. For example:

     String& tmp = func1();
     func2(tmp);

Finally, like all compilers (but especially C++ compilers, it seems), g++ has bugs, and you may have tweaked one.  If so, please file a bug report (after checking the above issues).

Why does g++ mangle names differently from other C++ compilers?
===============================================================

See the answer to the next question.

Why can't g++ code link with code from other C++ compilers?
===========================================================

``Why can't I link g++-compiled programs against libraries compiled by some other C++ compiler?''

Some people think that, if only the FSF and Cygnus Support folks would stop being stubborn and mangle names the same way that, say, cfront does, then any g++-compiled program would link successfully against any cfront-compiled library and vice versa.  Name mangling is the least of the problems. Compilers differ as to how objects are laid out, how multiple inheritance is implemented, how virtual function calls are handled, and so on, so if the name mangling were made the same, your programs would link against libraries provided from other compilers but then crash when run.  For this reason, the ARM encourages compiler writers to make their name mangling different from that of other compilers for the same platform. Incompatible libraries are then detected at link time, rather than at run time.

What documentation exists for g++ 2.x?
======================================

Relatively little. While the gcc manual that comes with the distribution has some coverage of the C++ part of the compiler, it focuses mainly on the C compiler (though the information on the ``back end'' pertains to C++ as well). Still, there is useful information on the command line options and the #pragma interface and #pragma implementation directives in the manual, and there is a useful section on template instantiation in the 2.6 version. There is a Unix-style manual entry, "g++.1", in the gcc-2.x distribution; the information here is a subset of what is in the manual.

You can buy a nicely printed and bound copy of this manual from the FSF; see above for ordering information.

A draft of a document describing the g++ internals appears in the gcc distribution (called g++int.texi); it is incomplete but gives lots of information.

For class libraries, there are several resources available:

  * The libg++ distribution has a manual libg++/libg++.texi describing the old libg++ classes, and another manual libio/iostream.texi describing the iostreams implementation.

  * While there is no libg++-specific document describing the STL implementation, SGI's web site, at http://www.sgi.com/Technology/STL/, is an excellent resource. Note that the SGI version of STL is the one that is included with the egcs and 2.8.0 releases of g++/libstdc++.

Problems with the template implementation
=========================================

g++ does not implement a separate pass to instantiate template functions and classes at this point; for this reason, it will not work, for the most part, to declare your template functions in one file and define them in another.  The compiler will need to see the entire definition of the function, and will generate a static copy of the function in each file in which it is used.

(The experimental template repository code (see repository) that can be added to 2.7.0 or later does implement a separate pass, but there is still no searching of files that the compiler never saw).

For version 2.6.0, however, a new switch -fno-implicit-templates was added; with this switch, templates are expanded only under user control.  I recommend that all g++ users that use templates read the section ``Template Instantiation'' in the gcc manual (version 2.6.x and newer).  g++ now supports explicit template expansion using the syntax from the latest C++ working paper:

     template class A<int>;
     template ostream& operator << (ostream&, const A<int>&);

As of version 2.7.2, there are still a few limitations in the template implementation besides the above (thanks to Jason Merrill for this info):

Note: these problems are eliminated in egcs and in gcc-2.8.0.

 1. Static data member templates are not supported.  You can work around this by explicitly declaring the static variable for each template specialization:

          template <class T> struct A {
            static T t;
          };

          template <class T> T A<T>::t = 0; // gets bogus error
          int A<int>::t = 0;                // OK (workaround)

     (still a limitation in 2.7.2)

 2. Template member names are not available when defining member function templates.

          template <class T> struct A {
            typedef T foo;
            void f (foo);
            void g (foo arg) { ... }; // this works
          };

          template <class T> void A<T>::f (foo) { } // gets bogus error

 3. Templates are instantiated using the parser.  This results in two problems:

     a) Class templates are instantiated in some situations where such instantiation should not occur.

          template <class T> class A { };
          A<int> *aip = 0; // should not instantiate A<int> (but does)

     b) Function templates cannot be inlined at the site of their instantiation.

          template <class T> inline T min (T a, T b) { return a < b ? a : b; }

          void f () {
            int i = min (1, 0);           // not inlined
          }

          void g () {
            int j = min (1, 0);           // inlined
          }

     A workaround that works in version 2.6.1 through 2.7.2.x is to specify

          extern template int min (int, int);

     before f(); this will force it to be instantiated (though not emitted).

     Note: this kind of ``guiding declaration'' is not standard and isn't supported by egcs or gcc-2.8.0, as the standard says that this declares a ``normal'' min function which has no relation to the template function min<int>(int,int).  But then the new compilers have no problem inlining template functions.

 4. Member function templates are always instantiated when their containing class is.  This is wrong (fixed in egcs/2.8).

I get undefined symbols when using templates
============================================

(Thanks to Jason Merrill for this section).

g++ does not automatically instantiate templates defined in other files. Because of this, code written for cfront will often produce undefined symbol errors when compiled with g++.  You need to tell g++ which template instances you want, by explicitly instantiating them in the file where they are defined.  For instance, given the files

templates.h:

     template <class T>
     class A {
     public:
       void f ();
       T t;
     };

     template <class T> void g (T a);

templates.cc:

     #include "templates.h"

     template <class T>
     void A<T>::f () { }

     template <class T>
     void g (T a) { }

main.cc:

     #include "templates.h"

     main ()
     {
       A<int> a;
       a.f ();
       g (a);
     }

compiling everything with g++ main.cc templates.cc will result in undefined symbol errors for A<int>::f () and g (A<int>).  To fix these errors, add the lines

     template class A<int>;
     template void g (A<int>);

to the bottom of templates.cc and recompile.

I get multiply defined symbols using templates
==============================================

You may be running into a bug that was introduced in version 2.6.1 (and is still present in 2.6.3) that generated external linkage for templates even when neither -fexternal-templates nor -fno-implicit-templates is specified.  There is a patch for this problem at

ftp://ftp.cygnus.com/pub/g++/gcc-2.6.3-template-fix.

I recommend either applying the patch or using -fno-implicit-templates together with explicit template instantiation as described in previous sections.

This bug is fixed in 2.7.0.

Does g++ support the Standard Template Library?
===============================================

If you want to use the Standard Template Library, do not pass go, upgrade immediately to gcc-2.8.0 or to egcs.  The new C++ front end handles STL very well, and the high-quality implementation of STL from SGI is included verbatim as part of the libstdc++ class library.

If for some reason you must use 2.7.2, you can probably get by with the hacked-up version of the old implementation from HP that is included with libg++-2.7.2, but it is definitely inferior and has more problems.  Alternatively, g++ 2.7.2.x users might try the following: a group at the Moscow Center for Sparc Technology has a port of the SGI STL implementation that mostly works with gcc-2.7.2. See http://www.ipmce.su/people/fbp/stl/stlport.html.

Mumit Khan has produced an ``STL newbie guide'' with lots of information on using STL with gcc.  See

http://www.xraylith.wisc.edu/~khan/software/stl/STL.newbie.html

I'm having problems mixing STL and the standard string class
============================================================

[ This section is for g++ 2.7.2.x users only ]

This is due to a bug in g++ version 2.7.2 and 2.7.2.1; the compiler is confused by the operator declarations.  There is an easy workaround, however; just make sure that the <string> header is included before any STL headers.  That is, just say

     #include <string>

before any other #include directives.

Unfortunately, this doesn't solve all problems; you may still have difficulty with the relational operators !=, <=, >, and >=, thanks to a conflict with the very general definition of these operators in function.h.  One trick that sometimes works is to try to use == and < in your code instead of the other operators.  Another is to use a derived class of <string>.  The only completely satisfactory solution, I'm afraid, is to wait for the new release.

Problems and limitations with exceptions
========================================

Recent g++ versions provide limited support for exceptions.  You must provide the -fhandle-exceptions flag to enable exception handling.  As of version 2.7.2, exceptions may not work properly (and you may get odd error messages when compiling) if you turn on optimization (the -O flag).

You must give the -frtti switch to enable catching of derived exception objects with handlers for the base exception class; if -frtti is not given, only exact type matching works.

For exception handling to work with 2.7.0 your CPU must be a SPARC, RS6000/PowerPC, 386/486/Pentium, or ARM.  Release 2.7.1 added support for the Alpha, and ``m68k is rumored to work on some platforms'' and ``VAX may also work'' (according to Mike Stump). It still doesn't work on HP-PA or MIPS platforms.

Does g++ support namespaces?
============================

As of version 2.7.2, g++ recognizes the keywords namespace and using, and there is some rudimentary code present, but almost nothing connected with namespaces works yet. The new versions (2.8.0/egcs) still lack namespace support, but to help compile standard programs they make

     using namespace std;

a no-op.

What are the differences between g++ and the ARM specification of C++?
======================================================================

Up until recently, there was no really usable exception support.  If you need exceptions, you want gcc-2.8.0 or egcs.  The implementation works fairly well.  The 2.7.x version was strictly alpha quality and quite fragile.

Some features that the ANSI/ISO standardization committee has voted in that don't appear in the ARM are supported, notably the mutable keyword, in version 2.5.x.  2.6.x added support for the built-in boolean type bool, with constants true and false.  Run-time type identification was rudimentary in 2.7.x but is fully supported in 2.8.0, so there are more reserved words: typeid, static_cast, reinterpret_cast, const_cast, and dynamic_cast.

As with any beta-test compiler, there are bugs.  You can help improve the compiler by submitting detailed bug reports.

[ This paragraph obsoleted by 2.8.0/egcs: ] One of the weakest areas of g++ other than templates is the resolution of overloaded functions and operators in complex cases.  The usual symptom is that in a case where the ARM says that it is ambiguous which function should be chosen, g++ chooses one (often the first one declared).  This is usually not a problem when porting C++ code from other compilers to g++, but shows up as errors when code developed under g++ is ported to other compilers.  (I believe this is no longer a significant problem in 2.7.0).

[A full bug list would be very long indeed, so I won't put one here. I may add a list of frequently-reported bugs and "non-bugs" like the static class members issue mentioned above].

Will g++ compile InterViews? The NIH class library? Rogue Wave?
===============================================================

The NIH class library uses a non-portable, compiler-dependent hack to initialize itself, which makes life difficult for g++ users. It will not work without modification, and I don't know what modifications are required or whether anyone has done them successfully.

In short, it's not going to happen any time soon (previous FAQs referred to patches that a new NIHCL release would hopefully contain, but this hasn't happened).

Note: I thought I saw an item indicating that someone had patched NIHCL to work with g++.  Any pointers?

I think that as of version 2.5.6, the standard g++ will compile the standard 3.1 InterViews completely successfully. Note that you'll need the -fno-for-scope flag if you use gcc-2.7.0; with 2.7.2 you may be able to omit this flag but you'll get warnings.

According to Jason Merrill, gcc-2.7.0 and newer works with Rogue Wave's tools.h++ class library, but you may want to grab ftp://ftp.cygnus.com/pub/g++/Tools.h++-6.1-patch.  Again, you'll need the -fno-for-scope flag since Rogue Wave hasn't fixed their code to comply with the new standard yet.

Debugging on SVR4 systems
=========================

``How do I get debugging to work on my System V Release 4 system?''

Most systems based on System V Release 4 (except Solaris) encode symbolic debugging information in a format known as `DWARF'.

Although the GNU C compiler already knows how to write out symbolic debugging information in the DWARF format, the GNU C++ compiler does not yet have this feature yet.  However, work is in progress for DWARF 2 debug support for gcc and g++ and it works fairly well in 2.8.0 and egcs, though we'll have to wait for gdb 4.17 to be released to take full advantage.

In the meantime, you can get g++ debugging under SVR4 systems by configuring gcc with the --with-stabs option.  This causes gcc to use an alternate debugging format, one more like that used under SunOS4. You won't need to do anything special to GDB; it will always understand the ``stabs'' format.

debugging problems on Solaris
=============================

``I'm on Solaris, and gdb says it doesn't know about some of my local symbols.  Help!''

This problem was introduced in gcc 2.7.2; debug symbols for locals that aren't declared at the beginning of a block come out in the wrong order, and gdb can't find such symbols.

This problem is fixed in gcc-2.7.2.1.

X11 conflicts with libg++ in definition of String
=================================================

``X11 and Motif define String, and this conflicts with the String class in libg++.  How can I use both together?''

One possible method is the following:

     #define String XString
     #include <X11/Intrinsic.h>
     /* include other X11 and Motif headers */
     #undef String

and remember to use the correct String or XString when you declare things later.

Why can't I assign one stream to another?
=========================================

[ Thanks to Per Bothner and Jerry Schwarz for this section. ]

Assigning one stream to another seems like a reasonable thing to do, but it's a bad idea.  Usually, this comes up because people want to assign to cout.  This is poor style, especially for libraries, and is contrary to good object-oriented design.  (Libraries that write directly to cout are less flexible, modular, and object-oriented).

The iostream classes do not allow assigning to arbitrary streams, because this can violate typing:

     ifstream foo ("foo");
     istrstream str(...);
     foo = str;
     foo->close ();  /* Oops! Not defined for istrstream! */

The original cfront implementation of iostreams by Jerry Schwarz allows you to assign to cin, cout, cerr, and clog, but this is not part of the draft standard for iostreams and generally isn't considered a good idea, so standard-conforming code shouldn't use this technique.

The GNU implementation of iostream did not support assigning to cin, cout, cerr, and clog for quite a while, but it now does, for backward compatibility with cfront iostream (versions 2.6.1 and later of libg++).

The ANSI/ISO C++ Working Paper does provide ways of changing the streambuf associated with a stream.  Assignment isn't allowed; there is an explicit named member that must be used.

However, it is not wise to do this, and the results are confusing.  For example: fstream::rdbuf is supposed to return the original filebuf, not the one you assigned. (This is not yet implemented in GNU iostream.)  This must be so because fstream::rdbuf is defined to return a filebuf *.

What are the rules for shipping code built with g++ and libg++?
***************************************************************

``Is it is possible to distribute programs for profit that are created with g++ and use the g++ libraries?''

I am not a lawyer, and this is not legal advice.  In any case, I have little interest in telling people how to violate the spirit of the GNU licenses without violating the letter.  This section tells you how to comply with the intention of the GNU licenses as best I understand them.

The FSF has no objection to your making money.  Its only interest is that source code to their programs, and libraries, and to modified versions of their programs and libraries, is always available.

The short answer is that you do not need to release the source to your program, but you can't just ship a stripped executable either, unless you use only the subset of libg++ that includes the iostreams classes (see discussion below) or the new libstdc++ library (available in libg++ 2.6.2 and later).

Compiling your code with a GNU compiler does not affect its copyright; it is still yours.  However, in order to ship code that links in a GNU library such as libg++ there are certain rules you must follow.  The rules are described in the file COPYING.LIB that accompanies gcc distributions; it is also included in the libg++ distribution. See that file for the exact rules.  The agreement is called the Library GNU Public License or LGPL.  It is much "looser" than the GNU Public License, or GPL, that covers must GNU programs.

Here's the deal: let's say that you use some version of libg++, completely unchanged, in your software, and you want to ship only a binary form of your code.  You can do this, but there are several special requirements.  If you want to use libg++ but ship only object code for your code, you have to ship source for libg++ (or ensure somehow that your customer already has the source for the exact version you are using), and ship your application in linkable form. You cannot forbid your customer from reverse-engineering or extending your program by exploiting its linkable form.

Furthermore, if you modify libg++ itself, you must provide source for your modifications (making a derived class does not count as modifying the library -- that is "a work that uses the library").

For certain portions of libg++ that implement required parts of the C++ language (such as iostreams and other standard classes), the FSF has loosened the copyright requirement still more by adding the ``special exception'' clause, which reads as follows:

     As a special exception, if you link this library with files compiled with GCC to produce an executable, this does not cause the resulting executable to be covered by the GNU General Public License. This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License.

If your only use of libg++ uses code with this exception, you may ship stripped executables or license your executables under different conditions without fear of violating an FSF copyright.  It is the intent of FSF and Cygnus that, as the other classes required by the ANSI/ISO draft standard are developed, these will also be placed under this ``special exception'' license. The code in the new libstdc++ library, intended to implement standard classes as defined by ANSI/ISO, is also licensed this way.

To avoid coming under the influence of the LGPL, you can link with -liostream rather than -lg++ (for version 2.6.x and earlier), or -lstdc++ now that it is available.  In version 2.7.0 all the standard classes are in -lstdc++; you can do the link step with c++ instead of g++ to search only the -lstdc++ library and avoid the LGPL'ed code in -lg++.

Note that in egcs and in gcc-2.8.0, if you do not specify any libraries the g++ command will only link in -lstdc++, so your executable will not be affected by the LGPL.

If you wish to discuss legal issues connected with GNU software on the net, please use gnu.misc.discuss, not the technical newsgroups.