This is the home of TEA(ish), a Tcl extension-builder tool in a vein of the TEA (Tcl Extension Architecture), also known as tclconfig. The primary difference from TEA is that teaish uses Steve Bennett's Autosetup instead of the GNU Autotools, and was it was born in the effort of porting SQLite's TEA build to Autosetup.

This project started out using the name "TEA port to Autosetup" because it intended to be a more or less straight port of TEA to autosetup. It has since gone in a slightly different direction, not because of any perceived flaws with TEA but because my ambitions for porting 4k+ lines of tea.m4 and friends have mysteriously disappeared.

The goal here is not to outright replace TEA but to provide an alternative implementation which (1) is based on Autosetup and (2) has close to feature-parity with that build, taking this opportunity to drop some of the historical cruft from that build. e.g. there is currently no intent to support Tcl versions older than 8.5, nor are there specific plans to support exotic platforms.

Collaborators are welcome! If interested, please get in touch. A willingness to use the Fossil SCM is a must (this is not hosted on github). Some moderate level of Tcl-fu is required, but nothing advanced. Familiarity with Autosetup is a plus.

Current Status

Let's call it beta. It can (./configure && make test install) the SQLite TEA extension (a copy of which is included in teaish's canonical source repository) but has yet to be tested with any other real-world Tcl extensions.

Summary of working features:

Easy to use: just create 1-3 files which describe the extension, run teaish's "configure" script on it, and you're ready to build with any POSIX-Make-compatible Make tool (e.g. GNU Make or BSD Make).
Can create new stub Tcl extensions and their teaish-specific files with a trivial invocation.
Supports out-of-tree builds.
Supports tests. If no tests are provided by the client then it generates one which ensures that the compiled extension can at least be loaded by Tcl.
Generates install/uninstall makefile rules, and the former automatically tests that the resulting installation can be loaded using Tcl's "package require".
Generates "make dist" rules for packaging your extension up for distribution.
Builds much more quickly than extensions build using TEA. For example, the SQLite extension with -O2 optimization builds in 20 seconds on my laptop with teaish vs 40 seconds with TEA. An -O0 build is even faster: 3.5 seconds vs 23 seconds.
Works with Tcl 8.5+.
Fairly portable.

Platform Portability

Autosetup runs on most POSIX-style systems. It does not work from a conventional Windows console.

Teaish has been seen to work on:

Linux of all sorts on Intel and ARM hardware.
OpenBSD
Haiku¹
Windows 11:
- Cygwin
- MSys2 (mingw64 environment)

It is regularly tested with both GNU Make and BSD Make.

Download

If you're reading this on the canonical site, you can download a recent build from here, then:

$ tar xzf teaish-TIMESTAMP-HASH.tar.gz

(The HASH part of the name corresponds to its check-in version.)

With that you can build Tcl extensions with this framework and build them using one of the following approaches:

From the directory containing the teaish-format extension:

$ /path/to/teaish/configure ...
$ make test

If you do not have tcl installed at the system level, or want to use a custom build, you may want to use the --with-tcl=/installation/prefix flag. Teaish requires a Tcl installation which has a tclConfig.sh.

From some arbitrary directory:

$ /path/to/teaish/configure --teaish-extension-dir=/path/to/extension
$ make test

Or copy the extension's files to the teaish dir and simply:

$ ./configure ...
$ make test

Cloning this Repository

This repository uses the Fossil SCM. The full tree contains lots of stuff which the downloadable distribution does not, though, for "historical reasons."

It can be cloned and used like:

$ fossil clone https://fossil.wanderinghorse.net/r/teaish
$ cd teaish/example/hello
$ ../../configure --with-tcl=/install/prefix/for/your/tcl
#            e.g. --with-tcl=$HOME/tcl/v9
#            If you have a system-level tcl, it can use that.
$ make test
$ make distclean

To demonstrate an out-of-tree build, starting from where the previous example leaves of:

$ mkdir ../x
$ cd ../x
$ ../../configure \
    --with-tcl=/install/prefix/for/your/tcl \
    --teaish-extension-dir=../hello
$ make

Authoring, Building, and Testing Extensions

See doc/extensions.md.

Source Tree Structure

This tree's structure is essentially a hand-built copy of what SQLite's canonical build generates when it creates an "autoconf build"² - a trimmed-down build process when includes only pre-generated files so that it does not rely on Tcl (whereas the canonical build has a strong dependency on Tcl for code generation and running tests). SQLite's developers do not actually use this build - it is provided as a convenience for downstream users, and SQLite's web server logs suggest that more than 80% of SQLite source code downloads are of this variant of the build.

The directories are as follows:

./teaish: the primary source code for this project.
./teaish/autosetup: a complete upstream copy of Autosetup, including any teaish-specific files. It is anticipated that the file proj.tcl will need to be modified in this tree, in which case those changes (A) must be compatible with the upstream SQLite tree and (B) must be copied back into the upstream copy. When updating this dir from upstream, it is important not to clobber any local changes to those files, so it's a good idea to make any changes to them in parallel with the upstream tree. Ideally, the process goes like this: (1) edit and test them here, (2) copy them to SQLite's canonical tree, (3) edit and test them there, (4) check them in there, (5) copy them back to here (to pick up the obligatory edits during testing), (6) then check them in here with a comment along the lines of "update autosetup from the upstream copy."
- The following files in this dir are specific to teaish:
- teaish.tcl is the main framework code (an autosetup module).
- teaish-tester.tcl is passed to scripts via make test and contains a small test utility API.

Notable TODOs

In no particular order...

Feature tests (i.e. Autosetup configure-script code)
- Start collecting a library of commonly-used external dependency tests so that (A) each extension doesn't have to reimplement such tests and (B) so that extensions have known-working templates to copy/paste/adapt for their custom uses.
  - This work has started in /file/teaish/teaish-feature-tests.tcl.
- Investigate the idea of autosetup tests which not only link their input C source but also capture the output from running that test. This idea came from Rolf in a Tcl meeting. It would not work when cross-compiling, but only Jan N. cross-compiles Tcl extensions ;).
Support script-only extensions, with no associated native library. We "could" do this by simply checking whether the input source code list is empty, but being limited to POSIX make means we can't do that nicely at build-time if the extension's makefile manages the source code list (as opposed to doing it in the extension's teaish.tcl). Ergo, we'd need to either set a specific flag from teaish.tcl or check: if the source file list is empty and there's no teaish.make.in, we can assume it's a script-only extension (because then we have all relevant state at configure-time).
From TEA/tclconfig:
- Scour tea.m4 for additional historical capabilities to port in.
Windows
- Even though teaish will not run in non-POSIX-style environments, we can generate a Makefile.msc for native Microsoft C when running --teaish-create-extension.
tclconfig checkins to investigate and potentially port in:
- tclconfig:3ceccd823ff62245: Handle lib prefix different on Cygwin only when using Tcl9+.
- tclconfig:1e33e4d4f5736d63: Do we need to add extra build flags on Windows?
3rd-party Extensions to attempt to port...
- TclTLS. Even if it can't be ported, there is much to learn from that tree's use of TEA.

License

2025 April 5

The author disclaims copyright to this source code. In place of a legal notice, here is a blessing:

May you do good and not evil.
May you find forgiveness for yourself and forgive others.
May you share freely, never taking more than you give.

^{^} Admittedly somewhat to my surprise. However, installing an extension on Haiku requires a workaround documented in ./doc/extensions.md#install.
^{^} "autoconf" is currently a misnomer - SQLite's so-called autoconf build is, since version 3.49.0, driven by Autosetup but the name autoconf is retained to avoid breaking countless amounts of documentation and downstream build/packaging automation. The autoconf/tea directory is driven by autoconf/automake, but the whole point of this project is to "fix that" ;).

TEA(ish): a TEA-like Build System for Tcl Extensions