path: root/carbon/README

Tcl/TkAqua Carbon Mac OS X README
---------------------------------

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
! This is the README for tk/carbon, the legacy version of TkAqua based on the  !
! Carbon API. This version of TkAqua is deprecated and no longer actively      !
! supported, it will be removed in a future release of Tk. It is only useful   !
! for users requiring support of Mac OS X releases older than 10.5.            !
! The supported version of TkAqua is located in tk/macosx and is based on the  !
! Cocoa API. It requires Mac OS X 10.5 or later.                               !
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

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/references/3753!
	http://wiki.tcl.tk/references/8361!

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

- 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).

- 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 /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.

- [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 'deploy' target of carbon/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 GNUmakefiles.

- 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

- /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 (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).

- 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. The old QD code is retained for now, just in case there are any
compatibility problems. To switch back to the QD drawing, put
    set tk::mac::useCGDrawing 0
in your script before you do drawing.
All CG 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.

- ATSUI 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.

- 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:
    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.2, 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 GNUmakefile in
tcl/macosx and tk/carbon (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 Apple's IDE via the projects in tk/carbon,
take care to only use the project matching your DevTools and OS version:
    * Wish.xcode for Xcode 2.4 on 10.4 and Xcode 2.5 on 10.4 and later, this has
	a 'Tk' target that simply calls through to the tcl/macosx/GNUMakefile.
	It requires a build of the 'Tcl' target of tcl/macosx/Tcl.xcode.
	Additionally this has native 'tktest' and 'tktest-X11' targets for
	debugging, these targets' 'Debug' build configuration has ZeroLink and
	Fix&Continue enabled, use the 'DebugNoFixZL' build configuration if you
	need a debug build without these features. The following build
	configurations are available:
	'DebugUnthreaded': debug build with threading turned off.
	'DebugNoCF': debug build with corefoundation turned off
		(for 'tktest-X11' only).
	'DebugNoCFUnthreaded': debug build with corefoundation turned off
		(for 'tktest-X11' only) and with threading turned off.
	'DebugMemCompile': debug build with memory and bytecode debugging on.
	'DebugLeaks': debug build with PURIFY defined.
	'DebugGCov': debug build with generation of gcov data files enabled.
	'ReleaseUniversal': builds the targets as universal binaries for the
		ppc and i386 architectures.
	'ReleaseUniversal10.4uSDK': same as 'ReleaseUniversal' but builds
		against the 10.4u SDK, required to build universal binaries on
		PowerPC Tiger (where the system libraries are not universal).
	'ReleasePPC10.3.9SDK': builds for PowerPC against the 10.3.9 SDK, useful
		for verifying on Tiger that building on Panther would succeed.
	'ReleasePPC10.2.8SDK': builds for PowerPC with gcc-3.3 against the
		10.2.8 SDK, useful to verify on Tiger that building on Jaguar
		would succeed.
    * Wish.xcodeproj for Xcode 3.1 on 10.5 and later, which has the following
	additional build configurations:
	'ReleaseUniversal10.5SDK': same as 'ReleaseUniversal' but builds
		against the 10.5 SDK on Leopard (with 10.5 deployment target).
	'Debug gcc42':  same as 'Debug' but builds with gcc 4.2.
	'Debug llvmgcc42': same as 'Debug' but builds with llvm-gcc 4.2.
	'ReleaseUniversal gcc42': same as 'ReleaseUniversal' but builds with
		gcc 4.2.
	'ReleaseUniversal llvmgcc42': same as 'ReleaseUniversal' but builds
		with llvm-gcc 4.2.
	'Debug64bit': builds the 'tktest-X11' target as 64bit with debugging
		 enabled (requires a 64bit capable processor).
	Note that all non-SDK configurations have 10.5 deployment target and
		that all Universal configurations build the 'tktest-X11' target
		also for the ppc64 and x86_64 architectures.

Notes about the native targets of the Xcode projects:
    * the Xcode projects refer to the toplevel tcl and tk source dirs through
	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', you'll
	need to manually change the TCL_SRCROOT and TK_SRCROOT settings by
	editing your ${USER}.pbxuser file (located inside the Wish.xcodeproj
	bundle directory) with a text editor.
    * 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/carbon/configure by the project but that requires 2.59 versions
	of autoconf & autoheader. These are not available on Mac OS X 10.5 by
	default and 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 AUTOCONF and AUTOHEADER build
	settings in ${USER}.pbxuser to their true locations if necessary.

- To build universal binaries 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 (the -isysroot flag is only required on PowerPC Tiger).
Note that configure requires CFLAGS to contain a least one architecture that can
be run on the build machine (i.e. ppc on PowerPC, ppc or i386 on Intel).
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 64-bit architectures, neither TkAqua nor
TkX11 can be built for 64-bit 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 x86_64' Tcl binary works just fine.
The Tk configure script automatically removes the 64-bit -arch flags from CFLAGS
to facilitate universal building of both Tcl and Tk with the same CFLAGS; the
same happens with configure in Tk extensions based on TEA 3.5 or later.

- To enable weak-linking, set the MACOSX_DEPLOYMENT_TARGET environment variable
to the minimal OS version (>= 10.2) the binaries should be able to run on, e.g:
    export MACOSX_DEPLOYMENT_TARGET=10.2
This requires Mac OS X 10.2 and gcc 3.1; if you have gcc 4 or later you can set
CFLAGS instead:
    export CFLAGS="-mmacosx-version-min=10.2"
The Wish.xcode project is setup to produce binaries that can run on 10.2 or
later (except for the Universal and SDK configurations).
Support for weak-linking was added to the code for 8.4.14/8.5a5.

Detailed Instructions for building with carbon/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}", respectively, where ${ver} is a shell variable
containing the Tcl and Tk version number (for example '8.4.12').
Setup the shell variable as follows:
	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

- 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:
	make -C tcl${ver}/macosx
	make -C tk${ver}/carbon
and the following will then install Tcl and Tk onto the root volume (admin
password required):
	sudo make -C tcl${ver}/macosx install
	sudo make -C tk${ver}/carbon  install
if you don't have the 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}/carbon  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 GNUmakefiles, respectively.
For example, to build and install only the optimized versions:
	make -C tcl${ver}/macosx deploy
	make -C tk${ver}/carbon deploy
	sudo make -C tcl${ver}/macosx install-deploy
	sudo make -C tk${ver}/carbon  install-deploy

- The GNUmakefiles can also build a version of 'Wish' 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' target variants of
the GNUmakefiles. For example, to build a standalone 'Wish.app'
in ./embedded/Applications/Utilities:
	make -C tcl${ver}/macosx embedded
	make -C tk${ver}/carbon embedded
	sudo make -C tcl${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/embedded/
	sudo make -C tk${ver}/carbon  install-embedded INSTALL_ROOT=`pwd`/embedded/
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 in 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/carbon GNUmakefile, e.g.
	make -C tk${ver}/carbon \
	    TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin
	sudo make -C tk${ver}/carbon 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.