Building Tcl from Source

Compiling Tcl from the source distribution is a two-step process: configuration, which uses a configure script; then compiling, which is controlled by the make program. The configure script examines the current system and makes various settings that are used during compilation. 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. You use make to compile the source code, install the compiled application, run the test suite, and clean up after yourself.

The make facility is familiar to any Unix programmer. By using the freely available Cygwin tools, you can use configure and make on Windows, too. You have two compiler choices on Windows, the free mingw compiler and the Microsoft VC++ compiler. However, gcc is not supported for Tcl builds on Windows.

Windows and Macintosh programmers may not have experience with make. The source distributions may also include project files for the Microsoft Visual C++ compiler and the Macintosh development environments. It may be easier for you to use these project files, especially on the Macintosh. Look in the win and mac subdirectories of the source distribution for these project files. However, the focus of this chapter is on using configure and make to build your Tcl applications and extensions.

Configure and Autoconf

Autoconf is a clever and, unfortunately, complex system for creating portable build environments. By using autoconf, a developer on Windows or Linux can generate a configure script and a Makefile template that is usable by other developers on Solaris, HP-UX, FreeBSD, AIX, or any system that is vaguely UNIX-like. The configure script examines the current system and turns the Makefile template into a platform specific Makefile. The three steps: setup, configuration and make, are illustrated by the build process for Tcl and Tk:

• Setup. The developer of a source code package creates a configure.in template that expresses the system dependencies of the source code. They use the autoconf program to process this template into a configure script. The developer also creates a Makefile.in template. Creating these templates is described later. The Tcl and Tk source distributions already contain the configure script, which can be found in the unix and win subdirectories.

• Configure. A user of a source code package runs configure on the computer system they will use to compile the sources. This step converts Makefile.in to a Makefile suitable for the platform and configuration settings. If you have only one platform, simply run configure in the unix (or win) directory:

  % cd /usr/local/src/tcl8.4/unix
  % ./configure flags
  

  The configure flags are described in Table 48-3. I use ./configure because I do not have . on my PATH. Furthermore, I want to ensure that I run the configure script from the current directory! If you build for multiple platforms, create subdirectories of unix and run configure from there. For example, here we use ../configure:

  % cd /usr/local/src/tcl8.2/unix
  % mkdir linux
  % cd linux
  % ../configure flags
  

• Make. The configure script uses the Makefile.in template to generate the Makefile. Once configure is complete, you build your program with make:

  % make
  

  You can do other things with make. To run the test suite, do:

  % make test
  

  To install the compiled program or extension, do:

  % make install
  

The Tcl Extension Architecture defines a standard set of actions, or make targets, for building Tcl sources. Table 48-4 on page 740 shows the standard make targets.

As the configure script executes, it prints out messages about the properties of the current platform. You can tell if you are in trouble if the output contains either of these messages:

checking for cross compiler ... yes

or

checking if compiler works ... no

Either of these means that configure has failed to find a working compiler. In the first case, it assumes that you are configuring on the target system but will cross-compile from a different system. In the second case, an attempt to compile a tiny sample program failed. In either case, the resulting Makefile is useless. While cross-compiling is common on embedded processors, it is rarely necessary on UNIX and Windows. I see these messages only when my UNIX environment isn't set up right to find the compiler.

Many UNIX venders no longer bundle a working compiler. Fortunately, the freely available gcc compiler has been ported to nearly every UNIX system. You should be able to search the Internet and find a ready-to-use gcc package for your platform.

On Windows, Tcl is built with either the free mingw compiler the Microsoft Visual C++ compiler. It ships with a batch file, vcvars32.bat, that sets up the environment so that you can run the Microsoft compiler from the command line. You should read that file and configure your environment so that you do not have to remember to run the batch file all the time.

Standard Configure Flags

Table 48-3 shows the standard options for Tcl configure scripts. These are implemented by a configure library file (aclocal.m4 and tcl.m4) that you can use in your own configure scripts. The facilities provided by tcl.m4 are described in more detail later.

Table 48-3. Standard configure flags

--prefix=dir	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-specific files. This defaults to the --prefix value. An example setting is /usr/local/solaris-sparc.
--enable-gcc	Uses the gcc compiler instead of the default system compiler.
--disable-shared	Disables generation of shared libraries and Tcl shells that dynamically link against them. Statically linked shells and static archives are built instead.
--enable-symbols	Compiles with debugging symbols.
--enable-threads	Compiles with thread support turned on.
--with-tcl=dir	Specifies the location of the build directory for Tcl.
--with-tk=dir	Specifies the location of the build directory for Tk.
--with-tclinclude=dir	Specifies the directory that contains tcl.h.
--with-tcllib=dir	Specifies the directory that contains the Tcl binary library (e.g., libtclstubs.a).
--with-x11include=dir	Specifies the directory that contains X11.h.
--with-x11lib=dir	Specifies the directory that contains the X11 binary library (e.g., libX11.6.0.so).

Any flag with disable or enable in its name can be inverted. Table 48-3 lists the nondefault setting, however, so you can just leave the flag out to turn it off. For example, when building Tcl on Solaris with the gcc compiler, shared libraries, debugging symbols, and threading support turned on, use this command:

configure --prefix=/home/welch/install \
    --exec-prefix=/home/welch/install/solaris \
    --enable-gcc --enable-threads --enable-symbols

Your builds will go the most smoothly if you organize all your sources under a common directory. In this case, you can specify the same configure flags for Tcl and all the other extensions you will compile. In particular, you must use the same --prefix and --exec-prefix so that everything gets installed together.

If your source tree is not adjacent to the Tcl source tree, then you must use --with-tclinclude or --with-tcllib so that the header files and runtime library can be found during compilation. Typically, this can happen if you build an extension under your home directory, but you are using a copy of Tcl that has been installed by your system administrator. The --with-x11include and --with-x11lib flags are similar options necessary when building Tk if your X11 installation is in a nonstandard location.

Installation

The --prefix flag specifies the main directory (e.g., /home/welch/install). The directories listed in Table 48-2 are created under this directory. If you do not specify --exec-prefix, then the platform-specific binary files are mixed into the main bin and lib directories. For example, the tclsh8.4 program and libtcl8.4.so shared library will be installed in:

/home/welch/install/bin/tclsh8.4
/home/welch/install/lib/libtclsh8.4.so

The script libraries and manual pages will be installed in:

/home/welch/install/lib/tcl8.4
/home/welch/install/man

If you want to have installations for several different platforms, then specify an --exec-prefix that is different for each platform. For example, if you use --exec-prefix=/home/welch/install/freebsd, then the tclsh8.4 program and libtcl8.4.so shared library will be installed in:

/home/welch/install/freebsd/bin/tclsh8.4
/home/welch/install/freebsd/lib/libtclsh8.4.so

The script libraries and manual pages will remain where they are, so they are shared by all platforms. Note that Windows has a slightly different installation location for binary libraries. They go into the arch/bin directory along with the main executable programs.