doc/fcgi-perl.htm

   1 <html>
   2 <head><title>Integrating FastCGI with Perl-5</title>
   3 </head>
   4
   5 <body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011"
   6 vlink="#555555">
   7
   8 <center>
   9 <a href="http://fastcgi.com">
  10     <img border=0 src="../images/fcgi-hd.gif" alt="[[FastCGI]]"></a>
  11 </center>
  12 <br clear=all>
  13 <h3><center>Integrating FastCGI with Perl-5</center></h3>
  14
  15 <!--Copyright (c) 1996 Open Market, Inc.                                    -->
  16 <!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
  17 <!--of this file, and for a DISCLAIMER OF ALL WARRANTIES.                   -->
  18
  19 <h5 align=center>
  20 Copyright &copy; 1996 Open Market, Inc.  245 First Street, Cambridge,
  21   MA 02142 U.S.A.<br>
  22 Tel: 617-949-7000 URL:
  23   <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
  24 $Id: fcgi-perl.htm,v 1.2 2001/05/14 13:00:30 robs Exp $ <br>
  25 </h5>
  26 <hr>
  27
  28 <ul type=square>
  29   <li><a HREF = "#S1">1. Introduction</a>
  30   <li><a HREF = "#S2">2. Perl with sfio and an FCGI module</a>
  31   <li><a HREF = "#S3">3. Perl with fcgi_stdio and an FCGI module</a>
  32   <ul type=square>
  33     <li><a HREF = "#S3.1">3.1 Basic recipe</a>
  34     <li><a HREF = "#S3.2">3.2 Semi-advanced recipe</a>
  35     <li><a HREF = "#S3.3">3.3 Advanced recipe</a>
  36   </ul>
  37   <li><a HREF = "#S4">4. Writing FastCGI applications in Perl</a>
  38 </ul>
  39
  40
  41 <H3><A NAME = "S1"> 1. Introduction</A></H3>
  42 Perl (Practical Extraction and Report Language) is a scripting language that
  43 is often used for CGI programming.  Perl is freely available as a
  44 source kit.<p>
  45
  46 FastCGI has been integrated with Perl in two different ways:
  47 <ol>
  48   <li>By writing a module that plugs into any Perl interpreter that's
  49       been built with sfio, a stdio alternative from AT&T.
  50   <li>By writing a module that plugs into any Perl interpreter that's
  51       been built with FastCGI's fcgi_stdio library
  52       layering over stdio.
  53
  54 The first approach, implemented by Sven Verdoolaege
  55 (skimo@breughel.ufsia.ac.be), is probably the better of the two,
  56 since sfio is a generally useful addition to Perl.
  57 The second approach, implemented by engineers at Open Market,
  58 predates the availability of an sfio-integrated
  59 Perl and demonstrates that the fcgi_stdio library
  60 can be used with a substantial C application.<p>
  61
  62 The two approaches
  63 are compatible at the Perl source code level; a Perl
  64 application developed using
  65 one approach can be run using the other.  And both approaches
  66 result in a general-purpose Perl interpreter, not a Perl interpreter
  67 that's only usable for FastCGI applications.<p>
  68
  69 This memo documents both approaches and explains a small
  70 Perl FastCGI application.<p>
  71
  72
  73 <h3><a name ="S2"> 2. Perl with sfio and an FCGI module</a></h3>
  74
  75 As of release 5 patch 3 subpatch 2 (5.003.02), Perl has announced an optional
  76 support for sfio (safe/fast string/file I/O), which is an alternative
  77 to stdio that AT&T distributes freely.  An advantage of sfio over stdio
  78 is that sfio provides the ability to implement
  79 new stream classes that don't simply transfer sequential bytes to or from
  80 a file descriptor.  This flexibility is exactly what FastCGI needs in order
  81 to implement the standard I/O streams in a manner that's
  82 transparent to applications.<p>
  83
  84 Perl interpreters incorporating sfio are not widely available in
  85 binary form, so most likely you'll have to build your own.
  86 Your build should go smoothly if you follow the instructions
  87 below.  The instructions assume:<p>
  88
  89 <ul>
  90   <li>You are building Perl 5.0 patch level 3 subpatch level 2 (5.003.02)
  91       or higher.  That's the first Perl release to support sfio.<p>
  92 </ul>
  93 <P>
  94
  95 Follow these steps to build a Perl with sfio:<p>
  96
  97 <ol>
  98   <li>Obtain sfio source code from
  99       <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc">
 100       ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc</a><p>
 101
 102   <li>Unpack the tar file using <tt>tar xvf</tt> command.  <EM>$sfio</EM>
 103       will be used as a shorthand for the directory in which sfio package
 104       is installed.<p>
 105
 106   <li>Update your $PATH variable as specified in <tt>$sfio/README</tt> and
 107       run <tt>make</tt> command in the <tt>$sfio/src/lib/sfio</tt> subdirectory.<p>
 108
 109   <li>Rename or delete the file <tt>$sfio/include/stdio.h</tt>, since it may
 110       interfere in the further build process.<p>
 111
 112   <li>Obtain Perl source (version 5 subversion 003 patchlevel 2 or higher) from
 113       <a href="http://fohnix.metronet.com/perlinfo/source/5.0/unsupported">
 114       http://fohnix.metronet.com/perlinfo/source/5.0/unsupported</a><p>
 115
 116   <li>Unpack the tar file using <tt>tar xvf</tt> command.  <EM>$perl</EM> is
 117       used as a shorthand for the directory that is created.<p>
 118
 119   <li>Configure, build, and install Perl as follows:
 120
 121 <pre>
 122 % cd $perl
 123 % ./Configure -Duseperlio -Dusesfio
 124 % make
 125 % make test
 126 % make install
 127 </pre><p>
 128
 129 There are certain Configure questions that must be answered
 130 differently when building Perl with sfio:<p>
 131
 132 <DL>
 133
 134 <DT><EM>Perl5 can now use alternate file IO mechanisms to ANSI stdio.
 135 However these are experimental and may cause problems with some
 136 extension modules.
 137 Use stdio as with previous versions? [y] </EM></DT>
 138 <DD>
 139 You should answer no.
 140 </DD><P>
 141
 142 <DT><EM>Any additional cc flags?</EM></DT>
 143 <DD>
 144 You should use the following cc flags along with any defaults that Perl
 145 Configure supplied:
 146 <UL>
 147 <LI> <strong>-I<em>$sfio</em>/include</strong>
 148 </UL>
 149 </DD><P>
 150
 151 <DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
 152 <DD>
 153 You should specify the following <tt>ld</tt> flags:
 154 <UL>
 155 <LI> <strong>-L<em>$sfio</em>/lib</strong>
 156 </UL>
 157 </DD><P>
 158
 159 <DT><EM>Additional Libraries:</EM></DT>
 160 <DD>
 161 Check that <strong>-lsfio</strong> is one of the specified libraries.  Press
 162 return key to continue.
 163 </DD><P>
 164 </DL>
 165
 166 <b>NOTE</b>: If you did not install Perl as a root user, make sure to
 167 correctly set environment variable <tt>PERL5LIB</tt> to indicate the location
 168 of Perl libraries.  For example, if you installed Perl binary into the
 169 <tt>$INSTALL</tt> subdirectory and you are running Solaris, the following
 170 will set your proper library path:
 171 <pre>
 172 % setenv PERL5LIB $INSTALL/lib:$INSTALL/lib/sun4-solaris/perl5.003_02
 173 </pre>
 174
 175 <p>
 176
 177   <li>Obtain Perl/Sfio module for FastCGI support from
 178       <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO">
 179       ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO</a><p>
 180
 181   <li>Unpack FCGI module using <tt>tar</tt> command.  We use <tt>$sfiomod</tt>
 182       to denote the subdirectory that is created in the process.<p>
 183
 184   <li>Build and install the module with the following commands:
 185 <pre>
 186 % cd $sfiomod
 187 % $INSTALL/bin/perl Makefile.PL
 188 % make
 189 % make test
 190 % make install
 191 </pre>
 192 </ol>
 193
 194
 195 <H3><a NAME = "S3">3. Perl with fcgi_stdio and an FCGI module</a></H3>
 196
 197 <H4><a NAME = "S3.1">3.1 Basic recipe</a></H4>
 198
 199 Here are the assumptions embedded in the following recipe:
 200 <UL>
 201
 202 <LI>You are building Perl 5.0 Patch 2 (5.002) or higher, since
 203 all examples that are provided are based on that release.
 204 <P></P>
 205
 206 <LI>You have gcc version 2.7 installed on your system, and use it in the
 207 build.  gcc is convenient because it supports the <tt>-include</tt>
 208 command-line option that instructs the C preprocessor to include a specific
 209 file before processing any other include files.  This allows you to include
 210 <tt>fcgi_stdio.h</tt> without modifying Perl source files.  (The reason for
 211 specifying gcc version 2.7 is that I have experienced bad behavior with an
 212 earlier version and the <tt>-include</tt> flag -- the C preprocessor died
 213 with SIGABRT.)
 214 <P></P>
 215
 216 <LI> <EM>$fcgi</EM> is used as shorthand for the full path of the FastCGI
 217 developers kit.
 218 </UL>
 219 <P>
 220 If those are valid assumptions, follow these steps:
 221 <OL>
 222 <LI> Pull the Perl source kit from
 223 <A HREF="http://www.metronet.com/perlinfo/src/latest.tar.gz">
 224 http://www.metronet.com/perlinfo/src/latest.tar.gz</A>
 225 <P>
 226 There are good sources of information on Perl at:
 227 <UL>
 228 <LI> <A HREF="http://www.perl.com/">http://www.perl.com/</A>
 229 <LI> <A HREF="http://www.metronet.com/perlinfo/">http://www.metronet.com/perlinfo/</A>
 230 </UL>
 231 <p></P>
 232
 233 <LI> Unpack the tar file in the parent directory of the FastCGI kit
 234 directory, so that the perl directory is a sibling of <tt>fcgi-devel-kit</tt>.
 235 <EM>$perl</EM> is used as shorthand for the full path of the directory
 236 in which Perl is installed.
 237 <p>
 238 <LI> Copy the version specific and the common files from
 239 <tt>fcgi-devel-kit/perl-5</tt> into the Perl-5 kit.
 240 <PRE>
 241 > cd $perl
 242 > mv perl.c perl.c.orig
 243 > mv proto.h proto.h.orig
 244 > mv Configure Configure.orig
 245 > cp -r ../fcgi-devel-kit/perl-5/perl5.002/* .
 246 > cp -r ../fcgi-devel-kit/perl-5/common/* .
 247 </PRE>
 248 <P>
 249 The files you are copying contain the Perl-5 FCGI extension, some
 250 files modified from the distribution, and a script to simplify the
 251 configuration process.
 252 </P>
 253 <LI> Set environment variables.
 254 The Perl-5 FastCGI configuration process requires that the environment
 255 variable <TT>FCGIDIR</TT> be set to the top level directory of the FastCGI
 256 development kit.
 257 <PRE>
 258 > setenv FCGIDIR <EM>$fcgi</EM>
 259 </PRE>
 260 If you do not want to use <tt>gcc</tt> to build Perl you can set the
 261 environment variable <TT>CC</TT> to the desired compiler. For example:
 262 <PRE>
 263 > setenv CC gcc2.7
 264 </PRE>
 265 By default Perl's installation prefix is /usr/local, so binaries get
 266 installed in /usr/local/bin, library files get installed into
 267 /usr/local/lib/perl, etc. If you want to specify a different installation
 268 prefix set the environment variable <tt>PERL_PREFIX</tt>.
 269 <PRE>
 270 > setenv PERL_PREFIX /usr/local/perl5-fcgi
 271 </PRE>
 272 <LI> Run fcgi-configure.
 273 <PRE>
 274 > ./fcgi-configure
 275 </PRE>
 276 <P>
 277 <TT>fcgi-configure</TT> is a wrapper around Perl's <tt>Configure</tt> script.
 278 It sets some variables according the the value of some environment variables,
 279 and runs Perl's <tt>Configure</tt> script
 280 in such a way that it does not prompt the
 281 user for any input. 90% of the time this should work without a problem.
 282 If for some reason this does not work for you, you'll have to
 283 follow the steps in the next section.<p>
 284 <LI> Run make.
 285 <PRE>
 286 > make
 287 </PRE>
 288 <LI> Install the newly built Perl-5.
 289 <PRE>
 290 > make install
 291 </PRE>
 292 </OL><p>
 293
 294
 295 <H4><a NAME = "S3.2">3.2 Semi-advanced recipe</a></H4>
 296
 297 If you do not have experience configuring and building Perl, you
 298 should find someone who does.  Perl can be pretty intimidating to configure
 299 since it asks you a large number of irrelevant-seeming
 300 questions that you won't know how to answer.<p>
 301 <P>
 302 <OL>
 303 <LI>Go into the top level directory of the Perl distribution and run
 304 <tt>Configure</tt>.
 305 <PRE>
 306 > cd $perl
 307 > ./Configure
 308 </PRE>
 309 <LI>
 310 There are some questions that you are going to
 311 have to answer differently when building FastCGI into Perl.
 312 These are described below:
 313 <P></P>
 314 <DL>
 315 <DT><EM>Use which C compiler?</EM></DT>
 316 <DD>
 317 You should specify <tt>gcc</tt>.
 318 </DD>
 319 <P></P>
 320 <DT><EM>Any additional cc flags?</EM></DT>
 321 <DD>
 322 You should use the following cc flags along with any defaults that Perl
 323 Configure supplied:
 324 <UL>
 325 <LI> <strong>-I<em>$fcgi</em>/include</strong>
 326 <LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong>
 327 </UL>
 328 This assumes you are using GCC.
 329 </DD>
 330 <P></P>
 331
 332 <DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
 333 <DD>
 334 You should specify the following <tt>ld</tt> flags:
 335 <UL>
 336 <LI> <strong>-L<em>$fcgi</em>/libfcgi</strong>
 337 </UL
 338 ></DD>
 339 <P></P>
 340
 341 <DT><EM>Additional Libraries:</EM></DT>
 342 <DD>
 343 add <strong>-lfcgi</strong> to the list of additional libraries.
 344 It should be added before -lc.
 345 </DD>
 346 <P></P>
 347
 348 <DT><EM>What extensions do you wish to load dynamically?</EM></DT>
 349 <DD>
 350 If you can support dynamic extensions, <tt>Configure</tt>
 351 will ask which of the
 352 supplied extensions should be loaded dynamically. Since we copied the FCGI
 353 extension into the Perl source directory it should be one of the ones in the
 354 default list. If you want FCGI to be dynamically loaded you should specify
 355 it here, otherwise leave it out.
 356 </DD>
 357 <P></P>
 358
 359 <DT><EM>What extensions do you wish to load statically?</EM></DT>
 360 <DD>
 361 If you do not support Dynamic extensions this is the only question about
 362 extensions you would get asked. You should specify FCGI here if you did not
 363 get asked about dynamic extensions (or did not specify FCGI as a dynamic
 364 extension).
 365 </DD>
 366 </DL>
 367 <P></P>
 368 <LI> Copy in the new <tt>proto.h</tt>.
 369 <P>
 370 The file proto.h has some macros that conflict with the FastCGI macros.
 371 The version of <tt>proto.h</tt> supplied in the FastCGI kit
 372 includes these changes:<p>
 373 <UL>
 374 <LI> At the beginning of the file it adds the following lines:
 375 <PRE>
 376 #ifdef _FCGI_STDIO
 377 #undef printf
 378 #endif
 379 </PRE>
 380 <LI> At the bottom it adds:
 381 <PRE>
 382 #ifdef _FCGI_STDIO
 383 #define printf FCGI_printf
 384 #endif
 385 </PRE>
 386 </UL>
 387 <LI> Copy in the new <tt>perl.c</tt>.
 388 <P>
 389 Perl-5.002 has a bug in <tt>perl.c</tt> that has a great
 390 chance of getting exercised
 391 with FastCGI.  A fix has been sumbitted to the Perl developers and hopefully
 392 it'll make it into perl-5.003. It was a one line fix, here is a diff for the
 393 curious:
 394 <PRE>
 395 *** perl.c      1996/03/15 17:10:10     1.1
 396 --- perl.c      1996/03/15 17:11:23
 397 ***************
 398 *** 405,410 ****
 399 --- 405,411 ----
 400       if (e_fp) {
 401         if (Fflush(e_fp) || ferror(e_fp) || fclose(e_fp))
 402             croak("Can't write to temp file for -e: %s", Strerror(errno));
 403 +       e_fp = Nullfp;
 404         argc++,argv--;
 405         scriptname = e_tmpname;
 406       }
 407 </PRE>
 408 Pretty straightforward.<p>
 409 <LI> Build and install Perl.
 410 <PRE>
 411 > make
 412 <EM>[...]</EM>
 413 > make install
 414 </PRE>
 415
 416 <p></P>
 417 <H4><a NAME = "S3.3">3.3 Advanced recipe</a></H4>
 418
 419 <P>
 420 If you already have a Perl-5 package that has been configured, and you do
 421 not really want to re-run Configure, you can take the following steps.
 422 </P>
 423 <P ALIGN=CENTER><STRONG>THIS IS NOT RECOMMENDED</STRONG></P>
 424 <P>
 425 Edit config.sh with your favorite editor and modify the following lines:
 426         <DL>
 427           <DT><EM>cc</EM></DT>
 428           <DD> Change to use gcc if you are not using it already. </DD>
 429           <P></P>
 430           <DT><EM>ccflags</EM> AND <EM>cppflags</EM></DT>
 431           <DD> Add the following flags:
 432             <UL>
 433               <LI> <strong>-I<em>$fcgi</em>/include</strong>
 434               <LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong>
 435             </UL>
 436             This assumes you are using GCC. See the above section on assumptions
 437           </DD>
 438           <P></P>
 439           <DT><EM>extensions</EM> AND <EM>known_extensions</EM></DT>
 440           <DD> Add FCGI to the list of extensions </DD>
 441           <P></P>
 442           <DT><EM>ldflags</EM></DT>
 443           <DD> Add -L $fcgi/libfcgi to the list. </DD>
 444           <P></P>
 445           <DT><EM>libs</EM></DT>
 446           <DD> Add -lfcgi to the list of libraries, should be added before -lc.
 447           </DD>
 448           <P></P>
 449           <DT><EM>static_ext</EM><STRONG> or </STRONG><EM>dynamic_ext</EM></DT>
 450           <DD> Add FCGI to the list of statically or dynamically loaded extensions.
 451           </DD>
 452           <P></P>
 453           <DT><EM>d_stdio_cnt_lval, d_stdio_ptr_lval, d_stdiobase, d_stdstdio</EM></DT>
 454           <DL> Change all of these to undef. </DL>
 455           <P> One you have edited config.sh you should do a "make Makefile depend
 456             all". If you're paranoid like me you may want to do a "make clean"
 457             first. </P>
 458           <H3><A NAME = "S4"> 4. Writing FastCGI applications in Perl</A></H3>
 459           <P> The Perl program <tt>examples/tiny-perl-fcgi</tt> performs the same
 460             function as the C program <tt>examples/tiny-fcgi</tt> that's used
 461             as an example in the <A HREF="fcgi-devel-kit.htm#S3.1.1">FastCGI Developer's
 462             Kit</A>. Here's what the Perl version looks like: </P>
 463           <pre>
 464 #!./perl
 465 use FCGI;
 466 $count = 0;
 467 while(FCGI::accept() >= 0) {
 468     print("Content-type: text/html\r\n\r\n",
 469           "&lt;title&gt;FastCGI Hello! (Perl)&lt;/title&gt;\n",
 470           "&lt;h1&gt;FastCGI Hello! (Perl)&lt;/h1&gt;\n",
 471           "Request number ", $++count,
 472           " running on host &lt;i&gt;$ENV('SERVER_NAME')&lt;/i&gt;");
 473 }
 474 </pre>
 475           If you've built Perl according to the recipe and you have a Web server
 476           set up to run FastCGI applications, load the FastCGI Developer's Kit
 477           Index Page in that server and run this Perl application now.
 478           <p> The script invokes Perl indirectly via the symbolic link <tt>examples/perl</tt>.
 479             It does this because HP-UX has a limit of 32 characters for the first
 480             line of a command-interpreter file such as <tt>examples/tiny-perl-fcgi</tt>.
 481             If you run on HP-UX you won't want to sprinkle symbolic links to perl
 482             everywhere, so you should choose a <tt>PERL_PREFIX</tt> shorter than
 483             <tt>/usr/local/perl5-fcgi</tt>.
 484           <p> You need to be aware of the following bug. If the initial environment
 485             to a FastCGI Perl application is empty (contains no name-value pairs)
 486             then when the first call to <tt>FCGI::accept</tt> returns, the environment
 487             will <i>still</i> be empty, i.e. <tt>%ENV</tt> will contain no associations.
 488             All the variables associated with the first request are lost. There
 489             are two known workarounds:
 490           <p>
 491           <ul>
 492             <li> In your Perl application, enumerate <tt>%ENV</tt> using <tt>each</tt>
 493               before entering the <tt>FCGI::accept</tt> loop. The program <tt>examples/tiny-perl-fcgi</tt>
 494               contains code for this.
 495               <p>
 496             <li> In configuring your application be sure to set at least one initial
 497               environment variable. You do this with the <tt>AppClass -initial-env</tt>
 498               directive to the Web server, or by running <tt>cgi-fcgi</tt> in
 499               a non-empty environment.
 500           </ul>
 501           <p> The Perl subroutine <tt>FCGI::accept</tt> treats the initial environment
 502             differently than the C function <tt>FCGI_Accept</tt>. The first call
 503             to the C function <tt>FCGI_Accept</tt> replaces the initial environment
 504             with the environment of the first request. The first call to the Perl
 505             subroutine <tt>FCGI::accept</tt> adds the variable bindings of the
 506             first request to the bindings present in the initial environment.
 507             So when the first call to <tt>FCGI::accept</tt> returns, bindings
 508             from the initial environment are still there (unless, due to naming
 509             conflicts, some of them have been overwritten by the first request).
 510             The next call to <tt>FCGI::accept</tt> removes the bindings made on
 511             the previous call before adding a new set for the request just accepted,
 512             again preserving the initial environment.
 513           <p> The Perl <tt>FCGI</tt> module also includes subroutines <tt>FCGI::finish</tt>,
 514             <tt>FCGI::set_exit_status</tt>, and <tt>FCGI::start_filter_data</tt>
 515             that correspond to C functions in <tt>fcgi_stdio.h</tt>; see the manpages
 516             for full information.
 517           <p> Converting a Perl CGI application to FastCGI is not fundamentally
 518             different from converting a C CGI application. You separate the portion
 519             of the application that performs one-time initialization from the
 520             portion that performs per-request processing. You put the per-request
 521             processing into a loop controlled by <tt>FCGI::accept</tt>.
 522           <p>
 523         </dl>
 524       </ol></ol></body>
 525 </html>