Tcl 2014 Conference, Portland/OR, US, Nov 10-14
Send your abstracts to by Sep 8.

Using teaparty


In the first instance, teaparty gives a nice client-side implementation of the protocol: think teacup, but simpler.

teapot-client get <dir> <os> <cpu> package ?...?

os comes from $(uname -s).

cpu comes from $(uname -m). (actually I think both of these come from platform::identify)

TODO: teapot-client lacks any way to retrieve other than the latest available version of a given package. It ought to be fairly straightforward to support package versions separated by a metacharacter (perhaps /?).

As distributed, teapot-client knows about two repositories: and These are set up near the top of the script, so modification is trivial.

TODO: teapot-client always uses HTTP. It should be possible to use HTTPS and file:// URLs as well without much trickery. The latter would make hosting a local archive much simpler.

teapot server

disclaimer: I'm still in the process of working this out.

Teaparty includes a build environment capable of cross-compiling extensions for a number of platforms, in server/buildpkgs.

Here, you will want to adjust and to suit your environment (cross compilers and target Tcl versions). Note that expects to find a build-cc environment, but that line can be commented if you have gcc cross toolchains in your $PATH.

This script is instructive in showing the difference between GCC and Tcl platform strings.

The essence of TEAPOT is provided in two parts:

  • buildpkgs/create_teapot creates a teapot.txt file in the package's out/ directory, which includes metadata for indexing (description, requirements etc).

This is run by, whose final output is a tarball tclpkgs-${os}-${arch}-${timestamp}.tar.bz2 which contains the built packages with their teapot.txt files ready for indexing.

  • teapot_index reads the content of tclpkgs-* tarballs (extracted into a directory) and creates a teapot archive in another directory.

Once complete, this is ready to be served up over HTTP using dustmote, filed or any other simple httpd.

TEAPOT Repository Layout

This doesn't seem to be documented anywhere else. The following is what I've inferred from reading the teaparty source.

A TEAPOT repo is just a filesystem layout, normally served over HTTP. The main index is at URI /packages/list, which contains a Tcl list between markers [[TPM[[ and ]]MPT]]. Each element of this list is in the form:

{$type $name $version $arch 0}
  • $type is one of package application ...
  • $name is the package name, which may include namespace qualifiers
  • $version is of a form acceptable to package vcompare. NOTE: there is currently an erroneously packaged vectcl in rkeene's teapot, whose version is an incompatible string. See [00bc6a8fb5] and [2566f06210] for more details.
  • $arch can be source, tcl (the generic platform specifier) or a platform specifier
  • platform specifiers are of the form ${os}-${cpu}, where $os cannot contain the character -
  • I don't know what the 0 is for, but it seems to be constant

Platform specifiers should be compared case-insensitively.

Files themselves are stored at:


Now, I'm not entirely clear on how this works: file and appear to be identical, and there's some special case handling of single file packages to get them distributed as .tms.

This seems to be only the bare essentials: ActiveState's teacup may hit some more complex interfaces to get searchable data, which is probably generated from (the equivalent of) teapot.txt (probably DESCRIPTION.txt, see TIP#55).

Platform specifiers

Gcc/unix identifiers come from $(uname -s)-$(uname -m).

Tcl identifiers come from package require platform; platform::identify.

Tricks and Traps

Support for secure transport and signed packages would be a Very Good Thing. I believe Roy may already have a good solution to this, or at least some good advice.

More Info

  • Tcllib's sak.tcl does (among many other things!) a bunch of work to package components of tcllib for TEAPOT distribution. It may be the source of some wisdom.
  • TIP#55 describes package metadata fields used in TEAPOT.