=head1 NAME
Getting Your Feet Wet with mod_perl
=head1 Description
This chapter gives you the bare minimum information to get you started
with mod_perl 2.0. For most people it's sufficient to get going.
=head1 Installation
If you are a Win32 user, please refer to the L<Win32 installation
document|docs::2.0::os::win32::install>.
First, L<download|download::index> the mod_perl 2.0 source.
Before installing mod_perl, you need to check that you have the
L<mod_perl 2.0
prerequisites|docs::2.0::user::install::install/Prerequisites> B<installed>.
Apache and the right Perl version have to be built and installed
B<before> you can proceed with building mod_perl.
In this chapter we assume that httpd and all helper files were
installed under I<$HOME/httpd/prefork>, if your distribution doesn't
install all the files under the same tree, please refer to L<the
complete installation
instructions|docs::2.0::user::install::install/Installing_mod_perl_from_Source>.
Now, configure mod_perl:
% tar -xvzf mod_perl-2.x.xx.tar.gz
% cd modperl-2.0
% perl Makefile.PL MP_APXS=$HOME/httpd/prefork/bin/apxs
where C<MP_APXS> is the full path to the C<apxs> executable, normally
found in the same directory as the C<httpd> executable, but could be
put in a different path as well.
Finally, build, test and install mod_perl:
% make && make test && make install
Become I<root> before doing C<make install> if installing system-wide.
If something goes wrong or you need to enable optional features please
refer to L<the complete installation
instructions|docs::2.0::user::install::install/Installing_mod_perl_from_Source>.
=head1 Configuration
If you are a Win32 user, please refer to the L<Win32 configuration
document|docs::2.0::os::win32::config>.
Enable mod_perl built as DSO, by adding to I<httpd.conf>:
LoadModule perl_module modules/mod_perl.so
There are many other configuration options which you can find in the
L<configuration manual|docs::2.0::user::config::config>.
If you want to run mod_perl 1.0 code on mod_perl 2.0 server enable the
compatibility layer:
PerlModule Apache2::compat
For more information see: L<Migrating from mod_perl 1.0 to mod_perl
2.0|docs::2.0::user::porting::compat>.
=head1 Server Launch and Shutdown
Apache is normally launched with C<apachectl>:
% $HOME/httpd/prefork/bin/apachectl start
and shut down with:
% $HOME/httpd/prefork/bin/apachectl stop
Check I<$HOME/httpd/prefork/logs/error_log> to see that the server has
started and it's a right one. It should say something similar to:
[Fri Jul 22 09:39:55 2005] [notice] Apache/2.0.55-dev (Unix)
mod_ssl/2.0.55-dev OpenSSL/0.9.7e DAV/2 mod_perl/2.0.2-dev
Perl/v5.8.7 configured -- resuming normal operations
=head1 Registry Scripts
To enable registry scripts add the following to I<httpd.conf>:
Alias /perl/ /home/httpd/httpd-2.0/perl/
<Location /perl/>
SetHandler perl-script
PerlResponseHandler ModPerl::Registry
PerlOptions +ParseHeaders
Options +ExecCGI
Order allow,deny
Allow from all
</Location>
and now assuming that we have the following script:
#!/usr/bin/perl
print "Content-type: text/plain\n\n";
print "mod_perl 2.0 rocks!\n";
saved in I</home/httpd/httpd-2.0/perl/rock.pl>. Make the script
executable and readable by everybody:
% chmod a+rx /home/httpd/httpd-2.0/perl/rock.pl
Of course the path to the script should be readable by the server too.
In the real world you probably want to have a tighter permissions, but
for the purpose of testing that things are working this is just fine.
Now restart the server and issue a request to
I<http://localhost/perl/rock.pl> and you should get the response:
mod_perl 2.0 rocks!
If that didn't work check the I<error_log> file.
For more information on the registry scripts refer to the
C<L<ModPerl::Registry|docs::2.0::api::ModPerl::Registry>>
manpage. (XXX: one day there will a tutorial on registry, should port
it from 1.0's docs).
=head1 Handler Modules
Finally check that you can run mod_perl handlers. Let's write a
response handler similar to the registry script from the previous
section:
#file:MyApache2/Rocks.pm
#----------------------
package MyApache2::Rocks;
use strict;
use warnings;
use Apache2::RequestRec ();
use Apache2::RequestIO ();
use Apache2::Const -compile => qw(OK);
sub handler {
my $r = shift;
$r->content_type('text/plain');
print "mod_perl 2.0 rocks!\n";
return Apache2::Const::OK;
}
1;
Save the code in the file I<MyApache2/Rocks.pm>, somewhere where
mod_perl can find it. For example let's put it under
I</home/httpd/httpd-2.0/perl/MyApache2/Rocks.pm>, and we tell mod_perl
that I</home/httpd/httpd-2.0/perl/> is in C<@INC>, via a startup file
which includes just:
use lib qw(/home/httpd/httpd-2.0/perl);
1;
and loaded from I<httpd.conf>:
PerlRequire /home/httpd/httpd-2.0/perl/startup.pl
Now we can configure our module in I<httpd.conf>:
<Location /rocks>
SetHandler perl-script
PerlResponseHandler MyApache2::Rocks
</Location>
Now restart the server and issue a request to
I<http://localhost/rocks> and you should get the response:
mod_perl 2.0 rocks!
If that didn't work check the I<error_log> file.
=head1 Troubleshooting
If after reading the complete
L<installation|docs::2.0::user::install::install> and L<configuration
chapters|docs::2.0::user::config::config> you are still having
problems, take a look at the L<troubleshooting
sections|docs::2.0::user::troubleshooting::troubleshooting>. If the problem
persist, please report them using the L<following
guidelines|docs::2.0::user::help::help/Reporting_Problems>.
=head1 Maintainers
Maintainer is the person(s) you should contact with updates,
corrections and patches.
=over
=item *
Stas Bekman [http://stason.org/]
=back
=head1 Authors
=over
=item *
Stas Bekman [http://stason.org/]
=back
Only the major authors are listed above. For contributors see the
Changes file.
=cut