CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
  • How To Write A Makefile.PL
  • Default Makefile Behaviour
  • make test
  • make testdb
  • make install
  • INSTALL_BASE
  • PREFIX and LIB attribute
  • AFS users
  • Static Linking of a new Perl Binary
  • Determination of Perl Library and Installation Locations
  • Which architecture dependent directory?
  • Using Attributes and Parameters
  • Additional lowercase attributes
  • Overriding MakeMaker Methods
  • The End Of Cargo Cult Programming
  • Hintsfile support
  • Distribution Support
  • Module Meta-Data (META and MYMETA)
  • Disabling an extension
  • Other Handy Functions
  • Supported versions of Perl
• ENVIRONMENT
• SEE ALSO
• AUTHORS
• LICENSE

#NAME

ExtUtils::MakeMaker - Create a module Makefile

#SYNOPSIS

use ExtUtils::MakeMaker;

WriteMakefile(
    NAME              => "Foo::Bar",
    VERSION_FROM      => "lib/Foo/Bar.pm",
);

#DESCRIPTION

This utility is designed to write a Makefile for an extension module from a Makefile.PL. It is based on the Makefile.SH model provided by Andy Dougherty and the perl5-porters.

It splits the task of generating the Makefile into several subroutines that can be individually overridden. Each subroutine returns the text it wishes to have written to the Makefile.

As there are various Make programs with incompatible syntax, which use operating system shells, again with incompatible syntax, it is important for users of this module to know which flavour of Make a Makefile has been written for so they'll use the correct one and won't have to face the possibly bewildering errors resulting from using the wrong one.

On POSIX systems, that program will likely be GNU Make; on Microsoft Windows, it will be either Microsoft NMake, DMake or GNU Make. See the section on the "MAKE" parameter for details.

ExtUtils::MakeMaker (EUMM) is object oriented. Each directory below the current directory that contains a Makefile.PL is treated as a separate object. This makes it possible to write an unlimited number of Makefiles with a single invocation of WriteMakefile().

All inputs to WriteMakefile are Unicode characters, not just octets. EUMM seeks to handle all of these correctly. It is currently still not possible to portably use Unicode characters in module names, because this requires Perl to handle Unicode filenames, which is not yet the case on Windows.

#How To Write A Makefile.PL

See ExtUtils::MakeMaker::Tutorial.

The long answer is the rest of the manpage :-)

#Default Makefile Behaviour

The generated Makefile enables the user of the extension to invoke

perl Makefile.PL # optionally "perl Makefile.PL verbose"
make
make test        # optionally set TEST_VERBOSE=1
make install     # See below

The Makefile to be produced may be altered by adding arguments of the form KEY=VALUE. E.g.

perl Makefile.PL INSTALL_BASE=~

Other interesting targets in the generated Makefile are

make config     # to check if the Makefile is up-to-date
make clean      # delete local temp files (Makefile gets renamed)
make realclean  # delete derived files (including ./blib)
make ci         # check in all the files in the MANIFEST file
make dist       # see below the Distribution Support section

#make test

MakeMaker checks for the existence of a file named test.pl in the current directory, and if it exists it executes the script with the proper set of perl -I options.

MakeMaker also checks for any files matching glob("t/*.t"). It will execute all matching files in alphabetical order via the Test::Harness module with the -I switches set correctly.

If you'd like to see the raw output of your tests, set the TEST_VERBOSE variable to true.

make test TEST_VERBOSE=1

If you want to run particular test files, set the TEST_FILES variable. It is possible to use globbing with this mechanism.

make test TEST_FILES='t/foobar.t t/dagobah*.t'

Windows users who are using nmake should note that due to a bug in nmake, when specifying TEST_FILES you must use back-slashes instead of forward-slashes.

nmake test TEST_FILES='t\foobar.t t\dagobah*.t'

#make testdb

A useful variation of the above is the target testdb. It runs the test under the Perl debugger (see perldebug). If the file test.pl exists in the current directory, it is used for the test.

If you want to debug some other testfile, set the TEST_FILE variable thusly:

make testdb TEST_FILE=t/mytest.t

By default the debugger is called using -d option to perl. If you want to specify some other option, set the TESTDB_SW variable:

make testdb TESTDB_SW=-Dx

#make install

make alone puts all relevant files into directories that are named by the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and INST_MAN3DIR. All these default to something below ./blib if you are not building below the perl source directory. If you are building below the perl source, INST_LIB and INST_ARCHLIB default to ../../lib, and INST_SCRIPT is not defined.

The install target of the generated Makefile copies the files found below each of the INST_* directories to their INSTALL* counterparts. Which counterparts are chosen depends on the setting of INSTALLDIRS according to the following table:

                               INSTALLDIRS set to
                         perl        site          vendor

               PERLPREFIX      SITEPREFIX          VENDORPREFIX
INST_ARCHLIB   INSTALLARCHLIB  INSTALLSITEARCH     INSTALLVENDORARCH
INST_LIB       INSTALLPRIVLIB  INSTALLSITELIB      INSTALLVENDORLIB
INST_BIN       INSTALLBIN      INSTALLSITEBIN      INSTALLVENDORBIN
INST_SCRIPT    INSTALLSCRIPT   INSTALLSITESCRIPT   INSTALLVENDORSCRIPT
INST_MAN1DIR   INSTALLMAN1DIR  INSTALLSITEMAN1DIR  INSTALLVENDORMAN1DIR
INST_MAN3DIR   INSTALLMAN3DIR  INSTALLSITEMAN3DIR  INSTALLVENDORMAN3DIR

The INSTALL... macros in turn default to their %Config ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.

You can check the values of these variables on your system with

perl '-V:install.*'

And to check the sequence in which the library directories are searched by perl, run

perl -le 'print join $/, @INC'

Sometimes older versions of the module you're installing live in other directories in @INC. Because Perl loads the first version of a module it finds, not the newest, you might accidentally get one of these older versions even after installing a brand new version. To delete all other versions of the module you're installing (not simply older ones) set the UNINST variable.

make install UNINST=1

#INSTALL_BASE

INSTALL_BASE can be passed into Makefile.PL to change where your module will be installed. INSTALL_BASE is more like what everyone else calls "prefix" than PREFIX is.

To have everything installed in your home directory, do the following.

# Unix users, INSTALL_BASE=~ works fine
perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir

Like PREFIX, it sets several INSTALL* attributes at once. Unlike PREFIX it is easy to predict where the module will end up. The installation pattern looks like this:

INSTALLARCHLIB     INSTALL_BASE/lib/perl5/$Config{archname}
INSTALLPRIVLIB     INSTALL_BASE/lib/perl5
INSTALLBIN         INSTALL_BASE/bin
INSTALLSCRIPT      INSTALL_BASE/bin
INSTALLMAN1DIR     INSTALL_BASE/man/man1
INSTALLMAN3DIR     INSTALL_BASE/man/man3

INSTALL_BASE in MakeMaker and --install_base in Module::Build (as of 0.28) install to the same location. If you want MakeMaker and Module::Build to install to the same location simply set INSTALL_BASE and --install_base to the same location.

INSTALL_BASE was added in 6.31.

#PREFIX and LIB attribute

PREFIX and LIB can be used to set several INSTALL* attributes in one go. Here's an example for installing into your home directory.

# Unix users, PREFIX=~ works fine
perl Makefile.PL PREFIX=/path/to/your/home/dir

This will install all files in the module under your home directory, with man pages and libraries going into an appropriate place (usually ~/man and ~/lib). How the exact location is determined is complicated and depends on how your Perl was configured. INSTALL_BASE works more like what other build systems call "prefix" than PREFIX and we recommend you use that instead.

Another way to specify many INSTALL directories with a single parameter is LIB.

perl Makefile.PL LIB=~/lib

This will install the module's architecture-independent files into ~/lib, the architecture-dependent files into ~/lib/$archname.

Note, that in both cases the tilde expansion is done by MakeMaker, not by perl by default, nor by make.

Conflicts between parameters LIB, PREFIX and the various INSTALL* arguments are resolved so that:

• setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB, INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);

• without LIB, setting PREFIX replaces the initial $Config{prefix} part of those INSTALL* arguments, even if the latter are explicitly set (but are set to still start with $Config{prefix}).

If the user has superuser privileges, and is not working on AFS or relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB, INSTALLSCRIPT, etc. will be appropriate, and this incantation will be the best:

perl Makefile.PL;
make;
make test
make install

make install by default writes some documentation of what has been done into the file $(INSTALLARCHLIB)/perllocal.pod. This feature can be bypassed by calling make pure_install.

#AFS users

will have to specify the installation directories as these most probably have changed since perl itself has been installed. They will have to do this by calling

perl Makefile.PL INSTALLSITELIB=/afs/here/today \
    INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
make

Be careful to repeat this procedure every time you recompile an extension, unless you are sure the AFS installation directories are still valid.

#Static Linking of a new Perl Binary

An extension that is built with the above steps is ready to use on systems supporting dynamic loading. On systems that do not support dynamic loading, any newly created extension has to be linked together with the available resources. MakeMaker supports the linking process by creating appropriate targets in the Makefile whenever an extension is built. You can invoke the corresponding section of the makefile with

make perl

That produces a new perl binary in the current directory with all extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP, and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on UNIX, this is called Makefile.aperl (may be system dependent). If you want to force the creation of a new perl, it is recommended that you delete this Makefile.aperl, so the directories are searched through for linkable libraries again.

The binary can be installed into the directory where perl normally resides on your machine with

make inst_perl

To produce a perl binary with a different name than perl, either say

perl Makefile.PL MAP_TARGET=myperl
make myperl
make inst_perl

or say

perl Makefile.PL
make myperl MAP_TARGET=myperl
make inst_perl MAP_TARGET=myperl

In any case you will be prompted with the correct invocation of the inst_perl target that installs the new binary into INSTALLBIN.

make inst_perl by default writes some documentation of what has been done into the file $(INSTALLARCHLIB)/perllocal.pod. This can be bypassed by calling make pure_inst_perl.

Warning: the inst_perl: target will most probably overwrite your existing perl binary. Use with care!

Sometimes you might want to build a statically linked perl although your system supports dynamic loading. In this case you may explicitly set the linktype with the invocation of the Makefile.PL or make:

perl Makefile.PL LINKTYPE=static    # recommended

or

make LINKTYPE=static                # works on most systems

#