Tcl Mac OS X README 
-----------------

RCS: @(#) $Id: README,v 1.1.2.4 2005/11/27 02:34:41 das Exp $

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


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 on Mac OS X
------------------------

- At a minimum, Mac OS X 10.1 is required to run Tcl, but OS X 10.3 or higher is
recommended (certain [file] operations behave incorrectly on earlier releases).

- Tcl built on Mac OS X 10.x will not run on 10.y for y < x, on the other hand
Tcl 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).

- 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 macosx/Makefile installs the html manpages into the
standard documentation location in the Tcl framework:
	Tcl.framework/Resources/Documentation/Reference/Tcl
No nroff manpages are installed by default by the Makefile.

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


3. Building Tcl on Mac OS X
---------------------------

- At least Mac OS X 10.1 is required to build Tcl, and 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 is most easily built as a Mac OS X framework via Makefile in tcl/macosx
(see below for details), but can also be built with the standard unix configure
and make buildsystem in tcl/unix as on any other unix platform (indeed, the
Makefile is just a wrapper around the unix buildsystem).
The Mac OS X specifc configure flags are --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).

- It is also possible to build with Apple's IDE via the tcl/macosx/Tcl.pbproj
project, this simply calls through to the tcl/macosx/GNUMakefile.

- To build universal binaires, set CFLAGS as follows:
    export CFLAGS="-arch ppc -arch ppc64 -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
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.

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

- Unpack the tcl source release archive.

- The following instructions assume the tcl source tree is named "tcl${ver}",
where ${ver} is a shell variable containing the tcl 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 tree 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 from the Terminal, assuming you are located
in the directory containing the tcl source tree:
	make -C tcl${ver}/macosx
and the following will then install Tcl onto the root volume (admin password
required):
	sudo make -C tcl${ver}/macosx 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}/"

- The default Makefile targets will build _both_ debug and optimized versions of
the Tcl framework with the standard convention of naming the debug library
Tcl.framework/Tcl_debug.
This allows you to dynamically link to the debug libraries at runtime by setting
	setenv 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 Makefiles, respectively.
For example, to build and install only the optimized versions:
	make -C tcl${ver}/macosx deploy
	sudo make -C tcl${ver}/macosx install-deploy
