use ExtUtils::MakeMaker;
WriteMakefile( ATTRIBUTE => VALUE [, ...] );
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.
MakeMaker.pm uses the architecture specific information from
Config.pm. In addition the extension may contribute to the %Config
hash table of Config.pm by supplying hints files in a hints/
directory. The hints files are expected to be named like their
counterparts in PERL_SRC/hints
, but with an .pl
file name
extension (eg. next_3_2.pl
). They are simply eval
ed by MakeMaker
within the WriteMakefile() subroutine, and can be used to execute
commands as well as to include special variables. If there is no
hintsfile for the actual system, but for some previous releases of the
same operating system, the latest one of those is used.
The Makefile to be produced may be altered by adding arguments of the
form KEY=VALUE
. If the user wants to work with a different perl
than the default, this is achieved by specifying
Other interesting targets in the generated Makefile are
The install target of the generated Makefile is a recursive call to make which sets
The three INSTALL... macros in turn default to $Config{installprivlib}, $Config{installarchlib}, and $Config{installbin} respectively.
The recommended way to proceed is to set only the INSTALL* macros, not the INST_* targets. In doing so, you give room to the compilation process without affecting important directories. Usually a 'make test' will succeed after the make, and a 'make install' can finish the game.
MakeMaker gives you much more freedom than needed to configure internal variables and get different results. It is worth to mention, that make(1) also lets you configure most of the variables that are used in the Makefile. But in the majority of situations this will not be necessary, and should only be done, if the author of a package recommends it.
The usual relationship between INSTALLPRIVLIB and INSTALLARCHLIB is
that the latter is a subdirectory of the former with the name
$Config{'archname'}
, MakeMaker supports the user who sets
INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not, then
MakeMaker defaults the latter to be INSTALLPRIVLIB/ARCHNAME if that
directory exists, otherwise it defaults to INSTALLPRIVLIB.
Previous versions of MakeMaker suggested to use the INST_* macros. For backwards compatibility, these are still supported but deprecated in favor of the INSTALL* macros.
Here is the description, what they are used for: If the user specifies the final destination for the INST_... macros, then there is no need to call 'make install', because 'make' will already put all files in place.
If there is a need to first build everything in the ./blib
directory and test the product, then it's appropriate to use the
INSTALL... macros. So the users have the choice to either say
or
Note, that the tilde expansion is done by MakeMaker, not by perl by default, nor by make. So be careful to use the tilde only with the perl Makefile.PL call.
It is important to know, that the INSTALL* macros should be absolute paths, never relativ ones. Packages with multiple Makefile.PLs in different directories get the contents of the INSTALL* macros propagated verbatim. (The INST_* macros will be corrected, if they are relativ paths, but not the INSTALL* macros.)
If the user has superuser privileges, and is not working on AFS (Andrew File System) or relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB, and INSTALLBIN will be appropriate, and this incantation will be the best:
( make test is not necessarily supported for all modules.)
make install
per default writes some documentation of what has been
done into the file
That produces a new perl binary in the current directory with all
extensions linked in that can be found in INST_ARCHLIB (usually
The binary can be installed into the directory where perl normally
resides on your machine with
To produce a perl binary with a different name than
perl
, either say
or say
In any case you will be prompted with the correct invocation of the
Note, that there is a
make inst_perl
per default writes some documentation of what has been
done into the file Warning: the inst_perl: target is rather mighty and will probably
overwrite your existing perl binary. Use with care!
Extensions may be built either using the contents of the perl source
directory tree or from an installed copy of the perl library.
If an extension is being built below the
If an extension is being built away from the perl source then MakeMaker
will leave PERL_SRC undefined and default to using the installed copy
of the perl library. The other variables default to the following:
If perl has not yet been installed then PERL_SRC can be defined on the
command line as shown in the previous section.
BASEEXT = Basename part of FULLEXT. May be just equal FULLEXT.
ROOTEXT = Directory part of FULLEXT with leading slash (eg /DBD)
PERL_LIB = Directory where we read the perl library files
PERL_ARCHLIB = Same as above for architecture dependent files
INST_LIB = Directory where we put library files of this extension
while building it. If we are building below PERL_SRC/ext
we default to PERL_SRC/lib, else we default to ./blib.
INST_ARCHLIB = Same as above for architecture dependent files
INST_LIBDIR = INST_AUTODIR = INST_ARCHAUTODIR =
This description is not yet documented; you can get at the description
with one of the commands
or you can edit the default by saying something like:
If you still need a different solution, try to develop another
subroutine, that fits your needs and submit the diffs to
perl5-porters@nicoh.com or comp.lang.perl as appropriate.
Customization of the dist targets can be done by specifying a hash
reference to the dist attribute of the WriteMakefile call. The
following parameters are recognized:
An example:
v4.100 May 10 1995 by Andreas Koenig
Broken out Mkbootstrap to make the file smaller and easier to manage,
and to speed up the build process.
Added ExtUtils::Manifest as an extra module that is used to streamline
distributions. (See pod section distribution support).
Added a VERSION_SYM macro, that is derived from VERSION but all Moved the whole documentation below __END__ for easier maintanance.
linkext => { LINKTYPE => '' } should work now as expected.
Rechecked the use of INST_LIB, INST_ARCHLIB, and INST_EXE from the
perspective of an AFS user (thanks to Rudolph T Maceyko for the
hint). With full backward compatiblity it is now possible, to set
INSTALLPRIVLIB, INSTALLARCHLIB, and INSTALLBIN either with 'perl
Makefile.PL' or with 'make install'. A bare 'make' ignores these
settings. The effect of this change is that it is no longer
recommended to set the INST_* attributes directly, although it doesn't
hurt, if they do so. The PASTHRU variables (now PASTHRU1 and PASTHRU2)
are fully aware of their duty: the INST_* attributes are only
propagated to runsubdirpl, not to 'cd subdir && make config' and 'cd
subdir && make all'.
Included Tim's "Unable to locate Perl library" patch.
Eliminated any excess of spaces in the $old/$new comparison in
const_cccmd().
Added a prompt function with usage $answer = prompt $message, $default.
Included Tim's patch that searches for perl5 and perl$] as well as
perl and miniperl.
Added .NO_PARALLEL for the time until I have a multiple cpu machine
myself :)
Introduced a macro() subroutine. WriteMakefile("macro" => { FOO
The manifest target now does no realclean anymore.
I_PERL_LIBS depreciated (no longer used). (unless you speak up, of
course)
I could not justify that we rebuild the Makefile when MakeMaker has
changed (as Kenneth suggested). If this is really a strong desire,
please convince me. But a minor change of the MakeMaker should not
trigger a 60 minutes rebuild of Tk, IMO.
Broken out extliblist into the new module ExtUtils::Liblist. Should
help extension writers for their own Configure scripts. The breaking
into pieces should be done now, I suppose.
Added an (experimenta!!) uninstall target that works with a
packlist. AutoSplit files are not yet in the packlist. This needs a
patch to AutoSplit, doesn't it? The packlist file is installed in
INST_ARCHAUTODIR/.packlist. It doesn't have means to decide, if a file
is architecture dependent or not, we just collect as much as we can
get. make -n recommended before actually executing. (I leave this
target undocumented in the pod section). Suggestions welcome!
Added basic chmod support. Nothing spectacular. *.so and *.a files get
permission 755, because I seem to recall, that some systems need
execute permissions in some weird constellations. The rest becomes
644. What else do we need to make this flexible?
Then I took Tim's word serious: no bloat. No turning all packages into
perl scripts. Leaving shar, tar, uu be what they are... Sorry,
Kenneth, we still have to convince Larry that a growing MakeMaker
makes sense :)
Added an extra check whenever they install below the perl source tree:
is this extension a standard extension? If it is, everything behaves
as we are used to. If it is not, the three INST_ macros are set to
./blib, and they get a warning that this extension has to be
installed manually with 'make install'.
Added a warning for targets that have a colon or a hashmark within
their names, because most make(1)s will not be able to process them.
Applied Hallvard's patch to ~user evaluation for cases where user does
not exist.
Added a ci target that checks in all files from the MANIFEST into rcs.
(Manifest.pm) Change delimiter for the evaluation of the regexes from
MANIFEST.SKIP to from "!" to "/". I had overlooked the fact, that ! no
has a meaning in regular expressions.
Disabled the new logic that prevents non-standard extensions from
writing to PERL_SRC/lib to give Andy room for 5.001f.
Added a Version_check target that calls MakeMaker for a simple Version
control function on every invocation of 'make' in the future. Doesn't
have an effect currently.
Target dist is still defaulting to tardist, but the level of
indirection has changed. The Makefile macro DIST_DEFAULT takes it's
place. This allows me to make dist dependent from whatever I intend as
my standard distribution.
Made sure that INST_EXE is created for extensions that need it.
4.13 is just a cleanup/documentation patch. And it adds a MakeMaker FAQ :)
Add a Add a FLAVOR variable that makes it easier to build debugging,
embedded or multiplicity perls. Currently the easiest way to produce a
debugging perl seems to be (after haveing built perl):
make clobber
./Configure -D"archname=IP22-irix-d" -des
make perllib=libperld.a
make test perllib=libperld.a
mv /usr/local/bin/perl /usr/local/bin/perl/O_perl5.001e
make install perllib=libperld.a
cp /usr/local/bin/perl/O_perl5.001e /usr/local/bin/perl
It would be nice, if the Configure step could be dropped. Also nice, but
maybe expensive, if 'make clobber' wouldn't be needed.
The uninstall target has to be completed, it's just a sketch.
Reconsider Makefile macros. The output of macro() should be the last
before PASTHRU and none should come after that -- tough work.
Think about Nick's desire, that the pTk subdirectory needs a special
treatment.
Find a way to have multiple MYEXTLIB archive files combined into
one. Actually I need some scenario, where this problem can be
illustrated. I currently don't see the problem.
Test if .NOPARALLEL can be omitted.
Don't let extensions write to PERL_SRC/lib anymore, build perl from
the extensions found below ext, run 'make test' and 'make install' on
each extension (giving room for letting them fail). Move some of the
tests from t/lib/* to the libraries.
Streamline the production of a new perl binary on systems that DO have
dynamic loading (especially make test needs further support, as test
most probably needs the new binary).
$Config{'installarchlib'}/perllocal.pod
. This is
an experimental feature. It can be bypassed by calling C
Support to Link a new Perl Binary (eg dynamic loading not available)
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
./blib
) and PERL_ARCHLIB.
inst_perl
target that installs the new binary into INSTALLBIN.
makeaperl
scipt in the perl distribution,
that supports the linking of a new perl binary in a similar fashion,
but with more options.
$Config{'installarchlib'}/perllocal.pod
. This
can be bypassed by calling
make pure_inst_perl
.
Determination of Perl Library and Installation Locations
MakeMaker needs to know, or to guess, where certain things are
located. Especially INST_LIB and INST_ARCHLIB (where to install files
into), PERL_LIB and PERL_ARCHLIB (where to read existing modules
from), and PERL_INC (header files and libperl*.*
).
ext/
directory of the perl
source then MakeMaker will set PERL_SRC automatically (e.g., ../..
).
If PERL_SRC is defined then other variables default to the following:
Useful Default Makefile Macros
FULLEXT = Pathname for extension directory (eg DBD/Oracle).
$(INST_LIB)$(ROOTEXT)
$(INST_LIB)/auto/$(FULLEXT)
$(INST_ARCHLIB)/auto/$(FULLEXT)
Customizing The Generated Makefile
If the Makefile generated does not fit your purpose you can change it
using the mechanisms described below.
Using Attributes (and Parameters)
The following attributes can be specified as arguments to WriteMakefile()
or as NAME=VALUE pairs on the command line:
.
Overriding MakeMaker Methods
If you cannot achieve the desired Makefile behaviour by specifying
attributes you may define private subroutines in the Makefile.PL.
Each subroutines returns the text it wishes to have written to
the Makefile. To override a section of the Makefile you can
either say:
Distribution Support
For authors of extensions MakeMaker provides several Makefile
targets. Most of the support comes from the ExtUtils::Manifest module,
where additional documentation can be found.
.
$(DISTNAME)-$(VERSION)
. If that directory
exists, it will be removed first.
tar
on that directory into a tarfile. Then
deletes the distdir. Finishes with a command $(POSTOP) which defaults
to a null command.
shar
on that directory into a sharfile. Then
deletes the distdir. Finishes with a command $(POSTOP) which defaults
to a null command. Note: For shdist to work properly a shar
program that can handle directories is mandatory.
ci -u
) and a $(RCS) (C
AUTHORS
Andy Dougherty <doughera@lafcol.lafayette.edu>, Andreas
Koenig <k@franz.ww.TU-Berlin.DE>, Tim Bunce
<Tim.Bunce@ig.co.uk>. VMS support by Charles Bailey
<bailey@HMIVAX.HUMGEN.UPENN.EDU>. Contact the makemaker
mailing list mailto:makemaker@franz.ww.tu-berlin.de, if you have any
questions.
MODIFICATION HISTORY
v1, August 1994; by Andreas Koenig. Based on Andy Dougherty's Makefile.SH.
v2, September 1994 by Tim Bunce.
v3.0 October 1994 by Tim Bunce.
v3.1 November 11th 1994 by Tim Bunce.
v3.2 November 18th 1994 by Tim Bunce.
v3.3 November 27th 1994 by Andreas Koenig.
v3.4 December 7th 1994 by Andreas Koenig and Tim Bunce.
v3.5 December 15th 1994 by Tim Bunce.
v3.6 December 15th 1994 by Tim Bunce.
v3.7 December 30th 1994 By Tim Bunce
v3.8 January 17th 1995 By Andreas Koenig and Tim Bunce
v3.9 January 19th 1995 By Tim Bunce
v3.10 January 23rd 1995 By Tim Bunce
v3.11 January 24th 1995 By Andreas Koenig
v4.00 January 24th 1995 By Tim Bunce
v4.01 January 25th 1995 By Tim Bunce
v4.02 January 29th 1995 By Andreas Koenig
v4.03 January 30th 1995 By Andreas Koenig
v4.04 Februeary 5th 1995 By Andreas Koenig
v4.05 February 8th 1995 By Andreas Koenig
v4.06 February 10th 1995 By Andreas Koenig
v4.061 February 12th 1995 By Andreas Koenig
v4.08 - 4.085 February 14th-21st 1995 by Andreas Koenig
v4.086 March 9 1995 by Andy Dougherty
v4.09 March 31 1995 by Andreas Koenig
v4.091 April 3 1995 by Andy Dougherty
v4.092 April 11 1995 by Andreas Koenig
v4.093 April 12 1995 by Andy Dougherty
v4.094 April 12 1995 by Andy Dougherty
\W
characters replaced by an underscore.
NEW in 4.11
MANIFEST.SKIP now contains only regular expressions. RCS directories
are no longer skipped by default, as this may be configured in the
SKIP file.
new in 4.12/4.13
"Please notify perl5-porters" message is now accompanied by
Config::myconfig().
TODO
Needs more complete documentation.
html:
target when there has been found a general solution to
installing html files.