1Tk UNIX README
2--------------
3
4This is the directory where you configure, compile, test, and install UNIX
5versions of Tk. This directory also contains source files for Tk that are
6specific to UNIX.
7
8The information in this file is maintained at:
9 http://www.tcl.tk/doc/howto/compile.html
10
11For information on platforms where Tcl/Tk is known to compile, along with any
12porting notes for getting it to work on those platforms, see:
13 http://www.tcl.tk/software/tcltk/platforms.html
14
15The rest of this file contains instructions on how to do this. The release
16should compile and run either "out of the box" or with trivial changes on any
17UNIX-like system that approximates POSIX, BSD, or System V. We know that it
18runs on workstations from Sun, H-P, DEC, IBM, and SGI, as well as PCs running
19Linux, BSDI, and SCO UNIX. To compile for a PC running Windows, see the README
20file in the directory ../win. To compile for MacOSX, see the README file in
21the directory ../macosx.
22
23RCS: @(#) $Id$
24
25How To Compile And Install Tk:
26------------------------------
27
28(a) Make sure that the Tcl release is present in the directory
29 ../../tcl<version> (or else use the "--with-tcl" switch described below).
30 This release of Tk will only work with the equivalently versioned Tcl
31 release. Also, be sure that you have configured Tcl before you configure
32 Tk.
33
34(b) Check for patches as described in ../README.
35
36(c) If you have already compiled Tk once in this directory and are now
37 preparing to compile again in the same directory but for a different
38 platform, or if you have applied patches, type "make distclean" to discard
39 all the configuration information computed previously.
40
41(d) Type "./configure". This runs a configuration script created by GNU
42 autoconf, which configures Tk for your system and creates a Makefile. The
43 configure script allows you to customize the Tk configuration for your
44 site; for details on how you can do this, type "./configure -help" or
45 refer to the autoconf documentation (not included here). Tk's "configure"
46 script supports the following special switches in addition to the standard
47 ones:
48
49 --with-tcl=DIR Specifies the directory containing the Tcl
50 binaries and Tcl's platform-dependent
51 configuration information. By default the Tcl
52 directory is assumed to be in the location
53 given by (a) above.
54 --with-x=DIR Tells configure where to find an installation
55 of the X Window System. Not normally needed.
56 --enable-threads If this switch is set, Tk will compile itself
57 with multithreading support.
58 --enable-shared If this switch is specified, Tk will compile
59 itself as a shared library if it can figure
60 out how to do that on this platform. This is
61 the default on platforms where we know how to
62 build shared libraries.
63 --disable-shared If this switch is specified, Tk will compile
64 itself as a static library.
65 --disable-rpath Turns off use of the rpath link option on
66 platforms that would otherwise use it.
67 --enable-symbols Build with debugging symbols. By default
68 standard debugging symbols are used. You can
69 specify the value "mem" to include
70 TCL_MEM_DEBUG memory debugging.
71 --disable-symbols Build without debugging symbols
72 --enable-64bit Enable 64bit support (where applicable)
73 --disable-64bit Disable 64bit support (where applicable)
74 --enable-64bit-vis Enable 64bit Sparc VIS support
75 --disable-64bit-vis Disable 64bit Sparc VIS support
76 --disable-xft Disable support for antialiased fonts via the
77 Freetype/xft library. By default, this is
78 switched on whenever the configure script can
79 detect the required libraries.
80 --enable-man-symlinks Use symlinks for linking the manpages that
81 should be reachable under several names.
82 --enable-man-compression=PROG
83 Compress the manpages using PROG.
84 --enable-man-suffix=STRING
85 Add STRING to the name of each of the manual
86 pages. If specified without giving STRING, the
87 suffix will be "tk".
88
89 Mac OS X only:
90
91 --enable-framework Package Tk as a framework.
92 --disable-corefoundation Disable use of CoreFoundation API.
93 --enable-aqua Use Aqua windowingsystem rather than X11,
94 requires --enable-corefoundation with Tcl and
95 Tk.
96
97 Note: by default gcc will be used if it can be located on the PATH. If you
98 want to use cc instead of gcc, set the CC environment variable to "cc"
99 before running configure. It is not safe to change the Makefile to use gcc
100 after configure is run.
101
102 Note: be sure to use only absolute path names (those starting with "/") in
103 the --prefix and --exec-prefix options.
104
105(e) Type "make". This will create a library archive called "libtk<version>.a"
106 or "libtk<version>.so" and an interpreter application called "wish" that
107 allows you to type Tcl/Tk commands interactively or execute script files.
108 It will also create a stub library archive "libtkstub<version>.a" that
109 developers may link against other C code to produce loadable extensions
110 that call into Tk's public interface routines.
111
112(f) If the make fails then you'll have to personalize the Makefile for your
113 site or possibly modify the distribution in other ways. First check the
114 porting Web page above to see if there are hints for compiling on your
115 system. If you need to modify Makefile, there are comments at the
116 beginning of it that describe the things you might want to change and how
117 to change them.
118
119(g) Type "make install" to install Tk's binaries and script files in standard
120 places. You'll need write permission on the installation directories to do
121 this. The installation directories are determined by the "configure"
122 script and may be specified with the --prefix and --exec-prefix options to
123 "configure". See the Makefile for information on what directories were
124 chosen. You should not override these choices by modifying the Makefile,
125 or by copying files post-install. The installed binaries have embedded
126 within them path values relative to the install directory. If you change
127 your mind about where Tk should be installed, start this procedure over
128 again from step (a) so that the path embedded in the binaries agrees with
129 the install location.
130
131(h) At this point you can play with Tk by running the installed "wish"
132 executable, or via the "make shell" target, and typing Tcl/Tk commands at
133 the interactive prompt.
134
135If you have trouble compiling Tk, see the URL noted above about working
136platforms. It contains information that people have provided about changes
137they had to make to compile Tk in various environments. We're also interested
138in hearing how to change the configuration setup so that Tk compiles on
139additional platforms "out of the box".
140
141Note: Do not specify either of the TCL_LIBRARY and TK_LIBRARY environment
142variables in a production installation, as this can cause conflicts between
143different versions of the libraries. Instead, the libraries should have the
144correct locations of their associated script directories built into them.
145
146Test suite
147----------
148
149Tk has a substantial self-test suite, consisting of a set of scripts in the
150subdirectory "tests". To run the test suite just type "make test" in this
151directory. You should then see a printout of the test files processed. If any
152errors occur, you'll see a much more substantial printout for each error. In
153order to avoid false error reports, be sure to run the tests with an empty
154resource database (e.g., remove your .Xdefaults file or delete any entries
155starting with *). Also, don't try to do anything else with your display or
156keyboard while the tests are running, or you may get false violations. See the
157README file in the "tests" directory for more information on the test suite.
158
159If the test suite generates errors, most likely they are due to non-portable
160tests that are interacting badly with your system configuration. We are
161gradually eliminating the non-portable tests, but this release includes many
162new tests so there will probably be some portability problems. As long as the
163test suite doesn't core dump, it's probably safe to conclude that any errors
164represent portability problems in the test suite and not fundamental flaws
165with Tk.
166
167There are also a number of visual tests for things such as screen layout,
168Postscript generation, etc. These tests all have to be run by manually
169enabling the "userInteraction" constraint when testing, and the results have
170to be verified visually. This can be done with:
171
172 make test TESTFLAGS="-constraints userInteraction"
173
174Some tests will present a main window with a bunch of menus, which you can use
175to select various tests.
176