Prerequisites
* perl5beta1 for header files
* tk3.6 library
* tcl library
* X11 library

Treat this the same as any other extension. The easiest way is to have this
hierarchy as the ext/Tk subdirectory of the perl distribution and add "Tk"
to the list of extensions that Configure asks you for. You'll probably
need to change the definition of tclincludeflag at the top of Makefile.SH
but, provided you're incredibly lucky, the libraries should be sorted out
automagically.

Platforms known to work:
    OSF/1, 2.0B and 3.0
    Ultrix 4.4
    NeXT
    Solaris 2.3
    Linux
    SunOS 4 (which possibly needs tweaking of -L options in Makefile if
             using unpatched perl5beta1)

Apart from tweaking tclincludeflag to pick up header files (and possibly
-L options if Perl's own Configure didn't find enough library directories),
the most likely problem to occur is symbol resolution problems.  There
should not be any subtle problems with static linking, but with building
a sharable object for dynamic loading some strange problems can crop up.
Since platforms all handle dynamic loading in slightly different ways,
it is difficult to be definite about the symptoms of problems. The
following three problems at least are know about:
(1) Undefined symbols making the run-time dynamic loading fail
    Even though the creation of the sharable object (usually Tk.so) may
    have succeeded, there may be problems at run-time with the dynamic
    loader for that O/S resolving symbols. This can happen if the ld
    stage in TkPerl's Makefile failed to give enough options to specify
    what libraries would be needed at dynamic-load-time and where they
    could be found.
(2) Multiply defined symbols making the run-time dynamic loading fail
    If the ld stage of the Makefile specified some libraries that would
    need to be resolved against at run-time *and* at least one of those
    libraries was statically linked into the perl executable, some
    O/Ses have trouble. This can even happen with -lc and -lm.
(3) Wrong symbol resolution causing weird symptoms at run-time.
    Under OSF/1 (at least), if libtk is statically linked into the perl
    executable then some symbols can be resolved from there instead of
    TkPerl's own rewritten versions that were linked into Tk.so. The
    visible symptoms of this are either that scripts using TkPerl dump
    core, or they ignore all incoming events. For example, the t/buttontest
    script will display its button but ignore mouse clicks on it. The
    t/canvastest test will display a black blob instead of a wide black
    square. If you see these symptoms, try rebuilding Perl *and* TkPerl
    *from scratch* and be very careful how you specify libraries to Perl's
    Configure. If you are building a dynamic version of Tk, do *not*
    specify the -ltcl -ltk -lX11 libraries to Perl's Configure. Also,
    make sure that all so_locations files are removed. They may hide in
    Perl's top level directory or lib/auto/Tk or even ext/Tk itself.

The subdirectory t contains some test scripts and looking at those in
conjunction with the GUIDE file will have to suffice for documentation.

Malcolm Beattie
5 September 1994