💎 PREMIUM: Gallery - Full Gallery 2025

Tcl Package User Guide

The Tcl Package User Guide describes how to obtain, manage, and use Tcl packages

See Also

User Guide

Package Developer Guide

for those who want ot create their own packages

Teapot

A package distribution system, for ActiveState::ActiveTcl

Package tips and tricks

package equivalences

jcs: a page to sort out issues regarding packages which need to co-exist, such as binaries with a fallback to a pure Tcl implementation.

What do I need to do to reuse someone else's Tcl code?

Description

In the most elementary case, using a package is a matter of directly employing the load or source command to make the code in some file available to Tcl. This can be seen in the following examples:

extension example

Typically, however, packages are distributed such that they can be loaded via the package command. In a nutshell, just make sure $auto_path contains the directories or parent directories (one level up) that should be searched for pkgIndex.tcl files, which in turn contain the package ifneeded commands to either source or load the files necessary to provide requested packages. If the default $auto_path value isn't doing the job, try augmenting it with the TCLLIBPATH environment variable, which is a Tcl list, not ; or :-separated values.

Files that end in .tm, are Tcl modules, and are found by a different mechanism. There is no environment variable like $auto_path for these. Instead, use the commands ::tcl::tm::path add, ::tcl::tm::path remove, and::tcl::tm::path list. The environment variables TCLX_Y_TM_PATH, where X is the Tcl major version, and Y is the Tcl minor version, are also detected, and are a sequence of pathnames delimited by ; (windows) or : (unix).

See also:

Just getting a package found already

Where does the package command find the packages it seeks?

Building Packages

Most packages use the TEA template, so it's a matter of doing

./configure
make
make install

The most common variant on this is to specify a certain tclConfig.sh

./configure --with-tcl=/pathname/of/tclConfig.sh
make
make install

If installing to some alternate prefix, the current behaviour of the TEA template requires that --exec-prefix is also specified.

./configure --with-tcl=/pathname/of/tclConfig.sh --prefix=/pathname/of/my/bin_directory --exec-prefix=/pathname/of/my/bin_directory
make
make install

And that's usually all there is to it!

If you are on Windows, then chances are you are using ActiveTcl, in which case you want

teacup install some_package

Or to get a list of available packages

teacup list

See also:

Building an extension for Tcl under Mac OS X

Solutions for Extension Building

How to build for WinCE

Unloading a Package

How to unload a package:

List of Currently Loaded Packages

proc packages {} {
    # returns the list of presently loaded packages
    set res {}
    foreach i [package names] {
        if {[string length [package provide $i]]} {
            lappend res $i
        }
    }
    set res
} ;# RS

LV Is there a way to modify this packages proc so that it also reports the version of the package that was loaded?

Lars H: Yes, simply change the

lappend res $i

line to

lappend res $i [package provide $i]

Report Package Versions

RS 2006-01-29: Here's a package version retriever that returns a list, which can be put into a dict or array:

proc packages {{pattern *}} {
        catch {package require ""}
        set res {}
        foreach p [lsort [package names]] {
                if [string match $pattern $p] {
                        lappend res $p [package versions $p]
                }
        }
        set res
}

Incidentally, packages Tcl and ActiveTcl report {} at package versions, seen on 8.4.5 and 8.4.12. At least the former could do the same as what info patchlevel does... Tk says 8.4 at least, but there are many precedents of packaging reporting 3-part version numbers, Mk4tcl even does four: 2.4.9.2. Test:

% foreach {p v} [packages T*] {puts "$p : $v"}
Tcl :
TclScript : 1.0
Tclx : 8.4
Tk : 8.4
Tkhtml : 2.0
Tktable : 2.8
Tkx : 8.3
Trf : 2.1

Modules

See also Tcl modules for possibly new alternatives to packages. Then there is kitten, which is an example of storing packages in a single starkit which is easier to ship around.

Misc