1 BEGIN {require 5.002;} # MakeMaker 5.17 was the last MakeMaker that was compatible with perl5.001m
3 package ExtUtils::MakeMaker;
6 $Version_OK = "5.17"; # Makefiles older than $Version_OK will die
7 # (Will be checked from MakeMaker version 4.13 onwards)
8 ($Revision = substr(q$Revision: 1.222 $, 10)) =~ s/\s+$//;
19 @ISA @EXPORT @EXPORT_OK $AUTOLOAD
20 $ISA_TTY $Is_Mac $Is_OS2 $Is_VMS $Revision
21 $VERSION $Verbose $Version_OK %Config %Keep_after_flush
22 %MM_Sections %Prepend_dot_dot %Recognized_Att_Keys
23 @Get_from_Config @MM_Sections @Overridable @Parent
28 # &DynaLoader::mod2fname should be available to miniperl, thus
29 # should be a pseudo-builtin (cmp. os2.c).
30 #eval {require DynaLoader;};
33 # Set up the inheritance before we pull in the MM_* packages, because they
34 # import variables and functions from here
37 @EXPORT = qw(&WriteMakefile &writeMakefile $Verbose &prompt);
38 @EXPORT_OK = qw($VERSION &Version_check &neatvalue &mkbootstrap &mksymlists);
41 # Dummy package MM inherits actual methods from OS-specific
42 # default packages. We use this intermediate package so
43 # MY::XYZ->func() can call MM->func() and get the proper
44 # default routine without having to know under what OS
47 @MM::ISA = qw[ExtUtils::MM_Unix ExtUtils::Liblist ExtUtils::MakeMaker];
50 # Setup dummy package:
51 # MY exists for overriding methods to be defined within
56 ### sub AUTOLOAD { use Devel::Symdump; print Devel::Symdump->rnew->as_string; Carp::confess "hey why? $AUTOLOAD" }
61 # "predeclare the package: we only load it via AUTOLOAD
62 # but we have already mentioned it in @ISA
63 package ExtUtils::Liblist;
65 package ExtUtils::MakeMaker;
67 # Now we can pull in the friends
69 $Is_VMS = $^O eq 'VMS';
70 $Is_OS2 = $^O eq 'os2';
71 $Is_Mac = $^O eq 'MacOS';
72 $Is_Win32 = $^O eq 'MSWin32';
73 $Is_Cygwin= $^O eq 'cygwin';
75 require ExtUtils::MM_Unix;
78 require ExtUtils::MM_VMS;
79 require VMS::Filespec; # is a noop as long as we require it within MM_VMS
82 require ExtUtils::MM_OS2;
85 require ExtUtils::MM_MacOS;
88 require ExtUtils::MM_Win32;
91 require ExtUtils::MM_Cygwin;
96 # The use of the Version_check target has been dropped between perl
97 # 5.5.63 and 5.5.64. We must keep the subroutine for a while so that
98 # old Makefiles can satisfy the Version_check target.
101 my($checkversion) = @_;
102 die "Your Makefile was built with ExtUtils::MakeMaker v $checkversion.
103 Current Version is $ExtUtils::MakeMaker::VERSION. There have been considerable
104 changes in the meantime.
105 Please rerun 'perl Makefile.PL' to regenerate the Makefile.\n"
106 if $checkversion < $Version_OK;
107 printf STDOUT "%s %s %s %s.\n", "Makefile built with ExtUtils::MakeMaker v",
108 $checkversion, "Current Version is", $VERSION
109 unless $checkversion == $VERSION;
113 $_[0] =~ /^Use of uninitialized value/ && return;
114 $_[0] =~ /used only once/ && return;
115 $_[0] =~ /^Subroutine\s+[\w:]+\s+redefined/ && return;
120 Carp::croak "WriteMakefile: Need even number of args" if @_ % 2;
121 local $SIG{__WARN__} = \&warnhandler;
124 MM->new(\%att)->flush;
129 $ISA_TTY = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ; # Pipe?
130 Carp::confess("prompt function called without an argument") unless defined $mess;
131 my $dispdef = defined $def ? "[$def] " : " ";
132 $def = defined $def ? $def : "";
135 print "$mess $dispdef";
137 chomp($ans = <STDIN>);
141 return ($ans ne '') ? $ans : $def;
144 sub eval_in_subdirs {
150 foreach $dir (@{$self->{DIR}}){
151 my($abs) = $self->catdir($pwd,$dir);
152 $self->eval_in_x($abs);
160 chdir $dir or Carp::carp("Couldn't change to directory $dir: $!");
162 # my $fh = new FileHandle;
163 # $fh->open("Makefile.PL") or Carp::carp("Couldn't open Makefile.PL in $dir");
165 open(FH,"Makefile.PL") or Carp::carp("Couldn't open Makefile.PL in $dir");
166 # my $eval = join "", <$fh>;
167 my $eval = join "", <FH>;
172 # if ($@ =~ /prerequisites/) {
173 # die "MakeMaker WARNING: $@";
175 # warn "WARNING from evaluation of $dir/Makefile.PL: $@";
177 warn "WARNING from evaluation of $dir/Makefile.PL: $@";
184 # package name for the classes into which the first object will be blessed
185 $PACKNAME = "PACK000";
189 AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION
190 C CAPI CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DL_FUNCS DL_VARS
191 EXCLUDE_EXT EXE_FILES FIRST_MAKEFILE FULLPERL FUNCLIST H
192 HTMLLIBPODS HTMLSCRIPTPODS IMPORTS
193 INC INCLUDE_EXT INSTALLARCHLIB INSTALLBIN INSTALLDIRS INSTALLHTMLPRIVLIBDIR
194 INSTALLHTMLSCRIPTDIR INSTALLHTMLSITELIBDIR INSTALLMAN1DIR
195 INSTALLMAN3DIR INSTALLPRIVLIB INSTALLSCRIPT INSTALLSITEARCH
196 INSTALLSITELIB INST_ARCHLIB INST_BIN INST_EXE INST_LIB
197 INST_HTMLLIBDIR INST_HTMLSCRIPTDIR
198 INST_MAN1DIR INST_MAN3DIR INST_SCRIPT LDFROM LIB LIBPERL_A LIBS
199 LINKTYPE MAKEAPERL MAKEFILE MAN1PODS MAN3PODS MAP_TARGET MYEXTLIB
201 NAME NEEDS_LINKING NOECHO NORECURS NO_VC OBJECT OPTIMIZE PERL PERLMAINCC
202 PERL_ARCHLIB PERL_LIB PERL_SRC PERM_RW PERM_RWX
203 PL_FILES PM PMLIBDIRS POLLUTE PPM_INSTALL_EXEC PPM_INSTALL_SCRIPT PREFIX
204 PREREQ_PM SKIP TYPEMAPS VERSION VERSION_FROM XS XSOPT XSPROTOARG
205 XS_VERSION clean depend dist dynamic_lib linkext macro realclean
209 # IMPORTS is used under OS/2 and Win32
211 # @Overridable is close to @MM_Sections but not identical. The
212 # order is important. Many subroutines declare macros. These
213 # depend on each other. Let's try to collect the macros up front,
214 # then pasthru, then the rules.
216 # MM_Sections are the sections we have to call explicitly
217 # in Overridable we have subroutines that are used indirectly
223 post_initialize const_config constants tool_autosplit tool_xsubpp
224 tools_other dist macro depend cflags const_loadlibs const_cccmd
229 c_o xs_c xs_o top_targets linkext dlsyms dynamic dynamic_bs
230 dynamic_lib static static_lib htmlifypods manifypods processPL
232 clean realclean dist_basics dist_core dist_dir dist_test dist_ci
233 install force perldepend makefile staticmake test ppd
235 ); # loses section ordering
237 @Overridable = @MM_Sections;
238 push @Overridable, qw[
240 dir_target libscan makeaperl needs_linking perm_rw perm_rwx
241 subdir_x test_via_harness test_via_script
245 push @MM_Sections, qw[
247 pm_to_blib selfdocument
251 # Postamble needs to be the last that was always the case
252 push @MM_Sections, "postamble";
253 push @Overridable, "postamble";
255 # All sections are valid keys.
256 @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
258 # we will use all these variables in the Makefile
261 ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
262 lib_ext obj_ext osname osvers ranlib sitelibexp sitearchexp so
267 foreach $item (@Attrib_help){
268 $Recognized_Att_Keys{$item} = 1;
270 foreach $item (@Get_from_Config) {
271 $Recognized_Att_Keys{uc $item} = $Config{$item};
272 print "Attribute '\U$item\E' => '$Config{$item}'\n"
277 # When we eval a Makefile.PL in a subdirectory, that one will ask
278 # us (the parent) for the values and will prepend "..", so that
279 # all files to be installed end up below OUR ./blib
284 INST_BIN 1 INST_EXE 1 INST_LIB 1 INST_ARCHLIB 1 INST_SCRIPT 1
285 MAP_TARGET 1 INST_HTMLLIBDIR 1 INST_HTMLSCRIPTDIR 1
286 INST_MAN1DIR 1 INST_MAN3DIR 1 PERL_SRC 1 PERL 1 FULLPERL 1
291 NEEDS_LINKING HAS_LINK_CODE
293 @Keep_after_flush{@keep} = (1) x @keep;
299 The extension you are trying to build apparently is rather old and
300 most probably outdated. We detect that from the fact, that a
301 subroutine "writeMakefile" is called, and this subroutine is not
302 supported anymore since about October 1994.
304 Please contact the author or look into CPAN (details about CPAN can be
305 found in the FAQ and at http:/www.perl.com) for a more recent version
306 of the extension. If you're really desperate, you can try to change
307 the subroutine name from writeMakefile to WriteMakefile and rerun
308 'perl Makefile.PL', but you're most probably left alone, when you do
316 sub ExtUtils::MakeMaker::new {
317 my($class,$self) = @_;
320 print STDOUT "MakeMaker (v$VERSION)\n" if $Verbose;
321 if (-f "MANIFEST" && ! -f "Makefile"){
325 $self = {} unless (defined $self);
329 my(%initial_att) = %$self; # record initial attributes
332 foreach $prereq (sort keys %{$self->{PREREQ_PM}}) {
333 my $eval = "require $prereq";
337 warn "Warning: prerequisite $prereq failed to load: $@";
339 elsif ($prereq->VERSION < $self->{PREREQ_PM}->{$prereq} ){
340 warn "Warning: prerequisite $prereq $self->{PREREQ_PM}->{$prereq} not found";
341 # Why is/was this 'delete' here? We need PREREQ_PM later to make PPDs.
343 # delete $self->{PREREQ_PM}{$prereq};
347 # unless (defined $ExtUtils::MakeMaker::useCPAN) {
348 # print qq{MakeMaker WARNING: prerequisites not found (@unsatisfied)
349 # Please install these modules first and rerun 'perl Makefile.PL'.\n};
350 # if ($ExtUtils::MakeMaker::hasCPAN) {
351 # $ExtUtils::MakeMaker::useCPAN = prompt(qq{Should I try to use the CPAN module to fetch them for you?},"yes");
353 # print qq{Hint: You may want to install the CPAN module to autofetch the needed modules\n};
354 # $ExtUtils::MakeMaker::useCPAN=0;
357 # if ($ExtUtils::MakeMaker::useCPAN) {
359 # CPAN->import(@unsatisfied);
361 # die qq{prerequisites not found (@unsatisfied)};
363 # warn qq{WARNING: prerequisites not found (@unsatisfied)};
366 if (defined $self->{CONFIGURE}) {
367 if (ref $self->{CONFIGURE} eq 'CODE') {
368 $self = { %$self, %{&{$self->{CONFIGURE}}}};
370 Carp::croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
374 # This is for old Makefiles written pre 5.00, will go away
375 if ( Carp::longmess("") =~ /runsubdirpl/s ){
376 Carp::carp("WARNING: Please rerun 'perl Makefile.PL' to regenerate your Makefiles\n");
379 my $newclass = ++$PACKNAME;
380 local @Parent = @Parent; # Protect against non-local exits
383 print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
384 mv_all_methods("MY",$newclass);
385 bless $self, $newclass;
387 @{"$newclass\:\:ISA"} = 'MM';
390 if (defined $Parent[-2]){
391 $self->{PARENT} = $Parent[-2];
393 for $key (keys %Prepend_dot_dot) {
394 next unless defined $self->{PARENT}{$key};
395 $self->{$key} = $self->{PARENT}{$key};
396 # PERL and FULLPERL may be command verbs instead of full
397 # file specifications under VMS. If so, don't turn them
399 $self->{$key} = $self->catdir("..",$self->{$key})
400 unless $self->file_name_is_absolute($self->{$key})
401 || ($^O eq 'VMS' and ($key =~ /PERL$/ && $self->{$key} =~ /^[\w\-\$]+$/));
403 if ($self->{PARENT}) {
404 $self->{PARENT}->{CHILDREN}->{$newclass} = $self;
405 foreach my $opt (qw(CAPI POLLUTE)) {
406 if (exists $self->{PARENT}->{$opt}
407 and not exists $self->{$opt})
409 # inherit, but only if already unspecified
410 $self->{$opt} = $self->{PARENT}->{$opt};
415 parse_args($self,split(' ', $ENV{PERL_MM_OPT} || ''),@ARGV);
418 $self->{NAME} ||= $self->guess_name;
420 ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
424 if (! $self->{PERL_SRC} ) {
425 my($pthinks) = $self->canonpath($INC{'Config.pm'});
426 my($cthinks) = $self->catfile($Config{'archlibexp'},'Config.pm');
427 $pthinks = VMS::Filespec::vmsify($pthinks) if $Is_VMS;
428 if ($pthinks ne $cthinks &&
429 !($Is_Win32 and lc($pthinks) eq lc($cthinks))) {
430 print "Have $pthinks expected $cthinks\n";
432 $pthinks =~ s![/\\]Config\.pm$!!i; $pthinks =~ s!.*[/\\]!!;
435 $pthinks =~ s!/Config\.pm$!!; $pthinks =~ s!.*/!!;
437 print STDOUT <<END unless $self->{UNINSTALLED_PERL};
438 Your perl and your Config.pm seem to have different ideas about the architecture
440 Perl thinks: [$pthinks]
441 Config says: [$Config{archname}]
442 This may or may not cause problems. Please check your installation of perl if you
443 have problems building this extension.
448 $self->init_dirscan();
449 $self->init_others();
450 my($argv) = neatvalue(\@ARGV);
454 push @{$self->{RESULT}}, <<END;
455 # This Makefile is for the $self->{NAME} extension to perl.
457 # It was generated automatically by MakeMaker version
458 # $VERSION (Revision: $Revision) from the contents of
459 # Makefile.PL. Don't edit this file, edit Makefile.PL instead.
461 # ANY CHANGES MADE HERE WILL BE LOST!
463 # MakeMaker ARGV: $argv
465 # MakeMaker Parameters:
468 foreach $key (sort keys %initial_att){
469 my($v) = neatvalue($initial_att{$key});
470 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
472 push @{$self->{RESULT}}, "# $key => $v";
475 # turn the SKIP array into a SKIPHASH hash
477 for $skip (@{$self->{SKIP} || []}) {
478 $self->{SKIPHASH}{$skip} = 1;
480 delete $self->{SKIP}; # free memory
482 if ($self->{PARENT}) {
483 for (qw/install dist dist_basics dist_core dist_dir dist_test dist_ci/) {
484 $self->{SKIPHASH}{$_} = 1;
488 # We run all the subdirectories now. They don't have much to query
489 # from the parent, but the parent has to query them: if they need linking!
490 unless ($self->{NORECURS}) {
491 $self->eval_in_subdirs if @{$self->{DIR}};
495 foreach $section ( @MM_Sections ){
496 print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
497 my($skipit) = $self->skipcheck($section);
499 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
501 my(%a) = %{$self->{$section} || {}};
502 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
503 push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
504 push @{$self->{RESULT}}, $self->nicetext($self->$section( %a ));
508 push @{$self->{RESULT}}, "\n# End.";
513 sub WriteEmptyMakefile {
514 if (-f 'Makefile.old') {
515 chmod 0666, 'Makefile.old';
516 unlink 'Makefile.old' or warn "unlink Makefile.old: $!";
518 rename 'Makefile', 'Makefile.old' or warn "rename Makefile Makefile.old: $!"
520 open MF, '> Makefile' or die "open Makefile for write: $!";
533 close MF or die "close Makefile for write: $!";
537 print STDOUT "Checking if your kit is complete...\n";
538 require ExtUtils::Manifest;
539 $ExtUtils::Manifest::Quiet=$ExtUtils::Manifest::Quiet=1; #avoid warning
540 my(@missed)=ExtUtils::Manifest::manicheck();
542 print STDOUT "Warning: the following files are missing in your kit:\n";
543 print "\t", join "\n\t", @missed;
545 print STDOUT "Please inform the author.\n";
547 print STDOUT "Looks good\n";
552 my($self, @args) = @_;
554 unless (m/(.*?)=(.*)/){
555 help(),exit 1 if m/^help$/;
556 ++$Verbose if m/^verb/;
559 my($name, $value) = ($1, $2);
560 if ($value =~ m/^~(\w+)?/){ # tilde with optional username
561 $value =~ s [^~(\w*)]
563 ((getpwnam($1))[7] || "~$1") :
567 $self->{uc($name)} = $value;
570 # catch old-style 'potential_libs' and inform user how to 'upgrade'
571 if (defined $self->{potential_libs}){
572 my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
573 if ($self->{potential_libs}){
574 print STDOUT "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
576 print STDOUT "$msg deleted.\n";
578 $self->{LIBS} = [$self->{potential_libs}];
579 delete $self->{potential_libs};
581 # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
582 if (defined $self->{ARMAYBE}){
583 my($armaybe) = $self->{ARMAYBE};
584 print STDOUT "ARMAYBE => '$armaybe' should be changed to:\n",
585 "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
586 my(%dl) = %{$self->{dynamic_lib} || {}};
587 $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
588 delete $self->{ARMAYBE};
590 if (defined $self->{LDTARGET}){
591 print STDOUT "LDTARGET should be changed to LDFROM\n";
592 $self->{LDFROM} = $self->{LDTARGET};
593 delete $self->{LDTARGET};
595 # Turn a DIR argument on the command line into an array
596 if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
597 # So they can choose from the command line, which extensions they want
598 # the grep enables them to have some colons too much in case they
599 # have to build a list with the shell
600 $self->{DIR} = [grep $_, split ":", $self->{DIR}];
602 # Turn a INCLUDE_EXT argument on the command line into an array
603 if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
604 $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
606 # Turn a EXCLUDE_EXT argument on the command line into an array
607 if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
608 $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
611 foreach $mmkey (sort keys %$self){
612 print STDOUT " $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
613 print STDOUT "'$mmkey' is not a known MakeMaker parameter name.\n"
614 unless exists $Recognized_Att_Keys{$mmkey};
621 # We allow extension-specific hints files.
623 return unless -d "hints";
625 # First we look for the best hintsfile we have
627 my($hint)="${^O}_$Config{osvers}";
632 # Also try without trailing minor version numbers.
634 last if -f "hints/$hint.pl"; # found
636 last unless $hint =~ s/_[^_]*$//; # nothing to cut off
638 return unless -f "hints/$hint.pl"; # really there
640 # execute the hintsfile:
642 # my $fh = new FileHandle;
643 # $fh->open("hints/$hint.pl");
645 open(FH,"hints/$hint.pl");
646 # @goodhints = <$fh>;
650 print STDOUT "Processing hints file hints/$hint.pl\n";
651 eval join('',@goodhints);
652 print STDOUT $@ if $@;
658 my($symtab) = \%{"${from}::"};
661 # Here you see the *current* list of methods that are overridable
662 # from Makefile.PL via MY:: subroutines. As of VERSION 5.07 I'm
663 # still trying to reduce the list to some reasonable minimum --
664 # because I want to make it easier for the user. A.K.
666 foreach $method (@Overridable) {
668 # We cannot say "next" here. Nick might call MY->makeaperl
669 # which isn't defined right now
671 # Above statement was written at 4.23 time when Tk-b8 was
672 # around. As Tk-b9 only builds with 5.002something and MM 5 is
673 # standard, we try to enable the next line again. It was
674 # commented out until MM 5.23
676 next unless defined &{"${from}::$method"};
678 *{"${to}::$method"} = \&{"${from}::$method"};
680 # delete would do, if we were sure, nobody ever called
681 # MY->makeaperl directly
683 # delete $symtab->{$method};
685 # If we delete a method, then it will be undefined and cannot
686 # be called. But as long as we have Makefile.PLs that rely on
687 # %MY:: being intact, we have to fill the hole with an
690 eval "package MY; sub $method { shift->SUPER::$method(\@_); }";
693 # We have to clean out %INC also, because the current directory is
694 # changed frequently and Graham Barr prefers to get his version
695 # out of a History.pl file which is "required" so woudn't get
696 # loaded again in another extension requiring a History.pl
698 # With perl5.002_01 the deletion of entries in %INC caused Tk-b11
699 # to core dump in the middle of a require statement. The required
700 # file was Tk/MMutil.pm. The consequence is, we have to be
701 # extremely careful when we try to give perl a reason to reload a
702 # library with same name. The workaround prefers to drop nothing
703 # from %INC and teach the writers not to use such libraries.
706 # foreach $inc (keys %INC) {
707 # #warn "***$inc*** deleted";
715 if ($section eq 'dynamic') {
716 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
717 "in skipped section 'dynamic_bs'\n"
718 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
719 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
720 "in skipped section 'dynamic_lib'\n"
721 if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
723 if ($section eq 'dynamic_lib') {
724 print STDOUT "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
725 "targets in skipped section 'dynamic_bs'\n"
726 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
728 if ($section eq 'static') {
729 print STDOUT "Warning (non-fatal): Target 'static' depends on targets ",
730 "in skipped section 'static_lib'\n"
731 if $self->{SKIPHASH}{static_lib} && $Verbose;
733 return 'skipped' if $self->{SKIPHASH}{$section};
741 # my $fh = new FileHandle;
743 print STDOUT "Writing $self->{MAKEFILE} for $self->{NAME}\n";
745 unlink($self->{MAKEFILE}, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : '');
746 # $fh->open(">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
747 open(FH,">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
749 for $chunk (@{$self->{RESULT}}) {
750 # print $fh "$chunk\n";
756 my($finalname) = $self->{MAKEFILE};
757 rename("MakeMaker.tmp", $finalname);
758 chmod 0644, $finalname unless $Is_VMS;
760 if ($self->{PARENT}) {
761 foreach (keys %$self) { # safe memory
762 delete $self->{$_} unless $Keep_after_flush{$_};
766 system("$Config::Config{eunicefix} $finalname") unless $Config::Config{eunicefix} eq ":";
769 # The following mkbootstrap() is only for installations that are calling
770 # the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
771 # writes Makefiles, that use ExtUtils::Mkbootstrap directly.
774 !!! Your Makefile has been built such a long time ago, !!!
775 !!! that is unlikely to work with current MakeMaker. !!!
776 !!! Please rebuild your Makefile !!!
780 # Ditto for mksymlists() as of MakeMaker 5.17
783 !!! Your Makefile has been built such a long time ago, !!!
784 !!! that is unlikely to work with current MakeMaker. !!!
785 !!! Please rebuild your Makefile !!!
791 return "undef" unless defined $v;
793 return "q[$v]" unless $t;
795 my(@m, $elem, @neat);
797 foreach $elem (@$v) {
798 push @neat, "q[$elem]";
800 push @m, join ", ", @neat;
804 return "$v" unless $t eq 'HASH';
806 while (($key,$val) = each %$v){
807 last unless defined $key; # cautious programming in case (undef,undef) is true
808 push(@m,"$key=>".neatvalue($val)) ;
810 return "{ ".join(', ',@m)." }";
817 push @m, "\n# Full list of MakeMaker attribute values:";
818 foreach $key (sort keys %$self){
819 next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
820 my($v) = neatvalue($self->{$key});
821 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
823 push @m, "# $key => $v";
829 package ExtUtils::MakeMaker;
836 ExtUtils::MakeMaker - create an extension Makefile
840 C<use ExtUtils::MakeMaker;>
842 C<WriteMakefile( ATTRIBUTE =E<gt> VALUE [, ...] );>
846 C<MM-E<gt>new(\%att)-E<gt>flush;>
850 This utility is designed to write a Makefile for an extension module
851 from a Makefile.PL. It is based on the Makefile.SH model provided by
852 Andy Dougherty and the perl5-porters.
854 It splits the task of generating the Makefile into several subroutines
855 that can be individually overridden. Each subroutine returns the text
856 it wishes to have written to the Makefile.
858 MakeMaker is object oriented. Each directory below the current
859 directory that contains a Makefile.PL. Is treated as a separate
860 object. This makes it possible to write an unlimited number of
861 Makefiles with a single invocation of WriteMakefile().
863 =head2 How To Write A Makefile.PL
865 The short answer is: Don't.
867 Always begin with h2xs.
868 Always begin with h2xs!
869 ALWAYS BEGIN WITH H2XS!
871 even if you're not building around a header file, and even if you
872 don't have an XS component.
874 Run h2xs(1) before you start thinking about writing a module. For so
875 called pm-only modules that consist of C<*.pm> files only, h2xs has
876 the C<-X> switch. This will generate dummy files of all kinds that are
877 useful for the module developer.
879 The medium answer is:
881 use ExtUtils::MakeMaker;
882 WriteMakefile( NAME => "Foo::Bar" );
884 The long answer is the rest of the manpage :-)
886 =head2 Default Makefile Behaviour
888 The generated Makefile enables the user of the extension to invoke
890 perl Makefile.PL # optionally "perl Makefile.PL verbose"
892 make test # optionally set TEST_VERBOSE=1
893 make install # See below
895 The Makefile to be produced may be altered by adding arguments of the
896 form C<KEY=VALUE>. E.g.
898 perl Makefile.PL PREFIX=/tmp/myperl5
900 Other interesting targets in the generated Makefile are
902 make config # to check if the Makefile is up-to-date
903 make clean # delete local temp files (Makefile gets renamed)
904 make realclean # delete derived files (including ./blib)
905 make ci # check in all the files in the MANIFEST file
906 make dist # see below the Distribution Support section
910 MakeMaker checks for the existence of a file named F<test.pl> in the
911 current directory and if it exists it adds commands to the test target
912 of the generated Makefile that will execute the script with the proper
913 set of perl C<-I> options.
915 MakeMaker also checks for any files matching glob("t/*.t"). It will
916 add commands to the test target of the generated Makefile that execute
917 all matching files via the L<Test::Harness> module with the C<-I>
918 switches set correctly.
922 A useful variation of the above is the target C<testdb>. It runs the
923 test under the Perl debugger (see L<perldebug>). If the file
924 F<test.pl> exists in the current directory, it is used for the test.
926 If you want to debug some other testfile, set C<TEST_FILE> variable
929 make testdb TEST_FILE=t/mytest.t
931 By default the debugger is called using C<-d> option to perl. If you
932 want to specify some other option, set C<TESTDB_SW> variable:
934 make testdb TESTDB_SW=-Dx
938 make alone puts all relevant files into directories that are named by
939 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_HTMLLIBDIR,
940 INST_HTMLSCRIPTDIR, INST_MAN1DIR, and INST_MAN3DIR. All these default
941 to something below ./blib if you are I<not> building below the perl
942 source directory. If you I<are> building below the perl source,
943 INST_LIB and INST_ARCHLIB default to ../../lib, and INST_SCRIPT is not
946 The I<install> target of the generated Makefile copies the files found
947 below each of the INST_* directories to their INSTALL*
948 counterparts. Which counterparts are chosen depends on the setting of
949 INSTALLDIRS according to the following table:
954 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH
955 INST_LIB INSTALLPRIVLIB INSTALLSITELIB
956 INST_HTMLLIBDIR INSTALLHTMLPRIVLIBDIR INSTALLHTMLSITELIBDIR
957 INST_HTMLSCRIPTDIR INSTALLHTMLSCRIPTDIR
959 INST_SCRIPT INSTALLSCRIPT
960 INST_MAN1DIR INSTALLMAN1DIR
961 INST_MAN3DIR INSTALLMAN3DIR
963 The INSTALL... macros in turn default to their %Config
964 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
966 You can check the values of these variables on your system with
970 And to check the sequence in which the library directories are
971 searched by perl, run
973 perl -le 'print join $/, @INC'
976 =head2 PREFIX and LIB attribute
978 PREFIX and LIB can be used to set several INSTALL* attributes in one
979 go. The quickest way to install a module in a non-standard place might
982 perl Makefile.PL LIB=~/lib
984 This will install the module's architecture-independent files into
985 ~/lib, the architecture-dependent files into ~/lib/$archname.
987 Another way to specify many INSTALL directories with a single
990 perl Makefile.PL PREFIX=~
992 This will replace the string specified by C<$Config{prefix}> in all
993 C<$Config{install*}> values.
995 Note, that in both cases the tilde expansion is done by MakeMaker, not
996 by perl by default, nor by make.
998 Conflicts between parameters LIB,
999 PREFIX and the various INSTALL* arguments are resolved so that:
1005 setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
1006 INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
1010 without LIB, setting PREFIX replaces the initial C<$Config{prefix}>
1011 part of those INSTALL* arguments, even if the latter are explicitly
1012 set (but are set to still start with C<$Config{prefix}>).
1016 If the user has superuser privileges, and is not working on AFS
1017 or relatives, then the defaults for
1018 INSTALLPRIVLIB, INSTALLARCHLIB, INSTALLSCRIPT, etc. will be appropriate,
1019 and this incantation will be the best:
1021 perl Makefile.PL; make; make test
1024 make install per default writes some documentation of what has been
1025 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
1026 can be bypassed by calling make pure_install.
1030 will have to specify the installation directories as these most
1031 probably have changed since perl itself has been installed. They will
1032 have to do this by calling
1034 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
1035 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
1038 Be careful to repeat this procedure every time you recompile an
1039 extension, unless you are sure the AFS installation directories are
1042 =head2 Static Linking of a new Perl Binary
1044 An extension that is built with the above steps is ready to use on
1045 systems supporting dynamic loading. On systems that do not support
1046 dynamic loading, any newly created extension has to be linked together
1047 with the available resources. MakeMaker supports the linking process
1048 by creating appropriate targets in the Makefile whenever an extension
1049 is built. You can invoke the corresponding section of the makefile with
1053 That produces a new perl binary in the current directory with all
1054 extensions linked in that can be found in INST_ARCHLIB , SITELIBEXP,
1055 and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1056 UNIX, this is called Makefile.aperl (may be system dependent). If you
1057 want to force the creation of a new perl, it is recommended, that you
1058 delete this Makefile.aperl, so the directories are searched-through
1059 for linkable libraries again.
1061 The binary can be installed into the directory where perl normally
1062 resides on your machine with
1066 To produce a perl binary with a different name than C<perl>, either say
1068 perl Makefile.PL MAP_TARGET=myperl
1075 make myperl MAP_TARGET=myperl
1076 make inst_perl MAP_TARGET=myperl
1078 In any case you will be prompted with the correct invocation of the
1079 C<inst_perl> target that installs the new binary into INSTALLBIN.
1081 make inst_perl per default writes some documentation of what has been
1082 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1083 can be bypassed by calling make pure_inst_perl.
1085 Warning: the inst_perl: target will most probably overwrite your
1086 existing perl binary. Use with care!
1088 Sometimes you might want to build a statically linked perl although
1089 your system supports dynamic loading. In this case you may explicitly
1090 set the linktype with the invocation of the Makefile.PL or make:
1092 perl Makefile.PL LINKTYPE=static # recommended
1096 make LINKTYPE=static # works on most systems
1098 =head2 Determination of Perl Library and Installation Locations
1100 MakeMaker needs to know, or to guess, where certain things are
1101 located. Especially INST_LIB and INST_ARCHLIB (where to put the files
1102 during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1103 existing modules from), and PERL_INC (header files and C<libperl*.*>).
1105 Extensions may be built either using the contents of the perl source
1106 directory tree or from the installed perl library. The recommended way
1107 is to build extensions after you have run 'make install' on perl
1108 itself. You can do that in any directory on your hard disk that is not
1109 below the perl source tree. The support for extensions below the ext
1110 directory of the perl distribution is only good for the standard
1111 extensions that come with perl.
1113 If an extension is being built below the C<ext/> directory of the perl
1114 source then MakeMaker will set PERL_SRC automatically (e.g.,
1115 C<../..>). If PERL_SRC is defined and the extension is recognized as
1116 a standard extension, then other variables default to the following:
1119 PERL_LIB = PERL_SRC/lib
1120 PERL_ARCHLIB = PERL_SRC/lib
1122 INST_ARCHLIB = PERL_ARCHLIB
1124 If an extension is being built away from the perl source then MakeMaker
1125 will leave PERL_SRC undefined and default to using the installed copy
1126 of the perl library. The other variables default to the following:
1128 PERL_INC = $archlibexp/CORE
1129 PERL_LIB = $privlibexp
1130 PERL_ARCHLIB = $archlibexp
1131 INST_LIB = ./blib/lib
1132 INST_ARCHLIB = ./blib/arch
1134 If perl has not yet been installed then PERL_SRC can be defined on the
1135 command line as shown in the previous section.
1138 =head2 Which architecture dependent directory?
1140 If you don't want to keep the defaults for the INSTALL* macros,
1141 MakeMaker helps you to minimize the typing needed: the usual
1142 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1143 by Configure at perl compilation time. MakeMaker supports the user who
1144 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1145 then MakeMaker defaults the latter to be the same subdirectory of
1146 INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
1147 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1148 for INSTALLSITELIB and INSTALLSITEARCH.
1150 MakeMaker gives you much more freedom than needed to configure
1151 internal variables and get different results. It is worth to mention,
1152 that make(1) also lets you configure most of the variables that are
1153 used in the Makefile. But in the majority of situations this will not
1154 be necessary, and should only be done if the author of a package
1155 recommends it (or you know what you're doing).
1157 =head2 Using Attributes and Parameters
1159 The following attributes can be specified as arguments to WriteMakefile()
1160 or as NAME=VALUE pairs on the command line:
1166 One line description of the module. Will be included in PPD file.
1170 Name of the file that contains the package description. MakeMaker looks
1171 for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1172 the first line in the "=head1 NAME" section. $2 becomes the abstract.
1176 String containing name (and email address) of package author(s). Is used
1177 in PPD (Perl Package Description) files for PPM (Perl Package Manager).
1179 =item BINARY_LOCATION
1181 Used when creating PPD files for binary packages. It can be set to a
1182 full or relative path or URL to the binary archive for a particular
1183 architecture. For example:
1185 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
1187 builds a PPD package that references a binary of the C<Agent> package,
1188 located in the C<x86> directory relative to the PPD itself.
1192 Ref to array of *.c file names. Initialised from a directory scan
1193 and the values portion of the XS attribute hash. This is not
1194 currently used by MakeMaker but may be handy in Makefile.PLs.
1198 [This attribute is obsolete in Perl 5.6. PERL_OBJECT builds are C-compatible
1201 Switch to force usage of the Perl C API even when compiling for PERL_OBJECT.
1203 Note that this attribute is passed through to any recursive build,
1204 but if and only if the submodule's Makefile.PL itself makes no mention
1205 of the 'CAPI' attribute.
1209 String that will be included in the compiler call command line between
1210 the arguments INC and OPTIMIZE.
1214 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1215 config.sh. MakeMaker will add to CONFIG the following values anyway:
1235 CODE reference. The subroutine should return a hash reference. The
1236 hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
1237 be determined by some evaluation method.
1241 Something like C<"-DHAVE_UNISTD_H">
1245 Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
1250 Your name for distributing the package (by tar file). This defaults to
1255 Hashref of symbol names for routines to be made available as universal
1256 symbols. Each key/value pair consists of the package name and an
1257 array of routine names in that package. Used only under AIX, OS/2,
1258 VMS and Win32 at present. The routine names supplied will be expanded
1259 in the same way as XSUB names are expanded by the XS() macro.
1262 {"$(NAME)" => ["boot_$(NAME)" ] }
1266 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1267 "NetconfigPtr" => [ 'DESTROY'] }
1269 Please see the L<ExtUtils::Mksymlists> documentation for more information
1270 about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1274 Array of symbol names for variables to be made available as universal symbols.
1275 Used only under AIX, OS/2, VMS and Win32 at present. Defaults to [].
1276 (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
1280 Array of extension names to exclude when doing a static build. This
1281 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
1282 details. (e.g. [ qw( Socket POSIX ) ] )
1284 This attribute may be most useful when specified as a string on the
1285 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
1289 Ref to array of executable files. The files will be copied to the
1290 INST_SCRIPT directory. Make realclean will delete them from there
1293 =item FIRST_MAKEFILE
1295 The name of the Makefile to be produced. Defaults to the contents of
1296 MAKEFILE, but can be overridden. This is used for the second Makefile
1297 that will be produced for the MAP_TARGET.
1301 Perl binary able to run this extension.
1305 This provides an alternate means to specify function names to be
1306 exported from the extension. Its value is a reference to an
1307 array of function names to be exported by the extension. These
1308 names are passed through unaltered to the linker options file.
1312 Ref to array of *.h file names. Similar to C.
1316 Hashref of .pm and .pod files. MakeMaker will default this to all
1317 .pod and any .pm files that include POD directives. The files listed
1318 here will be converted to HTML format and installed as was requested
1321 =item HTMLSCRIPTPODS
1323 Hashref of pod-containing files. MakeMaker will default this to all
1324 EXE_FILES files that include POD directives. The files listed
1325 here will be converted to HTML format and installed as was requested
1330 This attribute is used to specify names to be imported into the
1331 extension. It is only used on OS/2 and Win32.
1335 Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
1339 Array of extension names to be included when doing a static build.
1340 MakeMaker will normally build with all of the installed extensions when
1341 doing a static build, and that is usually the desired behavior. If
1342 INCLUDE_EXT is present then MakeMaker will build only with those extensions
1343 which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])
1345 It is not necessary to mention DynaLoader or the current extension when
1346 filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then
1347 only DynaLoader and the current extension will be included in the build.
1349 This attribute may be most useful when specified as a string on the
1350 command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
1352 =item INSTALLARCHLIB
1354 Used by 'make install', which copies files from INST_ARCHLIB to this
1355 directory if INSTALLDIRS is set to perl.
1359 Directory to install binary files (e.g. tkperl) into.
1363 Determines which of the two sets of installation directories to
1364 choose: installprivlib and installarchlib versus installsitelib and
1365 installsitearch. The first pair is chosen with INSTALLDIRS=perl, the
1366 second with INSTALLDIRS=site. Default is site.
1368 =item INSTALLHTMLPRIVLIBDIR
1370 This directory gets the HTML pages at 'make install' time. Defaults to
1371 $Config{installhtmlprivlibdir}.
1373 =item INSTALLHTMLSCRIPTDIR
1375 This directory gets the HTML pages at 'make install' time. Defaults to
1376 $Config{installhtmlscriptdir}.
1378 =item INSTALLHTMLSITELIBDIR
1380 This directory gets the HTML pages at 'make install' time. Defaults to
1381 $Config{installhtmlsitelibdir}.
1384 =item INSTALLMAN1DIR
1386 This directory gets the man pages at 'make install' time. Defaults to
1387 $Config{installman1dir}.
1389 =item INSTALLMAN3DIR
1391 This directory gets the man pages at 'make install' time. Defaults to
1392 $Config{installman3dir}.
1394 =item INSTALLPRIVLIB
1396 Used by 'make install', which copies files from INST_LIB to this
1397 directory if INSTALLDIRS is set to perl.
1401 Used by 'make install' which copies files from INST_SCRIPT to this
1404 =item INSTALLSITEARCH
1406 Used by 'make install', which copies files from INST_ARCHLIB to this
1407 directory if INSTALLDIRS is set to site (default).
1409 =item INSTALLSITELIB
1411 Used by 'make install', which copies files from INST_LIB to this
1412 directory if INSTALLDIRS is set to site (default).
1416 Same as INST_LIB for architecture dependent files.
1420 Directory to put real binary files during 'make'. These will be copied
1421 to INSTALLBIN during 'make install'
1425 Old name for INST_SCRIPT. Deprecated. Please use INST_SCRIPT if you
1428 =item INST_HTMLLIBDIR
1430 Directory to hold the man pages in HTML format at 'make' time
1432 =item INST_HTMLSCRIPTDIR
1434 Directory to hold the man pages in HTML format at 'make' time
1438 Directory where we put library files of this extension while building
1443 Directory to hold the man pages at 'make' time
1447 Directory to hold the man pages at 'make' time
1451 Directory, where executable files should be installed during
1452 'make'. Defaults to "./blib/script", just to have a dummy location during
1453 testing. make install will copy the files in INST_SCRIPT to
1458 defaults to "$(OBJECT)" and is used in the ld command to specify
1459 what files to link/load from (also see dynamic_lib below for how to
1464 LIB should only be set at C<perl Makefile.PL> time but is allowed as a
1465 MakeMaker argument. It has the effect of
1466 setting both INSTALLPRIVLIB and INSTALLSITELIB to that value regardless any
1467 explicit setting of those arguments (or of PREFIX).
1468 INSTALLARCHLIB and INSTALLSITEARCH are set to the corresponding
1469 architecture subdirectory.
1473 The filename of the perllibrary that will be used together with this
1474 extension. Defaults to libperl.a.
1478 An anonymous array of alternative library
1479 specifications to be searched for (in order) until
1480 at least one library is found. E.g.
1482 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
1484 Mind, that any element of the array
1485 contains a complete set of arguments for the ld
1486 command. So do not specify
1488 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
1490 See ODBM_File/Makefile.PL for an example, where an array is needed. If
1491 you specify a scalar as in
1493 'LIBS' => "-ltcl -ltk -lX11"
1495 MakeMaker will turn it into an array with one element.
1499 'static' or 'dynamic' (default unless usedl=undef in
1500 config.sh). Should only be used to force static linking (also see
1505 Boolean which tells MakeMaker, that it should include the rules to
1506 make a perl. This is handled automatically as a switch by
1507 MakeMaker. The user normally does not need it.
1511 The name of the Makefile to be produced.
1515 Hashref of pod-containing files. MakeMaker will default this to all
1516 EXE_FILES files that include POD directives. The files listed
1517 here will be converted to man pages and installed as was requested
1522 Hashref of .pm and .pod files. MakeMaker will default this to all
1523 .pod and any .pm files that include POD directives. The files listed
1524 here will be converted to man pages and installed as was requested
1529 If it is intended, that a new perl binary be produced, this variable
1530 may hold a name for that binary. Defaults to perl
1534 If the extension links to a library that it builds set this to the
1535 name of the library (see SDBM_File)
1539 Perl module name for this extension (DBD::Oracle). This will default
1540 to the directory name but should be explicitly defined in the
1545 MakeMaker will figure out if an extension contains linkable code
1546 anywhere down the directory tree, and will set this variable
1547 accordingly, but you can speed it up a very little bit if you define
1548 this boolean variable yourself.
1552 Defaults to C<@>. By setting it to an empty string you can generate a
1553 Makefile that echos all commands. Mainly used in debugging MakeMaker
1558 Boolean. Attribute to inhibit descending into subdirectories.
1562 In general, any generated Makefile checks for the current version of
1563 MakeMaker and the version the Makefile was built under. If NO_VC is
1564 set, the version check is neglected. Do not write this into your
1565 Makefile.PL, use it interactively instead.
1569 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
1570 string containing all object files, e.g. "tkpBind.o
1571 tkpButton.o tkpCanvas.o"
1573 (Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)
1577 Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
1578 passed to subdirectory makes.
1582 Perl binary for tasks that can be done by miniperl
1586 The call to the program that is able to compile perlmain.c. Defaults
1591 Same as below, but for architecture dependent files.
1595 Directory containing the Perl library to use.
1597 =item PERL_MALLOC_OK
1599 defaults to 0. Should be set to TRUE if the extension can work with
1600 the memory allocation routines substituted by the Perl malloc() subsystem.
1601 This should be applicable to most extensions with exceptions of those
1607 with bugs in memory allocations which are caught by Perl's malloc();
1611 which interact with the memory allocator in other ways than via
1612 malloc(), realloc(), free(), calloc(), sbrk() and brk();
1616 which rely on special alignment which is not provided by Perl's malloc().
1620 B<NOTE.> Negligence to set this flag in I<any one> of loaded extension
1621 nullifies many advantages of Perl's malloc(), such as better usage of
1622 system resources, error detection, memory usage reporting, catchable failure
1623 of memory allocations, etc.
1627 Directory containing the Perl source code (use of this should be
1628 avoided, it may be undefined)
1632 Desired permission for read/writable files. Defaults to C<644>.
1633 See also L<MM_Unix/perm_rw>.
1637 Desired permission for executable files. Defaults to C<755>.
1638 See also L<MM_Unix/perm_rwx>.
1642 Ref to hash of files to be processed as perl programs. MakeMaker
1643 will default to any found *.PL file (except Makefile.PL) being keys
1644 and the basename of the file being the value. E.g.
1646 {'foobar.PL' => 'foobar'}
1648 The *.PL files are expected to produce output to the target files
1649 themselves. If multiple files can be generated from the same *.PL
1650 file then the value in the hash can be a reference to an array of
1651 target file names. E.g.
1653 {'foobar.PL' => ['foobar1','foobar2']}
1657 Hashref of .pm files and *.pl files to be installed. e.g.
1659 {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
1661 By default this will include *.pm and *.pl and the files found in
1662 the PMLIBDIRS directories. Defining PM in the
1663 Makefile.PL will override PMLIBDIRS.
1667 Ref to array of subdirectories containing library files. Defaults to
1668 [ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
1669 they contain will be installed in the corresponding location in the
1670 library. A libscan() method can be used to alter the behaviour.
1671 Defining PM in the Makefile.PL will override PMLIBDIRS.
1673 (Where BASEEXT is the last component of NAME.)
1677 Release 5.005 grandfathered old global symbol names by providing preprocessor
1678 macros for extension source compatibility. As of release 5.6, these
1679 preprocessor definitions are not available by default. The POLLUTE flag
1680 specifies that the old names should still be defined:
1682 perl Makefile.PL POLLUTE=1
1684 Please inform the module author if this is necessary to successfully install
1685 a module under 5.6 or later.
1687 =item PPM_INSTALL_EXEC
1689 Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
1691 =item PPM_INSTALL_SCRIPT
1693 Name of the script that gets executed by the Perl Package Manager after
1694 the installation of a package.
1698 Can be used to set the three INSTALL* attributes in one go (except for
1699 probably INSTALLMAN1DIR, if it is not below PREFIX according to
1700 %Config). They will have PREFIX as a common directory node and will
1701 branch from that node into lib/, lib/ARCHNAME or whatever Configure
1702 decided at the build time of your perl (unless you override one of
1707 Hashref: Names of modules that need to be available to run this
1708 extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
1709 desired version is the value. If the required version number is 0, we
1710 only check if any version is installed already.
1714 Arryref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1715 Makefile. Caution! Do not use the SKIP attribute for the negligible
1716 speedup. It may seriously damage the resulting Makefile. Only use it
1717 if you really need it.
1721 Ref to array of typemap file names. Use this when the typemaps are
1722 in some directory other than the current directory or when they are
1723 not named B<typemap>. The last typemap in the list takes
1724 precedence. A typemap in the current directory has highest
1725 precedence, even if it isn't listed in TYPEMAPS. The default system
1726 typemap has lowest precedence.
1730 Your version number for distributing the package. This defaults to
1735 Instead of specifying the VERSION in the Makefile.PL you can let
1736 MakeMaker parse a file to determine the version number. The parsing
1737 routine requires that the file named by VERSION_FROM contains one
1738 single line to compute the version number. The first line in the file
1739 that contains the regular expression
1741 /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
1743 will be evaluated with eval() and the value of the named variable
1744 B<after> the eval() will be assigned to the VERSION attribute of the
1745 MakeMaker object. The following lines will be parsed o.k.:
1749 ( $VERSION ) = '$Revision: 1.222 $ ' =~ /\$Revision:\s+([^\s]+)/;
1750 $FOO::VERSION = '1.10';
1751 *FOO::VERSION = \'1.11';
1752 our $VERSION = 1.2.3; # new for perl5.6.0
1754 but these will fail:
1756 my $VERSION = '1.01';
1757 local $VERSION = '1.02';
1758 local $FOO::VERSION = '1.30';
1760 (Putting C<my> or C<local> on the preceding line will work o.k.)
1762 The file named in VERSION_FROM is not added as a dependency to
1763 Makefile. This is not really correct, but it would be a major pain
1764 during development to have to rewrite the Makefile for any smallish
1765 change in that file. If you want to make sure that the Makefile
1766 contains the correct VERSION macro after any change of the file, you
1767 would have to do something like
1769 depend => { Makefile => '$(VERSION_FROM)' }
1771 See attribute C<depend> below.
1775 Hashref of .xs files. MakeMaker will default this. e.g.
1777 {'name_of_file.xs' => 'name_of_file.c'}
1779 The .c files will automatically be included in the list of files
1780 deleted by a make clean.
1784 String of options to pass to xsubpp. This might include C<-C++> or
1785 C<-extern>. Do not include typemaps here; the TYPEMAP parameter exists for
1790 May be set to an empty string, which is identical to C<-prototypes>, or
1791 C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
1792 defaults to the empty string.
1796 Your version number for the .xs file of this package. This defaults
1797 to the value of the VERSION attribute.
1801 =head2 Additional lowercase attributes
1803 can be used to pass parameters to the methods which implement that
1804 part of the Makefile.
1810 {FILES => "*.xyz foo"}
1814 {ANY_TARGET => ANY_DEPENDECY, ...}
1816 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1820 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1821 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1822 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1824 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1825 needed to tell make the target file of the compression. Setting
1826 DIST_CP to ln can be useful, if you need to preserve the timestamps on
1827 your files. DIST_CP can take the values 'cp', which copies the file,
1828 'ln', which links the file, and 'best' which copies symbolic links and
1829 links the rest. Default is 'best'.
1833 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1837 {LINKTYPE => 'static', 'dynamic' or ''}
1839 NB: Extensions that have nothing but *.pm files had to say
1843 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1844 can be deleted safely. MakeMaker recognizes when there's nothing to
1849 {ANY_MACRO => ANY_VALUE, ...}
1853 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1859 =item tool_autosplit
1865 =head2 Overriding MakeMaker Methods
1867 If you cannot achieve the desired Makefile behaviour by specifying
1868 attributes you may define private subroutines in the Makefile.PL.
1869 Each subroutines returns the text it wishes to have written to
1870 the Makefile. To override a section of the Makefile you can
1873 sub MY::c_o { "new literal text" }
1875 or you can edit the default by saying something like:
1878 package MY; # so that "SUPER" works right
1879 my $inherited = shift->SUPER::c_o(@_);
1880 $inherited =~ s/old text/new text/;
1884 If you are running experiments with embedding perl as a library into
1885 other applications, you might find MakeMaker is not sufficient. You'd
1886 better have a look at ExtUtils::Embed which is a collection of utilities
1889 If you still need a different solution, try to develop another
1890 subroutine that fits your needs and submit the diffs to
1891 F<perl5-porters@perl.org> or F<comp.lang.perl.moderated> as appropriate.
1893 For a complete description of all MakeMaker methods see L<ExtUtils::MM_Unix>.
1895 Here is a simple example of how to add a new target to the generated
1900 $(MYEXTLIB): sdbm/Makefile
1901 cd sdbm && $(MAKE) all
1906 =head2 Hintsfile support
1908 MakeMaker.pm uses the architecture specific information from
1909 Config.pm. In addition it evaluates architecture specific hints files
1910 in a C<hints/> directory. The hints files are expected to be named
1911 like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
1912 name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
1913 MakeMaker within the WriteMakefile() subroutine, and can be used to
1914 execute commands as well as to include special variables. The rules
1915 which hintsfile is chosen are the same as in Configure.
1917 The hintsfile is eval()ed immediately after the arguments given to
1918 WriteMakefile are stuffed into a hash reference $self but before this
1919 reference becomes blessed. So if you want to do the equivalent to
1920 override or create an attribute you would say something like
1922 $self->{LIBS} = ['-ldbm -lucb -lc'];
1924 =head2 Distribution Support
1926 For authors of extensions MakeMaker provides several Makefile
1927 targets. Most of the support comes from the ExtUtils::Manifest module,
1928 where additional documentation can be found.
1932 =item make distcheck
1934 reports which files are below the build directory but not in the
1935 MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
1938 =item make skipcheck
1940 reports which files are skipped due to the entries in the
1941 C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
1944 =item make distclean
1946 does a realclean first and then the distcheck. Note that this is not
1947 needed to build a new distribution as long as you are sure that the
1948 MANIFEST file is ok.
1952 rewrites the MANIFEST file, adding all remaining files found (See
1953 ExtUtils::Manifest::mkmanifest() for details)
1957 Copies all the files that are in the MANIFEST file to a newly created
1958 directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
1959 exists, it will be removed first.
1963 Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
1964 a make test in that directory.
1968 First does a distdir. Then a command $(PREOP) which defaults to a null
1969 command, followed by $(TOUNIX), which defaults to a null command under
1970 UNIX, and will convert files in distribution directory to UNIX format
1971 otherwise. Next it runs C<tar> on that directory into a tarfile and
1972 deletes the directory. Finishes with a command $(POSTOP) which
1973 defaults to a null command.
1977 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1979 =item make uutardist
1981 Runs a tardist first and uuencodes the tarfile.
1985 First does a distdir. Then a command $(PREOP) which defaults to a null
1986 command. Next it runs C<shar> on that directory into a sharfile and
1987 deletes the intermediate directory again. Finishes with a command
1988 $(POSTOP) which defaults to a null command. Note: For shdist to work
1989 properly a C<shar> program that can handle directories is mandatory.
1993 First does a distdir. Then a command $(PREOP) which defaults to a null
1994 command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
1995 zipfile. Then deletes that directory. Finishes with a command
1996 $(POSTOP) which defaults to a null command.
2000 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
2004 Customization of the dist targets can be done by specifying a hash
2005 reference to the dist attribute of the WriteMakefile call. The
2006 following parameters are recognized:
2009 COMPRESS ('gzip --best')
2012 TO_UNIX (depends on the system)
2013 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
2023 WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
2025 =head2 Disabling an extension
2027 If some events detected in F<Makefile.PL> imply that there is no way
2028 to create the Module, but this is a normal state of things, then you
2029 can create a F<Makefile> which does nothing, but succeeds on all the
2030 "usual" build targets. To do so, use
2032 ExtUtils::MakeMaker::WriteEmptyMakefile();
2034 instead of WriteMakefile().
2036 This may be useful if other modules expect this module to be I<built>
2037 OK, as opposed to I<work> OK (say, this system-dependent module builds
2038 in a subdirectory of some other distribution, or is listed as a
2039 dependency in a CPAN::Bundle, but the functionality is supported by
2040 different means on the current architecture).
2048 Command line options used by C<MakeMaker-E<gt>new()>, and thus by
2049 C<WriteMakefile()>. The string is split on whitespace, and the result
2050 is processed before any actual command line arguments are processed.
2056 ExtUtils::MM_Unix, ExtUtils::Manifest, ExtUtils::testlib,
2057 ExtUtils::Install, ExtUtils::Embed
2061 Andy Dougherty <F<doughera@lafcol.lafayette.edu>>, Andreas KE<ouml>nig
2062 <F<A.Koenig@franz.ww.TU-Berlin.DE>>, Tim Bunce <F<Tim.Bunce@ig.co.uk>>.
2063 VMS support by Charles Bailey <F<bailey@newman.upenn.edu>>. OS/2
2064 support by Ilya Zakharevich <F<ilya@math.ohio-state.edu>>. Contact the
2065 makemaker mailing list C<mailto:makemaker@franz.ww.tu-berlin.de>, if
2066 you have any questions.