1. 介绍性指南
mod_perl 是个庞大而复杂的工具，它内建了许多模块帮助你方便地构建动态网站。这篇指南的目的是帮助你构建一个良好的 mod_perl 模块，并从中理解 mod_perl 的实现技术。我并不推荐使用这里介绍的技术来建立一个大型站点，尤其对于一个刚刚涉足 mod_perl 的人来说。但我推荐大家可以深入看一下它的一些内建的方案，比如 mason, axkit, embperl, apache::asp 和 pagekit 等等。
1.1. 你需要什么?
本指南假设你已经有过安装和测试 mod_perl 的经验。以及较新版本的 apache 的安装经验。因为有可能你需要在你的机器上实现时适当的修改本文提供的配置。我们需要你安装一些模块并且需要进入 apache 的配置目录作修改。所以最好你有 root 权限来做这些事情。当然你还需要一个文本编辑器。
1.2. 切入正题
mod_perl 模块也是 perl 模块，但它有较为特别的设计。最方便的创建一个 perl 模块的方法就是使用标准的 perl 分发自带的工具 h2xs 。你可以在命令行模式键入 h2xs 来看看它的参数列表。现在，到一个适当的目录开始一个新项目，键入:
h2xs -a -x -n apache::tutorial::first
h2xs 将会创建目录 apache, 以及其他一些子目录.现在进入最深一级的目录看看:
cd apache/tutorial/first
在这个新目录里面，你可以看到 5 个文件: changes, first.pm, manifest, makefile.pl 和 test.pl。它们的作用如下:
changes
这个文件作为你的项目的修改日志（changelog）文件
first.pm
这是主模块文件，包含你的 mod_perl 句柄代码（handler code）。
manifest
本文件用于自动构建 tar.gz 类型的模块版本分发。这样你就可以把你的模块拿到 cpan 发布或者分发给其他人。它包含了你在这个项目中所有文件的列表。
makefile.pl
这是标准的 perl makefile 构造器。用于创建 makefile.pl 文件来编译该模块。
test.pl
针对该模块的一些测试脚本。默认情况下它只是检查模块的编译和载入
好了，现在我们开始把 first.pm 变为可工作的 mod_perl 模块。使用文本编辑器打开该文件，修改后的内容如下:
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;
不要忘记文件末尾的"1;"，对于 perl 来说，一个模块最后返回的非零值表示该模块已经被成功编译。
1.3. 安装你的模块
h2xs 工具使我们的模块安装工作极为方便。在和你的 first.pm 文件相同的目录中。、，键入:
perl makefile.plmakemake test
如果 make test 成功的话，你需要以 root 身份执行:
make install
这样你就把你的模块安装到了 perl 的库目录（library directory）。
1.4. 添加该模块为 apache 的一个句柄（handler）
现在我们需要进入 apache 配置目录来修改配置文件，使我们的模块作为 apache 内容处理阶段的处理器。打开 httpd.conf 文件，在末尾加入如下配置:
<location /mod_perl_tutorial> sethandler perl-script perlhandler apache::tutorial::first</location>
然后保存配置文件，并且重新启动 apache 服务器:
apachectl stopapachectl start
现在使用浏览器访问 http://localhost/mod_perl_tutorial ，你将如期的看到显示 "hello world" 页面。
2. 这里都发生了些什么?
好，在这里都发生了什么事情呢?
当 apache 启动的时候，它读取它的配置指令并把适当的命令传递给相应的处理该命令的模块。这里有两个相关的指令 sethandler 和 perlhandler.
第一个指令 sethandler 由 mod_mime 模块处理，该指令表示使用什么模块作为处理请求的主要部分。这里所设置的 perl-script 表示使用 mod_perl 来处理请求。
第二个指令 perlhandler 由 mod_perl 模块来处理，它只是简单的说明使用我们的模块来处理请求的主要部分。有一点需要注意，无论何时在你有一个 perlhandler 时，你需要相应的 sethandler perl-script 配置指令。这样才能使你的 mod_perl 代码起作用。我总是认为这是一个弱点，但这将涉及 apache 内部的处理机制，所以在将来这也很难改变。
现在请求来了，apache 查看用什么模块来处理相应的 uri 并且在这里决定使用 mod_perl，而 mod_perl 知道它必须把请求发送给我们的模块，并调用我们模块的 handler() 函数作为 apache::request 对象的第一个参数。而我们的 handler() 函数的返回值决定了下一步 apache 将要做什么。现在我们知道返回值 ok 意味着一切成功。 ok 是个从 apache::constants 模块导出的常量。
3. 调试
如果你没有看到 "hello world", 那你可能看到了一个错误页面，或者其他什么完全不同的。第一步去查看错误日志看看到底是什么发生了错误。我习惯于在浏览器中请求后立即查看错误日志。你可以使用 tail 工具:
tail -f /path/to/apache/logs/error_log
(使用你的真实 error_log 路径替换上面的路径。如果你不肯定它在哪里，查看你的 httpd.conf 文件的 errorlog 指令部分)
现在重新载入页面，然后 error_log 将告诉你什么地方出现了问题。更多的关于 perl 调试，请参见 perldebug.
4. 加入更多
现在如果你想要针对上面的情况作一些修改，该如何做呢？不幸的，唯一一种安装模式如下:
修改你的 first.pm 文件
重新以 root 身份运行 make install
重新启动 apache
这也许很麻烦，特别是重新启动 apache。针对这个问题，我们可以另外安装一个特别设计的模块来避免每次这样麻烦的做。首先你需要从 cpan 下载并安装 apache::reload 模块（除非你已经使用 mod_perl 1.26 或者更高版本）。在这里 http://search.cpan.org/search?dist=apache-reload 下载。
解开 tar.gz 文件并进入新目录，执行:
perl makefile.plmake
然后到 root 身份执行:
make install
现在再次打开 httpd.conf 文件，加入:
perlinithandler apache::reload
这将测试所有有所改变的模块并在必要时自动重新载入新模块。这对于开发来说很有用，但会有性能损失，所以在开发完成之后，就将该特性关闭。
5. 阅读更多
从这里开始你有很多事情需要去做。apache api 本身就十分庞大，大多数都可以通过 perldoc apache 看到相应的文档. 现在这个模块基本上没有什么价值，因为只有一个 uri 可以用于被该模块所控制(http://server/mod_perl_tutorial)，这使得它变得不够灵活。为了使一个模块可以处理多个 uri ，有许多解决办法，但最好的还是推荐使用 apache::dispatch 模块。可以在 cpan 下载 http://search.cpan.org/search?dist=apache-dispatch. apache::dispatch 允许你保留标准的 mod_perl handler 构架，同时还允许多个函数和多个uris 被派发。
接下来我不建议象例子中一样直接向浏览器输出内容。请考虑使用一些常用的模版技术，比如 template-toolkit, html::template, 更甚于使用 xslt 或者 xpathscript （有很多很多这样的模版技术可选，我们希望有一天可以有文章来讨论这些技术来帮助你来选择）。
