1Tcl Mac OS X README 2------------------- 3 4RCS: @(#) $Id: README,v 1.16.2.1 2008/06/12 06:33:01 das Exp $ 5 6This is the README file for the Mac OS X/Darwin version of Tcl. 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 on Mac OS X 34------------------------ 35 36- At a minimum, Mac OS X 10.1 is required to run Tcl, but OS X 10.3 or higher is 37recommended (certain [file] operations behave incorrectly on earlier releases). 38 39- Unless weak-linking is used, Tcl built on Mac OS X 10.x will not run on 10.y 40with y < x; on the other hand Tcl built on 10.y will always run on 10.x with 41y <= x (but without any of the fixes and optimizations that would be available 42in a binary built on 10.x). 43Weak-linking is available on OS X 10.2 or later, it additionally allows Tcl 44built on 10.x to run on any 10.y with x > y >= z (for a chosen z >= 2). 45 46- Tcl extensions can be installed in any of: 47 $HOME/Library/Tcl /Library/Tcl /Network/Library/Tcl /System/Library/Tcl 48 $HOME/Library/Frameworks /Library/Frameworks /Network/Library/Frameworks 49 /System/Library/Frameworks (searched in that order). 50Given a potential package directory $pkg, Tcl on OSX checks for the file 51$pkg/Resources/Scripts/pkgIndex.tcl as well as the usual $pkg/pkgIndex.tcl. 52This allows building extensions as frameworks with all script files contained in 53the Resources/Scripts directory of the framework. 54 55- [load]able binary extensions can linked as either ordinary shared libraries 56(.dylib) or as MachO bundles (since 8.4.10/8.5a3); only bundles can be unloaded, 57and bundles are also loaded more efficiently from VFS (no temporary copy to the 58native filesystem required). 59 60- The 'deploy' target of macosx/GNUmakefile installs the html manpages into the 61standard documentation location in the Tcl framework: 62 Tcl.framework/Resources/Documentation/Reference/Tcl 63No nroff manpages are installed by default by the GNUmakefile. 64 65- The Tcl framework can be installed in any of the system's standard 66framework directories: 67 $HOME/Library/Frameworks /Library/Frameworks 68 /Network/Library/Frameworks /System/Library/Frameworks 69 70 713. Building Tcl on Mac OS X 72--------------------------- 73 74- At least Mac OS X 10.1 is required to build Tcl, and Apple's Developer Tools 75need to be installed (only the most recent version matching your OS release is 76supported). The Developer Tools installer is available on Mac OS X retail disks 77or is present in /Applications/Installers on Macs that came with OS X 78preinstalled. The most recent version can be downloaded from the ADC website 79http://connect.apple.com (after you register for free ADC membership). 80 81- Tcl is most easily built as a Mac OS X framework via GNUmakefile in tcl/macosx 82(see below for details), but can also be built with the standard unix configure 83and make buildsystem in tcl/unix as on any other unix platform (indeed, the 84GNUmakefile is just a wrapper around the unix buildsystem). 85The Mac OS X specific configure flags are --enable-framework and 86--disable-corefoundation (which disables CF and notably reverts to the standard 87select based notifier). 88 89- It is also possible to build with Apple's IDE via the projects in tcl/macosx, 90take care to only use the project matching your DevTools and OS version: 91 * Tcl.pbproj for Xcode or ProjectBuilder on 10.3 and earlier, this has a 92 'Tcl' target that simply calls through to the tcl/macosx/GNUMakefile. 93 * Tcl.xcode for Xcode 2.4 on 10.4 and Xcode 2.5 on 10.4 and later, which 94 additionally has native 'tcltest' and 'tests' targets for debugging and 95 running the testsuite, these targets' 'Debug' build configuration has 96 ZeroLink and Fix&Continue enabled, use the 'DebugNoFixZL' build 97 configuration if you need a debug build without these features. The 98 following build configurations are available: 99 'DebugUnthreaded': debug build with threading turned off. 100 'DebugNoCF': debug build with corefoundation turned off. 101 'DebugNoCFUnthreaded': debug build with corefoundation & threading off. 102 'DebugMemCompile': debug build with memory and bytecode debugging on. 103 'DebugLeaks': debug build with PURIFY defined. 104 'DebugGCov': debug build with generation of gcov data files enabled. 105 'Debug64bit': builds the targets as 64bit with debugging enabled, 106 requires a 64bit capable processor (i.e. G5 or Core2/Xeon). 107 'ReleaseUniversal': builds the targets as universal binaries for the 108 ppc, ppc64, i386 and x86_64 architectures. 109 'ReleaseUniversal10.4uSDK': same as 'ReleaseUniversal' but builds 110 against the 10.4u SDK, required to build universal binaries on 111 PowerPC Tiger (where the system libraries are not universal). 112 'ReleasePPC10.3.9SDK': builds for PowerPC against the 10.3.9 SDK, useful 113 for verifying on Tiger that building on Panther would succeed. 114 'ReleasePPC10.2.8SDK': builds for PowerPC with gcc-3.3 against the 115 10.2.8 SDK, useful to verify on Tiger that building on Jaguar 116 would succeed. 117 * Tcl.xcodeproj for Xcode 3.1 on 10.5 and later, which has the following 118 additional build configurations: 119 'ReleaseUniversal10.5SDK': same as 'ReleaseUniversal' but builds 120 against the 10.5 SDK on Leopard (with 10.5 deployment target). 121 'Debug gcc42': same as 'Debug' but builds with gcc 4.2. 122 'Debug llvmgcc42': same as 'Debug' but builds with llvm-gcc 4.2. 123 'ReleaseUniversal gcc42': same as 'ReleaseUniversal' but builds with 124 gcc 4.2. 125 'ReleaseUniversal llvmgcc42': same as 'ReleaseUniversal' but builds 126 with llvm-gcc 4.2. 127 Note that all non-SDK configurations have 10.5 deployment target. 128 129Notes about the native targets of the Xcode projects: 130 * the Xcode projects refer to the toplevel tcl source directory through the 131 TCL_SRCROOT user build setting, by default this is set to the 132 project-relative path '../../tcl', if your tcl source directory is named 133 differently, e.g. '../../tcl8.5', you'll need to manually change the 134 TCL_SRCROOT setting by editing your ${USER}.pbxuser file (located inside 135 the Tcl.xcodeproj bundle directory) with a text editor. 136 * the native targets need a version of the unix configure script with config 137 headers enabled, this is automatically generated as tcl/macosx/configure 138 by the project but that requires 2.59 versions of autoconf & autoheader. 139 These are not available on Mac OS X 10.5 by default and need to be 140 installed manually. By default they are assumed to be installed as 141 /usr/local/bin/autoconf-2.59 and /usr/local/bin/autoheader-2.59, set the 142 AUTOCONF and AUTOHEADER build settings in ${USER}.pbxuser to their true 143 locations if necessary. 144 145- To build universal binaries outside of Tcl.xcodeproj, set CFLAGS as follows: 146 export CFLAGS="-arch ppc -arch ppc64 -arch i386 -arch x86_64 \ 147 -isysroot /Developer/SDKs/MacOSX10.4u.sdk -mmacosx-version-min=10.4" 148This requires Mac OS X 10.4 and Xcode 2.4 (or Xcode 2.2 if -arch x86_64 is 149omitted, but _not_ Xcode 2.1) and will work on any of the architectures (the 150-isysroot flag is only required on PowerPC Tiger). 151Note that configure requires CFLAGS to contain a least one architecture that can 152be run on the build machine (i.e. ppc on G3/G4, ppc or ppc64 on G5, ppc or i386 153on Core and ppc, i386 or x86_64 on Core2/Xeon). 154Universal builds of Tcl TEA extensions are also possible with CFLAGS set as 155above, they will be [load]able by universal as well as thin binaries of Tcl. 156 157- To enable weak-linking, set the MACOSX_DEPLOYMENT_TARGET environment variable 158to the minimal OS version (>= 10.2) the binaries should be able to run on, e.g: 159 export MACOSX_DEPLOYMENT_TARGET=10.2 160This requires Mac OS X 10.2 and gcc 3.1; if you have gcc 4 or later you can set 161CFLAGS instead: 162 export CFLAGS="-mmacosx-version-min=10.2" 163The Tcl.xcode project is setup to produce binaries that can run on 10.2 or 164later (except for the Universal and SDK configurations). 165Support for weak-linking was added to the code for 8.4.14/8.5a5. 166 167Detailed Instructions for building with macosx/GNUmakefile 168---------------------------------------------------------- 169 170- Unpack the tcl source release archive. 171 172- The following instructions assume the tcl source tree is named "tcl${ver}", 173where ${ver} is a shell variable containing the tcl version number (for example 174'8.4.12'). 175Setup the shell variable as follows: 176 set ver="8.4.12" ;: if your shell is csh 177 ver="8.4.12" ;: if your shell is sh 178The source tree will be named this way only if you are building from a release 179archive, if you are building from CVS, the version numbers will be missing; so 180set ${ver} to the empty string instead: 181 set ver="" ;: if your shell is csh 182 ver="" ;: if your shell is sh 183 184- The following steps will build Tcl from the Terminal, assuming you are located 185in the directory containing the tcl source tree: 186 make -C tcl${ver}/macosx 187and the following will then install Tcl onto the root volume (admin password 188required): 189 sudo make -C tcl${ver}/macosx install 190if you don't have the admin password, you can install into your home directory, 191instead by passing an INSTALL_ROOT argument to make: 192 make -C tcl${ver}/macosx install INSTALL_ROOT="${HOME}/" 193 194- The default Makefile targets will build _both_ debug and optimized versions of 195the Tcl framework with the standard convention of naming the debug library 196Tcl.framework/Tcl_debug. 197This allows switching to the debug libraries at runtime by setting 198 export DYLD_IMAGE_SUFFIX=_debug 199(c.f. man dyld for more details) 200 201If you only want to build and install the debug or optimized build, use the 202'develop' or 'deploy' target variants of the Makefiles, respectively. 203For example, to build and install only the optimized versions: 204 make -C tcl${ver}/macosx deploy 205 sudo make -C tcl${ver}/macosx install-deploy 206