freebsd/contrib/libg++/libg++

This is version 2.7.2 of libg++, the GNU C++ class library.
Release date June 1996 by Cygnus Support

* Please skim through this once BEFORE attempting to make and install libg++.

* You probably want to at least skim ./g++FAQ.txt.

* Contents

    * g++ source files (with their include files) are in the ./src directory
    * Some simple tests and demo programs are in ./tests
    * documentation is in ./libg++.texi.
    * A perfect hash function generator is in ./gperf.
    * Some miscellaneous files of possible interest are in ./etc
      (These files are not officially a part of the libg++ distribution,
      and are subject to arbitrary changes, deletions, etc. from release
      to release.)

* Copyright restrictions

The GNU Library General Public License (which is in the file
../COPYING.LIB) covers all libraries (specificly libg++.a) and
include files that get installed (by 'make install').

Other parts of the libg++ *distribution* that are not part the libg++
*library* per se have the GNU General Public License (which is in the
file ../COPYING).

Individual files should bear the appropriate Copyright (let us know
if you think there is a mistake).  But specificly, if your application
only uses files that are installed by the normal build+install
procedure, then it is bound by the restrictions of the GNU Library
General Public License, but not those of the GNU General Public License.

* Pre-installation

    * This version of libg++ requires gcc-2.7.2 or newer.
      It assume that gcc is responsible for fixing standard C include
      files (such as stdio.h) so that they are suitable for C++
      (Using the fixproto script that is part of gcc).

    * You can compile libg++ using a gcc that you haven't installed.
      The most convenient way to do that is to make a symlink named
      gcc in the top-level directory (i.e. libg++-2.7.2) that points to
      the directory containing the new gcc.  (You should end up with
      libg++/../gcc/xgcc being a valid filename for the uninstalled gcc.)

    * With only trivial modifications (like changing file extensions,
      etc.) most things should compile and run with any modern C++ compiler.
      However, notice that libg++ may depend on recent (ANSI/ISO) changes
      to C++.  If libg++ depends on a g++ feature that is not specified
      by the C++ draft standard *or* if there is a simple and clean
      work-around that would make it more portable, please let me know.

* Installation (see libg++.texi for more details)

    * For VMS, cd to ./vms, and read AAAREADME.TXT
      [NOTE:  The VMS support is obsolete.  We need a volunteer to fix it.]

    * For Linux, things are complicated because the Linux C library is
      based on ../libio.  Unfortunately, there is no publicly available
      version of libc that will work quite right with this release of
      libg++ and libio.

      The latest released version of libg++ for Linux is

        ftp://sunsite.unc.edu/pub/Linux/GCC/libg++-2.7.1.4.bin.tar.gz

      To use it you need to upgrade your C library to 5.2.15 or higher; the
      latest released version is

        ftp://sunsite.unc.edu/pub/Linux/GCC/libc-5.2.18.bin.tar.gz

      This release of libio will mostly work with libc 5.2.18, but a few
      things break; getopt, for instance.

      To get beta releases, you may want to join the Linux Gcc developer's
      mailing list; send mail to majordomo@vger.rutgers.edu with the text
      "subscribe linux-gcc" in the message body.

    * To build shared libraries, see README.SHLIB.

    * Make sure your sed is *not* GNU sed version 1.12.
      Most other versions (including GNU sed 1.13) should be OK.
      (It has been reported at GNU sed 3.0 fails.)

    * Go to the directory *above* libg++ (i.e.. libg++-2.7.2).

    * Run './configure' to configure the tree and create Makefiles.

	Typical example:
	./configure [SYSTEM] --prefix=/usr/gnu

	The prefix says that installation should be into
	/usr/gnu/lib, /usr/gnu/bin, etc as appropriate.

	The SYSTEM indicates what machine configuration you're
	running on.  If you don't specify it, the system can usually
	guess a default.

	IMPORTANT:  The configure options (including SYSTEM and
	--prefix) must match those used to configure gcc, otherwise
	g++ may fail to find libg++.

	See etc/cfg-paper.texi for more details.  (This paper is
	in texinfo format;  see the section below on Installing
	the Documentation on how to make it more readable.)

    * Type `make all "CC=gcc -O2"'.
	(Builds libg++.a and some other things.)  (The "CC=gcc -O2"
	is optional.  It forces use of gcc to compile C programs.
	Set CXX to specify the C++ compiler, though it defaults to gcc.)

    * Optionally, type `make check' to make and run some tests/demos of libg++.

    * Before installing, if you have an old version that was installed
	into the same directory(s), you should probably remove it.
	(There is currently no clean mechanism to do that.
	You should at least remove $(prefix)/lib/g++-include/*.h,
	where $(prefix) is by default /usr/local.)

	If the previous version was libg++ 2.4 or older, you *must* remove
	the old includes.  Prior to version 2.5, libg++ installed its own
	versions of certain standard headers for use on systems where the
	vendor headers don't include prototypes.  Versions 2.5 and later of
	gcc add prototypes to vendor headers that don't have them, so
	the libg++ versions are no longer useful, and are harmful when
	they conflict with the vendor version.

    * Type `make install'  to install 

        libg++.a          (from .)
        include files     (from src and ../libio)
        prototype files   (from src/gen)
        gperf             (from gperf)
        some other stuff

    * Install the documentation

    If you are a systems administrator installing libg++ for others,
    please make the documentation available to users!

    The libg++.texi file may be formatted as a paper document by

        * Get a copy of texinfo.tex. 
            This file defines various tex macros used in libg++.texi
            One is in the gcc release.
            You can temporarily copy it into the current directory.
        * Run tex on libg++.texi
             and do whatever you normally do from there to print it.

    It may be made into an emacs info file:

	* use the 'makeinfo' program (from the texinfo distribution).

        * Copy these files into your emacs info directory
            (normally somewhere like /usr/gnu/emacs/info).
        * If you have not done so before, edit the emacs/info/dir file
            to add a libg++ node, by inserting a line like
		
            * Libg++: (libg++).	The GNU C++ Library

            to the bottom of the file.

    * (Optional) Install, from ./utils
        g++dep (a version of mkdep that understands c++)

* Notes on compiling and running libg++/tests

It is a very good idea to also cd to the test directory and run tests
manually, to see what they do. 

Compiling and running the tests consumes a fair amount of time and
disk space!

Some reported diffs may be perfectly reasonable, owing to things like
floating point precision differences: The expected.out file was created
on a Sun4/110.

    Some tRational and tFix results depend on floating point precision
    and may generate slightly different output on different machines.

    tRandom seeds some random-numbers in a way that also relies on
    floating-point representations -- Your output should be numerically
    similar, but probably not identical.

* Changes since previous versions(s).

    See the file NEWS.

* Known bugs and problems

    * If "make install" fails with the error message:

	Static constructor test failed - see libg++.README

      this indicates an error in installing gcc.
      C++ needs special linker support beyond that needed for C, to make
      sure that static objects get initialized and destroyed properly.
      Some linkers (including the GNU linker as well as linkers for
      the Elf object file format) already provide the needed support.
      In other cases, gcc (or g++) uses the "collect2" linker driver.
      Gcc should by default do the right thing, but if you tell
      gcc to assum the GNU linker (with the --with-gnu-linker option),
      and then fail to correctly install GNU ld, you will lose.

* Lots of other information is in the libg++.texi file. It really is
  very important to actually read the documentation before using 
  library classes. Examination of the demo files in the test directory
  may also be useful. (Note however, that the demo files are merely
  designed to test examples of each class capability,
  and are not especially good examples of client functions that might
  use these classes.)

* There is now a gnu libg++ mailing list (bug-lib-g++@prep.ai.mit.edu) and
  associated usenet gnu news group (gnu.g++.lib.bug).  (It is preferred
  that messages be sent to the mailing list, rather than posted to
  newsgroup.)  To subscribe or unsubscribe to the mailing list,
  send a request to bug-lib-g++-request@prep.ai.mit.edu.

* You will be performing a valuable service if you use libg++
   classes and report back any comments, and suggestions, or bugs,
   preferably to the bug-lib-g++ list. Your feedback is extremely 
   helpful in efforts to make libg++ as useful and reliable as possible.

* We continue to solicit

  * bug reports.
  * suggestions.
  * comments.
  * questions about installing and using libg++
  * other contributions to be incorporated into libg++.
  * sample programs using libg++.

  Often, the best place to send such things is bug-lib-g++@prep.ai.mit.edu,
  although direct mail is also welcome.

* Good luck!

Doug Lea <dl@oswego.edu> designed and implemented most of the classes,
and was the original maintainer and "owner" of libg++.
He has handed over "ownership" to Cygnus Support.

Per Bothner <bothner@cygnus.com> of Cygnus Support is now
maintaining libg++, with much help from the rest of the
Cygnus G++ team (Jason Merrill, Mike Stump, Brendan Kehoe).
Cygnus Support, 1937 Landings Drive, Mountain View, CA 94043