perl the complete reference second edition phần 8 doc

Chapter 24: Cross-Platform Migration Traps
835
FINE-TUNING
APPLICATIONS
Note that the actual test must be done within the BEGIN block so that it is executed
at compile rather than run time; then, by the time compilation reaches the use subs
pragma, the contents of @functions has already been populated with the required
information.
The definition for chown is then placed into the MyBuiltin package, which is
defined just like any other:
package MyBuiltin;
require Exporter;
@ISA = qw/Exporter/;
@EXPORT = ();
@EXPORT_OK = qw/chown/;
sub chown
{
print "Changed mode!";
return 1;
}
The contents of @EXPORT should be empty, since you don’t want to import
anything as standard. The value of @EXPORT_OK contains the list of built-in functions
that you want to support and overload, if necessary. Thus, when you call use
MyBuiltin with a list of unsupported built-in functions, you import your own list
of replacements. In this example, a simple print statement is used to show that the
overloading is working. In an actual case, you’ll probably want to put some real
functionality into the functions you want to overload.
If you are testing a lot of functions, you will need to use loops and references to test
the functions you want to overload:
BEGIN
{

@subtest = qw/chown exec/;
foreach $function (@subtest)
{
eval { &$function };
push @functions,$function if $@;
}
}
It’s not possible in this to optimize the loop by placing the foreach loop within
the eval block, since you’re using each eval invocation to test the existence of each
function. This is a performance hit, but the overall process improves compatibility,
and it’s one of the trade-offs examined at the beginning of the chapter.
This page intentionally left blank.
Chapter 25
Distributing Modules
and Applications
837
Copyright 2001 The McGraw-Hill Companies, Inc. Click Here for Terms of Use.
O
nce you’ve written your Perl module or application, there are a few more steps
you need to follow before it can finally be unleashed on the public. Although
there’s no fixed route to this process, it will probably go something like this:
■
Debug and optimize the module or application
■
Optionally compile the script into a stand-alone application or library
■
Document the script and update the comments to reflect any changes
■
Ensure cross-platform compatibility, providing you want to support
multiple platforms

We’ve actually covered all these stages in the past chapters in this section, but there
is one final stage—that of packaging up and making your module or application for
distribution to the rest of the world.
In this last chapter, we’re going to concentrate purely on the process behind
packaging up your module or application for distribution. The core of this process
centers around the ExtUtils::MakeMaker module and Perl makefiles. These are
essentially the same as normal makefiles as used by make, but are parsed by the
MakeMaker utility into the real thing, substituting the correct directories, command
names, and other information to allow easy installation of your module or application.
We’ll also look at some examples of using Perl makefiles, how to package a module
up for distribution to CPAN, and how to package up modules for use with the
ActiveState Perl Package Manager (PPM) format.
Perl Makefiles and ExtUtils::MakeMaker
We looked at the use of Perl makefiles in Chapter 20, when we set up and built an
extension. The makefile system is an integral part of the XS extension system, and a
makefile is automatically built for you when you use the h2xs utility. Although its
primary use is for building and installing modules and extensions, it can actually be
used for practically any installation that requires some form of automatic process.
The Perl makefile is, like many other parts of the Perl environment, just a Perl
script. It uses a module, ExtUtils::MakeMaker, and a configuration supplied in the
form of a hash to work out how to build and install the different elements of a package.
When the script executes, it loads the ExtUtils::MakeMaker module, determines the
local configuration parameters, such as the location of the active Perl binary, the
library directories, and other information, and then builds a makefile that can be
used in combination with the standard make command to actually extract, compile
(if necessary), and install the module or application into its correct location.
In this section, we’re going to look at how the ExtUtils::MakeMaker module works
and how to configure the system for your own uses above and beyond the default files
produced by h2xs.
838

Perl: The Complete Reference
FINE-TUNING
APPLICATIONS
Chapter 25: Distributing Modules and Applications
839
The ExtUtils::MakeMaker module actually splits the task of makefile generation
into several subroutines, and the overall configuration that is used with these
subroutines is infinitely configurable. In each case, the subroutines provided by the
module return the text that is required to be written to the makefile. The whole system
is object oriented, and the production of individual files within the MakeMaker system
is possible at all levels. Each file created is treated as a single object, and therefore a
single MakeMaker configuration can generate a number of makefiles both for the
original target and for subdirectories and their targets.
Perl Makefiles and CPAN
To the untrained eye, it might appear that the CPAN module and the MakeMaker
module are closely linked, since we can use CPAN to download and automatically
install these modules for us. In fact, the two items are relatively independent. The
MakeMaker tool works just as well if used “manually” at the command line—it still
produces a makefile that needs to be parsed by make before it does anything.
The CPAN module knows the required sequence of downloading, extracting,
running the MakeMaker tool, and then running make—if it wasn’t for the ease of use
provided by MakeMaker, CPAN would be difficult to write because the process
would be different for each module.
If you want to supply your module to CPAN, then check www.cpan.org for the
precise submission details. You’ll need to package up your source files and the
Makefile.PL script using tar and gzip. If you want to support the module under
Windows, then check the “Packing for PPM/VPM” section later in this chapter.
For more information on CPAN, see Chapter 2, Appendix B, and Web Appendix B.
Perl Makefiles and PPM
The Perl Package Manager (PPM) and the Visual Package Manager (VPM) are part

of ActivePerl and the Perl Developer’s Kit, respectively. These work in a similar
way to CPAN, downloading an extension or application automatically from a central
repository and then installing the extension for you. However, unlike CPAN, extensions
supplied through PPM are precompiled and ready to install, rather than requiring the
usual make step.
ActivePerl was, up until Perl 5.6, a Windows-only solution, but since the 5.6 release,
other versions are now available for a number of Linux and Unix platforms. The main
advantage of PPM over CPAN is that it doesn’t require the end-user to have access to a
compiler and development environment to install the extension. See Chapter 2 for
more information on how to use PPM, and see the “Packing for PPM/VPM” section
later in this chapter.
Extension Building and Installation Overview
Most of this process will be familiar; we’ve seen a lot of it already in Chapter 20.
However, the build and installation process is slightly more complex than the
examples we have already seen. You should already be aware that the extension uses
the AutoLoader module to decide which function should be included. The AutoLoader
module is actually capable of a number of different operations. Depending on the
context and requirements, it can do one of the following:
■
Perform the function itself; the caller will never know that the AutoLoader has
been used.
■
Create the function on the fly using an eval statement.
■
Use the system function to launch an external program of the same name.
■
Dynamically load a library using the DynaLoader module.
It is the last option that is used to load an external C library extension. The
AutoSplit module is used to separate the original Perl module file into separate files,
one per function, and a mapping within the split file then tells DynaLoader which

library to load in order to implement the function. This loading mechanism requires
a bootstrap file and an autoload file, which are both used to select the correct library
location for the function, based on the library that was built and the split module.
The whole system uses a specialized structure within the Perl module directory that
accounts for both site and architecture differences.
The entire process for the makefile produced by MakeMaker (under Solaris) is
shown here. Entries taken from the StatVFS module we saw in Chapter 20 are used for
reference:
1. A directory structure is created within the extensions directory that will hold
the files produced during the build process before they are installed:
mkdir blib
mkdir blib/lib
mkdir blib/arch
mkdir blib/arch/auto
mkdir blib/arch/auto/StatVFS
mkdir blib/lib/auto
mkdir blib/lib/auto/StatVFS
mkdir blib/man3
cp StatVFS.pm blib/lib/StatVFS.pm
2. The module is split into individual functions. Each function is placed into the
auto/StatVFS directory:
AutoSplitting blib/lib/StatVFS.pm (blib/lib/auto/StatVFS)
840
Perl: The Complete Reference
TEAMFLY

Team-Fly
®

3. The XS file is parsed by xsubpp, producing the C file that contains the
necessary functions:
/usr/bin/perl -I/usr/local/lib/perl5/5.00553/sun4-solaris
-I/usr/local/lib/perl5/5.00553
/usr/local/lib/perl5/5.00553/ExtUtils/xsubpp
-typemap
/usr/local/lib/perl5/5.00553/ExtUtils/typemap
StatVFS.xs >xstmp.c && mv xstmp.c StatVFS.c
4. The source code is compiled into object format:

gcc -B/usr/ccs/bin/ -c -I/usr/local/include
-DDEBUGGING -O -DVERSION=\"0.01\"
-DXS_VERSION=\"0.01\" -fPIC
-I/usr/local/lib/perl5/5.00553/sun4-solaris/CORE
StatVFS.c
5. The bootstrap code required for DynaLoader is produced. The StatVFS.bs file
contains the necessary information to enable DynaLoader to relate the Perl call
to the C function:
Running Mkbootstrap for StatVFS ()
chmod 644 StatVFS.bs
6. The library file is generated in its dynamic format:
LD_RUN_PATH="" gcc -B/usr/ccs/bin/
-o blib/arch/auto/StatVFS/StatVFS.so
-G -L/usr/local/lib StatVFS.o
7. The library and the bootstrap code are copied into the correct location ready for
installation, and the file modes are set to their correct values:
chmod 755 blib/arch/auto/StatVFS/StatVFS.so
cp StatVFS.bs blib/arch/auto/StatVFS/StatVFS.bs
chmod 644 blib/arch/auto/StatVFS/StatVFS.bs
8. The POD format documentation in the Perl module is extracted and converted
into a man page, ready for installation:
Manifying blib/man3/StatVFS.3
The main process is now finished. The installation process just copies the structure
below the blib directory into the site- or architecture-specific directories within the Perl
library directory. At this point, if you want to test the module, you can use the make
test command. The test files will need to include the just-built version of the library.
See the blib pragma in Chapter 19 for more information on this.
FINE-TUNING
APPLICATIONS
Chapter 25: Distributing Modules and Applications

841
The actual installation process has its tricks too. The following sample is a
continuation of the StatVFS module example.
1. The files are copied to the specified installation directory. This is defined as a
whole by the PREFIX option and individually with the INSTALL* options.
Installing /usr/local/lib/perl5/site_perl/5.00553/sun4-
solaris/auto/StatVFS/StatVFS.so
Installing /usr/local/lib/perl5/site_perl/5.00553/sun4-
solaris/auto/StatVFS/StatVFS.bs
Files found in blib/arch -> Installing files in blib/lib into
architecture dependent library tree!
Installing /usr/local/lib/perl5/site_perl/5.00553/sun4-
solaris/auto/StatVFS/autosplit.ix
Installing /usr/local/lib/perl5/site_perl/5.00553/sun4-solaris/
StatVFS.pm
Installing /usr/local/lib/perl5/5.00553/man/man3/StatVFS.3
2. A list of the files installed during the installation process is written in a special
file, called .packlist in the module’s AutoLoader directory. The actual location
will depend on whether you have installed an architecture or site version. See
the INSTALLDIRS option later in the chapter.
Writing /usr/local/lib/perl5/site_perl/5.00553/sun4-
solaris/auto/StatVFS/.packlist
3. The installation information, including the configuration details, is written to a
general file that can later be consulted (preferably via a POD file viewer) to
study which packages and extensions have been installed and when. This can
also be a helpful starting point for tracing problems when a script or module
suddenly stops working.
Appending installation info to /usr/local/lib/perl5/5.00553/sun4-
solaris/perllocal.pod
The rest of this chapter is devoted to describing the configurable parameters to the

MakeMaker module. We’ll also take the opportunity to look at some of the other
modules that are used by the MakeMaker module to do its work.
MakeMaker Overview
The basic use of the MakeMaker module is very simple. The synopsis for the module is
use ExtUtils::MakeMaker;
WriteMakefile( ATTRIBUTE => VALUE [, ] );
842
Perl: The Complete Reference
FINE-TUNING
APPLICATIONS
The basic method of operation is to create a simple file that imports the module and
then calls the WriteMakefile function. You need to specify at least one attribute to the
function, which is the name of the module. For example, to create the makefile for
building the StatVFS module we created in Chapter 20, you could get away with as
little as the following in Makefile.PL:
use ExtUtils::MakeMaker;
WriteMakefile('NAME' => 'StatVFS');
When run through a Perl interpreter, like this,
$ perl Makefile.PL
it automatically produces a makefile capable of building and installing the extension.
It accounts for the location of all the necessary libraries and include files, and it selects
the correct C compiler and definitions in order to ensure that the extension is compiled
properly. This information is selected from the information produced at build time and
is specific to the platform on which you use the MakeMaker file. Thus, the Perl
makefile is completely platform independent. Any platform on which you can build
Perl should be able to produce a suitable makefile for the platform for building an
extension. The resulting makefile produced is, of course, platform- and build-specific,
even though the original Makefile.PL file is completely platform independent. It’s the
MakeMaker module that provides the platform-independent information required to
build the module.

The resulting makefile is big—751 lines long. It is too long, and completely
pointless, to reproduce here. The point about MakeMaker is that it hides all the
complexity of the makefile production from the user and just ensures that the file
produced should work on whatever platform Perl is installed on.
Start with h2xs
It doesn’t matter what sort of module, extension, or application you are dealing with—
it’s almost certainly easier to create the makefile using h2xs. The h2xs tool is actually
designed to convert a header file into a suitable set of stub XS extensions ready for
integrating into Perl. However, it can also be used to create a simple MakeMaker
template. The command line options for the tool are shown in Table 25-1.
If you want just to create a dummy MakeMaker template, then you should use
$ h2xs -f -n MyModule -X
Writing MyModule/MyModule.pm
Writing MyModule/Makefile.PL
Writing MyModule/test.pl
Writing MyModule/Changes
Writing MyModule/MANIFEST
Chapter 25: Distributing Modules and Applications
843
Note that it creates most of the files that you need, including a blank module, test
script, MANIFEST file (which lists the files that make up your module), and the
MakeMaker template in Makefile.PL. The default template looks like this:
use ExtUtils::MakeMaker;
# See lib/ExtUtils/MakeMaker.pm for details of how to influence
# the contents of the Makefile that is written.
WriteMakefile(
'NAME' => 'MyModule',
'VERSION_FROM' => 'MyModule.pm', # finds $VERSION
'PREREQ_PM' => {}, # e.g., Module::Name => 1.1
);

844
Perl: The Complete Reference
Option Description
-A Omit the autoloading definitions (implies the -c option).
-F Additional flags for C preprocessor (used with -x).
-O Allow overwriting of a preexisting extension directory.
-P Omit the stub POD section.
-X Omit the XS portion.
-c Omit the constant() function and specialized AUTOLOAD from the
XS file.
-d Turn on debugging messages.
-f Force creation of the extension.
-n Specify a name to use for the extension—defaults to a title case
version of the header file’s base name.
-p Specify a string that will be removed from the start of the C functions
when they are reproduced as Perl functions.
-s Create subroutines for specified macros.
-v Specify a version number for this extension.
-x Autogenerate XSUBs using C::Scan.
Table 25-1.
Command Line Options for h2xs
Now it’s up to you to populate the module and the rest of the directory contents. Of
course, there are times when you want to support a more complex system, and in those
situations you need to know how to configure MakeMaker.
MakeMaker Configurable Options
The bulk of the information that is produced by MakeMaker is gleaned from the
configuration and environment of the machine on which the makefile is extracted.
MakeMaker uses a number of additional modules, including Config, which contains
all of the information gained at the configuration of the Perl version.
All of the options can be modified to specify alternative installation locations,

installation procedures, and even the architecture and version of Perl that you want
to install. The usual method is to specify the alternative values within Makefile.PL as
part of the hash argument passed to WriteMakefile; for example:
use ExtUtils::MakeMaker;
WriteMakefile('NAME' -> 'StatVFS',
'PREFIX' -> '/usr/lib',
'VERSION' -> '1.01');
Alternatively, they can be specified as NAME=VALUE pairs on the command line;
for example:
$ perl Makefile.PL PREFIX=/usr/lib
What follows is a list of all the configurable options for the field names supported
by the WriteMakeFile function from ExtUtils::MakeMaker.
AUTHOR The name and email address of the package author(s)—this information is
used by the PPD file used by the PPM/VPM system (see “Packing for PPM/VPM”
later in this chapter).
ABSTRACT A one-line description of the module—used by the PPM/VPM systems
in the PPD file.
ABSTRACT_FROM The name of the file that contains the package description.
This overrides ABSTRACT and is extracted from a POD file, normally taking the first
=head1 NAME section.
BINARY_LOCATION Defines the location of the binary package of the actual
module, relative to the PPD that is created when building a PPM file.
FINE-TUNING
APPLICATIONS
Chapter 25: Distributing Modules and Applications
845
C This should be a reference to an array of C source-file names. The information is
not currently used by MakeMaker, but it can be a handy reference if you want to use
some of the extensions available within MakeMaker and other modules. See the
“Related Modules” section later in this chapter.

CCFLAGS The string that will be passed to the compiler between the INC and
OPTIMIZE options on the command line. You might want to include debugging
options or special format handling (such as -traditional to gcc).
CONFIG An array reference to a list of configuration elements to be incorporated
from the configuration information built at Perl’s compile time. The following values
are added to Config by MakeMaker: ar, cc, cccdlflags, ccdlflags, dlext, dlsrc, ld,
lddlflags, ldflags, libc, lib_ext, obj_ext, ranlib, sitelibexp, sitearchexp, and so.
CONFIGURE Should contain a reference to a section of code (anonymous or named
function), which in turn should return a reference to a hash. The hash can contain the
list of configurable elements for the MakeMaker module.
DEFINE A string containing the definitions required to compile the extension. For
example, you may need to specify -DHAVE_STRING_H.
DIR A reference to an array containing a list of subdirectories that have their own
Makefile.PL. The list will be used to determine the list of subdirectories and extensions
that need to be included when each makefile is written, and also when the main
makefile is parsed by the make command.
DISTNAME The distribution name of the package that will be created when the
directory is packaged by tar or zip—defaults to the value of NAME
DL_FUNCS A hash reference to a list of symbol names for functions that should be
made available as universal symbols at compile time. This is currently only used under
AIX and VMS.
DL_VARS An array reference to a list of symbol names for variables that should be
made available as universal symbols at compile time. This is currently only used under
AIX and VMS
EXCLUDE_EXT An array reference to a list of extension names to be excluded when
creating a new static Perl binary
EXE_FILES An array reference to a list of executable files that will be installed into
the INST_SCRIPT directory
846
Perl: The Complete Reference

FIRST_MAKEFILE A string defining the name of the makefile to be produced for the
MAP_TARGET—defaults to the value of the MAKEFILE option
FULLPERL A string defining the name of the Perl binary able to run this extension
H A reference to an array of the header files within the extension distribution
HTMLLIBPODS Reference to a hash of .pm and .pod files to be converted into HTML
format and installed with the other HTML files—defaults to all .pod and .pm files that
contain any POD directive
HTMLSCRIPTPODS Reference to a hash of files containing POD-based
documentation that should be converted to HTML and installed—defaults to the value
of the EXE_FILES configuration option
IMPORTS Valid only on the OS/2 version of Perl
INC A string listing the names of the directories to be searched for header files
during extension compilation, for example, -I/usr/local/include
INCLUDE_EXT A reference to an array of extension names to be included in the Perl
binary when creating a new statically linked Perl. Normally, MakeMaker
automatically includes the list of currently installed extensions. This allows both the
new extension and all the extensions already installed to be incorporated into the new
static Perl binary. However, if you specify a list of specific options in INCLUDE_EXT,
then only the extensions listed will be included in the final binary.
The DynaLoader extension (if supported) will always be included in the binary. If
you specify an empty array, only the current extension (and DynaLoader) will be
included.
INSTALLARCHLIB A string defining the name of the directory in which to install the
files contained in INST_ARCHLIB if the value of INSTALLDIRS is perl
INSTALLBIN A string defining the directory in which executable binaries should
be installed
INSTALLDIRS A string specifying in which of the two directory sets to install the
extension. The options are perl, which specifies that the extension should be installed
into the architecture-specific INSTALLPRIVLIB and INSTALLARCHLIB directories,
and site, which installs the extensions into the site-specific INSTALLSITELIB and

INSTALLSITEARCH directories.
FINE-TUNING
APPLICATIONS
Chapter 25: Distributing Modules and Applications
847
INSTALLHTMLPRIVLIBDIR The directory into which library documentation in
HTML format will be installed during compilation time—defaults to
$Config{installhtmlprivlibdir}
INSTALLHTMLSCRIPTDIR The directory into which script documentation in HTML
format will be installed during compilation time—defaults to
$Config{installhtmlscriptdir}
INSTALLHTMLSITELIBDIR The directory into which site-specific library
documentation in HTML format will be installed during compilation time—defaults to
$Config{installhtmlsitelibdir}
INSTALLMAN1DIR A string specifying the directory to be used for the section 1
(commands) man pages during installation. The value defaults to the value contained
in $Config{installman1dir}.
INSTALLMAN3DIR A string specifying the directory to be used for the section 3
(functions/extensions) man pages during installation. The value defaults to the value
contained in $Config{installman3dir}.
INSTALLPRIVLIB A string specifying the directory in which to install the built
libraries; see INSTALLDIRS.
INSTALLSCRIPT A string specifying the directory in which to install any scripts.
The contents of the directory specified by INST_SCRIPT is copied to this directory
during installation.
INSTALLSITELIB A string specifying the directory in which to install the built
libraries; see INSTALLDIRS.
INSTALLSITEARCH A string specifying the directory in which to install the contents
of INST_ARCH during installation; see INSTALLDIRS.
INST_ARCHLIB A string specifying the local directory to be used for storing

architecture-dependent libraries during build and before installation
INST_BIN A string specifying the local directory to be used for storing binaries
during build and before installation.
INST_EXE Deprecated; use the INST_SCRIPT option instead.
INST_HTMLLIBDIR The directory that will hold the HTML documents during
build time; they will be copied from here into INSTALLHTMLPRIVLIBDIR during
a make install.
848
Perl: The Complete Reference
INST_HTMLSCRIPTDIR The directory that will hold the HTML documents during
build time; they will be copied from here into INSTALLHTMLSCRIPTDIR during a
make install.
INST_LIB A string specifying the local directory to be used for storing libraries
during build and before installation
INST_MAN1DIR A string specifying the local directory to be used for storing
section 1 man pages during build and before installation
INST_MAN3DIR A string specifying the local directory to be used for storing
section 3 man pages during build and before installation
INST_SCRIPT A string specifying the local directory to be used for storing binaries
and other executables during build and before installation—defaults to blib/bin
LDFROM A string specifying the list of files to be used to build the final library—
defaults to the value of $OBJECTS
LIBPERL_A A string defining the name of the Perl library to be used with the
extension—defaults to libperl.a
LIB A string specifying the directory into which the libraries will be installed—
has the effect of setting the values of INSTALLPRIVLIB and INSTALLSITELIB
LIBS A reference to an anonymous array listing the library specifications to be
searched for, in order, until a suitable library is found. Each element should contain the
full list of libraries to be searched. This can be used in situations where the functions
required may be in any number of files. For example, DBM interfaces can exist in

compatible forms in GDBM, NDBM, ODBM, and SDBM libraries. Other examples
include compatibility libraries (such as BSD on an SVR4 platform) and extension
libraries such as Tk and Tcl.
Note that because each element specifies the whole list, you will need to specify the
same library a number of times if you are looking for other compatibility; for example:
‘LIBS’ => ["-ltk -lgdbm", "-ltk -lndbm", "-ltk -lodbm"]
If you only want to supply one list of libraries, you can supply a scalar, and MakeMaker
will turn it into an array with only one element. Note that the specifications can also
include a library path, as in -L/usr/local/lib, in addition to the library list.
LINKTYPE A scalar specifying the type of linking to be used when creating the
extension. This is usually dynamic unless your operating system does not support it.
For a static build, use static.
FINE-TUNING
APPLICATIONS
Chapter 25: Distributing Modules and Applications
849
MAKEAPERL A scalar; a value of 1 indicates that MakeMaker should incorporate
the rules to make a new Perl binary.
MAKEFILE A scalar specifying the name of the makefile to be produced.
MAN1PODS A reference to a hash of files containing documentation in POD format
to be converted to man pages during installation—defaults to EXE_FILES
MAN3PODS A reference to a hash of files containing documentation in POD format
to be converted to man pages during installation—defaults to EXE_FILES
MAP_TARGET A string containing the name of the new Perl binary to be produced
if static linking is requested—defaults to “perl”
MYEXTLIB A string containing the name of a custom library file built by the
extension that should be included when linking the extension.
NAME A string specifying the name of the extension. If left unspecified, it will
default to the name of the directory containing Makefile.PL.
NEEDS_LINKING If set, it indicates to MakeMaker that there is linkable code in one

of the subdirectories. If not specified, MakeMaker will try to work it out and set this
value as necessary.
NOECHO A string specifying the prefix to be placed in front of commands in the
produced makefile. By default, it is set to @, which hides all the commands as they are
executed. You can set this to an empty string to force the make process to output all of
its commands, which can be useful for debugging.
NORECURS If set, MakeMaker will not recurse into subdirectories to create
additional makefiles. The default behavior is for MakeMaker to both create the
makefiles and ensure that the parent makefile is capable of recursing into
subdirectories to build additional targets.
NO_VC Normally MakeMaker will check the current version of
ExtUtils::MakeMaker against the version used to create the makefile and fail if it
determines that there could be an incompatibility. Setting this disables the version
check, but you should use the option on the command line, rather than setting the
value directly in the script.
OBJECT A string defining the list of object files to be created into a single library.
Defaults to the single file specified by $(BASEEXT)$(OBJ_EXT).
850
Perl: The Complete Reference
TEAMFLY

Team-Fly
®

FINE-TUNING
APPLICATIONS
Chapter 25: Distributing Modules and Applications
851
OPTIMIZE A string containing the flag to be passed to the compiler to make it
optimize the code during compilation. Defaults to -O. Other options you may want to
try are -g, to switch on debugging, and -g -O, to switch on debugging and optimization
for the compilers that support it (GNU C does).
PERL A string containing the location of a Perl binary capable of doing the tasks
normally executed by the miniperl binary created during a Perl build.
PERLMAINCC A string defining the program to use for compiling the perlmain.c
file. The default is to use the value of $(CC).
PERL_ARCHLIB A string defining the libraries to be used for building the Perl binary.
PERL_LIB A string specifying the directory containing the Perl library.

PERL_MALLOC_OK Should be set to true if you are happy to have the extension
built using the Perl malloc(), rather than the system’s own implementation. Defaults
to false (0).
PERL_SRC A string specifying the location of the Perl source code. Normally
unnecessary, since the Perl source code is not required to build extensions or a new
Perl binary.
PERM_RW A string defining the octal mode to be used for files that should be
available for reading and writing. Defaults to 0644, or read/write for the owner and
read-only for everybody else.
PERM_RWX A string defining the octal mode to be used for files that should be
executable. Defaults to 0755, or read, write, and execute for the owner and read and
execute for everybody else.
PL_FILES A reference to a hash that specifies the list of files to be processed as Perl
scripts rather than native commands. The default is to use any files in the directory
structure for the extension that end in .PL. The keys should be the full file name, and
the corresponding value should be the base name of the file. This can be used to create
custom installation routines.
PM A reference to a hash specifying the list of .pm and .pl files to be installed.
The key should be the name of the file, and the corresponding value should equal
the final installation location. By default, this will be all the matching files found
in PMLIBDIRS.
PMLIBDIRS A reference to an array of subdirectories containing library files to be
installed. Defaults to [ 'lib', $(BASEEXT) ]. The entire contents of the directories are
installed into the corresponding location according to their file type. The libscan
method can be used to alter this behavior. See the section “Customizing Commands”
for more details.
POLLUTE Pollutes the name space with the preprocessor macros used for installing
extensions—shouldn’t be required under Perl 5.6 and later.
PPM_INSTALL_EXEC The name of the executable to be used when installing a
package using PPM.

PPM_INSTALL_SCRIPT The name of the script to be executed after the module has
been installed using PPM.
PREFIX A string defining the default prefix to be used in front of installation
directories. The default is to use the value determined at configuration time.
PREREQ_PM A reference to a hash defining the list of modules that need to be
available to run this extension. The key for the hash is the module or extension name,
and the corresponding value is the minimum version number. If the value of the
version number is 0, then MakeMaker only checks that the module or extension has
been installed.
SKIP A reference to an array listing the parts of the makefile that should be skipped
during production—should be avoided in nearly all cases
TYPEMAPS A reference to an array of alternative typemap files to be used with
xsubpp. This should only be used when you want to use a typemap file that is either
not in the current directory or isn’t called typemap. A typemap file in the current
directory has the highest precedence, followed by the last element of $(TYPEMAPS).
The system typemap has the lowest precedence.
VERSION A string containing the version for this distribution of the package. This is
gleaned from an alternative file if VERSION_FROM is defined.
VERSION_FROM A string specifying the name of a file to be searched to define the
version number of the package distribution. The regular expression
/([\$*])(([\w\:\']*)\bVERSION)\b.*\=/ is used to find the version number in the file.
This allows for unqualified definitions in the file, for example:
$VERSION = '1.00';
852
Perl: The Complete Reference
The result is parsed with eval to get the final value, which means you can also use
arrays, hashes, and even functions if referenced by $VERSION or something similar.
Variables qualified with my or local, or those specified with their full package name,
will not be found. If you are using the strict pragma, then use the vars pragma to
predeclare the VERSION variable before assigning it a value.

XS A reference to a hash of XS files to be processed into C files. The key to the hash
should contain the XS file name, and the value should contain the corresponding
C source file name.
XSOPT A string specifying the options to be passed to xsubpp. Use the TYPEMAP
option if you want to specify typemap files and the XSPROTOARG option for
including prototypes.
XSPROTOARG A string that defines whether prototypes should be included
(see Chapter 20). If blank (default), it assumes prototypes should be included;
a value of -noprototypes specifies that prototypes should not be created.
XS_VERSION A string defining the version number for the XS file in the current
package. Defaults to VERSION.
Creating a Dummy Makefile
Not all Makefile.PL files are intended to create a makefile suitable for creating an
extension module. In these cases, you can get MakeMaker to create a dummy makefile
that just does nothing. It will succeed for all the specified targets, but otherwise achieve
nothing. To do this, you use a different function in the MakeMaker module:
ExtUtils::MakeMaker::WriteEmptyMakefile();
In most instances, this is really only useful for creating a dummy makefile that
will be used by some automated process, such as the CPAN module. The CPAN
module tries to determine which packages and modules are required, automatically
downloading and installing them as necessary. However, if the functionality of the
module is supported by some other method on the current platform, you need some
way to “trick” CPAN into believing that the installation was a success.
Default Makefile Targets
The makefile created by MakeMaker produces a set of standard targets to be used
during the build process. The default target always triggers the build process up to, but
not including, the installation process. Other default targets are shown in Table 25-2.
Other targets deserving special mention are covered in the following sections.
FINE-TUNING
APPLICATIONS

Chapter 25: Distributing Modules and Applications
853
854
Perl: The Complete Reference
Creating a New Perl Binary
The default operation for the produced makefile is to create a library suitable for
dynamic loading. A library file ending with .so on a Unix system and .dll on a Windows
system signifies a dynamic library. However, not all systems support dynamic loading,
and in these and other situations you may wish to create your own statically linked
Perl executable that includes the new extension. If this is the case, you can use a special
target, perl, to the makefile produced by the MakeMaker module. The operation is
then slightly different from the normal build process:
1. The extension is recompiled into a static rather than a dynamic library.
2. A new makefile is created—Makefile.aperl, although the exact name is system
dependent. This contains the definitions for building a new Perl binary.
3. The new makefile is used to produce the new binary, first by creating a new
file with a modified main() function, and then by linking the resulting object file
with the main Perl library and the extension library.
The new Perl binary is created within the current directory and can be installed
over the existing binary using
$ make -f Makefile.aperl inst_perl
The final binary actually includes all the extensions specified in the INST_ARCHLIB,
SITELIBEXP, and PERL_ARCHLIB options defined within the main MakeMaker
definition.
You can create a Perl binary with a different file name by defining the value of
MAP_TARGET in the Perl makefile. The best way to do this is on the command line,
Target Description
test Runs the defined test script(s)
testdb Runs the defined test script(s) within the Perl debugger
install Installs the extension, modules, and support files, including

documentation. The values of the INSTALL* options are used
to define the final locations for the specified files.
Table 25-2.
Default make Targets
because that overrides any options defined in the makefile itself, which might well
specify the default. For example, to change the name to vfsperl:
$ perl Makefile.PL MAP_TARGET=vfsperl
$ make vfsperl
As a final alternative, you may want to build a static Perl version on a dynamically
capable system. In this instance, you use the LINKTYPE value to specify the
destination type:
$ perl Makefile.PL LINKTYPE=static
Targets for Package Builders
The built makefile provides for some standard targets primarily aimed at developers.
The targets are designed to test and package the final distribution file. Note that the
tests are aimed at verifying that all of the required files are in the current directory
structure. This is achieved by checking the contents of the MANIFEST file, which
contains a list of all the files required before the package can be distributed.
The packaging process uses the defined archiving and compression programs
to produce a final distributable package file. This is normally a combination of tar
and gzip, but you can modify this if the file is aimed at Windows (which uses zip)
or Linux (which occasionally uses bzip2). The list of “package” targets is summarized
in Table 25-3.
Chapter 25: Distributing Modules and Applications
855
FINE-TUNING
APPLICATIONS
Target Description
distcheck Provides a list of files that appear in the current directory structure,
but not in MANIFEST, and vice versa. See the section on

“ExtUtils::Manifest” later in this chapter for more details.
skipcheck Provides a list of files that are skipped due to the list provided in
MANIFEST.SKIP. See the section on “ExtUtils::Manifest” later in this
chapter for more details.
distclean Executes the realclean target and then the distcheck target. The result
should be a set of files suitable for building a new distribution file or
for returning the current directory to its distributed (supplied) state.
Table 25-3.
Extension Developers’ Targets
856
Perl: The Complete Reference
Target Description
manifest Re-creates the MANIFEST file using the list of files found in the
current directory
distdir Creates a new directory in the parent called
$(DISTNAME)-$(VERSION) and copies the files listed in
MANIFEST to the new directory. This does all of the steps necessary
to create a new version-specific directory for the extension.
disttest Does a distdir first and then runs perl Makefile.PL, make, and make
test in the new directory. This should perform all of the steps
necessary to create and test a new version of an extension.
tardist Does a distdir, and then runs $(PREOP) followed by $(TOUNIX).
Then it runs $(TAR) on the new directory (using $(TARFLAGS))
before deleting the directory and running $(POSTOP).
This target is intended to create, package, and delete a new version
directory for the extension as a tar file, suitable for use by Unix
machines. You can modify $(TAR) and the other options according
to taste. See the following section, “Customizing Commands.”
dist Defaults to $(DIST_DEFAULT), which in turn defaults to tardist
uutardist Runs a tardist first and then uuencodes the tar file (using uuencode)

shdist Does a distdir, and then runs $(PREOP) followed by $(TOUNIX).
Then it runs $(SHAR) on the new directory before deleting the
directory and running $(POSTOP).
This target is intended to create, package, and delete a new version
directory for the extension as a shar file, suitable for ASCII
transmission. You can modify $(SHAR) and the other options
according to taste. See the following section, “Customizing
Commands.”
zipdist Does a distdir, and then runs $(PREOP). Then it runs $(ZIP) on the
new directory (using $(ZIPFLAGS)) before deleting the directory
and running $(POSTOP).
This target is intended to create, package, and delete a new version
directory for the extension as a zip file, suitable for use by Windows
machines. You can modify $(ZIP) and the other options according to
taste. See the following section, “Customizing Commands.”
ci Checks in a version of each file in MANIFEST (using the value of
$CI) and updates the RCS label (using $RCS_LABEL).
Table 25-3.
Extension Developers’ Targets
(continued)
Customizing Commands
The developer targets default to use a number of commands that are expected to be on
the host machine. The options can be configured where the destination or source
requires a different format. For example, Linux often uses the bzip2 command for
compression, rather than gzip or compress.
The options in Table 25-4 should be passed as a hash reference to the special dist
option to the WriteMakefile function.
Chapter 25: Distributing Modules and Applications
857
FINE-TUNING

APPLICATIONS
Option Default Description
CI ci -u Program for “checking in” a
revision
COMPRESS gzip -best Program for compression
POSTOP @ : Commands to be run after
archive creation
PREOP @ : Commands to be run before
archive creation
RCS_LABEL rcs -q -Nv$(VERSION_SYM): Extract the RCS label for a file.
SHAR shar Program to use for creating a
shar file
SUFFIX .gz Default suffix for
compressed files
TAR tar Program to use for creating a
tar format archive
TARFLAGS cvf Command line options to use
for creating the tar file
TO_UNIX System dependent Program used to convert the
files into Unix format
ZIP zip Command to use for zip files
ZIPFLAGS -r Command line options to use
for creating a zip file
Table 25-4.
Options for Extension Developers’ Targets
858
Perl: The Complete Reference
Related Modules
A number of different modules are used and can help in the process of creating a
makefile using MakeMaker. It’s unlikely that you will need to delve into the bowels of

any of these modules, even when creating quite complex extensions. The information
provided is merely background detail.
Config
The Config module exports a hash, %Config, that lists all of the configurable options
that were calculated when Perl was built, with the values containing the necessary
information. The MakeMaker module uses this information to select the correct C
compiler and installation directories, among many other things.
ExtUtils::Command
This function is used under Win32 implementations. It defines a list of alternative
functions to be used by the building and installation process in place of the usual
Unix command line utilities.
ExtUtils::Embed
This module provides the necessary command line options and other information for
use when you are embedding a Perl interpreter into an application. See Chapter 20 for
more information.
ExtUtils::Install
This module defines two functions, install and uninstall, which are used during the
installation and uninstallation process.
ExtUtils::Installed
This module defines a suite of functions that can be used to query the contents of the
.packlist files generated during module installation. If you call the new function, it
constructs the internal lists by examining the .packlist files. The modules function
returns a list of all the modules currently installed. The files and directories both
accept a single argument—the name of a module. The result is a list of all the files
installed by the package. The directory_tree function reports information for all the
related directories. In all cases, you can specify Perl to get information pertaining to
the core Perl installation.
The validate function checks that the files listed in .packlist actually exist. The
packlist function returns an object as defined by ExtUtils::Packlist for the specified
module. Finally, version returns the version number of the specified module.

Chapter 25: Distributing Modules and Applications
859
FINE-TUNING
APPLICATIONS
ExtUtils::Liblist
This module defines the libraries to be used when building extension libraries and other
Perl-based binaries. The information provided here broaches much of the complexity
involved in getting an extension to work across many platforms; the bulk of the code
relates to the information required for individual platforms.
ExtUtils::Manifest
This module provides the functions that produce, test, and update the MANIFEST file.
Five of the functions are the most useful, beginning with mkmanifest, which creates a
file based on the current directory contents. The maincheck function verifies the current
directory contents against the MANIFEST file, while filecheck looks for files in the
current directory that are not specified in the MANIFEST. Both maincheck and
filecheck are executed by the fullcheck function, and skipcheck lists the files in the
MAINFEST.SKIP file.
ExtUtils::Miniperl
This module provides the list of base libraries and extensions that should be included
when building the miniperl binary.
ExtUtils::Mkbootstrap
This module makes a bootstrap file suitable for the DynaLoader module.
ExtUtils::Mksymlists
This module produces the list of options for creating a dynamic link library.
ExtUtils::MM_OS2
MakeMaker specifics for the OS/2 operating system are produced by this module.
ExtUtils::MM_Unix
MakeMaker specifics for the Unix platform are produced by this module. It also includes
many of the core functions used by the main MakeMaker module, irrespective of the
host platform.

ExtUtils::MM_VMS
This module produces MakeMaker specifics for VMS.
ExtUtils::MM_Win32
This module produces MakeMaker specifics for Windows 95/98/NT.