README.1st
README.ActiveTcl
1ActiveTcl is ActiveState's quality-assured distribution of Tcl.
2
3# see <http://www.activestate.com/Products/ActiveTcl/>
4# <http://www.tcl.tk/>
5
6First of all, please try to configure without any options.
7"extconf.rb" searches ActiveTcl as default action.
8If you have ActiveTcl and standard (or your own) Tcl/Tk on your
9environment and don't want to use ActiveTcl on your Ruby/Tk, please
10use --without-ActiveTcl option.
11
12When "extconf.rb" fails to find your ActiveTcl libraries, please try
13the followings.
14
15If you want to use ActiveTcl binary package as the Tcl/Tk libraries,
16please use the following configure options.
17
18 --with-ActiveTcl=<ActiveTcl_root>
19 ( When without argument; no <ActiveTcl_root>; only '--with-ActiveTcl',
20 it same to '--with-ActiveTcl=/opt/ActiveTcl*/lib' )
21
22 --with-tcl-dir=<ActiveTcl_root>
23 --with-tk-dir=<ActiveTcl_root>
24
25And use the followings if you need.
26
27 --with-tcllib=<libname>
28 --with-tklib=<libname>
29 --enable-tcltk-stubs
30
31For example, when you install ActiveTcl-8.4.x to '/usr/local/ActiveTcl',
32
33 configure --with-tcl-dir=/usr/local/ActiveTcl/ \
34 --with-tk-dir=/usr/local/ActiveTcl/ \
35 --with-tcllib=tclstub8.4 \
36 --with-tklib=tkstub8.4 \
37 --enable-tcltk-stubs
38
39It depends on your environment that you have to add the directory of
40ActiveTcl's libraries to your library path when execute Ruby/Tk.
41One of the way is to add entries to TCLLIBPATH environment variable,
42and one of the others add to LD_LIBRARY_PATH environment variable
43
44Probably, using TCLLIBPATH is better. The value is appended at the
45head of Tcl's 'auto_path' variable. You can see the value of the
46variable by using 'Tk::AUTO_PATH.value' or 'Tk::AUTO_PATH.list'.
47
48For example, on Linux, one of the ways is to use LD_LIBRARY_PATH
49environment variable.
50-------------------------------------------------------------------------
51 [bash]$ LD_LIBRARY_PATH=/usr/local/ActiveTcl/lib:$LD_LIBRARY_PATH \
52 ruby your-Ruby/Tk-script
53
54 [bash]$ LD_LIBRARY_PATH=/usr/local/ActiveTcl/lib:$LD_LIBRARY_PATH irb
55-------------------------------------------------------------------------
56Based on it, the Tcl interpreter changes auto_path variable's value.
57
58Then, you'll be able to use Tcl/Tk extension libraries included in the
59ActiveTcl package (e.g. call TkPackage.require('BWidget'), and then,
60use functions/widgets of BWidget extention).
61
62 Hidetoshi NAGAI (nagai@ai.kyutech.ac.jp)
63
README.fork
1Ruby/Tk does NOT support forking the process on which Tk interpreter
2is running (unless NEVER control Tk interpreter under the forked child
3process). In the library 'tk.rb', a Tk interpreter is initialized.
4Therefore, if you want running Tk under a child process, please call
5"require 'tk'" in the child process.
6
7# If do fork and exec(<new Ruby/Tk>) on the child process, you can
8# control Ruby/Tk interpreter on the child process by 'send' command
9# of Tcl/Tk. About this, please see Tk.appsend and Tk.rb_appsend, or
10# 'remote-tk.rb' and the sample 'sample/remote-ip_sample.rb'.
11
12For example, the following sample1 will NOT work, and sample2 will
13work properly.
14
15---<sample1: NOT work>---------------------------------------
16require 'tk' ## init Tk interpreter under parent process
17
18exit! if fork ## exit parent process
19
20## child process
21TkButton.new(:text=>'QUIT', :command=>proc{exit}).pack
22Tk.mainloop
23-------------------------------------------------------------
24
25---<sample2: will work>--------------------------------------
26exit! if fork ## exit main process
27
28## child process
29require 'tk' ## init Tk interpreter under child process
30TkButton.new(:text=>'QUIT', :command=>proc{exit}).pack
31Tk.mainloop
32-------------------------------------------------------------
33
34 2004/05/22 Hidetoshi NAGAI
35
README.macosx-aqua
1
2 *** for MacOS X Aqua (Tcl/Tk Aqua) users ***
3
4First of all, please read README.tcltklib to use Tcl/Tk Aqua Framework.
5
6With Tcl/Tk Aqua libraries, current tcltklib somtimes freezes when
7using Aqua specific dialogs (e.g. Tk.messageBox).
8This is a known bug of Ruby-1.8.4 release.
9
10When you meet the trouble on your GUI, you'll be able to avoid the trouble
11by Tcl/Tk's traditional dialogs.
12If you want to do that, please call some of the following bits of script
13after "reqruie 'tk'".
14
15=================================================================
16# use a traditional dialog for Tk.chooseColor()
17Tk.ip_eval(<<'EOS')
18 proc ::tk_chooseColor {args} {
19 return [eval tk::dialog::color:: $args]
20 }
21EOS
22
23# use a traditional dialog for Tk.getOpenFile() and Tk.getMultipleOpenFile()
24Tk.ip_eval(<<'EOS')
25 proc ::tk_getOpenFile {args} {
26 if {$::tk_strictMotif} {
27 return [eval tk::MotifFDialog open $args]
28 } else {
29 return [eval ::tk::dialog::file:: open $args]
30 }
31 }
32EOS
33
34# use a traditional dialog for Tk.getSaveFile() and Tk.getMultipleSaveFile()
35Tk.ip_eval(<<'EOS')
36 proc ::tk_getSaveFile {args} {
37 if {$::tk_strictMotif} {
38 return [eval tk::MotifFDialog save $args]
39 } else {
40 return [eval ::tk::dialog::file:: save $args]
41 }
42 }
43EOS
44
45# use a traditional dialog for Tk.messageBox()
46Tk.ip_eval(<<'EOS')
47 proc ::tk_messageBox {args} {
48 return [eval tk::MessageBox $args]
49 }
50EOS
51
52# use a traditional dialog for Tk.chooseDirectory()
53Tk.ip_eval(<<'EOS')
54 proc ::tk_chooseDirectory {args} {
55 return [eval ::tk::dialog::file::chooseDir:: $args]
56 }
57EOS
58=================================================================
59
60Each of them replaces the platform specific dialog command to the
61traditional one.
62
63If you use some MultiTkIp objects, probably, you'll have to call the
64bits of script for each MultiTkIp object.
65
66--
67Hidetoshi NAGAI (nagai@ai.kyutech.ac.jp)
68
README.tcltklib
1To compile 'tcltklib', you must have Tcl/Tk libraries on your environment.
2Although 'extconf.rb' script searches Tcl/Tk libraries and header files
3(as default, searches tclConfig.sh/tkConfig.sh and use the defintions on
4those; ActiveTcl has high priority on searching unless --without-ActiveTcl),
5sometimes fails to find them. And then, 'tcltklib' cannot be compiled. If
6Tcl/Tk libraries or header files are installed but are not found, you can
7give the information by arguments of the 'configure' script. Please give
8some or all of the following options.
9
10 --with-tk-old-extconf use old "extconf.rb" (default: false).
11 If current extconf.rb doesn't work properly
12 (or your install process is based on old
13 documant about Ruby/Tk install), please try
14 this option.
15
16 --with-ActiveTcl / --without-ActiveTcl
17 --with-ActiveTcl=<dir> search ActiveTcl libraries (default: true).
18 When true, try to find installed ActiveTcl.
19 When <dir> is given, use it as the ActiveTcl's
20 top directory (use <dir>/lib, and so on).
21 Old "extconf.rb" doesn't support this option.
22
23 --with-tk-shlib-search-path=<paths>
24 teach the paths for loading shared-libraries
25 to linker.
26 <paths> is a path list with the same format
27 as PATH environment variable.
28 This option may be experimental.
29 Old "extconf.rb" doesn't support this option.
30
31 --with-tcltkversion=<version>
32 --with-tcltkversion=<tclversion>,<tkversion>
33 force version of Tcl/Tk libaray
34 (e.g. libtcl8.4g.so & libtk8.4g.so ==> --with-tcltkversion=8.4g
35 libtcl8.4.so & libtk8.4g.so ==> --with-tcltkversion=8.4,8.4g)
36
37 --enable-tcl-h-ver-check/--disable-tcl-h-ver-check
38 --enable-tk-h-ver-check/--disable-tk-h-ver-check
39 enable or disable for checking MAJOR_VERSION and
40 MINOR_VERSION on tcl.h/tk.h whether match with
41 Tcl/Tk libraries' version or not.
42
43 --with-tcl-build-dir=<dir>
44 --with-tk-build-dir=<dir> If you want to compile with libraries on Tcl/Tk
45 build dir (still NOT installed), you must use
46 these options.
47 (e.g. --with-tcl-build-dir=./build/tcl8.5.9/unix)
48 When use these options, --with-tclConfig-dir and
49 --with-tkConfig-dir options are ignored (however,
50 --with-tclConfig-file and --with-tkConfig-file
51 options are still available).
52
53 --with-tclConfig-file=<file>/--without-tclConfig-file
54 --with-tkConfig-file=<file>/--without-tkConfig-file
55 file path of tclConfig.sh/tkConfig.sh, or don't
56 refer those.
57 If you want use non-standard filenames of config
58 files (e.g. tclConfig-static.sh), you must use
59 these options.
60
61 --with-tclConfig-dir=<dir>
62 --with-tkConfig-dir=<dir> the directory contains 'tclConfig.sh' and
63 'tkConfig.sh'.
64 Current "extconf.rb" uses the information
65 on tclConfig.sh/tkConfig.rb, if possible.
66 Old "extconf.rb" doesn't support this option.
67
68 --with-tcllib=<libname> (e.g. libtcl8.4.so ==> --with-tcllib=tcl8.4)
69 --with-tklib=<libname> (e.g. libtk8.4.so ==> --with-tklib=tk8.4)
70
71 --enable-tcltk-stubs (if you force to enable stubs)
72 On old "extconf.rb", default is false.
73 On current "extconf.rb", default is true when
74 tclConfig.sh/tkConfig.sh have TCL_STUB_LIB_SPEC
75 /TK_STUB_LIB_SPEC, else default is false.
76
77 --with-tcl-dir=<path>
78 equal to "--with-tcl-include=<path>/include --with-tcl-lib=<path>/lib"
79
80 --with-tk-dir=<path>
81 equal to "--with-tk-include=<path>/include --with-tk-lib=<path>/lib"
82
83 --with-tcl-include=<dir> the directry contains 'tcl.h'
84 --with-tk-include=<dir> the directry contains 'tk.h'
85
86 --with-tcl-lib=<dir> the directry contains 'libtcl<version>.so'
87 --with-tk-lib=<dir> the directry contains 'libtk<version>.so'
88
89 --enable-mac-tcltk-framework (MacOS X) use Tcl/Tk framework
90 (Obsolete. Please use '--enable-tcltk-framework'.)
91
92 --enable-tcltk-framework use Tcl/Tk framework
93
94 --with-tcltk-framework=<dir> the directory contains Tcl/Tk framework;
95 "<dir>/Tcl.framework" and "<dir>/Tk.framework".
96 When this option is given, it is assumed that
97 --enable-tcltk-framework option is given also.
98
99 --with-tcl-framework-dir=<dir>
100 Tcl framework directory (e.g. "/Library/Frameworks/Tcl.framework")
101
102 --with-tk-framework-dir=<dir>
103 Tk framework directory (e.g. "/Library/Frameworks/Tk.framework")
104
105 --with-tcl-framework-header=<dir>
106 Tcl framework headers directory
107 (e.g. "/Library/Frameworks/Tcl.framework/Headers")
108
109 --with-tk-framework-header=<dir>
110 Tk framework headers directory
111 (e.g. "/Library/Frameworks/Tk.framework/Headers")
112
113
114 --with-X11 / --without-X11 use / not use the X Window System
115
116 --with-X11-dir=<path>
117 equal to "--with-X11-include=<path>/include --with-X11-lib=<path>/lib"
118
119 --with-X11-include=<dir> the directry contais X11 header files
120 --with-X11-lib=<dir> the directry contais X11 libraries
121
122
123If you forgot to give the options when do 'configure' on toplevel
124directry of Ruby sources, please try something like as the followings.
125
126 $ cd ext/tcltklib
127 $ rm Makefile
128 $ CONFIGURE_ARGS='--with-tcl-include=/usr/local/include/tcl8.4/ --with-tcllib=tcl8.4 --with-tklib=tk8.4' ruby extconf.rb
129
130
131 *** ATTENTION ***
132When your Tcl/Tk libraries are compiled with "pthread support",
133Ruby/Tk may cause "Hang-up" or "Segmentation Fault" frequently.
134If you have such a trouble, please try to use the '--enable-pthread'
135option of the 'configure' command and re-compile Ruby sources.
136It may help you to avoid this trouble. The following configure
137options may be useful.
138
139 --enable-tcl-thread/--disable-tcl-thread
140 --with-tclConfig-file=<path of 'tclConfig.sh'>
141 --with-tkConfig-file=<path of 'tkConfig.sh'>
142
143It is not need that 'tclConfig.sh' is a normal Tcl/Tk's tclConfig.sh.
144But the file is expected to include the line "TCL_THREADS=0" or "...=1".
145When no "TCL_THREADS=?" line, if Tcl version is 7.x or 8.0 which is
146given by "TCL_MAJOR_VERSION=?" line and "TCL_MINOR_VERSION=?" line,
147then --disable-tcl-thread is expected. Else, ignore the 'tclConfig.sh'.
148If --enable-tcl-thread or --disable-tcl-thread option is given, then
149--with-tclConfig-file option is ignored.
150
151==========================================================
152 Hidetoshi NAGAI (nagai@ai.kyutech.ac.jp)
153