README
1Tcl Mac OS X README
2-------------------
3
4This is the README file for the Mac OS X/Darwin version of Tcl.
5
6
71. Where to go for support
8--------------------------
9
10- The tcl-mac mailing list on sourceforge is the best place to ask questions
11specific to Tcl & Tk on Mac OS X:
12 http://lists.sourceforge.net/lists/listinfo/tcl-mac
13(this page also has a link to searchable archives of the list, please check them
14before asking on the list, many questions have already been answered).
15
16- For general Tcl/Tk questions, the newsgroup comp.lang.tcl is your best bet:
17 http://groups.google.com/group/comp.lang.tcl/
18
19- The Tcl'ers Wiki also has many pages dealing with Tcl & Tk on Mac OS X, see
20 http://wiki.tcl.tk/_/ref?N=3753
21 http://wiki.tcl.tk/_/ref?N=8361
22
23- Please report bugs with Tcl on Mac OS X to the tracker:
24 https://core.tcl-lang.org/tcl/reportlist
25
262. Using Tcl on Mac OS X
27------------------------
28
29- At a minimum, Mac OS X 10.3 is required to run Tcl.
30
31- Unless weak-linking is used, Tcl built on Mac OS X 10.x will not run on 10.y
32with y < x; on the other hand Tcl built on 10.y will always run on 10.x with
33y <= x (but without any of the fixes and optimizations that would be available
34in a binary built on 10.x).
35Weak-linking is available on OS X 10.2 or later, it additionally allows Tcl
36built on 10.x to run on any 10.y with x > y >= z (for a chosen z >= 2).
37
38- Tcl extensions can be installed in any of:
39 $HOME/Library/Tcl /Library/Tcl
40 $HOME/Library/Frameworks /Library/Frameworks
41 (searched in that order).
42Given a potential package directory $pkg, Tcl on OSX checks for the file
43$pkg/Resources/Scripts/pkgIndex.tcl as well as the usual $pkg/pkgIndex.tcl.
44This allows building extensions as frameworks with all script files contained in
45the Resources/Scripts directory of the framework.
46
47- [load]able binary extensions can linked as either ordinary shared libraries
48(.dylib) or as MachO bundles (since 8.4.10/8.5a3); bundles have the advantage
49that they are [load]ed more efficiently from a tcl VFS (no temporary copy to the
50native filesystem required), and prior to Mac OS X 10.5, only bundles can be
51[unload]ed.
52
53- The 'deploy' target of macosx/GNUmakefile installs the html manpages into the
54standard documentation location in the Tcl framework:
55 Tcl.framework/Resources/Documentation/Reference/Tcl
56No nroff manpages are installed by default by the GNUmakefile.
57
58- The Tcl framework can be installed in any of the system's standard
59framework directories:
60 $HOME/Library/Frameworks /Library/Frameworks
61
62
633. Building Tcl on Mac OS X
64---------------------------
65
66- At least Mac OS X 10.3 is required to build Tcl.
67Apple's Xcode Developer Tools need to be installed (only the most recent version
68matching your OS release is supported), the Xcode installer is available on Mac
69OS X install media or may be present in /Applications/Installers on Macs that
70came with OS X preinstalled. The most recent version can always be downloaded
71from the ADC website http://connect.apple.com (free ADC membership required).
72
73- Tcl is most easily built as a Mac OS X framework via GNUmakefile in tcl/macosx
74(see below for details), but can also be built with the standard unix configure
75and make buildsystem in tcl/unix as on any other unix platform (indeed, the
76GNUmakefile is just a wrapper around the unix buildsystem).
77The Mac OS X specific configure flags are --enable-framework and
78--disable-corefoundation (which disables CF and notably reverts to the standard
79select based notifier).
80
81- It is also possible to build with the Xcode IDE via the projects in
82tcl/macosx, take care to use the project matching your DevTools and OS version:
83 Tcl.xcode: for Xcode 3.1 on 10.5
84 Tcl.xcodeproj: for Xcode 3.2 on 10.6
85These have the following targets:
86 Tcl: calls through to tcl/macosx/GNUMakefile.
87 tcltest: static build of tcltest for debugging.
88 tests: build tcltest target and run tcl testsuite.
89The following build configurations are available:
90 Debug: debug build for the active architecture,
91 with Fix & Continue enabled.
92 Debug clang: use clang compiler.
93 Debug llvm-gcc: use llvm-gcc compiler.
94 Debug gcc40: use gcc 4.0 compiler.
95 DebugNoFixAndContinue: disable Fix & Continue.
96 DebugUnthreaded: disable threading.
97 DebugNoCF: disable corefoundation.
98 DebugNoCFUnthreaded: disable corefoundation an threading.
99 DebugMemCompile: enable memory and bytecode debugging.
100 DebugLeaks: define PURIFY.
101 DebugGCov: enable generation of gcov data files.
102 Debug64bit: configure with --enable-64bit (requires
103 building on a 64bit capable processor).
104 Release: release build for the active architecture.
105 ReleaseUniversal: 32/64-bit universal build.
106 ReleaseUniversal clang: use clang compiler.
107 ReleaseUniversal llvm-gcc: use llvm-gcc compiler.
108 ReleaseUniversal gcc40: use gcc 4.0 compiler.
109 ReleaseUniversal10.5SDK: build against the 10.5 SDK (with 10.5
110 deployment target).
111 Note that the non-SDK configurations have their deployment target set to
112 10.5 (Tcl.xcode) resp. 10.6 (Tcl.xcodeproj).
113The Xcode projects refer to the toplevel tcl source directory via the
114TCL_SRCROOT user build setting, by default this is set to the project-relative
115path '../../tcl', if your tcl source directory is named differently, e.g.
116'../../tcl8.7', you need to manually change the TCL_SRCROOT setting by editing
117your ${USER}.pbxuser file (located inside the Tcl.xcodeproj bundle directory)
118with a text editor.
119
120- To build universal binaries outside of the Xcode IDE, set CFLAGS as follows:
121 export CFLAGS="-arch i386 -arch x86_64 -arch ppc"
122This requires Mac OS X 10.4 and Xcode 2.4 (or Xcode 2.2 if -arch x86_64 is
123omitted, but _not_ Xcode 2.1) and will work on any architecture (on PowerPC
124Tiger you need to add "-isysroot /Developer/SDKs/MacOSX10.4u.sdk").
125Note that configure requires CFLAGS to contain a least one architecture that can
126be run on the build machine (i.e. ppc on G3/G4, ppc or ppc64 on G5, ppc or i386
127on Core and ppc, i386 or x86_64 on Core2/Xeon).
128Universal builds of Tcl TEA extensions are also possible with CFLAGS set as
129above, they will be [load]able by universal as well as thin binaries of Tcl.
130
131Detailed Instructions for building with macosx/GNUmakefile
132----------------------------------------------------------
133
134- Unpack the Tcl source release archive.
135
136- The following instructions assume the Tcl source tree is named "tcl${ver}",
137(where ${ver} is a shell variable containing the Tcl version number e.g. '8.7').
138Setup this shell variable as follows:
139 ver="8.7"
140If you are building from CVS, omit this step (CVS source tree names usually do
141not contain a version number).
142
143- Setup environment variables as desired, e.g. for a universal build on 10.5:
144 CFLAGS="-arch i386 -arch x86_64 -arch ppc -mmacosx-version-min=10.5"
145 export CFLAGS
146
147- Change to the directory containing the Tcl source tree and build:
148 make -C tcl${ver}/macosx
149
150- Install Tcl onto the root volume (admin password required):
151 sudo make -C tcl${ver}/macosx install
152if you don't have an admin password, you can install into your home directory
153instead by passing an INSTALL_ROOT argument to make:
154 make -C tcl${ver}/macosx install INSTALL_ROOT="${HOME}/"
155
156- The default GNUmakefile targets will build _both_ debug and optimized versions
157of the Tcl framework with the standard convention of naming the debug library
158Tcl.framework/Tcl_debug.
159This allows switching to the debug libraries at runtime by setting
160 export DYLD_IMAGE_SUFFIX=_debug
161(c.f. man dyld for more details)
162
163If you only want to build and install the debug or optimized build, use the
164'develop' or 'deploy' target variants of the GNUmakefile, respectively.
165For example, to build and install only the optimized versions:
166 make -C tcl${ver}/macosx deploy
167 sudo make -C tcl${ver}/macosx install-deploy
168
169- To build a Tcl.framework for use as a subframework in another framework, use the
170install-embedded target and set SUBFRAMEWORK=1. Set the DYLIB_INSTALL_DIR
171variable to the path which should be the install_name path of the Tcl library, set
172the DESTDIR variable to the pathname of a staging directory where the framework
173will be written . For example, running this command in the Tcl source directory:
174 make -C macosx install-embedded SUBFRAMEWORK=1 DESTDIR=/tmp/tcl \
175 DYLIB_INSTALL_DIR=/Library/Frameworks/Some.framework/Versions/X.Y/Frameworks/Tcl.framework
176will produce a Tcl.framework intended for installing as a subframework of
177Some.framework. The framework will be found in /tmp/tcl/Frameworks/
178