This page gathers together in one place examples and descriptions of how to develop a [Starkit] application. If you are a first time Starkit user then go to the Starkit home page (see [http://www.equi4.com/starkit/]) for an overview of Starkit and information on what tools you will need and where to down load them. Feel free to add your own ''How To'' or improve an existing one. [Tom Krehbiel] ---- '''How to [Build Your First Starkit].''' ---- '''How to convert an application to a Starkit.''' Most tcl applications can be converted to a Starkit with little or no modification. The primary requirement is that all code exist under one node in the file system directory structure. A recommended Starkit directory structure illustrated on the "Anatomy of a starkit" page (see [http://www.equi4.com/191]). This recommended structure should be used for all new applications, but when converting an application the only real requirement is that the file ''main.tcl'' exist at the top of the directory structure. Beyond this requirement you may want to put all packages in a ''lib'' directory at the top level because this directory is automatically added to the tcl auto_path by tclkit and doing this in the main.tcl script is a real pain. Once you have fixed the directory structure of your application, you can proceed wrapping your application into a Starkit or Starpack. ---- '''How to wrap/unwrap a Starkit or Starpack.''' A starkit (or starpack) is wrapped using the '''sdx''' application (see [http://mini.net/tcl/3411]). This application implements a lot of command but the wrap command is used to convert a directory containing an application into a starkit or starpack. To recover the original directory from a wrapped starkit or starpack use the sdx ''unwrap'' command. The "How to assemble a starkit" page (see [http://www.equi4.com/188]) illustrates how to use the sdx wrap and unwrap commands. ---- '''How to write the main.tcl for a starkit.''' The following description is paraphrased from comments made by [Jean-Claude Wippler]. These two lines should always be the first two in main.tcl: package require starkit if {[starkit::startup] eq "sourced"} return Usually, main.tcl contains just one more line after that (where "myapp" is replaced by whatever your app is called): package require app-myapp That way, you can run things 4 ways: 1. unwrapped: tclkit myapp.vfs/main.tcl 2. starkit: tclkit myapp.kit 3. starpack: myapp 4. sourced: source myapp.vfs/main.tcl 5. plugin: no, not yet, but who knows - one day? The string returned by startup is one of the above, and indicates to the main.tcl script how it was launched. The check and return on "sourced" is a convenience, it prevents main.tcl from actually starting anything up. The effect is that the starkit's lib/ directory will have been added to the path, so all packages are available to the context where "source" was called. This auto_path change is part of the logic in starkit::startup. The other thing starkit::startup does, is to set the starkit::topdir variable to the directory where main.tcl resides. There's a "gotcha" in the current startup logic. If one starkit sources another, say a collection of packages such as [kitten], then the starkit::topdir variable will end up pointing to kitten. That's usually not what you want, so you have to save topdir in your scripts before sourcing other starkits: set mytopdir $starkit::topdir source somepath/kitten.kit '''NOTE''' The VFS in a Starkit is case-sensitive. If working on 'Windows, ''do not rename files in an unwrapped Starkit'' as it can lead to failures of the wrapped application which don't show up in the unwrapped application (because the 'Windows file system is not case sensitive.). -- [CLN] ---- '''How to create/use a Starkit in a Starkit''' The following description was provided by [Jean-Claude Wippler]. > Could you elaborate a little on the "three-file mode". I'm only > familiar with the 2-file mode. What is the correct method for loading > extentions from a third starkit. It's what Kitten does. One file is tclkit, one file is the app starkit, and a third file contains a bunch of extensions, it could come from another source, or contain things want to have around in multiple projects anyway. Here's a quick summary of steps to create/use a separate starkit for extensions: * create myexts.vfs/main.tcl containing just these two lines (i.e. setup & return): package require starkit starkit::startup * place all your extensions inside myexts.vfs/lib/ * wrap it up using "sdx wrap myexts.kit" * to use these extensions, all you need to do is "source myexts.kit" A few possible refinements: * if you want it to work as above but also list all packages when launched, use: package require starkit if {[starkit::startup] eq "sourced"} return puts [lsort package names] # note that you'll also see other packages on auto_path * to source myexts.kit when it lives *next* to the launched app starkit: source [file join [file dirname $starkit::topdir] myexts.kit] * to avoid unwanted interaction between two starkits, perhaps make that: set savetop $starkit::topdir source [file join [file dirname $savetop] myexts.kit] set starkit::topdir $savetop ---- '''How to display a Console window when a starkit is run on Windows''' The following example illustrates how to display a Console window when a starkit (or starpack) is run on Windows. package require starkit starkit::startup if { $tcl_platform(platform) eq "windows" } { package require Tk wm withdraw . console show } ... application code starts here ... ---- Note that commands such as [file] may not work as expected on files within the [Virtual File System], which is the way a [starkit] provides access to the files within the starkit. ---- * What are the issues for locating the current directory within a starkit? The root {i.e. mount point} for a starkit is stored in the $starkit::topdir variable. The 'cd' and 'pwd' commands work as you would expect them to work. * Can one use relative path names within Tcl commands like [source]? Yes. * Can one [exec] another file within a starkit? No, but the executable file can be copied to /tmp (or some other location) on the host and then exec'ed. (An example of how to do this: [Matthias Hoffmann - Tcl-Code-Snippets - Starkit/pack-related].) * Should the default starkit directory structure, created by [sdx] qwrap, include support for multiple platforms by default? ---- [snichols] * How does someone go about making a starkit writable? Meaning, files can be updated, added, or deleted to/from the KIT at runtime? sdx wrap blah.kit -writable ;# see: sdx help wrap ---- [davidw] * How does one make a CGI ? I checked out the page that jcw made, but I still get: application-specific initialization failed: couldn't open "setup.tcl": no such file or directory What's really weird is that if I copy the starpack to /usr/bin, so that it's in the path, things seem to work. [Category Tclkit] | [[What other category should go here?]] [AMG]: Perhaps [[Category Awesome]]? :^)