|[Installing Tcl%|%previous : Installing Tcl]|[Extensions for Tcl and Tk%|%next : Extensions for Tcl/Tk]|

The '''Tcl Package User Guide''' describes how to obtain, manage, and use [Tcl] [package%|%packages] 



** See Also **

   [Tcl User Guide%|%User Guide%|%]:   
   
   [Tcl Package Developer 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.



** 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 '''[tm%|%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:

======none
% 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 **



<<categories>> Documentation