Using Teacup for the first time

Notes on using the Tcl Extension Archive client - TEAcup

(If teacup does not behave as expected, make sure you have the latest version - see Teacup for upgrade instructions).

You've installed ActiveTcl, ensured that the executables are in the search path of your shell, and you're looking at a command prompt.

I'm using Windows XP, but you could be using MacOS X or any of the different flavours of Unix.

 C:\Documents and Settings\Alastair Davies>tclsh
 % set auto_path
 C:/Tcl/lib/tcl8.5 C:/Tcl/lib C:/Tcl/lib/tcllib1.7 C:/Tcl/lib/tklib0.2
 {C:/Documents and Settings/Alastair Davies/Teapot/repository/package/win32-ix86/lib}
 {C:/Documents and Settings/Alastair Davies/Teapot/repository/package/tcl/lib}
 % exit

The last two elements of this list are new. The Teapot folder in my home directory has been created during the installation of the latest release of ActiveTcl. (I am using release Teapot contains a repository folder, which contains an INDEX and a config file, but there is no package folder yet.

You'll use the TEAcup client to manage the extensions, packages or modules in that folder.

 C:\Documents and Settings\Alastair Davies>teacup help

    is a tool to access package repositories

        teacup.exe help commands        List of commands provided by teacup
        teacup.exe help help            How to use help
        teacup.exe help options         Describes the standard options
        teacup.exe help queries         Describe the syntax of complex queries

 C:\Documents and Settings\Alastair Davies>teacup archive list

Out-of-the-box, TEAcup is set to access the ActiveState repository. Maybe you want to grab a copy of the dict extension, in order to be able to use your 8.5 scripts in an 8.4 installation.

 C:\Documents and Settings\Alastair Davies>teacup install dict
 Resolving dict -is package ... [package dict 8.5.3 win32-ix86 @]
 Resolving Tcl -require 8.4 -is package ... [package Tcl 8.5 _ ... Already installed, probing dependencies]

 Retrieving package dict    8.5.3 win32-ix86 ...@ ... Ok

 Installing into C:/Documents and Settings/Alastair Davies/Teapot/repository

 Installing package dict 8.5.3 win32-ix86

And, sure enough, there is now a new cascade of folders within my repository.

 Directory of C:\Documents and Settings\Alastair Davies\Teapot\repository\package\win32-ix86\lib\dict-8.5.3

 08/12/2006  10:12    <DIR>          .
 08/12/2006  10:12    <DIR>          ..
 08/12/2006  10:12            32,768 dict853.dll
 08/12/2006  10:12               268 pkgIndex.tcl
 08/12/2006  10:12               306 teapot.txt
               3 File(s)         33,342 bytes

So far, so very good. No doubt there will be some problems, but I've only stumbled on one so far. Consistently, the TEAcup client is unable to update itself.

 C:\Documents and Settings\Alastair Davies>teacup update-self
 Updating C:/Tcl/bin/teacup.exe ...
 Found newer version (win32-ix86) @

 Retrieving application teacup win32-ix86      ...@ ... Error: timeout
 Bad retrieval.

AK: Use the -v flag of 'get' to determine what operation is actually timing out. Problems should be also be reported at in the Project ActiveTcl. The relevant component in the 'add bugs' form is teapot.

AK: I ran into timeouts myself, not necessarily a server problem. I specify a 10 second -timeout for package http, and this is apparently absolute, not activity-based, so this may kill us mid-transfer. In the newest builds of teacup that value was upped to 30 seconds. Luckily even with update-self not working you can update manually. teacup get teacup will likely run into the same timeout. However you can use whatever your prefered browser is and go to This gives you the list of teacups, and from there you can download it either using the browser, or wget, ...

I myself ran into trouble with timeouts when downloading the INDEX took longer than 10 seconds, I was not aware that http would measure that in absolute terms, instead of activity-based. The timeout in the newest builds has been incremented to 30 seconds. To get a new teacup see teacup update-self.

Alastair Davies dutifully reported a bug [L1 ] -- I'm not saying it is a bug, just that it doesn't work for me -- that the operation consistently times out when requesting the more specific "teacup get XOTcl 1.4.0 macosx-universal" but consistently works for the less specific "teacup get XOTcl 1.4.0".

LV I have found that I have to have teacup update its timeout value to 120 or more seconds to be able to more consistently complete transactions. Your network speeds, etc. may result in varying values.

One other niggle struck me when I updated a buggy extension installed in C:\Tcl\lib to a newer version retrieved using TEAcup. Because of the order of the directories in the auto_path list, it was necessary to delete the former version (via teacup remove) in order to be able to use the latter. Perhaps with correct use of version numbers this would not be a problem, but this particular bug in the vfs::starkit package concerned the incorrect use of version numbers!

Anyway, these are minor problems, in an excellent development. Many thanks to ActiveState and others who have contributed. I hope this helps get more people started using the TEAcup client and that similar guidance for package authors to use the TEApot server will become available.

Alastair Davies 8 December 2006


Q. are there arguments to get reports rather than getting the data?

A. Yes, there is a '--dry-run argument that tells you what it would do, without actually doing it.

Q. For example, are there arguments so I can ask what items would be updated?

A. Along with that, teacup list has arguments to tell you what items already installed have newer versions in the repository.

Q. How about arguments for getting a list of extensions in the repository but not installed?

A. Yes, what items could be installed, but has not yet been installed, on the platform is also available from teacup list.

Q. What about a report of the metadata about an extension - what it is, who contributed it, what the license is, etc.?

A. Well, the potential is there via teacup describe. It would be nice if there was some way for the community to contribute updated descriptions though.

Q. And one last report I can envision knowing - a report of what versions of an extension are available and the dependencies of those extensions . This last report would be useful if you needed to assure yourself which version of the extension was needed for a particular version of tcl. Since one might be needing to download the extension on machine one and then to move it to another machine, the client can't depend on the current machine's version of tcl being the destination version (same for platform, etc.) ...

A. [fill in the answer here]

Alastair Davies didn't intend to reproduce the manual page [L2 ] in the example above -- just give people the confidence to grab a package using TEAcup for the first time. There are command line options galore.

For example, the --dry-run switch reports on what would be updated (if anything).

 C:\Documents and Settings\Alastair Davies>teacup install --dry-run dict
 Resolving dict -is package ... [package dict 8.5.3 _ ... Already installed, probing dependencies]

You can see what's in your own local repository...

 C:\Documents and Settings\Alastair Davies>teacup list --at-default
 package dict    8.5.3 win32-ix86
 package starkit 1.3.1 tcl
 package vfs     1.3   win32-ix86

...and the full list in the remote archive...

 C:\Documents and Settings\Alastair Davies>teacup list

...which I won't paste in here. Specific packages are available for more than one platform, and often in more than one version, as XOTcl, for example.

 C:\Documents and Settings\Alastair Davies>teacup list XOTcl
 package XOTcl 1.4.0 aix-powerpc
 package XOTcl 1.4.0 hpux-parisc
 package XOTcl 1.4.0 linux-glibc2.2-ix86
 package XOTcl 1.4.0 macosx-universal
 package XOTcl 1.4.0 solaris2.6-sparc
 package XOTcl 1.4.0 solaris2.10-ix86
 package XOTcl 1.4.0 win32-ix86
 package XOTcl 1.5.3 aix-powerpc
 package XOTcl 1.5.3 hpux-parisc
 package XOTcl 1.5.3 linux-glibc2.2-ix86
 package XOTcl 1.5.3 macosx-universal
 package XOTcl 1.5.3 solaris2.6-sparc
 package XOTcl 1.5.3 solaris2.10-ix86
 package XOTcl 1.5.3 win32-ix86

RLH Why does it bring back everything instead of the platform possible versions?

There were three other versions of XOTcl that I excised from the list. And what is XOTcl?

 C:\Documents and Settings\Alastair Davies>teacup describe --all XOTcl
 Entity   XOTcl
 Origin @
 category      : Object oriented programming
 description   : XOTcl combines the ideas of scripting and
                object-orientation in a way that preserves the benefits of
                both of them. It is equipped with several new language
 name          : XOTcl
 platform      : aix-powerpc hpux-parisc linux-glibc2.2-ix86
                macosx-universal solaris2.10-ix86 solaris2.6-sparc
 require       : {Tcl -require 8.4}
 subject       : OO Objects Classes Inheritance Methods
 summary       : An object-oriented scripting language based on MIT's OTcl
 version       : 1.4.0 1.5.0 1.5.1 1.5.2 1.5.3

Now you know.

Finally, LV asks above about downloading on one machine and moving to another, with a different set of installed packages and possibly even a different architecture. Is there a flag to force a particular choice of architecture and to retrieve all dependencies, even ones already present on the local machine? I'm not sure there is. But bear in mind that I used this for the first time yesterday, so that doesn't mean it can't be done.

Alastair Davies 8 December 2006

male 2007-06-04:

Sorry to ask, but from which ActiveTcl version on the Teapot repository should be installed?

I currently run 8.4.13 and have no repository at the expected location.

Another problem is, that my software was installed using the Administrator login and is now used with the "normal" login. I would expect, that the repository could be found in the Administrators profile, but there it is not.

And how is teacup to be used to create a standard repository?

LV The teapot/teacup setup comes when one installs ActiveTcl 8.4.14 or newer, I believe. Read the teacup wiki page for more information.

haylingchrist - 2011-11-22 12:57:58

The first thing I want to do is list the packages installed locally....

AK - 2011-11-22 15:21:24

AK: teacup list --at-default

MHo 2016-10-06: It should be noted that teacup update* doesn't work even for 32bit ActivTcl if running on 64bit windows systems.

Could that be true?

Today 64bit Windows is a de facto standard, 32bit Windows is silently shutting down....;-)