Updated 2018-09-21 19:45:01 by ak

Tcllib is a distribution of several packages for Tcl, all written entirely in Tcl, useful in a broad variety of areas. Tcllib has an approximately yearly release schedule.

A tklib module also exists under the tcllib project, which contains modules that depend on Tk.

Attributes edit

Latest release
1.19, 2018-02-16

See Also edit

Tcllib Location
Where to find and download Tcllib.
Tcllib Installation
How to install and then use Tcllib.
Tcllib Contribution & Feedback
How to contribute to Tcllib, report errors, etc.
Tcllib Contents
What is available in Tcllib

C implementations edit

Some modules of Tcllib include high-performance implementations written in C with the help of Critcl ("Tcllibc"). The typical package require ... automatically makes use of the more performant variants if possible. To check whether these more performant variants are available:
package require tcllibc

AMG: At present, the list of modules using Critcl is as follows:

Documentation edit

development version
The freshest version of the reference manual.
documentation for ActiveTcl 8.5
Tcllib 1.13 (?)
documentation for ActiveTcl 8.6
Tcllib 1.14
documentation at sourceforge
out-of-date as of 2013-03-20 - Should redirect to the development version at core.tcl.tk above.
How to start with tcllib
a discussion

Contributors edit

Cameron Laird
mime, base64, smtp, ftp, pop3, ... If

Community edit

AK has in the past written occasional but welcome Tcllib Messages of the Day (TMotD) for the mailing list.

Bugs edit

report bugs via the fossil bug tracker

Be sure to include as many of the following as possible:

  • your name
  • your email address (so you can be contacted when the bug is fixed)
  • a description of the behavior you expected to see
  • a description of the behavior you actually saw
  • the version of Tcl you are using
  • the version of Tcllib you are using
  • the OS you are using, and the version of the OS
  • anything else you think might be relevant

A sample script demonstrating the problem is always very helpful.

Misc edit

2004-05-25: Has the tcllib team considered adding some form of Michael Cleverly's package, nstcl? While most functionality is duplicated in the current distribution of tcllib, the nsset datatype is a wonderful thing to have; an indexed array! [index - key - value]. His api has some commands to utilize it as well. As an aolserver tcl coder, I work with it extensively and for me it renders the array command obsolete. APN The 8.5+ dict built-in seems to be a superset of this.
set id [ns_set create]
%t2
ns_set put $id fname Michael
%0
ns_set put $id lname Cleverly
%1
ns_set get $id fname
%Michael

As documented above, it generally isn't a matter of some team determining whether some code is worthy to add. It is typically a matter of some interested party contacting the tcllib maintainers to work out the details of their adding a new module to the library. Why not contact Michael and ask if he would like to add his code to tcllib? Over the years, it has turned out to work better if the author is involved with this process, so that no misunderstandings, etc. occur.

History edit

When Tcllib was originally released, the following was written:

In response to popular demand, the Tcl core group is introducing tcllib, a Tcl standard library. This meta-package will contain many modules, each of which is itself a standalone Tcl package. The intention is to provide commonly-used functions and libraries, bundled together under a single license (BSD), and with no binary dependencies. This will encourage use and growth of the library. Once tcllib is downloaded and installed, users will be able to "package require tcllib" or "package require any_module_in_tcllib".

Releases of tcllib will be made mostly independently of releases of the Tcl/Tk core. This will allow a faster release cycle, which is important in the early stages of development. It is possible that future releases of the core will include a snapshot of the tcllib.

Initially, we have seeded the library with several modules, some written in-house at Scriptics and by the core group:
struct
Tcl implementations of common data structures
profiler
Function level Tcl profiler
cmdline
getopt style command-line parser
base64
base64 encoder/decoder
fileutil
Tcl implementations of file utilities (grep, find, ...)
pop3
pop3 client
math
math functions (min, max, ...)

A subsequent article said
From: Dan Kuchler <kuchler@ajubasolutions.com>
Newsgroups: comp.lang.tcl
Subject: Re: Math extensions to TCLlib
Date: Sun, 05 Nov 2000 08:37:57 -0800
Organization: Ajuba Solutions
Message-ID: <3A058CE5.A9688085@ajubasolutions.com>
References: <8u4nib$ubt$1@nnrp1.deja.com>
To: Morgan <morgangoeller@usa.net>

Morgan wrote:
>
> [interesting proposed changes snipped]
>
> Also, are there any specific procedures for contributing to the
> TCLlib?  Anyone I need to contact or specific software I need to use?
> Would this go better in a sub-package of the math portion of the TCLlib?
>

It's great to hear that you are interested in helping contribute
to tcllib.  I thought your proposed set of functionality sounded
interesting.

Some folks have shown interest in having access to the functionality
available through the NumPy package (a python package) in tcl.

This might give you ideas for things that people might want.

The NumPy package is at:

http://sourceforge.net/projects/numpy/

I think the process for volunteering to work on a project there is
to contact an admin for a project.  Currently [AK] has
been organizing tcllib development, so it might be worthwhile to
contact him

Currently the web page that talks about tcllib (a little out of
date) is at:

http://www.purl.org/tcl/home/software/tcllib/

As far as guidelines for contributing, I think the current
requirement is that things in tcllib must be able to be
run in a tcl-only mode (i.e. no binary package dependencies),
and the contributed code should have either tests or documents,
but preferably will have both.

There are good contribution guidelines (that also contain a
link to the Tcl Sytle Guidelines) at:

http://www.purl.org/tcl/home/software/tcltk/contributing.tml

(while that page is focused on contributing to tcl/tk, most
of it is relevant to tcllib as well).

I hope that helps get you started!

--Dan

Discussion edit

Targeted Tcl versions

AMG: What versions of Tcl does tcllib target?

RLH: This is what I was told when I asked that on comp.lang.tcl:
Statically, you would have difficulties if you have 8.4. You have also, for instance "snit" which is an important package used by others that now requests 8.5, so with less bugs than previous edition, in the end 8.5 is mandatory and most of tcllib 1.18 will work with it.

Forward compatibility

AMG: If Tcllib is intended to support both 8.4 and 8.6, would it be appropriate to include 8.4-compatible pure-Tcl implementations of 8.6 commands? For example, I just finished writing a [dict] command that works in 8.4 yet passes most of the 8.6 test suite [1]. That might be a good fit. There are many other possible commands to consider, for instance [lassign]. See Forward compatibility for more.

JSON package categorization

RLH: Looking at the tcllib docs, json is under "CGI Programming" and it really shouldn't be. JSON is a data interchange format used for much more than "CGI Programming". So maybe "CGI Programming" needs to be renamed "Web Technologies" or another category altogether. Just a thought.

ak - 2017-09-01 21:38:12

Please file a ticket with Tcllib.

Precompiling C implementations

AMG: I need to use cross compilers to precompile various Tcllib packages to target various platforms (multiple OSes and CPUs). I can't use the target machines to do the actual compilation, especially since many of them don't have compilers installed. I am already successfully using cross compilers to build Tcl/Tk itself for all of my target platforms, so I know this is possible in principle.

What's the recommended way to go about doing this?

I tried using Critcl's -tea switch on sha256c.tcl (as a start, would do more later), but this produced very poor results, out of the box. To get the configure script to work, I had to copy many script files (e.g. gen_header.tcl, lassign.tcl) into the generated lib/sha256c/critcl/lib hierarchy. Next I had trouble with Critcl not knowing what to do with the sha256c version being "1.0", since somewhere downstream it was confusing itself by making a file with a ".0" extension. Changing the VERSION to empty string fixed that. After installing, I ended up with a package I couldn't load, not until I hacked pkgIndex.tcl to append "10" to the name of the package being loaded. With all that done, I finally had it working.

Without the sha256c package on my system, "time {sha2::sha256 hello} 100000" prints "626.25582 microseconds per iteration". With sha256c in place, that same command prints "26.26034". That's a 2384% speedup.

Here's the list of files I had to copy from the Critcl distribution into lib/sha256c/critcl/lib:

  • stubs/gen_decl.tcl
  • stubs/gen_header.tcl
  • stubs/gen_init.tcl
  • stubs/gen_lib.tcl
  • stubs/gen_macro.tcl
  • stubs/gen_slot.tcl
  • stubs/genframe.tcl
  • stubs/reader.tcl
  • stubs/writer.tcl
  • util84/lassign.tcl

I don't get it. Why should I be having multiple issues like this? Am I honestly the first person who ever wanted to precompile any part of Tcllib? Shouldn't these issues have been spotted and corrected by now? What am I doing wrong?

I'm using Critcl 3.1.17.

Also worth mentioning: I had to be sure Critcl and Tcllib were in my TCLLIBPATH because I don't have them "installed". It's definitely best that root access not be required in order to run this build procedure. This is tricky because of the issue I describe at [2].

ak - 2018-09-20 21:58:39

@AMG: I am interested in the exact (as much as possible) session you ran.

  • When I precompile tcllibc for myself I use sak.tcl critcl to do that.
  • However I don't cross-compile.
  • How did you inject the cross-compiler into the build target selection of critcl ?
  • The -tea option is still experimental. And it seems it was forgotten to be updated with regard to changes in the set of needed files.

Can you please file tickets at http://github.com/andreas-kupries/critcl ?

AMG: I haven't even gotten started on the cross compilation aspect of my task. I only put one day of effort into it, and I began by compiling for the local machine.

I'll file tickets when I have more information.

I'm glad -tea works as well as it does. I was able to get it the rest of the way there with some hacks in my driver script. I think I should be able to give you the script with minor redactions.

I'm not familiar with sak.tcl but will look around.

Also, that "append 10" part of my original writeup may be out of date. I spent the whole day on it, and over the course of the day I accumulated the writeup. That part may be obsoleted by me using empty string as VERSION rather than 10 which is what I originally used.

ak - 2018-09-21 19:45:01

Wrt the sak.tcl tool, it is in the top-level directory of Tcllib. This is also the tool used by the Makefile(.in). I.e. you can also configure ; make critcl.

Ok, without cross-compilation the whole -tea thing should not have been necessary, just either sak.tcl critcl or the make critcl after configuration should be good enough.

sak.tcl help provides help for the newer commands, and sak.tcl help old for the older set. critcl is among the latter. Although its doc is sparse, just the one line in the output.