The '''Tcl Extension Architecture''', or '''[TEA]''', by [John Ousterhout] and
others, is a set of guidelines and techniques for the distribution,
configuration, compilation, and installation of Tcl extensions. TEA alsoprovides a set of utilities that operate accordingly. Many Tcl extensions
leverage the TEA utilities, which
are designed to be easily customizable, and Many Tcl extensions use them.
** Attributes **
last release version: 3.9
release time: 2010-08-17
** See Also **
[https://core.tcl-lang.org/sampleextension/raw/tea.pdf%|%Tcl Extension Architecture Developer’s Guide — DRAFT]:
[Tcl Extension: Developer Guide%|%Tcl extension developer guide%|%]:
[tclconfig]:
[SampleExtension]:
[http://core.tcl.tk/tcl/tktview/1703170fffffffffffff%|%TEA_INIT does exact version matching], 2007-04-18: Details about the design and operation of `TEA_INIT()`.
[https://chiselapp.com/user/stwo/repository/spotoconf/index%|%Spot o' Conf]: Lightweight TEA-inspired configuration framework that caters to Tcl and Jim extensions
** Documentation **
[http://www.tcl.tk/doc/tea/tea_tcl2k.pdf%|%The Tcl Extension Architecture], [Brent Welch] and Michael Thomas, 1999: The current implementation of the TEA utilities updates and obsoletes some of this documentation.
[TIP] [https://core.tcl.tk/tips/doc/trunk/tip/34.md%|%34: Modernize TEA Build System]:
[TIP] [https://core.tcl.tk/tips/doc/trunk/tip/78.md%|%78: TEA 2.0 Definitions]:
[TEA: a summary of trying to use it, Vince Darley]:
[Annotated 10 steps to success with TEA], by [Vince Darley]: Reveals some frequently made mistakes in trying to build extensions for the first time on Windows.
[Converting your Tcl extension to TEA2]:
[https://fossil.sowaswie.de/teapuretcl/index%|%teapuretcl]: TEA for pure Tcl packages
** Description **
[TEA] is largely defined by the `tcl.m4` file in [tclconfig], along with the
`configure.in` and `Makefile` files in the [SampleExtension%|%sample
extension]. A `makefile.vc` and `rules.vc` file is also included for
[Microsoft Windows%|%Windows] builds. TEA describes a directory layout both
for the source distribution and for files installed as part of the extension.
Files in the source distribution of an extension are laid out such that
platform-specific components live in a directory dedicated to that platform.
The version of TEA is defined by the `TEA_VERSION` variable in the `tcl.m4`
file in [tclconfig].
TEA is generally used with the standard approach to building software for a
given platform. For example, on Unix systems, the standard way to build a
TEA-conforming extension is
======
./configure
make
make test
make install
======
. Developers for non-Unix operating systems and other build systems could
contribute to the [SampleExtension%|%sample extension] files and utilties
supporting their chosen platform.
TEA remains neutral on exact details of loading extensions, but in general, an
extension is loaded via the appropriate `[package require]` invocation, which
in turn employs some combination of `[load]` and `[source]`.
TEA offers a set of guidelines and aspires to become a reference for best
practices, but there is room for improvement and, indeed, alternatives.
** Versions **
[TEA3]: beta
[TEA2]: (aka TEA2002) simplified the original TEA configuration files and added features.
** Tools **
[Critcl]3: has a "generate TEA package" feature
** A Small Subset of Extensions Using TEA **
[Duft]:
[itcl]/[itk]:
[TclX]:
[Tktable]:
[Thread]:
[VUW widgets]:
Versions for Mac, [Unix], and [Windows] are available.
Especially for the former of these, see [Jim Ingham]'s comments in
...
** Compiling a TEA Extension **
[MSW] says: TEA doesn't pay attention to ''prefix''. If you specify
"--prefix=something" TEA still insists on "exec-prefix" being the directory
where tcl was found. '''THIS SUCKS'''. As a simple example, ''configure''
anything with a ''--prefix'' of ''something'', it'll try to install into
''/usr/local/tcl/'' or wherever tcl is found. Have you people not ever tried
installing something as non-root???? TEA-based Makefiles thus mean breaking any
locality of installed extensions. Welcome to the great wonderful world of
tomorrow.
[DGP]: So, the complaint is that ''--prefix='' and ''--exec-prefix=''
options must both be provided? It's a sensible complaint. Register it as
either a bug or feature request.
[PYK]: This is reported in [https://core.tcl-lang.org/tcl/info/1777301%|%Tcl Bug 1777301%|%]
[LV]: I've found that, at least at times, the sample, Tcl, and Tk distributed packages do the prefix/exec_prefix correctly. The way these are supposed to work
are that man pages, tcl scripts, script demos, etc. go under prefix while binary libraries and binary .exe (a.out) commands would be installed under exec_prefix. AND, when configure goes looking for things, it should use exec_prefix and prefix as the first locations to look for the various things it needs.
Not every use of TEA gets these things right, it seems.
Another tip - if you hard code path names (with versions in them ) into
configure, make certain these are updated each time a new version of tcl comes out.
** C++ Extensions with TEA, [MAK] 2004-11-09 **
I was going to submit this as a patch, but I don't have a complete and
necessarily correct solution, it turns out. More on that in a moment. The
template files and tests provided by TEA assume C-only extensions. A few quick
and simple changes can put you on your way to using TEA for C++ extensions.
First, in tcl.m4, find "AC_PROG_CC" in the TEA_SETUP_COMPILER_CC function, and
add another line that says "AC_PROG_CXX" and then run autoconf to regenerate
configure from configure.in. This adds the necessary tests to determine how to
run the C++ compiler, whether it be called "g++" or "CC" or whatever.
======none
AC_DEFUN(TEA_SETUP_COMPILER_CC, [
...
AC_PROG_CC
AC_PROG_CXX
AC_PROG_CPP
...
])
======
Second, in Makefile.in, find the CC definition and add a CXX definition. The
configure script will replace @CXX@ the way it does @CC@ so you can use $(CXX)
to refer to the C++ compiler rather than the $(CC) for the C compiler.
======none
...
PACKAGE_VERSION = @PACKAGE_VERSION@
CC = @CC@
CXX = @CXX@
CFLAGS_DEFAULT = @CFLAGS_DEFAULT@
...
======
Third, find the definition of the variable COMPILE and remove the $(CC) at the
start of it:
======
#COMPILE = $(CC) $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
COMPILE = $(DEFS) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
======
Fourth, you'll need to add the $(CC) into the .c.o rule, and add a .cpp.o rule
to call the appropriate compiler for .cpp files:
======none
.c.@OBJEXT@:
$(CC) $(COMPILE) -c `@CYGPATH@ $<` -o $@
.cpp.@OBJEXT@:
$(CXX) $(COMPILE) -c `@CYGPATH@ $<` -o $@
======
That's pretty much it, other than wrapping your extension's Init function in
extern "C" {...} to prevent mangling so Tcl's load command can find it. (You
don't need to wrap other functions, such as command functions, since they're
provided to Tcl via pointers rather than Tcl needing to search the symbol table
for them.)
Now, the problem: later versions of gcc can't link C++ objects because it will
try to use the wrong runtime library, and you'll get a number of unknown symbol
errors (on new/delete and gxx_personality_v0 etc.) Unfortunately the command
used for linking (assigned to the SHLIB_LD variable in the Makefile) either
comes from tclConfig.sh, or else is re-determined (either way it looks the same
to me), but either way it specifies the plain C compiler as the linker. You
can get around the problem by linking to the C++ runtime library, for instance
by adding "-lstdc++" to TEA_ADD_LIBS in your configure.in script, but I suspect
this is GNU-specific, and thus is probably not a good to codify in the sample
extension. The way TEA determines how to link shared libraries could stand a
little improvement in this regard. Maybe someone more familiar with autoconf
and m4 than I (who's not particularly familiar with either) can take the above
information, figure out what to do about SHLIB_LD and make C++ extensions
directly supported by TEA.
** Generating Source Files **
[PYK] 2017-06-27: The following steps allowed for the generation of `.c` files
in a recent TEA project:
1. In tclconfig/tcl.m4, neuter the file existence checks for `TEA_ADD_SOURCES` and `TEA_ADD_HEADERS`
1. include the relative directory name to .c files added to TEA_ADD_SOURCES and TEA_ADD_HEADERS in autoconf.ac
1. in Makefile.in, make PKG_LIB_FILE dependant on PKG_SOURCES and PKG_HEADERS
1. add a %.c %.h target to do the generation
** The History of TEA **
On 1999-03-15, [Scriptics] hosted the
[http://www.tcl.tk/doc/tea/tea-summit-99.html%|%Tcl Extension Architecture
(TEA) Summit] in Mountain View, CA.
** Discussion **
[Lars H] 2004-11-06: I've been told that TEA is a close relative (further
development of?) some [GNU] build system. Could someone provide links to
introductory material on that? It is my impression that the TEA docs are
written with the assumption that the developer already has some knowledge of
some similar system, so maybe there are some non-TEA-specific docs out there
that explains the basics...''
[MAK] 2004-11-09: Not exactly a relative, but rather TEA uses GNU
[autoconf]-generated configure scripts (i.e., rather than a relative, it is
based on the GNU build systems). It provides a template configure.in (the
input to [autoconf]) and Makefile.in (which the configure script uses to
generate Makefile), and and some other support files such as tcl.m4, which
defines the Tcl-specific tests done by the configure script. It also defines
the common "generic/unix/win/mac" layout you see in extensions.
For the most part, unless you need to write additional tests (e.g. determining
if certain headers are present, whether or not the platform supports a
particular function, etc.) the template files are pretty much "fill in the
blanks" (or otherwise "replace the name 'sample' with your extension's name")
and you don't have to worry about the nastiness of [m4].
----
[Sean McKnight] posted the following information on his experiences:
I posted a similar question about a month ago and got some pointers
to the Minimal GNU Windows 32 environment (i.e. mingw32) from some
Tcl programmers. Check out the mingw32 site for some good explanations
as to how Windows DLLs work. Essentially, all I wanted to do was
to create a DLL out of some basic C code that made some calls to the
Tcl/Tk libraries.
Note that in the instructions that follow I do not make use of the
TEA specification but instead just use a single Makefile. I would
have liked to stay with the TEA spec (and may do so eventually)
but from my experience I have found that the TEA is somewhat
incomplete at this point. I am hoping that will change at some
point in future (I wonder if anyone in the Tcl core group would
know what the plans for the TEA are at this point?).
So here is what eventually worked:
1). I downloaded the "mingw32" environment for Windows and installed
under WindowsNT 4.0 (also under Windows95). I also downloaded
the "impdef" utility, which is used (explained below) to generate
an "export list" of functions that can be called directly from
the DLL. These can be found on the mingw32 site at
http://www.mingw32.org.
2). My Tcl/Tk extension makes use of the Tcl C library. Under Windows,
I am required to link with an import library when creating my
extension DLL. The import library is created as follows:
C:\TCL832\BIN> impdef tcl83.dll > tcl83.def
C:\TCL832\BIN> impdef tk83.dll > tk83.def
C:\TCL832\BIN> dlltool --dllname tcl83.dll --def tcl83.def \
--output-lib libtcl83.a
C:\TCL832\BIN> dlltool --dllname tk83.dll --def tk83.def \
--output-lib libtk83.a
3). An export list for my Tcl extension also had to be created. Normally
only the "Init" function from the extension is exported, as it
is the entry point for the extension when the extension is loaded
into Tcl. All I did to create the export list was echo a couple
of lines into a text file:
C:\MYEXT> echo EXPORTS > myext.def
C:\MYEXT> echo Myext_Init >> myext.def
4). Each C source file in my extension is compiled using the "gcc"
compiler from the "mingw32" installation. After all the objects
are compiled, the final DLL is constructed. A snippet of the
makefile is presented below:
CC = gcc
OBJS = myext1.o myext2.o myext3.o
DLLTOOL = dlltool
TCLLIBS = c:/tcl832/lib/libtcl83.a c:/tcl832/lib/libtk83.a
RM = del
dll: $(OBJS)
$(CC) -mdll -o junk.tmp -Wl,--base-file,base.tmp $(OBJS) $(TCLLIBS)
$(RM) junk.tmp
$(DLLTOOL) --dllname myext.dll --base-file base.tmp --output-exp temp.exp --def myext.def
$(RM) base.tmp
$(CC) -mdll -o myext.dll $(OBJS) $(TCLLIBS) -Wl,temp.exp
$(RM) temp.exp
It seems to work, both under NT and 95 (at least for the extension that
was tested, which is pretty basic).
The main challenge is understanding the requirements for constructing
a DLL. Check the "[mingw32]" site documentation for the dirty details.
Sean
----
[tclguy] writes that, "If you have a TEA-based Makefile,
with all the latest targets up-to-date, then
[[to launch [gdb] usefully]] you should only need to do 'make gdb'.
This will launch tclsh into gdb with the right environment that
should allow you to say 'package require Receive' and get your
debugging version."
----
Vince rants: Unfortunately 'TEA' is relatively fragile and difficult and generally hopeless to use,
''unless'' you are a [unix]-based and unix-expert developer. On [Windows] it also contains numerous bugs, has no decent documentation (again unless of course you've been doing this stuff for years on unix when it is all second nature), and somehow, to compile a single [C] file, requires one to create/modify/copy about 10 supporting files. Of course, when it works it is great, but it rarely, if ever, works for non-unix developers. Furthermore since every extension needs its own 10 supporting files, it is not practical for unix-savvy-developers to fix problems for every single extension. Altogether TEA is an embarrassment to Tcl's cross-platform claims.
[stevel]: Does this still apply with the recent TEA 2002 effort from [Jeffrey Hobbs]?
Vince: that's a good question, and it also points to a fundamental flaw in TEA. What Jeff did was update the 'sampleextension', but that has no impact at all on the many extensions which used TEA before (i.e. copied/modified the files from the old sampleextension as instructed by TEA). Therefore all those extensions need fixing (Jeff may have done some of this as well, but certainly not to any extension I looked at). And they will all need fixing again any time another fix is made to TEA. So, I can't answer your question properly. I've wasted days of my life on TEA and refuse to do so any more (and, as you can see, I feel quite strongly that TEA is a waste of everyone's time). Just yesterday I tried to compile tclpro on Windows, from the cvs head, and even 'autoconf' failed with an error, which is rather pathetic.
''[JCW] barges in...'': - I've recently suggested one way in which this could be improved IMO. Instead of asking people to copy the sample, fight it, and then struggle ever after, why not generate things? So one would have one or more source files, then a Tcl script produces as much litter as it likes <wink> - with as end result that one generates, then does configure/make as before. I absolutely agree that copying boilerplate which is tricky and of a substantial size makes no sense and is a huge time waster (I'll confess that I never bought into TEA either...).
''Vince...'' that sounds like a very good idea for something to go in [tcllib].
We could even call the new module 'tea' ''grin''.
Yet another rant about TEA - and yet, where is the better mousetrap to cause all of Tcl development to begin beating a path.
----
'''[jlinkels] - 2022-05-01 14:26:04'''
I have found the TEA.PDF document here: https://wiki.tcl-lang.org/page/TEA. It is incomplete and dated back to 2000.
There seems to be still some activity going on, the last changes committed Januari 2022. Is there an updated version of the document? Is TEA still something which is being recommended?
Heck, is ''anyone'' still using TCL?
----
'''[aplsimple] - 2022-05-02 10:05:30'''
no heck for '''anyone'''
https://sourceforge.net/projects/tcl/
<<categories>> Glossary | Package | Porting