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.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))
	(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 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 or
       1.2 is 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
       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.



     - 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
========================================================================
What should i do if....


Q: I compile wafe or mofe with GhostView support and during linking
   "setenv" is reported as undefined.
A: Add the following lines somewhere at the begin of 
   wafe/lib/ghostview/Ghostview.c:

/* if compiled under wafe, the setenv implementation of Tcl can be used */
#ifdef GHOSTVIEW
#define setenv(name,value,bool) TclSetEnv(name,value)
#endif

   
Q: I compile mofe with HTML support under SunOS 4.1.3, 
   and i get the following message during compilation of HTMLjot.c:
   "./inkstore.h", line 361: syntax error at or near type word "char"
   "./inkstore.h", line 361: unknown size
A: Your compiler does not accept "signed char"; set HTML_DEFINES
   in wafe/src/Imakefile to
   HTML_DEFINES         = -DHTML -Dsigned= -D_NO_PROTO


Q: For some strange reasons, lines starting with XCOMM appear in my
   Makefiles alter xmkmf.
A: According to the compatibility guide from the X Consortium comments
   in Imakefiles should be marked by the word XCOMM; normally, these
   lines are transformed in lines starting with the character '#' in
   the generated Makefiles. If you see lines in the Makefiles starting
   with XCOMM, please check you X configuration or alter these lines
   manually.


Q: I compile with XPM support and BUILD_XPM and obtain the following
   message during compilation of XtGen.c:
      cc -c -O   -I/usr/include -I.   -I../lib/XmGraph  -I../lib/xpm-3.4a/lib
      ...   -DXPM  ...  XtGen.c
      "XtGen.c", line 4065: XpmReturnInfos undefined
      "XtGen.c", line 4290: XpmReturnInfos undefined
      *** Error code 1
      make: Fatal error: Command failed for target `XtGen.o'
A: You have in your /usr/include directory xpm.h from an earlier
   XPM distribution. Either update xpm.h there or remove /usr/include
   from the front of the include paths.


Q: I compile with XPM support without BUILD_XPM (using a version of
   XPM already installed on my system) have the following problems
   during linkage:
      ld: Undefined symbol
      _XpmFreeXpmInfo
      _XpmFreeXpmImage
      _XpmReadFileToXpmImage
A: You are using an old version of XPM. The XPM implementation was
   altered recently, Wafe uses the new version. The easiest solution is
   to compile with BUILD_XPM defined in wafe/src/Imakefile.


Q: When I compile Xaw3d.3.1.2.src.tar.gz from ftp.wu-wien.ac.at 
   make aborts with the following message: 
   (cd ../lib/Xaw3d; /usr/bin/X11/xmkmf; make includes; make)
   mv Makefile Makefile.bak
   imake -DUseInstalled -I/usr/lib/X11/config
   make: Fatal error in reader: Makefile, line 439: Unexpected end of line seen
A: You need X11R5 or better to compile the newer Xaw3d versions.  An
   X11R4 based Xaw3d should be available from ftp.x.org.  If you have
   the X11R5 libraries, include files and binaries on your machine,
   and you still get this message, be sure, that the X11R5 binary
   directory is in front of your search path and that the variable
   CONFIG_DIR_SPEC in the X11R5 shell script "xmkmf" points to the
   X11R5 config directory.


Q: I am starting a wafe application (wafemc) and instead of a graphical user 
   interface, messages like the following appear on my screen:

   %echo [getChannel] $WAFEVERSION: $XVERSION $PACKAGES
   %set FILESEARCHPATH /usr/lib/X11/wafe/%T/%N:/usr/lib/X11/wafe/faces/%N:/usr/include/X11/%T/%N:%N
   %sV topLevel iconPixmap wafe.xbm
   %mergeResources topLevel  *foreground  black  *shadowWidth 0
   % proc deleteWindowProtocol {cmd} { setWMProtocols topLevel WM_DELETE_WINDOW; action topLevel override "<Message>WM_PROTOCOLS: exec($cmd)" }
   ...
A: you are executing wafemc and not xwafemc.
   It should be possible now to run this progam in the following ways:
    -  xwafemc  (as suggested in the install file (note the leading "x".
                 wafemc will be executed as a subprocess of wafe)
    -  wafe --p wafemc
                (same as above, but more explicit)
    -  wafemc -P
                (wafe will be executed as a subprocess of perl ("Perl on top")
                this allows to use stdin and stdout of perl freely to
                run for example a perl debugger)
