Installing Tcl-DP
by Brian Smith (bsmith@cs.cornell.edu)
v3.5beta2, August 16, 1996

0. Quick Installation

    To install Tcl-DP, use the following five step formula:

	1) Unpack the distribution.  Make sure the directories (or
	   symlinks) ../tcl7.5 and ../tk4.1 point to the location of
	   the source Tcl/Tk source code.
	2) Edit Makefile.in to customize the pathnames of the
	   installation.
	3) run ./configure
	4) run make
	5a) run "make install" to install everything.
	5b) run "make install-binaries" to install just the binaries
	    (dpwish, the manual pages, and the supporting tcl library
	    files)
	6) Register as a user by filling out the form at
	http://www.cs.cornell.edu/Info/Projects/zeno/Tcl-DP/reg-form.html
	   
    This process is discussed in more detail in the paragraphs below.

1. Introduction

    The Tcl Distributed Programming (Tcl-DP) extension gives Tcl
    programs a rich set of primitives for inter-process communication.
    Tcl-DP provides an interface to TCP, UDP, and IP-multicast sockets,
    remote procedure call (RPC), a simple distributed object system,

    Tcl-DP runs most Unix variants; it's been known to compile and run
    on SunOS, Solaris, SGI, Linux, OSF/1, Ultrix, HP-UX, CrayOS, DGUX.
    Other non-Unix operating systems include VMS and Windows/NT.  A
    non-tk version of Tcl-DP called "dpsh" has been ported to DOS, and
    a port to the Machintosh is underway. Please note that Tcl-Dp 3.5
    beta 2 is a Unix port only.

    The rest of this document describes how to install Tcl-DP (section
    2) and trouble-shooting tips (section 3).

2. Installing Tcl-DP

    Tcl-DP can be compiled with or without X windows.  The advantage of
    compiling the version with X windows is that it gives you a wish type
    executable that contains Tcl-DP.  The non X-windows version gives
    you a much smaller executable, but is only useful for processes that
    do not connect to a display.  Most people choose the version with X
    windows support.   No matter which version you choose, your task will
    be a four step process:

	1. Unpack the distribution
	2. Edit Makefile.in
	3. Run "configure"
	4. Run "make install" (X version) or
	   "make install-dpsh" (no-X version)

    2.1 Unpack the distribution

    Chances are, if you're reading this file, you've already figured
    out how to unpack the distribution.  Tcl-DP is distributed as
    a tar file compressed using the Unix "gzip" program.  A
    typical way to uncompress and extract the Tcl-DP sources is
    to execute the command

	gzip -cd tcl-dp3.4b1.tar.gz | tar xvf -
    
    Running this command will create a directory called tcl-dp3.4b1 in
    the current directory.  You should also, at this point, locate the
    directory containing the tcl7.5 and tk4.1 source files (it should have
    tkInt.h and tclInt.h) and create symlinks to those directories with
    the names tcl7.5 and tk4.1.  For example, if /home/dave/src/tcl-7.5
    and /home/dave/src/tk-4.1 are the directories containing the Tcl
    7.5 and Tk 4.1 source code, you would create the symlinks using the
    following commands in the directory where you ran "uncompress":

	ln -s /home/dave/src/tcl-7.5 tcl7.5
	ln -s /home/dave/src/tk-4.1 tk4.1
    
    If you list the contents of the directory, you should see at least
    the following 3 items:

	tcl7.5 tk4.1 tcl-dp3.5beta2

    2.2 Edit Makefile.in

    If you don't want to create these symlinks for some reason, you
    can edit the TCL_DIR, TCL_ARCHIVE, TK_DIR, and TK_ARCHIVE variable in
    the file named Makefile.in in the tcl-dp3.5beta2 directory.  Most of the
    path names related to the installation are defined in Makefile.in,
    and are well commented.  The configure script (which you'll run at
    the next step) determines most of these automatically, but if you
    can't get it to do the right thing, edit Makefile.in.

    2.2 Building Tcl-DP

    After editing Makefile.in (if you have) execute the following sequence
    of commands to build and install the X windows version:

	1) execute "./configure"
	2) execute "make"
	3) (optional) execute "make test" to test the distribution.
	4a) execute "make install" to install everything, or
	4b) execute "make install-binaries" to install just the binaries
	    (dpwish, the manual pages, and the supporting tcl library
	    files)  This option is useful if you're compiling for several
	    architectures and have already installed the machine independent
	    files in a shared file system.

    To install the non-X windows version, execute the following sequence
    of commands:

	1) execute "./configure"
	2) execute "make dpsh"
	3) (optional) execute "make test-dpsh" to test the distribution.
	4a) execute "make install-dpsh" to install everything, or
	4b) execute "make install-dpsh-bin" to install just the binaries

    The configure script checks machine dependencies and looks for the
    various libraries and include files that are needed to compile
    Tcl-DP.  It then creates a Makefile from the file Makefile.in.
    You can modify the default targets one of two ways:

        o You can edit Makefile.in
        o You can run "configure --exec-prefix=<edir> --prefix=<pdir>"
          where "<edir>" is the root directory for machine dependent
          files (e.g., executables) and "<pdir>" is the root directory
          for machine independent files (e.g., man pages).  For example,
          if you want dpwish installed in /usr/local/bin, use /usr/local
          for <edir>.

    In addition, the configure script can take other command line arguments
    to modify its behavior (e.g., to use cc instead of gcc).  These options
    can be listed by running the command

	./configure -help

    If you have any trouble, the easiest strategy is to edit Makefile.in
    and then run "make Makefile" to rebuild the Makefile from Makefile.in.

    Incidentally, you can run "make install-man" to install just the
    manual pages, and "make install-libraries" to install just the header
    files and tcl scripts.

3. Troubleshooting

    If "make test" (or "make test-dpsh) fails, chances are you can still
    use Tcl-DP -- the test suite tends to be a bit paranoid.  I'd like
    to hear about any cases where make test fails -- please send me mail
    describing the operating system and version, machine type, and output
    of the "make test" command.  If you can figure out a work around or
    patch, please include that so that others can share your wisdom.

4. Registering

    Register as a user by filling out the form at

	http://www.cs.cornell.edu/Info/Projects/zeno/Tcl-DP/reg-form.html

    Registration helps us raise money to continue to support
    Tcl-DP (I've got to convince the NSF that people actually
    use it!).  What's in it for you?  We'll send you updates, and add
    you to the beta testers list if you say so.

Brian Smith (bsmith@cs.cornell.edu)
