INSTALLING TKDVI
================

Prerequisites
-------------

For TkDVI you need the following software packages:

- Tcl/Tk 8.x (see http://dev.scriptics.com/). Older versions will *not*
  work.

- Kpathsea library from Web2C 7.x. If you have teTeX 0.9 or later you
  should have it around somewhere or be able to obtain it. A working
  version extracted from the teTeX source code is available from
  ftp://ftp.tm.informatik.uni-frankfurt.de/pub/dist/tkdvi/kpathsea.tar.gz.

These must be installed on your system in order for the TkDVI build
process to succeed. (See below for quick-and-dirty Kpathsea installation
instructions.)


Configuration and Installation
------------------------------

TkDVI uses the GNU autoconf mechanism to adapt itself to your system.
Rather than write it all up myself, I've included a generic
description of autoconf-based configuration in the file
INSTALL.generic.

The general idea is

  $ tar xvzf tkdvi-0.3.tar.gz
  $ cd tkdvi-0.3
  $ `pwd`/configure --enable-shared
  $ make
  $ make install        # do this as `root' if necessary

If you don't have a suitable Kpathsea environment, obtain the
kpathsea.tar.gz archive from the URL mentioned in `Prerequisites' and
do

  $ tar xvzf kpathsea.tar.gz
  $ cd kpathsea
  $ `pwd`/configure --datadir=/usr/share

(insert the directory on your system where the `texmf' directory is
located, or the configure script will complain). Add `--enable-shared'
if you like.

  $ make
  $ make install        # do this as `root' if necessary

Then proceed as above for TkDVI.

If you run into trouble, please check the system-specific notes at the
end of this file. Be sure to report difficulties with the build process
to <tkdvi-bugs@tm.informatik.uni-frankfurt.de>.

TkDVI's configure script contains a number of special options, namely:

  --enable-debug	to enable support for the automatic regression
			test suite used in `make check'. Turn this on
			if you want to run the regression tests.

  --with-tcl=DIR	to use the Tcl configuration file (tclConfig.sh)
                        in directory DIR. The configure script tries to
                        derive the directory of tcl.h from this directory
                        as well. This defaults to `/usr/lib'.

  --with-tclinclude=DIR to specifiy the location of tcl.h. See
                        system-specific notes below for SuSE Linux.

  --with-tk=DIR	        to use the Tk configuration file (tkConfig.sh)
			in directory DIR.

  --with-kpathsea=DIR	to use the Kpathsea library in directory DIR.
			This should be the directory where the
			`libkpathsea.a' file is located. This defaults
			to `/usr/lib'.

  --with-kpathseainclude=DIR to specify the location of the Kpathsea
                        headers. DIR should be specified such that
                        `kpathsea/proginit.h' is in DIR.

The following TEA-compatible options are also honoured:

  --enable-threads      Build with thread support. TkDVI doesn't use
                        threads, and for the time being no work has
                        been done to ensure that the C code is, in
                        fact, thread-safe. DO NOT USE THIS.

  --enable-shared       Build and link with shared libraries. This
                        is generally a good idea.

  --enable-symbols      Builds a debugging library with symbols.
                        This is only useful if you intend to help
                        with TkDVI development.

The normal way would be to use `make install' to install TkDVI to a
directory hierarchy such as `/usr/local'. You can run TkDVI from
the compilation directory but you must invoke a `wish' explicitly
since the `tkdvi' script is only made executable by `make install'.
Also you need to make sure that TkDVI will find the dvi extension
and its Tcl files:

  $ export TKDVI_BINLIB=`pwd`/dvi
  $ export TKDVI_TCLLIB=`pwd`/lib
  $ wish ./tkdvi testdvi/mini

(After the `make install', `tkdvi testdvi/mini' should be sufficient
-- the environment variables are mostly for testing.)


Testing
-------

There is an incomplete regression test suite in the `tests'
subdirectory of the distribution. Use `make check' from the
compilation directory to run the tests -- note that you must have
said `--enable-debug' during configuration to be able to run the
test suite successfully! (See above.)

The tests that deal with font files may fail because your system
does not use the same sort of fonts as mine.


System-specific Notes
---------------------

Debian GNU/Linux:

    Install the `tetex-dev' package for Kpathsea headers.

SuSE Linux:

    In some versions of SuSE Linux, for some reason the tcl.h file
    is installed as /usr/include/tcl8.0.h, which sucks. The same
    applies to tclConfig.sh. This will bite you with any Tcl extension
    that you may want to install; the best solution is to rename the
    files or introduce symbolic links. You do not really want to keep a
    Tcl 7.6 development environment if you can help it at all --
    if you do, put its headers into a separate directory. Of course
    your best bet would be to get an up-to-date version of Tcl/Tk
    (it's up to 8.3.1 as of July, 2000, so 8.0 is *really* old) and
    install that in /usr/local.

    You will probably also have to install the Kpathsea emergency
    package from the TkDVI server.


$Id: INSTALL,v 1.4 2000/07/07 11:48:30 lingnau Exp $


