path: root/macosx/README

Tcl/Tk Mac OS X README
----------------------

This is the README file for the Mac OS X/Darwin version of Tcl/Tk.

1. Where to go for support
--------------------------

- 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:
	http://groups.google.com/group/comp.lang.tcl/

- The Tcl'ers Wiki also has many pages dealing with Tcl & Tk on Mac OS X, see
	http://wiki.tcl.tk/_/ref?N=3753
	http://wiki.tcl.tk/_/ref?N=8361

- Please report bugs with Tk on Mac OS X to the tracker:
	http://core.tcl.tk/tk/reportlist

2. Using Tcl/Tk on Mac OS X
---------------------------

- 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 or default install on recent Mac OS X).
TkAqua and TkX11 can be distinguished at runtime via [tk windowingsystem].

- At a minimum, Mac OS X 10.3 is required to run Tcl and TkX11.
TkAqua requires Mac OS X 10.5 or later (starting with the Cocoa-based Tk 8.5.7).

- Unless weak-linking is used, Tcl/Tk built on Mac OS X 10.x will not run on
10.y with y < x; on the other hand Tcl/Tk built on 10.y will always run on 10.x
with y <= x (but without any of the fixes and optimizations that would be
available in a binary built on 10.x).
Weak-linking is available on OS X 10.2 or later, it additionally allows Tcl/Tk
built on 10.x to run on any 10.y with x > y >= z (for a chosen z >= 2).

- 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.app' from the Terminal).

- Tcl extensions can be installed in any of:
	$HOME/Library/Tcl /Library/Tcl /System/Library/Tcl
	$HOME/Library/Frameworks /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.

- [load]able binary extensions can linked as either ordinary shared libraries
(.dylib) or as MachO bundles (since 8.4.10/8.5a3); bundles have the advantage
that they are [load]ed more efficiently from a tcl VFS (no temporary copy to the
native filesystem required), and prior to Mac OS X 10.5, only bundles can be
[unload]ed.

- The 'deploy' target of macosx/GNUmakefile 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 nroff manpages are installed by default by the GNUmakefile.

- The Tcl and Tk frameworks can be installed in any of the system's standard
framework directories:
	$HOME/Library/Frameworks /Library/Frameworks /System/Library/Frameworks

- ${prefix}/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 may contain a
"-psn_XXXX" argument. This is the 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 (i.e. via
LaunchServices) than when it (or tclsh) is invoked from the Terminal, in
particular PATH may not be what you expect. (Wish started by LaunchServices
inherits loginwindow's environment variables, which are essentially those set in
$HOME/.MacOSX/environment.plist, and are unrelated to those set in your shell).

- TkAqua drawing is antialiased by default, but (outline) linewidth can be used
to control whether a line/shape is drawn antialiased. The antialiasing threshold
is 0 by default (i.e. antialias everything), it can be changed by setting
	set tk::mac::CGAntialiasLimit <limit>
in your script before drawing, in which case lines (or shapes with outlines)
thinner than <limit> pixels will not be antialiased.

- Text antialiasing by default uses the standard OS antialising settings.
Setting the global variable '::tk::mac::antialiasedtext' allows to control text
antialiasing from Tcl: a value of 1 enables AA, 0 disables AA and -1 restores
the default behaviour of respecting the OS settings.

- Scrollbars: There are two scrollbar variants in Aqua, normal & small. The
normal scrollbar has a small dimension of 15, the small variant 11.
Access to the small variant was added in Tk 8.4.2.

- The default metrics of native buttons, radiobuttons, checkboxes and
menubuttons in the Cocoa-based Tk 8.5.7 and later preserve compatibility with
the older Carbon-based implementation, you can turn off the compatibility
metrics to get more native-looking spacing by setting:
	set tk::mac::useCompatibilityMetrics 0

- TkAqua provides access to native OS X images via the Tk native bitmap facility
(including any image file readable by NSImage). A native bitmap name is
interpreted as follows (in order):
    - predefined builtin 32x32 icon name (stop, caution, document, etc)
    - name defined by [tk::mac::iconBitmap]
    - NSImage named image name
    - NSImage url string
    - 4-char OSType of IconServices icon
the syntax of [tk::mac::iconBitmap] is as follows:
	tk::mac::iconBitmap name width height -kind value
where -kind is one of
    -file	    icon of file at given path
    -fileType	    icon of given file type
    -osType	    icon of given 4-char OSType file type
    -systemType	    icon for given IconServices 4-char OSType
    -namedImage	    named NSImage for given name
    -imageFile	    image at given path
This support was added with the Cocoa-based Tk 8.5.7.

- TkAqua cursor names are interpred as follows (in order):
    - standard or platform-specific Tk cursor name (c.f. cursors.n)
    - @path to any image file readable by NSImage
    - NSImage named image name
Support for the latter two was added with the Cocoa-based Tk 8.5.7.

- The standard Tk dialog commands [tk_getOpenFile], [tk_chooseDirectory],
[tk_getSaveFile] and [tk_messageBox] all take an additional optional -command
parameter on TkAqua. If it is present, the given command prefix is evaluated at
the global level when the dialog closes, with the dialog command's result
appended (the dialog command itself returning an emtpy result). If the -parent
option is also present, the dialog is configured as a modeless (window-modal)
sheet attached to the parent window and the dialog command returns immediately.
Support for -command was added with the Cocoa-based Tk 8.5.7.

- The TkAqua-specific [tk::mac::standardAboutPanel] command brings the standard
Cocoa about panel to the front, with all its information filled in from your
application bundle files (i.e. standard about panel with no options specified).
See Apple Technote TN2179 and the AppKit documentation for -[NSApplication
orderFrontStandardAboutPanelWithOptions:] for details on the Info.plist keys and
app bundle files used by the about panel.
This support was added with the Cocoa-based Tk 8.5.7.

- TkAqua has three special menu names that give access to the standard
Application, Window and Help menus, see menu.n for details.
By default, the platform-specific standard Help menu item "YourApp Help" peforms
the default Cocoa action of showing the Help Book configured in the
application's Info.plist (or displaying an alert if no Help Book is set). This
action can be customized by defining a procedure named [tk::mac::ShowHelp], if
present, this procedure is invoked instead by the standard Help menu item.
Support for the Window menu and [tk::mac::ShowHelp] was added with the
Cocoa-based Tk 8.5.7.

- The TkAqua-specific command [tk::unsupported::MacWindowStyle style] is used to
get and set Mac OS X-specific toplevel window class and attributes. Note that
the window class and many attributes have to be set before the window is first
mapped for the change to have any effect.
The command has the following syntax:
	tk::unsupported::MacWindowStyle style window ?class? ?attributes?
The 2 argument form returns a list of the current class and attributes for the
given window. The 3 argument form sets the class for the given window using the
default attributes for that class. The 4 argument form sets the class and the
list of attributes for the given window.
Window class names:
    document, modal, floating, utility, toolbar, simple, help, overlay
Window attribute names:
    standardDocument, standardFloating, resizable, fullZoom, horizontalZoom,
    verticalZoom, closeBox, collapseBox, toolbarButton, sideTitlebar,
    noTitleBar, unifiedTitleAndToolbar, metal, hud, noShadow, doesNotCycle,
    noActivates, hideOnSuspend, inWindowMenu, ignoreClicks, doesNotHide,
    canJoinAllSpaces, moveToActiveSpace, nonActivating, black, dark, light,
    gray, red, green, blue, cyan, yellow, magenta, orange, purple,
    brown, clear, opacity

Note that not all attributes are valid for all window classes.
Support for the 3 argument form was added with the Cocoa-based Tk 8.5.7, at the
same time support for some legacy Carbon-specific classes and attributes was
removed (they are still accepted by the command but no longer have any effect).

The color window attributes (black, dark, red, etc.) and the "opacity" allow  one to set the background and opacity of a textured ("metal") window. This allows a Tk window to implement a window without the dividing line between the titlebar and the rest of the window, or the "unified toolbar" effect, which is increasingly standard in Mac applications. An example:

toplevel .f
tk::unsupported::MacWindowStyle style .f document {metal light opaque closeBox collapseBox resizable standardDocument }

pack [label .f.f -bg  #ababab -text "This is a textured window\nwith opacity and a gray background\nsimilar to other Mac applications"] -fill both -expand yes

The color attributes correspond to system-defined NSColor constants (e.g., red is [NSColor redColor]. The "light" and "dark" attributes correspond to lightGrayColor and darkGrayColor, respectively (because of the way the attributes are parsed, using "lightgray" and "darkgray" would cause a conflict with the core "gray" attribute).

Below are the corresponding hex and/or Tk-defined colors that can be used from Tk widgets to match the NSColor-based attributes:

black	#000000
dark	#545454
light	#ababab
white	#ffffff
gray	#7f7f7f
red 	#ff0000
green	#00ff00
blue	#0000ff
cyan	#00ffff
yellow	#ffff00
magenta	#ff00ff
orange	#ff8000
purple 	#800080
brown	#996633
clear	systemTransparent

- The Cocoa-based TkAqua can be distinguished from the older Carbon-based
version via the [winfo server .] command, example output on Mac OS X 10.5.7:
    Cocoa-based:	CG409.3 Apple AppKit GC 949.46 Mac OS X 1057
    Carbon-based:	QD10R30 Apple 1057

- If you want to use Remote Debugging with Xcode, 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.3 is required to build Tcl and TkX11, and Mac OS X 10.5
is required to build TkAqua.
Apple's Xcode Developer Tools need to be installed (only the most recent version
matching your OS release is supported), the Xcode installer is available on Mac
OS X install media or may be present in /Applications/Installers on Macs that
came with OS X preinstalled. The most recent version can always be downloaded
from the ADC website http://connect.apple.com (free ADC membership required).

- Tcl/Tk are most easily built as Mac OS X frameworks via GNUmakefile 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 GNUmakefiles are just wrappers around the unix
buildsystem).
The Mac OS X specific configure flags are --enable-aqua, --enable-framework and
--disable-corefoundation (which disables CF and notably reverts to the standard
select based notifier). Note that --enable-aqua is incompatible with
--disable-corefoundation (for both Tcl and Tk configure).

- It is also possible to build with the Xcode IDE via the projects in
tk/macosx, take care to use the project matching your DevTools and OS version:
	Tk.xcode: 		    for Xcode 3.1 on 10.5
	Tk.xcodeproj:		    for Xcode 3.2 on 10.6
These have the following targets:
	Tk:			    calls through to tk/macosx/GNUMakefile,
				    requires a corresponding build of the Tcl
				    target of tcl/macosx/Tcl.xcode.
	tktest:			    static build of TkAqua tktest for debugging.
	tktest-X11:		    static build of TkX11 tktest for debugging.
The following build configurations are available:
	Debug:			    debug build for the active architecture,
				    with Fix & Continue enabled.
	Debug gcc42:		    use gcc 4.2 compiler.
	Debug gcc42 nogc:	    disable Objective-C garbage collection.
	Debug llvmgcc42:	    use llvm-gcc 4.2 compiler.
	DebugNoFixAndContinue:      disable Fix & Continue.
	DebugUnthreaded:	    disable threading.
	DebugNoCF:		    disable corefoundation (X11 only).
	DebugNoCFUnthreaded:	    disable corefoundation an threading.
	DebugMemCompile:	    enable memory and bytecode debugging.
	DebugLeaks:		    define PURIFY.
	DebugGCov:		    enable generation of gcov data files.
	Debug64bit:		    configure with --enable-64bit (requires
				    building on a 64bit capable processor).
	Release:		    release build for the active architecture.
	ReleaseUniversal:	    32/64-bit universal build.
	ReleaseUniversal gcc42:     use gcc 4.2 compiler.
	ReleaseUniversal llvmgcc42: use llvm-gcc 4.2 compiler.
	ReleaseUniversal10.5SDK:    build against the 10.5 SDK (with 10.5
				    deployment target).
	Note that the non-SDK configurations have their deployment target set to
	10.5 (Tk.xcode) resp. 10.6 (Tk.xcodeproj).
The Xcode projects refer to the toplevel tcl and tk source directories via the
the TCL_SRCROOT and TK_SRCROOT user build settings, by default these are set to
the project-relative paths '../../tcl' and '../../tk', if your source
directories are named differently, e.g. '../../tcl8.5' and '../../tk8.5', you
need to manually change the TCL_SRCROOT and TK_SRCROOT settings by editing your
${USER}.pbxuser file (located inside the Tk.xcodeproj bundle directory) with a
text editor.

- To build universal binaries outside of the Xcode IDE, set CFLAGS as follows:
	export CFLAGS="-arch i386 -arch x86_64 -arch ppc"
This requires Mac OS X 10.4 and Xcode 2.4 (or Xcode 2.2 if -arch x86_64 is
omitted, but _not_ Xcode 2.1) and will work on any architecture (on PowerPC
Tiger you need to add "-isysroot /Developer/SDKs/MacOSX10.4u.sdk").
Note that configure requires CFLAGS to contain a least one architecture that can
be run on the build machine (i.e. ppc on G3/G4, ppc or ppc64 on G5, ppc or i386
on Core and ppc, i386 or x86_64 on Core2/Xeon).
Universal builds of Tcl TEA extensions are also possible with CFLAGS set as
above, they will be [load]able by universal as well as thin binaries of Tcl.

- To enable weak-linking, set the MACOSX_DEPLOYMENT_TARGET environment variable
to the minimal OS version the binaries should be able to run on, e.g:
	export MACOSX_DEPLOYMENT_TARGET=10.4
This requires at least gcc 3.1; with gcc 4 or later, set/add to CFLAGS instead:
	export CFLAGS="-mmacosx-version-min=10.4"
Support for weak-linking was added with 8.4.14/8.5a5.

Detailed Instructions for building with macosx/GNUmakefile
----------------------------------------------------------

- 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 ]
[      ln -fs /path_to_tcl/build /path_to_tk/build			       ]
[ (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
"tcl${ver}" and "tk${ver}" (where ${ver} is a shell variable containing the
Tcl/Tk version number, e.g. '8.5').
Setup this shell variable as follows:
	ver="8.5"
If you are building from CVS, omit this step (CVS source tree names usually do
not contain a version number).

- Setup environment variables as desired, e.g. for a universal build on 10.5:
	CFLAGS="-arch i386 -arch x86_64 -arch ppc -mmacosx-version-min=10.5"
	export CFLAGS

- Change to the directory containing the Tcl and Tk source trees and build:
	make -C tcl${ver}/macosx
	make -C tk${ver}/macosx

- Install Tcl and Tk onto the root volume (admin password required):
	sudo make -C tcl${ver}/macosx install
	sudo make -C tk${ver}/macosx  install
if you don't have an admin password, you can install into your home directory
instead by passing an INSTALL_ROOT argument to make:
	make -C tcl${ver}/macosx install INSTALL_ROOT="${HOME}/"
	make -C tk${ver}/macosx  install INSTALL_ROOT="${HOME}/"

- The default GNUmakefile 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 switching to the debug libraries at runtime by setting
	export DYLD_IMAGE_SUFFIX=_debug
(c.f. man dyld for more details)

If you only want to build and install the debug or optimized build, use the
'develop' or 'deploy' target variants of the GNUmakefile, respectively.
For example, to build and install only the optimized versions:
	make -C tcl${ver}/macosx deploy
	make -C tk${ver}/macosx deploy
	sudo make -C tcl${ver}/macosx install-deploy
	sudo make -C tk${ver}/macosx  install-deploy

- The GNUmakefile can also build a version of Wish.app 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' variants of
the GNUmakefile targets.
For example, to build a standalone 'Wish.app' in ./emb/Applications/Utilities:
	make -C tcl${ver}/macosx embedded
	make -C tk${ver}/macosx embedded
	sudo make -C tcl${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/emb/
	sudo make -C tk${ver}/macosx  install-embedded INSTALL_ROOT=`pwd`/emb/
Notes:
  * if you've already built standard TclTkAqua, building embedded does not
  require any new compiling or linking, so you can skip the first two makes.
  (making relinking unnecessary was added with 8.4.2)
  * the embedded frameworks include only optimized builds and no documentation.
  * the standalone Wish has the directory Wish.app/Contents/lib in its
  auto_path. Thus you can place tcl extensions in this directory (i.e. embed
  them in the app package) and load them with [package require].

- 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.
If you used non-default install locations for Tcl.framework, specify them as
make overrides to the tk/macosx GNUmakefile, 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 with Tk 8.4.3.

4. About the event loop in Tk for Mac OSX
-----------------------------------------

The main program in a typical OSX application looks like this (see *)

    void NSApplicationMain(int argc, char *argv[]) {
        [NSApplication sharedApplication];
        [NSBundle loadNibNamed:@"myMain" owner:NSApp];
        [NSApp run];
    }

The run method implements the event loop for the application.  There
are three key steps in the run method.  First it calls 
[NSApp finishLaunching], which creates the bouncing application icon
and does other mysterious things. Second it creates an
NSAutoreleasePool.  Third, it starts an event loop which drains the
NSAutoreleasePool every time the queue is empty, and replaces the
drained pool with a new one.  This third step is essential to
preventing memory leaks, since the internal methods of Appkit objects
all assume that an autorelease pool is in scope and will be drained
when the event processing cycle ends.

Mac OSX Tk does not call the [NSApp run] method at all.  Instead it
uses the event loop built in to Tk.  So we must take care to replicate
the important features of the method ourselves.  Here is how this
works in outline.

We add a private NSAUtoreleasePool* property to our subclass of
NSApplication.  (The subclass is called TKApplication but can be
referenced with the global variable NSApp).  The TkpInit
function calls [NSApp _setup] which initializes this property by
creating an NSAutoreleasePool. A bit later on, TkpInit calls
[NSAPP _setupEventLoop] which in turn calls the
[NSApp finishLaunching] method.

Each time that Tcl processes an event in its queue, it calls a
platform specific function which, in the case of Mac OSX, is named
TkMacOSXEventsCheckProc.  In the unix implementations of Tk, including
the Mac OSX version, this function collects events from an "event
source", and transfers them to the Tcl event queue.  In Mac OSX the
event source is the NSApplication event queue.  Each NSEvent is
converted to a Tcl event which is added to the Tcl event queue.  The
NSEvent is also passed to [NSApp sendevent], which sends the event on
to the application's NSWindows, which send it to their NSViews, etc.
Since the CheckProc function gets called for every Tk event, it is an
appropriate place to drain the main NSAutoreleasePool and replace it
with a new pool.  This is done by calling the method
[NSApp _resetAutoreleasePool], where _resetAutoreleasePool is a method
which we define for the subclass TKApplication.

One minor caveat is that there are several steps of the Tk
initialization which precede the call to TkpInit.  Notably, the font
package is initialized first.  Since there is no NSAUtoreleasePool in
scope prior to calling TkpInit, the functions called in these
preliminary stages need to create and drain their own
NSAutoreleasePools whenever they call methods of Appkit objects
(e.g. NSFont).

* https://developer.apple.com/library/mac/documentation/Cocoa/\
Reference/ApplicationKit/Classes/NSApplication_Class