ExtUtils::MakeMaker (Perl in a Nutshell, 2nd Edition)

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.