The Tcl Extension Architecture

Brent Welch <[email protected]>

Michael Thomas <[email protected]>
Scriptics Corporation

Abstract • Recommended Source Directory Struc-

ture:
This paper describes goals and current state of the
• Standard Installation Directory Structure.
Tcl Extension Architecture (TEA). The goal of
TEA is to create a standard for Tcl extensions that • Stubs Libraries.
makes it easier to build, install, and share Tcl • Autoconf and Configure .
extensions. In its current form, TEA specifies a • Standard Make Targets.
standard compilation environment for Tcl and its • A Sample TEA-Compliant Extension.
extensions. The standard uses autoconf, config- • Future Plans.
ure and make on UNIX and Windows. A longer
term goal is to create an infrastructure that supports
network distribution and installation of Tcl exten- Standard Directory Structure
sions. A standard build environment is a necessary
first step to support automated compilation and dis- One goal of TEA is to make the process of config-
tribution of extensions. This paper describes the uring and building a Tcl extension very similar to
current state of TEA, but we expect to continue to building Tcl itself. In addition, building a Tcl
refine the standard and add to it as we gain experi- extension depends on having access to the Tcl
ence with it. source distribution. You must configure and build
Tcl before you build your extensions. The best way
to organize your source code is to have Tcl and all
Introduction your extensions under a common directory (e.g.,
/usr/local/src or /home/welch/cvs). This way
Compiling Tcl from the source distribution is easy. the build process for an extension can automati-
One of the strengths of Tcl is that it is quite porta- cally find the Tcl sources. The dependency on the
ble and so it has been built on all kinds of systems Tcl source distribution is described later, and in the
including Unix, Windows, Macintosh, AS/400, long term we hope to support building TEA-com-
IBM mainframes, and embedded systems. How- pliant extensions against a binary distribution of
ever, it can be a challenge to create a Tcl extension Tcl.
that has the same portability. The Tcl Extension
Architecture (TEA) provides guidelines and sam-
ples to help extension authors create portable Tcl The Source Distribution
extensions. The TEA is a result of collaboration
Table 1 describes the directory structure of the Tcl
within the Tcl user community, and it will continue
source distribution. The Tk distribution is similar.
to evolve. TEA covers the following topics, which
The directory structure divides the sources into
are described in more detail in the paper:
generic and platform-specific directories.
 Table 1 The Tcl source directory structure.
tcl8.2 The root of the Tcl sources. This contains a README and
license_terms file, and several subdirectories.
tcl8.2/compat This contains .c files that implement procedures that are other-
wise broken in the standard C library on some platforms. They
are only used if necessary.
tcl8.2/doc This contains the reference documentation. Currently this is in
nroff format suitable for use with the UNIX man program. The
goal is to convert this to XML.
tcl8.2/generic This contains the generic .c and .h source files that are shared
among Unix, Windows, and Macintosh.
tcl8.2/mac This contains the .c and .h source files that are specific to
Macintosh. It also contains Code Warrior project files.
tcl8.2/library This contains init.tcl and other Tcl files in the standard Tcl
script library.
tcl8.2/library/encoding This contains the Unicode conversion tables.
tcl8.2/library/package There are several subdirectories (e.g., http2.0) that contain Tcl
script packages.
tcl8.2/test This contains the Tcl test suite. These are Tcl scripts that exer-
cise the Tcl implementation.
tcl8.2/tools This is a collection of scripts used to help build the Tcl distribu-
tion.
tcl8.2/unix This contains the .c and .h source files that are specific to
UNIX. This also contains the configure script and the Make-
file.in template.
tcl8.2/unix/dltest This contains test files for dynamic loading.
tcl8.2/unix/platform These can be used to build Tcl for several different platforms.
You create the platform directories yourself.
tcl8.2/win This contains the .c and .h source files that are specific to Win-
dows. This also contains the configure script and the Make-
file.in template. This may contain a makefile.vc that is
compatible with nmake.
tcl8.2/win/Build Build is Release or Debug. This contains compiler output.

The Installation Directory ming libraries (i.e., DLLs) are in platform-specific

Structure directories. You can choose where these two groups
of files are installed with the --prefix and --exec-
When you install Tcl, the files end up in a different prefix options to configure. The --prefix option
arrangement than the one in the source distribution. specifies the root of the installation directory (e.g.,
The standard installation directory is organized so it /usr/local). The --exec-prefix option specifies a
can be shared by computers with different machine platform-specific directory (e.g., /usr/local/solaris-
types (e.g., Windows, Linux, and Solaris). The Tcl sparc) for applications and programming libraries.
scripts, include files, and documentation are all in Table 2 shows the standard installation directory
shared directories. The applications and program- structure:
 Table 2 The installation directory structure relative to the --prefix directory.
exec_prefix/bin This contains platform-specific applications. On Windows, this also con-
tains binary libraries (i.e., DLLs). Typical exec_prefix names end with
solaris-sparc, linux-ix86, and win-ix86 .
exec_prefix/lib This contains platform-specific binary libraries on UNIX systems (e.g.,
libtcl8.2.so)
exec_prefix/lib/ Contains pkgIndex.tcl files corresponding to binary libraries from pack-
package age that are found in exec_prefix/lib.
bin This contains platform-independent applications (e.g., Tcl script applica-
tions).
doc This contains documentation.
include This contains public .h files
lib This contains subdirectories for platform-independent script packages.
Packages stored here are found automatically by the Tcl auto loading
mechanism.
lib/tcl8.2 This contains the contents of the tcl8.2/library source directory,
including subdirectories.
lib/package This contains Tcl scripts for package and its pkgIndex.tcl file. Example
package directories include tk8.2 and itcl3.0.1.
man This contains reference documentation in UNIX man format.

The Package Mechanism shows a few sample package ifneeded scripts to

handle different configurations of packages.
Extensions are installed and used as packages. A
package can be one Tcl script, a collection of Tcl
scripts, a binary library, or some combination of Binary Library
scripts and libraries. When you install an extension
A binary library (i.e., DLL) goes into the platform-
you need to update the package registry so that oth-
specific lib directory. For example, you install your
ers can find the extension with package require.
DLL into exec_prefix/lib/libfoobar1.0.so and you
This section describes the default package manage-
create a package index file in
ment system, which uses a collection of pkgIn-
exec_prefix/lib/foobar1.0/pkgIndex.tcl, which con-
dex.tcl files in directories along your auto_path.
tains this code:
The package registry is implemented by a collection package ifneeded foobar 1.0 [list load \
of pkgIndex.tcl files. Tcl searches the directories [file join $dir .. \
listed in its auto_path variable for pkgIndex.tcl libfoobar1.0[info sharedlibextension]]\
files. It also searches down one directory, so you Foobar]
can put your extensions and pkgIndex.tcl files into Collecting all the binary libraries in one directory
subdirectories of the main directories listed on makes it easy to resolve dependencies among them
auto_path. The default auto_path is and third-party libraries that support your Tcl exten-
sion. UNIX users may have to adjust their
prefix/lib/tclversion prefix/lib exec_prefix/lib
LD_LIBRARY_PATH to include the exec_prefix/lib
Each pkgIndex.tcl file has one or more package directory. On Windows, these files are actually in
ifneeded commands in it. These register Tcl com- the exec_prefix/bin directory, which is automati-
mands that are called whenever a particular package cally searched. Keeping the pkgIndex.tcl files in
is requested with package require. This section separate directories keeps them independent.
 Tcl Scripts Create a pkgIndex.tcl file in the
exec_prefix/lib/foobar1.0 subdirectory. You will
If your extension is just Tcl scripts, then it can be need to install a copy for each different platform
shared by users on different platforms. These librar- that you compile for (e.g., solaris-
ies are typically kept in a subdirectory of prefix/lib, sparc/lib/foobar1.0/pkgIndex.tcl and linux-
(e.g., /usr/local/lib/foobar1.0). You can use the ix86/lib/foobar1.0/pkgIndex.tcl.). This file loads
pkg_mkIndex Tcl command to generate a pkgIn- the binary library and sources the Tcl script. We
dex.tcl file for your scripts: assume that the scripts are installed relative to the
pkg_mkIndex -verbose prefix/lib *.tcl Tcl script library:
By default, pkg_mkIndex generates pkgIndex.tcl package ifneeded foobarArch 1.0 \
files that contain tclPkgSetup commands that use "[list load \
source or load indirectly. You might imagine that [file join $dir ../libfoobar1.0[info \
sharedlibextension] Foobar] \;
package require actually loads code, but by
[list source [file join [file dirname \
default is does not. Instead, the following tclPkg- $tcl_library] \
Setup command arranges for foobar.tcl to be foobar1.0/foobar.tcl]]"
sourced whenever the unknown command tries to This example assumes the standard directory struc-
find Foobar_Init, Foobar_DoSomething, or ture. It would be more general to search along the
Foobar_End .
auto_path for the foobar1.0 subdirectory and then
package ifneeded foobar 1.0 \
source its foobar.tcl file. If you have several script
[list tclPkgSetup $dir foobar 1.0 \
{{foobar.tcl source {Foobar_Init files, you can introduce a short procedure to source
Foobar_DoSomthing Foobar_End}}}] all of them. Or, you can have two pkgIndex.tcl files
The tclPkgSetup command is complex, so you and require that your users require both (e.g., foobar
should use the pkg_mkIndex command to generate and foobarArch). The packages can also require
these commands for you. If you use pkg_mkindex - each other. For example:
package ifneeded foobarArch 1.0 \
direct, you can create a simpler package that is
"[list load \
sourced immediately in response to the package [file join $dir ../libfoobar1.0[info \
require command. This direct package index looks sharedlibextension] Foobar] \;
like this: [list package require foobar 1.0]"
package ifneeded foobar 1.0 \ Finally, by using the package unknown hook, you
[list source [file join $dir
foobar.tcl]]
could define and use an alternate package manager.
Newsgroup discussions have pointed out that
searching for all the pkgIndex.tcl files can be slow
Library and Script Combina- on some systems. An alternate package manager
tion could keep a more compact and efficient database,
and perhaps have smarts about downloading pack-
If you have both scripts and binary libraries, then
ages from standard TEA repositories.
you can split your package into two parts: the
shared part as Tcl scripts, and a platform-specific
part as a binary library. The tricky part is building Autoconf, Configure and Make
your pkgIndex.tcl file correctly. There are two prob-
lems. First, you can only have one package In the past, UNIX, Windows, and Macintosh have
ifneeded command for a single package, so you different compilation environments. The advent of
need to specify something about the scripts and the the free Cygwin tools have made it possible to
library in one command. Next, you cannot predict standardize on autoconf, configure and make for
the location of both parts of the package, so you the UNIX and Windows compilation environ-
have to assume they are installed in a standard loca- ments. The Macintosh still uses Code Warrior
tion relative to the auto_path. Our preferred solu- project files, however. On Windows we use make,
tion is modeled after the one in the SNACK sound sh, and autoconf from Cygwin, and the cl
extension by Kåre Sjölander. (VC++) compiler from Microsoft.
The autoconf system is used to create Makefiles developer also creates a Makefile.in tem-
that have settings appropriate for the current operat- plate. Creating these templates is described
ing system. By using autoconf, a developer on later. The Tcl and Tk source distributions
Windows or Linux can generate a configure script already contain the configure script, which
that is usable by other developers on Solaris, HP- can be found in the unix and win subdirecto-
UX, FreeBSD, AIX, or any system that is vaguely ries. However, if you get the Tcl sources from
UNIX-like. The configure script, in turn, is used to the network CVS repository, you must run
generate the working Makefile. The three steps:
autoconf yourself to generate the configure
setup, configuration and make, are illustrated by the
script.
build process for Tcl and Tk:
2. A user of a source code package runs con-
1. The developer of a source code package cre- figure on the computer system they will use

ates a configure.in template that expresses to compile the sources. The configure script
the system dependencies of the source code. examines the current system and makes vari-
They use the autoconf program to process ous settings that are used during compilation.
this template into a configure script. The

Table 3 Standard configure flags.

--prefix=dir This defines the root of the installation directory hierarchy. The
default is /usr/local.
--exec-prefix=dir This defines the root of the installation area for platform-spe-
cific files. This defaults to the --prefix value. An example set-
ting is /usr/local/solaris-sparc.
--enable-gcc Use the gcc compiler instead of the default system compiler.
--disable-shared Disable generation of shared libraries and Tcl shells that
dynamically link against them. Statically linked shells and static
archives are built instead.
--enable-symbols Compile with debugging symbols.
--enable-threads Compile with thread support turned on.
--with-tcl=dir This specifies the location of the build directory for Tcl.
--with-tk=dir This specifies the location of the build directory for Tk.
--with-tclinclude=dir This specifics the directory that contains tcl.h.
--with-tcllib=dir This specifies the directory that contains the Tcl binary library
(e.g., libtclstubs.a). (Note: this option is not yet supported.)
--with-x-includes=dir This specifics the directory that contains X11.h.
--with-x-libraries=dir This specifies the directory that contains the X11 binary library
(e.g., libX11.6.0.so).

3. When you run configure, you make some basic choices about how you will compile Tcl, such as
whether you will compile with debugging systems, or whether you will turn on threading support.
You also define the Tcl installation directory with configure. This step converts Makefile.in to a
Makefile suitable for the platform and configuration settings. .
 4. Once configure is complete, you build your Any flag with disable or enable in its name can be
program with make. This steps checks your inverted. Table 3 lists the non-default setting, how-
source files against the compiled files and ever, so you can just leave the flag out to turn it off.
reruns the compiler on any files that have For example, when building Tcl on Solaris with the
changed since the last compilation. The gcc compiler, shared libraries, debugging symbols,
and threading support turned on, use this command:
results are binary libraries for extensions and
configure --prefix=/home/welch/install \
executable programs for applications. Make is --exec-pre-
used for testing and installation, too. Table 5 fix=/home/welch/install/solaris \
on page 8 shows the standard make targets. --enable-gcc --enable-threads --
enable-symbols
Your builds will go the most smoothly if you orga-
Standard configure Flags nize all your sources under a common directory. In
this case, you should be able to specify the same
Table 3 shows the standard options for Tcl config- configure flags for Tcl and all the other extensions
ure scripts. These are implemented by a configure
you will compile. In particular, you must use the
library file (tcl.m4) that you can use in your own same --prefix and --exec-prefix so everything
configure scripts. The facilities provided by
gets installed together.
tcl.m4 are described in more detail later. There are
also many other command line options that come If you use alternate build directories, like the
standard with configure. Some of these are meant unix/solaris example above, you must specify --
to give you control over where the different parts of with-tcl when building your extensions. This is
the installation go. However, because of the way Tcl the directory where the Tcl build occurred. It con-
automatically searches for scripts and binary librar- tains libraries and a tclConfig.sh file that is used by
ies, you can mess up the Tcl installation by install- the extensions configure process.
ing the libraries and the binaries in wildly different If your source tree is not adjacent to the Tcl source
locations. Because of this, the Tcl installation pro- tree, then you must use --with-tclinclude or --
cedures in the standard Makefile do not support the with-tcllib so the header files and runtime library
--libdir and --bindir options. In general, if the can be found during compilation. Typically this can
flags are not listed in Table 3, then they are not guar- happen if you build an extension under your home
anteed to be supported by the standard Makefile directory, but you are using a copy of Tcl that has
template. been installed by your system administrator. The --
with-x-includes and --with-x-libraries flags
are similar options necessary when building Tk if
Examples your X11 installation is in a non-standard location.
If you only have one platform, simply run config-
ure in the unix (or win) directory:
Finding a working compiler
% cd /usr/local/src/tcl8.2/unix
% ./configure flags As the configure script executes, it prints out mes-
Use ./configure to ensure you run the configure sages about the properties of the current platform.
script from the current directory. If you build for You can tell if you are in trouble if the output con-
multiple platforms, create subdirectories of unix tains either of these messages:
and run configure from there. You are free to cre- checking for cross compiler ... yes
ate the compilation directory anywhere (some pre- or
fer to keep all the generated files away from the checking if compiler works ... no
sources.) Here we just use a subdirectory of the unix Either of these means configure has failed to find
directory: a working compiler. In the first case, it assumes you
% cd /usr/local/src/tcl8.2/unix are configuring on the target system but will cross-
% mkdir solaris
% cd solaris
compile from a different system. Configure pro-
% ../configure flags ceeds bravely ahead, but the resulting Makefile is
useless. While cross-compiling is common on library will be installed in:
embedded processors, it is rarely necessary on /home/welch/install/bin/tclsh8.2
UNIX and Windows. The cross-compiling message /home/welch/install/lib/libtclsh8.2.so
typically occurs when your UNIX environment The script libraries and manual pages will be
isn’t set up right to find the compiler. installed in:
/home/welch/install/lib/tcl8.2/
On Windows there is a more explicit compiler
/home/welch/install/man/
check, and configure exits if it cannot find the
compiler. Currently, the Windows configure macros If you want to have installations for several differ-
knows only about the Visual C++ compiler. VC++ ent platforms, then specify an --exec-prefix that
ships with a batch file, vcvars32.bat, that sets up is different for each platform. For example, if you
the environment so you can run the compiler, cl, use --exec-pre-
fix=/home/welch/install/solaris, then the
from the command line. You must run
tclsh8.2 program and libtcl8.2.so shared
vcvars32.bat before running configure, or set up
your environment so you do not have to remember library will be installed in:
/home/welch/install/solaris/bin/tclsh8.2
to run the batch file all the time.
/home/welch/install/solaris/lib/libtclsh8
.2.so

Installation Directories The script libraries and manual pages will remain
where they are, so they are shared by all platforms.
The --prefix flag specifies the main installation Note that Windows has a slightly different installa-
directory (e.g., /home/welch/install). The direc- tion location for binary libraries (i.e., DLLs). They
tories listed in Table 2 are created under this direc- go into the exec_prefix/bin directory along with
tory. If you do not specify --exec-prefix, then the the main executable programs.:
platform-specific binary files are mixed into the
main bin and lib directories. For example, the
tclsh8.2 program and libtcl8.2.so shared

Table 4 Standard autoconf macros defined by tcl.m4.

SC_PATH_TCLCONFIG Locate the tclConfig.sh file and sanity check the compiler
flags. This implements the --with-tcl option.
SC_PATH_TKCONFIG Locate the tkConfig.sh file. This implements --with-tk.
SC_LOAD_TCLCONFIG Load the tclConfig.sh file.
SC_LOAD_TKCONFIG Load the tkConfig.sh file.
SC_ENABLE_GCC Implements the --enable-gcc option.
SC_ENABLE_SHARED Implements the --enable-shared option.
SC_ENABLE_THREADS Implements the --enable-threads option.
SC_ENABLE_SYMBOLS Implements the --enable-symbols option.
SC_MAKE_LIB Generates definitions used to make shared or unshared libraries
on various platforms.
SC_LIB_SPEC Generates the name of a library and appropriate linker flags
needed to link it.
SC_PRIVATE_TCL_HEADERS Use this if you need to include tclInt.h
SC_PUBLIC_TCL_HEADERS Locate the standard Tcl include files.
Using autoconf and the tcl.m4 File tclConfig.sh, and some of the tcl.m4 macros
depend on it. We plan to restructure the macros fur-
Autoconf uses the m4 macro processor to translate ther so tclConfig.sh (and tkConfig.sh) will no
the configure.in template into the configure longer be needed. So, instead of using
script. Creating the configure.in template is sim- SC_LOAD_TCLCONFIG, extensions will use a new
plified by a standard m4 macro library that is dis- macro that computes compiler settings.
tributed with autoconf. In addition, a Tcl
Table 4 lists the public macros defined in the
distribution contains a tcl.m4 file that has addi-
tcl.m4 file. The tcl.m4 file defines macros whose
tional autoconf macros. Among other things,
names begin with SC_ (for Scriptics). The four
these macros support the standard configure flags
TCLCONFIG and TK_CONFIG macros listed in Table 4
described in Table 3.
will be eventually be replaced. There are other mac-
ros defined, but the following are the only ones
The goal of tcl.m4 is to simply the configure.in guaranteed to persistStandard Make Targets
templates used for extensions and to replace the use The sample Makefile includes several standard tar-
of the tclConfig.sh and tkConfig.sh files. The gets. Even if you decide not to use the sample
idea of tclConfig.sh was to capture some impor- Makefile.in template, you should still define the
tant results of Tcl’s configure so they could be targets listed in Table 5 to ensure your extension is
included in the configure scripts used by an exten- TEA compliant. Plans for automatic build environ-
sion. However, it is better to recompute these set- ments depend on every extension implementing the
tings when configuring an extension because, for standard make targets. The targets can be empty,
example, different compilers could be used to build but you should define them so that make will not
Tcl and the extension. At present Tcl still generates complain if they are used.

Table 5 TEA standard Makefile targets.

all Makes these targets in order: binaries, libraries, doc.
binaries Makes executable programs and binary libraries (e.g., DLLs).
libraries Makes platform-independent libraries.
doc Generates documentation files.
install Makes these targets in order: all, install-binaries, install-
libraries, install-doc.
install-binaries Makes binaries, and installs programs and binary libraries.
install-libraries Makes libraries, and installs script libraries.
install-doc Makes doc, and installs documentation files.
test Runs the test suite for the package.
depend Generates makefile dependency rules.
clean Removes files built during the make process.
distclean Makes clean, and removes files built during the configure process.
Using Stub Libraries The Sample Extension
One problem with extensions is that they get com- This section describes the sample extension that is
piled for a particular version of Tcl. As new Tcl distributed as part of TEA. The sample extension
releases occur, you find yourself having to recom- implements the Secure Hash Algorithm (SHA1).
pile extensions. This was necessary for two rea- Steve Reid wrote the original SHA1 C code, and
sons. First, the Tcl C library tended to changes its Dave Dykstra wrote the original Tcl interface to it.
APIs from release to release. Changes in its symbol Michael Thomas created the standard configure
table tie a compiled extension to a specific version and Makefile templates.
of the Tcl library. Another problem occurred if you The goal of the sample extension is to provide a
compiled tclsh statically, and then tried to dynam- TEA-compliant example that is easy to read and
ically load a library. Some systems do not support modify for your own extension. Instead of using the
back linking in this situation, so tclsh would original name, sha1, the example uses a more
crash. Paul Duffin created a stub library mecha- generic name, exampleA, in its files, libraries, and
nism for Tcl that helps solve these problems. package names. When editing the sample templates
The main idea is that Tcl creates two binary librar- for your own extension, you can simply replace
ies: the main library (e.g., libtcl8.2.so) and a occurrences of "exampleA" with the appropriate
stub library (e.g., libtclstub.a). All the code is in name for your extension. The sample files are well
the main library. The stub library contains a big commented, so it is easy to see where you need to
jump table that has addresses of the functions in the make the changes.
main library. An extension calls Tcl through the
jump table. The level of indirection makes the
extension immune to changes in the Tcl library. It configure.in
also handles the back linking problem. If this The configure.in file is the template for the con-
sounds expensive, it turns out to be equivalent to figure script. This file is very well commented.
what the operating system does when you use The places you need to change are marked with
shared libraries (i.e., dynamic link libraries). Tcl has __CHANGE__. The first macro to change is:
just implemented dynamic linking in a portable, AC_INIT(exampleA.h)
robust way. The AC_INIT macro lists a file that is part of the dis-
To make your extension use stubs, you have to com- tribution. The name is relative to the configure.in
pile with the correct flags, and you have to add a file. Other possibilities include ../generic/tcl.h
new call to your extensions Init procedure (e.g., or src/mylib.h, depending on where the config-
Examplea_Init). The TCL_USE_STUBS compile- ure.in file is relative to your sources. The AC_INIT
time flag turns the Tcl C API calls into macros that macro is necessary to support building the package
use the stub table. The Tcl_InitStubs call ensures in different directories (e.g., either tcl8.2/unix or
that the jump table is initialized, so you must call tcl8.2/unix/solaris).
Tcl_InitStubs as the very first thing in your Init The next thing in configure.in is a set of variable
procedure. A typical call looks like this: assignments that define the package’s name and
if (Tcl_InitStubs(interp, "8.1", 0) == version number:
NULL) {
return TCL_ERROR; PACKAGE = exampleA
} MAJOR_VERSION = 0
MINOR_VERSION = 2
Tcl_InitStubs is similar in spirit to PATCH_LEVEL =
Tcl_PkgRequire in that you request a minimum Tcl
The package name determines the file names used
version number. Stubs have been supported since for the directory and the binary library file created
Tcl 8.1, and the Tcl C API will evolve in a back- by the Makefile. This name is also used in several
ward-compatible way. Unless your extension uses configure and Makefile variables. You will need
new C APIs introduced in later versions, you should to change all references to "exampleA" to match the
specify the lowest version possible so that it is com- name you choose for your package.
patible with more Tcl applications.
The version and patch level support a three-level You must define the set of source files and the cor-
scheme, but you can leave the patch level empty for responding object files that are part of the library. In
two-level versions like 0.2. If you do specify a the sample, exampleA.c implements the core of the
patch-level, you need to include a leading "." or "p" Secure Hash Algorithm, and the tclexampleA.c
in it. These values are combined to create the ver- file implements the Tcl command interface:
sion number like this: exampleA_SOURCES = exampleA.c tclexam-
VERSION = pleA.c
${MAJOR_VERSION}.${MINOR_VERSION}${PATCH_ SOURCES = $(exampleA_SOURCES)
LEVEL} The object file definitions use the OBJEXT variable
Windows compilers create a special case for shared that is .o for UNIX and .obj for Windows:
libraries (i.e., DLLs). When you compile the library exampleA_OBJECTS = exampleA.${OBJEXT}
itself, you need to declare its functions one way. tclexampleA.${OBJEXT}
OBJECTS = $(exampleA_OBJECTS)
When you compile code that uses the library, you
need to declare its functions another way. This com- The header files that you want to have installed are
plicates the exampleA.h header file. Happily, the assigned to the GENERIC_HDRS variable. The srcdir
complexity is hidden inside some macros. The stan- Make variable is defined during configure to be
dard configure.in defines a build_Package vari- the name of the directory containing the file named
able with the following line, which you do not need in the AC_INIT macro:
to change: GENERIC_HDRS = $(srcdir)/exampleA.h
AC_DEFINE_UNQUOTED(BUILD_${PACKAGE}) Unfortunately, you must specify explicit rules for
The build_packageA variable is only set when you each C source file. The VPATH mechanism is not
are building the library itself, and it is only defined reliable enough to find the correct source files reli-
when compiling on Windows. We will show later ably. The configure script uses AC_INIT to locate
how this is used in exampleA.h to control the defi- source files, and you create rules that use the result-
nition of the Examplea_Init procedure. ing $(srcdir) value. The rules look like this:
exampleA.$(OBJEXT) : $(srcdir)/exampleA.c
The configure.in file has a bunch of magic to $(COMPILE) -c ‘@CYGPATH@
determine the name of the shared library file (e.g., $(srcdir)/exampleA.c‘ -o $@
packageA02.dll , packageA.0.2.so, packa- The cygpath program converts file names to differ-
geA.0.2.shlib, etc.). All you need to do is change ent formats required by different tools on Windows.
one macro to match your package name. On UNIX, the CYGWIN macro is simply defined to
AC_SUBST(exampleA_LIB_FILE) echo.
These should be the only places you need to edit
when adapting the sample configure.in to your
extension. Standard Header Files
This section explains a technique you should use to
Makefile.in get symbols defined properly in your binary library.
The Makefile.in template is converted by the The issue is raised by Windows compilers, which
configure script into the Makefile. The sample
have a notion of explicitly importing and exporting
Makefile.in is well commented so that it is easy to
symbols. When you build a library you export sym-
see where to make changes. There are a few vari- bols. When you link against a library, you import
ables with exampleA in their name. In particular, symbols. The BUILD_exampleA variable is defined
exampleA_LIB_FILE corresponds to a variable
on Windows when you are building the library. This
name in the configure script. You need to change variable should be undefined on UNIX, which does
both files consistently. Some of the lines you need not have this issue. Your header file uses this vari-
to change are shown below: able like this:
#ifdef BUILD_exampleA
exampleA_LIB_FILE = @exampleA_LIB_FILE@
#undef TCL_STORAGE_CLASS
lib_BINARIES = $(exampleA_LIB_FILE)
#define TCL_STORAGE_CLASS DLLEXPORT
$(exampleA_LIB_FILE)_OBJECTS =
$(exampleA_OBJECTS) #endif
The TCL_STORAGE_CLASS variable is used in the start with a standard framework for configuring and
definition of the EXTERN macro. You must use building extensions.
EXTERN before the prototype for any function you
want to export from your library:
EXTERN int Examplea_Init Web Links
_ANSI_ARGS_((Tcl_Interp *Interp));
The _ANSI_ARGS_ macro is used to guard against The TEA home page is:
http://www.scriptics.com/tea/
old C compilers that do not tolerate function proto-
types. The sample extension can be found at the Scriptics
FTP site:
ftp://ftp.scriptics.com/pub/tcl/exam-
Using the Sample Extension ples/tea/
The on-line CVS repository for Tcl software is
You should be able to configure, compile and
explained here:
install the sample extension without modification.
http://www.scriptics.com/cvs/
On my Solaris machine it creates a binary library
named exampleA0.2.so, while on my Windows
NT machine the library is named exampleA02.dll. Acknowledgments
The package name is Tclsha1, and it implements
the sha1 Tcl command. Ordinarily these names We would like to thank the following people and
would be more consistent with the file names and organizations: Paul Duffin, Jan Nijtmans, Jean-
package names in the template files. However, the Claude Wippler, and Scott Stanton designed and
names in the sample are designed to be easy to edit implemented the stub library mechanism for Tcl.
in the template. Assuming you use make install to Steve Reid and Dave Dykstra wrote the Secure
copy the binary library into the standard location for Hash Algorithm and the Tcl interface to it. Unified
your site, you can use the package from Tcl like building procedures on all flavors of UNIX would
this: not be possible without the autoconf tools from the
package require Tclsha1 GNU project, and the Cygwin tools from Cygwin
sha1 -string "some string" extend this functionality to Windows.
The sha1 command returns a 128 bit encoded hash A different version of this paper will appear as a
function of the input string. There are a number of chapter in Brent Welch’s book, Practical Program-
options to sha1 you can learn about by reading the ming in Tcl and Tk, 3rd Edition, published by Pren-
man page that is part of the sample. tice Hall.

Future Directions
The short term goal of TEA is to provide a standard
way to build Tcl extensions. We have created a
sample extension for others to learn from, and we
have been converting the widely used [incr Tcl],
Expect, and TclX extensions to adhere to the stan-
dard.
The long term goal of TEA is to make distributing
and installing Tcl extensions easy for the end user.
We envision a system where open source extensions
can be hosted in a common CVS repository, built
automatically on a variety of platforms, and distrib-
uted to end users and installed automatically on
their system. For this goal to succeed, we need to