Introductory Guide
mod_perl is a huge and complex tool. It has many built-in modules to help you easily build dynamic websites. The purpose of this guide is to help you build a good mod_perl module and understand the implementation technology of mod_perl. I do not recommend using the technology introduced here to build a large site, especially for someone who has just gotten into mod_perl. But I recommend you to take a closer look at some of its built-in solutions, such as Mason, AxKit, EmbPerl, Apache::ASP and PageKit, etc.
What do you need?
This guide assumes that you have experience in installing and testing mod_perl. And the installation experience of newer versions of Apache. Because it is possible that you need to modify the configuration provided in this article appropriately when implementing it on your machine. We need you to install some modules and need to enter the Apache configuration directory for modification. So it's better that you have root permissions to do these things. Of course you also need a text editor.
Get to the point
The mod_perl module is also a Perl module, but it has a special design. The most convenient way to create a Perl module is to use the standard Perl distribution tool h2xs. You can type h2xs in command line mode to see its parameter list. Now, start a new project in an appropriate directory, type:h2xs-AX-n Apache::Tutorial::Firsth2xs will create the directory Apache, as well as some other subdirectories. Now enter the deepest directory to see:cd Apache/Tutorial/First In this new directory, you can see 6 files: README, Changes, , MANIFEST, and . Their functions are as follows:
README
This file contains some installation information, module dependencies, copyright information, etc.
Changes
This file serves as the changelog file for your project
This is the main module file, which contains your mod_perl handle code (handler code).
MANIFEST
This file is used to automatically build the module version distribution of types. In this way, you can take your module to CPAN and publish or distribute it to others. It contains a list of all the files you have in this project.
This is the standard Perl Makefile constructor. Used to create a file to compile the module.
Some test scripts for this module. By default it just checks the loading of the module, you can add some new test units. OK, now we start to turn into a working mod_perl module. Open the file using a text editor, and the modified content is as follows:
package Apache::Tutorial::First;
use strict;
use vars qw/$VERSION/;
use Apache::Constants;
$VERSION = 0.01;
sub handler {
my $r = shift;
$r->send_http_header('text/html');
print
"<html><body>Hello World</body></html>";
return OK;
}
1;
Don't forget "1;" at the end of the file. For Perl, the non-zero value returned by a module indicates that the module has been successfully compiled.
Install your module
The h2xs tool makes our module installation extremely convenient. In the same directory as your file. Type:
perl
make
make test If make test is successful, you need to execute it as root:
make install so that you install your module in the perl library directory.
Add this module as a handler (handler) to Apache
Now we need to enter the Apache configuration directory to modify the configuration file, so that our module can be used as the processor of the Apache content processing stage. Open the file and add the following configuration at the end:
<Location /mod_perl_tutorial>
SetHandler perl-script
PerlHandler Apache::Tutorial::First
Then save the configuration file and restart the apache server:
apachectl stop
apachectl start Now use your browser to access http://localhost/mod_perl_tutorial, and you will see the "Hello World" page as scheduled.
When Apache starts, it reads its configuration instructions and passes the appropriate commands to the corresponding module that handles the command. Here are two related instructions, SetHandler and PerlHandler.
The first instruction, SetHandler, is processed by the mod_mime module, which indicates which module is used as the main part of processing the request. The perl-script set here means using mod_perl to process the request.
The second instruction PerlHandler is handled by the mod_perl module, which is simply a description of the main part of the request using our module. One thing to note is that whenever you have a PerlHandler, you need the corresponding SetHandler perl-script configuration directive. This will make your mod_perl code work. I always think this is a weakness, but this will involve the internal processing mechanism of Apache, so this will be difficult to change in the future.
Now that the request is here, Apache sees what module is used to handle the corresponding URI and decides to use mod_perl here, and mod_perl knows that it must send the request to our module and calls our module's handler() function as the first parameter of the Apache::Request object. And the return value of our handler() function determines what Apache will do next. Now we know that the return value OK means everything is successful. OK is a constant exported from the Apache::Constants module.
debug
If you don't see "Hello World", then you may have seen an error page, or something completely different. The first step is to check the error log to see what the error occurred. I'm used to viewing the error log right after requesting in the browser. You can use the tail tool: tail -f /path/to/apache/logs/error_log (replace the path above with your real error_log. If you are not sure where it is, check the ErrorLog directive section of your file)
Now reload the page and then error_log will tell you where the problem is happening. For more information about perl debugging, see perldebug.
Join more
Now if you want to make some modifications to the above situation, what should you do? Unfortunately, the only installation mode is as follows:
Modify your file
Run as root again make install
Restart Apache
This may be troublesome, especially restarting Apache. To address this problem, we can install another specially designed module to avoid such troublesome tasks every time. First you need to download and install the Apache::Reload module from CPAN (unless you have already used mod_perl 1.26 or later). Download here /search?dist=Apache-Reload.
Unlock the file and enter a new directory and execute:
perl
Make and then execute in the root identity:
make install now open the file again, add:
PerlInitHandler Apache::Reload This will test all modules that have changed and automatically reload new modules if necessary. This is useful for development, but there will be performance losses, so after development is completed, the feature is turned off.
Read more
From here you have a lot to do. The Apache API itself is very large, and most of them can see the corresponding documents through perldoc Apache. Now this module is basically of no value, because there is only one URI that can be used to be controlled by the module (http://server/mod_perl_tutorial), which makes it inflexible. There are many solutions to make a module able to handle multiple URIs, but the best thing is to recommend using the Apache::Dispatch module.
You can download /search?dist=Apache-Dispatch on CPAN. Apache::Dispatch allows you to retain the standard mod_perl handler architecture, and also allows multiple functions and multiple URIs to be distributed.
Next, I do not recommend directly outputting content to the browser like in the example. Please consider using some commonly used template technologies, such as Template-Toolkit, HTML::Template, and more so than using XSLT or XPathScript (there are many, many such template technologies to choose from, and we hope one day there will be articles to discuss these technologies to help you choose).
mod_perl is a huge and complex tool. It has many built-in modules to help you easily build dynamic websites. The purpose of this guide is to help you build a good mod_perl module and understand the implementation technology of mod_perl. I do not recommend using the technology introduced here to build a large site, especially for someone who has just gotten into mod_perl. But I recommend you to take a closer look at some of its built-in solutions, such as Mason, AxKit, EmbPerl, Apache::ASP and PageKit, etc.
What do you need?
This guide assumes that you have experience in installing and testing mod_perl. And the installation experience of newer versions of Apache. Because it is possible that you need to modify the configuration provided in this article appropriately when implementing it on your machine. We need you to install some modules and need to enter the Apache configuration directory for modification. So it's better that you have root permissions to do these things. Of course you also need a text editor.
Get to the point
The mod_perl module is also a Perl module, but it has a special design. The most convenient way to create a Perl module is to use the standard Perl distribution tool h2xs. You can type h2xs in command line mode to see its parameter list. Now, start a new project in an appropriate directory, type:h2xs-AX-n Apache::Tutorial::Firsth2xs will create the directory Apache, as well as some other subdirectories. Now enter the deepest directory to see:cd Apache/Tutorial/First In this new directory, you can see 6 files: README, Changes, , MANIFEST, and . Their functions are as follows:
README
This file contains some installation information, module dependencies, copyright information, etc.
Changes
This file serves as the changelog file for your project
This is the main module file, which contains your mod_perl handle code (handler code).
MANIFEST
This file is used to automatically build the module version distribution of types. In this way, you can take your module to CPAN and publish or distribute it to others. It contains a list of all the files you have in this project.
This is the standard Perl Makefile constructor. Used to create a file to compile the module.
Some test scripts for this module. By default it just checks the loading of the module, you can add some new test units. OK, now we start to turn into a working mod_perl module. Open the file using a text editor, and the modified content is as follows:
package Apache::Tutorial::First;
use strict;
use vars qw/$VERSION/;
use Apache::Constants;
$VERSION = 0.01;
sub handler {
my $r = shift;
$r->send_http_header('text/html');
"<html><body>Hello World</body></html>";
return OK;
}
1;
Don't forget "1;" at the end of the file. For Perl, the non-zero value returned by a module indicates that the module has been successfully compiled.
Install your module
The h2xs tool makes our module installation extremely convenient. In the same directory as your file. Type:
perl
make
make test If make test is successful, you need to execute it as root:
make install so that you install your module in the perl library directory.
Add this module as a handler (handler) to Apache
Now we need to enter the Apache configuration directory to modify the configuration file, so that our module can be used as the processor of the Apache content processing stage. Open the file and add the following configuration at the end:
<Location /mod_perl_tutorial>
SetHandler perl-script
PerlHandler Apache::Tutorial::First
Then save the configuration file and restart the apache server:
apachectl stop
apachectl start Now use your browser to access http://localhost/mod_perl_tutorial, and you will see the "Hello World" page as scheduled.
When Apache starts, it reads its configuration instructions and passes the appropriate commands to the corresponding module that handles the command. Here are two related instructions, SetHandler and PerlHandler.
The first instruction, SetHandler, is processed by the mod_mime module, which indicates which module is used as the main part of processing the request. The perl-script set here means using mod_perl to process the request.
The second instruction PerlHandler is handled by the mod_perl module, which is simply a description of the main part of the request using our module. One thing to note is that whenever you have a PerlHandler, you need the corresponding SetHandler perl-script configuration directive. This will make your mod_perl code work. I always think this is a weakness, but this will involve the internal processing mechanism of Apache, so this will be difficult to change in the future.
Now that the request is here, Apache sees what module is used to handle the corresponding URI and decides to use mod_perl here, and mod_perl knows that it must send the request to our module and calls our module's handler() function as the first parameter of the Apache::Request object. And the return value of our handler() function determines what Apache will do next. Now we know that the return value OK means everything is successful. OK is a constant exported from the Apache::Constants module.
debug
If you don't see "Hello World", then you may have seen an error page, or something completely different. The first step is to check the error log to see what the error occurred. I'm used to viewing the error log right after requesting in the browser. You can use the tail tool: tail -f /path/to/apache/logs/error_log (replace the path above with your real error_log. If you are not sure where it is, check the ErrorLog directive section of your file)
Now reload the page and then error_log will tell you where the problem is happening. For more information about perl debugging, see perldebug.
Join more
Now if you want to make some modifications to the above situation, what should you do? Unfortunately, the only installation mode is as follows:
Modify your file
Run as root again make install
Restart Apache
This may be troublesome, especially restarting Apache. To address this problem, we can install another specially designed module to avoid such troublesome tasks every time. First you need to download and install the Apache::Reload module from CPAN (unless you have already used mod_perl 1.26 or later). Download here /search?dist=Apache-Reload.
Unlock the file and enter a new directory and execute:
perl
Make and then execute in the root identity:
make install now open the file again, add:
PerlInitHandler Apache::Reload This will test all modules that have changed and automatically reload new modules if necessary. This is useful for development, but there will be performance losses, so after development is completed, the feature is turned off.
Read more
From here you have a lot to do. The Apache API itself is very large, and most of them can see the corresponding documents through perldoc Apache. Now this module is basically of no value, because there is only one URI that can be used to be controlled by the module (http://server/mod_perl_tutorial), which makes it inflexible. There are many solutions to make a module able to handle multiple URIs, but the best thing is to recommend using the Apache::Dispatch module.
You can download /search?dist=Apache-Dispatch on CPAN. Apache::Dispatch allows you to retain the standard mod_perl handler architecture, and also allows multiple functions and multiple URIs to be distributed.
Next, I do not recommend directly outputting content to the browser like in the example. Please consider using some commonly used template technologies, such as Template-Toolkit, HTML::Template, and more so than using XSLT or XPathScript (there are many, many such template technologies to choose from, and we hope one day there will be articles to discuss these technologies to help you choose).