C++ Compiler configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~ 

The Eiffel compiler is capable of generating ANSI standard C++ with a
few basic variations. In order to cope with a variety of different
C++ compilers, the interface between the Eiffel compiler and the C++
compiler is described in a configuration file.

You will only be interested in this file if:

(a) You have an unsupported C++ compiler and wish to build an interface
file for it.

(b) You want to modify the C++ compiler's options, for example, control
of optimisation or debugging code generation.



Location of configuration files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

All the configurations files supplied with the compiler are stored in
the "default" directory, and will be named to identify the C++ compiler
they are designed to interface with.

for example,

default/gnu.cfg			-- The Unix gnu compiler
default/bcc.cfg			-- Borland version 4.0
default/bcc-win.cfg			-- Borland version 4.0 with MS-Windows support

To make use of a particular file either:

(a) Copy it to "eon.cfg". This is the default file name

(b) Set the environment variable, EON_COMPILER for example,

	EON_COMPILER=gnu.cfg


What is configurable
~~~~~~~~~~~~~~~~~~~~

(a) The generated C++ code. There is only limited scope for adjustment. Special
instructions are passed to "ec2" via the -E option. These are only documented
in the various configuration files because they are intended to overcome
specific problems with a C++ compiler.

(b) The various compiler flags and switches. These are grouped in the
form of macros.

(c) The C++ compiler command line calling convention. This allows the
syntax used to call individual compiler stages. These are compiling,
library archiving and linking (some compilers have additional stages)
MSDOS systems will require the C++ compiler to be called via an
intermediate "response file". These too, can be configured.

Macros
~~~~~~

Most of the macros can be set as well as used as substitutes in the
various compiler command lines. By convention, those that *cannot*
are written in upper case. These are initialised by the Eiffel compiler.
Macros are not case sensitive and may contain the following 'escape'
characters:

%N	: newline
%T	: a tab character
%%	: the % character

The following list describes the available macros. Only predefined names 
are recognised. 


EON			:   The EON environment variable

Response file	: 	Requires a "Yes" or "No" to indicate if a response
					file is needed to call the C++ compiler
				Default: No

Unix path	: 	Requires a "Yes" or "No" to indicate if file paths
				need the Unix '/' separator or the MSDOS '\'
				Default: Unix=Yes
					    MSDOS=No

Vendor		:	The compiler vendors name
				 (Documentation only)





C compiler  	:	Compilers executable name 
					(Default: cc)
C++ compiler  	:	Compilers executable name
					(Default: cc)

Compiler flags :    Equivalent to CFLAGS in "make"
Linker flags	:	Required by the linker
Libraries		: 	The name of any additional libraries that may be needed

Cc command	:	C++ compilation command
archiver command	: Command used to run the library archiver
Ranlib command		:	Name of library post processor (if required)
Post link command	: Command to be run subsequent to the linking process


If Response files are to be used these must be defined:

Cc response		: C++ response file command processor
					(Usually the same as $(C++ compiler))
Archiver response	: The library archiver response file command
					processor (Usually the same as $(Archiver))
Linker response	: The linker response file command processor
					(Usually the same as $(Linker))
					



Leadin character	: Special character used to create the root classes
				  name

				Default: UNIX	= '_'
					    MSDOS  = '$'

C++ extension	:  	File name extension. .cc is preferred. If you
				use something else, rename the supplied C++ source
				code files in the "bibt" directory.

Header file extension :	File name extension for C++ header files

Library extension	Library file name extension
Library prefix		: Prefix for library file name

Object extension	: Object file name extension

Executable extension : Extension for the executable file

Linker output name	: Records the linker output name. Use this only in
					special cases. If the output name is not the
					executable file, this will be used when checking
					for an out of date program and when tidying up.

Ec2 flags			: Special flags given to the Eiffel compilers ec2
					phase. These control the generation of the
					certain aspects of the source code


Response file separator : Any white spaces in the response file will be
						changed to this string. The default is a
						space.


SOURCE		: Name of the current source file being compiled
				e.g. string.cc
TARGET		: Name of the current target for C++ compilation
				e.g. string.o

DEBUG KEYS	: Debug keys, taken from the system description file

MANIFESTS		: C++ command line definitions that are always required.
				These are built-in.
				
INCLUDE FLAGS	: List of include (.H) file directories.
				This list build at runtime from the cluster list

OBJECT FILES	: List of object files to be archived. This list is
				built from C++ files that have just been compiled

ROOT MODULE	: Name of the root classes stub file. This is created
				from the root class name prepended with the
				$(leadin character) macro.

CLUSTER PATH	: Path of the current cluster
				(Used to produce the library archive)
CLUSTER		: Name of the current cluster
				(Used to produce the library archive)

CLUSTER LIST	: List of additional clusters
				(Taken from the system description file)
	
	


SYSTEM NAME	: This corresponds to the Eiffel system name. It is
				equivalent to the root class name, but not
				necessarily the final executable file name

TEMPFILE		: This is the name of the temporary file created for
				the response file (if used)



Requirements of the C++ compiler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In theory all C++ compilers should be able to compile the output
code generated by the Eiffel compiler. The following lists likely
problem areas. Where extra definitions are required these can be
added to the top of "bibt/ert.H" which has a configuration section.

1. C++ source file extensions. The most convienant extension is
.cc. If your compiler can't handle this you will have to rename
a number of existing source code files. These will be in the "bibt" 
directory. C++ compilers will either accept a number of different
extensions or have a compiler command line switch.

2. Exception handling - longjmp(). Exceptions are currently handled
using C's longjmp() function. In theory C++ should support the key
word's "catch" and "throw" but so far we haven't come across a compiler
in which these are fully implemented. If your compiler does not have
longjmp(), you must undefine "#HAS_LONGJMP" in "bibt/ert.H" and live
without full exceptions. In such circumstances, an exception will
cause immediate termination of the running program.


3. Exception handling - signal(). Software signals (such as the keyboard
interrupt) are handled via the Unix signal set of functions. If your
compiler does not support these you will have to live without such
functionality.

Note: DJGPP, the MSDOS version of the Gnu C compiler has a dummy signal()
function that does nothing. 

4. The "bool" type. The latest standard for C++ includes the boolean
types "true" and "false". If your compiler does not yet have these,
you should add the definition "NEEDS_BOOL" to "bibt/ert.H"

5. Reliable signals. Most System V Unix systems will support a replacement
for the signal() function called sigset(). If you compiler does not, you
should add the following line to the top of "bibt/ert.H":

#define sigset signal

6. Smart preprocessors. The Gnu preprocessor supports the "#" operator
which can be used to provide more information to the exception backtrace.
This can be enabled with the _SMART_CPP_  if you are able to make use
of it (it is already defined for Gnu compilers).

7. Your compiler should be configured to allow case sensitivity.
If a C keyword is used in an eiffel program, it's first letter is mapped 
to upper case.

Hints on adding support for a new compiler
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. Look in in the "config/untested" directory in case there is a 
compiler configuration file available there

2. The "config/test" directory contains a number of test programs that
will check out your compiler to see if can handle some of the more
complex aspects of C++

3. If you are on MSDOS you will need to use response files, set
Response file = Yes in your .cfg file

4. You will need to create a new .cfg file. Copy an existing one and
modify it for your needs.

5. You can make use of eon's -v2 and -p options. -v2 gives you a lot
more information on how the compiler interface is being interpreted
and -p prevents files from being deleted when the have been used.
On MSDOS, therefore, you can note down the name of the response file
and run it by hand.
