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.  Please do consider upgrading to at least Tcl/Tk 8.3.3.

  TkDVI uses the `stubs' mechanism, so a version of TkDVI built against
  Tcl/Tk 8.x (x >= 1) is likely to work with Tcl/Tk 8.y (y > x) with
  no recompilation required.

- 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
  the TkDVI project page at http://tkdvi.sourceforge.net/.

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

If the configure script complains it is most probably because it
couldn't find the Tcl/Tk configuration and include files. See below
on how to point it in the correct direction.

  $ 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 me at <lingnau@users.sf.net>.

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. In later
    versions of Debian GNU/Linux this is called `libkpathsea-dev'
    which is somewhat more apt (no pun intended).

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. (I'm told that newer versions of SuSE
    Linux are better in that respect.)

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

FreeBSD:

    BSD make doesn't appear to understand nested makefile variable
    evaluation, which may result in a libtkdvi.so that does not
    in fact contain any object code.  Use GNU make instead, or fix
    the linker command in dvi/Makefile.in.


$Id: INSTALL,v 1.5 2001/08/10 18:24:31 anselm Exp $


