perl the complete reference second edition phần 8 doc

These are essentially the same as normal makefiles as used by make, but are parsed by the MakeMakerutility into the real thing, substituting the correct directories, commandnames, and ot

C h a p t e r 2 4 : C r o s s - P l a t f o r m M i g r a t i o n T r a p s 835

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:

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

MyBuiltinwith 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)

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.

Once 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 Althoughthere’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 platformsWe’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 fordistribution 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 MakeMakerutility into the real thing, substituting the correct directories, commandnames, 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 anextension 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 beused 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 P e r l : T h e C o m p l e t e R e f e r e n c e

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 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

MakeMakertool 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 theexamples 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 thecontext 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

AutoSplitmodule 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 librarylocation 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 thataccounts 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 holdthe files produced during the build process before they are installed:

mkdir blibmkdir blib/libmkdir blib/archmkdir blib/arch/automkdir blib/arch/auto/StatVFSmkdir blib/lib/auto

mkdir blib/lib/auto/StatVFSmkdir blib/man3

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/typemapStatVFS.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/COREStatVFS.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

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

testcommand 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.

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 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 solaris/auto/StatVFS/StatVFS.so

Installing solaris/auto/StatVFS/StatVFS.bs

/usr/local/lib/perl5/site_perl/5.00553/sun4-Files found in blib/arch -> Installing files in blib/lib intoarchitecture dependent library tree!

Installing solaris/auto/StatVFS/autosplit.ix

/usr/local/lib/perl5/site_perl/5.00553/sun4-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 specialfile, called packlist in the module’s AutoLoader directory The actual locationwill depend on whether you have installed an architecture or site version See

the INSTALLDIRS option later in the chapter.

Writing solaris/auto/StatVFS/.packlist

/usr/local/lib/perl5/site_perl/5.00553/sun4-3 The installation information, including the configuration details, is written to ageneral file that can later be consulted (preferably via a POD file viewer) tostudy which packages and extensions have been installed and when This canalso be a helpful starting point for tracing problems when a script or modulesuddenly stops working

Appending installation info to solaris/perllocal.pod

/usr/local/lib/perl5/5.00553/sun4-The rest of this chapter is devoted to describing the configurable parameters to the

MakeMakermodule 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.

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

MakeMakermodule 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

Note that it creates most of the files that you need, including a blank module, testscript, 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 P e r l : T h e C o m p l e t e R e f e r e n c e

Option Description

XS file

-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

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 NAMEsection

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

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 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 OPTIMIZEoptions 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 incorporatedfrom 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 namedfunction), 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 extensionsthat 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 bemade available as universal symbols at compile time This is currently only used underAIX and VMS

DL_VARS An array reference to a list of symbol names for variables that should bemade available as universal symbols at compile time This is currently only used underAIX and VMS

EXCLUDE_EXT An array reference to a list of extension names to be excluded whencreating 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 P e r l : T h e C o m p l e t e R e f e r e n c e

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

INSTALLSITEARCHdirectories

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 847

INSTALLHTMLPRIVLIBDIR The directory into which library documentation inHTML format will be installed during compilation time—defaults to

$Config{installhtmlprivlibdir}

INSTALLHTMLSCRIPTDIR The directory into which script documentation in HTMLformat 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

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 binariesduring 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 P e r l : T h e C o m p l e t e R e f e r e n c e

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.

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 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 theextension 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 intosubdirectories to build additional targets

NO_VC Normally MakeMaker will check the current version of ExtUtils::MakeMakeragainst the version used to create the makefile and fail if itdetermines that there could be an incompatibility Setting this disables the versioncheck, but you should use the option on the command line, rather than setting thevalue 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 P e r l : T h e C o m p l e t e R e f e r e n c e

Team-Fly®

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 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 installingextensions—shouldn’t be required under Perl 5.6 and later

PPM_INSTALL_EXEC The name of the executable to be used when installing apackage using PPM

PPM_INSTALL_SCRIPT The name of the script to be executed after the module hasbeen 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 beavailable 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 skippedduring 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 eithernot 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 theversion 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 P e r l : T h e C o m p l e t e R e f e r e n c e

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

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 853

854 P e r l : T h e C o m p l e t e R e f e r e n c e

Creating a New Perl Binary

The default operation for the produced makefile is to create a library suitable fordynamic loading A library file ending with so on a Unix system and dll on a Windowssystem 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 linkedPerl 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 systemdependent 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 installedover 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_TARGETin the Perl makefile The best way to do this is on the command line,

Target Description

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

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 thischapter 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 orfor returning the current directory to its distributed (supplied) state

Table 25-3 Extension Developers’ Targets

856 P e r l : T h e C o m p l e t e R e f e r e n c e

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 inMANIFEST 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

testin the new directory This should perform all of the stepsnecessary 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.”

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, “CustomizingCommands.”

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 ) 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.

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 857

Option Default Description

revision

COMPRESS gzip -best Program for compression

archive creation

archive creation

RCS_LABEL rcs -q -Nv$(VERSION_SYM): Extract the RCS label for a file

sharfile

compressed files

tarformat archive

for creating the tar file TO_UNIX System dependent Program used to convert the

files into Unix format

for creating a zip file

Table 25-4 Options for Extension Developers’ Targets

858 P e r l : T h e C o m p l e t e R e f e r e n c e

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 informationprovided 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 alternativefunctions to be used by the building and installation process in place of the usualUnix command line utilities

ExtUtils::Embed

This module provides the necessary command line options and other information foruse when you are embedding a Perl interpreter into an application See Chapter 20 formore 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.

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 859

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.

MakeMakerspecifics 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

Checking for Prerequisites

Some modules that you develop may require the preinstallation of other modules that

are not included in the standard Perl distribution The PREREQ_PM configuration

option can be used to list the modules and version numbers that are required Forexample, here’s the configuration line used in the LWP bundle:

PREREQ_PM => { 'URI' => "1.03",

'MIME::Base64' => "2.1",'Net::FTP' => "2.4",'HTML::HeadParser' => 0,'Digest::MD5' => 0,},

Sometimes, however, you want a more interactive and informative method forreporting these problems To do this, you need to add your own set of tests before the

call to MakeMaker to test for the existence of the modules For example, you might

place some code like this to check for an individual module:

print "Checking for My::Module ";

eval{require My::Module;

};

if ($@){

You need the My::Module in order to ensure that you have

the right modules installed for installation

Because eval uses its own interpreter, it’ll raise an exception if the module you

need can’t be found without actually interrupting the current script In this case,

we report an error and also increment the $missing_modules++ variable Using this

method, you could insert multiple tests just like this and then fail the installation script

if $missing_modules is greater than 0.

Application Installation

Installing an application is really just a case of supplying the configuration options to

MakeMakerto copy the scripts into the correct location This is as simple as

use ExtUtils::MakeMaker;

WriteMakefile(

NAME => 'mctest',EXE_FILES => [qw/ping.pl/],);

The EXE_FILES option specifies the list of scripts that should be copied first into

the directory pointed to by INST_SCRIPT (defaults to /blib/scripts) during the build

phase, and then into the INSTALLSCRIPT directory (usually /usr/local/bin) during

the installation phase

If you want to do something more complex during the build phase, you need to

configure MakeMaker to write the commands you want to execute directly into the

makefile Because these are module specific, there is no “automatic” way of getting

MakeMakerto do this stage for you Remember that the process needs to be completed

during the call to make, not when actually creating the makefile itself.

The way to do this is to override one of the methods used by MakeMaker during

the production of the makefile You can override methods used in MakeMaker by

defining the methods within the MY package For modifying what happens after the

main build process, you need to override the postamble method, which by default is

undefined The return value from your postamble subroutine should be the string

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 861

containing the make target and commands For example, here’s another extract from

What’s happening here is that we are building a string that will create symbolic

links to the lwp-request script so that users can type GET url or POST url at the

command line The output produced in the makefile under Unix looks like this:

# - MakeMaker postamble section:

You can see here the Perl code to install links for GET, HEAD, and POST The

$Config{"lns"}is the name of the link command determined by Perl during the build

process, and the rest is just a foreach loop that first deletes and then creates the link.

The links are made in the blib/script directory and will be copied into the final script

directory (/usr/local/bin) during the installation phase

Packing for CPAN

When packing up your module and makefile for CPAN, all you need to do is clean

the extension or module directory for your application and then use tar and gzip to

package the entire directory You’ll need to delete any unnecessary files and also clean

the directory of any of the build files specific to your development platform For the

former, it’s a case of manually deleting those files; for the latter, the easiest way to do

this is to change to your directory and then type

$ make distclean

To actually package the module up, use something like this

$ tar cf - /MyModule|gzip -c - >MyModule.tar.gz

where MyModule is the name of your module When supplying to CPAN, you should

include the version number and then separate the module name from the version by a

single hyphen; for example, MyModule-1.13.tar.gz

Alternatively, make sure your MANIFEST file is up to date and then use

$ make dist

This will package up all the files listed in MANIFEST into a tar file and then zip them

using gzip The name of the resultant file will be based on the NAME and VERSION

options in the Perl makefile

Packing for PPM/VPM

The Perl Package Manager is actually very similar to the CPAN module, and it provides

a way for users of the ActivePerl distribution to download and install modules

precompiled for a number of platforms, but primarily the Windows series This is the

only major difference between a traditional MakeMaker package and PPM—with PPM

you package up a precompiled version of the module, rather than its raw source

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 863

You need to develop the Perl makefile and the options and other tricks you use

with MakeMaker as normal, build it on your target platform, and then produce a

separate file, the PPD, which contains all of the information about the module required

by the PPM system There is, of course, a simple way of doing this

For example, consider this makefile template:

use ExtUtils::MakeMaker;

WriteMakefile(

'NAME' => 'MyModule','VERSION_FROM' => 'MyModule.pm',($] ge '5.005') ? (

'AUTHOR' => 'Me (me@me.org)','ABSTRACT' => 'Does my stuff',) : (),

);

Normally at this point, with all the modules and the Perl makefile ready-written,we’d package everything up into a distributable package ready for posting on CPAN.However, we need to perform the build process on behalf of the end-user, since wecannot guarantee they will have the utilities required to extract the file themselves

This will go through the build process creating the standard directory structure

used by MakeMaker PPM uses this base structure when installing the module into its final location—normally this would be handled by make or a similar utility You might see output like the following, although it will depend on the make utility you are using.

You now need to package the blib directory up using tar and gzip.

You can get these utilities from a variety of places—ActiveState recommends

http://www.itribe.net/virtunix/ For example:

C:\> tar cvf MyModule.tar blib

C:\> gzip MyModule.tar

This will create a file called MyModule.tar.gz.

The final step is to create the PPD (Perl Package Definition) file that specifies the

package information required by PPM This is, in essence, a condensed version of the

information that is normally extracted from a number of files by the CPAN module.

The PPD is read by PPM/VPM when you are searching for a given package To make

the process easier, the MakeMaker utility places the necessary steps into the makefile,

based on the definitions you’ve already provided, so we can type

C:\> nmake ppd

The resulting file that is produced should be called MyModule.PPD, and it’ll look

something like this:

<SOFTPKG NAME="MyModule" VERSION="1,0,0,0">

The file is actually in XML format and defines all of the information required by

PPM when you search a repository You will need to change the value of the

CODEBASEproperty to point to the location of the source package file

If you want to actually supply your final package to a public repository, like the

one at ActiveState, you need to put the MyModule.tar.gz file in an x86 directory, and

then Zip the x86 directory and send it to the repository concerned (See Chapter 2 for

more information on PPM/VPM repositories.)

C h a p t e r 2 5 : D i s t r i b u t i n g M o d u l e s a n d A p p l i c a t i o n s 865

This page intentionally left blank.

Part V

Appendixes

Copyright 2001 The McGraw-Hill Companies, Inc Click Here for Terms of Use

This page intentionally left blank.

This appendix is a quick guide to the functions and major operators (including

regular expression and quoting mechanisms) support by Perl v5.7 (the latestdevelopmental release at the time of writing)

Because of the way in which most of the Perl functions operate, it’s difficult to give

a strict or coherent meaning to all of the functions Most of the functions and operatorshave their own special meaning and treatment, depending on the context in which theyare used It’s also impossible to qualify functions according to what they return, sincedifferent functions return different information according to their context For example,

the localtime function returns a date/time string in scalar context, but the individual

time and date components when used in a list context

Each function description includes details of the function’s operation and the effects

of the function (using the short codes listed in Table A-1) References to other functions,chapters, or modules that may extend or provide a better interface to the facilitiesoffered by the function are also mentioned

For a quick reference to some of the more popular problems and effects of the Perlbuilt-in functions, see Table A-2 This lists functions and the variables they use ormodify, or the types of exceptions they raise The same codes are used within thefunction definitions The column descriptions for Table A-2 are given in Table A-1

within eval, setting the value of $@ with the error string

unsupported on the current platform; you should be able to trap

the function call and error using eval

Table A-1 Effect Codes Used on Functions

Team-Fly®