| =head1 NAME |
| |
| cgi_to_mod_perl - First steps needed to use mod_perl as a CGI replacement |
| |
| =head1 DESCRIPTION |
| |
| As the README and other mod_perl documents explain, mod_perl as |
| a CGI replacement is only a small piece of what the package offers. |
| However, it is the most popular use of mod_perl, this document is here |
| so you can cut to the chase. |
| |
| =head1 INSTALLATION |
| |
| Read the INSTALL document, in most cases, nothing more is required |
| than: |
| |
| perl Makefile.PL && make && make install |
| |
| =head1 CONFIGURATION |
| |
| For using mod_perl as a CGI replacement, the recommended configuration |
| is as follows: |
| |
| Alias /perl/ /real/path/to/perl-scripts/ |
| |
| <Location /perl> |
| SetHandler perl-script |
| PerlHandler Apache::Registry |
| Options +ExecCGI |
| </Location> |
| |
| `Location' refers to the uri, not a directory, think of the above as |
| |
| <Location http://www.yourname.com/perl> |
| |
| Any files under that location (which live on your filesystem under |
| /real/path/to/perl-scripts/), will be handled by the Apache::Registry |
| module, which emulates the CGI environment. The file must exist and |
| be executable, in addition, 'Options ExecCGI' must be turned on. |
| |
| If you wish to have mod_perl execute scripts in any location based on |
| file extension, use a configuration like so: |
| |
| <Files ~ "\.pl$"> |
| SetHandler perl-script |
| PerlHandler Apache::Registry |
| Options ExecCGI |
| </Files> |
| |
| Note that `ScriptAlias' does _not_ work for mod_perl. |
| |
| =head1 PORTING CGI SCRIPTS |
| |
| =over 4 |
| |
| =item I/O |
| |
| If you are using Perl 5.004 most CGI scripts can run under mod_perl |
| untouched. If you're using 5.003, Perl's built-in C<read()> and |
| C<print()> functions do not work as they do under CGI. If you're |
| using CGI.pm, use C<$query-E<gt>print> instead of plain 'ol C<print()>. |
| |
| =item HEADERS |
| |
| By default, mod_perl does not send any headers by itself, however, you |
| may wish to change this: |
| |
| PerlSendHeader On |
| |
| Now the response line and common headers will be sent as they are by |
| mod_cgi. And, just as with mod_cgi, PerlSendHeader will not send a |
| terminating newline, your script must send that itself, e.g.: |
| |
| print "Content-type: text/html\n\n"; |
| |
| If you're using CGI.pm and 'print $q-E<gt>header' you do |
| _not_ need C<PerlSendHeader On>. |
| |
| =item NPH SCRIPTS |
| |
| To run a CGI `nph' script under mod_perl, simply add to your code: |
| |
| local $| = 1; |
| |
| If you normally set B<PerlSendHeader On>, add this to your httpd.conf: |
| |
| <Files */nph-*> |
| PerlSendHeader Off |
| </Files> |
| |
| =item PROGRAMMING PRACTICE |
| |
| CGI lets you get away with sloppy programming, mod_perl does not. |
| Why? CGI scripts have the lifetime of a single HTTP request as a |
| separate process. When the request is over, the process goes away and |
| everything is cleaned up for you, e.g. globals variables, open files, |
| etc. Scripts running under mod_perl have a longer lifetime, over |
| several request, different scripts may be in the same process. This |
| means you must clean up after yourself. You've heard: |
| |
| always 'use strict' and C<-w>!!! |
| |
| It's more important under mod_perl Perl than anywhere else, while it's |
| not required, it B<strongly> recommended, it will save you more time |
| in the long run. And, of course, clean scripts will still run under |
| CGI! |
| |
| =item TRAPS |
| |
| See L<mod_perl_traps>. |
| |
| =back |
| |
| =head1 REPORTING PROBLEMS |
| |
| Read the L<SUPPORT> file. |
| |
| =head1 SEE ALSO |
| |
| Apache::PerlRun(3) |