Book HomeJava and XSLTSearch this book

8.74. ExtUtils::MakeMaker

Writes a Makefile for module installation. Provides a function, WriteMakefile, which creates an object with attributes that are set from various sources and that actually write the Makefile. See Chapter 2, "Installing Perl" for information about the using the Makefile and MakeMaker during module installation. This section explains the details of actually creating the Makefile with MakeMaker. It assumes an understanding of make and Makefiles.

If you are a Perl programmer writing a module, you should run h2xs to generate the template for your module. Among other things, h2xs creates a file called Makefile.PL, and it's Makefile.PL that runs MakeMaker. On the other hand, if you are installing a module, you can usually just run the Makefile.PL that came with the module, perhaps adding a PREFIX argument if you are installing the module locally (see Chapter 2, "Installing Perl"). In either case, you shouldn't need to run ExtUtils::MakeMaker directly unless you have special requirements.

A typical call to MakeMaker might look like this example from the CGI distribution:

use ExtUtils::MakeMaker;
WriteMakefile(
        NAME => "CGI",
        DISTNAME => "CGI-modules",
        VERSION => "2.76",
        linkext => { LINKTYPE => '' },
        dist => {COMPRESS=>'gzip -9f', SUFFIX => 'gz'},
);

MakeMaker attributes can be passed as arguments to WriteMakefile, as in the example, or they can be passed as name=value pairs on the command line:

perl Makefile.PL PREFIX=/home/mydir/Perl/Modules

To see what MakeMaker is doing, you can say:

perl Makefile.PL verbose

The following attributes can be specified:

C
Reference to array of *.c filenames. Initialized from a directory scan and the values portion of the XS attribute hash. Not currently used by MakeMaker but may be handy in Makefile.PLs.

CCFLAGS
String to be included in the compiler call command line between the INC and OPTIMIZE arguments.

CONFIG
An array reference containing a list of attributes to get from %Config. The following values are always added to CONFIG:

ar       cc          cccdlflags   ccdlflags
dlext    dlsrc       ld           lddlflags
ldflags  libc        lib_ext      obj_ext
ranlib   sitelibexp  sitearchexp  so
CONFIGURE
Reference to a subroutine that should return a hash reference. The hash may contain further attributes that need to be determined by some evaluation method.

DEFINE
An attribute containing additional defines.

DIR
Reference to array of subdirectories containing Makefile.PL files.

DISTNAME
Your name for distributing the package (by tar file). Defaults to NAME, which is described below.

DL_FUNCS
Reference to a hash of symbol names for routines to be made available as universal symbols. Each key/value pair consists of the package name and an array of routine names in that package. Used only under AIX (export lists) and VMS (linker options) at present. Defaults to "$PKG" => ["boot_$PKG"].

DL_VARS
Array of symbol names for variables to be made available as universal symbols. Used only under AIX (export lists) and VMS (linker options) at present. Defaults to [].

EXCLUDE_EXT
Array of module names to exclude when doing a static build. Ignored if INCLUDE_EXT is present.

EXE_FILES
Reference to array of executable files to be copied to the INST_SCRIPT directory. make realclean deletes them from there.

NO_VC
If set, the Makefile does not check the current version of MakeMaker against the version the Makefile was built under. Should be used interactively, not written into your Makefile.PL file.

FIRST_MAKEFILE
Name of the Makefile to be produced. Defaults to the contents of MAKEFILE, but can be overridden.

FULLPERL
Perl binary that can run this module.

H
Reference to array of *.h filenames. Similar to C attribute.

IMPORTS
Used only on OS/2.

INC
Directories containing include files, in -I form. For example:

INC => "-I/usr/5include -I/path/to/inc"
INCLUDE_EXT
Array of module names to be included when doing a static build. If present, only those modules that are explicitly mentioned are used for the build (instead of all installed extensions). It is not necessary to mention DynaLoader or the current module when filling in INCLUDE_EXT—they are always included.

INSTALLARCHLIB
Used by make install, which copies files from INST_ARCHLIB to this directory if INSTALLDIRS is set to perl.

INSTALLBIN
Directory to install binary files into.

INSTALLDIRS
Determines which of the two sets of installation directories to choose. There are two possible values:

perl
Uses INSTALLLPRIVLIB and INSTALLARCHLIB directories.

site
The default. Uses INSTALLSITELIB and INSTALLSITEARCH directories.

INSTALLMAN1DIR
Directory where command manpages are put during make install. Defaults to $Config{installman1dir}.

INSTALLMAN3DIR
Directory where library manpages are put during make install. Defaults to $Config{installman3dir}.

INSTALLPRIVLIB
Used by make install, which copies files from INST_LIB to this directory if INSTALLDIRS is set to perl.

INSTALLSCRIPT
Used by make install, which copies files from INST_SCRIPT to this directory.

INSTALLSITELIB
Used by make install, which copies files from INST_LIB to this directory if INSTALLDIRS is set to site (the default).

INSTALLSITEARCH
Used by make install, which copies files from INST_ARCHLIB to this directory if INSTALLDIRS is set to site (the default).

INST_ARCHLIB
Same as INST_LIB for architecture-dependent files.

INST_BIN
Directory where real binary files are put during make, for later copying to INSTALLBIN during make install.

INST_EXE
Deprecated. Old name for INST_SCRIPT, which you should use instead.

INST_LIB
Directory to hold library files for this module while it is being built.

INST_MAN1DIR
Directory to hold the command manpages at make time.

INST_MAN3DIR
Directory to hold the library manpages at make time.

INST_SCRIPT
Directory where executable files should be installed during make. Defaults to ./blib/bin, to have a dummy location during testing. make install copies the files in INST_SCRIPT to INSTALLSCRIPT.

LDFROM
Used by the ld command to specify the files to link/load from. Defaults to $(OBJECT).

LIBPERL_A
Filename of the Perl library that will be used with this module. Defaults to libperl.a.

LIB
Can be set only when Makefile.PL is run; both INSTALLPRIVLIB and INSTALLSITELIB are set to the value of LIB.

LIBS
Anonymous array of alternative library specifications to be searched for (in order) until at least one library is found. Note that any element of the array contains a complete set of arguments for the ld command.

LINKTYPE
Should be used only to force static linking (see the linkext attribute below). Possible values are static or dynamic. Default is dynamic unless usedl=undef in config.sh.

MAKEAPERL
Boolean. Tells MakeMaker to include the rules for making a Perl binary. Normally handled automatically by MakeMaker and not needed by the user.

MAKEFILE
Name of the Makefile to be produced.

MAN1PODS
Reference to a hash of pod-containing files to be converted to manpages and installed as requested at configure time. Default is all EXE_FILES files that include pod directives.

MAN3PODS
Reference to a hash of .pm and .pod files to be converted to manpages and installed as requested at configure time. Default is all .pod and any .pm files that include pod directives.

MAP_TARGET
Name for new Perl binary if one will be produced. Default is perl.

MYEXTLIB
Name of library that the module builds and links to.

NAME
Perl module name for this module (e.g., DBD::Oracle). Defaults to the directory name but should be explicitly defined in the Makefile.PL.

NEEDS_LINKING
Boolean. Can be set to speed up MakeMaker processing a little bit, but not needed since MakeMaker will figure out if linking is needed.

NOECHO
Controls make's echo (@) feature. Defaults to @. By setting it to an empty string, you can generate a Makefile that echos all commands. Used mainly in debugging MakeMaker itself.

NORECURS
Boolean. If set, inhibits descending into subdirectories.

OBJECT
List of object files. Defaults to $(BASEEXT)$(OBJ_EXT); can be set to a long string containing all object files.

OPTIMIZE
If set to -g, turns debugging on. Defaults to -O. Passed to subdirectory makes.

PERL
Perl binary for tasks that can be done by miniperl.

PERLMAINCC
The call to the program that can compile perlmain.c. Defaults to $(CC).

PERL_LIB
Directory containing the Perl library to use.

PERL_ARCHLIB
Same as PERL_LIB for architecture-dependent files.

PERL_SRC
Directory containing the Perl source code. Avoid using this attribute, since it may be undefined.

PL_FILES
Reference to hash of files to be processed as Perl programs. By default, MakeMaker turns any *.PL file it finds (except the Makefile.PL) into a key and the basename of the file into the value. The *.PL files are expected to produce output to the target files themselves.

PM
Reference to hash of .pm and *.pl files to be installed.

PMLIBDIRS
Reference to array of subdirectories containing library files. Defaults to ['lib', $(BASEEXT)]. The directories are scanned, and any files they contain are installed in the corresponding location in the library. A libscan method can be used to alter the behavior. Defining PM in the Makefile.PL overrides PMLIBDIRS.

PREFIX
Can be used to set the three INSTALL* attributes at once so they have PREFIX as a common directory node.

PREREQ_PM
Reference to a hash of modules that need to be available to run this module (e.g., Fcntl for SDBM_File). The name of each required module is the key, and the desired version is the value. If the required version is 0, MakeMaker just checks to see if any version is installed.

SKIP
Reference to an array specifying sections of the Makefile that shouldn't be written. Do not use the SKIP attribute for the negligible speedup, which may seriously damage the resulting Makefile.

TYPEMAPS
Reference to array of typemap filenames. Use when the typemaps are in a directory other than the current directory or when they are not named typemap. The last typemap in the list takes precedence, but a typemap in the current directory has highest precedence even if it isn't listed in TYPEMAPS. The default system typemap has lowest precedence.

VERSION
Your version number for the package. Defaults to 0.1.

VERSION_FROM
Names a file for MakeMaker to parse to find the version number for the package, so you don't need to specify VERSION. The file must contain a single line to compute the version number. The first line in the file that contains the regular expression:

/([\$*])(([\w:\']*)\bVERSION)\b.*\=/

is evaluated with eval and the result assigned to VERSION.

XS
Reference to a hash of .xs files. MakeMaker defaults this. For example:

{'name_of_file.xs' => 'name_of_file.c'}

The .c files are automatically deleted by a make clean.

XSOPT
String of options to pass to xsubpp, which might include -C++ or -extern but not typemaps, which go in TYPEMAPS.

XSPROTOARG
May be set to an empty string, which is identical to -prototypes or -noprototypes. Defaults to the empty string.

XS_VERSION
Your version number for the package's .xs file. Defaults to the value of VERSION.

The following lowercase attributes can be used to pass parameters to the methods that implement the corresponding part of the Makefile:

clean
Extra files to clean.

depend
Extra dependencies.

dist
Distribution options.

dynamic_lib
Options for dynamic library support.

installpm
Installation options related to AutoSplit. Deprecated as of MakeMaker 5.23. See the pm_to_blib entry for ExtUtils::Install.

linkext
Linking style.

macro
Extra macros to define.

realclean
Extra files to make realclean.

tool_autosplit
Attributes for the tool_autosplit method.

If specifying attributes isn't sufficient to accomplish what you want, you can define your own subroutines in the Makefile.PL that return the text to be written to the Makefile. You can also override MakeMaker's subroutines (described in Section 8.85, "ExtUtils::MM_Unix") this way.



Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.