This is the file README. It documents release 1.39.1 of the GNU C++
compiler system, still in test release status. Many bugs reported in
the previous test releases have been fixed. Some bugs surely remain. To
see the list of current issues/bugs in GNU C++, look at the file
dist-g++/ideas, or see the BugList section of the GNU C++ Users Guide.

See the file HINTS for special clues relating to GNU C++ configuration
and troubleshooting.

Introduction.

GNU C++ is GNU CC, with a C++ front end. GNU CC is the Free Software
Foundation's optimizing, retargetable, ANSI C compiler. GNU CC has
source level debugging support from the GDB debugger (also available
from the Free Software Foundation). For more information about GNU CC,
write to the Free Software Foundation at the address given below. GNU
C++ is an extension of GNU CC. It keeps the powerful optimizer, and
maintains a high degree of source-level debugging support, while
providing the object-oriented features of C++. Numerous files have been
added, changed, and hacked without mercy from their original GNU CC
incarnation to make this compiler accept a reasonable super/subset of
C++.

*Disclaimer*: GNU C++ is not perfectly compatible with AT&T C++. It is,
however, a reasonably faithful implementation of C++ as described in the
C++ reference manual. To make GNU C++ more mobile, only the files that
are not shared with GNU CC are currently being distributed. If you do
not have GNU CC yet, or your version is older than 1.39, you should take
care of getting that first. GNU CC is available to sites which have
anonymous ftp capability to prep.ai.mit.edu. Contact the Free Software
Foundation for more information.

GNU C++ is still under development, but has stabilized (hopefully) to
the point where bug fixes will not require major implementation or
reimplementation. The purpose of this distribution is to give
interested parties a chance to start working with a free C++ compiler.
It is expected (and hoped) that this compiler will continue to evolve at
a fairly rapid pace. I am hoping to receive not just bug reports, but
also code contributions, new features, and anything else that makes GNU
C++ a better compiler.

Documentation for GNU C++ does not really exist. If you would like to
write some, more power to you. What does exist is in the file
dist-g++/g++.texinfo .

GNU C++ is no longer distributed with a special debugger. The current
version of GDB needed to debug GNU C++ program is version 3.5, which can
be gotten from prep.ai.mit.edu in the usual way.

Currently, the debugger supports all of the features of the compiler,
except for: new and delete, operator forms of new and delete, user
defined type conversion, and multiple inheritance when multiple
inheritance must actually be used. The reason for these exceptions is
the degree of difficulty of their implementation. I am waiting until I
see a clean, general way of doing it. Until then, I would appreciate
any input (thoughts, caveats, source code) you would like to provide.

A name demangler has been provided by James Clark. Here is the text
from his README file:

This package contains a demangler for GNU C++ version 1.39 (November
6 version); it will probably require work for other versions.

It has *not* been extensively tested, so use with caution.

Demangling converts an encoded g++ symbol name approximately into
the form of a C++ declaration.

cplus-dem.c provides a self-contained implementation of the
demangling function cplus_demangle.

g++filt.c is a simple filter that illustrates the use of
cplus_demangle. It has a similar function to the c++filt program
provided for cfront 2.0. It filters its input replacing encoded g++
symbol names by their demangled equivalents. Anything not part of a
g++ symbol name is passed through unchanged. It can be used to
filter the output of, for example, gprof or nm.

ld.c.patch contains a rather ugly patch to ld.c (the version which
comes with g++) to make it use cplus_demangle for printing the names
of undefined symbols when a -lg++ option is given.

James Clark
[email protected]

GNU C++ was originally developed on a Sun-3 workstation, running Sun's
OS 3.5, and was migrated to a Sun-4 workstation, running Sun's OS 4.0
(Berkeley 4.2 compatible with some System V enhancements). The GNU C++
library was developed on a VAX 11/750 running BSD 4.3, and is now being
developed on a Sun-4 workstation as well. If you have machines other
than these, or any kind of machine running System V, you may experience
installation difficulties due to conditions which I cannot anticipate.
I will try to help you with problems on these machines, but my primary
goal is supporting GNU C++, and not System V (or VMS).

Installation of GNU C++. (From distribution tape)

Select the directory in your file system where GNU code usually goes. If
this is your first GNU code, then you have probably not installed GNU
CC. Please install it, and then continue with these instructions. You
also need to have bison installed. In this directory, you should have
the subdirectories

gcc-1.39/
gcc/ linked to -> gcc-1.39
gcc-test/

and possibly others. Unload the tape by using the tar command.

install% tar xvf TARFILE

where TARFILE is either the name of a tar file if you got the
distribution via ftp, or is the name of the tape device on which the
release tape is held.

Your directory tree should now contain the additional file

g++-1.39.1/

If you have specifically requested that the GNU C++ library be included
on the tape that we make for you, you will also have the directory

libg++-1.39.0/

If you got this tar file electronically instead of by tape, these
directories will come from separate tar files.

The GNU C++ library contains header files such as `stdio.h', `stream.h',
etc., which are useful when trying examples from the book. It also
contains a number of useful classes which serve both as function program
units, as well as example C++ code.

The code for GNU C++ is in the directory g++-1.39.1/. Here is how to
install GNU C++:

(0) Installation of GNU C++ assumes that you will share binaries with
GNU CC. If this is not the case, then run "make cleanconfig" after
running "make maketest".

(1) Make a directory, e.g. g++/ and `cd' into it

install% mkdir g++
install% cd g++

(2) Make symbolic links from all files in the g++-1.39.1 directory to
the current g++ directory, i.e., ln -s ../g++-1.39.1/* .

(3) Read carefully the comments at the top of the Makefile, to see what
flags, you will need to modify, if any. For example, if you have a
System V machine, you may have to uncomment the line which defines
USG_STDIO.

(4) Do a `make' of the "maketest" target in the Makefile. If your
directory structure is as described here, you need not give any
additional arguments. Otherwise, you must set DIR to the directory
which contains GNU CC sources, and TDIR to the directory which
contains GNU CC object files. The variable CDIR is the directory
for GNU CC's machine-specific files. You do not need to explicitly
give this a value unless you have moved GNU CC's "config" directory
relative to the DIR director.

The error messages about links that could not be made should be ignored.

(5) Configure the compiler for the machine target you want. This is
accomplished by running the program "config.g++". For example, on a
Sun4 running SunOS 4.0, you would type:

install% config.g++ sun4-os4

Now, You should still be in the directory g++/:

install% pwd
./g++
install%

If GAS and GNU LD work for your machine, *use them*. That will permit
you to use the system's crt0.o, including mcrt0.o and gcrt0.o which
support profiling and other features. Said another way, if you use GNU
ld and GNU as, don't use special crt0.o!

To install GAS, you should have release 1.34 or greater. Since GAS and
GNU C/C++ do not share source code, there is no need to try to match GAS
and GNU C/C++ version numbers. To install GAS in such a way that GNU
C/C++ can find it, install it as `gcc-as' wherever `gcc-cc1' and
`gcc-cc1plus' are installed. Usually this is `/usr/local/lib/gcc-as'.
Similarly install GNU LD as `gcc-ld' where `gcc-cc1' and friends are
installed, usually `/usr/local/lib/gcc-ld'.

GNU LD will not work if your system uses COFF object files. In this
case, use the `collect' program.

If neither GNU LD or `collect' works, use collect2.c. (In particular,
use it on Convex machines.) To use collect2.c, your system must support
the -r flag of ld. Edit collect2.c if necessary to tell it about your
assembler syntax, then compile it with gcc and install it as
/usr/local/lib/gcc-ld.

*Very Important* [For non-GAS users]: If you do not use GAS, GNU C++ may
need to use its own crt0.c, borrowed and modified from GNU Emacs. You
should verify that the crt0.c provided is fed suitable definitions for
correct compilation. If you have GNU Emacs, and you are not compiling
to a SUN, consult your local GNU Emacs guru, to see what sort of
#defines are required for proper operation.

In any event, at this point, just type `make':

install% make

If you are not using a SUN, you will need to use the appropriate machine
dependent files, as per GNU CC. If you do not provide a proper crt0.c,
any executable produced by GNU C++ may fail to run at all. Conversely,
if you have a program which does not make it as far as the first line in
main (), you have probably failed to provide the correct flags to the
compiler when building crt0.c.

You have now just made GNU C++. Having done that, you should now
proceed to use GNU C++ to build the GNU C++ run-time libraries, which
are in the directory dist-libg++/ . This code was contributed by Doug
Lea, and implements streams, obstacks, structured files, and other C++
public service objects. The README in that directory explains the
installation procedure for that code. Also, by making the library and
running the test programs (the Makefile in dist-libg++/ will tell you
what to do), you can verify that GNU C++ has been properly installed.

GNU ld is normally distributed with the GNU binary utilities. It is
preferable to use that for linking GNU C++ programs. However, it is
possible to link GNU C++ programs using the version of GNU ld
distributed with GNU C++ (this has been tested under SunOS 4.0 and under
SunOS 4.1.1). To install GNU ld from these sources, execute the
following command:

install% make install-ld

Installation of GDB.

GNU C++ and GDB 3.5 are intended to be compatible. GDB+ no longer
exists. Read installation instructions provided in dist-gdb.

Suggestions.

I suggest making all of the files in ../gcc/ read-only, so that when you
are making modifications to files of GNU C++, you will notice when new
ground is being broken. It also helps to know what files can be updated
from the standard GNU software without impacting GNU C++. For example,
if there is a bug fix for the file `cse.c', that same fix applies to GNU
CC and GNU C++. With both compilers pointing to the same directory via
symbolic links, one need not concern oneself with those changes.

Have fun!

Michael Tiemann

5/11/91

For more information.

For questions concerning GNU CC and GDB, the Free Software Foundation
maintains the following address:

The Free Software Foundation
675 Massachusetts Avenue
Cambridge, Mass
02139

Phone: (617) 876 - 3296

Cygnus Support provides commercial support for GNU C++ on a fixed-fee
basis. If you want support, or have support-related questions, please
contact:

Cygnus Support
814 University Avenue
Palo Alto, CA
94301

Phone: (415) 322-3811

Software from the Free Software Foundation is provided with absolutely
no warranty, to the extent permitted by applicable state law.
Redistribution of its code (source and/or executable) by MCC does not
imply that MCC offers a warranty for such code.