Merge from gcc-2.8

[pf3gnuchains/gcc-fork.git] / gcc / cp / g++FAQ.texi

\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: @(#)g++FAQ.texi     1.56 09/15/97
@c %**end of header

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

@ifinfo
@node Top, basics, (dir), (dir)
@top
@unnumbered FAQ for g++ and libg++, by Joe Buck (jbuck@@synopsys.com)
@end ifinfo

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

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 @file{http://www.cygnus.com/misc/g++FAQ_toc.html}.

This document has just been reorganized a bit.  There is some new
information about upcoming g++ releases and egcs; more needs to be done
but that will need to wait for next time.  A diff would look misleadingly
large, since I blew away and rebuilt the texinfo menus.

Please send updates and corrections to the FAQ to
@code{jbuck@@synopsys.com}.  Please do @emph{not} use me as a resource
to get your questions answered; that's what @file{gnu.g++.help} is for and I
don't have the time to support the net's use of g++.

Many FAQs, including this one, are available on the archive site
``rtfm.mit.edu''; see @*
@file{ftp://rtfm.mit.edu/pub/usenet/news.answers}.
This FAQ may be found in the subdirectory g++-FAQ.

@cindex Marshall Cline 
@cindex comp.lang.c++
@cindex C++ FAQ
This FAQ is intended to supplement, not replace, Marshall Cline's
excellent FAQ for the C++ language and for the newsgroup
@file{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
@file{ftp://rtfm.mit.edu/pub/usenet/comp.lang.c++},
or in HTML form at @file{http://www.cerfnet.com/~mpcline/On-Line-C++-FAQs/}.

@menu
* basics::                      What is g++?  How do I get it?
* installation::                How to install, installation problems
* evolution::                   The Evolution of g++
* User Problems::               Commonly reported problems and bugs
* legalities::                  Lawyer stuff, GPL, LGPL, etc.
* index::                       Index of terms

 --- The Detailed Node Listing ---

The basics: what is g++?

* latest versions::             
* g++ for Unix::                
* g++ for HP::                  
* g++ for Solaris 2.x::         
* g++ for other platforms::     
* 1.x vs 2.x versions::         

Installation Issues and Problems

* gcc-2 + g++-1::               
* what else do I need?::        
* use GNU linker?::             
* Use GNU assembler?::          
* shared libraries::            
* repository::                  
* repo bugs::                   
* Use GNU C library?::          
* Global constructor problems::  
* Strange assembler errors::    
* Other problems building libg++::  
* More size_t problems::        
* Rebuild libg++?::             
* co-existing versions::        
* Installing on Linux::         
* Linux Slackware 3.0::         

The Evolution of g++

* version 2.7.x::               
* libstdc++::                   
* new work::                    
* egcs::                        
* When?::                       

User Problems

* missing virtual table::       
* for scope::                   
* const constructor::           
* unused parameter warnings::   
* jump crosses initialization::  
* Demangler::                   
* static data members::         
* internal compiler error::     
* bug reports::                 
* porting to g++::              
* name mangling::               
* problems linking with other libraries::  
* documentation::               
* templates::                   
* undefined templates::         
* redundant templates::         
* Standard Template Library::   
* STL and string::              
* exceptions::                  
* namespaces::                  
* agreement with standards::    
* compiling standard libraries::  
* debugging on SVR4 systems::   
* debugging problems on Solaris::  
* X11 conflicts with libg++::   
* assignment to streams::       
@end menu

@node basics, installation, Top, Top
@chapter The basics: what is g++?

@cindex Free Software Foundation
@cindex GNU Public License
@cindex GPL

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 (@pxref{legalities}).

@menu
* latest versions::             
* g++ for Unix::                
* g++ for HP::                  
* g++ for Solaris 2.x::         
* g++ for other platforms::     
* 1.x vs 2.x versions::         
@end menu

@node latest versions, g++ for Unix, basics, basics
@section What is the latest version of gcc, g++, and libg++?

@cindex gcc/g++, version date
The current version of gcc/g++ is 2.7.2.3, released August 20, 1997.
Although that looks very recent, the only change is a minor patch to
resolve a problem with Linux and the GNU C library; users not interested
in that functionality have no reason to upgrade.

The current version of libg++ is 2.7.2, released July 4, 1996.
The last release of gcc/g++ with improvements to the C++ front end was
2.7.2, released Nov. 25, 1995, nearly two years ago.

I would strongly recommend that anyone using a g++ version earlier
than 2.7.2 should upgrade if at all possible (@pxref{version 2.7.x}).

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

@node g++ for Unix, g++ for HP, latest versions, basics
@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) 542-5942 or anonymous ftp file
@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'').

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

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

@cindex GNUware, anonymous FTP sites

@example
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
@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 libg++
Don't forget to retrieve libg++ as well!

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

@cindex HP Precision Architecture
@cindex Hewlett-Packard
@cindex GNU GAS 
@cindex GNU gdb

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
@file{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.

@node g++ for Solaris 2.x, g++ for other platforms, g++ for HP, basics
@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

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.

@cindex Solaris pkgadd utility
The WWW site @file{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).

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

@cindex Windows NT support
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
@file{http://www.cygnus.com/misc/gnu-win32/} on the WWW, or the
anonymous FTP directory
@file{ftp://ftp.cygnus.com/pub/gnu-win32/}.

@cindex VMS support
@cindex VAX
@cindex VMS, g++/libg++ precompiled

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
@file{ftp://mango.rsmas.miami.edu/pub/VMS-gcc/}.

@cindex OpenVMS/Alpha
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
@file{http://www.progis.de} for more details.

@cindex MS-DOS support
@cindex Delorie's gcc/g++
@cindex DJGPP
@cindex EMX
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
@file{ftp://ftp.coast.net/SimTel/vendors/djgpp/}
or, for a complete list, see
@file{http://www.delorie.com/djgpp/getting.html}.


The latest version of DJGPP is 2.00.  See
@file{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: @file{comp.os.msdos.djgpp}.

@cindex Amiga support
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
@file{http://www.ninemoons.com/}.

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

@cindex Atari ST support
A port of gcc to the Atari ST can be found at @*
@file{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
@file{comp.sys.atari.st} for more information.

@cindex EMX port 
@cindex OS/2 support

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
@file{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

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

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

@cindex Apple support
@cindex Macintosh support

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 @*
@file{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.

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

``I keep hearing people talking about g++ 2.7.2 (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 installation, evolution, basics, Top
@chapter Installation Issues and Problems

@menu
* gcc-2 + g++-1::               
* what else do I need?::        
* use GNU linker?::             
* Use GNU assembler?::          
* shared libraries::            
* repository::                  
* repo bugs::                   
* Use GNU C library?::          
* Global constructor problems::  
* Strange assembler errors::    
* Other problems building libg++::  
* More size_t problems::        
* Rebuild libg++?::             
* co-existing versions::        
* Installing on Linux::         
* Linux Slackware 3.0::         
@end menu

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

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

@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.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:
@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 (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.

@cindex collect linker, advantages
Advantages of collect:

@cindex Shared libraries
If your native linker supports shared libraries, you can use shared
libraries with collect.  This used to be a strong reason @emph{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).

@xref{shared libraries}

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

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.

@node Use GNU assembler?, shared libraries, 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.

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
@code{--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.

@node shared libraries, repository, Use GNU assembler?, installation
@section 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 @code{--enable-shared} option to the configure
program.  When compiling your own code for shared libraries you
generally
must use the @code{-fPIC} flag to get position-independent code.

@cindex -shared flag of gcc

If your shared library contains global or static objects with
constructors, then make sure to use @code{gcc -shared}, not
@code{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
@code{-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 (@pxref{use GNU linker?}).

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

@example
_GLOBAL__DI   <-- calls all module constructors
_GLOBAL__DD   <-- calls all module destructors
@end example

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

Therefore, if you make a wrapper around dlopen that looks up the
symbol @code{_GLOBAL__DI} (or @code{__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
@code{_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 @code{atexit()} that
calls all the destructors left in dynamically loaded modules.

@cindex Shared version of libg++
Check the file @file{README.SHLIB} from the libg++ distribution for more
about making and using shared libraries.

@cindex Shared libraries with HP

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
@file{ftp://ftp.cygnus.com/pub/g++/libg++-2.7.2-hppa-gcc-fix}.

@node repository, repo bugs, shared libraries, installation
@section How do I use the new repository code?

@cindex repo patch
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: @file{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.

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

After you've applied the patch, the @code{-frepo} flag will enable the
repository mechanism.  The flag works much like the existing
@code{-fno-implicit-templates} flag, except that auxiliary files, with
an @file{.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 @file{foo.C} contains template
definitions corresponding to template declarations in @file{foo.h}.

@cindex closure with repo
@cindex template closure
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.''

@node repo bugs, Use GNU C library?, repository, installation
@section Known bugs and problems with the repo patch

``The @code{-frepo} won't expand templated friend functions!''

This is a known bug; currently you'll have to explicitly instantiate
friend functions when using @code{-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

@example
-D'MESSAGE="hello there"'
@end example

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.

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

@cindex GNU C library
@cindex libg++
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.

@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
(@pxref{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.  (I'm
not certain for which versions of gcc this problem occurs, and whether
it is still present).

@node Strange assembler errors, Other problems building libg++, 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 Other problems building libg++, More size_t problems, Strange assembler errors, 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 libg++.

@cindex patch for libg++-2.6.2

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
@file{ftp://ftp.cygnus.com//pub/g++/libg++-2.6.2-fix.gz}.

@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++?, co-existing versions, 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 Incompatibilities between g++ versions

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.

@node co-existing versions, Installing on Linux, Rebuild libg++?, installation
@section I want several versions of g++ and libg++ to co-exist.

I recommend against using the @code{-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 @code{--prefix} flag when configuring gcc.  Use a
different value of @code{--prefix} for each gcc version.  Use the
same value of @code{--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 @code{--prefix} to
@file{/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
@file{/usr/local/bin/gcc} and @file{/usr/local/bin/g++}.

@node Installing on Linux, Linux Slackware 3.0, co-existing versions, installation
@section 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.''

@cindex Linux
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 @file{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 @file{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.

@node Linux Slackware 3.0,  , Installing on Linux, installation
@section Problems with g++ on Linux Slackware 3.0

@cindex Slackware
@cindex Linux Slackware
``When I try to compile the traditional Hello, world program on Linux,
the compiler can't find @file{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:

@example
ln -s /usr/lib/g++-include /usr/include/g++
@end example

@node evolution, User Problems, installation, Top
@chapter The Evolution of g++

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

@menu
* version 2.7.x::               What's changed in 2.7.x from earlier versions
* libstdc++::                   The GNU C++ standard library
* new work::                    What's been done since 2.7.x
* egcs::                        The Experimental GNU Compiler System
* When?::                       When can I get all this new stuff?
@end menu

@node version 2.7.x, libstdc++, evolution, evolution
@section What's new in version 2.7.x of gcc/g++

The current version of gcc/g++ is 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++ is 2.7.2.1, released August 14, 1996.
The current version of libg++ 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.

@cindex C++ working paper
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
@file{http://www.cygnus.com/misc/wp/} or
@file{http://www.maths.warwick.ac.uk/c++/pub/wp/html/cd2/}.
See
@file{http://www.setech.com/x3.html}
or
@file{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:

@itemize @bullet
@item
@cindex for scope
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 @code{-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.

@item
@cindex vtable duplication
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.

@item
@cindex automatic template instantiation
Support for automatic template instantiation has @emph{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 @file{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).

@item
@cindex exception handling, 2.7.0

@xref{exceptions}

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

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

@item
@cindex assignment in conditional expressions
The parsing of expressions such as @code{a ? b : c = 1}
has changed from
@code{(a ? b : c) = 1} to @code{a ? b : (c = 1)}.  This is a new C/C++
incompatibility brought to you by the ANSI/ISO standards committee.

@item
@cindex new operator keywords
The operator keywords and, and_eq, bitand, bitor, compl, not, not_eq,
or, or_eq, xor and xor_eq are now supported.  Use @code{-ansi} or
@code{-foperator-names} to enable them.

@item
@cindex explicit keyword
The @code{explicit} keyword is now supported.  @code{explicit} is used to mark
constructors and type conversion operators that should not be used
implicitly.

@item
@cindex user-defined type conversion
Handling of user-defined type conversion has been improved.

@item
@cindex explicit template instantiation
Explicit instantiation of template methods is now supported.  Also,
@code{inline template class foo<int>;}
can be used to emit only the vtable
for a template class.

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

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

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

@end itemize

@node libstdc++, new work, version 2.7.x, evolution
@section 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
(@pxref{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 (@pxref{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.

@node new work, egcs, libstdc++, evolution
@section What can we expect in future gcc releases?

A great deal of work has gone into enhancements to the C++ front end, as well
as to other aspects of the compiler.

The next major release(s) of gcc/g++ can be expected to have the following
features:

@itemize @bullet
@cindex new template implementation
@item
A completely new template implementation, much closer to the draft
standard.  Limitations in 2.7.2.x concerning inlining template functions
will be eliminated.  Static template data members, template class member
functions, partial specification, and default template arguments will be
supported.  An instantiation method resembling that used in Borland C++
(instantiating functions possibly in multiple .o files and using weak
symbols to link correctly) will be provided, in addition to other
options.  The SGI version of STL will be shipped with libstdc++ and will
compile unchanged.

@item
@cindex new exception implementation
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).

@item
@cindex RTTI
RTTI has been re-done to work correctly and is on by default.

@item
@cindex overloading
Overloading has been re-worked to conform to the latest draft of the
standard.
@end itemize

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

@node egcs, When?, new work, evolution
@section What's this I hear about egcs?

The egcs effort is a new effort to merge several threads of gcc
development and to provide a faster development process.
For more information see @file{http://www.cygnus.com/egcs/}.

@node When?,  , egcs, evolution
@section OK, when can I get this stuff?

The FSF has a policy of never announcing release dates in advance.
I'm sure this is frustrating to a lot of people, since it's taken
so long, and this frustration was one of the reasons the egcs effort
was created.  An egcs release should be expected to occur in the
very near future.   [ More on this next time ].

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

@menu
* missing virtual table::       
* for scope::                   
* const constructor::           
* unused parameter warnings::   
* jump crosses initialization::  
* Demangler::                   
* static data members::         
* internal compiler error::     
* bug reports::                 
* porting to g++::              
* name mangling::               
* problems linking with other libraries::  
* documentation::               
* templates::                   
* undefined templates::         
* redundant templates::         
* Standard Template Library::   
* STL and string::              
* exceptions::                  
* namespaces::                  
* agreement with standards::    
* compiling standard libraries::  
* debugging on SVR4 systems::   
* debugging problems on Solaris::  
* X11 conflicts with libg++::   
* assignment to streams::       
@end menu

@node missing virtual table, for scope, User Problems, User Problems
@section 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.

@node for scope, const constructor, missing virtual table, User Problems
@section gcc-2.7.0 breaks declarations in "for" statements!

@cindex declarations in for statements
@cindex for statements: declarations

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

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

In the above example, most existing C++ compilers would pass the
value 11 to the function @code{foo}.  In gcc 2.7 and in the ANSI/ISO
working paper, the scope of @code{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 @code{-fno-for-scope} that causes the old rule to be used.
@cindex -fno-for-scope

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 @code{-ffor-scope} flag under 2.7.1 and 2.7.2 gives the 2.7.0 behavior.

@node const constructor, unused parameter warnings, for scope, User Problems
@section 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.

@cindex ObjectSpace<STL>

The default constructor for the template @code{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

@example
os_pair () : first (T1 ()), second (T2 ()) @{@}
@end example

to just

@example
os_pair () @{@}
@end example

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

@node unused parameter warnings, jump crosses initialization, const constructor, User Problems
@section How to silence ``unused parameter'' warnings

@cindex -Wall
@cindex -Wunused

``When I use @code{-Wall} (or @code{-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:

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

will give a warning for the unused parameter @code{arg}.  To suppress
the warning write

@example
int Foo::bar(int) @{ return 0; @}
@end example

@node jump crosses initialization, Demangler, unused parameter warnings, User Problems
@section 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:

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

The reason is that @code{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 @code{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:

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

@node Demangler, static data members, jump crosses initialization, 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.

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

@node static data members, internal compiler error, Demangler, 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
define @emph{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 internal compiler error, bug reports, static data members, User Problems
@section 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).

@node bug reports, porting to g++, internal compiler error, 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.  See the output of the
command @code{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 @code{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.

@cindex g++ bug report
First, mail your bug report to "bug-g++@@prep.ai.mit.edu".  You may also
post to @file{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.

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

@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 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 @file{ftp://research.att.com/dist/stdc++/WP}.  For HTML and ASCII
versions, see @file{ftp://ftp.cygnus.com/pub/g++}.  On the World Wide Web, see
@file{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 @file{ftp://ftp.std.com/AW/stroustrup2e/new_iso.ps}.

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

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:

@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

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

@cindex ANSI draft standard
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.

@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, templates, 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,
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:

@itemize @bullet
@item
The libg++ distribution has a manual
@file{libg++/libg++.texi} describing the old libg++ classes, and
another manual @file{libio/iostream.texi} describing the iostreams
implementation.
@item
While there is no libg++-specific document describing the STL
implementation, SGI's web site, at @file{http://www.sgi.com/Technology/STL/},
is an excellent resource.
@end itemize

@node templates, undefined templates, documentation, User Problems
@section Problems with the template implementation

@cindex g++, template support
@cindex Templates

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 (@pxref{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).

@cindex -fno-implicit-templates
For version 2.6.0, however, a new switch @code{-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:

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

@cindex template limitations
As of version 2.6.3, there are still a few limitations in the template
implementation besides the above (thanks to Jason Merrill for this info):
These are still present in version 2.7.2, but a new implementation of
templates planned for version 2.8 will eliminate them.

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

@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 (workaround)
@end example

(still a limitation in 2.7.2)

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

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

A workaround that works in version 2.6.1 and later is to specify

@example
extern template int min (int, int);
@end example

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

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

@node undefined templates, redundant templates, templates, User Problems
@section I get undefined symbols when using templates

(Thanks to Jason Merrill for this section).

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

@file{templates.h}:
@example
template <class T>
class A @{
public:
  void f ();
  T t;
@};

template <class T> void g (T a);
@end example

@file{templates.cc}:
@example
#include "templates.h"

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

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


main.cc:
@example
#include "templates.h"

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

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

@example
template class A<int>;
template void g (A<int>);
@end example

to the bottom of @samp{templates.cc} and recompile.

@node redundant templates, Standard Template Library, undefined templates, User Problems
@section 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 @code{-fexternal-templates} nor
@code{-fno-implicit-templates} is specified.  There is a patch for
this problem at @*
@file{ftp://ftp.cygnus.com/pub/g++/gcc-2.6.3-template-fix}.

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

This bug is fixed in 2.7.0.

@node Standard Template Library, STL and string, redundant templates, User Problems
@section Does g++ support the Standard Template Library?

@cindex STL
@cindex Standard Template Library
The Standard Template Library (STL) uses many of the extensions that the
ANSI/ISO committee has made to templates, and g++ doesn't support
some of these yet.  So if you grab HP's free implementation of STL it
isn't going to work.  However, starting with libg++-2.6.2 libg++ contains a
hacked version of STL, based on work by Carsten Bormann, which permits
g++ to compile at least the containers (thanks to Per Bothner for this
text).

Actually, as of libg++ version 2.7.2 most of this works quite well, most
of the time;
I've succeeded
in making significant use of it.
Almost all of the ObjectSpace examples (a set of
over 200 simple examples of STL usage) now work.

When version 2.8.0 is out (with its complete redesign of the template
implementation) a much more complete implementation of the
STL (based on a newer free implementation from SGI) will be included.
In the meantime, 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
@file{http://www.ipmce.su/people/fbp/stl/stlport.html}.

In addition, there are several commercial suppliers of STL implementations;
ObjectSpace's version supports gcc-2.7.x.

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

@file{http://www.xraylith.wisc.edu/~khan/software/stl/STL.newbie.html}

@node STL and string, exceptions, Standard Template Library, User Problems
@section I'm having problems mixing STL and the standard string class

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 @code{<string>} header is included
before any STL headers.  That is, just say

@example
#include <string>
@end example

before any other @code{#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.

@node exceptions, namespaces, STL and string, User Problems
@section Problems and limitations with exceptions

Recent g++ versions provide limited support for exceptions.  You must
provide the @code{-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 @code{-O} flag).

You must give the @code{-frtti} switch to enable catching
of derived exception objects with handlers for the base exception class;
if @code{-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).
@emph{It still doesn't work on HP-PA or MIPS platforms.}

@node namespaces, agreement with standards, exceptions, User Problems
@section Does g++ support namespaces?

As of version 2.7.2, g++ recognizes the keywords @code{namespace} and
@code{using}, and there is some rudimentary code present, but almost
nothing connected with namespaces works yet.  It appears that this will
still be true when 2.8.0 is released.

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

@cindex ARM [Annotated C++ Ref Manual]
@cindex exceptions
As of version 2.7.0, g++ has exception support on most but not all
platforms
(no support on MIPS-based platforms yet), but
it doesn't work right if optimization is enabled, which means the
exception
implementation is still
not really ready for production use.


@cindex mutable
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.  2.6.x adds support for the built-in boolean
type @code{bool}, with constants @code{true} and @code{false}.  The
beginnings of run-time type identification are present, so there are
more reserved words: @code{typeid}, @code{static_cast},
@code{reinterpret_cast}, @code{const_cast}, and @code{dynamic_cast}.

@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.  (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].

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

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

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

@cindex InterViews
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 @code{-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.

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

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

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

@cindex DWARF debug format

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 will be available in a future release (probably 2.8.0).

@cindex stabs
@cindex --with-stabs

In the meantime, you @emph{can} get g++ debugging under SVR4 systems by
configuring gcc with the @code{--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.

@node debugging problems on Solaris, X11 conflicts with libg++, debugging on SVR4 systems, User Problems
@section 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.

@node X11 conflicts with libg++, assignment to streams, debugging problems on Solaris, User Problems
@section X11 conflicts with libg++ in definition of String
@cindex String, conflicts in definition

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

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

and remember to use the correct @code{String} or @code{XString} when
you declare things later.

@node assignment to streams,  , X11 conflicts with libg++, User Problems
@section 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 @code{cout}.  This is poor style, especially for libraries, and is
contrary to good object-oriented design.  (Libraries that write directly
to @code{cout} are less flexible, modular, and object-oriented).

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

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

@cindex assignment to cout

The original cfront implementation of iostreams by Jerry Schwarz allows
you to assign to @code{cin}, @code{cout}, @code{cerr}, and @code{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 
@code{cin}, @code{cout}, @code{cerr}, and @code{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: @code{fstream::rdbuf} is supposed to return the @emph{original}
filebuf, not the one you assigned. (This is not yet implemented in GNU
iostream.)  This must be so because @code{fstream::rdbuf} is defined to
return a @code{filebuf *}.

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

@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 and other standard classes), 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.
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
@file{-liostream} rather than @file{-lg++} (for version 2.6.x and
earlier), or @file{-lstdc++} now that it is available.  In version 2.7.0
all the standard classes are in @file{-lstdc++}; you can do the link
step with @code{c++} instead of @code{g++} to search only the
@file{-lstdc++} library and avoid the LGPL'ed code in @file{-lg++}.

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

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

@printindex cp

@page
@contents
@bye