Writing Apache Modules with Perl and C By:   Lincoln Stein and Doug MacEachern Published:   O'Reilly & Associates, Inc.  - March 1999 Copyright © 1999 by O'Reilly & Associates, Inc.

Chapter 2 - A First Module
Preliminaries

In this section...

Introduction A Working Apache Web Server A C Compiler and make Utility A Complete Perl Installation Recent Versions of CGI.pm and LWP

Introduction

Before you can start hacking away at your own Apache modules, there are a number of preliminaries to take care of. This section discusses what you need and how you can get it if you don't have it already.

A Working Apache Web Server

You'll need a working version of Apache, preferably a recent release (the version we used to prepare this book was Version 1.3.4). If you do not already have Apache, you can download it, free of charge, from http://www.apache.org/.

Users of Windows 95 and NT systems (henceforth called "Win32") who want to write modules using the Perl API can download precompiled binaries. You will need two components: the server itself, available at http://www.apache.org/dist/, and ApacheModulePerl.dll, which is mod_perl implemented as a dynamically loadable module. ApacheModulePerl.dll has been made available by Jeffrey W. Baker. You can find it on the Comprehensive Perl Archive Network (CPAN) in the directory authors/Jeffrey_Baker/.¹ Win32 users with access to the Microsoft Visual C++ development environment can also compile ApacheModulePerl.dll from mod_perl source code.

This book will not try to teach you how to install and maintain an Apache-based web site. For the full details, see the Apache server's excellent online documentation or the reference books listed in the preface.

A C Compiler and make Utility

To use the C API, you'll need a working C compiler and its associated utilities. Most Unix systems come with the necessary software development tools preinstalled, but sometimes the bundled tools are obsolete or nonstandard (SunOS and HP-UX systems are particularly infamous in this regard). To save yourself some headaches, you may want to install the GNU gcc compiler and make programs. They are available via anonymous FTP from prep.ai.mit.edu, in the directory /pub/gnu, or via the web at http://www.gnu.org/.

Win32 users are not so lucky. To develop C API modules, you will need the Microsoft Visual C++ 5.0 development package. No other development environment is guaranteed to work, although you are certainly welcome to try; Borland C++ is reported to work in some people's hands. If you are primarily interested in the Perl API, you can use the precompiled binaries mentioned in the previous section.

A Complete Perl Installation

To use the Perl API, you will need a full installation of Perl, Version 5.004 or higher. In many cases, this means that you will have to download and install Perl yourself. We have found that some systems that come with Perl preinstalled are missing some of the essential parts of the library hierarchy needed to create and install new Perl modules. This includes certain Linux distributions. Find the Perl source distribution at any of the CPAN sites, download it, and install it according to the directions. This book was prepared using Perl Version 5.004_04.

During installation Perl creates a library file containing all its core routines. On some Unix systems, Perl will offer you the choice between building a statically linked library (usually named libperl.a) or building a shared library (named libperl.so or libperl.o). Unless you're going to be linking many different executables to Perl, there's no compelling reason to create a shared library. Most sites will have only two executables linked to Perl: the Apache server daemon and the perl program itself. Under these circumstances the memory saved by using the shared version is inconsequential compared to the execution overhead of using the shared library. We recommend that you build the statically linked library unless you are going to build multiple embedded Perl systems.

Recent Versions of CGI.pm and LWP

While not strictly necessary, your life will be easier if you have recent versions of the Perl CGI.pm and LWP modules installed. CGI.pm is a collection of utilities that makes conventional CGI scripts easier to write. It also comes in handy for modules written with the mod_perl API. We recommend using Version 2.42 or higher.

LWP (Library for WWW access in Perl) is a collection of modules for creating web robots, agents, and browsers in Perl. LWP is invaluable for creating web proxies, and we make use of it in later chapters. More important, mod_perl uses LWP during installation for regression testing. We recommend using LWP Version 5.36 or higher.

Both CGI.pm and LWP can be found on CPAN, in the subdirectories modules/by-module/CGI and modules/by-module/LWP. Complete installation directions can be found in the packages themselves.

Footnotes

¹ See the preface for instructions on finding and using a CPAN site close to you.