X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=doc%2Ffcgi-tcl.htm;h=9d42465313fa91194cefb42f8ca591f5f2035da3;hb=af1b4cad97c093e021899eb02a1b4bb22a0c299d;hp=f860fcc5a508d8192927759bc072dd0c2d44bc39;hpb=6791223eaff3cd3ff05cc1da59b5ed8fde3a5037;p=catagits%2Ffcgi2.git diff --git a/doc/fcgi-tcl.htm b/doc/fcgi-tcl.htm index f860fcc..9d42465 100644 --- a/doc/fcgi-tcl.htm +++ b/doc/fcgi-tcl.htm @@ -1,316 +1,366 @@ - -
-Michael S. Shanzer
-
-Open Market, Inc.
-
-19 January 1995
-
- -We've built a Tcl interpreter that runs as a FastCGI application. Our -purpose in doing so was twofold: - -
-
- -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.
- -
- -
- -
-
- -
- - 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 Sun Labs Tcl/Tk - Project Page contains a wealth of information on Tcl, including - up to date information on the latest kits.
- -
- > 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/* .- -
- > autoconf- -
- > ./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.
-
-
+ + + ++ Integrating FastCGI with Tcl + + + + + +
+++ + + ++ Integrating FastCGI with Tcl +
++ 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: +
+
+
++ 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. +
++
++ Here are the assumptions embedded in the following recipe: +
++
++
++ If those are valid assumptions, follow these steps: +
++
++ 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 Sun Labs Tcl/Tk Project Page contains a wealth + of information on Tcl, including up to date information on the latest kits. +
++
++ > 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/* . ++
+ > autoconf ++
+ > ./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.
+ 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. +
++
+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.
-
-
- - This builds the FastCGI Tcl commands and - links them into the Tcl interpreter.
- -
- - This includes fcgi_stdio.h - when compiling C code for the Tcl interpreter, overriding - the normal stdio types, variables, and functions.
- -
- - 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.
- -
-
+ } ++ This registers four Tcl commands (FCGI_Accept, FCGI_Finish, + FCGI_SetExitStatus, and FCGI_StartFilterData), implemented in tclFCGI.c, + with the Tcl interpreter. +
+
++
++ This builds the FastCGI Tcl commands and links them into the Tcl interpreter. +
++
++ This includes fcgi_stdio.h when compiling C code for the Tcl interpreter, overriding the + normal stdio types, variables, and functions. +
++
++ 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. +
++
++
+AC_C_CROSS -CC=${CC-cc}- with the lines -
+CC=${CC-cc} ++ with the lines +
AC_PROG_CC -AC_C_CROSS- This selects gcc in preference to other C compilers.
- -
-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.
-
-
- > SETENV CC gcc- before running configure.
- -
-
- -
- -
+AC_C_CROSS ++ This selects gcc in preference to other C compilers. +
+
++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. +
+
++
++ > SETENV CC gcc ++ before running configure. +
+
++
++
++ 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>" + 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.
+ +
+ 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. +
++
+