Tk UNIX README
--------------

This is the directory where you configure, compile, test, and install
UNIX versions of Tk.  This directory also contains source files for Tk
that are specific to UNIX.

The information in this file is maintained at:
	http://www.purl.org/tcl/home/doc/howto/compile.html

For information on platforms where Tcl/Tk is known to compile, along
with any porting notes for getting it to work on those platforms, see:
	http://www.purl.org/tcl/home/software/tcltk/platforms.html

The rest of this file contains instructions on how to do this.  The
release should compile and run either "out of the box" or with trivial
changes on any UNIX-like system that approximates POSIX, BSD, or System
V.  We know that it runs on workstations from Sun, H-P, DEC, IBM, and
SGI, as well as PCs running Linux, BSDI, and SCO UNIX.  To compile for
a PC running Windows, see the README file in the directory ../win.  To
compile for a Macintosh, see the README file in the directory ../mac.

RCS: @(#) $Id: README,v 1.12 2001/07/05 17:23:53 hobbs Exp $

How To Compile And Install Tk:
------------------------------

(a) Make sure that the Tcl 8.4 release is present in the directory
    ../../tcl8.4 (or else use the "--with-tcl" switch described below). 
    This release of Tk will only work with Tcl 8.4. Also, be sure that
    you have configured Tcl before you configure Tk.

(b) Check for patches as described in ../README.

(c) If you have already compiled Tk once in this directory and are now
    preparing to compile again in the same directory but for a different
    platform, or if you have applied patches, type "make distclean" to
    discard all the configuration information computed previously.

(d) Type "./configure".  This runs a configuration script created by GNU
    autoconf, which configures Tcl for your system and creates a
    Makefile.  The configure script allows you to customize the Tcl
    configuration for your site; for details on how you can do this,
    type "./configure -help" or refer to the autoconf documentation (not
    included here).  Tk's "configure" script supports the following
    special switches in addition to the standard ones:
	--enable-threads	Tk on Unix currently does not support
				threaded builds.
	--with-tcl=DIR		Specifies the directory containing the Tcl
				binaries and Tcl's platform-dependent
				configuration information.  By default
				the Tcl directory is assumed to be in the
				location given by (a) above.
	--enable-shared		If this switch is specified, Tk will compile
				itself as a shared library if it can figure
				out how to do that on this platform.  This
				is the default on platforms where we know
				how to build shared libraries.
	--disable-shared	If this switch is specified, Tk will compile
				itself as a static library.

    Note: by default gcc will be used if it can be located on the PATH.
    if you want to use cc instead of gcc, set the CC environment variable
    to "cc" before running configure. It is not safe to change the Makefile
    to use gcc after configure is run.

    Note: be sure to use only absolute path names (those starting with "/")
    in the --prefix and --exec-prefix options.

(e) Type "make".  This will create a library archive called
    "libtk<version>.a" or "libtk<version>.so" and an interpreter
    application called "wish" that allows you to type Tcl commands
    interactively or execute script files.

(f) If the make fails then you'll have to personalize the Makefile
    for your site or possibly modify the distribution in other ways.
    First check the porting Web page above to see if there are hints
    for compiling on your system.  If you need to modify Makefile,
    there are comments at the beginning of it that describe the things
    you might want to change and how to change them.
    
(g) Type "make install" to install Tk's binaries and script files in
    standard places.  You'll need write permission on the installation
    directoryies to do this.  The installation directories are
    determined by the "configure" script and may be specified with
    the --prefix and --exec-prefix options to "configure".  See the
    Makefile for information on what directories were chosen; you
    can override these choices by modifying the "prefix" and
    "exec_prefix" variables in the Makefile.

(h) At this point you can play with Tk by invoking the "wish"
    program and typing Tcl commands.  However, if you haven't installed
    Tk then you'll first need to set your TK_LIBRARY environment
    variable to hold the full path name of the "library" subdirectory.
    If you haven't installed Tcl either then you'll need to set your
    TCL_LIBRARY environment variable as well (see the Tcl README file
    for information on this).  Note that installed versions of wish,
    libtk.a, libtk.so, and the Tk library have a version number in their
    names, such as "wish8.4" or "libtk8.4.so"; to use the installed
    versions, either specify the version number or create a symbolic
    link (e.g. from "wish" to "wish8.4").

If you have trouble compiling Tk, see the URL noted above about working
platforms.  It contains information that people have provided about changes
they had to make to compile Tk in various environments.  We're also
interested in hearing how to change the configuration setup so that Tk
compiles on additional platforms "out of the box".

Test suite
----------

Tk has a substantial self-test suite, consisting of a set of scripts in
the subdirectory "tests".  To run the test suite just type "make test"
in this directory.  You should then see a printout of the test files
processed.  If any errors occur, you'll see a much more substantial
printout for each error.  In order to avoid false error reports, be sure
to run the tests with an empty resource database (e.g., remove your
.Xdefaults file or delete any entries starting with *).  Also, don't
try to do anything else with your display or keyboard whlie the tests
are running, or you may get false violations.  See the README file in
the "tests" directory for more information on the test suite.

If the test suite generates errors, most likely they are due to non-
portable tests that are interacting badly with your system configuration.
We are gradually eliminating the non-portable tests, but this release
includes many new tests so there will probably be some portability
problems.  As long as the test suite doesn't core dump, it's probably
safe to conclude that any errors represent portability problems in the
test suite and not fundamental flaws with Tk.

There are also a number of visual tests for things such as screen layout,
Postscript generation, etc.  These tests all have to be run manually and
the results have to be verified visually.  To run the tests, cd to the
"tests" directory and run the script "visual".  It will present a main
window with a bunch of menus, which you can use to select various tests.
