util/src/TclTk/tcl8.6.12/macosx/README

   1 Tcl Mac OS X README
   2 -------------------
   3
   4 This is the README file for the Mac OS X/Darwin version of Tcl.
   5
   6
   7 1. Where to go for support
   8 --------------------------
   9
  10 - The tcl-mac mailing list on sourceforge is the best place to ask questions
  11 specific to Tcl & Tk on Mac OS X:
  12         http://lists.sourceforge.net/lists/listinfo/tcl-mac
  13 (this page also has a link to searchable archives of the list, please check them
  14 before asking on the list, many questions have already been answered).
  15
  16 - For general Tcl/Tk questions, the newsgroup comp.lang.tcl is your best bet:
  17         http://groups.google.com/group/comp.lang.tcl/
  18
  19 - The Tcl'ers Wiki also has many pages dealing with Tcl & Tk on Mac OS X, see
  20         http://wiki.tcl.tk/_/ref?N=3753
  21         http://wiki.tcl.tk/_/ref?N=8361
  22
  23 - Please report bugs with Tcl on Mac OS X to the tracker:
  24         https://core.tcl-lang.org/tcl/reportlist
  25
  26 2. Using Tcl on Mac OS X
  27 ------------------------
  28
  29 - At a minimum, Mac OS X 10.3 is required to run Tcl.
  30
  31 - Unless weak-linking is used, Tcl built on Mac OS X 10.x will not run on 10.y
  32 with y < x; on the other hand Tcl built on 10.y will always run on 10.x with
  33 y <= x (but without any of the fixes and optimizations that would be available
  34 in a binary built on 10.x).
  35 Weak-linking is available on OS X 10.2 or later, it additionally allows Tcl
  36 built on 10.x to run on any 10.y with x > y >= z (for a chosen z >= 2).
  37
  38 - Tcl extensions can be installed in any of:
  39         $HOME/Library/Tcl /Library/Tcl
  40         $HOME/Library/Frameworks /Library/Frameworks
  41         (searched in that order).
  42 Given a potential package directory $pkg, Tcl on OSX checks for the file
  43 $pkg/Resources/Scripts/pkgIndex.tcl as well as the usual $pkg/pkgIndex.tcl.
  44 This allows building extensions as frameworks with all script files contained in
  45 the Resources/Scripts directory of the framework.
  46
  47 - [load]able binary extensions can linked as either ordinary shared libraries
  48 (.dylib) or as MachO bundles (since 8.4.10/8.5a3); bundles have the advantage
  49 that they are [load]ed more efficiently from a tcl VFS (no temporary copy to the
  50 native filesystem required), and prior to Mac OS X 10.5, only bundles can be
  51 [unload]ed.
  52
  53 - The 'deploy' target of macosx/GNUmakefile installs the html manpages into the
  54 standard documentation location in the Tcl framework:
  55         Tcl.framework/Resources/Documentation/Reference/Tcl
  56 No nroff manpages are installed by default by the GNUmakefile.
  57
  58 - The Tcl framework can be installed in any of the system's standard
  59 framework directories:
  60         $HOME/Library/Frameworks /Library/Frameworks
  61
  62
  63 3. Building Tcl on Mac OS X
  64 ---------------------------
  65
  66 - At least Mac OS X 10.3 is required to build Tcl.
  67 Apple's Xcode Developer Tools need to be installed (only the most recent version
  68 matching your OS release is supported), the Xcode installer is available on Mac
  69 OS X install media or may be present in /Applications/Installers on Macs that
  70 came with OS X preinstalled. The most recent version can always be downloaded
  71 from the ADC website http://connect.apple.com (free ADC membership required).
  72
  73 - Tcl is most easily built as a Mac OS X framework via GNUmakefile in tcl/macosx
  74 (see below for details), but can also be built with the standard unix configure
  75 and make buildsystem in tcl/unix as on any other unix platform (indeed, the
  76 GNUmakefile is just a wrapper around the unix buildsystem).
  77 The Mac OS X specific configure flags are --enable-framework and
  78 --disable-corefoundation (which disables CF and notably reverts to the standard
  79 select based notifier).
  80
  81 - It is also possible to build with the Xcode IDE via the projects in
  82 tcl/macosx, take care to use the project matching your DevTools and OS version:
  83         Tcl.xcode:                  for Xcode 3.1 on 10.5
  84         Tcl.xcodeproj:              for Xcode 3.2 on 10.6
  85 These have the following targets:
  86         Tcl:                        calls through to tcl/macosx/GNUMakefile.
  87         tcltest:                    static build of tcltest for debugging.
  88         tests:                      build tcltest target and run tcl testsuite.
  89 The following build configurations are available:
  90         Debug:                      debug build for the active architecture,
  91                                     with Fix & Continue enabled.
  92         Debug clang:                use clang compiler.
  93         Debug llvm-gcc:             use llvm-gcc compiler.
  94         Debug gcc40:                use gcc 4.0 compiler.
  95         DebugNoFixAndContinue:      disable Fix & Continue.
  96         DebugUnthreaded:            disable threading.
  97         DebugNoCF:                  disable corefoundation.
  98         DebugNoCFUnthreaded:        disable corefoundation an threading.
  99         DebugMemCompile:            enable memory and bytecode debugging.
 100         DebugLeaks:                 define PURIFY.
 101         DebugGCov:                  enable generation of gcov data files.
 102         Debug64bit:                 configure with --enable-64bit (requires
 103                                     building on a 64bit capable processor).
 104         Release:                    release build for the active architecture.
 105         ReleaseUniversal:           32/64-bit universal build.
 106         ReleaseUniversal clang:     use clang compiler.
 107         ReleaseUniversal llvm-gcc:  use llvm-gcc compiler.
 108         ReleaseUniversal gcc40:     use gcc 4.0 compiler.
 109         ReleaseUniversal10.5SDK:    build against the 10.5 SDK (with 10.5
 110                                     deployment target).
 111         Note that the non-SDK configurations have their deployment target set to
 112         10.5 (Tcl.xcode) resp. 10.6 (Tcl.xcodeproj).
 113 The Xcode projects refer to the toplevel tcl source directory via the
 114 TCL_SRCROOT user build setting, by default this is set to the project-relative
 115 path '../../tcl', if your tcl source directory is named differently, e.g.
 116 '../../tcl8.6', you need to manually change the TCL_SRCROOT setting by editing
 117 your ${USER}.pbxuser file (located inside the Tcl.xcodeproj bundle directory)
 118 with a text editor.
 119
 120 - To build universal binaries outside of the Xcode IDE, set CFLAGS as follows:
 121         export CFLAGS="-arch i386 -arch x86_64 -arch ppc"
 122 This requires Mac OS X 10.4 and Xcode 2.4 (or Xcode 2.2 if -arch x86_64 is
 123 omitted, but _not_ Xcode 2.1) and will work on any architecture (on PowerPC
 124 Tiger you need to add "-isysroot /Developer/SDKs/MacOSX10.4u.sdk").
 125 Note that configure requires CFLAGS to contain a least one architecture that can
 126 be run on the build machine (i.e. ppc on G3/G4, ppc or ppc64 on G5, ppc or i386
 127 on Core and ppc, i386 or x86_64 on Core2/Xeon).
 128 Universal builds of Tcl TEA extensions are also possible with CFLAGS set as
 129 above, they will be [load]able by universal as well as thin binaries of Tcl.
 130
 131 Detailed Instructions for building with macosx/GNUmakefile
 132 ----------------------------------------------------------
 133
 134 - Unpack the Tcl source release archive.
 135
 136 - The following instructions assume the Tcl source tree is named "tcl${ver}",
 137 (where ${ver} is a shell variable containing the Tcl version number e.g. '8.6').
 138 Setup this shell variable as follows:
 139         ver="8.6"
 140 If you are building from CVS, omit this step (CVS source tree names usually do
 141 not contain a version number).
 142
 143 - Setup environment variables as desired, e.g. for a universal build on 10.5:
 144         CFLAGS="-arch i386 -arch x86_64 -arch ppc -mmacosx-version-min=10.5"
 145         export CFLAGS
 146
 147 - Change to the directory containing the Tcl source tree and build:
 148         make -C tcl${ver}/macosx
 149
 150 - Install Tcl onto the root volume (admin password required):
 151         sudo make -C tcl${ver}/macosx install
 152 if you don't have an admin password, you can install into your home directory
 153 instead by passing an INSTALL_ROOT argument to make:
 154         make -C tcl${ver}/macosx install INSTALL_ROOT="${HOME}/"
 155
 156 - The default GNUmakefile targets will build _both_ debug and optimized versions
 157 of the Tcl framework with the standard convention of naming the debug library
 158 Tcl.framework/Tcl_debug.
 159 This allows switching to the debug libraries at runtime by setting
 160         export DYLD_IMAGE_SUFFIX=_debug
 161 (c.f. man dyld for more details)
 162
 163 If you only want to build and install the debug or optimized build, use the
 164 'develop' or 'deploy' target variants of the GNUmakefile, respectively.
 165 For example, to build and install only the optimized versions:
 166         make -C tcl${ver}/macosx deploy
 167         sudo make -C tcl${ver}/macosx install-deploy
 168
 169 - To build a Tcl.framework for use as a subframework in another framework, use the
 170 install-embedded target and set SUBFRAMEWORK=1.  Set the DYLIB_INSTALL_DIR
 171 variable to the path which should be the install_name path of the Tcl library, set
 172 the DESTDIR variable to the pathname of a staging directory where the framework
 173 will be written .  For example, running this command in the Tcl source directory:
 174         make -C macosx install-embedded SUBFRAMEWORK=1 DESTDIR=/tmp/tcl \
 175         DYLIB_INSTALL_DIR=/Library/Frameworks/Some.framework/Versions/X.Y/Frameworks/Tcl.framework
 176 will produce a Tcl.framework intended for installing as a subframework of
 177 Some.framework.  The framework will be found in /tmp/tcl/Frameworks/