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)
         Xaw3d     ......... 3-d version of Athena widgets
                             (not included, optional)

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

The distribution consists of the following packages:

	(a)   tcl 7.3 (John Ousterhout: extensible tcl shell)
	(b)   dbug (Fred Fish: debug library)
	(c)*  xpm3.2g (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))
	(g)   src (ours: Wafe source)
	(h)*  apps (ours: sample application programs)

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) can be obtained for 
example from 

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

and install it in wafe/lib as indicated above.


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:

       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 a modified (or patched) version
       of tcl 7.3 you should be able to use it. Some people mentioned to
       me that they have built Wafe together with extended tcl (tclX, it
       was in the times of tcl 6.7).


     - building the plotter widget:

       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.


     - building OSF/Motif versions of Wafe:

       #define MOTIF

       Wafe will find out whether OSF/Motif 1.1 or 1.2 is available.
       If the MOTIF flags is set, ATHENA is automatically unset.  I
       have build mofe originally on a DECstation 5000/200, where i am
       using X11R5. Since the OSF/Motif libraries provided by DEC are
       based on X11R4, i have 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.


     - building XmGraph Widget (requires Motif):

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

		$WAFE/lib/XmGraph/Makefile


     - defining LAYOUT in $WAFE/src/Imakefile:

       The Layout widget class is a very powerful constraint widget
       which is supported by Wafe. The Layout widget source is distributed
       together with Xaw3d (see above). If you have no XAW3D on your
       system, you might want to remove this option from the Imakefile.

       If LAYOUT is defined and you are building an OSF/Motif version
       of Wafe, and you are using shared libraries for Motif and Xaw3d,
       you will have either to 
           -  undefine LAYOUT in the Imakefile, 
           -  link LAYOUT with a static library, or
           -  link the object file of the Layout widget separately

       If LAYOUT is defined in the Imakefile and you get an error
       message during compile that Layout.h is not found, it is likely
       that you have no Xaw3d on your system. Undefine LAYOUT or obtain
       Xaw3d.

     - Check the variable WAFELIB in the Imakefile, which should point
       to a place where wafe specific libraries (bitmaps, faces, perl,
       tcllib etc.) will be placed.

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


     - building wafe or mofe:

	   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; 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!

