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 "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 developer 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 "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 .
• 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 "ExtUtils::MM_Unix") this way.