• Intro
  • Current Status
  • Platform Portability
  • Download
  • Cloning this Repository
• Authoring, Building, and Testing Extensions
• Source Tree Structure
• TODOs
• License

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.

Teaish's only scope is the build process of an extension. It in no way affects the source code of an extension. Any given extension can be hosted by both TEA and Teaish.

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 target 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 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. It can either include a full copy of itself with the extension, making it self-contained, or use a single copy of teaish for multiple extensions.

• 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 extension up for distribution, optionally with or without an included copy of teaish.

• Builds much more quickly than extensions built 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+. Teaish itself, being based on Autosetup, works with JimTcl, but Tcl extensions of course require a canonical Tcl.

• Supports script-only extensions in "pkgIndex" or "tcl::tm" flavors.

• 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/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

The directories are as follows:

• doc: holds the main docs.
• teaish: the "home directory" of this project's sources. This is where the configure script lives and is intended to be usable as-is as the home directory of a single arbitrary extension.
• 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."
• teaish/autosetup/teaish/*.tcl contain the main teaish code.
• teaish/autosetup/teaish/feature/*.tcl is home to larger-scale and/or niche feature tests.
• teaish/examples: is home to several test/demo extensions.

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/autosetup/teaish/feature.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 ;).

• 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?

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.

1. ^{^} Admittedly somewhat to my surprise.