How to start with tcllib

Purpose: to discuss how to install and use the tcllib extension.

Most of the information contained here is more up to date at the top of the tcllib page

Since this is the page for those new to tcllib, could someone please add a newbie-oriented basic introduction? There's some descriptive material on the tcllib page, but the very top of that page (currently) directs all beginners to *this* page. Sorry, I'd write it myself, but as yet I'm still one of those newbies. :) Feel free to delete this comment once an introductory description is in place. --willdye

Hmm. Come to think of it, it might be better to put the introduction at the top of tcllib itself, since that page is named "tcllib", and it seems desirable that people using the wiki can often find out about "x" just by adding it to the URL. Ater the introductory paragraph, newbies can then be directed here for installation issues, and a separate page can be created for advanced discussions ("tcllib development" or somesuch). Well, whoever takes up this request can do as they wish, but IMO we need at least one introduction, here or at the top of tcllib. --willdye again

LV what kind of basic introduction are you thinking of? There's not much basic introduction I can think of relating to tcllib itself - because there's no code that is specifically tcllib. Instead, there are various modules, listed on tcllib, each one of which I could see needing a basic introduction.

You should have an installed Tcl version greater or equal to 8.2 for most packages in Tcllib, for 64-bit systems a recent Tcl 8.4 or newer is recommended.

Getting the Tcllib group of packages edit

See Tcllib location for the appropriate URLs and tools to get a tcllib install.

---

Installing Tcllib edit

If you used something like ActiveStates Distro, a deb or rpm package, you probably don't need this.

The easiest way to install tcllib is the included installer, try:

 tclsh installer.tcl

 wish installer.tcl

It pops up a GUI if Tk is available, which will guide you through the installation. You can get infos about valid command line switches for the installer by running:

 tclsh installer.tcl -help

Testing if one of the Tcllib packages works edit

Fire up your default tcl interpreter. Try this:

 package require logger 0.3

If it works and returns the version number of the returned package, you installed Tcllib correctly. If it does not work, check your auto_path variable like this:

 % set auto_path

It has to contain the parent directory of the directory you installed the packages to, or the install directory itself. If it is missing, you have to add it to your auto_path in your scripts.

 % lappend auto_path /path/to/tcllib/installdir

Checking Dependencies edit

How am I supposed to test the availability of a given tcllib version - I am writing a tool that should interact with the user to install packages, which needs to check dependencies. Basically, if packages Y needs Tcllib version X, how can I know if Tcllib version X does *not* need to be installed ? -- 20060509 Sarnold

schlenk You do not. package require tcllib has been deprecated for quite a while. You check the individual package dependencies, not the tcllib version. There are a lot of people who strip modules from their tcllib for deployment, so if you just check for the existance of tcllib you will check the wrong thing.

Sarnold Okay. I will take this into account when managing packages dependencies. And I realized my problem is much a problem in detecting available packages, and what I would need is something like Tcl Modules. -- 20060509

Examples for Usage of Tcllib Packages edit

There are some short examples in the documentation for the packages, but not all contain examples. Second there is an examples dir installed, if you selected it during install, it contains some example scripts for packages.

A further place to look for examples is this wiki, tcllib has links to most packages/commands and some of them contain examples.

Historical info and discussion for pre 1.6 versions edit

Crude answer, relevant mostly to versions before 1.0: unpack the source distribution into a directory such as

  $MYDIR

so that there are files such as

  $MYDIR/tcllib/mime/mime.tcl

At the level of Tcl source, you don't use tcllib; you use packages from the tcllib distribution. To use the mime package, for example, you might

  lappend auto_path $MYDIR/tcllib
  package require mime
  # ... Now you can use any of the mime::* proc's.

HOWEVER I (LV) strongly recommend that, if at all possible, you go ahead and do the configure, etc. mentioned below.

Later, someone else writes: BUT tcllib now contains a very simple 'install.tcl' file which you can just execute to install everything without all the configure, make nonsense. Yippee! Tcl finally uses itself to install packages.

LV writes: unfortunately, I never was able to get the install.tcl to work. It wants me to delete any previous version of tcllib1.3 that I had installed before it will work. that was rather nasty. It also didn't allow me to even specify a new directory where I might want to install tcllib to test before installing it into production. Thank goodness the configure/makefile continues to work right.

AK A bit of defense: The script always uses a directory relative to the tcl shell used to execute the script. This means that by calling the script with a shell in a development environment, like

 % /path/to/devel/tclsh install.tcl

tcllib will be installed in that development environment.

The safest thing to do though is to run the tcllib/configure [make point of detailing which versions of tcllib have configure - versions since 2000 at least] with the appropriate flags, then to run "make install" so that files end up in the location tcl expects to find them, with the proper names, etc.

configure can be invoked with flags pointing to some other directory than where Tcl is installed; point at a $HOME directory for instance. When you do this, then don't forget to make use of the auto_path trick mentioned above.

WARNING! Use Tcl8.2 or later with recent tcllib (certainly 0.8 and higher). There are cases where in particular the code uses the new string functionality that appears in later versions of tcl to dramatically improve performance. This results in locking tcllib currently into newer versions.

There have been discussions about people wanting/needing tcllib to work on older versions of tcl working together to write some forward compatibility procs for tcllib, so that it can be used over a wider range of versions. Alas, this work has not proceeded very quickly.

Steps to installing tcllib - or most other TEA based applications edit

The way one does this is this. Perhaps at some point, some derivative of this information might be useful to make available in tcllib and the other TCT managed software distributions.

1. Obtain the tar file that you wish to use.

        I currently recommend to people that they get the latest tcllib tar
        file from either http://tcllib.sf.net/ or
                         ftp://www.tcl.tk/pub/tcl/nightly-cvs/

2. cd into a working directory

3. Untar the downloaded file. What you have as a result is a directory in the current directory called "tcllib". If you see an error, the most likely cause of this error is that the file was downloaded as a text file instead of a binary file. Other possible errors are not having a program that knows how to deal with a gzip'd tar file, lack of disk space, or lack of permissions to write into the disk space.

4. cd tcllib

5. Now a choice needs to be made . Tcl needs to find the modules in a known directory. You have two choices. You can either install things into one of the built in directories of Tcl, or you can add an environment variable or lines to your Tcl code so that Tcl can find the library. What _I_ do is to tell tcllib to install in the same place I tell Tcl to install. For instance, I currently am building Tcl 8.3.4 to install in /usr/tcl83 ; when I build tcllib for that version of tcl, I tell tcllib to install there as well. In my case, I type:

$PWD/configure --prefix=/usr/tcl83

You would use a directory matching the directory you told tcl. If you installed a binary version of tcl, then type

 info library

and you will get a path back such as:

 % info library
 /usr/tcl83/lib/tcl8.3

In this case, Tcl was configured with a '--prefix=/usr/tcl83' .

6. The result of the configure you just did SHOULD be a Makefile. If not, then you've found a problem on your system; this might be a configure bug, or it might be some problem on your system (for instance, perhaps your system has no compiler or some other required application).

In the case of an error, read through the output to the screen as well as the config.log file and see if the error messages lead you to a solution. It would be useful to search http://tcllib.sf.net/

bug report database to see if you can find previous reports of errors with fixes. If nothing reasonable is determinable or found, then submit a bug report. The form there asks for a lot of info - the more you provide, the more likely the problem can be resolved. At this point, you would cycle back to one of the previous steps and begin again.

7. If the result of the configure was a Makefile, then you should type the name of the make command you use. Often this will be "make" or "gmake". There are other make files for other platforms - I don't know those other platforms, so I don't have instructions for you.

8. In the case of an error, read through the output to the screen and see if the error messages lead you to a solution. It would be useful to search http://tcllib.sf.net/

9. If the result of the make was successful, then I recommend telling your make to run the target of "test", which runs the tcllib through a test suite. If this results in any indication of warnings or errors, read through the output to the screen and see if the error messages lead you to a solution. It would be useful to search http://tcllib.sf.net/

10. If the result of the test was successful, then you tell your make command to run the install target. This results in an attempt to create directories and copy files into those directories. During this process, you will likely see warnings about directories already existing - this is an error you can ignore. The result should be a tcllib whose modules are installed appropriately.

And for Windows users ...

JCW Ouch! ... given that this is all about platform-independent scripted Tcl code: why does tcllib introduce all this machinery? Why can it not simply be unpacked and used, with optional stuff for those who feel that life without (dare I say "after"?) configure and make is too big a change. It seems a bit self-defeating to insist on creating a fine package full of goodies which do not require compilation, and then have it all end up being deployed in such a way that Windows users and others are left behind... CL replies: 'You asking me, Jean-Claude? I find tcllib packaging too complicated to understand.

Vince: even worse. The above instructions fail, because you need to download a 'config' module from somewhere as well, else step 5 fails.

LV Vince, I am working on this config problem. JCW, I didn't put the wrappings around tcllib, I'm just documenting the current needs. There have been dozens, if not hundreds, of msgs around usenet and elsewhere about developing a TEA lite for script only distributions, to make distributions simple. So far, no one has written up a proposed standard for people to follow. So we have everything from the ugly structure of TEA, never designed for script only, to various install scripts, some good and some not so good, to nothing. The tcllib project is open to all to join and submit patches, feature requests, etc. - if the community wants change, there is certainly a process in place to see that change occur.

CM That's how to install, ok, it works for me.. (apt-get is my friend! ;-). Now does anybody know where to find small examples of use? Most of the ref doc seems to be in the vein of Unix mans.. Has Anybody tricky code working with javascript or htmlparse or just a simple ncgi script ? Maybe we can extend their wiki page and then forward a selection to the maintainers to get some kind of tutorial docs. What do you think? (I'll post my CGI and MIME handling scripts if needed but at that time, they're very simple! :-). CL answers: CM, we're building up lots of examples in the Wiki. They're generally found under the package names: "ftp", "mime", ...

AK --- Note that the tcllib sources contain an examples directory. I am currently not sure if this directory is in the latest official source distribution. It definitely is in the CVS. The latest official distribution is tcllib 1.3 and contains the examples directory.

Suggestions moved from Ask, and it shall be given.

Is any one interested in starting a tutorial page for tcllib ? Maybe it could start with just pasted in example code snippets. I think with some good tutorial examples a time limited programmer will more likely step in and try it out. Actually I don't even know how to start a page on the Wiki so that is why I did not even just do it myself. So, for starters, let's just create this section with various packages like this:

packageN

 link to manual
 list of code examples
  Example 1
  Description that is optional
  the example code

lv july 2003 - hmm - the wiki page tcllib certainly has a series of links to the packages, each of which have a link to the appropriate manual. So the best way to proceed would be to visit those links and either add examples, or add questions regarding the packages.

17feb04 jcw - Another way to use tcllib is through kitten, which has been updated to include 1.6. It's a no-hassle way to get going if you have Tclkit or a starkit-aware Tcl installation such as ActiveTcl or Daniel Steffens Mac OS X builds. Note that kitten is a 4.6 Mb download however (there's a lot of other stuff in there - not nearly as up to date):

   # download http://www.equi4.com/pub/sk/kitten.kit
   # in your app, do:
        source kitten.kit
   # that's it, you can now "package require" any of the tcllib packages

No docs, no support. This is not a replacement but an alternative access path to the many gems that make up tcllib.

LES But if you have ActiveTcl you have tcllib. It's part of the bundle.

LV Some of this page overlaps with tcllib installation; perhaps the common parts could be removed from here?

Category Tutorial

Category Tcllib