








            ET++ Installation Notes (April 1989)





This is the first public domain distribution  of  ET++.  The
distribution is organized hierarchically as follows:

et
  .cshrc         example profile (mandatory environment variables)
  CSHRC          same as above
  C++            patches to AT&T's cfront 1.2.1
  src            source code of ET++ class library
    MALLOC       extended malloc
    SUNWINDOW    interface for SunView/SunWindows
    SERVER       a window server running under SunView
    XSERVER      interface for X11.3(beta)
    NEWS         interface for the NeWS window system (experimental)
    PIC          interface for producing pic output (experimental)
    POSTSCRIPT   interface for producing postscript output
    SUNOS        interface for SUNOS
    PROGENV      ET++'s programming environment
    images       bitmap images
  applications   example applications developed with ET++
  postscript     postscript libraries
  doc            this installation guide
                 ET++ - Introduction Paper
                 GNU's regular expressions syntax
  fonts          fonts for SunView
  xfonts         fonts for X11
  bin            utility programs for ET++
  bin.68020      binaries of ET++ example programs for SUNOS 4.0
  dyn.68020      *.o files for dynamic loading/linking with "app"
  util
    makedep      public domain makefile dependency generator
    patch        public domain utility for applying patches
  lib            a fixed version of libc.a for SunOS 4.0(EXPORT)


1.  Hardware and Software Requirements

About 16 MBytes of disk space are required to install  ET++.
ET++  currently  runs  on  SUN-2 and SUN-3 architectures. In
order to run ET++ on a SUN-4 support for  variable  argument
lists  has  to  be implemented for C++ on this architecture.
The standard definition of <varargs.h> cannot be  used  with
function prototypes as found in ANSI C or C++. ET++ uses the
<stdarg.h> interface distributed with  cfront  for  handling
variable  argument lists.  Until now running ET++ on a SUN-4
has never been tried out.



                        May 24, 1989





                           - 2 -


ET++ applications run on color screens but the current  ver-
sion does not support colors.

ET++ runs under the SunOS releases 3.4, 3.5, 4.0 and  4.0.1.
There are some problems under 4.0 due to a bug that is fixed
in 4.0.1. The symptom of this bug is that an  ET++  applica-
tion  can only be executed once. Attempts to start an appli-
cation a second time fail with a strange core dump. To over-
come  this  bug  link all ET++ applications static (->etld).
SunOS 4.0(EXPORT) has another bug  buried  in  libc.a  which
does not allow to statically link applications. A fixed ver-
sion  of  libc.a  for  SunOS  4.0(EXPORT)  is  included   in
lib/libc.a.

ET++ currently supports the following window systems:

-    SunView (the primary ET++ development environment)

-    X11.3(beta)

-    NeWS 1.1 (support for NeWS is not completely finished)

The ET++ collection classes are  window  system  independent
and can be used on all platforms.

ET++ was developed with "cfront 1.2.1 2/16/87". In order  to
compile  ET++  with this version of cfront some bugs have to
be fixed. The corresponding patches are  shipped  with  this
distribution.

     Notice:  These bug fixes require the  source  code
     for cfront 1.2.1

An attempt to compile ET++ with a beta version of the Oregon
C++ compiler was not successful.

2.  Installation Procedure

The ET++ software is location independent, e.g.  it  can  be
installed at any place in the file system. Choose the direc-
tory where ET++ should be  installed,  for  example  /local.
Extract the files:

        tar -xvfb /dev/rst0 126

The standard location for ET++ is /local/et. If the standard
location  is not used the environment variable ET DIR has to
be set accordingly. For example, if  ET++  is  installed  in
/home/oolibs/et,  ET DIR  has  to be set to /home/oolibs/et.
The installation directory is referred to as ET DIR  in  the
following explanations.

If you are running SunOS 4.0 or 4.0.1  on  a  SUN3  you  are
ready  to  experiment with some ET++ applications located in



                        May 24, 1989





                           - 3 -


ET DIR/bin.68020.  Before  starting   an   application   the
environment  variable  ET DIR  has  to  be  set as described
above.  These ET++ applications were compiled to include the
ET++  programming environment. Refer to the section entitled
The Built-in  Programming  Environment  in  the  paper  ET++
Introduction  for  a  description on how to invoke it and to
get some information about its functionality.  The  applica-
tions run under SunView and X11.

2.1.  Applying the Patches to cfront

If  you  are  using  cfront  1.2.1  apply  the  patches   in
cfront.patch  stored  in  ET DIR/C++. A version of the patch
program is included in the directory ET DIR/util/patch.

Install the CC driver shell script.   The  standard  CC  for
cfront  1.2.1  was modified to call nm during munch with the
-p option in order give some control over the calling  order
of  static  constructors.  Standard  CC calls nm without any
option. The other modification was the additional definition
of the symbol   COMPILEDIR   to refer to the pathname of the
current  directory.    COMPILEDIR    is  only  used  by  the
browser  of  the  ET++ programming environment to locate the
source code of a class. If not  set  by  CC  the  symbol  is
defined  as  "" and the environment variable ET SRC PATH can
be used to specify a list of search paths for source files.

2.2.  Edit ET DIR/src/Types.h

If your C++ compiler uses ANSI C as the underlying C defini-
tion modify the token concatenating macros  NAME1 ,  NAME2 ,
 NAME3  to use the ANSI C string concatenation operator ##.

2.3.  Configuring the ET++ library in ET DIR/src/makefile

Edit the macros MUNCH and LIBCC to match the location of the
munch  part  and  the  standard library of C++. The makefile
builds a local copy of the standard  C++  library  (libC2.a)
with  files   dtor.o  and  ctor.o removed. This is necessary
for optimizing the link step (->see 2.6).

ET++ class library includes support  for  several  different
window   systems  and  printing  devices.  The  makefile  in
ET DIR/C++/src includes under the  section  entitled  confi-
guration  some  macros to tailor ET++ to a specific environ-
ment.


2.3.1.  Selecting the Window System Interfaces

By  default  all  supported  window  system  interfaces  are
included.  This  allows an application linked with this ver-
sion of the library to run on all  these  platforms  without
any recompiling.



                        May 24, 1989





                           - 4 -



        WS OFILES       =   $(SUNSERVER) $(NEWSSERVER) $(XSERVER) $(SUNWINDOW)
        WS IFDEFS       =   -DWS SUNSERVER -DWS NEWS -DWS X -DWS SUNWINDOW
        WS DIRS         =   SUN XSERVER SERVER NEWS

To remove a window system interface, delete the  correspond-
ing entry from these lines. The macro names stand for:

SUNSERVER    interface to a server for the sunwindow system
NEWSSERVER   interface for NeWS 1.1, this interface is only experimental
XSERVER      interface for X11.3(BETA)
SUNWINDOW    interface for sunwindow/sunview

The following example shows the definition of the macros for
a version of ET++ which includes only the X interface

        WS OFILES       =   $(XSERVER)
        WS IFDEFS       =   -DWS X
        WS DIRS         =   XSERVER


2.3.2.  Selecting the Printers

ET++ supports generating either postscript or pic output. By
default  both  formats  are  included.  To  remove a printer
interface, adapt the macros as described above.

        PR OFILES       =   $(POSTSCRIPT) $(PIC)
        PR IFDEFS       =   -DPR POSTSCRIPT -DPR PIC
        PR DIRS         =   POSTSCRIPT PIC


2.3.3.  Operating System Interface

Currently, only an interface for SUNOS is supported.

2.3.4.  Programming Environment

By default the ET++  library  and  therefore  all  the  ET++
applications  linked  with it include a programming environ-
ment (an inspector, and a browser). These tools add 30KB  to
an  ET++  application but have no influence on the execution
speed. In order to remove this inspecting and browsing  code
in  a  final  version of an application modify the macros as
shown below:

        PE OFILES       =  # $(ET PROGENV)
        PE IFDEFS       =  # -DET PROGENV
        PE DIRS         =  # PROGENV

Recompile the class library with make config and relink your
application.   make config should be called whenever the PE
or the WS  macros are changed.




                        May 24, 1989





                           - 5 -


2.4.  Adapting ET DIR/src/order

The file order has been introduced to solve the  problem  of
the      correct      calling      order      for     static
constructors/destructors. Order contains a  list  of  object
file  names  with static constructors. The constructors will
be called in the reverse order specified in the file.  Order
has  to  include the pathname to the standard C++ library in
order to call its static constructors. The absolute pathname
to  the  standard C++ library has to be adapted according to
your local configuration:

        ...
        Set.o
        ObjArray.o
        /local/lib/libC.a <-
        Storage.o


2.5.  Building the ET++ Library

The ET++ classes are built by running  make  in  ET DIR/src.
This  step  will  take around 40 minutes on a SUN 3/260. The
output of this step is not an  archive  including  the  ET++
object  files  but  a  relocatable object file with the name
et.o. Experience has shown  that  this  approach  speeds  up
linking  of  an ET++ application. An ET++ application linked
with an archive is not significantly smaller than an  appli-
cation  linked with a relocatable object file containing all
the object files.

With the command make col you may build a library  including
the ET++ collections without any graphical and window system
dependent classes.


2.6.  Adapting etld

The shell script etld has been introduced to optimize  link-
ing  for the AT&T implementation of C++ on BSD systems. Etld
avoids linking an application twice in order to find out all
the  static  constructors/destructors.  The idea is to cache
all the static constructors/destructors from et.o in a  file
et.ctdt and to merge those with the constructors/destructors
found in the application object files. The shell  script  is
stored  in ET DIR/bin. The macros described below have to be
adapted.

STATIC OPT
specifies the options to be  used  when  an  application  is
statically linked.

For SUNOS 4.0(EXPORT):




                        May 24, 1989





                           - 6 -



        STATIC OPT="-Bstatic -L${ET DIR}/lib"

For SUNOS 4.0 or SUNOS 4.0.1:

        STATIC OPT="-Bstatic"

MUNCH
specifies the location of munch

LIBS
lists additional libraries to be linked

For SUNOS 3.4, 3.5 (without shared libraries)

        LIBS="-lm -lC"

For SUNOS 4.0 and above, if  ET++  has  been  configured  to
include an interface to SunWindow/SunView. The shared window
libraries have to be listed in addition to -lm and -lC:

        LIBS="-lsuntool -lsunwindow -lpixrect -lm -lC"


2.7.  Compiling the Fonts for X11

The ET++ distribution includes fonts for X11 in snf and  bdf
format.  The snf fonts were generated for SUN3 architectures
and have to be regenerated for other environments  from  the
bdf  descriptions.  In  order to compile the fonts adapt the
makefile in ET DIR/xfonts. FC has to be defined to refer  to
the X11 font compiler.

2.8.  Compiling the ET++ Example Applications

After step 2.7 you are  ready  to  build  the  ET++  example
applications.  They  are  compiled  by  calling  make in the
directory ET DIR/applications.  More information about these
example applications can be found in "ET++ Introduction"

2.9.  Compiling ET++ Support Applications

The directory ET DIR/src contains the source code  for  some
additional  ET++ applications. A window server running under
SunView can be compiled with make  server.  This  server  is
only useful if the ET++ applications include the correspond-
ing window system interface, e.g. by compiling them  with  a
version  of  the  ET++  library  with SUNSERVER enabled. The
server is started by calling server, all  ET++  applications
started  afterwards  will  automatically  connect  with this
server.

In order to support  cut/copy/paste  operations  among  dif-
ferent  application  processes  under  SunWindow,  a special



                        May 24, 1989





                           - 7 -


clipboard server is required. If the clipboard server is not
running  applications can only execute cut/copy/paste opera-
tions between their own windows. Make clipboard compiles the
SunWindow  clipboard  server.   The  clipboard is started by
calling clipboard.

The application app generated with make app  starts  up  any
ET++  application  and dynamically links the missing classes
for this application.  App is called with the  name  of  the
application  as  argument, e.g. app micky, after dynamically
linking all the classes required by this  application  micky
will  start  up as usual. The search path to be used to find
object  files  can  be  set  in  the  environment   variable
ET DYN PATH.   ET DIR/dyn.68020  contains all the neccessary
.o files to dynamically load  applications  micky,  vobedit,
miniedit, and layout.

     Notice: App is not completely finished yet

The command make install moves these additional applications
to ET DIR/bin.

3.  Maintaining the ET++ Class Library

Whenever a new class with a static constructor is  added  to
the  ET++  class  library (et.o) the name of the object file
has to be inserted at the beginning of ET DIR/src/order.


4.  Known cfront 1.2.1 Dependencies

The file ET DIR/src/Object.h includes  the  member  function
overridden  that allows to test whether a method is overrid-
den in a subclass.

        int overridden(int *ip, ObjMemberFunc p)
            { return ((int*) vptr)[(int)p-1] != ip[(int)p-1]; }

The implementation of this test depends on  the  implementa-
tion of vtbls of cfront 1.2.1. The body of this function can
be replaced with

            { return TRUE; }

if you are not using AT&T's cfront.  Overridden is  used  by
ET++ only to eliminate some function calls.

The file ET DIR/src/Class.C includes a reference to the vtbl
pointer  in the debugging method Class::DisplayOn. This code
segment can be deleted without any loss of functionality.

The file ET DIR/src/SUNWINDOW/sunwindow.c is the implementa-
tion of the C++ class SunWindowPort in pure C! For this rea-
son, the structure layout and the name of  member  functions



                        May 24, 1989





                           - 8 -


were  chosen to match the cfront-generated names. A portable
solution to this problem, would be to implement the  members
of SunWindowPort as stubs calling the corresponding external
C functions.

5.  Hardcopy Documentation

The ET DIR/doc  directory  includes  the  document  "ET++  -
Introduction"   stored   in   intro.tbl.ms.   This  document
describes the stylistic conventions used in ET++  and  gives
an  overview  of  the ET++ classes. It is based on troff and
can be printed with the  help  of  the  makefile  stored  in
ET DIR/doc.  This  document  uses  a simple preprocessor for
troff  called  sgml.  This  program  is  included   in   the
ET DIR/doc  directory and can be build with the makefile.  A
copy of the paper "Design and  Implementation  of  ET++"  is
shipped  with  the  distribution (sorry for the bad quality)
and  is  available  through  the  mail  from  the  following
address:

        ET++ Information
        Institut fuer Informatik
        University of Zurich
        Winterthurerstr. 190
        CH-8057 Zuerich
































                        May 24, 1989


