Starpacker 1.0 Documentation What is Starpacker? =================== Starpacker is a utility that helps create Starpacks. Starpacks are executables that consist of a Tclkit (a Tcl/Tk interpreter) joined to a Starkit (a self- contained suite of Tcl files and other resources that comprise an application). There are many different versions of Tclkit corresponding to different platforms and Tcl/Tk releases. Starpacker automatically retrieves requested Tclkits and combines them with Starkits you provide to create stand-alone Starpacks. SDX is a command line tool that provides many useful functions for Starkit users and developers. Starpacker incorporates some SDX functionality, but it is intended as a complementary tool rather than a comprehensive replacement. - Starkits: - Tclkits: - SDX: Initial Setup ============= The first time you run Starpacker, a setup window will appear. The setup window reports where Starpacker's preferences will be saved and the default location of the cache, which is a folder Starpacker uses to store Tclkits it has downloaded and temporary files used during the creation of Starpacks. If you prefer to use a different directory as the cache, check the "Choose cache location..." button. You will be prompted to select a folder once you click "Start". The cache directory can also be changed later. If you wish to update Starpacker's list of Tclkits available from Equi 4 Software, check the "Check for new Tclkits" button. The current choices will be retrieved from after you click "Start". You can also check for new Tclkits later. Clicking "Start" carries out the selected options, writes initial preferences, and displays the regular user interface. As long as the preferences file is found, the setup window will not appear during subsequent use. Preference Paths ---------------- Starpacker looks for its preferences in different places on different platforms. Note that bugs and Tclkit discrepancies may prevent Starpacker from functioning properly on some of these platforms. - Mac OS X: ~/Library/Preferences/starpackerrc - Mac OS Classic: :System Folder:Preferences:starpackerrc - Linux/Unix: ~/.starpackerrc - Windows: as "starpackerrc" in directory specified by "AppData" registry key or environment variable Cache Paths ----------- The default location for the cache folder is also platform-dependent. - Mac OS X: ~/Library/Caches/Starpacker - Mac OS Classic: :System Folder:Preferences:starpacker (next to preferences) - Linux/Unix: ~/.starpacker - Windows: as "starpacker" directory next to preferences Unlike the preferences path, the cache path may be modified. User Interface ============== The Starpacker window has two sections corresponding to the two parts that comprise a Starpack. In the "Starkit" section, you can enter the path to an existing Starkit or click "Browse..." to choose a Starkit using a file browser. The "Tclkit" section contains a menu of Tcl/Tk releases for which Tclkits are known to be available. The "Runtime" menu lists the platform-specific Tclkits known to be available for the selected "Release". These are the choices updated by the "Check for new Tclkits" option. If you check "Other", the "Release" and "Runtime" menus are disabled and controls for selecting an arbitrary Tclkit are enabled. You can enter the path directly or click "Browse..." to choose a Tclkit with a file browser. This option is recommended for Tclkits obtained from other sources or from Equi 4 in formats Starpacker cannot extract. Check "Create Mac OS X application package" to create an application bundle directory structure containing the output Starpack. This option will be initially unchecked if you select a Tclkit runtime for a non-Mac OS X platform. Click the "Pack" button to choose where to save the output Starpack. Once you click "Save" in the file browser, the Starpack will be created. Status messages will appear at the bottom of the window while packing is in progress. Menus ----- The "File" menu contains commands corresponding to controls in the main window as well as commands for managing Tclkits and the cache. - "Open Starkit...": Equivalent to clicking "Browse..." in the "Starkit" section - "Open Recent Starkit": Select a recently-used Starkit - "Save Starpack As...": Equivalent to clicking "Pack..." in the main window - "Check for new Tclkits...": Update list of Tclkits as described in Setup - "Cache": Inspect or manipulate the cache: - "Report": Display the path and size of the cache - "Reveal": Open the cache folder (on Mac OS X) - "Reset...": Delete the contents of the cache - "Choose Location...": Select a new cache folder as described in Setup Mac OS X -------- Dragging a Starkit to Starpacker's Dock icon will use it as the Starkit to pack. The "Create Mac OS X application package" option uses the method described at . For any purposes other than packing quick test applications, it is important to replace the default icon and review the application property list. Command Line ============ Starpacker can be controlled from the command line. Usage: starpacker Displays interface. [-starkit PATH] Identify Starkit to pack. [-release VERSION] Select Tclkit Tcl/Tk release [-runtime PLATFORM] and select platform variant of release [-tclkit PATH] or select an arbitrary Tclkit. [-option macapp] Create a Mac OS X application bundle. [-starpack PATH] Choose location for output Starpack. The -tclkit option is an alternative to -release and -runtime. A -starkit and some sort of Tclkit are required to use -starpack. If -starpack is specified, the Starpack will be created immediately. Otherwise, command line options will initialize interface choices. Help: starpacker -h|-help|-help usage Print this usage message and quit. starpacker -help text Print documentation and quit. Update: starpacker -update tclkits Retrieve list of available Tclkits. Starpacker can download requested Tclkits as needed from Equi 4 Software. Tclkits are retrieved from http://www.equi4.com/pub/tk/downloads.html. Cache: starpacker -cache path Report cache location. starpacker -cache size Report cache size. starpacker -cache clear Delete cache. starpacker -cache PATH Set new cache location. The cache contains temporary files and Tclkits downloaded by Starpacker. About ===== Starpacker was written as a convenience for my personal use on Mac OS X. I have encountered VFS problems with Tclkits for earlier versions of Mac OS and for Windows. These issues are unfortunately beyond my present ability to resolve; otherwise, Starpacker should be relatively platform-independent. Starpacker has been an experiment in Tcl programming as much as anything else. Jim DeVona http://anoved.net/ $Id: help.text 274 2008-03-26 18:15:38Z anoved $