1Tcl/Tk Mac OS X README 2---------------------- 3 4RCS: @(#) $Id: README,v 1.6.2.15 2007/04/29 02:26:47 das Exp $ 5 6This is the README file for the Mac OS X/Darwin version of Tcl/Tk. 7 8 91. Where to go for support 10-------------------------- 11 12- The tcl-mac mailing list on sourceforge is the best place to ask questions 13specific to Tcl & Tk on Mac OS X: 14 http://lists.sourceforge.net/lists/listinfo/tcl-mac 15(this page also has a link to searchable archives of the list, please check them 16before asking on the list, many questions have already been answered). 17 18- For general Tcl/Tk questions, the newsgroup comp.lang.tcl is your best bet: 19 http://groups.google.com/group/comp.lang.tcl/ 20 21- The Tcl'ers Wiki also has many pages dealing with Tcl & Tk on Mac OS X, see 22 http://wiki.tcl.tk/references/3753! 23 http://wiki.tcl.tk/references/8361! 24 25- Please report bugs with Tcl or Tk on Mac OS X to the sourceforge bug trackers: 26 Tcl: http://sf.net/tracker/?func=add&group_id=10894&atid=110894 27 Tk: http://sf.net/tracker/?func=add&group_id=12997&atid=112997 28please make sure that your report Tk specific bugs to the tktoolkit project bug 29tracker rather than the tcl project bug tracker. 30Mac OS X specific bugs should usually be assigned to 'das' or 'wolfsuit'. 31 32 332. Using Tcl/Tk on Mac OS X 34--------------------------- 35 36- There are two versions of Tk available on Mac OS X: TkAqua using the native 37aqua widgets and look&feel, and TkX11 using the traditional unix X11 wigets. 38TkX11 requires an X11 server to be installed, such as Apple's X11 (which is 39available as an optional install on recent Mac OS X retail disks). 40TkAqua and TkX11 can be distinguished at runtime via [tk windowingsystem]. 41 42- At a minimum, Mac OS X 10.1 is required to run Tcl and TkX11, and OS X 10.2 is 43required to run TkAqua. However OS X 10.3 or higher is recommended (certain 44[file] operations behave incorrectly on earlier releases). 45 46- Unless weak-linking is used, Tcl/Tk built on Mac OS X 10.x will not run on 4710.y with y < x; on the other hand Tcl/Tk built on 10.y will always run on 10.x 48with y <= x (but without any of the fixes and optimizations that would be 49available in a binary built on 10.x). 50Weak-linking is available on OS X 10.2 or later, it additionally allows Tcl/Tk 51built on 10.x to run on any 10.y with x > y >= z (for a chosen z >= 2). 52 53- Wish checks the Resources/Scripts directory in its application bundle for a 54file called AppMain.tcl, if found it is used as the startup script and the 55Scripts folder is added to the auto_path. This can be used to emulate the old 56OS9 TclTk droplets. 57 58- If standard input is a special file of zero length (e.g. /dev/null), Wish 59brings up the Tk console window at startup. This is the case when double 60clicking Wish in the Finder (or using 'open Wish.app' from the Terminal). 61 62- Tcl extensions can be installed in any of: 63 $HOME/Library/Tcl /Library/Tcl /Network/Library/Tcl /System/Library/Tcl 64 $HOME/Library/Frameworks /Library/Frameworks /Network/Library/Frameworks 65 /System/Library/Frameworks (searched in that order). 66Given a potential package directory $pkg, Tcl on OSX checks for the file 67$pkg/Resources/Scripts/pkgIndex.tcl as well as the usual $pkg/pkgIndex.tcl. 68This allows building extensions as frameworks with all script files contained in 69the Resources/Scripts directory of the framework. 70 71- [load]able binary extensions can linked as either ordinary shared libraries 72(.dylib) or as MachO bundles (since 8.4.10/8.5a3); only bundles can be unloaded, 73and bundles are also loaded more efficiently from VFS (no temporary copy to the 74native filesystem required). 75 76- The 'deploy' target of macosx/GNUmakefile installs the html manpages into the 77standard documentation location in the Tcl/Tk frameworks: 78 Tcl.framework/Resources/Documentation/Reference/Tcl 79 Tk.framework/Resources/Documentation/Reference/Tk 80No nroff manpages are installed by default by the GNUmakefiles. 81 82- The Tcl and Tk frameworks can be installed in any of the system's standard 83framework directories: 84 $HOME/Library/Frameworks /Library/Frameworks 85 /Network/Library/Frameworks /System/Library/Frameworks 86 87- /usr/bin/wish8.x is a script that calls a copy of 'Wish' contained in 88 Tk.framework/Resources 89 90- if 'Wish' is started from the Finder or via 'open', $argv contains a 91"-psn_XXXX" argument. This is the Wish's carbon process serial number, you may 92need to filter it out for cross platform compatibility of your scripts. 93 94- the env array is different when Wish is started from the Finder (i.e. via 95LaunchServices) than when it (or tclsh) is invoked from the Terminal, in 96particular PATH may not be what you expect. (Wish started by LaunchServices 97inherits loginwindow's environment variables, which are essentially those set in 98$HOME/.MacOSX/environment.plist, and are unrelated to those set in your shell). 99 100- As of Tk 8.4.7, TkAqua has a version of the low-level drawing primitives using 101the CoreGraphics routines - the code is primarily due to James Tittle. There 102were numerous problems with the QD version, mostly due to the different drawing 103model of QD & Tk. CG also trivially supports dashed lines, and the various end 104caps & miters. The old QD code is retained for now, just in case there are any 105compatibility problems. To switch back to the QD drawing, put 106 set tk::mac::useCGDrawing 0 107in your script before you do drawing. 108All CG drawing is antialiased by default, but (outline) linewidth can be used to 109control whether a line/shape is drawn antialiased. The antialiasing threshold is 1100 by default (i.e. antialias everything), it can be changed by setting 111 set tk::mac::CGAntialiasLimit <limit> 112in your script before drawing, in which case lines (or shapes with outlines) 113thinner than <limit> pixels will not be antialiased. 114 115- Quickdraw text antialiasing is enabled by default when available (from 10.1.5 116onwards). Changing the global boolean variable '::tk::mac::antialiasedtext' 117allows to dis/enable antialiasing on the fly from Tcl (even for existing text). 118 119- Scrollbars: There are two scrollbar variants in Aqua, normal & small. The 120normal scrollbar has a small dimension of 15, the small variant 11. Access to 121the small variant was added in Tk 8.4.2. 122 123- Cursors: You can now put up and spin the Classic MacOS spinner, and the 124counting hands and watch cursor. The way this is done is each of the spinners 125have a base name: 126 spinning: The circular B&W circular spinner 127 countinguphand: The counting up hand 128 countingdownhand: The counting down hand 129 countingupanddownhand: The counting up then down hand 130 watch: The watch cursor 131Then to get the sequential variants, add an integer to the end of the base name. 132So, for instance this code will spin the spinner: 133 proc spinCursor {widget count} { 134 $widget configure -cursor spinning$count 135 after 100 spinCursor [incr count] 136 } 137This was added in Tk 8.4.2 138 139 1403. Building Tcl/Tk on Mac OS X 141------------------------------ 142 143- At least Mac OS X 10.1 is required to build Tcl and TkX11 and OS X 10.2 is 144required to build TkAqua. Apple's Developer Tools need to be installed (only the 145most recent version matching your OS release is supported). The Developer Tools 146installer is available on Mac OS X retail disks or is present in 147/Applications/Installers on Macs that came with OS X preinstalled. The most 148recent version can be downloaded from the ADC website http://connect.apple.com 149(after you register for free ADC membership). 150 151- Tcl/Tk are most easily built as Mac OS X frameworks via GNUmakefile in 152tcl/macosx and tk/macosx (see below for details), but can also be built with the 153standard unix configure and make buildsystem in tcl/unix resp. tk/unix as on any 154other unix platform (indeed, the GNUmakefiles are just wrappers around the unix 155buildsystem). 156The Mac OS X specific configure flags are --enable-aqua, --enable-framework and 157--disable-corefoundation (which disables CF and notably reverts to the standard 158select based notifier). Note that --enable-aqua is incompatible with 159--disable-corefoundation (for both Tcl and Tk configure). 160 161- It is also possible to build with Apple's IDE via the tk/macosx/Wish.pbproj 162project, this simply calls through to the tk/macosx/Makefile. It requires a 163build of the tcl/macosx/Tcl.pbproj project. 164 165- To build universal binaries, set CFLAGS as follows: 166 export CFLAGS="-arch ppc -arch i386 \ 167 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4" 168This requires Mac OS X 10.4 and Xcode 2.2 (_not_ Xcode 2.1) and will work on any 169of the architectures (the -isysroot flag is only required on PowerPC Tiger). 170Note that configure requires CFLAGS to contain a least one architecture that can 171be run on the build machine (i.e. ppc on PowerPC, ppc or i386 on Intel). 172Universal builds of Tk TEA extensions are also possible with CFLAGS set as 173above, they will be [load]able by universal as well as thin binaries of Tk. 174Note that while Tcl can be built for 64-bit architectures, neither TkAqua nor 175TkX11 can be built for 64-bit as the corresponding GUI libraries are not 176available for 64bit at present. However, linking a universal 'ppc i386' Tk 177binary against a universal 'ppc ppc64 i386 x86_64' Tcl binary works just fine. 178The Tk configure script automatically removes the 64-bit -arch flags from CFLAGS 179to facilitate universal building of both Tcl and Tk with the same CFLAGS; the 180same happens with configure in Tk extensions based on TEA 3.5 or later. 181 182- To enable weak-linking, set the MACOSX_DEPLOYMENT_TARGET environment variable 183to the minimal OS version (>= 10.2) the binaries should be able to run on, e.g: 184 export MACOSX_DEPLOYMENT_TARGET=10.2 185This requires Mac OS X 10.2 and gcc 3.1; if you have gcc 4 or later you can set 186CFLAGS instead: 187 export CFLAGS="-mmacosx-version-min=10.2" 188Support for weak-linking was added to the code for 8.4.14/8.5a5. 189 190Detailed Instructions for building with macosx/GNUmakefile 191---------------------------------------------------------- 192 193- Unpack the Tcl and Tk source release archives and place the tcl and tk source 194trees in a common parent directory. 195[ If you don't want have the two source trees in one directory, you'll need to ] 196[ create the following symbolic link for the build to work as setup by default ] 197[ ln -fs /path_to_tcl/build /path_to_tk/build ] 198[ (where /path_to_{tcl,tk} is the directory containing the tcl resp. tk tree) ] 199[ or you can pass an argument of BUILD_DIR=/somewhere to the tcl and tk make. ] 200 201- The following instructions assume the Tcl and Tk source trees are named 202"tcl${ver}" and "tk${ver}", respectively, where ${ver} is a shell variable 203containing the Tcl and Tk version number (for example '8.4.12'). 204Setup the shell variable as follows: 205 set ver="8.4.12" ;: if your shell is csh 206 ver="8.4.12" ;: if your shell is sh 207The source trees will be named this way only if you are building from a release 208archive, if you are building from CVS, the version numbers will be missing; so 209set ${ver} to the empty string instead: 210 set ver="" ;: if your shell is csh 211 ver="" ;: if your shell is sh 212 213- The following steps will build Tcl and Tk from the Terminal, assuming you are 214located in the directory containing the tcl and tk source trees: 215 make -C tcl${ver}/macosx 216 make -C tk${ver}/macosx 217and the following will then install Tcl and Tk onto the root volume (admin 218password required): 219 sudo make -C tcl${ver}/macosx install 220 sudo make -C tk${ver}/macosx install 221if you don't have the admin password, you can install into your home directory, 222instead by passing an INSTALL_ROOT argument to make: 223 make -C tcl${ver}/macosx install INSTALL_ROOT="${HOME}/" 224 make -C tk${ver}/macosx install INSTALL_ROOT="${HOME}/" 225 226- The default Makefile targets will build _both_ debug and optimized versions of 227the Tcl and Tk frameworks with the standard convention of naming the debug 228library Tcl.framework/Tcl_debug resp. Tk.framework/Tk_debug. 229This allows switching to the debug libraries at runtime by setting 230 export DYLD_IMAGE_SUFFIX=_debug 231(c.f. man dyld for more details) 232 233If you only want to build and install the debug or optimized build, use the 234'develop' or 'deploy' target variants of the Makefiles, respectively. 235For example, to build and install only the optimized versions: 236 make -C tcl${ver}/macosx deploy 237 make -C tk${ver}/macosx deploy 238 sudo make -C tcl${ver}/macosx install-deploy 239 sudo make -C tk${ver}/macosx install-deploy 240 241- The Makefiles can also build a version of 'Wish' that has the Tcl and Tk 242frameworks embedded in its application package. This allows for standalone 243deployment of the application with no installation required, e.g. from read-only 244media. To build & install in this manner, use the 'embedded' target variants of 245the Makefiles. For example, to build a standalone 'Wish.app' 246in ./embedded/Applications/Utilities: 247 make -C tcl${ver}/macosx embedded 248 make -C tk${ver}/macosx embedded 249 sudo make -C tcl${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/embedded/ 250 sudo make -C tk${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/embedded/ 251Notes: 252 * if you've already built standard TclTkAqua, building embedded does not 253 require any new compiling or linking, so you can skip the first two makes. 254 (making relinking unnecessary was added in 8.4.2) 255 * the embedded frameworks include only optimized builds and no documentation. 256 * the standalone Wish has the directory Wish.app/Contents/lib in its 257 auto_path. Thus you can place tcl extensions in this directory (i.e. embed 258 them in the app package) and load them with [package require]. 259 260- It is possible to build Tk against an installed Tcl.framework; but you will 261still need a tcl sourcetree in the location specified in TCL_SRC_DIR in 262Tcl.framework/tclConfig.sh. Also, linking with Tcl.framework has to work exactly 263as indicated in TCL_LIB_SPEC in Tcl.framework/tclConfig.sh. 264If you used non-default install locations for Tcl.framework, specify them as 265make overrides to the tk/macosx Makefile, e.g. 266 make -C tk${ver}/macosx \ 267 TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin 268 sudo make -C tk${ver}/macosx install \ 269 TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin 270The Makefile variables TCL_FRAMEWORK_DIR and TCLSH_DIR were added in Tk 8.4.3. 271