TclTkAqua README ---------------- RCS: @(#) $Id: README,v 1.4 2003/02/11 07:26:18 wolfsuit Exp $ This is the README file for the Mac OS X native versions of Tcl & Tk. 1. General ---------- - The tcl-mac mailing list on sourceforge is the canonical place for questions specific to Tcl & Tk on Mac OS X: http://lists.sourceforge.net/lists/listinfo/tcl-mac (this page also has a link to searchable archives of the list, please check them before asking on the list, many questions have already been answered). - For general tcl/tk questions, the newsgroup comp.lang.tcl is your best bet, but also check the Tcl'ers Wiki for a wealth of information: http://wiki.tcl.tk/ - The wiki has a page listing known bugs in Mac OS X Tk (and other tips) http://wiki.tcl.tk/MacOS%20X as well as a page with info on building Tcl/Tk on Mac OS X http://wiki.tcl.tk/Steps%20to%20build%20Tcl/Tk%208.4.0%20on%20MacOS%20X - You should report bugs to the sourceforge bug trackers as usual: https://sourceforge.net/tracker/?func=add&group_id=10894&atid=110894 https://sourceforge.net/tracker/?func=add&group_id=12997&atid=112997 2. Using TclTkAqua ------------------ - Mac OS X 10.1 (or higher) is required to run TclTkAqua. - Tcl built on Mac OS X 10.2 or higher will not run on 10.1 due to missing symbols in libSystem, however Tcl built on 10.1 will run on 10.2 (but without prebinding and other optimizations). - Wish checks the Resources/Scripts directory in its application bundle for a file called AppMain.tcl, if found it is used as the startup script and the Scripts folder is added to the auto_path. This can be used to emulate the old OS9 TclTk droplets. - If standard input is a special file of zero length (e.g. /dev/null), Wish brings up the tk console window at startup. This is the case when double clicking Wish in the finder (or using 'open Wish\ Shell.app' from the Terminal). - Tcl extensions will be found in any of: $HOME/Library/Tcl /Library/Tcl /Network/Library/Tcl /System/Library/Tcl $HOME/Library/Frameworks /Library/Frameworks /Network/Library/Frameworks /System/Library/Frameworks (searched in that order). Given a potential package directory $pkg, Tcl on OSX checks for the file $pkg/Resources/Scripts/pkgIndex.tcl as well as $pkg/pkgIndex.tcl (as usual). This allows building extensions as frameworks with all script files contained in the Resources/Scripts directory of the framework. - Tcl.framework contains the Tcl and Tk documentation in html format in the standard location for frameworks: Tcl.framework/Resources/English.lproj/Documentation/Reference/Tcl Tk.framework contains no documentation, and no manpages are installed by default. - the frameworks Tcl.framework and Tk.framework can be placed in any of the system's standard framework directories: $HOME/Library/Frameworks /Library/Frameworks /Network/Library/Frameworks /System/Library/Frameworks and 'Wish Shell' as well as /usr/bin/tclsh will work. - /usr/bin/wish is a script that calls 'Wish Shell' in its default location /Applications/Utilities/Wish Shell.app it will break if 'Wish Shell' is moved. - if 'Wish Shell' is started from the Finder or via 'open', $argv contains a "-psn_XXXX" argument. This is the Wish's carbon process serial number, you may need to filter it out for cross platform compatibility of your scripts. - the env array is different when Wish is started from the Finder than when it (or tclsh) is invoked from the Terminal, in particular PATH may not be what you expect. (Wish started from the Finder inherits the Finder's environment variables, which are essentially those set in $HOME/.MacOSX/environment.plist and not those set by your shell configuration files). - Quickdraw text antialiasing is enabled by default when available (from 10.1.5 onwards). Changing the global boolean variable '::tk::mac::antialiasedtext' allows to dis/enable antialiasing on the fly from tcl (even for existing text). - the format of binary extensions expected by [load] is that of ordinary shared libraries (.dylib) and not MachO bundles, at present loading of MachO bundles is not supported. - Scrollbars: There are two scrollbar variants in Aqua, normal & small. The normal scrollbar has a small dimension of 16, the small variant 12. Access to the small variant was added in Tk 8.4.3. - Cursors: You can now put up and spin the Classic MacOS spinner, and the counting hands and watch cursor. The way this is done is each of the spinners have a base name: spinning: The circular B&W circular spinner countinguphand: The counting up hand countingdownhand: The counting down hand countingupanddownhand: The counting up then down hand watch: The watch cursor Then to get the sequential variants, add an integer to the end of the base name. So, for instance this code will spin the spinner: proc spinCursor {widget count} { $widget configure -cursor spinning$count after 100 spinCursor [incr count] } This was added in Tk 8.4.3 3. Building TclTkAqua --------------------- - Apple's Developer Tools CD needs to be installed (the version matching your OS release). This CD should have come with Mac OS X retail or should be present as a disk image on new macs that had OSX preinstalled. It can also be downloaded from http://connect.apple.com (free ADC membership required). - Mac OS X 10.1.5 with the April 2002 Developer Tools update (or higher) is required to build TclTkAqua. - Tcl and TkAqua are built as Mac OS X frameworks using Apple's ProjectBuilder IDE, but you do not have to deal with the IDE if you don't want to: there are Makefiles available in tcl/macosx and tk/macosx that take care of calling the ProjectBuilder command line tool with all the details taken care of. - For the following instructions to work as is, the tcl and tk source trees should be located in a common directory and be named 'tcl' resp. 'tk' (as is the case when building directly from CVS). You need to adapt the paths in the instructions if they are named differently (e.g. when building from a distribution tarball), but the build process will still work fine. If the source trees are not located in the same directory, you'll need to create a symbolic link ln -fs /path_to_tcl/build /path_to_tk/build (where /path_to_{tcl,tk} is the directory where the 'tcl' resp. 'tk' sourcetree is located) for the build to work as setup by default by the Makefiles; or you can pass an argument of BUILD_DIR=somewhere to both the tcl and tk make. - If you're only interested in _building_ TclTkAqua and don't plan on doing development with the ProjectBuilder projects, using the Makefiles is easiest. The following steps will build Tcl and Tk from the Terminal (assuming you are located in the directory above the tcl and tk source trees): make -C tcl/macosx make -C tk/macosx and the following will then install Tcl and Tk onto the root volume (admin privileges required): sudo make -C tcl/macosx install sudo make -C tk/macosx install you can also pass an INSTALL_ROOT argument to 'make install', e.g. make -C tcl/macosx install INSTALL_ROOT=$HOME make -C tk/macosx install INSTALL_ROOT=$HOME will install into you home directory (useful if you're not an admin on your machine) - The default Makefile targets will build _both_ debug and optimized versions of the Tcl and Tk frameworks with the standard convention of naming the debug library Tcl.framework/Tcl_debug resp. Tk.framework/Tk_debug. This allows to dynamically link to the debug library at runtime by setting setenv DYLD_IMAGE_SUFFIX _debug (c.f. man dyld for more details) If you only want to build/install the debug resp. optimized build, use the 'develop' resp. 'deploy' target variants of the Makefiles, e.g. make -C tcl/macosx deploy make -C tk/macosx deploy sudo make -C tcl/macosx install-deploy sudo make -C tk/macosx install-deploy will build and install only the optimized versions. - The Makefiles can also build a version of 'Wish Shell' that has the Tcl and Tk frameworks embedded in its application package, this allows for standalone deployment of the application with no installation required, e.g. from read-only media. To build & install in this manner, use the 'embedded' target variants of the Makefiles, i.e. make -C tcl/macosx embedded make -C tk/macosx embedded make -C tcl/macosx install-embedded INSTALL_ROOT=`pwd`/embedded make -C tk/macosx install-embedded INSTALL_ROOT=`pwd`/embedded will build a standalone 'Wish Shell.app' in ./embedded/Applications/Utilities (if you've already built standard TclTkAqua, this only requires a relink). Note that the embedded frameworks include only optimized builds and no documentation. The standalone Wish has the directory Wish\ Shell.app/Contents/lib in its auto_path, this can be used to embed tcl extensions into the app package and have them automatically available via [package require]. - To build from the IDE using the projects directly without going through the Makefiles you need so setup a common build folder for the projects. A simple way to achieve this is to make symbolic links ln -fs ../../build tcl/macosx/build ln -fs ../../build tk/macosx/build (this location of the build folder is compatible with the Makefiles). Another way is to set the build folder location directly in tcl/macosx/Tcl.pbproj and tk/macosx/Wish/pbproj using ProjectBuilder's "Project->Show Info" on the topmost icon in the filelist. Switch to "Place build products in a separate location" with a setting of "$SRCROOT/../../build" (this gets stored in Tcl.pbproj/$USER.pbxuser & Wish.pbproj/$USER.pbxuser).