Archive-name: g++-FAQ/texi
Last-modified: 15 Jun 1994
Frequency: bimonthly

[ This is the texinfo version.  If you don't know what texinfo is,
  then you probably want to use the companion plain-text version. ]

------------- cut here ----------------------------------------------
\input texinfo.tex      @c -*-texinfo-*-
@c %**start of header
@setfilename g++FAQ.info
@settitle Frequently asked questions about the GNU C++ compiler
@setchapternewpage off
@c version: %W% %G%
@c %**end of header

@iftex
@finalout
@end iftex
@titlepage
@title G++ FAQ
@subtitle Frequently asked questions about the GNU C++ compiler
@subtitle May 25, 1994
@sp 1
@author Joe Buck
@page
@end titlepage

@ifinfo
@node Top, getting g++, (dir), (dir)
@top
@unnumbered Preface
@cindex FAQ for g++, latest version
@cindex Archive site for FAQ lists
@cindex rtfm.mit.edu
@cindex Joe Buck <jbuck@@synopsys.com>
@cindex FAQ for C++
@cindex Marshall Cline [FAQ for comp.lang.c++]
@cindex /anonymous@@sun.soe.clarkson.edu:/ftp/pub/C++/FAQ
@end ifinfo

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.

Many FAQ's, including this one, are available on the archive site
rtfm.mit.edu, in the directory @file{pub/usenet/news.answers}.
This FAQ may be found in the subdirectory g++-FAQ.

Some information in this FAQ was developed for earlier versions of the
compiler and may now be obsolete.  Please send corrections.

I'm looking for new questions (@emph{with} answers), better answers,
or both.  You can mail comments,
suggestions, flames, etc. to jbuck@@synopsys.com.  Please don't
assume, though, that because my name is on this thing that I am the
world expert on g++/C++ and you should mail all your tricky questions to
me.  I'd like to be helpful but I'm getting more of this than I can
deal with lately.  Also please don't assume that I am an official
spokesman for g++, FSF, or Cygnus; I'm not.

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 obtain the
C++ FAQ by anonymous FTP from sun.soe.clarkson.edu [128.153.12.3],
in the file @file{~ftp/pub/C++/FAQ}.  (There is also a mail server for that
FAQ, but it seems to be broken).

@menu
* getting g++::     Obtaining Source Code
* installation::    Installation Issues and Problems
* User Problems::   User Problems
* legalities::      What are the rules for shipping code built with g++ and
libg++?
* index::           Concept Index

 --- The Detailed Node Listing ---

Obtaining Source Code

* g++ for Unix::    How do I get a copy of g++ for Unix?
* g++ for HP::  Getting gcc/g++ for the HP Precision Architecture
* g++ for Solaris 2.x::  Getting gcc/g++ binaries for Solaris 2.x
* g++ for other platforms::  How do I get a copy of g++ for (some other
platform)?
* 1.x vs 2.x versions::  But I can only find g++-1.42!
* latest versions::  What is the latest version of gcc, g++, and libg++?

Installation Issues and Problems

* gcc-2 + g++-1::   I can't build g++ 1.x.y with gcc-2.x.y!
* what else do I need?::  OK, I've obtained gcc; what else do I need?
* use GNU linker?::  Should I use the GNU linker, or should I use "collect"?
* Use GNU assembler?::  Should I use the GNU assembler, or my vendor's
assembler?
* Use GNU C library?::  Should I use the GNU C library?
* Global constructor problems:: Global constructors aren't being called
* Strange assembler errors:: Strange assembler errors when linking C++ programs
* Problems building libg++ on 386/486::  
* Other problems building libg++::  
* Rebuild libg++?:: Do I need to rebuild libg++ to go with my new g++?

User Problems

* 2.5.x changes in overloading:: Changes in function overloading
* Demangler::     Where can I find a demangler?
* etags for C++::   Where can I find a version of etags for C++?
* static data members::  Linker reports undefined symbols for static data
members
* placement new syntax::  g++ won't accept the placement new syntax.
* overloaded increment and decrement:: @code{operator++} and @code{operator--}
* bug reports::     I think I have found a bug in g++.
* porting to g++::  Porting programs from other compilers to g++
* name mangling::   Why does g++ mangle names differently from other C++
compilers?
* problems linking with other libraries::  Why can't g++ code link with code
from other C++ compilers?
* documentation::   What documentation exists for g++ 2.x?
* agreement with standards::  What are the differences between g++ and the ARM
specification of C++?
* compiling standard libraries::  Will g++ compile InterViews?  The NIH class
library?
* debugging on SVR4 systems::  Debugging on SVR4 systems
@end menu

@node getting g++, installation, Top, Top
@chapter Obtaining Source Code
@cindex Source code

@menu
* g++ for Unix::    How do I get a copy of g++ for Unix?
* g++ for HP::  Getting gcc/g++ for the HP Precision Architecture
* g++ for Solaris 2.x::  Getting gcc/g++ binaries for Solaris 2.x
* g++ for other platforms::  How do I get a copy of g++ for (some other
platform)?
* 1.x vs 2.x versions::  But I can only find g++-1.42!
* latest versions::  What is the latest version of gcc, g++, and libg++?
@end menu

@node g++ for Unix, g++ for HP,  , getting g++
@section 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).
@cindex GNU gcc, version
@cindex GNU g++ and gcc

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.
@cindex g++, ordering
@cindex g++, getting a copy

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++.
@cindex FSF [Free Software Foundation]
@cindex GNU [GNU's not unix]

For more information about ordering from the FSF, contact
gnu@@prep.ai.mit.edu, phone (617) 876-3296 or anonymous ftp file
@file{/pub/gnu/GNUinfo/ORDERS} from prep.ai.mit.edu or one of the sites
listed below.

@cindex FSF, contact <gnu@@prep.ai.mit.edu>

Here is a list of anonymous FTP archive sites for GNU software.
@cindex GNUware, anonymous FTP sites

@example
ASIA: ftp.cs.titech.ac.jp, utsun.s.u-tokyo.ac.jp:/ftpsync/prep,
     cair.kaist.ac.kr:/pub/gnu
AUSTRALIA: archie.oz.au:/gnu (archie.oz or archie.oz.au for ACSnet)
AFRICA: ftp.sun.ac.za:/pub/gnu
MIDDLE-EAST: ftp.technion.ac.il:/pub/unsupported/gnu
EUROPE: irisa.irisa.fr:/pub/gnu, grasp1.univ-lyon1.fr:pub/gnu,
     ftp.mcc.ac.uk, unix.hensa.ac.uk:/pub/uunet/systems/gnu,
     src.doc.ic.ac.uk:/gnu, ftp.win.tue.nl, ugle.unit.no, ftp.denet.dk,
     ftp.informatik.rwth-aachen.de:/pub/gnu, ftp.informatik.tu-muenchen.de,
     ftp.eunet.ch, nic.switch.ch:/mirror/gnu, nic.funet.fi:/pub/gnu,
     isy.liu.se, ftp.stacken.kth.se, ftp.luth.se:/pub/unix/gnu, archive.eu.net
CANADA: ftp.cs.ubc.ca:/mirror2/gnu
USA: wuarchive.wustl.edu:/mirrors/gnu, labrea.stanford.edu,
     ftp.kpc.com:/pub/mirror/gnu, ftp.cs.widener.edu, uxc.cso.uiuc.edu,
     col.hp.com:/mirrors/gnu, ftp.cs.columbia.edu:/archives/gnu/prep,
     gatekeeper.dec.com:/pub/GNU, ftp.uu.net:/systems/gnu
@end example

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

@cindex gzip
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.

@cindex UUNET
@cindex UUCP
UUNET customers can get GNU sources from UUNET via UUCP.
UUCP-only sites can get GNU sources by ``anonymous UUCP'' from site
"osu-cis" at Ohio State University.  You pay for the long-distance call
to OSU; the price isn't too bad on weekends at 9600 bps.  Send mail to 
uucp@@cis.ohio-state.edu or osu-cis!uucp for more information.

OSU lines are often busy.  If you're in the USA, and are willing to spend
more money, you can get sources via UUCP from UUNET using their 900 number:
1-900-GOT-SRCS (900 numbers don't work internationally).  You will be
billed $0.50/minute by your phone company.

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

@node g++ for HP, g++ for Solaris 2.x, g++ for Unix, getting g++
@section Getting gcc/g++ for the HP Precision Architecture

@cindex HP Precision Architecture
@cindex Hewlett-Packard
@cindex GNU gas 
@cindex GNU gdb
@cindex gcc-2.5.8.u8 [Utah version]
@cindex gcc, patches added

If you use the HP Precision Architecture (HP-9000/7xx and HP-9000/8xx)
and you want to use debugging, you'll need to grab a special version of
GAS from the University of Utah, site jaguar.cs.utah.edu.  Look in the
@file{/dist} directory for gas-2.2.u7.  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 now has code that understands the native HP format.
For now, the GNU
debugger, GDB, understands the debug format produced by this version of
GAS, but not the format produced by HP's compilers.
However, another there is another version of GDB avaiable from this site
that understands the debug format produced by the HP C compiler (but no
version that understands both, unfortunately).

Some enhancements for the HP that haven't been integrated back into the
official GCC are available from the same site in version gcc-2.5.8.u8.
The site also has GDB (4.12.u3), GAS (2.2.u7), and libg++ (2.5.3.u3).
The libg++ version is actually the same as the FSF 2.5.3.

I recommend that HP users use the Utah versions of the tools (see above).
At present, the Utah compiler, assembler, binutils, and debugger
@emph{must} be used as a complete set; they won't work with the generic
FSF versions.  This will change in the future once the Utah changes have
been merged back into the main FSF distributions.

HP GNU users can also find useful stuff on the site geod.emr.ca in the
@file{/pub/GNU-HP} directory.

@node g++ for Solaris 2.x, g++ for other platforms, g++ for HP, getting g++
@section Getting gcc/g++ binaries for Solaris 2.x

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

@cindex Solaris
@cindex gcc/g++ binaries for Solaris

No; prep.ai.mit.edu and its mirror sites provide GCC binaries for
Solaris.  As a rule, these binaries are not updated as often as the
sources are, so if you want the very latest version of gcc/g++, you
may need to grab and install binaries for an older version and use it to
bootstrap the latest version from source.

@cindex gzip
The latest gcc binaries on prep.ai.mit.edu and its mirror sites are for
version 2.5.6 for Solaris on the Sparc, and version 2.4.5 for Solaris on
Intel 386/486 machines.
There are also binaries for ``gzip'', the GNU compression utility, which
you'll need for uncompressing the binary distribution.

@cindex Solaris pkgadd utility
The ftp directory /pub/GNU on site camus.quintus.com contains various
GNU and freeware programs for Solaris2.X running on the sparc. These are
packaged to enable installation using the Solaris ``pkgadd'' utility.
These include GNU emacs 19.19, gcc (and g++) 2.5.8, Perl 4.036, and others.

@node g++ for other platforms, 1.x vs 2.x versions, g++ for Solaris 2.x, getting
g++
@section How do I get a copy of g++ for (some other platform)?

@cindex VMS support
@cindex VAX
@cindex VMS, g++/libg++ precompiled
The standard gcc/g++ distribution includes VMS support.  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 are available by FTP from mango.rsmas.miami.edu.  See also
the site ftp.stacken.kth.se (in Sweden), directory /pub/GNU-VMS/contrib,
which has gcc-2.5.8 and libg++-2.5.3.

@cindex MS-DOS support
@cindex Delorie's gcc/g++
@cindex DJGPP
DJ Delorie has ported gcc/g++ to MS-DOS; this port is popularly known as
"DJGPP" (the P's stand for "plus").  It can be found on many FTP archive
sites; its "home" is on oak.oakland.edu, directory @file{~ftp/pub/msdos/djgpp}.

The latest version of DJGPP is 1.11.maint5.  This version runs under
Windows 3.x.  It includes a port of gcc 2.5.7, plus support software.

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

@cindex Amiga support
For information on Amiga ports of gcc/g++, retrieve the file
@file{/pub/gnu/MicrosPorts/Amiga} from prep.ai.mit.edu, or write
to Markus M. Wild <wild@@nessie.cs.id.ethz.ch>, who I hope won't be too upset
that I mentioned his name here.

@cindex Atari ST support
A port of gcc to the Atari ST can be found on the site
``atari.archive.umich.edu'', under @file{/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.

@cindex EMX port 
@cindex gcc/2
@cindex OS/2 support

There are two different ports of gcc to OS/2, the
so-called EMX port, and a port called ``gcc/2''.
The EMX port's C library attempts to provide a Unix-like environment;
gcc/2 uses
a rather buggy port of the BSD libc.  For more information ask
around on ``comp.os.os2.programmer.misc''.  gcc/2, together with other
GNUware for OS/2, can be obtained by FTP from

@example
ftp-os2.cdrom.com(192.153.46.2) in /pub/os2/2_x/unix/gnu
ftp-os2.nmsu.edu (128.123.35.151) in /pub/os2/2_x/unix/gnu
luga.latrobe.edu.au (131.172.2.2) in /pub/os2/2_x/unix/gnu
@end example

The current maintainer of the gcc/2 port is Colin Jensen (Michael Johnson
did the original port).  His address is cjensen@@netcom.com.

Eberhard Mattes did the EMX port.  His address is
mattes@@azu.informatik.uni-stuttgart.de.

@cindex Apple support
@cindex Macintosh support
Because the legal policies of Apple threaten the long-term goals of FSF,
as well as the concept of free software, no support will be lent to
efforts to port GNU software to Macintosh or other Apple hardware.

@node 1.x vs 2.x versions, latest versions, g++ for other platforms, getting g++
@section But I can only find g++-1.42!

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

@cindex Objective-C
@cindex g++, version number
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.''

@node latest versions,  , 1.x vs 2.x versions, getting g++
@section What is the latest version of gcc, g++, and libg++?

@cindex gcc/g++, version date
The latest "2.x" version of gcc/g++ is 2.5.8, released January 23, 1994.
The latest version of libg++ is 2.5.3, released December 21, 1993.
Don't use 2.5.x, with x less than 5, for C++ code; there were some
serious bugs that didn't have easy workarounds.

For some non-Unix platforms, the latest port of gcc may be an earlier
version (2.4.5, 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.4 with gcc version 2.4.5.

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.

@node installation, User Problems, getting g++, Top
@chapter Installation Issues and Problems

@menu
* gcc-2 + g++-1::   I can't build g++ 1.x.y with gcc-2.x.y!
* what else do I need?::  OK, I've obtained gcc; what else do I need?
* use GNU linker?::  Should I use the GNU linker, or should I use "collect"?
* Use GNU assembler?::  Should I use the GNU assembler, or my vendor's
assembler?
* Use GNU C library?::  Should I use the GNU C library?
* Global constructor problems:: Global constructors aren't being called
* Strange assembler errors:: Strange assembler errors when linking C++ programs
* Problems building libg++ on 386/486::  Problems building libg++ on 386/486
* Other problems building libg++::  Other problems building libg++
* More size_t problems::        But I'm still having problems with size_t!
* Rebuild libg++?::  Rebuild libg++ to go with my new g++?
@end menu

@node gcc-2 + g++-1, what else do I need?, , installation
@section 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?''

@cindex g++, building 
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.

@cindex g++, template support
@cindex Templates
@cindex ANSI draft standard
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.

@node what else do I need?, use GNU linker?, gcc-2 + g++-1, installation
@section OK, I've obtained gcc; what else do I need?

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

@cindex GNU gas 
@cindex GNU gas [assembler]
Second, depending on your platform, you may need "gas", the GNU assembler,
or the GNU linker (see next question).

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

@node use GNU linker?, Use GNU assembler?, what else do I need?, installation
@section Should I use the GNU linker, or should I use "collect"?

@cindex Linker
@cindex System VR3, linker
@cindex System VR4, linker
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 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).

@cindex AT&T cfront
@cindex Cfront-end
@cindex collect program
@cindex GNU linker
@cindex GNU binutils
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.3, released Nov. 11, 1993.

(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:
@cindex GNU linker, advantages
@cindex GNU ld
@cindex ld [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.

If there are undefined symbols, GNU ld reports which object file(s) refer to
the undefined symbol(s).

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, which in at least some cases may
make up, in disk space, for its inability to use shared libraries.

@cindex collect linker, advantages
Advantages of collect:

@cindex Shared libraries
If your native linker supports shared libraries, you can use shared
libraries with collect.  The GNU linker does not (yet) support shared
libraries.

Note: using existing shared libraries (X and libc, for example) works
very nicely; generating shared libraries from g++-compiled code is
another matter, generally requiring OS-dependent tricks if it is
possible at all.

@cindex Shared libraries, Solaris and SVR4
Ron Guilmette has written a set of patches for the g++ compiler that
will permit people using g++ on SVr4 systems (including Solaris) to
build ELF format shared libraries.  These patches ensure that any
file scope static-storage objects within such libraries will be properly
initialized when the libraries are first attached to your running process.
These patches are for version 2.5.8.  They @emph{might} be incorporated into
the standard 2.6 distribution, but this isn't certain yet.

Contact Ron at <rfg@@netcom.com> for further information and to get the
patches.

@cindex GNU linker, porting
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.

In conclusion, I don't see a clear win for either alternative at this
point.  Take your pick.

@node Use GNU assembler?, Use GNU C library?, use GNU linker?, installation
@section Should I use the GNU assembler, or my vendor's assembler?

@cindex Assembler
@cindex GNU gas
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.

If you want to build shared libraries from gcc/g++ output and you are on
a Sun, you must @emph{not} use GNU as, as it cannot do
position-independent code correctly yet.

@node Use GNU C library?, Global constructor problems, Use GNU assembler?,
installation
@section Should I use the GNU C library?

@cindex GNU C library
@cindex libg++
At this point in time, no.  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.

@node Global constructor problems, Strange assembler errors, Use GNU C library?,
installation
@section Global constructors aren't being called

@cindex global constructors
``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?''

@cindex collect program
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
(@xref{use GNU linker?}).

@cindex constructor problems on Solaris
@cindex Solaris, constructor problems
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.

@cindex IRIX, installing collect
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

@example
make install-collect2
@end example

from the gcc source directory after installing the compiler.

@node Strange assembler errors, Problems building libg++ on 386/486, Global
constructor problems, installation
@section 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

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

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

@cindex nm program
@cindex GNU nm program
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.

@node Problems building libg++ on 386/486, Other problems building libg++,
Strange assembler errors, installation
@section Problems building libg++ on 386/486

Attempts to install libg++ on 386 or 486 systems running ports of SVR4
have problems because of bugs in debugging support on that platform.
Briefly, debugging does not currently work right yet for C++.  You
should be able to build the library successfully by deleting the @code{-g}
flag from the Makefiles (this should no longer be necessary with gcc
2.4.x although debugging still doesn't work).

See the section entitled ``Debugging on SVR4 systems.''

@node Other problems building libg++, More size_t problems, Problems building
libg++ on 386/486, installation
@section Other problems building libg++
@cindex libg++ on Ultrix
@cindex libg++ on SunOS

``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 @file{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 @code{--prefix} option to install gcc somewhere
other than @file{/usr/local}, you must use the same value for
@code{--prefix} when installing libg++, or else g++ will not be able
to find g++.

@node More size_t problems, Rebuild libg++?, Other problems building libg++,
installation
@section But I'm @emph{still} having problems with @code{size_t}!

@cindex Type of size_t
``I did all that, and I'm @emph{still} having problems with disagreeing
definitions of size_t, SIZE_TYPE, and the type of functions like
@code{strlen}.''

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

@node Rebuild libg++?,  , More size_t problems, installation
@section 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++?''

@cindex Name mangling change
@cindex Type of size_t
@cindex Incompatibilities between g++ versions
This depends; as a rule, some upgrades will require rebuilding libg++
and others will not.  Both versions 2.3.3 and 2.4.0 introduced some
incompatibilities with previous versions.  For 2.3.3, the name mangling
of certain virtual table names changed, which introduced an
incompatiblity.  For 2.4.0, the type of ``size_t'' changed on Suns
from int (as declared by the include files provided by Sun) to
unsigned long (the ANSI C and draft ANSI C++ standards declare that
size_t must be unsigned, and the GCC maintainers are now correcting
this ``bug'').

With version 2.5 of g++ and libg++, major changes were made in the way
that prototypes are provided for system functions.  Before, libg++
provided prototypes for such functions in the g++-include directory.
As of 2.5, gcc creates fixed headers suitable for both C and C++ as part
of its installation process.  You definitely need to install a new
libg++ to go with a 2.5.x release of g++.

As a rule, the first two digits of your g++ and libg++ should be the
same.

@node User Problems, legalities, installation, Top
@chapter User Problems

@menu
* 2.5.x changes in overloading:: Changes in function overloading
* Demangler:: Where can I find a demangler?
* etags for C++::   Where can I find a version of etags for C++?
* static data members::  Linker reports undefined symbols for static data
members
* placement new syntax::  g++ won't accept the placement new syntax.
* overloaded increment and decrement:: @code{operator++} and @code{operator--}
* bug reports::     I think I have found a bug in g++.
* porting to g++::  Porting programs from other compilers to g++
* name mangling::   Why does g++ mangle names differently from other C++
compilers?
* problems linking with other libraries::  Why can't g++ code link with code
from other C++ compilers?
* documentation::   What documentation exists for g++ 2.x?
* agreement with standards::  What are the differences between g++ and the ARM
specification of C++?
* compiling standard libraries::  Will g++ compile InterViews?  The NIH class
library?
* debugging on SVR4 systems::  Debugging on SVR4 systems
@end menu

@node 2.5.x changes in overloading, Demangler, , User Problems
@section gcc 2.5.x broke my code!  Changes in function overloading

``I have a program that worked just fine with older g++ versions, but as
of version 2.5.x it doesn't work anymore.  Help!''

@cindex hiding rule
While it's always possible that a new bug has been introduced into the
compiler, it's also possible that you have been relying on bugs in older
versions of g++.  For example, version 2.5.0 was the first version of
g++ to correctly implement the ``hiding rule.''  That is, if you have
an overloaded function in a base class, and in a derived class you
redefine one of the names, the other names are effectively ``hidden''.
@emph{All} the names from the baseclass need to be redefined in the
derived class.  See section 13.1 of the ARM: ``A function member of
a derived class is @emph{not} in the same scope as a function member of
the same name in a base class''.

Here's an example that is handled incorrectly by g++ versions before 2.5.0
and correctly by newer versions:

@example
class Base @{
public:
    void foo(int);
@};

class Derived : public Base @{
public:
    void foo(double);  // @emph{note that Base::foo(int) is hidden}
@};

main() @{
    Derived d;
    d.foo(2); // @emph{Derived::foo(double), not Base::foo(int), is called}
@}
@end example

@node Demangler, etags for C++, 2.5.x changes in overloading, User Problems
@section Where can I find a demangler?

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

@node etags for C++, static data members, Demangler, User Problems
@section Where can I find a version of etags for C++?

@cindex etags
The libg++ distribution contains a version of etags that works for C++
code.  Look in @file{libg++/utils}.  It's not built by default when you
install libg++, but you can cd to that directory and type

@example
make etags
@end example

after you've installed libg++.

@node static data members, placement new syntax, etags for C++, User Problems
@section Linker reports undefined symbols for static data members

@cindex 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

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

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
defined BOTH method() and bar in some source file.  According to the draft
ANSI standard, you must supply an initializer, such as

@example
int Foo::bar = 0;
@end example

@noindent
in one (and only one) source file.

@node placement new syntax, overloaded increment and decrement, static data
members, User Problems
@section g++ won't accept the placement new syntax.

``I have a program that uses the "placement syntax" of operator new,
e.g.

@example
   new (somewhere) T;
@end example

@noindent
and g++ won't accept it.''

Up until version 2.3.1, g++ accepted an alternate form of the placement
syntax, for historical reasons; use

@example
   new @{somewhere@} T;
@end example

@noindent
if you are using g++-2.2.2 or older.

@cindex g++, version 2.3.1
@cindex g++, version 2.3.2
As of 2.3.1, g++ finally fixed this, using the standard ARM syntax for
"placement new".  A few remaining glitches were fixed in 2.3.2.  The
only remaining problem is with declarators for pointers to functions;

@example
new (void (*)(int));  // confuses gcc 2.3.2
new (a) (void (*)(int)); // ditto
@end example

@cindex typedef
These can be worked around with a typedef:

@example
typedef void (*fun)(int);
new fun;
new (a) fun;
@end example

@node overloaded increment and decrement, bug reports, placement new syntax,
User Problems
@section Overloaded increment (@code{++}) and decrement (@code{--}) operators

@cindex @code{operator++}
@cindex @code{operator--}
``g++ doesn't seem to distinguish the prefix and postfix forms of
@code{operator++}.  What gives?''

This is a relatively new feature in the C++ language.  The solution is
to upgrade your compiler; distinguishing the prefix and postfix cases
of @code{operator++} and @code{operator--} was first implemented in g++ version
2.4.1.

For backward compatibility, if a class declares a prefix version of
@code{operator++} (or @code{operator--}) but no postfix version, and
code attempts to use @code{++} (or @code{--}) as a postfix operator, g++
will use the prefix version (unless the @code{-pedantic} flag is set).
This feature is to avoid breaking old code.

@node bug reports, porting to g++, overloaded increment and decrement, User
Problems
@section I think I have found a bug in g++.

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

@cindex Manual, for gcc
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.  Also provide enough code
so that the g++ maintainers can duplicate your bug.

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

@cindex g++ bug report
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.

@cindex libg++ bug report
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.

@cindex C++, reference books
@cindex ARM [Annotated C++ Ref Manual]
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 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''.

The reference manual, without annotations, also appears in Stroustrup's
"The C++ Programming Language, Second Edition" (copyright 1991, ISBN
#0-201-53992-6).  Both books are published by Addison-Wesley.

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

@node porting to g++, name mangling, bug reports, User Problems
@section 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?''

@cindex Porting to g++
First, see the questions on placement new syntax and static data members.

@cindex @code{-fansi-overloading}
Secondly, if the porting problem relates to the resolution of overloaded
operators or functions, you might try the @code{-fansi-overloading}
switch in g++ 2.5.0 or later.
This switch enables new code that attempts to match
the ARM specification of overloaded argument resolution better.

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:

@example
void func(int,int);

int i = 3;
func(i++,i++);
@end example

@cindex Order of evaluation, problems in porting
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.

@cindex Classes, problems in porting
@cindex Problems in porting, class
The second problem often happens with classes like the libg++ String
class.  Let's say I have

@example
String func1();
void func2(const char*);
@end example

and I say

@example
func2(func1());
@end example

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

@example
func2(func1().convert());
@end example

where I'm pretending I have a convert() method that is the same as the
cast.  This is unsafe, 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.

@cindex ANSI draft standard
Both the cfront and the 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++ now deletes temporaries too early, and cfront deletes temporaries
too late.

@cindex Scope, problems in porting
@cindex Problems in porting, scope
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:

@example
String& tmp = func1();
func2(tmp);
@end example

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

@node name mangling, problems linking with other libraries, porting to g++, User
Problems
@section Why does g++ mangle names differently from other C++ compilers?

See the answer to the next question.
@cindex Mangling names

@node problems linking with other libraries, documentation, name mangling, User
Problems
@section 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?''

@cindex Mangling names
@cindex Cygnus Support
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 @emph{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.
@cindex ARM [Annotated C++ Ref Manual]
@cindex Compiler differences

@node documentation, agreement with standards, problems linking with other
libraries, User Problems
@section What documentation exists for g++ 2.x?

@cindex g++, documentation
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.
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.

Postscript versions of GNU documentation in U.S. letter format
are availably by anonymous FTP to primus.com in /pub/gnu-ps.
The same, in A4 format, are on liasun3.epfl.ch in /pub/gnu/ps-doc.

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

@node agreement with standards, compiling standard libraries, documentation,
User Problems
@section What are the differences between g++ and the ARM specification of C++?

@cindex ARM [Annotated C++ Ref Manual]
The chief thing missing from g++ that is in the ARM is exceptions.
There are bits and pieces of exception code present, but it is not
presently usable.

@cindex g++, template support
@cindex Templates
The template implementation is still new.  The implementation in 2.5.x
represents a considerable improvement over that of previous releases,
but it has a long way to go.  This continues to improve from release to
release.

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.
@cindex @code{-fexternal-templates}
For 2.5.0, however, a new switch
@code{-fexternal-templates} was added; this makes it possible to have
only one globally visible copy of a given template expansion in your
executable.  See the gcc manual for details.

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

@enumerate 1
@item
Static data member templates are not supported.

@example
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
@end example

@item
Template member names are not available when defining member function
templates.

@example
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
@end example

@item
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.

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

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

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

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

@item
Member function templates are always instantiated when their containing
class is.  This is wrong.
@end enumerate

Some features that the ANSI/ISO standardization committee has voted in
that don't appear in the ARM are supported, notably the @code{mutable}
keyword, in version 2.5.x.

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

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.

@cindex @code{-fansi-overloading}
As of 2.5.0, the overloading code has been rewritten.  For now, you must
specify the option @code{-fansi-overloading} to get the new code, since
there were some important users actually depending on g++'s incorrect
resolution of ambiguities.  This switch should disappear in the future.
If a program that compiled under previous g++ versions now reports
that a use of an overloaded function is ambiguous, it is likely that the
old g++ was letting you write buggy code and the new one is detecting
the problem.  If in doubt, consult the ARM.

[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].

@node compiling standard libraries, debugging on SVR4 systems, agreement with
standards, User Problems
@section Will g++ compile InterViews?  The NIH class library?

@cindex NIH class library
@cindex NIHCL with g++
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).

[ From Steinar Bang <steinarb@@idt.unit.no>]

@cindex InterViews 3.1
@cindex gcc, version 2.3.3
@cindex libg++, version 2.3
InterViews 3.1 compiles and runs with gcc-2.3.3 and libg++-2.3, except
that the "doc" application immediately dumps core when you try to run it.  
There is also a small glitch with idraw.

There is a patch for InterViews 3.1 from Johan Garpendahl
<garp@@isy.liu.se> available for FTP from site ``ugle.unit.no''.
It is in the file

@file{/pub/X11/contrib/InterViews/g++/3.1-beta3-patch}.

This fixes two things: the Doc coredump, and the pattern menu of idraw.
Read the instructions at the start of the file.

I think that as of version 2.5.6, the standard g++ will compile the
standard 3.1 InterViews completely successfully.  I'd appreciate a
confirmation.

@node debugging on SVR4 systems,  , compiling standard libraries, User Problems
@section Debugging on SVR4 systems
@cindex System VR4, debugging

``When I use the @code{-g} flag on C++ code on a System V Release 4 system,
I get lots of undefined symbols at link time.  Why?  Help!''

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, nor is it likely to in the immediate future.

Ron Guilmette has done a great deal of work to try to get the GNU C++ com-
piler to produce DWARF format symbolic debugging information (for C++ code)
but he gave up on the project because of a lack of funding and/or interest
from the g++ user community.  If you have a strong desire to see this project
completed, contact Ron at <rfg@@netcom.com>.

@node legalities, index, User Problems, Top
@chapter What are the rules for shipping code built with g++ and libg++?
@cindex Shipping rules
@cindex GPL [GNU Public License]

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

@cindex FSF [Free Software Foundation]
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).

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.

@cindex libg++, shipping code
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.

@cindex libg++, modifying
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").

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

@quotation
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.
@end quotation

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.

To avoid coming under the influence of the LGPL, you can link with
@file{-liostream} rather than @file{-lg++}.

@node index,  , legalities, Top
@comment  node-name,  next,  previous,  up
@appendix Concept Index

@printindex cp

@page
@contents
@bye

-- 
-- Joe Buck  <jbuck@synopsys.com>
Posting from but not speaking for Synopsys, Inc.
***** Stamp out junk e-mail spamming!  If someone sends you a junk e-mail
***** ad just because you posted in comp.foo, boycott their company.
