The TEA (Tcl Extension Architecture) build system is designed to provide consistency and compiler environment independence to Tcl extension creators and consumers.

This page was revamped on 2007-12-27 by JH. This document describes the step-by-step method to setting yourself up to use TEA. It is targeted primarily for Windows as that is the platform with the fewest default installed build tools, but TEA works consistently across all platforms.

TEA uses typical unix tools (configure, make) to provide consistency, but any compiler may be used (set CC environment variable to your preferred compiler if you have more than one).

Why not use Tcl to build Tcl extensions? Tcl would appear much better suited to the task, but autoconf's primary benefit is the wealth of cross-platform knowledge that would otherwise need to be replicated in Tcl.

Note that not all extensions make use of TEA, and there may be some which make some use but alter the process to the point of the build process varying from this description.

10 Steps to Success edit

1. Ensure you have the prerequisite tools: make, configure, autoconf, a C/C++ compiler

These are fairly standard tools on unix systems, but Windows users are best served with getting Msys (+ Mingw-gcc if you want a compiler).

      Msys + Mingw [http://www.mingw.org/download.shtml]
      http://prdownloads.sourceforge.net/tcl/msys_mingw8.zip

This Msys + Mingw download above is the minimal environment needed to build Tcl and extensions under Windows. It includes a shell environment and gcc. The release is designed to make it as easy as possible to build Tcl and extensions.

2. (Windows only) Install msys (and mingw for gcc)

To install, you just download the zip file and extract the files into a directory (the source one defaults to C:/msys/). The README.TXT file describes how to launch the msys shell, and then run the configure script in the Tcl source tcl/win or extension toplevel directory.

3. Ensure that prerequisite tools are on your PATH

On Windows, I recommend setting this in My Computer -> System Properties -> Environment Variables for persistence. Add C:\msys\1.0\bin and mingw if you installed that in a separate directory.

Changing PATH under Vista is done differently: see http://banagale.com/changing-your-system-path-in-windows-vista.htm for a good explanation.

4. Run the command shell (DOS prompt or unix shell of choice)

5. (Developers only) Download autoconf

Autoconf is the program that converts configure.in files into configure scripts. In some cases the CVS repository will only contain configure.in, and the end user must generate configure using autoconf. autoconf may not be installed with msys. You can download it from ftp://ftp.gnu.org/gnu/autoconf/. You may need to use one of the mirror sites. TEA extensions require 2.57 (2.59+ is recommended).

6. (Developers only) Install autoconf

You'll use configure and make to install autoconf. Unpack the .tar.gz file. WinZip can handle this format, as does tar that comes with msys.

      mkdir C:/build-area
      tar zxf C:/source-area/autoconf-2.60.tar.gz
      cd C:/build-area/autoconf-2.60
      sh configure --prefix=C:/msys/1.0
      make
      make install

The --prefix argument value corresponds to the Cygwin installation directory structure. If you leave out the --prefix, the default value is c:/usr/local. The --prefix flag is explained in more detail in the TEA document. You'll see this sequence of configure and make more when we build Tcl and extensions.

7. Build Tcl (if not already provided as binary)

I recommend and document here a clean method of keeping the build and source areas separate. This isn't strictly necessary, but it is useful if you share sources across platforms or build numerous variants from the same sources.

      mkdir C:/build-area/tcl8.x.y
      cd C:/build-area/tcl8.x.y
      sh /c/source-area/tcl-8.x.y/win/configure --prefix=C:/Tcl --enable-threads
      make
      make test    ; # you want to know it works, right?
      make install

The --enable-threads option turns on threading in the Tcl core. Tcl is thread-safe but does not use threads by default. As the next example uses the Thread extension, we want to make sure to enable threads.

It is important to use the /c/... msys pathname style to reference drive C:\... as that prevents issues in the Makefiles (where : can be used as a separator).

8. Build an Extension

      mkdir C:/build-area/thread
      cd C:/build-area/thread
      # we could use --with-tcl=C:/build-area/tcl8.x.y if it wasn't installed
      sh /c/source-area/thread2.6/configure --with-tcl=C:/Tcl
      make
      make test    ; # you want to know it works, right?
      make install

TEA extensions have their configure and Makefile.ion at the top of their directory structure. These files are shared by all platforms. Run sh autoconf in the top directory if configure.in exists without configure.

9. Cross fingers and hope the above worked

10. Add comments here to address common problems

First, make sure you have Microsoft VC++ or mingw-gcc installed. You may need to set your CC environment variable to the correct compiler.

For MSVC, if the configure step cannot find the compiler even though it is installed, then your PATH probably does not include BIN directory of Developer Studio (e.g., C:/program files/Microsoft Visual Studio/VC98/Bin). There are a few other environment variables you need, too. You may need to run MSVC's VCVARS32.bat in the command shell before the compiler environment is setup appropriately.

If "make test" generates lots of errors, try running the test suite from a directory on the local hard drive. Many of the file system tests do not work well with remote file systems. If "make install" puts the files into the wrong locations, specify the --prefix and --exec-prefix configure options to set those installation locations properly.

---

ro: 2008-01-03 I don't understand why there are two links for getting msys+mingw in Step 1. What is an old version of it doing linked off the main Tcl sf project? Well I'm using the Tcl sf version anyhow.

JH: The older one off the Tcl sf project is an older snapshot that includes both msys and mingw, which are separate downloads from the main site. It's just a convenience.

In Step 8 if you do not use --enable-threads to build Tcl, then configure will give this message:

  configure: WARNING:
      --enable-threads requested, but building against a Tcl that is NOT
      thread-enabled.  This is an OK configuration that will also run in
      a thread-enabled core.

That is because all TEA extensions default to enabling threads, as this method works when you run against either a threaded or non-thread Tcl core. Some extensions (like the Thread extension itself) require a threaded core, but can check at runtime.

[DrD]: Ive searched the whole internet, there is no proper guide to installing tclxml 3.2 for a beginner, Ive spent 2 days now tryin to install on windows platform, tried everything from TEA to VC++, no luck. COnfiguration if very difficult without a proper guide HaO Similar experience, using tcom now.

---

HaO: 2010-09-29 Test pilot trying to build tkimg with msvc6 and msys

Starting point

• Platform: Win 32 Vista
• msvc 6 installed
• win server 2000 sp1 platform sdk installed
• c:\program files\tcl8.5 contains wish compiled with makefile.vc
• cygwin installed

Steps:

• On wiki page TEA, it is stated, that cygwin may be used on windows. Here, nothing about cygwin
• contents of msys_mingw8.zip copied to c:\msys\1.0
• Started a windows command shell cmd.exe
• Executed vcvars32.bat from msvc
• Executed SetEnv.cmd /RELEASE from the platform sdk
• Added msys to path:

PATH c:\msys\1.0\bin;%PATH%

tkimg configure script uses the command sort and requires the msys version and not the windows version. In a consequence, the msys path must be before the windows system path which might break other windows software. Thus, I install it only temporarely and not system wide as suggested in step 3.

Prepare TCL

Even if tkImg will be build, prepending tcl and tk builds are necessary to get the tcl/tkConfig.sh files and tclsh85.exe and wish85.exe at the build places. In addition, its parameters set the final install-location.

• unzip tcl 8.5.9 sources in c:\test
• Create build folder for tcl and start configure:

mkdir c:\test\build-area\tcl8.5.9\win
cd c:\test\build-area\tcl8.5.9\win
sh /c/test/tcl8.5.9/win/configure --prefix=c:/test/tcl859 --enable-threads

This generates the file c:\test\build-area\tcl8.5.9\win\tclConfig.sh which is needed again. The win subfolder is necessary that the following tk build will find the file.

prepare Tk

• My tclsh is not in the path so extend the path by my tcl bin folder: PATH C:\Progra~1\tcl8.5\bin;%PATH%

(It will only be found if the path does not contain spaces. Otherwise, you get a warning: No tclsh found)

• unzip tk 8.5.9 sources in c:\test

mkdir c:\test\build-area\tk8.5.9\win
cd c:\test\build-area\tk8.5.9\win
sh /c/test/tk8.5.9/win/configure --prefix=c:/test/tcl859 --enable-threads

This generates the file c:\test\build-area\tk8.5.9\win\tclConfig.sh which is needed again.

The configure script states, there is a tclsh85.exe in /c/test/build-area/tcl8.5.9/win, but there is nothing.

build tkimg

tkimg configure script outputs "/c/test/build-area/tcl8.5.9/win/tclsh85.exe" found, but there is nothing. To be shure build it now.

cd c:\test\build-area\tcl8.5.9\win
make

tkimg configure script outputs "/c/test/build-area/tk8.5.9/win/wish85.exe" found, but there is nothing -> build it

cd c:\test\build-area\tk8.5.9\win
make

Now build it

mkdir c:\test\build-area\tkimg
cd c:\test\build-area\tkimg
sh /c/test/tkimg/configure --prefix=c:/test/tkimg

-> some "permission denied" on install warnings

make all
make install

Notes

To test, I also did a make install for tcl and tk. Here are the differences to the makefile.vc method:

• Threaded build does not have a "t" suffix on libraries and executables.
• There are no docs in the doc folder. A help compiler setup is included, so it must be somewhere, behind a special target...

---