
The programs provided contain the necessary code to link Wafe 1.0.6 or newer
DYNAMICALLY with Perl 5.0. This kit allows to build an extension of Perl
that has a few additional commands that allow to build Xt based
applications directly in Perl (using either the Athena widget set "use
wafe" or the OSF/Motif widget set "use mofe"). The Wafe distribution
contains as well code for linking Wafe statically to perl4.036.

Wafe was originally developed to provide graphical user front-ends for
programs in arbitrary programming languages. When Wafe is used as a
front-end, it executes as a separate process (coprocess) linked via
sockets to an application program. In the Wafe distribution there are
various examples how to use Wafe together with Perl. The applications
ranges from various monitoring programs to news reader, mailer and ftp
clients. The Wafe applications from the distribution can show how to
run an Perl application as a subprocess of Wafe or Wafe as a
subprocess of Perl.

This kit offers a third possibility to use Wafe together with Perl by
building an extended version of Perl, in which Wafe functions can be
called as use subprograms of Perl and Perl functions can be called
from Wafe vice versa.


The extensions "wafe" and "mofe" define the following additional
commands in Perl:

   - wafe::cmd($wafeCommand)

     Evaluate the specified command (in Tcl Syntax) and 
     return its return value


   - wafe::set($varName,$value)

     this command can be used to set a Tcl variable with the specified
     name to the given value, bypassing Tcl_Eval. This allows to pass
     values without the need to escape characters with special Tcl
     meaning (such as {}[]$\")


   - wafe::process_events

     This command calls the Xt event loop, it will never
     finish. Note that Xt events can be as well processed by
     wafe::cmd('processPendingEvents'), which processes only
     pending events.


In order to call Perl from Wafe (e.g. in a callback procedure)
only once command is needed

   - "perl subroutine arg1 arg2 .."

     This Wafe command will call the specified subroutine with the
     specified arguments and will return the scalar return
     value (optionally) to Wafe in form of a string.

Wafe provides Xt-style command line argument processing (e.g. -display
..., -bg pink, etc).  Notes concerning (a): When the command line
arguments are processed they are not removed automatically from Perl's
@ARGV.  As it looks to me, arguments cannot be removed from the Perl
argument list from the c level without patching Perl itself. For the
time being, one can use the following trick to adjust @ARGV by using
Wafe's argument list:

       sub setargv {
         @ARGV=();
         local($ARGC) = &wafe_cmd('return [set argc]');
         for($i=0; $i<$ARGC; $i++) {
             push(@ARGV,&wafe_cmd("return [lindex [set argv] $i]"));
         }
       }
       &setargv();

============================================================================
INSTALLATION:

Prerequesits: 
	Perl 5.0000 or newer (source)
	Wafe 1.0.6  or newer

Wafe can be obtained for example from 

	ftp.wu-wien.ac.at:pub/src/X11/wafe/*

Step 1: Build Wafe as indicated in the Wafe distribution
Step 2: Build Perl (we will need the .o files in the next step)
Step 3: Copy or move the files from wafe/wafeperl5/ext/*
        into the source tree of Perl 5 such you get an 
        directory structure like

          .../perl-5.000/lib/...
          .../perl-5.000/ext/...
          .../perl-5.000/ext/wafe/...
          .../perl-5.000/ext/mofe/...

        In order to build the 'wafe' or 'mofe' extension for Perl,
        please add the following symbols to perl5*/global.sym and
        recompile and reinstall Perl (unless these symbols are already
        included there)

          origargc
          origargv
          tmps_floor
          tmps_ix

        'origargc' and 'origargv' are needed by Wafe to interpret the
        standard Xt command line arguments (for example to get
        "-display MYHOST:0", "-background pink" etc. working like for
        other Xt based applications). The two last symbols are
        required (at least on an AIX machine) in order to follow the
        guidelines for returning values form Perl to C.

Step 4: Check Makefile.PL in ext/wafe/ or ext/mofe, whether it has all
        desired options configured and build a Makefile using

            perl Makefile.PL

        in the the extension subdirectory and build and install the
        extension


The Wafe extensions were only tested as dynamic extensions
for Perl5 (no static testing), but the dynamic cases are
typically both more fragile and desirable.

The packaged sample scripts for the Perl5 extensions are

   ext/wafe/wp-sample    # script showing type of parameter passing
   ext/mofe/mp-edit      # simple editor

Have fun
-gustaf

