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. Tcl still uses the Microsoft VC++ compiler; it does not use gcc 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 Code Warrior compiler, and 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
If you are the developer of a Tcl extension, there is a preliminary setup step that comes before configuration. In this step you create templates for the configure script and the Makefile that drives make. Then, you use the autoconf program to create the configure script. By using autoconf, a developer on Windows or Linux can generate a configure script that is usable by other developers on Solaris, HP-UX, FreeBSD, AIX, or any system that is vaguely UNIX-like.
The three steps: setup, configuration and make, are illustrated by the build process for Tcl and Tk:
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. However, if you get the Tcl sources from the network CVS repository, you must run autoconf yourself to generate the configure script.
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 only have one platform, simply run configure in the unix (or win) directory:
% cd /usr/local/src/tcl8.2/unix
% ./configure flags
The configure flags are described in Table 45-3. I use ./configure because I do not have . on my PATH. Furthermore, I want to ensure 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 solaris
% cd solaris
% ../configure flags
The configure script uses the Makefile.in template to generate the Makefile. Once configure is complete, you build your program with 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 45-4 on page 652 shows the standard make targets.
Make sure you have a working compiler.
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
checking if compiler works ... no
Either of these means configure has failed to find a working compiler. In the first case, it assumes you are configuring on the target system but will cross-compile from a different system. Configure proceeds bravely ahead, but the resulting Makefile is useless. While cross-compiling is common on embedded processors, it is rarely necessary on UNIX and Windows. I only see this message 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 search the Internet and find a ready to use gcc package for your platform.
On Windows there is a more explicit compiler check, and configure exits if it cannot find the compiler. Tcl is built with the Microsoft Visual C++ compiler. It ships with a batch file, vcvars32.bat, that sets up the environment so you can run the compiler from the command line. You should read that file and configure your environment so you do not have to remember to run the batch file all the time. If you use a different compiler on Windows, make sure you configure your environment so it can be run from the DOS prompt.
Standard Configure Flags
Table 45-3 shows the standard options for Tcl configure scripts. These are implemented by a configure library file (aclocal.m4) that you can use in your own configure scripts. The facilities provided by aclocal.m4 are described in more detail later.
Table 45-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-specific files. This defaults to the --prefix value. An example setting 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).|
|--with-x11include=dir||This specifics the directory that contains X11.h. |
|--with-x11lib=dir||This 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 45-3 lists the non-default 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 \
--enable-gcc --enable-threads --enable-symbols
Keep all your sources next to the Tcl sources.
Your builds will go the most smoothly if you organize all your sources under a common directory. In this case, you should be able to 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 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 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.
The --prefix flag specifies the main directory (e.g., /home/welch/install). The directories listed in Table 45-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.2 program and libtcl8.2.so shared library will be installed in:
The script libraries and manual pages will be installed in:
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/solaris, then the tclsh8.2 program and libtcl8.2.so shared library will be installed in:
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.