Michael S. Shanzer
Open Market, Inc.
19 January 1995

Copyright © 1996 Open Market, Inc. 245 First Street, Cambridge, MA 02142 U.S.A.
Tel: 617-621-9500 Fax: 617-621-1703 URL: http://www.openmarket.com/
$Id: fcgi-tcl.htm,v 1.4 2002/02/25 00:42:59 robs Exp $

1. Introduction

Tcl (tool command language) is an embeddable scripting language that's often used for CGI programming. Tcl is freely available as a source kit.

We've built a Tcl interpreter that runs as a FastCGI application. Our purpose in doing so was twofold:

• Create a useful artifact. Open Market has written many CGI applications using Tcl. Now we'd like to turn them into FastCGI applications.

• Demonstrate how easy it is to integrate FastCGI with an existing program. The Tcl interpreter is a substantial program, so integrating FastCGI with the Tcl interpreter is a good test of the fcgi_stdio compatibility library.

We've succeeded on both counts. We now have a platform for migrating our Tcl-based CGI applications to FastCGI. And the integration required a very small effort. The only source code change to the Tcl interpreter was the routine addition of a handful of new commands: FCGI_Accept, FCGI_Finish, FCGI_SetExitStatus, and FCGI_StartFilterData.

The FastCGI-integrated Tcl interpreter works as usual when run from a shell or as a CGI program. You don't need two Tcls, one for FastCGI and one for other uses.

The remainder of this document gives a recipe you can follow to build FastCGI into Tcl, explains what's happening in the recipe, and illustrates the use of FastCGI Tcl with an example program.

2. Recipe

Here are the assumptions embedded in the following recipe:

• You are building Tcl 7.4p3, the current stable Tcl release as this is written. You unpack the Tcl kit into a directory tcl7.4 that's a sibling of the FastCGI kit directory fcgi-devel-kit.

• You have gcc version 2.7 installed on your system, and use it in the build. gcc is convenient because it supports the -include command-line option that instructs the C preprocessor to include a specific file before processing any other include files. This allows you to include fcgi_stdio.h without modifying Tcl source files. (The reason for specifying gcc version 2.7 is that I have experienced bad behavior with an earlier version and the -include flag -- the C preprocessor died with SIGABRT.)

• You have GNU autoconf installed on your system. If you don't have GNU autoconf, you will have to make certain edits by hand and repeat these edits for each build platform.
  
  

If those are valid assumptions, follow these steps:

1. Build the FastCGI Developer's Kit. Tcl needs to link against libfcgi.a, so build the FastCGI Developer's Kit in order to create this library for your platform.

2. Pull the Tcl 7.4p3 kit. You'll need the files tcl7.4.tar.Z, tcl7.4p1.patch.gz, tcl7.4p2.patch.gz, and tcl7.4p3.patch.gz. (Some older Netscape browsers can't perform these retrievals because of a protocol conflict between Netscape and Sun's firewall.)

   Unpack the tar file in the parent directory of the FastCGI kit directory you used in the previous step, so that the directories tcl7.4 and fcgi-devel-kit are siblings. After unpacking the tar file, follow the directions in the README to apply the patches.

   The Tcl/Tk Project Page contains a wealth of information on Tcl, including up to date information on the latest kits.

3. Copy the files tclFCGI.c, tclAppInit.c, Makefile.in, and configure.in from the FastCGI kit.

       > cd tcl7.4
       > mv tclAppInit.c tclAppInit.c.orig
       > mv Makefile.in.orig Makefile.in.orig.orig
       > mv Makefile.in Makefile.in.orig
       > mv configure.in configure.in.orig
       > cp ../fcgi-devel-kit/tcl/tcl7.4/* .
       > cp ../fcgi-devel-kit/tcl/common/* .
   

4. Create a new configure script.

       > autoconf
   

5. Configure and build.

       > ./configure
       > make
   

   The make creates the Tcl interpreter tclsh and library archive libtcl.a (for embedding Tcl in your own C applications). The Tcl README file explains how you can experiment with tclsh without installing it in a standard place.
   
   

3. Recipe Explained

The recipe alone is fine if you are using Tcl 7.4p3, you have gcc version 2.7, and you have GNU autoconf. In case one or more of these assumptions doesn't hold for you, and to illuminate how little work was involved in integrating FastCGI, here's an explanation of how and why you would modify the files tclAppInit.c, Makefile.in, and configure.in from the Tcl kit.

• tclAppInit.c:
  • Add the following three lines of code to the function Tcl_AppInit after the call to Tcl_Init and after the comment about calling init procedures:

        if (FCGI_Init(interp) == TCL_ERROR) {
            return TCL_ERROR;
        }
    

    This registers four Tcl commands (FCGI_Accept, FCGI_Finish, FCGI_SetExitStatus, and FCGI_StartFilterData), implemented in tclFCGI.c, with the Tcl interpreter.

• Makefile.in:
  • Add tclFCGI.o to the GENERIC_OBJS variable, and add tclFCGI.c to the SRCS variable.

    This builds the FastCGI Tcl commands and links them into the Tcl interpreter.

  • Add -I../fcgi-devel-kit/include -include ../fcgi-devel-kit/include/fcgi_stdio.h to the CFLAGS variable.

    This includes fcgi_stdio.h when compiling C code for the Tcl interpreter, overriding the normal stdio types, variables, and functions.

  • Add ../fcgi-devel-kit/libfcgi/libfcgi.a before the @LIBS@ part of the LIBS variable.

    This links the implementation of fcgi_stdio.h into the Tcl interpreter, for use by the FCGI_accept command and any code that uses stdio variables or calls stdio functions.

  The last two edits will vary if you use a compiler other than gcc or install the tcl7.4 directory somewhere else in relation to the fcgi-devel-kit directory.

• configure.in:
  • Replace the lines

    AC_C_CROSS
    CC=${CC-cc}
    

    with the lines

    AC_PROG_CC
    AC_C_CROSS
    

    This selects gcc in preference to other C compilers.

  • Add the following lines just after the AC_SUBST(CC) line:

    AC_CHECK_LIB(socket, main, [LIBS="$LIBS -lsocket"])
    AC_CHECK_LIB(nsl, main, [LIBS="$LIBS -lnsl"])
    AC_SUBST(LIBS)
    

    This ensures that the socket libraries used by FastCGI are linked into the Tcl interpreter.

  If GNU autoconf is not available to you, you'll leave configure.in alone and perform the following steps:
  • Execute

        > SETENV CC gcc
    

    before running configure.

  • If you are running on a SVR4-derived Unix platform, edit Makefile to add -lsocket -lnsl to the LIBS value after running configure.

  If you ever re-run configure, you'll need to repeat these steps.

4. Writing FastCGI applications in Tcl

The Tcl program tcl/tiny-tcl-fcgi performs the same function as the C program examples/tiny-fcgi.c that's used as an example in the FastCGI Developer's Kit document. Here's what the Tcl version looks like:

#!./tclsh
set count 0 
while {[FCGI_Accept] >= 0 } {
    incr count
    puts -nonewline "Content-type: text/html\r\n\r\n"
    puts "<title>FastCGI Hello! (Tcl)</title>"
    puts "<h1>FastCGI Hello! (Tcl)</h1>"
    puts "Request number $count running on host <i>$env(SERVER_NAME)</i>"
}

If you've built Tcl according to the recipe and you have a Web server set up to run FastCGI applications, load the FastCGI Developer's Kit Index Page in that server and run this Tcl application now.

The script invokes Tcl indirectly via the symbolic link examples/tclsh. It does this because HP-UX has a limit of 32 characters for the first line of a command-interpreter file such as examples/tiny-tcl-fcgi. If you run on HP-UX you won't want to sprinkle symbolic links to tclsh everywhere, so you should install tclsh with a shorter pathname than /usr/local/tcl7.4-fcgi/bin/tclsh7.4.

The Tcl command FCGI_Accept treats the initial environment differently than the C function FCGI_Accept. The first call to the C function FCGI_Accept replaces the initial environment with the environment of the first request. The first call to the Tcl command FCGI_Accept adds the variable bindings of the first request to the bindings present in the initial environment. So when the first call to FCGI_Accept returns, bindings from the initial environment are still there (unless, due to naming conflicts, some of them have been overwritten by the first request). The next call to FCGI_Accept removes the bindings made on the previous call before adding a new set for the request just accepted, again preserving the initial environment.

The FastCGI-integrated tclsh also includes commands FCGI_Finish, FCGI_SetExitStatus, and FCGI_StartFilterData that correspond to C functions in fcgi_stdio.h; see the manpages for full information.

Converting a Tcl CGI application to FastCGI is not fundamentally different from converting a C CGI application. You separate the portion of the application that performs one-time initialization from the portion that performs per-request processing. You put the per-request processing into a loop controlled by FCGI_Accept.