Compiling Wafe and its components
=================================

Wafe can be build in configured in various ways.
Depending on the options chosen during compilations
certain functionalities may be available in the 
resulting executable or not. Please read through these 
instructions carefully.

The Wafe directory tree has the following structure:

   wafe      ........ Wafe home

      src       ........ Wafe source
         tcl      ........ sample tcl scripts 
         tcllib   ........ tcl library files

      lib       ........ optional and required libraries
                         to build Wafe

         tcl7.3    ......... Tcl (required)
         dbug      ......... dbug library (required)
         xpm-3.4a  ......... xpm (optional)
         plotter   ......... plotter widgets (optional)
         libhtmlw  ......... HTML widget (optional)
         XmGraph   ......... Graph widget (requires Motif, optional)
         mtree     ......... Motif Tree Widget (requires Motif, optional)
         Xaw3d     ......... 3-d version of Athena widgets
                             (not included, optional)
         Xbae-3.8  ......... Xbae Matrix and Caption widgets
                             (not included, optional, require Motif)


      hardcopy   ....... documentation in postscript
      wafeperl   ....... kit to build Perl 4.036 with Wafe functionality
      wafeperl5  ....... kit to build Perl 5.00 with Wafe functionality
      wafepython ....... kit to build Python 1.0.2 with Wafe functionality
      apps       ....... (mostly) Perl written sample applications
                         using Wafe as a frontend 
                         (a Perl executable will be necessary)

The distribution consists of the following parts:

	(a)   tcl 7.3 (John Ousterhout: extensible tcl shell)
	(b)   dbug (Fred Fish: debug library)
	(c)*  xpm3.4a (Arnaud Le Hors: pixmap library)
	(d)*  plotter (Peter Klingebiel et.al.: plotter widget set)
	(e)*  XmGraph (Douglas Young: Motif Graph Widget)
	(f)*  libhtmlw (Mosaic's hypertext widget (HTML), requires XPM)
	(g)   src (ours: Wafe source, sample wafe tcl scripts)
	(h)*  apps (ours: sample application programs using wafe as a frontend)

The packages marked with * are optional.  (a) to (f) are
prerequisites of (g) which is a prerequisite of (h).  For many
application programs in (h) you will need Perl 4.036, which you can
obtain from every good archive server (such as ftp.uu.net or
wuarchive.wustl.edu).

Before you build Wafe and its components, check out which packages you
will need or which packages you can build. It is possible to build
either an Athena (Xaw) Wafe binary (called "wafe") or an OSF/Motif
Wafe binary (called "mofe"). The OSF/Motif version of Wafe and (e) can
only built when an OSF/Motif development kit is installed on the
target system (include files and libraries).

Here comes a short descriptions of the components of the distribution:

  (a) Tcl is the core programming language on which Wafe is based on.

  (b) The debug library which can be used for tracing, debugging and
      profiling. These functionalities can be turned off by a compile
      option in wafe/src/Imakefile (see below).

  (c) xpm is a format to store color icons (or pictures). The
      library in this directory contains functions to read, display 
      etc. xpm files. When Wafe is compiled with xpm, it is possible
      to set labels, icons backgrounds etc. of various widgets to
      color pictures just by referring to .xpm files instead of the
      standard monochrome (1 plane) .xbm files.

  (d) The Plotter library contains several widgets for producing
      applications bar plot or line plot graphs.

  (e) XmGraph is a widget for the OSF/Motif widget set which 
      can be used for drawing arbitrary graphs (directed or undirected).

  (f) libhtmlw contains the Mosaic 2.4 Hypertext (HTML) widget.
      When Wafe is built with HTML support, it is possible to 
      build hypertext applications with Wafe, to provide an easy
      way to implement fill out forms and to trigger shell commands
      etc. from pressing buttons in the hypertext (visual scripts).
      The HTML widget can be used in wafe and mofe.


Certain steps below can be omitted in cases where the libraries are 
already installed (eg. a, b, c are unmodified redistributions; 
d, e and f contain fixes and enhancements over the original 
distributions)

If you decide to build a version of Wafe using the Athena Widget set,
i would recommend to use Xaw3d. If you have Xaw3d not already installed
you can obtain a version (with several patches) for example from 

    ftp.wu-wien.ac.at:pub/src/X11/wafe/Xaw3d.3.1.2.src.tar.gz

and install it in wafe/lib as indicated above; this version of Xaw3d 
requires X11R5. A fixed version for R6 can be found at the same
place. For more information about various versions of Xaw3d please
consult http://www.wu-wien.ac.at/wafe/Xaw3d.html.


HOW TO BUILD WAFE:

  1) Choose a directory where you want to build wafe 
     and its application programs.

	csh
	gunzip < wafe-1.0.tar.gz | tar -xvf -
	cd wafe
	setenv WAFE `pwd`

     Note: some systems might prefer "xvf" instead of "-xvf"
           as command line option of tar. 


  2) Read and configure $WAFE/src/Imakefile.
     
     This Imakefile will try to build all subcomponents of
     Wafe. This is quite ambitious since various add ons to Wafe
     have been written by various authors which have frequently
     different ideas how to configure their programs.

     Here is some additional information for various packages:

     - Building tcl 7.3 or using an already installed version:

       Wafe uses the standard Tcl library (which is very small). 
       The directory where it is to be installed is defined in
       $WAFE/lib/tcl7.3/Makefile, it can be installed using 

                make install-libraries

       from $WAFE/lib/tcl7.3, once Tcl is compiled.

       The tcl7.3 version included in the Wafe distribution is a
       complete unmodified version from a tcl archive (i think i got it
       from sprite the day it came out). Wafe does NOT NEED ANY
       modifications on tcl. If you have already a version of tcl 7.3
       you should be able to use it. In order to avoid the compilation
       of tcl, undefine BUILD_TCL in $wafe/src/Imakefile.  Some people
       reported that they have built Wafe together with extended tcl
       (tclX, it was in the times of tcl 6.7).


     - Building an OSF/Motif version of Wafe:

       When MOTIF is defined in $WAFE/src/Imakefile, Wafe will be built
       with MOTIF support (but with no Athena widget set support). The
       resulting binary will be called "mofe".

       When MOTIF is defined Wafe will find out whether OSF/Motif 1.1,
       1.2 or 2.0 are available.  I have build mofe originally on a
       DECstation 5000/200, where i am using X11R5. Since the
       OSF/Motif libraries provided by DEC were based on X11R4, i had
       to use separate X libraries, as well as separate Plotter Widget
       libraries and so on. That's why there are so many MOTIF flags
       in the Imakefile. I have left it there, maybe someone will find
       it useful

       As shipped -DMOTIF_EDITRES is turned on, which will allow to
       use the editres protocol with mofe applications. If you compile
       a MOTIF version with an X Toolkit which is older than X11R5 you
       will have the remove this flag.


     - Support for the plotter widget class:

       Support for the plotter widget class is enabled by defining
       PLOTTER in $WAFE/src/Imakefile (this is the default). The plotter
       widgets can be used together with the Athena or OSF/Motif widget
       sets.

       The plotter widget source as it is distributed with Wafe
       has several bug fixes. The full original distribution
       of the plotter widget set can be obtained from

		ftp.wu-wien.ac.at:pub/src/X11/plotter.v60.README
		ftp.wu-wien.ac.at:pub/src/X11/plotter.v60.tar.Z
		ftp.wu-wien.ac.at:pub/src/X11/plotter.v6b.doc.tar.Z
		ftp.wu-wien.ac.at:pub/src/X11/plotter.v6b.afm.tar.Z

       or other sources. You might want to obtain .afm files for 
       printing or the full documentation.



     - Support for the XmGraph Widget (requires Motif):

       Support for the XmGraph widget class is controlled by the
       variable XMGRAPH in $WAFE/src/Imakefile. Per default, the
       XmGraph widget class will be supported.

       In cases where the OSF/Motif include files are installed
       on non-standard places, you will have to edit 

		$WAFE/lib/XmGraph/Makefile


     - Support for the Layout widget class:

       Support for the Layout widget class can be enabled by
       defining LAYOUT in $WAFE/src/Imakefile.

       The Layout widget class is a very powerful constraint widget
       with TeX like semantics and is supported by Wafe. The Layout
       widget source is distributed together with Xaw3d (see above)
       and Wafe. The version distributed with Wafe has various bug
       fixes and has been extended to work better together with
       OSF/Motif widgets (the Layout widget class is now 
       resubclassed under XmManager).


     - Ghostview support:

       optionally you might want to build wafe or mofe with support for
       displaying postscript files.

        1. obtain ghostview (i used for testing ghostview-1.5.tar.gz)
        2. define GHOSTVIEW in $WAFE/src/Imakefile (or in TOPMAKE)
        3. copy or link
              Ghostview.h
              GhostviewP.h
              Ghostview.c
           from the ghostview sources to $WAFE/lib/ghostview/
        4. do a xmkmf in $WAFE/src followed by make (or use TOPMAKE).

       Ghostview can be built with together with the Motif of Athena
       widget set.


     - Check the variable WAFELIB in $WAFE/src/Imakefile, which should point
       to a place where wafe specific libraries (bitmaps, faces, perl,
       tcllib etc.) will be placed. You will need write permissions
       during installation in this directory.

       At runtime of Wafe, the the environment variable WAFELIB could be
       used to override the default specified in the Imakefile.


     - Building wafe or mofe binary:

	   cd $WAFE/src

       Decide, which libraries you want (have) to build in Imakefile;
       for example, under Linux i would recommend to comment BUILD_XPM
       and BUILD_TCL; please note, that the XPM library has changed
       recently and the current version of Wafe depends on XPM 3.4 or
       newer.
   
       If BUILD_XAW3D is specified, you have to obtain Xaw3d
       separately (see above) and make a link from its source to
       $WAFE/lib/Xaw3d

           xmkmf
           make

       You should now be able to run the sample scripts in $WAFE/src/tcl.
       The scripts starting with 'm-' are Motif-only versions, the others
       are for Athena. In order to install Wafe, issue
       
	   strip wafe
	   make install

       If you intend to build various versions of wafe that require
       editing of the Imakefile, you could use $WAFE/src/TOPMAKE on
       top of the generic Imakefile. Read the top section of
       $WAFE/src/TOPMAKE for more information.


     - configuring and installing the Perl written Wafe applications

  	   cd $WAFE/apps

       You can choose whether you prefer a 'local installation' (i.e. in
       your home directory) or a global installation (typically in
       /usr/bin/X11 and /usr/lib/X11). If LOCAL is defined in the
       Imakefile, parms.local are used, otherwise parms.global.  Modify
       the appropriate parms.xxxxx file. At runtime the environment
       variable WAFELIB can still be set to address a wafe library on a
       nonstandard location.

	   xmkmf
	   make Makefile
	   make Makefiles
	   make install

       If you can write to the directory, where your man pages are
       installed you might issue

	   make install.man
	   rehash

       If everything works, you might try to answer the questions in
			
	   xwafemc -l english

       provided, you have Perl on your system. If you have trouble with
       fonts etc, read the man page of "wafeapp". To see examples in
       various languages check the directory

	   $WAFE/apps/lang/

       A postscript version of the documentation (man-pages+handbook)
       and a copy of our Usenix paper can be found in

	   $WAFE/hardcopy/

       you will find additional programs in

	   $WAFE/apps/contrib/

       and small sample scripts for beginners in 
 
	   $WAFE/src/tcl/


Good luck!

Gustaf Neumann
