ExtUtils::MakeMaker - create an extension Makefile use ExtUtils::MakeMaker; WriteMakefile( ATTRIBUTE => VALUE [, ...] ); 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. 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 evaled 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.

Default Makefile Behaviour
The automatically 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. If the user wants to work with a different perl than the default, this is achieved by specifying perl Makefile.PL PERL=/tmp/myperl5 Other interesting targets in the generated Makefile are make config # to check if the Makefile is up-to-date make clean # delete local temporary files (Makefile gets renamed) make realclean # delete all derived files (including installed files) make dist # see below the Distribution Support section

Special case make install
make alone puts all relevant files into directories that are named by the macros INST_LIB, INST_ARCHLIB, and INST_EXE. All three default to ./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_EXE is not defined. The install target of the generated Makefile is a recursive call to make which sets INST_LIB to INSTALLPRIVLIB INST_ARCHLIB to INSTALLARCHLIB INST_EXE to INSTALLBIN 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 # case: trust the module perl Makefile.PL INST_LIB=~/perllib INST_EXE=~/bin make make test or perl Makefile.PL INSTALLPRIVLIB=~/foo \ INSTALLARCHLIB=~/foo/bar INSTALLBIN=~/bin make make test make install 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: perl Makefile.PL; make; make test make install (make test is not necessarily supported for all modules.) make install per default writes some documentation of what has been done into the file $Config{'installarchlib'}/perllocal.pod. This is an experimental feature. It can be bypassed by calling make pure_install.

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 make perl That produces a new perl binary in the current directory with all extensions linked in that can be found in INST_ARCHLIB (usually ./blib) and PERL_ARCHLIB. 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. Note, that there is a makeaperl scipt in the perl distribution, that supports the linking of a new perl binary in a similar fashion, but with more options. make inst_perl per default writes some documentation of what has been done into the file $Config{'installarchlib'}/perllocal.pod. This can be bypassed by calling make pure_inst_perl. Warning: the inst_perl: target is rather mighty and will probably overwrite your existing perl binary. Use with care!

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*.*). 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 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: PERL_INC = PERL_SRC PERL_LIB = PERL_SRC/lib PERL_ARCHLIB = PERL_SRC/lib INST_LIB = PERL_LIB INST_ARCHLIB = PERL_ARCHLIB 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: PERL_INC = $archlib/CORE PERL_LIB = $privlib PERL_ARCHLIB = $archlib INST_LIB = ./blib INST_ARCHLIB = ./blib If perl has not yet been installed then PERL_SRC can be defined on the command line as shown in the previous section.

Useful Default Makefile Macros
FULLEXT = Pathname for extension directory (eg DBD/Oracle). 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_LIB)$(ROOTEXT) INST_AUTODIR = $(INST_LIB)/auto/$(FULLEXT) INST_ARCHAUTODIR = $(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: This description is not yet documented; you can get at the description with one of the commands

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: sub MY::c_o { "new literal text" } or you can edit the default by saying something like: sub MY::c_o { $_=MM->c_o; s/old text/new text/; $_ } 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.

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. -Nv$(VERSION_SYM):) on all files in the MANIFEST file" 4 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: TAR ('tar') TARFLAGS ('cvf') COMPRESS ('compress') SUFFIX ('Z') SHAR ('shar') PREOP ('@ :') POSTOP ('@ :') An example: WriteMakefile( 'dist' => { COMPRESS=>"gzip", SUFFIX=>"gz" }) 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 the mailto:makemaker@franz.ww.tu-berlin.de manpage, if you have any questions. 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 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 \W characters replaced by an underscore. 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 => BAR }) defines the macro FOO = BAR in the generated Makefile. Rolled in Tim's patch for needs_linking. writedoc now tries to be less clever. It was trying to determine, if a perllocal.pod had to be created or appended to. As we have now the possibility, that INSTALLARCHLIB is determined at make's runtime, we cannot do this anymore. We append to that file in any case. Added Kenneth's pod installation patch. v4.110 May 19 1995 by Andreas Koenig MANIFEST.SKIP now contains only regular expressions. RCS directories are no longer skipped by default, as this may be configured in the SKIP file. 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 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. "Please notify perl5-porters" message is now accompanied by Config::myconfig(). (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 :) Reintroduces the LD_RUN_PATH macro. LD_RUN_PATH is passed as an environment variable to the ld run. It is needed on Sun OS, and does no harm on other systems. It is a colon seperated list of the directories in LDLOADLIBS. Add -I$(PERL_ARCHLIB) -I$(PERL_LIB) to calls to xsubpp. Split test: target into test_static: and test_dynamic: with automatic selection based on LINKTYPE. The test_static: target automatically builds a local ./perl binary containing the extension and executes the tests using that binary. This fixes problems that users were having dealing with building and testing static extensions. It also simplifies the process down to the standard: make + make test. MakeMaker no longer incorrectly considers a perlmain.c file to be part of an extensions source files. The map_clean target is now invoked by clean not realclean and now deletes MAP_TARGET but does not delete Makefile (since that's done properly elsewhere). Since the staticmake section defines macros that the test target now needs the test section is written into the makefile after the staticmake section. The postamble section has been made last again, as it should be. Needs more complete documentation. Add a html: target when there has been found a general solution to installing html files. 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).