EXTENDED TCL SOURCE DIRECTORY HIERARCHY
=======================================

Building the Extended Tcl requires access to built Tcl and Tk source
directories.  Their location relative to the tclX7.3b directory must be
configured by editing tclX7.3b/Config.mk.  The default is to place tclX7.3b
in a directory parallel to the Tcl and Tk distributions:

                   tcl7.3      tk3.6      tclX7.3b


The following directories are included under the tclX7.3b directory:

    o man - Unformatted manual pages for TclX.

    o src - The main source for TclX.

    o osSupport - Library routines required by TclX that may not be available
      on all Unix versions.

    o tclsrc - Tcl source that is built into the standard Tcl package library.
      The makefile also handles generation of help files.

    o tests - Tests for TclX.

    o tclhelp - The Tcl and TclX help files.  These can be rebuilt from the
      manual pages if necessary.

    o tksrc - A makefile that builds a version of the Tk wish shell containing
      Extended Tcl.

    o tktclsrc - Tcl source that is built into the standard Tk package library.
      The makefile also handles generation of help files.

    o tktests - Files used to test wishx.

    o tkhelp - The Tk help files.  These can be rebuilt from the manual pages
      if necessary.

    o tools - Tools used for building and installing TclX.

    o tclmaster - Tcl master directory.  All files required to run TclX are
      built or copied into this directory.  The entire contents of this
      directory are installed.  This directory is created by the build, it is
      not part of the distribution.

    o tkmaster - Tk master directory.  All files required to run Tk
      are built or copied into this directory.  The entire contents of
      this directory are installed.  This directory is created by the build,
      it is not part of the distribution.

THE EXTENDED TCL INSTALLATION MODELS
====================================

Two installation models are supported by Extended Tcl.  You should decide which
model you are going to use before building TclX.  We encourage use of the 
"master directory" model, as it supports multiple versions of Extended Tcl and
Tk being installed on the system at the same time and allows for easy copying
to other systems.

Standard Installation Model
---------------------------

The standard model follows the GNU standards.  Two variables are defined
by configure, "prefix" and "exec_prefix".  The variable "prefix" is the
path that will contain the directories containing hardware and system
independent files:

   o ${prefix}/tclX/7.3b - TclX runtime files.
   o ${prefix}/tkX/3.6b - TkX runtime files.
   o ${prefix}/include - Include files for TclX.
   o ${prefix}/man - Manual pages for TclX.

The variable "exec_prefix" is the path that will contain the directories
containing hardware and system dependent files:

   o ${exec_prefix}/bin - tcl, wishx and tclhelp programs.
   o ${exec_prefix}/lib - libtclx.a and libtkx.a

Both "exec_prefix" and "prefix" default to "/usr/local".  All of these
directories can be changed independently by editing "Config.mk".  To set
the prefix directories:

    ./configure --prefix=/usr/site  --exec_prefix==/usr/site.cray

With the standard model, only Extended Tcl files are installed.  Its is
assumed that the Tcl & Tk standard libraries, include files and manual
pages have been installed.

Master Directory Installation Model
-----------------------------------

The master directory model installs *all* files required by TclX (including
files from the Tcl and Tk distributions) in master directories.  

   o ${prefix}/tclX/7.3b - TclX runtime files.
   o ${prefix}/tclX/7.3b/include - Include files.
   o ${prefix}/tclX/7.3b/man - Manual pages.
   o ${prefix}/tclX/7.3b/bin - tcl program.
   o ${prefix}/tclX/7.3b/lib - libtclx.a and libtcl.a

   o ${prefix}/tkX/3.6b - TkX runtime files.
   o ${prefix}/tkX/3.6b/include - Include files.
   o ${prefix}/tkX/3.6b/man - Manual pages.
   o ${prefix}/tkX/3.6b/bin - wishx and tclhelp programs.
   o ${prefix}/tkX/3.6b/lib - libtkx.a and libtk.a

Symbolic links are then built for executables from the standard locations
to the files in the master directory.

   /usr/local/bin/tcl   -> /usr/local/tclX/7.3b/bin/tcl
   /usr/local/bin/wishx -> /usr/local/tkX/3.6b/bin/wishx


If the --with-arch=ARCH option was specified to configure (see below), the bin
and lib files are stored in architecture-dependent directories with the
specified architecture as a suffix to the directory name:

   o ${prefix}/tclX/7.3b/bin.arch
   o ${prefix}/tclX/7.3b/lib.arch
   o ${prefix}/tkX/3.6b/bin.arch
   o ${prefix}/tkX/3.6b/lib.arch

You may defined "arch" to be any string you like; it might include OS type or
version as well as processor architecture.

Symbolic links are still build from the standard locations of the machines
of specified architecture to the master directory:

   /usr/local/bin/tcl   -> /usr/local/tclX/7.3b/bin.sparc/tcl
   /usr/local/bin/wishx -> /usr/local/tkX/3.6b/bin.sparc/wishx

Symbolic links are also built for the include and library files in a similar
manner.  Due to the difficulty in getting it right, manual pages must be linked
by hand.
        
HOW TO BUILD EXTENDED TCL
=========================

    o Configure and compile Tcl 7.3 following the instructions that come with
      Tcl.  You do not need to install it.

    o If you are going to be using Tk and want to build an Extended Tcl wish
      shell (wishx), configure and compile Tk 3.6.  You do not need to install
      it.

    o Enter ./configure to run the configure script.  The following options are
      recognized by the TclX configure script:
 
        o --srcdir=DIR
          If you are using a make that supports VPATH (e.g. GNU make) you can
          use this to compile in a separate directory from the source.
          Note: The source directory must be clean, it can't contain a built
          copy of TclX.

        o --with-arch=ARCH
          If your are using the master directory installation model, this
          specifies the a suffix to use for the architecture-dependent
          directories under the master directory.  Use the --execprefix
          option for installing architecture-dependent under the standard
          installation model.

        o --prefix=PREFIX
          Directory under which the "include" and "man" directories are
          found for installation. 

        o --execprefix=EXECPREFIX
          Directory under which the "bin" and "lib" directories are
          found for installation.  

    o If you decide to change the --with-arch, --prefix or --execprefix,
      just rerun configure and make. The configure script will purge the
      minimum set of files that have to be rebuilt due to any of these
      changing.
 
    o Edit Config.mk in the build directory following the instructions in the
      file.  You normally don't need to do this, only if special configuration
      options are required.  If the --srcdir option to configure is used, it is
      copied from the source directory to the build directory.  This file is
      used to specify values that can't be figured out by the configure script.
      This includes the location of the Tcl and Tk distributions.  It's also
      used to specify the sections that the Tcl manual pages are to be
      installed in.

    o If you want to use the C++ classes provided in tcl++.h, edit Config.mk
      to define TCL_PLUS_BUILD.

    o Note that the site specific installation options should be set in
      Config.mk before compiling.  It is especially important to set the value
      for TCL_MASTERDIR and TK_MASTERDIR in Config.mk before compiling TclX.
      See the section on "Installing Extended Tcl" for more details.

    o Config.mk can be used to override several values that configure might
      have gotten wrong or that you desire to be change (like gcc vs cc).

    o Now do a "make".  If all goes well, this will build an extended
      "libtclx.a" and the "tcl" executable in the tclmaster directory.  If Tk
      is requested, an extended "libtkx.a" and "wishx" executable will be
      built in the tkmaster directory.

    o Until the Extended Tcl runtime files are installed, "tcl" and "wishx"
      can't be run directly.  To run them before installation, use "runtcl" or
      "runwishx".

    o Extended Tcl comes with help pages that are built from the Tcl 7.3 and
      Tk 3.6 manual pages as well as the TclX manual page.  If you are building
      TclX with a later version of Tcl or Tk, you might want to rebuild these
      manual pages.  If new manual pages have been added, you can add them
      by editing the files "tools/tclmanpages" and "tools/tkmanpages".
      You must have nroff and the man macro package installed on your system
      to build the manual pages.  Enter "make buildtclhelp" to build the
      Tcl and TclX help pages and "make buildtkhelp" to build the Tk manual
      pages or "make buildhelp" to build both.  If the help files are rebuilt,
      another make should be done to copy them into the master directories.

    o Note that if you modify any files in the Tcl or Tk library directories
      you need to do a "make clean" and a "make" to rebuild Extended Tcl,
      as these changes are not detected by the TclX make files.

   We have a limited number of systems available to test Extended Tcl on,
we need your help in supporting TclX on a wide range of platforms.  The nature
of the functionality TclX supports mean a great deal of system dependent code.
Thanks to all of those who have submitted configuration files and changes to
TclX.

TESTING EXTENDED TCL
====================

   There are three sets of tests: the tests for Berkeley Tcl, the tests for
Tk and the tests for Extended Tcl, which test both the new commands added by
Extended Tcl and the procedures defined in the Extended Tcl procedure
library.

    o Run both the Berkeley and TclX tests by typing "make test" in the
      tclX7.3b directory.  The some of the UCB tests require a tcl shell with
      added commands (tcltest in the tcl7.3 distribution).  Because the
      Extended TCL shell (tcl) does not have these commands, the you will
      receive warnings about not having the following commands:

        testasync
        testcmdinfo
        testdcall
        testdstring
        testlink

      Your will also receive warning about not having the following math
      functions:

        T1
        T2

    o To run the Tk tests with wishx, type "make tktest".  The tests require
      a tcl shell with added commands (tcltest in the tcl7.3 distribution).
      Because the Extended TCL shell (tcl) does not have these commands, the
      following tests will not run:

        raise.test

    o The Extended Tcl tests may be run by themselves with "make extdtests".

    o If a test fails, please dig into the test and the C source for the
      function being tested, fix the bug and mail us the change.  If you're
      not inclined to do this, please report the problem, including the output
      of the test, to tcl-project@neosoft.com.  Sometimes tests fail due to
      problems in the system environment or bugs in that test rather than
      problems with TclX.  Even if a few of the tests fail, you probably still
      have a working TclX.  See the "Porting Notes" section of this document
      for problems we have encountered.

    o If you're having trouble with the Berkeley tests, and you suspect that
      the extensions might be involved, you can build a special minimal
      version of Berkeley Tcl by cd'ing to the tcl7.3 directory and doing
      a "make test".  Similarly, you can do "make test" in the tk3.6 directory.

INSTALLING EXTENDED TCL
=======================

Standard Installation Model
---------------------------

To install Extended Tcl (and Tk if built) using the standard installation
model, enter:

   su use-to-own-files
   make install

to only install the executable and library files (useful for installing on
a multi-architecture server that has the rest of TclX already installed):

   su use-to-own-files
   make install-exec

Master Directory Installation Model
-----------------------------------
To install Extended Tcl (and Tk if built) using the master directory
installation model, enter:

   su use-to-own-files
   make install-master

to only install the executable and library files (useful for installing on
a multi-architecture server that has the rest of TclX already installed):

   su use-to-own-files
   make install-master-exec

SHARED LIBRARIES
================

   Shared libraries are not directly supported by the TclX build process,
since the mechanisms for building them are not portable across Unix
platforms.  See the file README.SHLIB for help in building shared libraries.
This file is oriented towards Suns.  If you have instructions on other
platforms, please contact us.


INTEGRATING PATCHES
===================

TclX copies and recomplies the following files:

   ${TCL_UCB_SRC}/tcl7.3/tclCmdIL.c to src/tclCmdIL.c
   ${TK_UCB_SRC/tk3.6/tkWindow.c to tksrc/tkWindow.c

If you patch either of these files, you must compile TclX.  The make rules
should take care of recompiling the correct files.  If you patch any of the
tcl or tk .h files, you should do a make clean and then a make of TclX.

These files are recompiled as they have compiled in paths to the library 
directories, which are different under TclX.  We are talking with John
Ousterhout about a solution.

INTEGRATING WITH OTHER EXTENSIONS AND APPLICATIONS
==================================================
  TclX is normally fairly easy to integrate with other applications and
extensions.  This section contains notes on the general approach, plus
notes on extensions that are a little tricky.

To integrate applications following the Tcl_AppInit conventions with TclX,
including the TclX library handling and shell:

    o Replace the call to "Tcl_Init" with a call to "TclX_Init" in the
      Tcl_AppInit function.

    o In Tk based application, replace the call to "TK_Init" with a call to
      "TkX_Init" in the Tcl_AppInit function.

    o Link with "-ltkx -ltk -ltclx -ltcl" in that order.  If you get strange
      behavior, such as no shell prompt, check this order.

To add just the TclX commands, but not the TclX library handling or shell
(including shell signal handling):

    o Add a call to "TclXCmd_Init" after the call to Tcl_Init in the
      Tcl_AppInit function.
   
    o Link with "-ltk -ltcl -ltclx" in that order.

If you need more details on how to initialize TclX, see the TclXInit(3) manual
page.

TkPixmap:
    o Build Tk with TkPixmap as directed.  You should have TkPixmap 3.6e or
      greater.

    o If TclX is already built, do a "rm -rf tkmaster".

    o Change the XLDLIBS line in Config.mk to:
        XLDLIBS=/full/path/to/libXpm.a

    o Configure and build TclX as directed.

    o If you want to have the pixmap documentation added to the TclX help
      pages (this is a slow process):

        o Added the line:
            {pinfo.n        tk/control/pinfo}
            {uxpm.n         tk/control/uxpm}
          to the list in tools/tkmanpages.

        o Do a "make buildtkhelp".

        o Do another "make"

PORTING NOTES
=============

General Porting Notes:
   o Flock tests hanging:  Problems have been encountered on some Sun
     systems with the flock tests.  This might occur on other systems as
     well.  These are probably due to an incorrectly configured NFS lockd.
     The tests have been modified to try and report problems rather than
     hang.  It might hang anyway, in this case, rename tests/flock.test to
     tests/flock.bad to prevent them from being run.  If anyone can give
     any clues into what is going on, we would love to detect this.

   o glob failures:  Don't add tcl7.3/compat/opendir.o to your libtcl.a unless
     you really don't have opendir on your system.  This will cause the glob
     command and TclX package libraries to fail.


DEC Ultrix:
   o Several tests fail when Tcl is run on an NFS mounted file system.
   o flock tests have been reported.  See `General Porting Notes' section
     above.

DEC Alpha:
   o message-cat-1.3 test fails due to broken catopen.  This is should not
     affect actual use of this command.
   o On OSF/1 V2.0 Rev 240 it has been noted that strtod segmentation faults
     when the first character of a string has the high order bit set. This
     breaks string expressions and eight bit characters.

SUN:
   o See note on flock tests hanging under the "general" section.

    
SOLARIS:
   o message-cat-1.3 test fails due to broken catopen.  This is should not
     affect actual use of this command.
   o tcllib-4.1 test fails.


SCO:
   o SCO Unix systems have a "ranlib" command that is used for Xenix cross-
     development.  Pre-ODT 3.0 development systems, the command returns
     an error if used on COFF files.  Many developers rename the command
     to "xranlib" if they are not doing cross development.  Later versions
     of the command return a warning if used on COFF binaries.


SGI:
   o There appears to be a compiler bug with some SGI compilers.
     If you see core dumps during the tests, recompile both Tcl and TclX
     without -O (make CFLAGS=).  This was seen on IRIX 4.0.5.

   o The strftime function does not work correctly on SGI (tested on
     IRIX 4.0.5).  This is a known bug and will be fixed in the next IRIX
     release.  The %I format specifier is broken.  The configure script 
     explictly checks for this version of IRIX and forces a functioning
     (but not internationalized) strftime to be built and added to libtclx.a.


BSDI:
   o The BSDI 1.0  make is broken.  It does not correctly handle the setting of
     ${MAKEFLAGS} and quits on an error when an empty make flags set is passed
     to the next level of make.  GNU make is advised instead.  Use the
     following make command to work around the problem:

          make -k MAKEFLAGS=k

   o BSDI 1.1 nice system call does not return an error on attempts to increase
     priority for non-root users.  This causes nice test 1.7 to fail.

   o Also seee the 386BSD/BSDI section below.


386BSD/NetBSD:
   o Expect round off errors in floating point math tests.
   o Expect errors in floating point math error handling tests.
   o Expect errors in format command tests.
   o The installation of the manual pages fails because make can't handle
     passing a empty string as an argument to a program (it deletes the
     string).  Try GNU make.
   o Also seee the 386BSD/BSDI section below.


386BSD/BSDI
   o There is some problem in the configure parsing of the --with-arch option.
     The syntax "./configure --arch=XXX" will not work, use
     "./configure --arch XXX" instead.


CONVEX:
   o Set both NOBUF and NONBLOCK on a pipe will result in read returning the
     the error "Errno is zero".

LINUX:
   o Some versions Linux are shipped with a catclose declaration
     in /usr/include/nl_types.h that returns type void rather than int.
     This does not follow the XPG/3 standard.  You must edit src/tclXmsgcat.c
     to ignore the return of catclose.  Also, please send mail to the Linux
     maintainers to get them to fix this.

CRAY:
   o catgets does not return the default string, causing failure of 
     some msgcat tests.
