1Tcl/Tk Mac OS X README 2---------------------- 3 4RCS: @(#) $Id$ 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 in general be assigned to user 'das'. 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 or default install on recent Mac OS X). 40TkAqua and TkX11 can be distinguished at runtime via [tk windowingsystem]. 41 42- At a minimum, Mac OS X 10.3 is required to run Tcl and TkX11. 43TkAqua requires Mac OS X 10.5 or later (starting with the Cocoa-based Tk 8.5.7). 44 45- Unless weak-linking is used, Tcl/Tk built on Mac OS X 10.x will not run on 4610.y with y < x; on the other hand Tcl/Tk built on 10.y will always run on 10.x 47with y <= x (but without any of the fixes and optimizations that would be 48available in a binary built on 10.x). 49Weak-linking is available on OS X 10.2 or later, it additionally allows Tcl/Tk 50built on 10.x to run on any 10.y with x > y >= z (for a chosen z >= 2). 51 52- Wish checks the Resources/Scripts directory in its application bundle for a 53file called AppMain.tcl, if found it is used as the startup script and the 54Scripts folder is added to the auto_path. This can be used to emulate the old 55OS9 TclTk droplets. 56 57- If standard input is a special file of zero length (e.g. /dev/null), Wish 58brings up the Tk console window at startup. This is the case when double 59clicking Wish in the Finder (or using 'open Wish.app' from the Terminal). 60 61- Tcl extensions can be installed in any of: 62 $HOME/Library/Tcl /Library/Tcl /System/Library/Tcl 63 $HOME/Library/Frameworks /Library/Frameworks /System/Library/Frameworks 64 (searched in that order). 65Given a potential package directory $pkg, Tcl on OSX checks for the file 66$pkg/Resources/Scripts/pkgIndex.tcl as well as the usual $pkg/pkgIndex.tcl. 67This allows building extensions as frameworks with all script files contained in 68the Resources/Scripts directory of the framework. 69 70- [load]able binary extensions can linked as either ordinary shared libraries 71(.dylib) or as MachO bundles (since 8.4.10/8.5a3); bundles have the advantage 72that they are [load]ed more efficiently from a tcl VFS (no temporary copy to the 73native filesystem required), and prior to Mac OS X 10.5, only bundles can be 74[unload]ed. 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 GNUmakefile. 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 /System/Library/Frameworks 85 86- ${prefix}/bin/wish8.x is a script that calls a copy of 'Wish' contained in 87 Tk.framework/Resources 88 89- if 'Wish' is started from the Finder or via 'open', $argv may contain a 90"-psn_XXXX" argument. This is the process serial number, you may need to filter 91it out for cross platform compatibility of your scripts. 92 93- the env array is different when Wish is started from the Finder (i.e. via 94LaunchServices) than when it (or tclsh) is invoked from the Terminal, in 95particular PATH may not be what you expect. (Wish started by LaunchServices 96inherits loginwindow's environment variables, which are essentially those set in 97$HOME/.MacOSX/environment.plist, and are unrelated to those set in your shell). 98 99- TkAqua drawing is antialiased by default, but (outline) linewidth can be used 100to control whether a line/shape is drawn antialiased. The antialiasing threshold 101is 0 by default (i.e. antialias everything), it can be changed by setting 102 set tk::mac::CGAntialiasLimit <limit> 103in your script before drawing, in which case lines (or shapes with outlines) 104thinner than <limit> pixels will not be antialiased. 105 106- Text antialiasing by default uses the standard OS antialising settings. 107Setting the global variable '::tk::mac::antialiasedtext' allows to control text 108antialiasing from Tcl: a value of 1 enables AA, 0 disables AA and -1 restores 109the default behaviour of respecting the OS settings. 110 111- Scrollbars: There are two scrollbar variants in Aqua, normal & small. The 112normal scrollbar has a small dimension of 15, the small variant 11. 113Access to the small variant was added in Tk 8.4.2. 114 115- The default metrics of native buttons, radiobuttons, checkboxes and 116menubuttons in the Cocoa-based Tk 8.5.7 and later preserve compatibility with 117the older Carbon-based implementation, you can turn off the compatibility 118metrics to get more native-looking spacing by setting: 119 set tk::mac::useCompatibilityMetrics 0 120 121- TkAqua provides access to native OS X images via the Tk native bitmap facility 122(including any image file readable by NSImage). A native bitmap name is 123interpreted as follows (in order): 124 - predefined builtin 32x32 icon name (stop, caution, document, etc) 125 - name defined by [tk::mac::iconBitmap] 126 - NSImage named image name 127 - NSImage url string 128 - 4-char OSType of IconServices icon 129the syntax of [tk::mac::iconBitmap] is as follows: 130 tk::mac::iconBitmap name width height -kind value 131where -kind is one of 132 -file icon of file at given path 133 -fileType icon of given file type 134 -osType icon of given 4-char OSType file type 135 -systemType icon for given IconServices 4-char OSType 136 -namedImage named NSImage for given name 137 -imageFile image at given path 138This support was added with the Cocoa-based Tk 8.5.7. 139 140- TkAqua cursor names are interpred as follows (in order): 141 - standard or platform-specific Tk cursor name (c.f. cursors.n) 142 - @path to any image file readable by NSImage 143 - NSImage named image name 144Support for the latter two was added with the Cocoa-based Tk 8.5.7. 145 146- The standard Tk dialog commands [tk_getOpenFile], [tk_chooseDirectory], 147[tk_getSaveFile] and [tk_messageBox] all take an additional optional -command 148parameter on TkAqua. If it is present, the given command prefix is evaluated at 149the global level when the dialog closes, with the dialog command's result 150appended (the dialog command itself returning an emtpy result). If the -parent 151option is also present, the dialog is configured as a modeless (window-modal) 152sheet attached to the parent window and the dialog command returns immediately. 153Support for -command was added with the Cocoa-based Tk 8.5.7. 154 155- The TkAqua-specific [tk::mac::standardAboutPanel] command brings the standard 156Cocoa about panel to the front, with all its information filled in from your 157application bundle files (i.e. standard about panel with no options specified). 158See Apple Technote TN2179 and the AppKit documentation for -[NSApplication 159orderFrontStandardAboutPanelWithOptions:] for details on the Info.plist keys and 160app bundle files used by the about panel. 161This support was added with the Cocoa-based Tk 8.5.7. 162 163- TkAqua has three special menu names that give access to the standard 164Application, Window and Help menus, see menu.n for details. 165By default, the platform-specific standard Help menu item "YourApp Help" peforms 166the default Cocoa action of showing the Help Book configured in the 167application's Info.plist (or displaying an alert if no Help Book is set). This 168action can be customized by defining a procedure named [tk::mac::ShowHelp], if 169present, this procedure is invoked instead by the standard Help menu item. 170Support for the Window menu and [tk::mac::ShowHelp] was added with the 171Cocoa-based Tk 8.5.7. 172 173- The TkAqua-specific command [tk::unsupported::MacWindowStyle style] is used to 174get and set Mac OS X-specific toplevel window class and attributes. Note that 175the window class and many attributes have to be set before the window is first 176mapped for the change to have any effect. 177The command has the following syntax: 178 tk::unsupported::MacWindowStyle style window ?class? ?attributes? 179The 2 argument form returns a list of the current class and attributes for the 180given window. The 3 argument form sets the class for the given window using the 181default attributes for that class. The 4 argument form sets the class and the 182list of attributes for the given window. 183Window class names: 184 document, modal, floating, utility, toolbar, simple, help, overlay 185Window attribute names: 186 standardDocument, standardFloating, resizable, fullZoom, horizontalZoom, 187 verticalZoom, closeBox, collapseBox, toolbarButton, sideTitlebar, 188 noTitleBar, unifiedTitleAndToolbar, metal, hud, noShadow, doesNotCycle, 189 noActivates, hideOnSuspend, inWindowMenu, ignoreClicks, doesNotHide, 190 canJoinAllSpaces, moveToActiveSpace, nonActivating 191Note that not all attributes are valid for all window classes. 192Support for the 3 argument form was added with the Cocoa-based Tk 8.5.7, at the 193same time support for some legacy Carbon-specific classes and attributes was 194removed (they are still accepted by the command but no longer have any effect). 195 196- The Cocoa-based TkAqua can be distinguished from the older Carbon-based 197version via the [winfo server .] command, example output on Mac OS X 10.5.7: 198 Cocoa-based: CG409.3 Apple AppKit GC 949.46 Mac OS X 1057 199 Carbon-based: QD10R30 Apple 1057 200 201- If you want to use Remote Debugging with Xcode, you need to set the 202environment variable XCNOSTDIN to 1 in the Executable editor for Wish. That will 203cause us to force closing stdin & stdout. Otherwise, given how Xcode launches 204Wish remotely, they will be left open and then Wish & gdb will fight for stdin. 205 206 2073. Building Tcl/Tk on Mac OS X 208------------------------------ 209 210- At least Mac OS X 10.3 is required to build Tcl and TkX11, and Mac OS X 10.5 211is required to build TkAqua. 212Apple's Xcode Developer Tools need to be installed (only the most recent version 213matching your OS release is supported), the Xcode installer is available on Mac 214OS X install media or may be present in /Applications/Installers on Macs that 215came with OS X preinstalled. The most recent version can always be downloaded 216from the ADC website http://connect.apple.com (free ADC membership required). 217 218- Tcl/Tk are most easily built as Mac OS X frameworks via GNUmakefile in 219tcl/macosx and tk/macosx (see below for details), but can also be built with the 220standard unix configure and make buildsystem in tcl/unix resp. tk/unix as on any 221other unix platform (indeed, the GNUmakefiles are just wrappers around the unix 222buildsystem). 223The Mac OS X specific configure flags are --enable-aqua, --enable-framework and 224--disable-corefoundation (which disables CF and notably reverts to the standard 225select based notifier). Note that --enable-aqua is incompatible with 226--disable-corefoundation (for both Tcl and Tk configure). 227 228- It is also possible to build with the Xcode IDE via the projects in 229tk/macosx, take care to use the project matching your DevTools and OS version: 230 Tk.xcode: for Xcode 3.1 on 10.5 231 Tk.xcodeproj: for Xcode 3.2 on 10.6 232These have the following targets: 233 Tk: calls through to tk/macosx/GNUMakefile, 234 requires a corresponding build of the Tcl 235 target of tcl/macosx/Tcl.xcode. 236 tktest: static build of TkAqua tktest for debugging. 237 tktest-X11: static build of TkX11 tktest for debugging. 238The following build configurations are available: 239 Debug: debug build for the active architecture, 240 with Fix & Continue enabled. 241 Debug gcc42: use gcc 4.2 compiler. 242 Debug gcc42 nogc: disable Objective-C garbage collection. 243 Debug llvmgcc42: use llvm-gcc 4.2 compiler. 244 DebugNoFixAndContinue: disable Fix & Continue. 245 DebugUnthreaded: disable threading. 246 DebugNoCF: disable corefoundation (X11 only). 247 DebugNoCFUnthreaded: disable corefoundation an threading. 248 DebugMemCompile: enable memory and bytecode debugging. 249 DebugLeaks: define PURIFY. 250 DebugGCov: enable generation of gcov data files. 251 Debug64bit: configure with --enable-64bit (requires 252 building on a 64bit capable processor). 253 Release: release build for the active architecture. 254 ReleaseUniversal: 32/64-bit universal build. 255 ReleaseUniversal gcc42: use gcc 4.2 compiler. 256 ReleaseUniversal llvmgcc42: use llvm-gcc 4.2 compiler. 257 ReleaseUniversal10.5SDK: build against the 10.5 SDK (with 10.5 258 deployment target). 259 Note that the non-SDK configurations have their deployment target set to 260 10.5 (Tk.xcode) resp. 10.6 (Tk.xcodeproj). 261The Xcode projects refer to the toplevel tcl and tk source directories via the 262the TCL_SRCROOT and TK_SRCROOT user build settings, by default these are set to 263the project-relative paths '../../tcl' and '../../tk', if your source 264directories are named differently, e.g. '../../tcl8.6' and '../../tk8.6', you 265need to manually change the TCL_SRCROOT and TK_SRCROOT settings by editing your 266${USER}.pbxuser file (located inside the Tk.xcodeproj bundle directory) with a 267text editor. 268 269- To build universal binaries outside of the Xcode IDE, set CFLAGS as follows: 270 export CFLAGS="-arch i386 -arch x86_64 -arch ppc" 271This requires Mac OS X 10.4 and Xcode 2.4 (or Xcode 2.2 if -arch x86_64 is 272omitted, but _not_ Xcode 2.1) and will work on any architecture (on PowerPC 273Tiger you need to add "-isysroot /Developer/SDKs/MacOSX10.4u.sdk"). 274Note that configure requires CFLAGS to contain a least one architecture that can 275be run on the build machine (i.e. ppc on G3/G4, ppc or ppc64 on G5, ppc or i386 276on Core and ppc, i386 or x86_64 on Core2/Xeon). 277Universal builds of Tcl TEA extensions are also possible with CFLAGS set as 278above, they will be [load]able by universal as well as thin binaries of Tcl. 279 280- To enable weak-linking, set the MACOSX_DEPLOYMENT_TARGET environment variable 281to the minimal OS version the binaries should be able to run on, e.g: 282 export MACOSX_DEPLOYMENT_TARGET=10.4 283This requires at least gcc 3.1; with gcc 4 or later, set/add to CFLAGS instead: 284 export CFLAGS="-mmacosx-version-min=10.4" 285Support for weak-linking was added with 8.4.14/8.5a5. 286 287Detailed Instructions for building with macosx/GNUmakefile 288---------------------------------------------------------- 289 290- Unpack the Tcl and Tk source release archives and place the tcl and tk source 291trees in a common parent directory. 292[ If you don't want have the two source trees in one directory, you'll need to ] 293[ create the following symbolic link for the build to work as setup by default ] 294[ ln -fs /path_to_tcl/build /path_to_tk/build ] 295[ (where /path_to_{tcl,tk} is the directory containing the tcl resp. tk tree) ] 296[ or you can pass an argument of BUILD_DIR=/somewhere to the tcl and tk make. ] 297 298- The following instructions assume the Tcl and Tk source trees are named 299"tcl${ver}" and "tk${ver}" (where ${ver} is a shell variable containing the 300Tcl/Tk version number, e.g. '8.6'). 301Setup this shell variable as follows: 302 ver="8.6" 303If you are building from CVS, omit this step (CVS source tree names usually do 304not contain a version number). 305 306- Setup environment variables as desired, e.g. for a universal build on 10.5: 307 CFLAGS="-arch i386 -arch x86_64 -arch ppc -mmacosx-version-min=10.5" 308 export CFLAGS 309 310- Change to the directory containing the Tcl and Tk source trees and build: 311 make -C tcl${ver}/macosx 312 make -C tk${ver}/macosx 313 314- Install Tcl and Tk onto the root volume (admin password required): 315 sudo make -C tcl${ver}/macosx install 316 sudo make -C tk${ver}/macosx install 317if you don't have an admin password, you can install into your home directory 318instead by passing an INSTALL_ROOT argument to make: 319 make -C tcl${ver}/macosx install INSTALL_ROOT="${HOME}/" 320 make -C tk${ver}/macosx install INSTALL_ROOT="${HOME}/" 321 322- The default GNUmakefile targets will build _both_ debug and optimized versions 323of the Tcl and Tk frameworks with the standard convention of naming the debug 324library Tcl.framework/Tcl_debug resp. Tk.framework/Tk_debug. 325This allows switching to the debug libraries at runtime by setting 326 export DYLD_IMAGE_SUFFIX=_debug 327(c.f. man dyld for more details) 328 329If you only want to build and install the debug or optimized build, use the 330'develop' or 'deploy' target variants of the GNUmakefile, respectively. 331For example, to build and install only the optimized versions: 332 make -C tcl${ver}/macosx deploy 333 make -C tk${ver}/macosx deploy 334 sudo make -C tcl${ver}/macosx install-deploy 335 sudo make -C tk${ver}/macosx install-deploy 336 337- The GNUmakefile can also build a version of Wish.app that has the Tcl and Tk 338frameworks embedded in its application package. This allows for standalone 339deployment of the application with no installation required, e.g. from read-only 340media. To build & install in this manner, use the 'embedded' variants of 341the GNUmakefile targets. 342For example, to build a standalone 'Wish.app' in ./emb/Applications/Utilities: 343 make -C tcl${ver}/macosx embedded 344 make -C tk${ver}/macosx embedded 345 sudo make -C tcl${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/emb/ 346 sudo make -C tk${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/emb/ 347Notes: 348 * if you've already built standard TclTkAqua, building embedded does not 349 require any new compiling or linking, so you can skip the first two makes. 350 (making relinking unnecessary was added with 8.4.2) 351 * the embedded frameworks include only optimized builds and no documentation. 352 * the standalone Wish has the directory Wish.app/Contents/lib in its 353 auto_path. Thus you can place tcl extensions in this directory (i.e. embed 354 them in the app package) and load them with [package require]. 355 356- It is possible to build Tk against an installed Tcl.framework; but you will 357still need a tcl sourcetree in the location specified in TCL_SRC_DIR in 358Tcl.framework/tclConfig.sh. Also, linking with Tcl.framework has to work exactly 359as indicated in TCL_LIB_SPEC in Tcl.framework/tclConfig.sh. 360If you used non-default install locations for Tcl.framework, specify them as 361make overrides to the tk/macosx GNUmakefile, e.g. 362 make -C tk${ver}/macosx \ 363 TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin 364 sudo make -C tk${ver}/macosx install \ 365 TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin 366The Makefile variables TCL_FRAMEWORK_DIR and TCLSH_DIR were added with Tk 8.4.3. 367