calog/vendor/tcl/macosx/README

Tcl macOS README
-------------------

This is the README file for the macOS/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/_/ref?N=3753
	http://wiki.tcl.tk/_/ref?N=8361

- Please report bugs with Tcl on Mac OS X to the tracker:
	https://core.tcl-lang.org/tcl/reportlist

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

- At a minimum, Mac OS X 10.3 is required to run Tcl.

- Unless weak-linking is used, Tcl built on Mac OS X 10.x will not run on 10.y
with y < x; on the other hand Tcl 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
built on 10.x to run on any 10.y with x > y >= z (for a chosen z >= 2).

- Tcl extensions can be installed in any of:
	$HOME/Library/Tcl /Library/Tcl
	$HOME/Library/Frameworks /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 framework:
	Tcl.framework/Resources/Documentation/Reference/Tcl
No nroff manpages are installed by default by the GNUmakefile.

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


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

- Tcl supports macOS 10.13 and newer.
While Tcl may build on earlier versions of the OS, it is not tested on versions
older than 10.13.  You will need to install an  Apple clang toolchain either by
downloading the Xcode app from Apple's App Store, or by installing the Command
Line Tools. The Command Line Tools can be installed by running the command:
    xcode-select --install
in the Terminal.

- Tcl is most easily built as a macOS framework via the GNUmakefile 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
GNUmakefile is just a wrapper around the unix buildsystem).
The Mac OS X specific configure flags are --enable-framework and
--disable-corefoundation (which disables CF and notably reverts to the standard
select based notifier).

- To build universal binaries for macOS 10.13 and newer set CFLAGS as follows:
	export CFLAGS="-arch x86_64 -arch arm64 -mmacosx-version-min=10.13"
(This will cause clang to set macOS 11 as the target OS for the arm64 architecture
since Apple Silicon was not supported until macOS 11.)
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/GNUmakefile
----------------------------------------------------------

- 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 e.g. '9.0').
Setup this shell variable as follows:
	ver="9.0"

- Setup environment variables as desired, for example:
	CFLAGS="-arch x86_64 -arch arm64 -mmacosx-version-min=10.13"
	export CFLAGS

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

- Install Tcl onto the root volume (admin password required):
	sudo make -C tcl${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}/"

- The default GNUmakefile 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 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
	sudo make -C tcl${ver}/macosx install-deploy

- To build a Tcl.framework for use as a subframework in another framework, use the
install-embedded target and set SUBFRAMEWORK=1.  Set the DYLIB_INSTALL_DIR
variable to the path which should be the install_name path of the Tcl library, set
the DESTDIR variable to the pathname of a staging directory where the framework
will be written .  For example, running this command in the Tcl source directory:
	make -C macosx install-embedded SUBFRAMEWORK=1 DESTDIR=/tmp/tcl \
	DYLIB_INSTALL_DIR=/Library/Frameworks/Some.framework/Versions/X.Y/Frameworks/Tcl.framework
will produce a Tcl.framework intended for installing as a subframework of
Some.framework.  The framework will be found in /tmp/tcl/Frameworks/