<h1>Using teaparty</h1>

<h2>teapot-client</h2>

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 ?...?

<tt>os</tt> comes from <tt>$(uname -s)</tt>.

<tt>cpu</tt> comes from <tt>$(uname -m)</tt>.  <i>(actually I think both of these come from

<b>TODO</b>:  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, <tt>teapot-client</tt> knows about two repositories:  and These are set up near the top of the script, so modification is trivial.

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


<h2>teapot server</h2>

<i>disclaimer</i>:  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

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

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

The essence of TEAPOT is provided in two parts:

  * creates a <tt>teapot.txt</tt> file in the package's directory, which includes metadata for indexing (description, requirements etc).

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

  * <tt>teapot_index</tt> reads the content of <tt>tclpkgs-*</tt> 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 or any other simple httpd.


<h1>TEAPOT Repository Layout</h1>

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 which contains a Tcl list between markers <tt>[[TPM[[</tt> and <tt>]]MPT]]</tt>.
Each element of this list is in the form:

    {$type $name $version $arch 0}

  * <tt>$type</tt> is one of <tt>package application ...</tt>
  * <tt>$name</tt> is the package name, which may include namespace qualifiers
  * <tt>$version</tt> is of a form acceptable to <tt>package vcompare</tt>.  <b>NOTE</b>:  there is currently an erroneously packaged vectcl in rkeene's teapot, whose version is an incompatible string.  See [00bc6a8fb5] and [2566f06210] for more details.
  * <tt>$arch</tt> can be <tt>source</tt>, <tt>tcl</tt> (the generic platform specifier) or a platform specifier
  * platform specifiers are of the form <tt>${os}-${cpu}</tt>, where <tt>$os</tt> cannot contain the character <tt>-</tt>
  * I don't know what the <tt>0</tt> 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:  <tt>file</tt> and <tt>file.zip</tt> appear to be identical, and there's some special case handling of single file packages to get them distributed as <tt>.tm</tt>s.

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) <tt>teapot.txt</tt> (probably <tt>DESCRIPTION.txt</tt>, see TIP#55).


<h1>Platform specifiers</h1>

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

Tcl identifiers come from <tt>package require platform; platform::identify</tt>.


<h1>Tricks and Traps</h1>

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.


<h1>More Info</h1>

  * Tcllib's 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.
  * describes package metadata fields used in TEAPOT.