diff options
Diffstat (limited to 'gcc/cp/g++FAQ.texi')
| -rwxr-xr-x | gcc/cp/g++FAQ.texi | 2423 |
1 files changed, 2423 insertions, 0 deletions
diff --git a/gcc/cp/g++FAQ.texi b/gcc/cp/g++FAQ.texi new file mode 100755 index 0000000..3cbec50 --- /dev/null +++ b/gcc/cp/g++FAQ.texi @@ -0,0 +1,2423 @@ +\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 June 8, 1998 +@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}. + +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++. If you ignore this +request your message to me may be deleted without a reply. Sorry. + +Many FAQs, including this one, are available on the archive site +``rtfm.mit.edu''; see @* +@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? +* egcs and 2.8.x:: The next generation(s) of g++ +* 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:: What are the latest versions of g++ and libraries? +* g++ for Unix:: How do I get g++ for Unix? +* getting-egcs:: How do I get egcs? +* g++ for HP:: +* g++ for Solaris 2.x:: +* g++ for other platforms:: +* 1.x vs 2.x versions:: + +The Next Generation(s) of g++ + +* new-in-2.8.x:: What's new in gcc 2.8.x? +* egcs-intro:: What is egcs? +* egcs-whats-new:: What's new in egcs vs 2.7.2? +* egcs-bug-fixes:: What was fixed in the latest egcs releases? +* egcs-linux:: If I install on Linux, will it overwrite my libraries? +* egcs-run-both:: How can I run both egcs and an FSF release? +* egcs-vs-2.8.x:: How will egcs affect 2.8.x? +* egcs-robustness:: How robust is egcs? + +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:: What's changed in 2.7.x from earlier versions +* libstdc++:: + +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, egcs and 2.8.x, 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:: What is the latest version of gcc/g++/libg++? +* g++ for Unix:: How do I get a copy of g++ for Unix? +* getting-egcs:: How do I get egcs? +* g++ for HP:: Getting g++ for the HP precision architecture +* g++ for Solaris 2.x:: Getting g++ for Solaris +* 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 egcs release + +The newest release from the egcs project (on the Web: +@file{http://www.cygnus.com/egcs/}) is egcs-1.0.3, released May 15, +1998. + +@cindex gcc/g++, version date +The current version of gcc/g++ is 2.8.1, released March 4, 1998. +This release fixes some bugs in the 2.8.x release from January. +It is a huge improvement over the 2.7.x releases. + +libg++ has now been deprecated (that is, it is no longer really +supported), so gcc2.8.1 users need to grab libstdc++-2.8.1 from +their favorite GNU site (egcs users don't need to get this separately +as it is bundled with egcs). However, there is an 'add-on' libg++ 2.8.1 +mini-release. If you want to use it, you need to combine it with +libstdc++ 2.8.1. + +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}). +Folks who need modern C++ features should upgrade to 2.8.1 or egcs. + +For some non-Unix platforms, the latest port of gcc may be an earlier +version (2.7.2, 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.7.x (for the latest x you can find) with gcc version 2.7.2.1. + +From version 2.8.0 on, you don't need libg++, you only need libstdc++ +(again, the latest version with the same two leading digits as the +version of g++ you use). + +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, g++ 1.x is only of +historical interest (since the C++ language has changed so much). + +@node g++ for Unix, getting-egcs, 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 libstdc++ +Don't forget to retrieve libstdc++ as well! + +@node getting-egcs, g++ for HP, g++ for Unix, basics +@section How do I get egcs? + +See @xref{egcs-intro} to find out what egcs is. + +You can obtain egcs either by FTP or with a Web browser. To do the +latter, start from @file{http://egcs.cygnus.com/}. The master +FTP site is @file{ftp://ftp.cygnus.com/pub/egcs/releases}, however +you'll probably get a faster download if you use a mirror site. +Mirror sites also have egcs snapshots unless otherwise noted. +@itemize @bullet +@item +US (west coast): @file{ftp://go.cygnus.com/pub/ftp.cygnus.com/egcs/} +@item +US (east coast): @file{ftp://ftp.goof.com/pub/pcg/egcs/} +or (for releases only): @file{ftp://cambridge.cygnus.com/pub/egcs/} +@item +US (Arizona): @file{ftp://ftp.ninemoons.com/pub/mirrors/egcs/} +@item +UK: @file{ftp://sunsite.doc.ic.ac.uk/Mirrors/egcs.cygnus.com/pub/egcs/} +@item +Austria: @file{ftp://gd.tuwien.ac.at/gnu/egcs} +@item +France: @file{ftp://ftp.ilog.fr/pub/mirrors/egcs/} or +@file{ftp://ftp.lip6.fr/pub/egcs} +@item +Czech Republic: @file{ftp://sunsite.mff.cuni.cz/pub/GNU/egcs/} +@item +Denmark: @file{ftp://sunsite.auc.dk/pub/egcs/} +@item +Germany @file{ftp://ftp.fu-berlin.de/unix/languages/egcs/} or +@file{ftp://ftp.gwdg.de/pub/cygnus/egcs/} +@item +Poland: @file{ftp://sunsite.icm.edu.pl/pub/programming/egcs/} +@item +Sweden: @file{ftp://ftp.sunet.se/pub/gnu/egcs/} +@item +Brasil (releases only, no snapshots): +@file{ftp://ftp.unicamp.br/pub/gnu/=EXTRA=/cygnus/egcs/} +@item +Portugal: @file{ftp://ftp.lca.uevora.pt/pub/egcs/} +@item +Romania: @file{ftp://ftp.lbi.ro/pub/egcs/} +@item +Australia/NZ (release only): @file{ftp://moshpit.cygnus.com/pub/egcs/} +@end itemize + +@node g++ for HP, g++ for Solaris 2.x, getting-egcs, 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 can obtain and install prebuilt binaries of gcc. + + +@cindex Solaris pkgadd utility +The WWW site @file{http://smc.vnet.net/} +contains various +GNU and freeware programs for Solaris 2.5 or 2.6, for either the Sparc +or Intel platforms. These are +packaged to enable easy installation using the Solaris ``pkgadd'' utility. +These include GNU emacs, gcc, gdb, perl, and others. + +You can find also find prebuilt binaries of many GNU tools, including the +compiler, at @file{http://sunsite.unc.edu/pub/solaris/}. + +@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 harrassing 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.8.1 (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 egcs and 2.8.x, installation, basics, Top +@chapter The Next Generation(s) of g++ + +@menu +* new-in-2.8.x:: What's new in gcc 2.8.x? +* egcs-intro:: What is egcs? +* egcs-whats-new:: What's new in egcs vs 2.7.2? +* egcs-bug-fixes:: What was fixed in the latest egcs releases? +* egcs-linux:: If I install on Linux, will it overwrite my libraries? +* egcs-run-both:: How can I run both egcs and an FSF release? +* egcs-vs-2.8.x:: How will egcs affect 2.8.x? +* egcs-robustness:: How robust is egcs? +@end menu + +@node new-in-2.8.x, egcs-intro, egcs and 2.8.x, egcs and 2.8.x +@section What's new in gcc/g++ 2.8.x? + +After a two-year wait, gcc 2.8.0 was released in January 1998, along +with libstdc++-2.8.0 and libg++-2.8.0. This has been followed up in +March by the 2.8.1 release of all three packages, though libg++-2.8.1 +is an "add-on" (it does not contain libstdc++ anymore). Note that +libstdc++ is required. + +For those familiar with egcs, the most obvious difference between +gcc-2.8.x and egcs is the packaging: egcs is bundled with +libstdc++, and gcc-2.8.x does not contain the class library. Otherwise, +except for the lack of the @code{-frepo} option and some bug fixes +that have not yet made it into gcc-2.8.x, C++ users will find the +two compilers to be almost the same at this stage, other than that 2.8.x +users may get more bogus warnings with -Wall and optimization because +some fixes to flow analysis in the presence of exceptions that egcs made +are not yet present in gcc 2.8.x (as of 2.8.1). + +The flow analysis problem in 2.8.1 produces bad code in some cases, not +just spurious errors. It only affects code that actually throws an +exception, and only the path corresponding to a thrown exception gets +misoptimized. If this happens, you can try reducing the level of +optimization. + +Because the new feature lists for egcs and gcc 2.8 are almost the same, +please see @xref{egcs-whats-new} for a list of new features. It is a +fairly long list. + +@node egcs-intro, egcs-whats-new, new-in-2.8.x, egcs and 2.8.x +@section What is egcs? + +egcs is the experimental GNU compiler system (see +@file{http://www.cygnus.com/egcs} on the Web). It is an effort to +accelerate development of new gcc features by providing a more open +development model than gcc has traditionally used. + +The first egcs release, egcs-1.0, came out on December 3, 1997. +The current release is egcs-1.0.3, released May 15, 1998. + +Questions not addressed here may be answered in the egcs FAQ +(@file{http://www.cygnus.com/egcs/faq.html}). + +@node egcs-whats-new, egcs-bug-fixes, egcs-intro, egcs and 2.8.x +@section What new C++ features are in egcs? + +@strong{Note}: unless indicated otherwise, these features are also +present in g++ 2.8.x. + +@itemize @bullet +@item +@cindex integrated libstdc++ + +The standard C++ classes are integrated with the egcs release (but +@strong{not} for gcc-2.8.x, which does not include the class libraries). +libg++ is not being +supported, though an add-on version that will work with egcs can be found at +@file{ftp://ftp.yggdrasil.com/private/hjl/libg++-2.8.0b6.6.tar.gz}, +thanks to H.J. Lu. The compiler and library are configured and built +in one step. + +@item +@cindex new template implementation +A completely new template implementation, much closer to the draft +standard. Limitations in 2.7.2.x concerning inlining template functions +are eliminated. Static template data members, template class member +functions, partial specification, and default template arguments are +supported. An instantiation method resembling that used in Borland C++ +(instantiating functions possibly in multiple .o files and using weak +symbols to link correctly) is provided, in addition to other +options. The SGI version of STL is shipped verbatim with libstdc++ +(libstdc++ is included with egcs, separate with gcc-2.8.x). + +@item +@cindex redundant template elimination +@cindex templates: removing redundancy +On ELF platforms (Linux/ELF, Solaris, SVR4), if the GNU linker is used, +duplicated template functions and virtual function tables are eliminated +at link time. + +@item +@cindex repository +@cindex -frepo +The @code{-frepo} flag is supported in egcs (it is not in 2.8.x). +However, because of the previous item, I don't recommend its use on ELF +systems, as the default method is better. + +@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. + +@item +There are many more changes: see @file{http://www.cygnus.com/egcs/c++features.html} for a list. +@end itemize + +Features that are still missing include namespaces and templates as +template arguments, though there is support for the latter feature +in the egcs snapshots (which has not yet made it into a release). + +@node egcs-bug-fixes, egcs-linux, egcs-whats-new, egcs and 2.8.x +@section What was fixed in the latest egcs releases? + +@itemize @bullet + +@item +Add support for Red Hat 5.0 Linux and better support for Linux +systems using glibc2. (1.0.3 was specifically done to fix some +remaining problems detected when building Red Hat 5.1). + +@item +Compatibility with both egcs-1.0 and gcc-2.8 libgcc exception handling +interfaces (see below). + +@item +Various bugfixes in the x86, hppa, mips, and rs6000/ppc backends. + +@item +A few machine independent bugfixes, mostly to fix code generation bugs +when building Linux kernels or glibc. + +@item +Fix a few critical exception handling and template bugs in the C++ +compiler. + +@item +Fix build problems on x86-solaris systems. +@end itemize + +To avoid future compatibility problems, we strongly urge anyone who is +planning on distributing shared libraries that contain C++ code to +upgrade to at least egcs-1.0.1 first (and preferably to 1.0.3). See +@file{http://www.cygnus.com/egcs/egcs-1.0.1.html} for details about the +compatibility issues as well as additional information about the +bugfixes since the egcs-1.0 release. + +@node egcs-linux, egcs-run-both, egcs-bug-fixes, egcs and 2.8.x +@section If I install egcs on Linux, will it overwrite my libraries? + +No. If you build from sources, by default, egcs installs executables in +@code{/usr/local/bin} and libraries in @code{/usr/local/lib}, and you +can change this default if desired (see next section). + +If, however, you install a package (e.g. Debian or Red Hat) that wants +to put egcs in @code{/usr/bin} and @code{/usr/lib}, then yes, you are +replacing your system compiler and C++ library (I don't know if anyone +has provided such packages yet -- proceed with caution). + +@node egcs-run-both, egcs-vs-2.8.x, egcs-linux, egcs and 2.8.x +@section How can I run both egcs and an FSF release of g++ on the same machine? + +The recommended approach is to provide a different argument to the +@code{--prefix} flag when you configure egcs. For example, say +@code{--prefix=/usr/local/egcs} and then, after installation, you +can make symbolic links from @file{/usr/local/egcs/bin} to whereever +you want, for example + +@example +ln -s /usr/local/egcs/bin/gcc /usr/local/bin/egcc +ln -s /usr/local/egcs/bin/g++ /usr/local/bin/eg++ +@end example + +@node egcs-vs-2.8.x, egcs-robustness, egcs-run-both, egcs and 2.8.x +@section What about 2.8.x? How does egcs affect the 2.8.x development? + +2.8.0 has now been released (followed up by 2.8.1), with essentially the +same C++ front end as egcs. + +Bug fixes generated in egcs will be passed to the 2.8.x releases for +inclusion; the reverse is also taking place, though a bug fix may +appear in one before it does in the other. egcs development is currently +proceeding much more quickly than gcc 2.8.x development. However, there +is essentially only one C++ front end, which is shared by the two +distinct compiler back ends (however, since egcs-1.0.3 is newer than +gcc 2.8.1, it has more bug fixes). + +@node egcs-robustness, , egcs-vs-2.8.x, egcs and 2.8.x +@section How robust is egcs? + +While the 'e' stands for 'experimental', egcs has been tested thoroughly +and should be of high quality. The author considers egcs 1.0.3 the +most robust GNU C++ compiler ever produced. + +@node installation, evolution, egcs and 2.8.x, 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.17, released April 27, 1997. +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.9.1, released May 1, 1998. + +Note that if you want to use exceptions on Intel-like platforms and use +gas (e.g. you run Linux), you need binutils version 2.8.1 or newer for +exceptions to work correctly! + +(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. + +Users of egcs or 2.8.x on ELF systems should definitely +use GNU ld (2.8 or later), as it will automatically remove duplicate +instantiations of templates, virtual function tables, or ``outlined'' +copies of inline functions. + +@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++:: +@end menu + +@node version 2.7.x, libstdc++, evolution, evolution +@section What's new in version 2.7.x of gcc/g++ + +[ This section is old now, since 2.8.x/egcs is the new stuff ] The +latest 2.7.x version was 2.7.2.2, released February 10, 1997. The only +change between 2.7.2.1 and 2.7.2.2 is that support was added for using +the GNU C library, version 2, on Linux; users not interested in that +functionality have no reason to upgrade. The previous version of +gcc/g++ was 2.7.2.1, released August 14, 1996. The libg++ version that +should be used with any 2.7.x gcc/g++ is 2.7.2, released July 4, 1996. + +Note that gcc 2.7.2.1 just consists of several small patches to +gcc-2.7.2. The release is mainly +intended to fix platform-specific bugs and does not affect the C++ +``front end'' of the compiler (the part that parses your C++ code). + +The 2.7.x releases represent a great deal of work on the part of the g++ +maintainers to fix outstanding bugs and move the compiler closer to the +current ANSI/ISO standards committee's working paper, including +supporting many of the new features that have been added to the +language. I recommend that everyone read the NEWS file contained in the +distribution (and that system administrators make the file available to +their users). I've borrowed liberally from this file here. + +@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++, , 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 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 vast 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. +Note that the SGI version of STL is the one that is included with the +egcs and 2.8.x releases of g++/libstdc++. + +@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). + +As of 2.8.x and egcs-1.0.x, the template implementation has most +of the features specified in the draft standard. Still missing are +template arguments that are themselves templates; however, template +class member functions work, and most of the limitations of the older +g++ versions are fixed. + +I think that given this new implementation, it should not be necessary +for users to mess around with switches like @code{-fno-implicit-templates} +and @code{#pragma} directives; most of the time, the default behavior +will work OK. Users of older versions might want to read on. + +@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.7.2, there are still a few limitations in the template +implementation besides the above (thanks to Jason Merrill for this info): + +@strong{Note}: these problems are eliminated in egcs and in gcc-2.8.x. + +@enumerate 1 +@item +Static data member templates are not supported in compiler versions older +than 2.8.0. 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 + +@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 (again, these problems are fixed in 2.8.0 and egcs): + +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 through 2.7.2.x 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). + +@strong{Note:} this kind of ``guiding declaration'' is not standard and +isn't supported by egcs or gcc-2.8.x, as the standard says that this +declares a ``normal'' @code{min} function which has no relation to +the template function @code{min<int>(int,int)}. But then the new +compilers have no problem inlining template functions. + +@item +Member function templates are always instantiated when their containing +class is. This is wrong (fixed in egcs/2.8). +@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? + +If you want to use the Standard Template Library, do not pass go, +upgrade immediately to gcc-2.8.x or to egcs. The new C++ front end +handles STL very well, and the high-quality implementation of STL +from SGI is included verbatim as part of the libstdc++ class library. + +If for some reason you must use 2.7.2, you can probably get by with +the hacked-up version of the old implementation from HP that is +included with libg++-2.7.2, but it is definitely inferior and has more +problems. Alternatively, g++ 2.7.2.x users might try the following: +a group at the Moscow Center for Sparc Technology has +a port of the SGI STL implementation that mostly works with gcc-2.7.2. +See +@file{http://www.ipmce.su/people/fbp/stl/stlport.html}. + +Mumit Khan has produced an ``STL newbie guide'' with lots of information +on using STL with gcc. See + +@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 section is for g++ 2.7.2.x users only ] + +This is due to a bug in g++ version 2.7.2 and 2.7.2.1; the compiler +is confused by the operator declarations. There is an easy workaround, +however; just make sure that the @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 + +The first really usable exceptions implementations are in 2.8.x and +egcs. With these versions, exceptions are enabled by default; use +-fno-exceptions to disable exceptions. + +However, 2.8.1 still has not integrated egcs work that computes an +accurate control flow graph in the presence of exceptions. For this +reason, you will sometimes get bogus warnings when compiling with 2.8.1, +-O, and -Wall, about uninitialized variables and the like. + +2.7.2.x has very limited and partially broken support for exceptions. +With that compiler, you must +provide the @code{-fhandle-exceptions} flag to enable exception +handling. In version 2.7.2 and older, exceptions may not work properly +(and you may get odd error messages when compiling) if you turn +on optimization (the @code{-O} flag). If you care about exceptions, +please upgrade to a newer compiler! + +In 2.7.2, 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.} + +Exception handling adds space overhead (the size of the executable +grows); the problem is worse on the ix86 (Intel-like) architecture +than on RISC architectures. The extra exceptions code is generated +in a separate program section and is only paged in if an exception +is thrown, so the cost is in disk, not in RAM or CPU. + +Exception overhead is much lower on ix86 if you use binutils 2.9 or +later, as gas (the GNU assembler) can now compress the information. + +@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. +The new versions (2.8.x/egcs) still lack namespace support, but to help +compile standard programs they make + +@example +using namespace std; +@end example + +a no-op. There is namespace implementation work going on in the egcs +snapshots (but it hasn't been released yet). + +@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 + +Up until recently, there was no really usable exception support. If you +need exceptions, you want gcc-2.8.x or egcs. The implementation works +fairly well. The 2.7.x version was strictly alpha quality and quite +fragile. + +@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 added support for the built-in boolean +type @code{bool}, with constants @code{true} and @code{false}. Run-time +type identification was rudimentary in 2.7.x but is fully supported in +2.8.x, 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. + +[ This paragraph obsoleted by 2.8.x/egcs: ] +One of the weakest areas of g++ other than templates is the resolution +of overloaded functions and operators in complex cases. The usual +symptom is that in a case where the ARM says that it is ambiguous which +function should be chosen, g++ chooses one (often the first one +declared). This is usually not a problem when porting C++ code from +other compilers to g++, but shows up as errors when code developed under +g++ is ported to other compilers. (I believe this is no longer a +significant problem in 2.7.0 or later). + +[A full bug list would be very long indeed, so I won't put one here; +the sheer complexity of the C++ language means that every compiler I've +tried has some problems. 2.8.x and egcs are a big improvement] + +@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'. There are two forms +of DWARF, DWARF 1 and DWARF 2. The default is often DWARF 1, which is +not really expressive enough to do C++ correctly. + +Now that we have gdb 4.17, DWARF debugging is finally supported (if +you use gcc 2.8.1 or egcs-1.0.x or newer). + +@cindex stabs +@cindex --with-stabs + +For users of older versions of the tools, 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. + +To specify DWARF 2 output on Unixware, you can give the @code{-ggdb} +switch; alternatively, @code{-gstabs} produces ``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++}. + +Note that in egcs and in gcc-2.8.x, if you do not +specify any libraries the @code{g++} command will only link in +@file{-lstdc++}, so your executable will not be affected by the LGPL +(unless you link in some other LGPLed library: the GNU C library used +on GNU/Linux systems is one such library). + +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 |