D 2015-04-16T02:38:50.843
L technotes
N text/x-markdown
P c59d5c43969a55130beb8c7f09df4baf05a84bd1
U aspect
W 5170
<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 <tt>platform::identify</tt>)</i>
<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 <tt>/</tt>?).
As distributed, <tt>teapot-client</tt> knows about two repositories: [http://teapot.rkeene.org/](http://teapot.rkeene.org/) and [http://teapot.activestate.com/](http://teapot.activestate.com/). 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 <tt>file://</tt> 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 <tt>server/buildpkgs</tt>.
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 [build-cc](http://build-cc.rkeene.org) 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:
* <tt>buildpkgs/create_teapot</tt> creates a <tt>teapot.txt</tt> file in the package's <tt>out/</tt> 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 [dustmote](http://wiki.tcl.tk/dustmote), [filed](http://filed.rkeene.org/) 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 <tt>/packages/list</tt>, 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:
/package/name/${name}/ver/${version}/arch/${arch}/file
/package/name/${name}/ver/${version}/arch/${arch}/file.zip
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 [sak.tcl](http://core.tcl.tk/tcllib/finfo?name=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](http://www.tcl.tk/cgi-bin/tct/tip/55.html) describes package metadata fields used in TEAPOT.
Z a45d793f9d015fb64d920e1054a386ac
