	This directory contains the VMS specific files for libg++.  To 
install, you will need to have both gcc and gxx (C++) already running, and 
you must have write access to the directories that GNU_GXX_INCLUDE:[000000], 
GNU_CC:[000000] and GNU_CC_INCLUDE:[000000] point to.  If you have not figured
it out already, you must run the command file "make-l2.com" in the gcc 2.0
distribution (which creates the library gcclib2.olb), and then you should
extract all of the object modules from this library and add them to
GNU_CC:[000000]GCCLIB.OLB. If you have write access to sys$library,  then the
compiled libgxx_shr.exe will be copied there, and if you have  CMKRNL
privilege, the installation procedure will run INSTALL to make it a  known
image.  If you do not have the correct privileges or write access to 
sys$library, the compiled libgxx_shr.exe will be left in the directory  where
it was built, and the installation procedure will continue.
  The installation procedure will automatically copy all of the header
files from the directory where you unpacked the library to the appropriate
header directory (GNU_GXX_INCLUDE).  To start the installation, simply
type: 

	@VMS-INSTALL-LIBGXX

and go get a cup of coffee.  (This can be submitted to a batch queue if you 
wish).

	For one reason or another, the installation procedure may bomb on 
your system when it is running.  For this reason, I will describe the 
various steps that it takes in order to help you figure out what went wrong.

	1) A Unix filesystem is case sensitive with respect to filenames
	while VMS is not case-sensitive.  Thus String.h and string.h appear
	to be two different files under Unix, and would appear the same to 
	VMS.  Unfortunately, there are a couple of cases where two files
	differ only in the case of their names, and when you unpack libg++
	on a VMS system, you are left with two seperate versions of what
	would appear to be the same file.

	The installation procedure knows about these cases and attempts to
	rename the offending files by renaming String.h to sstring.h for 
	example.  Next the installation procedure edits any files in the
	distribution that contain references to these header files, and
	changes the include directives to refer to the new names.

	This procedure may fail if a new file is added to the distribution
	that has a name that needs to be changed, or if a current or new 
	file includes one of the existing files that was renamed.  In this
	case, you can simply hack the file VMS-INSTALL-LIBGXX.COM to handle
	these new cases.

	* Next the install procedure moves all of the header files to 
	GNU_GXX_INCLUDE.  This step is fairly robust, and the only problem
	that could occur is if you run out of disk space/quota.  If there
	are already existing files present in the directory, the install
	procedure copies the new set over the old ones, and you must purge
	the old ones by hand.


	* Finally, the install procedure will compile the source modules and
	build the library.  In addition, it will automatically move the
	support files into the required directories.  Building the library
	should take several hours.  After all of the compilation is complete
	it will	build a sharable image library, will be moved to sys$library,
	if the account you are running this from has write access 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.
$cxlink:==@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 have probably already done this.

	Once you have built the library itself, you may wish to run the test
suite that is included with libgxx.  To do this you simply need to execute
the command procedure VMS-TEST-LIBGXX.COM, which will compile and link all of the
source modules that are required to run the test.  Once again, you should
expect this to take several hours. 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.LIST	List of the executables to be run to generate EXPECTED.VMS
		Used by VMS-TEST-LIBGXX.COM to generate RUN.COM
EXPECTED.VMS	Expected output from the test suite.  Execute command file
		VMS-TEST-LIBGXX, and then the file RUN.COM that is generated, and
		compare the output to this file.
FNDVEC.C	Source file to a program that will automatically generate
		LIBGXX_VECTOR.C, the list of all of the transfer vectors.
GENCLASS.COM	Command file to generate container classes.
GENCLASS.TPU	TPU code called by GENCLASS.COM
GXX_MAIN_SHR.MAR
		This does not contain any routines, but it does contain a
		couple of psect definitions that are used by __MAIN to locate
		any global objects in the sharable libg++, and initialize them.
OPTIONS.OPT	Options file used when linking to the non-shared library.
VMS-BUILD-LIBGXX.COM
		Command file that actually does the dirty work of building the
		library.
VMS-CURSES.C	A couple of routines that are needed by the curses module
		in libg++.
VMS-GCCLIB.MAR	Source to the modified version of module GCCLIB in library
		GCCLIB.OLB
VMS-INSTALL-LIBGXX.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.
VMS-TEST-LIBGXX.COM	Command file to build the test suite and create RUN.COM
VMS_FIXINCLUDES.TPU
		This file is used to fix include directives that refer to files
		such as String.h (when there is also a string.h).

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

	1) I strongly recommend that you use the sharable library if at all
possible. (See note 4 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.  

	2) If you get warning messages from the assembler about g++ making
references to __vt.* as a routine, ignore them.  There is a bug in the g++ 
compiler, but the assembler catches them and fixes it before anything bad 
happens.

	3) You should have the proper versions of both the compiler and
assembler in order to use this version of libg++.  In addition, there may be
times when there are patches to the compiler and/or the assembler which have
not made it into the distribution version.  In the past, executables have been
made available via anonymous FTP from mango.miami.edu, which have the proper
patches.

	6) 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 idiosyncrasies that it has.  Currently the tCurses
program does not run perfectly, since the prompts do not appear on the screen.

	7) 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:[GEN] directory, and they
have extensions .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.

	In this version of libg++, there is a optional behavior that can be
selected via the /define="__OPTIMIZE__" switch on the gcc command.  Note
that this is *not* defined by default, even with /optimize (which may not be
as advertised in the preprocessor manual, but that is how most people's
compiler drivers are set up).

	Without /define="__OPTIMIZE__", most of the inline functions
definitions are skipped in the header files, and as a result function calls are
generated instead.  Naturally these functions are now present in the library,
so that the externals can be resolved (There are roughly 1500 entry points in
the library, whereas before there were only about 650.  The difference is that
all of the inlines now also have an entry point in the library). The main
advantage of doing this is that the compiler runs noticeably faster (since it
does not have to generate code for all of the inline functions).  In the case
of TFILE.CC in the [.TESTS] directory, the program compiles at *least* 2.5
times faster, and the .OBJ files are roughly a factor of two smaller.  This is,
perhaps, an extreme example, since TFILE.CC makes heavy use of inline
functions.  The intention is that program development will be made much easier,
since the compiler runs faster without the inlines, and when you wish to
compile a final version you can use the inlines for an addition
performance gain in the actual program.  This may not sound like much to some
people, but I have seen factors of two in CPU time from running the same
program with and without inlines.  (This example could be viewed as a number
cruncher)  The additional gain will have a lot to do with how many times each
function is called and so forth (i.e. your mileage may vary...). Your programs
should give identical output in either case, and if you find a situation where
you get different results with and without the __OPTIMIZE__, you have probably
discovered a bug somewhere, and it should be reported.

	Any programs that were linked to the old sharable libg++ will not work
with the new libg++, since so many things have changed.  You should 
recompile and relink any such programs.

	Also the installation procedure is more robust, and more automatic,
which should in principle mean that there will be less maintainance required
for the VMS  port.  The general idea is that in the future you will
will always have to relink any program linked to the sharable image library
each time you upgrade libg++.  The reason for this is that it is a lot of 
work trying to keep track of which entry points were used for what and so 
forth.  The fndvec.c program can keep track of some of this, but if modules 
or objects change names, then this can get thrown off.

	You *may* wish to keep the old sharable libgxx libraries, 
especially if you have programs linked to the old library.

	I have tried to make the non-sharable library more workable, by 
adding GLOBALREF and GLOBALDEF hacks where required.  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 STREAMBUF in the library. If your program uses only functions
that are inline, then the linker does not need to include STREAMBUF, without
STREAMBUF 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, just
strange runtime behavior.
	The best way to avoid this trap is to use the sharable library.  All
of the constructors for the objects in the sharable library are
*automatically* called 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 STREAMBUF from the library and force link to include it. 


								2/25/92
						Eric Youngdale
						YOUNGDALE@V6550C.NRL.NAVY.MIL


***************************************************************************
