.hc 4 USER MANUAL 

.h 4.1 @{CLASSES}

@{Classes} are the building blocks of an Eiffel system. Each must be part
of a cluster and is therefore strongly related to that cluster. A @{class}
name must be unique within a cluster, however different clusters may
have @{classes} with duplicate names. This should be avoided if
possible since it is bound to end in confusion if such clusters are
used in the same system.

Each @{class} is described in a source code file with a .@{e} extension. If
the @{class} name does not match the file name, a compilation error will
result.


If the compiler is being run on a case sensitive file system ( such
as Unix) the following rules must be observed.

@{Class} names must be in upper case, failure to follow this rule will lead
to compilation errors. 

These restrictions are due to the compiler executives ability to determine
which @{classes} are required for a given system without the need for complex
@[makefile] like instructions. Such rules speed up the process of tracking
down source code files from there corresponding @{class} names.


More information about @{classes} is given in the section on CLUSTERS.



.h 5.2 ROOT @{CLASSES}

     NOT WRITTEN

.h 5.3 CLUSTERS

A cluster is a group of clusters that have some commonality. It is physically
represented by a directory that contains the source code of the @{classes} plus
other files required to make the cluster usable.

Example:

.../eon/basic/
          COMMENT        comparab.e     general.e      numeric.e
          std_files.e    any.e          core.e         in_stream.e    
          out_stream.e   string.e       array.e        file.e         
          io_stream.e    platform.e    

This directory structure shows the @[basic] cluster similar to that
shipped with Eon/Eiffel.


* The clusters name is taken from the name of the directory.

* The @{class} source code (.e files) are create and edited in the cluster
  directory.

* The cluster may be commented by including the (optional) @[COMMENT] text
  file. (SEE REF-CLUSTCOMMENT)


After the cluster has been compiled it will look something like this.
The file extensions will, of course, vary for different @{C++} compilers.

.../eon/basic/
     COMMENT        core.t         general.cc     io_stream.e    std_files.H
     ERXXX.OTD      except.H       general.e      io_stream.t    std_files.cc
     alias.dir      except.cc      general.t      out_stream.H   std_files.e
     any.H          except.e       hashable.e     out_stream.cc  std_files.t
     any.cc         except.t       in_stream.H    out_stream.e   string.H
     any.e          file.H         in_stream.cc   out_stream.t   string.cc
     any.t          file.cc        in_stream.e    platform.H     string.e
     core.H         file.e         in_stream.t    platform.cc    string.t
     core.cc        file.t         io_stream.H    platform.e
     core.e         general.H      io_stream.cc   platform.t


Not all of these are directly related to @{class} files. A cluster can
contain C or @{C++} files, although this is unusual. In this case they form
part of the Eon/Eiffel runtime system. The file types are detailed below:

 .@{e}   @{class} source code
 .@{t}   AST file produced by the Eiffel compiler
 .cc   @{C++} source code. This may me produced by the Eiffel compiler or
       may be written by the programmer
 .h    @{C++} header file associated with the corresponding .cc file
 .a    A library archive of all the object files. MSDOS users are more likely
       to see a @[.lib] extension 
 ERXXX.OTD
      Directory for .o files. There may be several of these depending on the
      type of assertions used.


If a cluster contains root @{classes}, it may look something like this

.../test/
     _test.cc 
     test.e 
     test.l 
     test.o
     test.t
     test.cc
     test.H
     libtest.a
     test

Here we have several other files added:

test.l         The system description file (Lace)
_test.cc       The programs root stub. This is generated when a root @{class} is
                compiled. It contains the C main() routine and will create the
                root object and call a creation routine. The program will run
                from this point.
test           The executable file ( MSDOS users will see test.exe)

Note that there is still a library archive even though the only @{class} is a
root. This is simply because the @{class} @[test.e] may be used by another program
as an ordinary @{class} so it must be treated as such when it is compiled.


It can be seen from this example that clusters are not just for libraries,
the @{classes} that produce executable programs are also in clusters. The above
example shows a @{class} that produces a program in a cluster that are all
called @[test]. A slightly more realistic example would be:

.../accounts/
     purchase.e
     purchase.l
     sales.e
     sales.l
     stock.e
     stock.l

This is the basis for an accounts system with three programs, @[sales], @[stock]
and purchase.


When a program's C code is compiled, the cluster directory is
specified with the compilers -I option so header files can be located. When
the program is linked, the library archive in the cluster directory is
specified.


Clusters may be created anywhere in a file system and any programs produced
need not be located in the cluster. This sort of control is given by the
system description file (@[LACE]).

A cluster directory may be created and referred to in upper or lower case. 
However, the compiler will always convert them to upper case internally.
Mixing cases in a name may lead to confusion.



MSDOS.

If a cluster name is greater than 8 characters it is still valid, and will
access a directory with the name truncated. This will, of course, give problems
if two clusters are similarly named where the first 8 characters are the
same.




.h 5.4 CLUSTER COMMENTS

A cluster may be optionally commented with the inclusion of a text file
called @[COMMENT] in the cluster directory.

The comment file will be read by the browser and documentation tools.

Lines within the file may be text read by such tools or free text. The
former begins with the standard Eiffel comments (@[--]).

Example:

  Cluster: Intrinsic
  
  -- Basic @{class} library
  -- Development only
  -- Incomplete     
          
  Manifest:    
               
  array.e 
  comparable.e 
  core.e
  file.e  
  general.e
  in_stream.e  
  integer.e    
  io_stream.e
  numeric.e
  out_stream.e
  platform.e   
  std_files.e
  string.e


.h 5.5 DATABASE


At the heart of an Eon/Eiffel system lies a database that accumulates 
information abstracted from Eiffel @{classes}. In practice the programmer
need know little about the database itself since it is self maintaining
and developing an Eiffel system needs no direct access to it.

It may, however, need to be rebuilt (if it becomes corrupted) or moved, 
and the system manager may want to specify it's location.


Since the database contains information that is in the source files, its
condition and integrity need not be a major worry. If it is lost it can
be rebuilt any time, in fact if it is missing entirely, it will be rebuilt
the next time a @{class} is compiled.


By database standards it is unlikely to become large, the information stored
is quite small. It is basically a set of balanced btree, and a Unix dbm styled
data store. It can maintain variable length fields and records and has
alternate indexes built on some of the fixed length fields.


.h 5.5.1 RELOCATING THE DATABASE

By default the Eon/Eiffel compiler uses the name @[class.edb] for the 
database and looks for it in the following place:

/usr/eon       - on Unix systems (/usr/eon/class.edb)

\eon           - on MSDOS systems (\eon\class.edb)


This default can be overridden with the environment variable @[EON].
This, in fact, moves more that the database. It controls where the
compiler looks for its configuration files and default clusters.

Example:

To relocate the database to @[/compilers/eon] use one of these commands:

EON=/compilers/eon ;; export EON         # Unix Bourne/Korn shell

setenv EON /compilers/eon               # Unix Csh

set EON=\compilers\eon                  # MSDOS



.h 5.5.2 DETERMING IF THE DATABASE HAS BECOME CORRUPTED

If a compilation is failing (or the compiler crashing) for no obvious reason
the fault may lie in the information being retrieved from the database. If
the same program has been successfully compiled before, database corruption
is the most likely caused.


There is no utility for rebuilding the database. Deleting the database
directory will cause it to be rebuilt when a @{class} is next compiled.


.hc 5.5 DEBUGGING EIFFEL CODE

Eiffel: The Language describes a number of debugging options that are
supported in Eon/Eiffel. The following are implementation notes that
should be read in conjunction to the book.

5.6.1 ASSERTIONS

Assertions control is via the system description file ELACE. At
runtime, finer control can be achieved via the EON_ASSERT environment
variable. If this variable is not defined, all the assertions that
were compiled into the code will be checked and acted up if required.

EON_ASSERT may be set to one of or a combination of the following:

e    -    ensure
r    -    require
i    -    invariant
c    -    check
l    -    loop
a    -    all
n    -    none

In the presence of EON_ASSERT only the specified conditions will be
checked. This applies to the whole system.

Example:

EON_ASSERT=erc

Here, only the pre and post conditions (@[ensure] and @[require]) and @[check]
statements are acted upon. The must, of course, have been specified in the
ELACE file.


When an assertion traps an error, a message will be generated
and the program aborted.

Example:
--------------------------------------------------------------
"ARRAY.put": Precondition failed
"inside_bounds" AND_THEN ( (lower <= index), (index <= upper))
No Traceback available.
--------------------------------------------------------------


If the program was compiled with the trace feature enabled, a traceback
will be displayed:

--------------------------------------------------------------
"ARRAY.put": Precondition failed
"inside_bounds" AND_THEN ( (lower <= index), (index <= upper))
Object     @{Class}        Routine           Arguments
--------------------------------------------------------------
0x004076f0 ARRAY        put               element="a string"
                                          index="100"
==============================================================
--------------------------------------------------------------

This shows a condition in which an array element that is outside the 
arrays limits has been written too. The traceback shows the @{class}, 
feature and parameters of the call in which the error was trapped.

The traceback is, for the most part, obvious. However the display of the
functions arguments require further examination because they show a data 
element for each @{class}. 

In the example, index=100 clearly indicates the index
element to be 100 which is of type INTEGER. The first option, 
element="a string" is (if we look at the code) of type ANY. This raises
the question of how the traceback selects a text string from the 
supplied @{class}.

The @{class} GENERAL defines a function called `out'. This returns a 
string initialised to "out - not implemented". In order to make the
traceback arguments useful, a @{class} must redefine `out' and make it
return a string that is relevent to that @{class}. For example FILE would
return the name of the file that is open. STRING would (of course) return
whatever the current object is being used for.



Trace: If the trace option has been enabled, information for a traceback
listing is accumulated. In addition a log of functions and procedures
is maintained as the they are entered and exited. By setting the
EON_TRACE environment variable, a trace is displayed at the start and
end of a procedure or function:

Example:

-------------------------------------
+++ ARRAY.make
   +++ ARRAY.resize
      +++ ARRAY.initialise
      --- ARRAY.initialise
   --- ARRAY.resize
--- ARRAY.make
-------------------------------------

The @[+++] symbol indicates that the named function has been entered. The
@[---] symbol indicates the exit point.

The environment variable EON_TRACE does not require a value, it's existence
is tested for.

setenv EON_TRACE                   Unix C shell

set EON_TRACE ;; export EON_TRACE   Unix Bourne shell

set EON_TRACE=1                    MSDOS


.h 5.6.2 RUNTIME CHECKING OF NULL ENTITIES

Under normal circumstances an attempt to access a reference object 
that has not been created will end in disaster. On Unix a segmentation
violation will occur and on DOS anything could happen.

Example:

     --------------------------
     str:STRING

     str := "DISASTER"
     --------------------------

The correct code, is more like:

     --------------------------
     str:STRING

     !!str.make
     str := "DISASTER"
     --------------------------

To prevent this unfriendly behaviour, the compiler inserts code to
abort the program in a more informative way. If possible a traceback
is given along with a description of the @{class} being abused.

This adds a small runtime overhead however the code can be removed
with the optimisation feature.


.h 5.7 EON EXECUTIVE


The main compiler stages are run from an executive program called @[eon].
This has the complicated task of taking a root @{class} and a system 
description file and compiling out-of-date dependent @{classes}. It then
goes on to produce an executable program. The programmer has various
options to control this process.


A normal compilation, in which a root @{class} is to be compiled, will 
perform the following steps:


* Read @{C++} compiler definitions file

* Locate and open the database (creating and initialising if it does not exist)

* Read the lace file for the given @{class} name

* Determine a list of out-of-date dependent @{classes}
     - check inheritance @{classes}. If an ancestor is out of date, include
       that @{class} and all descendants 
     - check generic information. Include if the @{class} has generic parameters
       and one of those is out of date
     - check supplier @{classes}

* Rebuild AST files and update database for all out-of-date dependents. This
   is done for all in before the full compilation stage. Produce .@{t} files.

* Perform @{C++} code generation from out-of-date @{classes}. If it was a supplier
   @{class} this is only necessary if the @{class} interface has changed

* Run @{C++} compiler for all required files. This is not the same as just 
   running the @{C++} stage on the out-of-data @{classes}. The task is to build
   object files from @{C++} source so if the object files have been removed or
   the @{C++} code changed, this stage still takes place. 

* Add modified object files to the library. As in the previous stage, this
   is not just a question of adding out-of-date @{classes}. Any updated object
   file is added.

* Link the final program


.h 5.7.1 COMMAND LINE OPTIONS

The basic command is a single @{class} name.

Example:
     
     eon sales
     eon SALES
     eon sales.e

     These will compile the @{class} SALES in the current directory. In each case
     the source code will be expected to be in the file @[sales.e].


The following options control the way @[eon] works and the output generated.
If no options or names are specified, a help message is displayed.


-b             Build entire cluster. This is an automatic update of each
               @{class} in a cluster. It does not compile root @{classes} and can
               be used to compile all source files regardless of their 
               dependency upon others.

               Example:

               eon -c /usr/eon/basic -b

-c pathname    Cluster name for @{class} to be compiled. If this option is not
               specified the current directory is used.

               Example:
               
               eon -c /usr/accounts sales

               This compiles the @{class} SALES in the cluster ACCOUNTS found
               by the path /usr/accounts.

-d             Describe compilation stages. This option prints a short
               message at the major points in the compilation so that 
               progress can be observed.

               Example:

               eon -d sales


-n classname   Specify non-root @{class} name. @[classname] is compiled directly
               rather than part of the compilation process of a root @{class}.
               This can be useful for syntax checking a @{class} while it is
               being developed.

               Example:

               eon -n string

               This compiles the @{class} @[string] which is not a root @{class}.
               Suppliers and ancestors of @[string] will be recompiled if
               necessary.


-p             Preserve generated C code files. If the compilation fails
               for some reason, @{C++} source files are normally deleted. If 
               the error was causes by @{C++} being unable to compile the 
               generated code, this option allows that code to be inspected.
               Beware, that when @[eon] is rerun it will think that the @{C++}
               file is up-to-date and not compile it. In such cases delete
               the @{C++} source file by hand.

-r             Rebuild the runtime system. If the runtime modules
               (eiffel_rt & tracb) have been changed, this option will compile
               the source files and add them to the appropriate library.

                    
-u directory name
               Set universe name. @[directory name] must be set to a directory
               that contains (or is able to contain) a system database. 
               This option is similar the function served by the EON
               environment variable when it is used to locate the database.
               However, the option will relocate the database only, not the
               configuration files.

               Example:

               eon -u /compiler/tmp test

               The database /compiler/tmp/class.edb is used rather than the
               main database.


-v [1-2]       Set level of verbosity. The amount of diagnostic output can be 
               configured to help diagnose problems with the compilation
               process. Level 1 is the minimum setting. Levels higher than
               2 are only really for use in the development of the compiler
               itself.


-z             Clean up cluster directory. This option will scan a cluster
               for any @{class} source code files and delete the associated files
               that were generated by the compiler. Although this option
               can be used to create more space on a full disc the files
               will probably be regenerated when a system using that
               cluster is compiled.



.h 5.7.2 CONFIGURATION

When @[eon] first runs, a number of files are read. If any of these are
unavailable, they may be created or the compilation aborted.

* The database. If a database is not found, a new one is created (after
  the programmer has been prompted to make sure this is the correct course
  of action). The database base is initialised and the the basic @{class}
  library is located and built. This may take some time so copying a fresh
  database from elsewhere is a better approach.

* The system description file (Lace). If @[eon] was run with the intention of
  compiling an executable program, a Lace file will be required. If there is
  not one matching the name of the root @{class} specified, the programmer is
  prompted and a basic file created. This contains the minimum specification
  and will almost certainly need attention.

  Example for a @{class} called `test':

 -----------------------------------
|    root                          |
|         test                     |
|                                  |
|    creation                      |
|         make                     |
|                                  |
|    generate                      |
|         executable:"test"        |
|                                  |
|    cluster                       |
|         $(EON)/basic             |
|                                  |
 -----------------------------------


* The @{C++} compiler configuration file. If this is missing, @[eon] terminates.


  
.h 5.8 SYSTEM DESCRIPTION FILES

The way in which a program is built is governed by a description file,
the syntax of which follows that of LACE as described in Eiffel: The Language.

Only a minimum subset of LACE is implemented in the current release of 
Eon/Eiffel, and so a full description follows. Future releases will see 
proper support for LACE.

For this reason we will refer to the current system as ELACE to alert
programmers to the descrepences.

ELACE files are textual and must have a @[.l] file extension. There general
syntax is as follows:

 root                                          
     <root @{class} name>

creation
     <creation procedure name>

option
        debug(<on|off>):class_name_list, ......
        trace(<on|off>):class_name_list, ......
        optimise(<on|off>):class_name_list, ......
        assertion(ensure):class_name_list, ......
        assertion(require):class_name_list, ......
        assertion(loop):class_name_list, ......
        assertion(invariant):class_name_list, ......
        assertion(on):class_name_list, ......
        assertion(off):class_name_list, ......
        assertion(none):class_name_list, ......

generate
        executable:"file_name"
        compile_with: "link_flags"
        link_with: "link_flags"

cluster
        "cluster_name"
        "cluster_name"


There are five sections as described below:

@[root]        name the root @{class} to be of the program to be compiled

@[creation]    name the creation procedure to be called in the root @{class}.
               This is a normal Eiffel creation procedure and must, therefore,
               be named in the creation clause of the root @{class}.

@[option]      specify Eiffel compilation options. These handle standard
               Eiffel debugging and efficiency controls. There are 
               implementation differences which are documented in the
               section on debugging.

@[generate]    include extra options for the @{C++} compiler and linker for
               a particular system. These are extra to those specified in
               the @{C++} compiler interface file.


@[cluster]          name clusters required by the system. These names may include
               environment variables in the form of:

               cluster
                    "$(EON)/basic"
                    "$(MYCLUSTER)/basic"
          

Example:

root
        SALES

creation
        init_sales

option
        debug(on):SALES, CUSTOMER, STOCK
        trace(on):SALES
        assertion(ensure):SALES,STOCK
        assertion(require):SALES,STOCK

generate
        executable:"$(ACCOUNTS)/bin/sales"
        link_with: "-lcposix"

cluster
        "$(EON)/basic"
        "$(ACCOUNTS)/accounts"


The examples shows part of an accounts system. A program called sales is
is compiled and saved in $(ACCOUNTS)/bin. Its root @{class} is SALES and, when
run, the first procedure called is @[init_sales]. There is debugging control
on @{classes} SALES, CUSTOMER and STOCK.


.hc 5.9 NAMING CONVENTIONS

This section describes some of the terminology that is specific to Eiffel.


.h 5.9.1 CONVENTIONS USED IN THE LANGUAGE

System:  In Eiffel terminology a @[system] refers to a group of @{classes}
         put together to produce a single executable program. Thus a
          system will have, at runtime, one or more objects. There
          is always a special object, called @[the root] that is the
          entry point into the system.

Cluster:  A cluster is a group of @{classes} that are considered to be
          related in some way. In physical terms, a cluster is a
          directory containing @{class} source files.

          Cluster names are case in-sensitive.

Universe: 
          When a system is defined it will require one or more clusters
          from which to draw @{classes}. This is said to be the universe
          for that system.

          A universe is defined in a Lace file for a given system.


@{Classes}:  All @{class} names used in Eiffel source code should be in upper case.
          Each @{class} name will relate to a source file found in a cluster
          belonging to the universe of the system being built.

          A @{class} must have a source code file in the cluster to which it
          belongs.  All @{class} source code files should have a @[.e] extension
          and be in lower case (assuming the operation system supports
          uppper and lower case).

          When a @{class} is defined, it's name must match that of the file it
          is in.

          A @{class} name can be up to to 30 characters in length, thereby 
          exceeding the maximum file name length of many operating systems.
          (MSDOS, for example, only supports file names of up to 8 characters).

          To overcome the obvious difficulties of readablilty and portability
          that such restrictions bring, a @{class} name alias feature is 
          available. This file contains a list of @{class} names and their
          associated file names.

          Example:
     
               basic/alias.dir
               --------------------------
               | LINKED_LIST  link_lst  |
               | ASCII_WINDOW awindow   |
               --------------------------
               
          LINKED LIST and ASCII_WINDOW are @{class} names and link_lst and
          awindow are their corresponding file names.

          If a @{class} name appears twice in a system a warning will be
          displayed when the system is compiled.

          Note: When a root @{class} is compiled, a stub program is produced
          which ::

variables:
          Variable names are not case sensitive.
          


.h 5.9.2 CONVENTIONS USED IN THE DOCUMENTATION

The documentation uses Unix conventions and styles. Most MSDOS @{C++} compilers
support similar conventions even if the operation system does not.


@[Path names]

     Path names given as MSDOS \ characters are converted to Unix / format
     throughout. 

     File names of greater than 8 characters will be truncated on MSDOS.

@[Environment]

     Environment variables are accessed via a $ leadin character where
     applicable:

     Example:
          $(EON)

     can be used to substitute the EON environment variable. This applies
     to MSDOS and Unix.

