INSTALLATION INSTRUCTIONS FOR EXTENDED TCL ON UNIX AND UNIX-LIKE SYSTEMS ------------------------------------------------------------------------ $Id: INSTALL,v 8.9 1997/11/28 20:41:08 markd Exp $ COMPATIBILITY ============= This version is compatible Tcl 8.0p2 and Tk 8.0p2. 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/ tcl8.0/ tk8.0/ tclX8.0.2/ o are installing under /usr/local. o don't care about NFS sharing to multiple arcitectures. ...then the following steps will build, test and install TclX: cd tclX8.0.2/unix configure # add --enable-shared to build shared libraries # If there are patches in tclX8.0.2/TCL-REQUIRED-PATCHES: make patch-tcl-core make make test # Run both standard and extended Tcl tests make tktest # Run Tk tests with wishx make install 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 ======================================= To successfully build and install Extended Tcl, you must have already built Tcl and Tk, and make their built source trees available to Extended Tcl during the build process. Their location relative to the tclX8.0.2 directory is configured by editing tclX8.0.2/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. REQUIRED PATCHES ================ In some releases of Extended Tcl, particularly beta releases, it is sometimes necessary for us to ship patches to the Tcl core to fix or work around a problem, etc. These patches usually come from postings to the comp.lang.tcl newsgroup made by the Sunscript team. If any patches are included in this package's TCL-REQUIRED-PATCHES directory, they must be installed into the corresponding version of Tcl you're building with. You may either install the patches by hand, or, go ahead and cd to "unix" and configure TclX. This will put a rule in your tclX8.0b1/unix/Makefile where you can then say "make patch-tcl-core" to make the patches on the Tcl core. If any patch is reversed or has already been applied, it is ignored. HOW TO BUILD EXTENDED TCL FOR UNIX SYSTEMS ========================================== o Configure, compile and install Tcl 8.0 following the instructions that come with Tcl. Tcl 8.0 can be obtained from ftp://ftp.smli.com/pub/tcl/ ftp://mirror.neosoft.com/pub/tcl/mirror/ftp.smli.com/ o If you are going to be using Tk and want to build an Extended Tcl wish shell (wishx), you will also need to configure, compile and install Tk 8.0. Generic instructions on how to build and work worth packages configured by "configure" scripts may be found in the file INSTALL.generic, located in the same directory as the file you are currently reading. o If there are patchs in tclX8.0.2/TCL-REQUIRED-PATCHES, then install these patches to Tcl and rebuild it. o After building and installing Tcl and Tk, cd to tclX8.0.2/unix o Edit Config.mk in the build directory following the instructions in the file. You normally won't need to change anything, unless you require any special configuration options. If the --srcdir option to configure is used, Config.mk 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". If you say "--enable-shared" with no argument, it enables building shared libraries. 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 "tclX8.0.2/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 --prefix=PREFIX Directory under which the "include" and "man" directories are found for installation. o --exec-prefix=EXECPREFIX Directory under which the "bin" and "lib" directories are found for installation. o If you decide to change the --prefix or --exec-prefix option, just rerun configure and make. The dependencies will cause the correct files to be built. o Now do a "make" to compile TclX. 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 8.0 and Tk 8.0 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. HELP... AND THANKS ================== We have access to a few different platforms to test Extended Tcl on, but we need your help in supporting TclX on a wide range of systems. As Extended Tcl hooks into many of the trickier nooks and crannies of your operating system, there is quite a bit of system-dependent code, and it took us much fiddling with the configure script to get it right... or mostly right. 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 tclX8.0.2/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 testx". 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 tcl8.0 directory and doing a "make test". Similarly, you can do "make test" in the tk8.0 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 built for all systems that Tcl supports shared libraries on. The --enable-shared flag to configure generates TclX shared libraries. PLUS-PATCHES ============ If Jan Nijtmans' Plus patch is applied to Tcl, TclX will automatically generate standalone object in the static (.a) library. This allows building applications with no external dependencies. The following additional make targets are also available: o standalone - Generate standalone executables, tcl.standalone and wishx.standalone. o test.standalone - Run the tests using the standalone executables. See http://www.worldaccess.nl/~nijtmans/plus.html for the Plus patches. INTEGRATING WITH OTHER EXTENSIONS AND APPLICATIONS ================================================== See the manual page TclX_Init.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. o compat/server tests 8.2.8 and 8.2.22 fail on Solaris 2.4 and maybe earlier. This appears to be a bug in the Solaris kernal related to dup-ing sockets. The problem does not occur in Solaris 2.5.1. 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. 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.