QUICK START
===========

This section is a quick set of step by step instructions for building TclX
in the manner that addresses the needs of most users.   If you:

    o have built and installed  both Tcl and Tk and the built trees are in
     directories adjacent to the TclX source directory.  i.e.

                            mybuilddir/
                 tcl7.5/      tk4.1/      tclX7.5.0/
 
    o are installing under /usr/local.

    o don't care about NFS sharing to multiple arcitectures.

    o don't care about having multiple versions installed.

then the following steps will build, test and installed TclX:

    cd tclX7.5.0/unix
    configure          # add --enable-shared to build shared libraries
    make
    make test          # Run both standard and extended Tcl tests
    make tktest        # Run Tk tests with wishx
    make install

If you build with --enable-shared, Tcl and Tk must be built with
--enable-shared.
    
If you have a failure, check the "Porting Notes" section at the end of
this file.  If you still have problems, try to debug it as much as
possible and then contact us at tcl-project@neosoft.com.

If you want to customize your installation, read on.

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

Building the Extended Tcl requires access to built Tcl and Tk source
directories.  Their location relative to the tclX7.5.0 directory is
configured by editing tclX7.5.0/unix/Config.mk.

The following directories are included under the TclX directory:

  o unix - Build directory for Unix systems:
    o tools - Build tools.

  o tcl - TclX extensions to the Tcl language and the TclX shell:
    o generic - Source code that executes on multiple platforms.
    o tests - Test scripts.
    o compat - C library routines that are not available on all systems.
    o runtime - Run time Tcl code.
    o unix - Unix specific source code and build directory.

  o tk - TclX extensions to the Tk environment, including the wishx shell:
    o generic - Source code that executes on multiple platforms.
    o tests - Test scripts.
    o compat - C library routines that are not available on all systems.
    o runtime - Run time Tcl code.
    o unix - Unix specific source code and build directory.

  o doc - Unformatted manual pages for TclX.

HOW EXTENDED TCL IS INSTALLED 
=============================

There are two models for installing TclX, the GNU standard and the master
directory modes.

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

The basic approach to installing TclX follows the GNU standards.  Two
variables are defined on the configure command line, "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.5.0 - TclX runtime files.
   o ${prefix}/tkX/4.1.0 - 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

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.5.0/bin.ARCH
   o ${prefix}/tclX/7.5.0/lib.ARCH
   o ${prefix}/tkX/4.1.0/bin.ARCH
   o ${prefix}/tkX/4.1.0/lib.ARCH

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

With the master directory model, all TclX files are stored in the runtime
directory.  This approach makes it easy to move a complete distrbution
to other machines, store multiple versions of TclX on a system and remove
all of the files associated with an outdated version. 

The master directory model is specified by the --enable-master option to the
configure command.

The resulting directory layout is:

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

   o ${prefix}/tkX/4.1.0 - TkX runtime files.
   o ${prefix}/tkX/4.1.0/include - Include files.
   o ${prefix}/tkX/4.1.0/man - Manual pages.
   o ${prefix}/tkX/4.1.0/bin - wishx and tclhelp programs.
   o ${prefix}/tkX/4.1.0/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.5.0/bin/tcl
   /usr/local/bin/wishx -> /usr/local/tkX/4.1.0/bin/wishx

NOTE: Symbolic linking must currently be done manually by the user (but this
is easy with unix wildcards).   This was removed from the makefiles so that
it doesn't happen automaticly.

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.5.0/bin.arch
   o ${prefix}/tclX/7.5.0/lib.arch
   o ${prefix}/tkX/4.1.0/bin.arch
   o ${prefix}/tkX/4.1.0/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.5.0/bin.sparc/tcl
   /usr/local/bin/wishx -> /usr/local/tkX/4.1.0/bin.sparc/wishx

HOW TO BUILD EXTENDED TCL FOR UNIX SYSTEMS
==========================================

    o Configure, compile and install Tcl 7.5 following the instructions that
      come with Tcl. 

    o If you are going to be using Tk and want to build an Extended Tcl wish
      shell (wishx), configure, compile and install Tk 4.1.

    o cd to tclX7.5.0/unix

    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.  This must be done before running configure, as 
      configure uses this file to fine tclConfig.sh and tkConfig.sh.

    o Enter ./configure to run the configure script.  If you are going to
      be compiling with gcc, set the environment variable CC to "gcc".
      The following options are recognized by the TclX configure script:

        o --enable-shared=YES|NO
          If "YES", build and link with shared libraries if "NO", no shared
          libraries will be compiled.  Default is "NO".
 
        o --with-tk=YES|NO
          If "YES", compile Tk specific code and wishx, if "NO", no Tk related
          code will be compiled.  Default is "YES".
 
        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.  You
          must create a directory called "unix" in your build tree and run
          configure while in the "unix" directory.  The --srcdir argument must
          specify the "tclX7.5.0/unix" directory, not the top-level TclX 
          directory.
          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 --enable-master
          Configure for the master installation model.

    o If you decide to change the --with-arch, --prefix or --execprefix,
      just rerun configure and make.  The dependencies will cause the
      correct files to be built.
 
    o Now do a "make" to compile Tcl.  The following variables maybe passed
      to on the make command line to override values set by configure or in
      Config.mk:

         CC - The C compiler to use.
         CFLAGS - The optimization flags to pass to the C compiler.

     These variables are passed using a command line in the form:

         make CC=gcc CFLAGS="-O -g"

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

    o Extended Tcl comes with help pages that are built from the Tcl 7.5 and
      Tk 4.1 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 "unix/tools/tclmanpages" and "unix/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.

    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 helped debug 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 TclX tests by typing "make test" in the tclX7.5.0/unix directory.
      This runs both the TclX specific tests and an the Tcl tests though
      a interpreter built with TclX.

    o To run the Tk tests with wishx, type "make tktest".

    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.5 directory and doing
      a "make test".  Similarly, you can do "make test" in the tk4.1 directory.
      If the test works with standard Tcl or Tk and fails with TclX, contact
      us.

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

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

   su user-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 user-to-own-files
   make install-exec

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

   Shared libraries can be build for all systems that Tcl supports shared
libraries on.  The --enable-shared flag to configure generates TclX shared
libraries and links the TclX shells with shared libraries.

INTEGRATING WITH OTHER EXTENSIONS AND APPLICATIONS
==================================================

  See the manual page TclXInit.3 for details on how to add TclX to an
existing application.

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

General Porting Notes:
   o Flock test hanging:  Running the flock tests on a tmpfs filesystem will
     cause flock failures on some systems.

   o Other 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.


SVR3 systems (14 character file name limit):
   o All critical files in TclX are 14 characters or less.  A few help
     files are longer that 14 characters.  If these can be extracted with
     name truncation, they can still be referenced in the help system by the
     truncated name.  If they can't be extracted, then they can be regenerated
     with truncated names by doing a "make buildhelp".


DEC Ultrix:
   o Setting O_APPEND via the fcntl FSETFL system call returns an EOPNOTSUPP
     (Operation not supported) error.  This causes failures of fcntl tests
     2.4 and 2.5. This is an Ultrix bug as far as we can tell.

   o The fstat system call does does not return updated modification times on
     an open file.  This causes fstat test 3.1 to fail. This is an Ultrix bug.

   o Several tests fail when Tcl is run on an NFS mounted file system.

   o Problems with flock tests have been reported on some Ultrix systems.  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.


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


SOLARIS:
   o glob & library test failures observed on SunOS 5.3. Doing a "glob *"
     in either the tclX shell or tclsh produces a mangled listing of the
     directory.  This is caused by a mismatch between the the dirent.h
     include file and C library that is being used.  We have been told
     that this can be fixed either by making sure /usr/ucb is not in your
     path or by compiling with the "ucbcc" command.  If you chose to use
     ucbcc, remember to set CC=ucbcc environment variable, make clean, and
     reconfigure before going a "make CC=ucbcc". Using gcc is another
     solution.

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


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 Systems upgraded to IRIX 5.2 may have old versions of libsocket.a and
     libnsl.a left on the system.  The configure  will pick these up and 
     attempt to use them.  This will prevent wishx from connecting to the
     display.   Either remove the files from the system or edit the makefiles
     to remove the use of "-lsocket -lnsl".

   o The fstat system call does does not return updated modification times on
     an open NFS accessed file.  This causes fstat test 3.1 to fail.
     This is an IRIX bug.

  
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.

   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.


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 NetBSD 1.0 declares catclose as returning void rather than int. This is
     checked for in configure but still causes the message-cat-2.4 test
     to fail.


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


LINUX:
   o If shell scripts run in make file exit with exit code 127, a new
     version of Bash is needed.
   o Received error:  ld: Output file requires shared library `libc.so.4'
     gcc: Internal compiler error: program ld got fatal signal 6:
     Recompile without -g.


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