[Chapter 8] 8.54 ExtUtils::MakeMaker
Author: Ellen Siever, Stephen Spainhour & Nathan Patwardhan
Date: 1999-07-02T01:45:40Z

#

| Chapter 8 Standard Modules |

## 8.54 ExtUtils::MakeMaker

Writes a Makefile for use during module installation. Provides a function, `WriteMakefile`, which creates an object whose attributes are set from various sources and which actually writes the Makefile. See Chapter 2 for information about the use of 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). 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, 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 man pages are put during make install. Defaults to `$Config{installman1dir}`.

INSTALLMAN3DIR

  Directory where library man pages 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 only be set at 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 `linkext` 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 is to 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 very 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 that 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 returns the text to be written to the Makefile. You can also override MakeMaker's subroutines (described in Section 8.60, "ExtUtils::MM_Unix") this way.

8.53 ExtUtils::Liblist |  | 8.55 ExtUtils::Manifest