diff options
Diffstat (limited to 'macosx/README')
| -rw-r--r-- | macosx/README | 260 |
1 files changed, 157 insertions, 103 deletions
diff --git a/macosx/README b/macosx/README index b06c454..86dacf8 100644 --- a/macosx/README +++ b/macosx/README @@ -1,44 +1,51 @@ -TclTkAqua README ----------------- +Tcl/Tk Mac OS X README +---------------------- -RCS: @(#) $Id: README,v 1.13 2005/05/23 20:24:59 das Exp $ +RCS: @(#) $Id: README,v 1.14 2005/11/27 02:36:14 das Exp $ -This is the README file for the Mac OS X native versions of Tcl & Tk. +This is the README file for the Mac OS X/Darwin version of Tcl/Tk. -1. General ----------- +1. Where to go for support +-------------------------- -- The tcl-mac mailing list on sourceforge is the canonical place for questions +- The tcl-mac mailing list on sourceforge is the best place to ask 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/ +- For general Tcl/Tk questions, the newsgroup comp.lang.tcl is your best bet: + http://groups.google.com/group/comp.lang.tcl/ -- The wiki has a page listing known bugs in Mac OS X Tcl/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 +- The Tcl'ers Wiki also has many pages dealing with Tcl & Tk on Mac OS X, see + http://wiki.tcl.tk/references/3753! + http://wiki.tcl.tk/references/8361! -- You should report bugs to the sourceforge bug trackers as usual: - Tcl: https://sourceforge.net/tracker/?func=add&group_id=10894&atid=110894 - Tk: https://sourceforge.net/tracker/?func=add&group_id=12997&atid=112997 -please make sure that your report Tk specific bugs to the tktoolkit bug -tracker and not the tcl one. +- Please report bugs with Tcl or Tk on Mac OS X to the sourceforge bug trackers: + Tcl: http://sf.net/tracker/?func=add&group_id=10894&atid=110894 + Tk: http://sf.net/tracker/?func=add&group_id=12997&atid=112997 +please make sure that your report Tk specific bugs to the tktoolkit project bug +tracker rather than the tcl project bug tracker. +Mac OS X specific bugs should usually be assigned to 'das' or 'wolfsuit'. -2. Using TclTkAqua ------------------- +2. Using Tcl/Tk on Mac OS X +--------------------------- -- Mac OS X 10.2 (or higher) is required to run TclTkAqua. +- There are two versions of Tk available on Mac OS X: TkAqua using the native +aqua widgets and look&feel, and TkX11 using the traditional unix X11 wigets. +TkX11 requires an X11 server to be installed, such as Apple's X11 (which is +available as an optional install on recent Mac OS X retail disks). +TkAqua and TkX11 can be distinguished at runtime via [tk windowingsystem]. -- Tcl built on Mac OS X 10.3 or higher will not run on 10.2 due to missing -symbols in libSystem, however Tcl built on 10.2 will run on 10.3 (but without -prebinding and other optimizations). +- At a minimum, Mac OS X 10.1 is required to run Tcl and TkX11, and OS X 10.2 is +required to run TkAqua. However OS X 10.3 or higher is recommended (certain +[file] operations behave incorrectly on earlier releases). + +- Tcl/Tk built on Mac OS X 10.x will not run on 10.y for y < x, on the other +hand Tcl/Tk built on 10.y will run on 10.x for y < x (but without any of the +fixes and optimizations that would be available in a binary built on 10.x). - 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 @@ -46,117 +53,165 @@ 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 +brings up the Tk console window at startup. This is the case when double clicking Wish in the Finder (or using 'open Wish.app' from the Terminal). -- Tcl extensions will be found in any of: +- Tcl extensions can be installed 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 the usual $pkg/pkgIndex.tcl. -This allows building extensions as frameworks with all script files contained -in the Resources/Scripts directory of the framework. +This allows building extensions as frameworks with all script files contained in +the Resources/Scripts directory of the framework. + +- [load]able binary extensions can linked as either ordinary shared libraries +(.dylib) or as MachO bundles (since 8.4.10/8.5a3); only bundles can be unloaded, +and bundles are also loaded more efficiently from VFS (no temporary copy to the +native filesystem required). -- The Tcl and Tk frameworks contain documentation in html format in the -standard location for frameworks: +- The 'deploy' target of macosx/Makefile installs the html manpages into the +standard documentation location in the Tcl/Tk frameworks: Tcl.framework/Resources/Documentation/Reference/Tcl Tk.framework/Resources/Documentation/Reference/Tk -No manpages are installed by default for either tcl or tk. +No nroff manpages are installed by default by the Makefiles. -- the frameworks Tcl.framework and Tk.framework can be placed in any of the -system's standard framework directories: +- The Tcl and Tk frameworks can be installed in any of the system's standard +framework directories: $HOME/Library/Frameworks /Library/Frameworks /Network/Library/Frameworks /System/Library/Frameworks -and 'Wish' as well as /usr/bin/tclsh will work. -- /usr/bin/wish is a script that calls a copy of 'Wish' contained in +- /usr/bin/wish8.x is a script that calls a copy of 'Wish' contained in Tk.framework/Resources - if 'Wish' 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 +- 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). -- As of Tk 8.4.7, AquaTk has a version of the low-level drawing primitives using +- As of Tk 8.4.7, TkAqua has a version of the low-level drawing primitives using the CoreGraphics routines - the code is primarily due to James Tittle. There were numerous problems with the QD version, mostly due to the different drawing -model of QD & Tk. CG also trivially supports dashed lines, and the various end -caps & miters. So this is a great improvement. - -The old QD code is retained for now, just in case there are any -compatibility problems. To switch back to the QD drawing, just put: - -set tk::mac::useCGDrawing 0 - -in your script before you do drawing. Also the CG drawing can anti-alias line drawing. -However, anti-aliased thin lines look washed out, so the threshold for antialiasing -is set to 3 pixel width lines. You can change this if you want by putting: - -set tk::mac::CGAntialiasLimit <limit> - -in your script before drawing, in which case only lines thinner that <limit> pixels -will not be antialiased. +model of QD & Tk. CG also trivially supports dashed lines, and the various end +caps & miters. So this is a great improvement. +The old QD code is retained for now, just in case there are any compatibility +problems. To switch back to the QD drawing, just put: + set tk::mac::useCGDrawing 0 +in your script before you do drawing. Also the CG drawing can anti-alias line +drawing. However, anti-aliased thin lines look washed out, so the threshold for +antialiasing is set to 3 pixel width lines. You can change this if you want by +putting: + set tk::mac::CGAntialiasLimit <limit> +in your script before drawing, in which case only lines thinner that <limit> +pixels will not be antialiased. - 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. +allows to dis/enable antialiasing on the fly from Tcl (even for existing text). -- 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.2. +- 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.2. -- 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 +- 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: +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.2 -- If you want to use Remote Debugging with Xcode 1.5 or 2.0, then you need to set -the environment variable XCNOSTDIN to 1 in the Executable editor for Wish. That -will cause us to force closing stdin & stdout. Otherwise, given how Xcode launches -Wish remotely, they will be left open and then Wish & gdb will fight for stdin... - -3. Building TclTkAqua ---------------------- - -- Mac OS X 10.2 (or higher) is required to build TclTkAqua on MacOSX. - -- Apple's Developer Tools CD needs to be installed (the most recent version -matching your OS release, but no earlier than December 2002). This CD should -have come with Mac OS X retail or should be present as a disk image on new macs -that came with OSX preinstalled. It can also be downloaded from -http://connect.apple.com (after you register for free ADC membership). - -- Tcl and Tk are built as a Mac OS X frameworks via the Makefiles in tcl/macosx -and tk/macosx, but can also be built directly with the standard unix configure -and make buildsystem in tcl/unix resp. tk/unix. - -- It is still possible to build with Apple's Xcode IDE using the Tcl.pbproj and -Wish.pbproj projects but this is not recommended anymore (currently Tcl.pbproj -calls through to the tcl/macosx/Makefile; but Wish.pbproj doesn't, so there could -be build differences). - -- Unpack the tcl and tk source release archives and place the tcl and tk source +- If you want to use Remote Debugging with Xcode 1.5 or 2.2, then you need to +set the environment variable XCNOSTDIN to 1 in the Executable editor for Wish. +That will cause us to force closing stdin & stdout. Otherwise, given how Xcode +launches Wish remotely, they will be left open and then Wish & gdb will fight +for stdin... + + +3. Building Tcl/Tk on Mac OS X +------------------------------ + +- At least Mac OS X 10.1 is required to build Tcl and TkX11 and OS X 10.2 is +required to build TkAqua. Apple's Developer Tools need to be installed (only the +most recent version matching your OS release is supported). The Developer Tools +installer is available on Mac OS X retail disks or is present in +/Applications/Installers on Macs that came with OS X preinstalled. The most +recent version can be downloaded from the ADC website http://connect.apple.com +(after you register for free ADC membership). + +- Tcl/Tk are most easily built as Mac OS X frameworks via Makefile in +tcl/macosx and tk/macosx (see below for details), but can also be built with the +standard unix configure and make buildsystem in tcl/unix resp. tk/unix as on any +other unix platform (indeed, the Makefiles are just wrappers around the unix +buildsystem). +The Mac OS X specifc configure flags are --enable-aqua, --enable-framework and +--disable-corefoundation (which disables CF and notably reverts to the standard +select based notifier, you will only need this if your require use of naked fork +(i.e. not followed by execve) in an unthreaded core). Note that --enable-aqua is +incompatible with --disable-corefoundation (for both Tcl and Tk configure). + +- It is also possible to build with Apple's IDE via the projects in tk/macosx, +take care to only use the project matching your DevTools and OS version: + * Wish.pbproj for ProjectBuilder on 10.2 and earlier, this has a 'Tk' target + that simply calls through to the tcl/macosx/GNUMakefile. It requires a + build of the 'Tcl' target of the tcl/macosx/Tcl.pbproj project. + * Wish.xcode for Xcode 1.5 on 10.3, this additionally has a native 'tktest' + target useful for debugging, this target's 'Development' buildstyle + has ZeroLink and Fix&Continue enabled, use the 'DevelNoFixZL' buildstyle + if you need a debug build without these features. + * Wish.xcodeproj for Xcode 2.2 on 10.4, this additionally has a + 'ReleaseUniversal'configuration which builds both the 'Tk' and the + 'tktest' targets as universal binaries for ppc and i386. +Notes about the native targets of the Xcode projects: + * the Xcode projects refer to the tcl and source directories with a relative + path of ../../tcl and ../../tk to the project location, if your source + directories are named differently you'll need to enter the correct path + in the info panel of the 'Tcl Sources' and 'Tk Sources' groups. + * XCode 1.5 has a bug that causes Fix&Continue and the Build menu items + Compile/Preprocess/ShowAssembly to fail in presence of relative paths to + source files, as a workaround change the Path Type of the 'Tcl Sources' + and 'Tk Sources' groups to 'Absolute Path' in the groups' Info panel. + (fixed in Xcode 2.2) + * the native targets need a version of the unix configure scripts with + config headers enabled, this is automatically generated as + tcl/macosx/configure and tk/macosx/configure by the project but this + requires 2.59 versions of autoconf & autoheader, which are not available + on on Mac OS X 10.3 by default, and so need to be installed manually. By + default they are assumed to be installed as /usr/local/bin/autoconf-2.59 + and /usr/local/bin/autoheader-2.59, set the env vars AUTOCONF and + AUTOHEADER to their true locations if necessary. + +- To build universal binaires outside of Wish.xcodeproj, set CFLAGS as follows: + export CFLAGS="-arch ppc -arch i386 \ + -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4" +This requires Mac OS X 10.4 and Xcode 2.2 (_not_ Xcode 2.1) and will work on +any of the architectures (on i386 DTKs, the -isysroot is not required). +Note that it is not possible to configure correctly if the current architecture +is not present in CFLAGS (i.e. -arch `arch` must always be there). +Universal builds of Tk TEA extensions are also possible with CFLAGS set as +above, they will be [load]able by universal as well as thin binaries of Tk. +Note that while Tcl can be built for the ppc64 architecture, neither TkAqua nor +TkX11 can be built with -arch ppc64 as the corresponding GUI libraries are not +available for 64bit at present. However, linking a universal 'ppc i386' Tk +binary against a universal 'ppc ppc64 i386' Tcl binary works just fine. + +Detailed Instructions for building with macosx/Makefile +------------------------------------------------------- + +- Unpack the Tcl and Tk source release archives and place the tcl and tk source trees in a common parent directory. [ If you don't want have the two source trees in one directory, you'll need to ] [ create the following symbolic link for the build to work as setup by default ] @@ -164,17 +219,17 @@ trees in a common parent directory. [ (where /path_to_{tcl,tk} is the directory containing the tcl resp. tk tree) ] [ or you can pass an argument of BUILD_DIR=/somewhere to the tcl and tk make. ] -- The following instructions assume the tcl and tk source trees are named +- The following instructions assume the Tcl and Tk source trees are named "tcl${ver}" and "tk${ver}", respectively, where ${ver} is a shell variable -containing the tcl and tk version number (for example '8.4.2'). +containing the Tcl and Tk version number (for example '8.4.12'). Setup the shell variable as follows: - set ver="8.4.2" ;: if your shell is csh - ver="8.4.2" ;: if your shell is sh + set ver="8.4.12" ;: if your shell is csh + ver="8.4.12" ;: if your shell is sh The source trees will be named this way only if you are building from a release archive, if you are building from CVS, the version numbers will be missing; so set ${ver} to the empty string instead: - set ver="" ;: if your shell is csh - ver="" ;: if your shell is sh + set ver="" ;: if your shell is csh + ver="" ;: if your shell is sh - The following steps will build Tcl and Tk from the Terminal, assuming you are located in the directory containing the tcl and tk source trees: @@ -225,13 +280,12 @@ Notes: - It is possible to build Tk against an installed Tcl.framework; but you will still need a tcl sourcetree in the location specified in TCL_SRC_DIR in -Tcl.framework/tclConfig.sh. Also, linking with Tcl.framework has to work -exactly as indicated in TCL_LIB_SPEC in Tcl.framework/tclConfig.sh. +Tcl.framework/tclConfig.sh. Also, linking with Tcl.framework has to work exactly +as indicated in TCL_LIB_SPEC in Tcl.framework/tclConfig.sh. If you used non-default install locations for Tcl.framework, specify them as make overrides to the tk/macosx Makefile, e.g. make -C tk${ver}/macosx \ TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin sudo make -C tk${ver}/macosx install \ TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin - The Makefile variables TCL_FRAMEWORK_DIR and TCLSH_DIR were added in Tk 8.4.3. |