summaryrefslogtreecommitdiffstats
path: root/macosx/README
diff options
context:
space:
mode:
Diffstat (limited to 'macosx/README')
-rw-r--r--macosx/README260
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.