* macosx/README: info specific to building and running

	TclTk on Mac OS X, answers to tcl-mac list FAQs.
	* macosx/Makefile: permission fix after embedded install.
	* macosx/Wish.pbproj/project.pbxproj: after install, fix
	permissions of uninstalled products.


FossilOrigin-Name: 58b7e09c17c84d99c04cc5b487cca6b4aaf343b9

1 files changed, 172 insertions, 0 deletions

diff --git a/macosx/README b/macosx/README
new file mode 100644
index 0000000..a5446d9
--- /dev/null
+++ b/macosx/README
@@ -0,0 +1,172 @@
+TclTkAqua README 
+----------------
+
+RCS: @(#) $Id: README,v 1.1 2002/10/16 23:56:02 das Exp $
+
+This is the README file for the Mac OS X native versions of Tcl & Tk.
+
+
+1. General
+----------
+
+- The tcl-mac mailing list on sourceforge is the canonical place for 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/
+
+- The wiki has a page listing known bugs in Mac OS X 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
+
+- You should report bugs to the sourceforge bug trackers as usual:
+	https://sourceforge.net/tracker/?func=add&group_id=10894&atid=110894
+	https://sourceforge.net/tracker/?func=add&group_id=12997&atid=112997
+
+
+2. Using TclTkAqua
+------------------
+
+- Mac OS X 10.1 (or higher) is required to run TclTkAqua.
+
+- Tcl built on Mac OS X 10.2 or higher will not run on 10.1 due to missing
+symbols in libSystem, however Tcl built on 10.1 will run on 10.2 (but without
+prebinding and other optimizations).
+
+- 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\ Shell.app').
+
+- Wish accepts drag & drop of text files (i.e. OS type TEXT and other files that
+the system recognizes as being of NSStringPboardType). To claim other OS types
+or file extensions in your Wish clone, you need to edit
+	Wish Shell.app/Contents/Info.plist
+for more info on how this works, c.f. the System Overview document:
+	file:///Developer/Documentation/Essentials/SystemOverview/index.html
+
+- Tcl extensions will be found in any of:
+	$HOME/Library/Tcl /Library/Tcl 
+	Network/Library/Tcl /System/Library/Tcl
+(searched in that order).
+
+- Tcl.framework contains the Tcl and Tk documentation in html format in the
+standard location for frameworks:
+	Tcl.framework/Resources/English.lproj/Documentation/Reference/Tcl
+(OTOH no manpages are installed by default).
+Tk.framework contains no documentation.
+
+- the frameworks Tcl.framework and Tk.framework can be placed in any of the
+system's standard framework directories:
+	$HOME/Library/Frameworks /Library/Frameworks
+	/Network/Library/Frameworks /System/Library/Frameworks
+and 'Wish Shell' as well as /usr/bin/tclsh will work.
+
+- /usr/bin/wish is a script that calls 'Wish Shell' in its default location
+	/Applications/Utilities/Wish Shell.app
+it will break if 'Wish Shell' is moved.
+
+- if 'Wish Shell' 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.
+Also note that the env array is different when Wish is started from
+the Finder, in particular PATH may not be what you expect.
+(Wish inherits the Finder's environment variables, which are essentially
+those set in $HOME/.MacOSX/environment.plist).
+
+- 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.
+
+
+3. Building TclTkAqua
+---------------------
+
+- Apple's Developer Tools CD needs to be installed (the version matching your OS
+release). This CD should have come with Mac OS X retail or should be present as
+a disk image on new macs that had OSX preinstalled. It can also be downloaded
+from http://connect.apple.com (free ADC membership required).
+
+- Mac OS X 10.1.5 with the April 2002 Developer Tools update (or higher) is
+required to build TclTkAqua.
+
+- Tcl and TkAqua are built as Mac OS X frameworks using Apple's ProjectBuilder
+IDE, but you do not have to deal with the IDE if you don't want to: there are
+Makefiles available in tcl/macosx and tk/macosx that take care of calling the
+ProjectBuilder command line tool with all the details taken care of. 
+
+- If you're only interested in _building_ TclTkAqua and don't plan on doing
+development with the ProjectBuilder projects, using the Makefiles is easiest.
+The following steps will build Tcl and Tk from the Terminal (assuming you are
+located in the directory above the tcl and tk source trees):
+	make -C tcl/macosx
+	make -C tk/macosx
+and the following will then install Tcl and Tk onto the root volume (admin
+privileges required):
+	sudo make -C tcl/macosx install
+	sudo make -C tk/macosx  install
+you can also pass an INSTALL_ROOT argument to 'make install', e.g.
+	make -C tcl/macosx install INSTALL_ROOT=$HOME
+	make -C tk/macosx  install INSTALL_ROOT=$HOME
+will install into you home directory (useful if you're not an admin on your
+machine)
+
+- The default Makefile 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 to dynamically link to the debug library at runtime by setting
+	setenv DYLD_IMAGE_SUFFIX _debug
+(c.f. man dyld for more details)
+
+If you only want to build/install the debug resp. optimized build, use the
+'develop' resp. 'deploy' target variants of the Makefiles, e.g.
+	make -C tcl/macosx deploy
+	make -C tk/macosx deploy
+	sudo make -C tcl/macosx install-deploy
+	sudo make -C tk/macosx  install-deploy
+will build and install only the optimized versions.
+
+- The Makefiles can also build a version of 'Wish Shell' 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 Makefiles, i.e.
+	make -C tcl/macosx embedded
+	make -C tk/macosx embedded
+	make -C tcl/macosx install-embedded INSTALL_ROOT=`pwd`/embedded
+	make -C tk/macosx  install-embedded INSTALL_ROOT=`pwd`/embedded
+will build a standalone 'Wish Shell.app' in ./embedded/Applications/Utilities
+(this only requires a relink if you've already built standard TclTkAqua).
+
+Note that the embedded frameworks include only optimized builds and no
+documentation.
+The standalone Wish has the directory Wish\ Shell.app/Contents/lib in its
+auto_path, this can be used to embed tcl extensions into the app package and
+have them automatically available via [package require].
+
+- To build from the IDE using the projects directly without going through the
+Makefiles you need so setup a common build folder for the projects. A simple way
+to achieve this is to make symbolic links
+	ln -fs ../../build tcl/macosx/build
+	ln -fs ../../build tk/macosx/build
+(this location of the build folder is compatible with the Makefiles).
+
+Another way is to set the build folder location directly in
+tcl/macosx/Tcl.pbproj and tk/macosx/Wish/pbproj using ProjectBuilder's
+"Project->Show Info" on the topmost icon in the filelist. Switch to "Place build
+products in a separate location" with a setting of "$SRCROOT/../../build"
+(this gets stored in Tcl.pbproj/$USER.pbxuser & Wish.pbproj/$USER.pbxuser).
+