This is a companion piece to the article Getting started with tcltest. If you already have tcltest installed on your system you may not need to read this article.

Installing tcltest

The source distribution of Tcl comes with a test harness named tcltest [1]. If you build and install from the source distribution you should have this package available. Additionally, some third-party packaging of tcl may also include this package. To determine if you have it available you can simply run a tcl shell interactively and try to load the package:

$ tclsh
% package require tcltest

The last part of that output -- "2.2.8" -- is the version of the package. If it is not installed on your machine you'll likely see output like this:

$ tclsh
% package require tcltest
can't find package tcltest

If you see a version number that begins with "1." you have an old version of tcltest on your machine. tcltest has had some substantial improvements made since the 1.x series so you should consider replacing your old version with something newer.

Because tcltest is part of the core tcl distribution it isn't available as a standalone package. It may be used as a standalone package, it's just not distributed that way. If you wish to use tcltest and don't want to or are not able to reinstall tcl from scratch, it is easy to install. This document breaks the process down into four simple steps:

  1. Create the installation directory
  2. Download the tcltest files
  3. Install the tcltest files
  4. Test the installation

There are occassions where you may not be able to install tcltest. For example, you may be running tcl as part of a larger application and simply don't have the ability to add additional packages. Or, you may want to have a testing environment as near to the production environment as possible and therefore don't want to install extra packages. In any case, it is still possible to create test suites with tcltest without having to properly install tcltest. That is covered in the last part of this article, in the section titled Using tcltest without installing.

Step 1: Create the installation directory

One of the great things about Tcl is that it can look for and use packages in a variety of directories. One of the bad things about tcl is, well, that it can look for and use packages in a variety of directories. If you're not used to installing Tcl packages, deciding where to install can often be the biggest challenge. Fortunately, Tcl can tell you where to install new packages. All you have to do is ask.

When you do "package require packageName" the tcl interpreter will search through a list of predefined directories looking for the requested package. These directories are defined in the global variable auto_path. To see where your particular installation of tcl looks for packages you can print out the contents of this variable. Depending on the platform and on the actual program you are using (tclsh, wish, expect, etc) you'll get different results. Here are some examples from a few common systems:

tclsh on linux

% set auto_path
/usr/share/tcl8.4 /usr/share /usr/lib /usr/share/tcl8.4/tcllib1.7 /usr/share/tcl8.4/tklib0.2

wish on Windows XP

% set auto_path
C:/Tcl/lib/tcl8.4 C:/Tcl/lib C:/Tcl/lib/tcllib1.5 C:/Tcl/lib/tcllib1.7
C:/Tcl/lib/tklib0.2 C:/Tcl/lib/tk8.4

tclsh on MacOSX

% set auto_path
/Library/Frameworks/Tcl.framework/Versions/8.4/Resources /usr/lib 
~/Library/Tcl /Library/Tcl /Network/Library/Tcl /System/Library/Tcl 
~/Library/Frameworks /Library/Frameworks /Network/Library/Frameworks 

What does this mean? It means that you can install packages in any of the directories listed in auto_path and Tcl will find them when you do a "package require". It also means that you can put a package in any directory you like as long as the root directory is included in auto_path. For example, you may not have write access to any of the predefined directories so you could create a directory named "packages" in your home directory. As long as you appended this directory to auto_path everything will work just fine.

Once you have determined the directory where you want to install tcltest, create a subdirectory which will contain the tcltest files. Call this directory tcltest or anything else you want. For example, if you install tcltest version 2.2.8 and you want to install it in the packages subdirectory of your home directory you may want to create a directory named ~/packages/tcltest-228. If you have access to the standard locations on linux you may want to create a directory named /usr/share/tcl8.4/tcltest228, and so on.

Remember, if you create it in a directory that is not in auto_path by default, you must add your parent directory to auto_path before the "package require" will work (e.g. if you created the directory ~/packages/tcltest228 you'll need to do "lappend ::auto_path ~/packages").

Step 2: Download the tcltest files

The official Tcl sourcecode is maintained on sourceforge. You can download the entire source tree, or you can directly download just the tcl source files. I have also provided a copy of tcltest 2.2.8 on this website.

Downloading from sourceforge

The tcltest source files can be found in the library subdirectory of the tcl cvs repository at [2] You should download the files tcltest.tcl and pkgIndex.tcl. These files will work for all platforms and for any version of Tcl from version 8.3 and beyond.

Downloading from this site

I have created a .zip file that includes both tcltest.tcl and pkgIndex.tcl. These files correspond to version 2.2.8 of tcltest. A link to [3] can be found on the Downloads page. Download the file then expand the file to get the two individual files

Step 3: Installing the files

Once you have the files tcltest.tcl and pkgIndex.tcl you need to copy these into the directory you created in step 1. That's all there is to installing tcltest.

Step 4: Testing the installation

After doing the installation, it is an easy matter to determine if the files were installed properly. Open up an interactive tcl shell and type "package require tcltest" at the prompt. If the installation was successful you will see the following:

$ tclsh
% package require tcltest

Once again, if you installed in a directory that is not in auto_path by default, you will need to modify auto_path before doing the package require:

$ tclsh
% file exists ~/packages/tcltest
% lappend auto_path ~/packages
<complete list of directories ending with ~/packages>
% package require tcltest

Using tcltest without installing

There may be times when installing tcltest as a package is impractical or impossible. In such cases it is still possible to use tcltest. tcltest is implemented within a single Tcl script so all you need to do is place tcltest.tcl somewhere you can access from your own scripts, then include it in your test scripts with "source /path/to/tcltest.tcl". In such a case you don't need to worry about pkgIndex.tcl.