[catagits/fcgi2.git] / doc / fcgi-perl.htm

<html>
<head><title>Integrating FastCGI with Perl-5</title>
</head>

<body bgcolor="#FFFFFF" text="#000000" link="#cc0000" alink="#000011" 
vlink="#555555">

<center>
<a href="http://fastcgi.com">
    <img border=0 src="../images/fcgi-hd.gif" alt="[[FastCGI]]"></a>
</center>
<br clear=all>
<h3><center>Integrating FastCGI with Perl-5</center></h3>

<!--Copyright (c) 1996 Open Market, Inc.                                    -->
<!--See the file "LICENSE.TERMS" for information on usage and redistribution-->
<!--of this file, and for a DISCLAIMER OF ALL WARRANTIES.                   -->

<h5 align=center>
Copyright &copy; 1996 Open Market, Inc.  245 First Street, Cambridge,
  MA 02142 U.S.A.<br>
Tel: 617-949-7000 URL:
  <a href="http://www.openmarket.com/">http://www.openmarket.com/</a><br>
$Id: fcgi-perl.htm,v 1.2 2001/05/14 13:00:30 robs Exp $ <br>
</h5>
<hr>

<ul type=square>
  <li><a HREF = "#S1">1. Introduction</a>
  <li><a HREF = "#S2">2. Perl with sfio and an FCGI module</a>
  <li><a HREF = "#S3">3. Perl with fcgi_stdio and an FCGI module</a>
  <ul type=square>
    <li><a HREF = "#S3.1">3.1 Basic recipe</a>
    <li><a HREF = "#S3.2">3.2 Semi-advanced recipe</a>
    <li><a HREF = "#S3.3">3.3 Advanced recipe</a>
  </ul>
  <li><a HREF = "#S4">4. Writing FastCGI applications in Perl</a>
</ul>


<H3><A NAME = "S1"> 1. Introduction</A></H3>
Perl (Practical Extraction and Report Language) is a scripting language that
is often used for CGI programming.  Perl is freely available as a
source kit.<p>

FastCGI has been integrated with Perl in two different ways:
<ol>
  <li>By writing a module that plugs into any Perl interpreter that's
      been built with sfio, a stdio alternative from AT&T.
  <li>By writing a module that plugs into any Perl interpreter that's
      been built with FastCGI's fcgi_stdio library
      layering over stdio.

The first approach, implemented by Sven Verdoolaege
(skimo@breughel.ufsia.ac.be), is probably the better of the two,
since sfio is a generally useful addition to Perl.
The second approach, implemented by engineers at Open Market,
predates the availability of an sfio-integrated
Perl and demonstrates that the fcgi_stdio library
can be used with a substantial C application.<p>

The two approaches
are compatible at the Perl source code level; a Perl
application developed using
one approach can be run using the other.  And both approaches
result in a general-purpose Perl interpreter, not a Perl interpreter
that's only usable for FastCGI applications.<p>

This memo documents both approaches and explains a small
Perl FastCGI application.<p>


<h3><a name ="S2"> 2. Perl with sfio and an FCGI module</a></h3>

As of release 5 patch 3 subpatch 2 (5.003.02), Perl has announced an optional 
support for sfio (safe/fast string/file I/O), which is an alternative
to stdio that AT&T distributes freely.  An advantage of sfio over stdio
is that sfio provides the ability to implement
new stream classes that don't simply transfer sequential bytes to or from
a file descriptor.  This flexibility is exactly what FastCGI needs in order
to implement the standard I/O streams in a manner that's
transparent to applications.<p>

Perl interpreters incorporating sfio are not widely available in
binary form, so most likely you'll have to build your own.
Your build should go smoothly if you follow the instructions
below.  The instructions assume:<p>

<ul>
  <li>You are building Perl 5.0 patch level 3 subpatch level 2 (5.003.02) 
      or higher.  That's the first Perl release to support sfio.<p>
</ul>
<P>

Follow these steps to build a Perl with sfio:<p>

<ol>
  <li>Obtain sfio source code from 
      <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc">
      ftp://ftp.funet.fi/pub/languages/perl/CPAN/src/misc</a><p>

  <li>Unpack the tar file using <tt>tar xvf</tt> command.  <EM>$sfio</EM>
      will be used as a shorthand for the directory in which sfio package 
      is installed.<p>

  <li>Update your $PATH variable as specified in <tt>$sfio/README</tt> and 
      run <tt>make</tt> command in the <tt>$sfio/src/lib/sfio</tt> subdirectory.<p>

  <li>Rename or delete the file <tt>$sfio/include/stdio.h</tt>, since it may
      interfere in the further build process.<p>

  <li>Obtain Perl source (version 5 subversion 003 patchlevel 2 or higher) from
      <a href="http://fohnix.metronet.com/perlinfo/source/5.0/unsupported">
      http://fohnix.metronet.com/perlinfo/source/5.0/unsupported</a><p>

  <li>Unpack the tar file using <tt>tar xvf</tt> command.  <EM>$perl</EM> is
      used as a shorthand for the directory that is created.<p>

  <li>Configure, build, and install Perl as follows:

<pre>
% cd $perl
% ./Configure -Duseperlio -Dusesfio
% make 
% make test
% make install
</pre><p>

There are certain Configure questions that must be answered
differently when building Perl with sfio:<p>

<DL>

<DT><EM>Perl5 can now use alternate file IO mechanisms to ANSI stdio.
However these are experimental and may cause problems with some
extension modules.
Use stdio as with previous versions? [y] </EM></DT>
<DD>
You should answer no.
</DD><P>

<DT><EM>Any additional cc flags?</EM></DT>
<DD>
You should use the following cc flags along with any defaults that Perl
Configure supplied:
<UL>
<LI> <strong>-I<em>$sfio</em>/include</strong>
</UL>
</DD><P>

<DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
<DD>
You should specify the following <tt>ld</tt> flags:
<UL>
<LI> <strong>-L<em>$sfio</em>/lib</strong>
</UL>
</DD><P>

<DT><EM>Additional Libraries:</EM></DT>
<DD>
Check that <strong>-lsfio</strong> is one of the specified libraries.  Press 
return key to continue.  
</DD><P>
</DL>

<b>NOTE</b>: If you did not install Perl as a root user, make sure to 
correctly set environment variable <tt>PERL5LIB</tt> to indicate the location
of Perl libraries.  For example, if you installed Perl binary into the 
<tt>$INSTALL</tt> subdirectory and you are running Solaris, the following 
will set your proper library path: 
<pre>
% setenv PERL5LIB $INSTALL/lib:$INSTALL/lib/sun4-solaris/perl5.003_02
</pre>

<p>

  <li>Obtain Perl/Sfio module for FastCGI support from 
      <a href="ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO">
      ftp://ftp.funet.fi/pub/languages/perl/CPAN/authors/id/SKIMO</a><p>

  <li>Unpack FCGI module using <tt>tar</tt> command.  We use <tt>$sfiomod</tt>
      to denote the subdirectory that is created in the process.<p>

  <li>Build and install the module with the following commands:
<pre>
% cd $sfiomod
% $INSTALL/bin/perl Makefile.PL
% make
% make test
% make install
</pre>
</ol>


<H3><a NAME = "S3">3. Perl with fcgi_stdio and an FCGI module</a></H3>

<H4><a NAME = "S3.1">3.1 Basic recipe</a></H4>

Here are the assumptions embedded in the following recipe:
<UL>

<LI>You are building Perl 5.0 Patch 2 (5.002) or higher, since 
all examples that are provided are based on that release.
<P></P>

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

<LI> <EM>$fcgi</EM> is used as shorthand for the full path of the FastCGI
developers kit.
</UL>
<P>
If those are valid assumptions, follow these steps:
<OL>
<LI> Pull the Perl source kit from
<A HREF="http://www.metronet.com/perlinfo/src/latest.tar.gz">
http://www.metronet.com/perlinfo/src/latest.tar.gz</A>
<P>
There are good sources of information on Perl at:
<UL>
<LI> <A HREF="http://www.perl.com/">http://www.perl.com/</A>
<LI> <A HREF="http://www.metronet.com/perlinfo/">http://www.metronet.com/perlinfo/</A>
</UL>
<p></P>

<LI> Unpack the tar file in the parent directory of the FastCGI kit
directory, so that the perl directory is a sibling of <tt>fcgi-devel-kit</tt>.
<EM>$perl</EM> is used as shorthand for the full path of the directory
in which Perl is installed.
<p>
<LI> Copy the version specific and the common files from
<tt>fcgi-devel-kit/perl-5</tt> into the Perl-5 kit.
<PRE>
> cd $perl
> mv perl.c perl.c.orig
> mv proto.h proto.h.orig
> mv Configure Configure.orig
> cp -r ../fcgi-devel-kit/perl-5/perl5.002/* .
> cp -r ../fcgi-devel-kit/perl-5/common/* .
</PRE>
<P>
The files you are copying contain the Perl-5 FCGI extension, some
files modified from the distribution, and a script to simplify the
configuration process.
</P>
<LI> Set environment variables.
The Perl-5 FastCGI configuration process requires that the environment
variable <TT>FCGIDIR</TT> be set to the top level directory of the FastCGI
development kit.
<PRE>
> setenv FCGIDIR <EM>$fcgi</EM>
</PRE>
If you do not want to use <tt>gcc</tt> to build Perl you can set the
environment variable <TT>CC</TT> to the desired compiler. For example:
<PRE>
> setenv CC gcc2.7
</PRE>
By default Perl's installation prefix is /usr/local, so binaries get
installed in /usr/local/bin, library files get installed into
/usr/local/lib/perl, etc. If you want to specify a different installation
prefix set the environment variable <tt>PERL_PREFIX</tt>.
<PRE>
> setenv PERL_PREFIX /usr/local/perl5-fcgi
</PRE>
<LI> Run fcgi-configure.
<PRE>
> ./fcgi-configure
</PRE>
<P>
<TT>fcgi-configure</TT> is a wrapper around Perl's <tt>Configure</tt> script.
It sets some variables according the the value of some environment variables,
and runs Perl's <tt>Configure</tt> script
in such a way that it does not prompt the
user for any input. 90% of the time this should work without a problem.
If for some reason this does not work for you, you'll have to
follow the steps in the next section.<p>
<LI> Run make.
<PRE>
> make
</PRE>
<LI> Install the newly built Perl-5.
<PRE>
> make install
</PRE>
</OL><p>


<H4><a NAME = "S3.2">3.2 Semi-advanced recipe</a></H4>

If you do not have experience configuring and building Perl, you
should find someone who does.  Perl can be pretty intimidating to configure
since it asks you a large number of irrelevant-seeming
questions that you won't know how to answer.<p>
<P>
<OL>
<LI>Go into the top level directory of the Perl distribution and run
<tt>Configure</tt>.
<PRE>
> cd $perl
> ./Configure
</PRE>
<LI>
There are some questions that you are going to
have to answer differently when building FastCGI into Perl.
These are described below:
<P></P>
<DL>
<DT><EM>Use which C compiler?</EM></DT>
<DD>
You should specify <tt>gcc</tt>.
</DD>
<P></P>
<DT><EM>Any additional cc flags?</EM></DT>
<DD>
You should use the following cc flags along with any defaults that Perl
Configure supplied:
<UL>
<LI> <strong>-I<em>$fcgi</em>/include</strong>
<LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong>
</UL>
This assumes you are using GCC.
</DD>
<P></P>

<DT><EM>Any additional ld flags (NOT including libraries):</EM></DT>
<DD>
You should specify the following <tt>ld</tt> flags:
<UL>
<LI> <strong>-L<em>$fcgi</em>/libfcgi</strong>
</UL
></DD>
<P></P>

<DT><EM>Additional Libraries:</EM></DT>
<DD>
add <strong>-lfcgi</strong> to the list of additional libraries.
It should be added before -lc.
</DD>
<P></P>

<DT><EM>What extensions do you wish to load dynamically?</EM></DT>
<DD>
If you can support dynamic extensions, <tt>Configure</tt>
will ask which of the
supplied extensions should be loaded dynamically. Since we copied the FCGI
extension into the Perl source directory it should be one of the ones in the
default list. If you want FCGI to be dynamically loaded you should specify
it here, otherwise leave it out.
</DD>
<P></P>

<DT><EM>What extensions do you wish to load statically?</EM></DT>
<DD>
If you do not support Dynamic extensions this is the only question about
extensions you would get asked. You should specify FCGI here if you did not
get asked about dynamic extensions (or did not specify FCGI as a dynamic
extension).
</DD>
</DL>
<P></P>
<LI> Copy in the new <tt>proto.h</tt>.
<P>
The file proto.h has some macros that conflict with the FastCGI macros.
The version of <tt>proto.h</tt> supplied in the FastCGI kit
includes these changes:<p>
<UL>
<LI> At the beginning of the file it adds the following lines:
<PRE>
#ifdef _FCGI_STDIO
#undef printf
#endif
</PRE>
<LI> At the bottom it adds:
<PRE>
#ifdef _FCGI_STDIO
#define printf FCGI_printf
#endif
</PRE>
</UL>
<LI> Copy in the new <tt>perl.c</tt>.
<P>
Perl-5.002 has a bug in <tt>perl.c</tt> that has a great
chance of getting exercised
with FastCGI.  A fix has been sumbitted to the Perl developers and hopefully
it'll make it into perl-5.003. It was a one line fix, here is a diff for the
curious:
<PRE>
*** perl.c      1996/03/15 17:10:10     1.1
--- perl.c      1996/03/15 17:11:23
***************
*** 405,410 ****
--- 405,411 ----
      if (e_fp) {
	if (Fflush(e_fp) || ferror(e_fp) || fclose(e_fp))
	    croak("Can't write to temp file for -e: %s", Strerror(errno));
+	e_fp = Nullfp;
	argc++,argv--;
	scriptname = e_tmpname;
      }
</PRE>
Pretty straightforward.<p>
<LI> Build and install Perl.
<PRE>
> make
<EM>[...]</EM>
> make install
</PRE>

<p></P>
<H4><a NAME = "S3.3">3.3 Advanced recipe</a></H4>

<P>
If you already have a Perl-5 package that has been configured, and you do
not really want to re-run Configure, you can take the following steps.
</P>
<P ALIGN=CENTER><STRONG>THIS IS NOT RECOMMENDED</STRONG></P>
<P>
Edit config.sh with your favorite editor and modify the following lines:
        <DL> 
          <DT><EM>cc</EM></DT>
          <DD> Change to use gcc if you are not using it already. </DD>
          <P></P>
          <DT><EM>ccflags</EM> AND <EM>cppflags</EM></DT>
          <DD> Add the following flags: 
            <UL>
              <LI> <strong>-I<em>$fcgi</em>/include</strong> 
              <LI> <strong>-include <em>$fcgi</em>/include/fcgi_stdio.h</strong> 
            </UL>
            This assumes you are using GCC. See the above section on assumptions 
          </DD>
          <P></P>
          <DT><EM>extensions</EM> AND <EM>known_extensions</EM></DT>
          <DD> Add FCGI to the list of extensions </DD>
          <P></P>
          <DT><EM>ldflags</EM></DT>
          <DD> Add -L $fcgi/libfcgi to the list. </DD>
          <P></P>
          <DT><EM>libs</EM></DT>
          <DD> Add -lfcgi to the list of libraries, should be added before -lc. 
          </DD>
          <P></P>
          <DT><EM>static_ext</EM><STRONG> or </STRONG><EM>dynamic_ext</EM></DT>
          <DD> Add FCGI to the list of statically or dynamically loaded extensions. 
          </DD>
          <P></P>
          <DT><EM>d_stdio_cnt_lval, d_stdio_ptr_lval, d_stdiobase, d_stdstdio</EM></DT>
          <DL> Change all of these to undef. </DL>
          <P> One you have edited config.sh you should do a "make Makefile depend 
            all". If you're paranoid like me you may want to do a "make clean" 
            first. </P>
          <H3><A NAME = "S4"> 4. Writing FastCGI applications in Perl</A></H3>
          <P> The Perl program <tt>examples/tiny-perl-fcgi</tt> performs the same 
            function as the C program <tt>examples/tiny-fcgi</tt> that's used 
            as an example in the <A HREF="fcgi-devel-kit.htm#S3.1.1">FastCGI Developer's 
            Kit</A>. Here's what the Perl version looks like: </P>
          <pre>
#!./perl
use FCGI;
$count = 0;
while(FCGI::accept() >= 0) {
    print("Content-type: text/html\r\n\r\n",
          "&lt;title&gt;FastCGI Hello! (Perl)&lt;/title&gt;\n",
          "&lt;h1&gt;FastCGI Hello! (Perl)&lt;/h1&gt;\n",
          "Request number ", $++count,
          " running on host &lt;i&gt;$ENV('SERVER_NAME')&lt;/i&gt;");
}
</pre>
          If you've built Perl 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 Perl application now. 
          <p> The script invokes Perl indirectly via the symbolic link <tt>examples/perl</tt>. 
            It does this because HP-UX has a limit of 32 characters for the first 
            line of a command-interpreter file such as <tt>examples/tiny-perl-fcgi</tt>. 
            If you run on HP-UX you won't want to sprinkle symbolic links to perl 
            everywhere, so you should choose a <tt>PERL_PREFIX</tt> shorter than 
            <tt>/usr/local/perl5-fcgi</tt>.
          <p> You need to be aware of the following bug. If the initial environment 
            to a FastCGI Perl application is empty (contains no name-value pairs) 
            then when the first call to <tt>FCGI::accept</tt> returns, the environment 
            will <i>still</i> be empty, i.e. <tt>%ENV</tt> will contain no associations. 
            All the variables associated with the first request are lost. There 
            are two known workarounds:
          <p> 
          <ul>
            <li> In your Perl application, enumerate <tt>%ENV</tt> using <tt>each</tt> 
              before entering the <tt>FCGI::accept</tt> loop. The program <tt>examples/tiny-perl-fcgi</tt> 
              contains code for this. 
              <p> 
            <li> In configuring your application be sure to set at least one initial 
              environment variable. You do this with the <tt>AppClass -initial-env</tt> 
              directive to the Web server, or by running <tt>cgi-fcgi</tt> in 
              a non-empty environment. 
          </ul>
          <p> The Perl subroutine <tt>FCGI::accept</tt> treats the initial environment 
            differently than the C function <tt>FCGI_Accept</tt>. The first call 
            to the C function <tt>FCGI_Accept</tt> replaces the initial environment 
            with the environment of the first request. The first call to the Perl 
            subroutine <tt>FCGI::accept</tt> adds the variable bindings of the 
            first request to the bindings present in the initial environment. 
            So when the first call to <tt>FCGI::accept</tt> 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 <tt>FCGI::accept</tt> removes the bindings made on 
            the previous call before adding a new set for the request just accepted, 
            again preserving the initial environment.
          <p> The Perl <tt>FCGI</tt> module also includes subroutines <tt>FCGI::finish</tt>, 
            <tt>FCGI::set_exit_status</tt>, and <tt>FCGI::start_filter_data</tt> 
            that correspond to C functions in <tt>fcgi_stdio.h</tt>; see the manpages 
            for full information.
          <p> Converting a Perl 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 <tt>FCGI::accept</tt>.
          <p> 
        </dl>
      </ol></ol></body>
</html>
Commit	Line	Data
0198fd3c	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>
6791223e	9	<a href="http://fastcgi.com">
6791223e	10	<img border=0 src="../images/fcgi-hd.gif" alt="[[FastCGI]]"></a>
0198fd3c	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 © 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>
6791223e	24	$Id: fcgi-perl.htm,v 1.2 2001/05/14 13:00:30 robs Exp $ <br>
0198fd3c	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.
6791223e	53
0198fd3c	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>
6791223e	174
0198fd3c	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>
6791223e	231	<p></P>
6791223e	232
0198fd3c	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
6791223e	338	></DD>
0198fd3c	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>
6791223e	415
6791223e	416	<p></P>
0198fd3c	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:
6791223e	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>
0198fd3c	464	#!./perl
	465	use FCGI;
	466	$count = 0;
	467	while(FCGI::accept() >= 0) {
	468	print("Content-type: text/html\r\n\r\n",
	469	"<title>FastCGI Hello! (Perl)</title>\n",
	470	"<h1>FastCGI Hello! (Perl)</h1>\n",
	471	"Request number ", $++count,
	472	" running on host <i>$ENV('SERVER_NAME')</i>");
	473	}
	474	</pre>
6791223e	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>
0198fd3c	525	</html>