The GNU C++ library
===================

Introduction
------------

This is a port of the GNU C++ library (version 2.7.2) for use with the
C++ programming language to the Acorn range of ARM based machines, running
under RISC OS. As such, this package is covered by the FSF General
Public License (see the files docs.COPYING and docs.COPYINGLIB for details).

This port is  1996 Nick Burrett

As with GNU programs, THERE IS NO WARRANTY OF ANY SORT


Files
-----

This distribution does not include any of the C++ source files. For these
you must retrieve them from a suitable GNU archive site listed at the end
of this document.

libgpp:h contains all the header files
libgpp:o.libg++ is the library file to link against.
!libgpp.docs.libg++ contains full instructions for this library
!libgpp.docs.!Readme is this document.

!libgpp.gen.hp and !libgpp.gen.cpp are C++ source for the generated
classes.  Please read the full library instructions for information on
how to use genclass.


Installation
------------

To install the GNU C++ library, just copy the directory !libgpp onto your
hard disc. Double clicking on !libgpp will then setup the relevant path
variables to point to !libgpp.


Before attempting to use the GNU C++ library, it should be noted that you
will need the GNU C++ compiler. A library file has not been created for
use with Acorn C++, since I do not have the package.

If you do not have a copy of GNU C++, it can be retrieved from the files
  ftp://micros.hensa.ac.uk/micros/arch/riscos/b/b013/gccmain.zip
  ftp://micros.hensa.ac.uk/micros/arch/riscos/b/b013/cc1plus.zip
and relevant mirrors.

The GNU C++ library requires:

  a) The C runtime library, UnixLib 3.7b or later.
    ftp://micros.hensa.ac.uk/micros/arch/riscos/a/a042/unixlib.arc
    or http://www.callan.demon.co.uk/unixlib


  b) The two other GNU C++ class libraries that came in this package:
       The GNU ANSI C++ Library (or LibStdc++)
       The GNU IOStream library (libio)

  c) If using the regular expression class (Regex) then you will also
     require Librx.


Using the GNU C++ library
-------------------------

In general usage, all that is needed is an extra three command line options
to G++:
  -ILibgpp: -ILibstdc: -ILibio:
and in that particular order. Rearranging the order will cause file resolving
problems between Libgpp and Libstdc.

Linking against the GNU C++ library will also mean linking against the
GNU ANSI C++ library and the GNU IOStream library, so libgpp:o.libg++,
libstdc:o.libstdc++ and libio:o.libio should be included on the linker
command line.


As an example in general use: to compile file cc.fib:
  g++ -c cc.fib -O2 -ILibgpp: -ILibstdc: -ILibio:
  drlink -o fib o.fib libgpp:o.libgpp libstdc:o.libstdc++ libio:o.libio
gcc:o.libgcc unix:o.unixlib

should be sufficient. Although adding -rescan to the drlink command line
might help resolve missing link references.

When using the class Regex, it is necessary to include Librx on
the search path with the extra command line option:
  -ILibrx:
and specify librx:o.librx on the linker command line.


Using genclass
--------------

genclass is a binary used for translating the container class prototypes
stored in the gen directory.  Full instructions can be obtained from
the libg++ main document.

Due to the filename restrictions of RISC OS resultant C++ source and header
files will be buried within sub-directories. e.g.

  For basic container classes:
     genclass base [val,ref] proto

  output will be stored in directory 'base' in the current directory,
  with filename 'proto'.
  
  e.g. genclass int val List
  generates int.h.List and int.cc.List
  
  For classes like dictionaries and maps that require two types:
    genclass -2 keytype [val,ref] basetype [val,ref] proto

  e.g. genclass -2 String ref int val VHMap
  generates String.int.h.VHMap and String.int.cc.VHMap
  
  output 'proto' will be stored in directory 'basetype' which in turn
  is located within directory 'keytype'.

Directories must also be pre-created before running genclass.
  
These inconviences are a necessity at the moment but it's quite possible
to hand edit the files as you wish.


Contacting me
-------------

I can be contacted by e-mail at: nickb@digibank.demon.co.uk

However, if there is no response from that address I can be contacted
through Simon Callan: gcc@callan.demon.co.uk.
