Once you have developed an application, say a database viewer or a chat program, you probably want to distribute it to other people. There are several ways to do that. One simple way is:
Have them install Tcl/Tk and give them the source code to your application. Then they can run your application like this:
This way of invoking your program means that the working directory is (or should be) the directory containing the main source file and any files your application requires, such as other source files or files containing configuration data can be found relative to that working directory.
But what if the user wants to start your program in an arbitrary directory? She might put the command in a batch file or shell script, and store that in a convenient place that is found by the invocation mechanism, like one of the directories in the PATH environmental variable, something over which you have no control. To find out where your application is installed, you can use the global variable argv0, like in the lesson on command-line arguments or the command info script as explained in the lesson on modularization.
The drawback of the simple method described above that they have to install Tcl/Tk, which your users may have no privileges for, and they will have to have the source code to your application. In a day and age where open source applications abound that is perhaps not such a bad idea, but you may not want that, for any number of reasons. One is that users can easily upset the program by trying to "customise" it in a way you do not support directly and then the question is: do you help them to restore it? Or perhaps it contains some code you want to protect because of considerations of intellectual property or you want to sell the application.
A convenient solution to that is to package your application and turn it into a standalone program. There are at least three methods that allow you to do so, these are known as starpack, mktclapp and freewrap. Each has its own pros and cons, but it is mostly a matter of taste which one you chose. Here we describe the use of starpack in some detail.
To work with starpack you first need to get the tclkit executable for your platform and for any platform you want to distribute your application to. The second piece that you will need is the sdx application, which is designed to work with tclkit.
Then it is a matter of following a few steps:
Step 1: Create an initial wrapping for your application - using the command
tclkit sdx.kit qwrap myapp.tcl
This creates a so-called starkit myapp.kit.
Step 2: As you may have more than one source file and some other files, you will need to put them in the starkit too. Use
tclkit sdx.kit unwrap myapp.kit
to unwrap the starkit. This gives you a directory myapp.vfs with the basic layout of a starkit. If you look in this directory, you will find:
.../lib/ app-myapp/ pkgIndex.tcl myapp.tcl .../main.tcl
Step 3: Put any files that are part of your application under the lib directory (packages, with their appropriate pkgIndex.tcl file) or in the directory lib/app-myapp (files you refer to directly - using [info script] to construct the proper directory). For instance:
.../lib/ app-myapp/ pkgIndex.tcl myapp.tcl auxiliary_procs_1.tcl auxiliary_procs_2.tcl ... .../main.tcl
# # The code below appears outside any procedure # (it should be run once at start-up) # # Load the files we need ... set srcdir [file dirname [info script]] source [file join $srcdir "auxiliary_procs_1.tcl"] source [file join $srcdir "auxiliary_procs_2.tcl"] ... # # Now define the procedures etc. # ...
Step 4: Wrap all these files again via the command tclkit sdx.kit wrap myapp.kit (note that the extension is "kit", not "vfs" ("virtual file system"))
This give you a starkit, which you can run with tclkit or tclsh or wish, just as if it were an ordinary Tcl source file.
Step 4: However, you can also create a standalone program using
tclkit sdx.kit wrap myapp.kit -runtime tclkit_for_target_platform
where tclkit_for_target_platform is the name of the tclkit executable for any platform on which you want to run your application. That is: you can "cross-build" your application on your favourite platform for any other platform supporting starpacks.
Some notes are in order:
One last remark: to test your standalone program to be, there is no need to go through the whole procedure. You can run the program already when you have the .vfs directory, via tclkit instead of tclsh:
This gives you the opportunity to get all the directories right where to find the files your application uses and to make sure that all packages are included.