Dear Gentle Hacker:

	This directory contains the VMS specific files for libg++.  To install
you need to have gcc and gxx (C++) already running, and the C++ header files
must be in GNU_GXX_INCLUDE:[000000].  Assuming that you are in [.vms], the
source modules must be in [-.src]

AT THIS POINT I SHOULD WARN YOU THAT THERE WILL BE TWO VERSIONS OF FILEBUF.CC
AND FILEBUF.H.  THE REASON FOR THIS IS THAT UNIX IS CASE SENSITIVE, AND THESE
ARE ACTUALLY TWO DIFFERENT FILES.  THE FILES FOR THE OBJECT "filebuf"
SHOULD BE RENAMED TO FFILEBUF.CC AND FFILEBUF.H.   You can still use the
objects by the regular names, since C++ is case sensitive.

Once you have done this, execute the command file MAKE_LIBGXX, which will
compile all of the source modules and build the library.  After all of the
compilation is complete it will build a sharable image library, which can be
moved to sys$library.  It will also move the other files that are required by
libg++ into the GNU_CC:[000000] directory.

After this, you should define the following commands in SYLOGIN.COM:

$gxx:==gcc/plus
$genclass:==@gnu_cc:[000000]genclass
$cxlink:==@gnu_cc:[000000]cxlink	!only if using non-shared libraries.
$cxshare:==@gnu_cc:[000000]cxshare	!only if using shared libraries

Finally, make sure that GCC_INSTALL.COM is in the system startup file, 
if you have already installed C++, then you may not have to do this.

	If you wish to run the test suite that is included with libgxx, execute
the command procedure MAKE_TEST.COM, which will compile and link all of the
source modules that are required to run the test.  It will create a file
RUN.COM, which can be submitted to a batch queue, and you can compare the
output to the file EXPECTED.VMS

The files included in this directory are:

AAAREADME.TXT	This file.
CXLINK.COM	Command file to link to the non-shared library.
CXSHARE.COM	Command file to link to the shared version of the library.
EXPECTED.VMS	Expected output from the test suite.  Execute command file
		MAKE_TEST, and then the file RUN.COM that is generated, and
		compare the output to this file.
GCCLIB_VMS.MAR	Source to the modified version of module GCCLIB in library
		GCCLIB.OLB
GENCLASS.COM	Command file to generate container classes.
GENCLASS.TPU	TPU code called by GENCLASS.COM
GNULIB.C	Defines __eprintf used in assert macro.	
GSHRSTART.C	Source to program that calls global constructors.
		This version has been slightly changed from GSTART, since this
		module is designed to call the global constructors that are
		present in the sharable library.  GSTART will still call the
		constructors in the user program, even when using the
		sharable library.
GSTART.C	Source to program that calls global constructors.
GXX-STARTUP-1.MAR
		This is the 3rd variant on GXX_MAIN.  This version is used when
		using the non-shared version of the library.
GXX_MAIN.MAR
		Definition of __main, used when linking to the sharable library
		THIS MODULE DOES NOT BELONG IN THE LIBRARY ITSELF.  IT IS
		LINKED EXTERNAL TO IT, SINCE IT IS CALLING THE CODE TO
		INITIALIZE BOTH THE USER VARIABLES, AND THE LIBRARY VARIABLES.
GXX_MAIN_SHR.MAR
		When using the sharable library, this is called by GXX_MAIN.
		This in turn calls the routine GSHRSTART.  If you are using the
		non-sharable library, then this routine is never called.
		It is also present to define some PSECTS that are used by the
		linker for grouping the list of global constructors.
LIBGXX_INSTALL.COM
		This command file builds the actual library, and moves any
		assorted files required by libg++ to the correct directory.
		This is not idiot proof, so beware.  It will delete the obj's
		after it is finished, and leave behind the lib.
LIBGXX_SHR_BLD.OPT
		Option file used in the creation of the sharable library.
LIBGXX_VECTOR.MAR
		Source file to list of transfer vectors.  THIS FILE IS
		GENERATED AND AUTOMATICALLY MAINTAINED BY MACHINE.  IF YOU
		CHANGE THIS, YOU MAY GENERATE EXECUTABLES THAT ARE INCOMPATIBLE
		WITH THOSE GENERATED BY THE STANDARD LIBRARY.  This file
		contains all entry points to the library except for __MAIN and
		_GXX_VMS_STARTUP_2(Found in modules GXX_MAIN and GSTART).
MAKE_LIBGXX.COM
		Command file that actually does the dirty work of building the
		library.
MAKE_TEST.COM	Command file to build the test suite and create RUN.COM
OPTIONS.OPT	Options file used when linking to the non-shared library.
OPTIONS_SHR.OPT	Options file used when linking to the shared library.

************************************************
A few comments are in order.

	1) When I set about porting libg++ to VMS, I had to change quite
a variety of things to get it working.  I modified the assembler, and
the compiler driver.  It is a very good idea to have the latest version of
the compiler *and* the latest version of the assembler.  In addition, the
compiler should have been built with NO_DOLLAR_IN_LABEL defined in tm.h.

	2) I strongly recommend that you use the sharable library if at all
possible. (See note 5 below) This is really quite painless.  This is created by
default when you execute @LIBGXX_INSTALL.  If you want to get the optimum
performance, and you expect a lot of people to use libg++, you have the option
of installing LIBGXX_SHR.EXE. Obviously, there are no special privileges
required for the image.  Make sure that you have the most up to date version of
the compiler driver on hand, since for older versions of the compiler the
-fforce-addr switch was required to generate code compatible with sharable
libraries.  Patches to the compiler have been submitted, and I expect 
that versions later than 1-37-1 will not require this switch.

	3) Some changes and hacks needed to be made to the assembler and
compiler in order to get things working, and some of these changes are not yet
in the distribution versions.  Executables have been made available via
anonymous FTP from mango.miami.edu, and these do have the proper patches in
them.  If you are using C++ version 1-37-1 or earlier, or gcc-as version 1-36
or earlier you should get the executables from mango.
	There are several patches and they are:
	a)  C++ generates long symbol names - sometimes very long.  The VMS
linker only recognizes the first 31 characters in the name, and thus there is
great potential for two symbols conflicting.  The assembler (GCC-AS) has been
modified to solve this problem. If the name is long enough such that it cannot
be represented in 31 characters, the entire name is passed through a hashing
algorithm.  The 30 bit output is converted to a string (base 32, 0-9, A-V) of 6
characters in length.  The symbol name thus consists of the first 23 characters
of the name, an underscore, and the 5 character ASCII hash.  If the /VERBOSE
switch is used when compiling, the assembler will print out a message  for
every symbol that is truncated, giving both the old and new names for the
symbol. IF YOU DO NOT USE THIS VERSION OF THE ASSEMBLER, YOU WILL *NOT* BE ABLE
TO LINK TO THE LIBRARY.
	b) The original C++ compiler did not put the jsb c$$main_args
instruction at the entry point for main(), and an assembler hack was used to
get it in there.  This has been fixed in the C++ compiler, and thus the hack
has been removed from the assembler.  Make sure that you have compatible
versions of the assembler and compiler.  This should be called just once.
You can use ANAL/IMAGE to find the entry point, and PATCH to exam/inst at the
entry point+2 to verify that it has been called just once.
	c) The original C compiler generated code that was not really
compatible with the use of shared libraries.  It has now been patched.

	4) If you are using the non-shared version of the library,  it is
possible to get strange results (usually access violations) when attempting to
use cout or cin (perhaps others as well). The reason for this is that cout is
defined in module OSTREAM in the library. If your program uses only functions
that are inline, then the linker does not need to include OSTREAM, without
OSTREAM there is no constructor for cout in the list of global constructors,
and thus there is no call made to the constructor. The result is an
uninitialized variable.  You will not get any compiler or linker errors.
	The best way to avoid this trap is to use the sharable library.  All
of the global variable in the sharable library are *automatically* initialized
by constructors whether you use them or not.
	A second way to get around this is to call an ostream function that
is *NOT* an inline function, i.e.

ostream junk("nla0:");

or to extract the module OSTREAM from the library and force link to include it. 
(This is one reason to use the shared library).
	
	5)  In order to get buffered I/O working in libg++, I had to hack the
Filebuf object a bit.  In particular, it is now impossible to use the same
Filebuf object for input and output (I am not really sure that it was possible
to begin with anyway).  There are two little bits of weirdness that I have
encountered: first, when you are prompting for information from the terminal,
the last character is not printed.  After you enter the information, *then*
the character appears.  Secondly, when executing in a batch file, the output
written to cout starts on a new line after a read from cin.

	6) There is something very weird going on with the debugger.
Some programs work fine, just like with GNU-C, and some programs the debugger
loses all track of where it should be.  Sometimes instead of printing the
source line, it prints gobs and gobs of question marks, gives an error message
about reading past end of file, and sometimes the debugger crashes,
and sometimes goes into an infinite loop of error messages.  You cannot
control-Y out of it.  The best recourse is to type "EXIT" while it is printing
this crap, although sometimes I have been able to get it to stop temporarily
by typing some control letters (keep trying things until you get the DCL
prompt.  If you do not EXIT, it goes back to printing messages).

	7) As far as I can tell the curses module works, however I am no expert
on curses.  If someone finds something that does not seem to work quite right
let me know.  Keep in mind that you are interfacing to VAXCCURSES, and you are
stuck with all of the ideosynchrosies that it has.

	8) In chapter 6 of the libg++ manual there is a description of what
are called the "container class prototypes".  These are classes that can be
made for any type of data object.  The way that this is done now, is to
use a simple text substitution to fill in data types where required.  The
prototype files are in the GNU_GXX_INCLUDE:[000000] directory, and they
have exensions .HP and .CCP.  The GENCLASS command can be used to generate
the classes, where GENCLASS is defined as:

$genclass:==@gnu_cc:[000000]genclass

The command syntax is identical to that given in the libg++ manual (except that
the data type should be quoted).  If there is one data type, then the syntax is:

$genclass "var" mode class

where var is the data type (quoted to preserve case). mode is either REF or
VAL, and class is the name of the container class.  For a class with two data
types, the syntax is 

$genclass -2 "var1" mode1 "var2" mode2 class

GENCLASS puts the output files in the current default directory.


								6/25/90
						Eric Youngdale
						YOUNGDALE@V6550C.NRL.NAVY.MIL
