* carbon/ (new directory): copy of current state of 'macosx'

	source directory, to preserve legacy TkAqua implementation based on
	Carbon API (with support for Mac OS X releases older than 10.5).

1 files changed, 341 insertions, 0 deletions

diff --git a/carbon/README b/carbon/README
new file mode 100644
index 0000000..3e12858
--- /dev/null
+++ b/carbon/README
@@ -0,0 +1,341 @@
+Tcl/TkAqua Carbon Mac OS X README
+---------------------------------
+
+RCS: @(#) $Id: README,v 1.1 2009/06/26 01:42:46 das Exp $
+
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+! 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.