home *** CD-ROM | disk | FTP | other *** search
/ Serving the Web / ServingTheWeb1995.disc1of1.iso / linux / slacksrce / tcl / tcl+tk+t / tclx7.3bl / tclx7 / tclX7.3b / INSTALL < prev    next >
Encoding:
Text File  |  1994-07-16  |  19.0 KB  |  488 lines
  1. EXTENDED TCL SOURCE DIRECTORY HIERARCHY
  2. =======================================
  3.  
  4. Building the Extended Tcl requires access to built Tcl and Tk source
  5. directories.  Their location relative to the tclX7.3b directory must be
  6. configured by editing tclX7.3b/Config.mk.  The default is to place tclX7.3b
  7. in a directory parallel to the Tcl and Tk distributions:
  8.  
  9.                    tcl7.3      tk3.6      tclX7.3b
  10.  
  11.  
  12. The following directories are included under the tclX7.3b directory:
  13.  
  14.     o man - Unformatted manual pages for TclX.
  15.  
  16.     o src - The main source for TclX.
  17.  
  18.     o osSupport - Library routines required by TclX that may not be available
  19.       on all Unix versions.
  20.  
  21.     o tclsrc - Tcl source that is built into the standard Tcl package library.
  22.       The makefile also handles generation of help files.
  23.  
  24.     o tests - Tests for TclX.
  25.  
  26.     o tclhelp - The Tcl and TclX help files.  These can be rebuilt from the
  27.       manual pages if necessary.
  28.  
  29.     o tksrc - A makefile that builds a version of the Tk wish shell containing
  30.       Extended Tcl.
  31.  
  32.     o tktclsrc - Tcl source that is built into the standard Tk package library.
  33.       The makefile also handles generation of help files.
  34.  
  35.     o tktests - Files used to test wishx.
  36.  
  37.     o tkhelp - The Tk help files.  These can be rebuilt from the manual pages
  38.       if necessary.
  39.  
  40.     o tools - Tools used for building and installing TclX.
  41.  
  42.     o tclmaster - Tcl master directory.  All files required to run TclX are
  43.       built or copied into this directory.  The entire contents of this
  44.       directory are installed.  This directory is created by the build, it is
  45.       not part of the distribution.
  46.  
  47.     o tkmaster - Tk master directory.  All files required to run Tk
  48.       are built or copied into this directory.  The entire contents of
  49.       this directory are installed.  This directory is created by the build,
  50.       it is not part of the distribution.
  51.  
  52. THE EXTENDED TCL INSTALLATION MODELS
  53. ====================================
  54.  
  55. Two installation models are supported by Extended Tcl.  You should decide which
  56. model you are going to use before building TclX.  We encourage use of the 
  57. "master directory" model, as it supports multiple versions of Extended Tcl and
  58. Tk being installed on the system at the same time and allows for easy copying
  59. to other systems.
  60.  
  61. Standard Installation Model
  62. ---------------------------
  63.  
  64. The standard model follows the GNU standards.  Two variables are defined
  65. by configure, "prefix" and "exec_prefix".  The variable "prefix" is the
  66. path that will contain the directories containing hardware and system
  67. independent files:
  68.  
  69.    o ${prefix}/tclX/7.3b - TclX runtime files.
  70.    o ${prefix}/tkX/3.6b - TkX runtime files.
  71.    o ${prefix}/include - Include files for TclX.
  72.    o ${prefix}/man - Manual pages for TclX.
  73.  
  74. The variable "exec_prefix" is the path that will contain the directories
  75. containing hardware and system dependent files:
  76.  
  77.    o ${exec_prefix}/bin - tcl, wishx and tclhelp programs.
  78.    o ${exec_prefix}/lib - libtclx.a and libtkx.a
  79.  
  80. Both "exec_prefix" and "prefix" default to "/usr/local".  All of these
  81. directories can be changed independently by editing "Config.mk".  To set
  82. the prefix directories:
  83.  
  84.     ./configure --prefix=/usr/site  --exec_prefix==/usr/site.cray
  85.  
  86. With the standard model, only Extended Tcl files are installed.  Its is
  87. assumed that the Tcl & Tk standard libraries, include files and manual
  88. pages have been installed.
  89.  
  90. Master Directory Installation Model
  91. -----------------------------------
  92.  
  93. The master directory model installs *all* files required by TclX (including
  94. files from the Tcl and Tk distributions) in master directories.  
  95.  
  96.    o ${prefix}/tclX/7.3b - TclX runtime files.
  97.    o ${prefix}/tclX/7.3b/include - Include files.
  98.    o ${prefix}/tclX/7.3b/man - Manual pages.
  99.    o ${prefix}/tclX/7.3b/bin - tcl program.
  100.    o ${prefix}/tclX/7.3b/lib - libtclx.a and libtcl.a
  101.  
  102.    o ${prefix}/tkX/3.6b - TkX runtime files.
  103.    o ${prefix}/tkX/3.6b/include - Include files.
  104.    o ${prefix}/tkX/3.6b/man - Manual pages.
  105.    o ${prefix}/tkX/3.6b/bin - wishx and tclhelp programs.
  106.    o ${prefix}/tkX/3.6b/lib - libtkx.a and libtk.a
  107.  
  108. Symbolic links are then built for executables from the standard locations
  109. to the files in the master directory.
  110.  
  111.    /usr/local/bin/tcl   -> /usr/local/tclX/7.3b/bin/tcl
  112.    /usr/local/bin/wishx -> /usr/local/tkX/3.6b/bin/wishx
  113.  
  114.  
  115. If the --with-arch=ARCH option was specified to configure (see below), the bin
  116. and lib files are stored in architecture-dependent directories with the
  117. specified architecture as a suffix to the directory name:
  118.  
  119.    o ${prefix}/tclX/7.3b/bin.arch
  120.    o ${prefix}/tclX/7.3b/lib.arch
  121.    o ${prefix}/tkX/3.6b/bin.arch
  122.    o ${prefix}/tkX/3.6b/lib.arch
  123.  
  124. You may defined "arch" to be any string you like; it might include OS type or
  125. version as well as processor architecture.
  126.  
  127. Symbolic links are still build from the standard locations of the machines
  128. of specified architecture to the master directory:
  129.  
  130.    /usr/local/bin/tcl   -> /usr/local/tclX/7.3b/bin.sparc/tcl
  131.    /usr/local/bin/wishx -> /usr/local/tkX/3.6b/bin.sparc/wishx
  132.  
  133. Symbolic links are also built for the include and library files in a similar
  134. manner.  Due to the difficulty in getting it right, manual pages must be linked
  135. by hand.
  136.         
  137. HOW TO BUILD EXTENDED TCL
  138. =========================
  139.  
  140.     o Configure and compile Tcl 7.3 following the instructions that come with
  141.       Tcl.  You do not need to install it.
  142.  
  143.     o If you are going to be using Tk and want to build an Extended Tcl wish
  144.       shell (wishx), configure and compile Tk 3.6.  You do not need to install
  145.       it.
  146.  
  147.     o Enter ./configure to run the configure script.  The following options are
  148.       recognized by the TclX configure script:
  149.  
  150.         o --srcdir=DIR
  151.           If you are using a make that supports VPATH (e.g. GNU make) you can
  152.           use this to compile in a separate directory from the source.
  153.           Note: The source directory must be clean, it can't contain a built
  154.           copy of TclX.
  155.  
  156.         o --with-arch=ARCH
  157.           If your are using the master directory installation model, this
  158.           specifies the a suffix to use for the architecture-dependent
  159.           directories under the master directory.  Use the --execprefix
  160.           option for installing architecture-dependent under the standard
  161.           installation model.
  162.  
  163.         o --prefix=PREFIX
  164.           Directory under which the "include" and "man" directories are
  165.           found for installation. 
  166.  
  167.         o --execprefix=EXECPREFIX
  168.           Directory under which the "bin" and "lib" directories are
  169.           found for installation.  
  170.  
  171.     o If you decide to change the --with-arch, --prefix or --execprefix,
  172.       just rerun configure and make. The configure script will purge the
  173.       minimum set of files that have to be rebuilt due to any of these
  174.       changing.
  175.  
  176.     o Edit Config.mk in the build directory following the instructions in the
  177.       file.  You normally don't need to do this, only if special configuration
  178.       options are required.  If the --srcdir option to configure is used, it is
  179.       copied from the source directory to the build directory.  This file is
  180.       used to specify values that can't be figured out by the configure script.
  181.       This includes the location of the Tcl and Tk distributions.  It's also
  182.       used to specify the sections that the Tcl manual pages are to be
  183.       installed in.
  184.  
  185.     o If you want to use the C++ classes provided in tcl++.h, edit Config.mk
  186.       to define TCL_PLUS_BUILD.
  187.  
  188.     o Note that the site specific installation options should be set in
  189.       Config.mk before compiling.  It is especially important to set the value
  190.       for TCL_MASTERDIR and TK_MASTERDIR in Config.mk before compiling TclX.
  191.       See the section on "Installing Extended Tcl" for more details.
  192.  
  193.     o Config.mk can be used to override several values that configure might
  194.       have gotten wrong or that you desire to be change (like gcc vs cc).
  195.  
  196.     o Now do a "make".  If all goes well, this will build an extended
  197.       "libtclx.a" and the "tcl" executable in the tclmaster directory.  If Tk
  198.       is requested, an extended "libtkx.a" and "wishx" executable will be
  199.       built in the tkmaster directory.
  200.  
  201.     o Until the Extended Tcl runtime files are installed, "tcl" and "wishx"
  202.       can't be run directly.  To run them before installation, use "runtcl" or
  203.       "runwishx".
  204.  
  205.     o Extended Tcl comes with help pages that are built from the Tcl 7.3 and
  206.       Tk 3.6 manual pages as well as the TclX manual page.  If you are building
  207.       TclX with a later version of Tcl or Tk, you might want to rebuild these
  208.       manual pages.  If new manual pages have been added, you can add them
  209.       by editing the files "tools/tclmanpages" and "tools/tkmanpages".
  210.       You must have nroff and the man macro package installed on your system
  211.       to build the manual pages.  Enter "make buildtclhelp" to build the
  212.       Tcl and TclX help pages and "make buildtkhelp" to build the Tk manual
  213.       pages or "make buildhelp" to build both.  If the help files are rebuilt,
  214.       another make should be done to copy them into the master directories.
  215.  
  216.     o Note that if you modify any files in the Tcl or Tk library directories
  217.       you need to do a "make clean" and a "make" to rebuild Extended Tcl,
  218.       as these changes are not detected by the TclX make files.
  219.  
  220.    We have a limited number of systems available to test Extended Tcl on,
  221. we need your help in supporting TclX on a wide range of platforms.  The nature
  222. of the functionality TclX supports mean a great deal of system dependent code.
  223. Thanks to all of those who have submitted configuration files and changes to
  224. TclX.
  225.  
  226. TESTING EXTENDED TCL
  227. ====================
  228.  
  229.    There are three sets of tests: the tests for Berkeley Tcl, the tests for
  230. Tk and the tests for Extended Tcl, which test both the new commands added by
  231. Extended Tcl and the procedures defined in the Extended Tcl procedure
  232. library.
  233.  
  234.     o Run both the Berkeley and TclX tests by typing "make test" in the
  235.       tclX7.3b directory.  The some of the UCB tests require a tcl shell with
  236.       added commands (tcltest in the tcl7.3 distribution).  Because the
  237.       Extended TCL shell (tcl) does not have these commands, the you will
  238.       receive warnings about not having the following commands:
  239.  
  240.         testasync
  241.         testcmdinfo
  242.         testdcall
  243.         testdstring
  244.         testlink
  245.  
  246.       Your will also receive warning about not having the following math
  247.       functions:
  248.  
  249.         T1
  250.         T2
  251.  
  252.     o To run the Tk tests with wishx, type "make tktest".  The tests require
  253.       a tcl shell with added commands (tcltest in the tcl7.3 distribution).
  254.       Because the Extended TCL shell (tcl) does not have these commands, the
  255.       following tests will not run:
  256.  
  257.         raise.test
  258.  
  259.     o The Extended Tcl tests may be run by themselves with "make extdtests".
  260.  
  261.     o If a test fails, please dig into the test and the C source for the
  262.       function being tested, fix the bug and mail us the change.  If you're
  263.       not inclined to do this, please report the problem, including the output
  264.       of the test, to tcl-project@neosoft.com.  Sometimes tests fail due to
  265.       problems in the system environment or bugs in that test rather than
  266.       problems with TclX.  Even if a few of the tests fail, you probably still
  267.       have a working TclX.  See the "Porting Notes" section of this document
  268.       for problems we have encountered.
  269.  
  270.     o If you're having trouble with the Berkeley tests, and you suspect that
  271.       the extensions might be involved, you can build a special minimal
  272.       version of Berkeley Tcl by cd'ing to the tcl7.3 directory and doing
  273.       a "make test".  Similarly, you can do "make test" in the tk3.6 directory.
  274.  
  275. INSTALLING EXTENDED TCL
  276. =======================
  277.  
  278. Standard Installation Model
  279. ---------------------------
  280.  
  281. To install Extended Tcl (and Tk if built) using the standard installation
  282. model, enter:
  283.  
  284.    su use-to-own-files
  285.    make install
  286.  
  287. to only install the executable and library files (useful for installing on
  288. a multi-architecture server that has the rest of TclX already installed):
  289.  
  290.    su use-to-own-files
  291.    make install-exec
  292.  
  293. Master Directory Installation Model
  294. -----------------------------------
  295. To install Extended Tcl (and Tk if built) using the master directory
  296. installation model, enter:
  297.  
  298.    su use-to-own-files
  299.    make install-master
  300.  
  301. to only install the executable and library files (useful for installing on
  302. a multi-architecture server that has the rest of TclX already installed):
  303.  
  304.    su use-to-own-files
  305.    make install-master-exec
  306.  
  307. SHARED LIBRARIES
  308. ================
  309.  
  310.    Shared libraries are not directly supported by the TclX build process,
  311. since the mechanisms for building them are not portable across Unix
  312. platforms.  See the file README.SHLIB for help in building shared libraries.
  313. This file is oriented towards Suns.  If you have instructions on other
  314. platforms, please contact us.
  315.  
  316.  
  317. INTEGRATING PATCHES
  318. ===================
  319.  
  320. TclX copies and recomplies the following files:
  321.  
  322.    ${TCL_UCB_SRC}/tcl7.3/tclCmdIL.c to src/tclCmdIL.c
  323.    ${TK_UCB_SRC/tk3.6/tkWindow.c to tksrc/tkWindow.c
  324.  
  325. If you patch either of these files, you must compile TclX.  The make rules
  326. should take care of recompiling the correct files.  If you patch any of the
  327. tcl or tk .h files, you should do a make clean and then a make of TclX.
  328.  
  329. These files are recompiled as they have compiled in paths to the library 
  330. directories, which are different under TclX.  We are talking with John
  331. Ousterhout about a solution.
  332.  
  333. INTEGRATING WITH OTHER EXTENSIONS AND APPLICATIONS
  334. ==================================================
  335.   TclX is normally fairly easy to integrate with other applications and
  336. extensions.  This section contains notes on the general approach, plus
  337. notes on extensions that are a little tricky.
  338.  
  339. To integrate applications following the Tcl_AppInit conventions with TclX,
  340. including the TclX library handling and shell:
  341.  
  342.     o Replace the call to "Tcl_Init" with a call to "TclX_Init" in the
  343.       Tcl_AppInit function.
  344.  
  345.     o In Tk based application, replace the call to "TK_Init" with a call to
  346.       "TkX_Init" in the Tcl_AppInit function.
  347.  
  348.     o Link with "-ltkx -ltk -ltclx -ltcl" in that order.  If you get strange
  349.       behavior, such as no shell prompt, check this order.
  350.  
  351. To add just the TclX commands, but not the TclX library handling or shell
  352. (including shell signal handling):
  353.  
  354.     o Add a call to "TclXCmd_Init" after the call to Tcl_Init in the
  355.       Tcl_AppInit function.
  356.    
  357.     o Link with "-ltk -ltcl -ltclx" in that order.
  358.  
  359. If you need more details on how to initialize TclX, see the TclXInit(3) manual
  360. page.
  361.  
  362. TkPixmap:
  363.     o Build Tk with TkPixmap as directed.  You should have TkPixmap 3.6e or
  364.       greater.
  365.  
  366.     o If TclX is already built, do a "rm -rf tkmaster".
  367.  
  368.     o Change the XLDLIBS line in Config.mk to:
  369.         XLDLIBS=/full/path/to/libXpm.a
  370.  
  371.     o Configure and build TclX as directed.
  372.  
  373.     o If you want to have the pixmap documentation added to the TclX help
  374.       pages (this is a slow process):
  375.  
  376.         o Added the line:
  377.             {pinfo.n        tk/control/pinfo}
  378.             {uxpm.n         tk/control/uxpm}
  379.           to the list in tools/tkmanpages.
  380.  
  381.         o Do a "make buildtkhelp".
  382.  
  383.         o Do another "make"
  384.  
  385. PORTING NOTES
  386. =============
  387.  
  388. General Porting Notes:
  389.    o Flock tests hanging:  Problems have been encountered on some Sun
  390.      systems with the flock tests.  This might occur on other systems as
  391.      well.  These are probably due to an incorrectly configured NFS lockd.
  392.      The tests have been modified to try and report problems rather than
  393.      hang.  It might hang anyway, in this case, rename tests/flock.test to
  394.      tests/flock.bad to prevent them from being run.  If anyone can give
  395.      any clues into what is going on, we would love to detect this.
  396.  
  397.    o glob failures:  Don't add tcl7.3/compat/opendir.o to your libtcl.a unless
  398.      you really don't have opendir on your system.  This will cause the glob
  399.      command and TclX package libraries to fail.
  400.  
  401.  
  402. DEC Ultrix:
  403.    o Several tests fail when Tcl is run on an NFS mounted file system.
  404.    o flock tests have been reported.  See `General Porting Notes' section
  405.      above.
  406.  
  407. DEC Alpha:
  408.    o message-cat-1.3 test fails due to broken catopen.  This is should not
  409.      affect actual use of this command.
  410.    o On OSF/1 V2.0 Rev 240 it has been noted that strtod segmentation faults
  411.      when the first character of a string has the high order bit set. This
  412.      breaks string expressions and eight bit characters.
  413.  
  414. SUN:
  415.    o See note on flock tests hanging under the "general" section.
  416.  
  417.     
  418. SOLARIS:
  419.    o message-cat-1.3 test fails due to broken catopen.  This is should not
  420.      affect actual use of this command.
  421.    o tcllib-4.1 test fails.
  422.  
  423.  
  424. SCO:
  425.    o SCO Unix systems have a "ranlib" command that is used for Xenix cross-
  426.      development.  Pre-ODT 3.0 development systems, the command returns
  427.      an error if used on COFF files.  Many developers rename the command
  428.      to "xranlib" if they are not doing cross development.  Later versions
  429.      of the command return a warning if used on COFF binaries.
  430.  
  431.  
  432. SGI:
  433.    o There appears to be a compiler bug with some SGI compilers.
  434.      If you see core dumps during the tests, recompile both Tcl and TclX
  435.      without -O (make CFLAGS=).  This was seen on IRIX 4.0.5.
  436.  
  437.    o The strftime function does not work correctly on SGI (tested on
  438.      IRIX 4.0.5).  This is a known bug and will be fixed in the next IRIX
  439.      release.  The %I format specifier is broken.  The configure script 
  440.      explictly checks for this version of IRIX and forces a functioning
  441.      (but not internationalized) strftime to be built and added to libtclx.a.
  442.  
  443.  
  444. BSDI:
  445.    o The BSDI 1.0  make is broken.  It does not correctly handle the setting of
  446.      ${MAKEFLAGS} and quits on an error when an empty make flags set is passed
  447.      to the next level of make.  GNU make is advised instead.  Use the
  448.      following make command to work around the problem:
  449.  
  450.           make -k MAKEFLAGS=k
  451.  
  452.    o BSDI 1.1 nice system call does not return an error on attempts to increase
  453.      priority for non-root users.  This causes nice test 1.7 to fail.
  454.  
  455.    o Also seee the 386BSD/BSDI section below.
  456.  
  457.  
  458. 386BSD/NetBSD:
  459.    o Expect round off errors in floating point math tests.
  460.    o Expect errors in floating point math error handling tests.
  461.    o Expect errors in format command tests.
  462.    o The installation of the manual pages fails because make can't handle
  463.      passing a empty string as an argument to a program (it deletes the
  464.      string).  Try GNU make.
  465.    o Also seee the 386BSD/BSDI section below.
  466.  
  467.  
  468. 386BSD/BSDI
  469.    o There is some problem in the configure parsing of the --with-arch option.
  470.      The syntax "./configure --arch=XXX" will not work, use
  471.      "./configure --arch XXX" instead.
  472.  
  473.  
  474. CONVEX:
  475.    o Set both NOBUF and NONBLOCK on a pipe will result in read returning the
  476.      the error "Errno is zero".
  477.  
  478. LINUX:
  479.    o Some versions Linux are shipped with a catclose declaration
  480.      in /usr/include/nl_types.h that returns type void rather than int.
  481.      This does not follow the XPG/3 standard.  You must edit src/tclXmsgcat.c
  482.      to ignore the return of catclose.  Also, please send mail to the Linux
  483.      maintainers to get them to fix this.
  484.  
  485. CRAY:
  486.    o catgets does not return the default string, causing failure of 
  487.      some msgcat tests.
  488.