diff options
Diffstat (limited to 'tk8.6/macosx/README')
| -rw-r--r-- | tk8.6/macosx/README | 451 |
1 files changed, 0 insertions, 451 deletions
diff --git a/tk8.6/macosx/README b/tk8.6/macosx/README deleted file mode 100644 index b27f9ff..0000000 --- a/tk8.6/macosx/README +++ /dev/null @@ -1,451 +0,0 @@ -Tcl/Tk Mac OS X README ----------------------- - -This is the README file for the Mac OS X/Darwin version of Tcl/Tk. - -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 Tk on Mac OS X to the tracker: - http://core.tcl.tk/tk/reportlist - -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 or default install on recent Mac OS X). -TkAqua and TkX11 can be distinguished at runtime via [tk windowingsystem]. - -- At a minimum, Mac OS X 10.3 is required to run Tcl and TkX11. -TkAqua requires Mac OS X 10.5 or later (starting with the Cocoa-based Tk 8.5.7). - -- 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 /System/Library/Tcl - $HOME/Library/Frameworks /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); 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/Tk frameworks: - Tcl.framework/Resources/Documentation/Reference/Tcl - Tk.framework/Resources/Documentation/Reference/Tk -No nroff manpages are installed by default by the GNUmakefile. - -- The Tcl and Tk frameworks can be installed in any of the system's standard -framework directories: - $HOME/Library/Frameworks /Library/Frameworks /System/Library/Frameworks - -- ${prefix}/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 may contain a -"-psn_XXXX" argument. This is the 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). - -- TkAqua 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. - -- 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. - -- The default metrics of native buttons, radiobuttons, checkboxes and -menubuttons in the Cocoa-based Tk 8.5.7 and later preserve compatibility with -the older Carbon-based implementation, you can turn off the compatibility -metrics to get more native-looking spacing by setting: - set tk::mac::useCompatibilityMetrics 0 - -- TkAqua provides access to native OS X images via the Tk native bitmap facility -(including any image file readable by NSImage). A native bitmap name is -interpreted as follows (in order): - - predefined builtin 32x32 icon name (stop, caution, document, etc) - - name defined by [tk::mac::iconBitmap] - - NSImage named image name - - NSImage url string - - 4-char OSType of IconServices icon -the syntax of [tk::mac::iconBitmap] is as follows: - tk::mac::iconBitmap name width height -kind value -where -kind is one of - -file icon of file at given path - -fileType icon of given file type - -osType icon of given 4-char OSType file type - -systemType icon for given IconServices 4-char OSType - -namedImage named NSImage for given name - -imageFile image at given path -This support was added with the Cocoa-based Tk 8.5.7. - -- TkAqua cursor names are interpred as follows (in order): - - standard or platform-specific Tk cursor name (c.f. cursors.n) - - @path to any image file readable by NSImage - - NSImage named image name -Support for the latter two was added with the Cocoa-based Tk 8.5.7. - -- The standard Tk dialog commands [tk_getOpenFile], [tk_chooseDirectory], -[tk_getSaveFile] and [tk_messageBox] all take an additional optional -command -parameter on TkAqua. If it is present, the given command prefix is evaluated at -the global level when the dialog closes, with the dialog command's result -appended (the dialog command itself returning an emtpy result). If the -parent -option is also present, the dialog is configured as a modeless (window-modal) -sheet attached to the parent window and the dialog command returns immediately. -Support for -command was added with the Cocoa-based Tk 8.5.7. - -- The TkAqua-specific [tk::mac::standardAboutPanel] command brings the standard -Cocoa about panel to the front, with all its information filled in from your -application bundle files (i.e. standard about panel with no options specified). -See Apple Technote TN2179 and the AppKit documentation for -[NSApplication -orderFrontStandardAboutPanelWithOptions:] for details on the Info.plist keys and -app bundle files used by the about panel. -This support was added with the Cocoa-based Tk 8.5.7. - -- TkAqua has three special menu names that give access to the standard -Application, Window and Help menus, see menu.n for details. -By default, the platform-specific standard Help menu item "YourApp Help" peforms -the default Cocoa action of showing the Help Book configured in the -application's Info.plist (or displaying an alert if no Help Book is set). This -action can be customized by defining a procedure named [tk::mac::ShowHelp], if -present, this procedure is invoked instead by the standard Help menu item. -Support for the Window menu and [tk::mac::ShowHelp] was added with the -Cocoa-based Tk 8.5.7. - -- The TkAqua-specific command [tk::unsupported::MacWindowStyle style] is used to -get and set Mac OS X-specific toplevel window class and attributes. Note that -the window class and many attributes have to be set before the window is first -mapped for the change to have any effect. -The command has the following syntax: - tk::unsupported::MacWindowStyle style window ?class? ?attributes? -The 2 argument form returns a list of the current class and attributes for the -given window. The 3 argument form sets the class for the given window using the -default attributes for that class. The 4 argument form sets the class and the -list of attributes for the given window. -Window class names: - document, modal, floating, utility, toolbar, simple, help, overlay -Window attribute names: - standardDocument, standardFloating, resizable, fullZoom, horizontalZoom, - verticalZoom, closeBox, collapseBox, toolbarButton, sideTitlebar, - noTitleBar, unifiedTitleAndToolbar, metal, hud, noShadow, doesNotCycle, - noActivates, hideOnSuspend, inWindowMenu, ignoreClicks, doesNotHide, - canJoinAllSpaces, moveToActiveSpace, nonActivating, black, dark, light, - gray, red, green, blue, cyan, yellow, magenta, orange, purple, - brown, clear, opacity - -Note that not all attributes are valid for all window classes. -Support for the 3 argument form was added with the Cocoa-based Tk 8.5.7, at the -same time support for some legacy Carbon-specific classes and attributes was -removed (they are still accepted by the command but no longer have any effect). - -The color window attributes (black, dark, red, etc.) and the "opacity" allow one to set the background and opacity of a textured ("metal") window. This allows a Tk window to implement a window without the dividing line between the titlebar and the rest of the window, or the "unified toolbar" effect, which is increasingly standard in Mac applications. An example: - -toplevel .f -tk::unsupported::MacWindowStyle style .f document {metal light opaque closeBox collapseBox resizable standardDocument } - -pack [label .f.f -bg #ababab -text "This is a textured window\nwith opacity and a gray background\nsimilar to other Mac applications"] -fill both -expand yes - -The color attributes correspond to system-defined NSColor constants (e.g., red is [NSColor redColor]. The "light" and "dark" attributes correspond to lightGrayColor and darkGrayColor, respectively (because of the way the attributes are parsed, using "lightgray" and "darkgray" would cause a conflict with the core "gray" attribute). - -Below are the corresponding hex and/or Tk-defined colors that can be used from Tk widgets to match the NSColor-based attributes: - -black #000000 -dark #545454 -light #ababab -white #ffffff -gray #7f7f7f -red #ff0000 -green #00ff00 -blue #0000ff -cyan #00ffff -yellow #ffff00 -magenta #ff00ff -orange #ff8000 -purple #800080 -brown #996633 -clear systemTransparent - -- The Cocoa-based TkAqua can be distinguished from the older Carbon-based -version via the [winfo server .] command, example output on Mac OS X 10.5.7: - Cocoa-based: CG409.3 Apple AppKit GC 949.46 Mac OS X 1057 - Carbon-based: QD10R30 Apple 1057 - -- If you want to use Remote Debugging with Xcode, 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.3 is required to build Tcl and TkX11, and Mac OS X 10.5 -is required to build TkAqua. -Apple's Xcode Developer Tools need to be installed (only the most recent version -matching your OS release is supported), the Xcode installer is available on Mac -OS X install media or may be present in /Applications/Installers on Macs that -came with OS X preinstalled. The most recent version can always be downloaded -from the ADC website http://connect.apple.com (free ADC membership required). - -- Tcl/Tk are most easily built as Mac OS X frameworks via GNUmakefile in -tcl/macosx and tk/macosx (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 the Xcode IDE via the projects in -tk/macosx, take care to use the project matching your DevTools and OS version: - Tk.xcode: for Xcode 3.1 on 10.5 - Tk.xcodeproj: for Xcode 3.2 on 10.6 -These have the following targets: - Tk: calls through to tk/macosx/GNUMakefile, - requires a corresponding build of the Tcl - target of tcl/macosx/Tcl.xcode. - tktest: static build of TkAqua tktest for debugging. - tktest-X11: static build of TkX11 tktest for debugging. -The following build configurations are available: - Debug: debug build for the active architecture, - with Fix & Continue enabled. - Debug clang: use clang compiler. - Debug llvm-gcc: use llvm-gcc compiler. - Debug gcc40: use gcc 4.0 compiler. - DebugNoGC: disable Objective-C garbage collection. - DebugNoFixAndContinue: disable Fix & Continue. - DebugUnthreaded: disable threading. - DebugNoCF: disable corefoundation (X11 only). - DebugNoCFUnthreaded: disable corefoundation an threading. - DebugMemCompile: enable memory and bytecode debugging. - DebugLeaks: define PURIFY. - DebugGCov: enable generation of gcov data files. - Debug64bit: configure with --enable-64bit (requires - building on a 64bit capable processor). - Release: release build for the active architecture. - ReleaseUniversal: 32/64-bit universal build. - ReleaseUniversal clang: use clang compiler. - ReleaseUniversal llvm-gcc: use llvm-gcc compiler. - ReleaseUniversal gcc40: use gcc 4.0 compiler. - ReleaseUniversal10.5SDK: build against the 10.5 SDK (with 10.5 - deployment target). - Note that the non-SDK configurations have their deployment target set to - 10.5 (Tk.xcode) resp. 10.6 (Tk.xcodeproj). -The Xcode projects refer to the toplevel tcl and tk source directories via the -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.6' and '../../tk8.6', you -need to manually change the TCL_SRCROOT and TK_SRCROOT settings by editing your -${USER}.pbxuser file (located inside the Tk.xcodeproj bundle directory) with a -text editor. - -- To build universal binaries outside of the Xcode IDE, set CFLAGS as follows: - export CFLAGS="-arch i386 -arch x86_64 -arch ppc" -This requires Mac OS X 10.4 and Xcode 2.4 (or Xcode 2.2 if -arch x86_64 is -omitted, but _not_ Xcode 2.1) and will work on any architecture (on PowerPC -Tiger you need to add "-isysroot /Developer/SDKs/MacOSX10.4u.sdk"). -Note that configure requires CFLAGS to contain a least one architecture that can -be run on the build machine (i.e. ppc on G3/G4, ppc or ppc64 on G5, ppc or i386 -on Core and ppc, i386 or x86_64 on Core2/Xeon). -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. - -- To enable weak-linking, set the MACOSX_DEPLOYMENT_TARGET environment variable -to the minimal OS version the binaries should be able to run on, e.g: - export MACOSX_DEPLOYMENT_TARGET=10.4 -This requires at least gcc 3.1; with gcc 4 or later, set/add to CFLAGS instead: - export CFLAGS="-mmacosx-version-min=10.4" -Support for weak-linking was added with 8.4.14/8.5a5. - -Detailed Instructions for building with macosx/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}" (where ${ver} is a shell variable containing the -Tcl/Tk version number, e.g. '8.6'). -Setup this shell variable as follows: - ver="8.6" -If you are building from CVS, omit this step (CVS source tree names usually do -not contain a version number). - -- Setup environment variables as desired, e.g. for a universal build on 10.5: - CFLAGS="-arch i386 -arch x86_64 -arch ppc -mmacosx-version-min=10.5" - export CFLAGS - -- Change to the directory containing the Tcl and Tk source trees and build: - make -C tcl${ver}/macosx - make -C tk${ver}/macosx - -- Install Tcl and Tk onto the root volume (admin password required): - sudo make -C tcl${ver}/macosx install - sudo make -C tk${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}/" - make -C tk${ver}/macosx 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 GNUmakefile, respectively. -For example, to build and install only the optimized versions: - make -C tcl${ver}/macosx deploy - make -C tk${ver}/macosx deploy - sudo make -C tcl${ver}/macosx install-deploy - sudo make -C tk${ver}/macosx install-deploy - -- The GNUmakefile can also build a version of Wish.app 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' variants of -the GNUmakefile targets. -For example, to build a standalone 'Wish.app' in ./emb/Applications/Utilities: - make -C tcl${ver}/macosx embedded - make -C tk${ver}/macosx embedded - sudo make -C tcl${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/emb/ - sudo make -C tk${ver}/macosx install-embedded INSTALL_ROOT=`pwd`/emb/ -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 with 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/macosx GNUmakefile, e.g. - make -C tk${ver}/macosx \ - TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin - sudo make -C tk${ver}/macosx install \ - TCL_FRAMEWORK_DIR=$HOME/Library/Frameworks TCLSH_DIR=$HOME/usr/bin -The Makefile variables TCL_FRAMEWORK_DIR and TCLSH_DIR were added with Tk 8.4.3. - -4. About the event loop in Tk for Mac OSX ------------------------------------------ - -The main program in a typical OSX application looks like this (see *) - - void NSApplicationMain(int argc, char *argv[]) { - [NSApplication sharedApplication]; - [NSBundle loadNibNamed:@"myMain" owner:NSApp]; - [NSApp run]; - } - -The run method implements the event loop for the application. There -are three key steps in the run method. First it calls -[NSApp finishLaunching], which creates the bouncing application icon -and does other mysterious things. Second it creates an -NSAutoreleasePool. Third, it starts an event loop which drains the -NSAutoreleasePool every time the queue is empty, and replaces the -drained pool with a new one. This third step is essential to -preventing memory leaks, since the internal methods of Appkit objects -all assume that an autorelease pool is in scope and will be drained -when the event processing cycle ends. - -Mac OSX Tk does not call the [NSApp run] method at all. Instead it -uses the event loop built in to Tk. So we must take care to replicate -the important features of the method ourselves. Here is how this -works in outline. - -We add a private NSAUtoreleasePool* property to our subclass of -NSApplication. (The subclass is called TKApplication but can be -referenced with the global variable NSApp). The TkpInit -function calls [NSApp _setup] which initializes this property by -creating an NSAutoreleasePool. A bit later on, TkpInit calls -[NSAPP _setupEventLoop] which in turn calls the -[NSApp finishLaunching] method. - -Each time that Tcl processes an event in its queue, it calls a -platform specific function which, in the case of Mac OSX, is named -TkMacOSXEventsCheckProc. In the unix implementations of Tk, including -the Mac OSX version, this function collects events from an "event -source", and transfers them to the Tcl event queue. In Mac OSX the -event source is the NSApplication event queue. Each NSEvent is -converted to a Tcl event which is added to the Tcl event queue. The -NSEvent is also passed to [NSApp sendevent], which sends the event on -to the application's NSWindows, which send it to their NSViews, etc. -Since the CheckProc function gets called for every Tk event, it is an -appropriate place to drain the main NSAutoreleasePool and replace it -with a new pool. This is done by calling the method -[NSApp _resetAutoreleasePool], where _resetAutoreleasePool is a method -which we define for the subclass TKApplication. - -One minor caveat is that there are several steps of the Tk -initialization which precede the call to TkpInit. Notably, the font -package is initialized first. Since there is no NSAUtoreleasePool in -scope prior to calling TkpInit, the functions called in these -preliminary stages need to create and drain their own -NSAutoreleasePools whenever they call methods of Appkit objects -(e.g. NSFont). - -* https://developer.apple.com/library/mac/documentation/Cocoa/\ -Reference/ApplicationKit/Classes/NSApplication_Class |