Tcl Tutorial Lesson APP

Building and distributing applications

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:

     tclsh myapp.tcl

Note:

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.

Creating a standalone application

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.

Basic use of starpacks

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.

Notes on creating standalone applications

Some notes are in order:

• Starpacks support incorporating binary packages as well as text-based packages. As binary packages depend on the operating system, you will need to put in versions for all operating systems you want to support.
• Some operating systems, notably Windows, require you to copy out binary packages before you can load them.
• The runtime program tclkit comes in different flavours - some are built with only basic Tcl packages, others already include a wide range of packages, such as BLT for instance. This may save you time to incorporate all the "standard" packages yourself.
• It is possible to unwrap a starpack, so your code would not be completely safe, using this technique.
• The other solutions for creating standalone applications, mktclapp and freewrap, offer very similar possibilities and come with different sets of packages already built in. These may very well suit your purposes better than the starpack method. So do check them!

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:

     tclkit myapp.vfs/main.tcl

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.