3 package ExtUtils::MakeMaker;
6 $Version_OK = "5.49"; # Makefiles older than $Version_OK will die
7 # (Will be checked from MakeMaker version 4.13 onwards)
8 ($Revision = substr(q$Revision: 1.37 $, 10)) =~ s/\s+$//;
15 @ISA @EXPORT @EXPORT_OK
16 $ISA_TTY $Revision $VERSION $Verbose $Version_OK %Config
17 %Keep_after_flush %MM_Sections @Prepend_parent
18 %Recognized_Att_Keys @Get_from_Config @MM_Sections @Overridable
24 @EXPORT = qw(&WriteMakefile &writeMakefile $Verbose &prompt);
25 @EXPORT_OK = qw($VERSION &neatvalue &mkbootstrap &mksymlists);
27 # These will go away once the last of the Win32 & VMS specific code is
29 my $Is_VMS = $^O eq 'VMS';
30 my $Is_Win32 = $^O eq 'MSWin32';
34 require ExtUtils::MM; # Things like CPAN assume loading ExtUtils::MakeMaker
39 Carp::croak "WriteMakefile: Need even number of args" if @_ % 2;
43 my $mm = MM->new(\%att);
51 $ISA_TTY = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ; # Pipe?
52 Carp::confess("prompt function called without an argument")
54 my $dispdef = defined $def ? "[$def] " : " ";
55 $def = defined $def ? $def : "";
59 print "$mess $dispdef";
60 if ($ISA_TTY && !$ENV{PERL_MM_USE_DEFAULT}) {
65 else { # user hit ctrl-D
72 return (!defined $ans || $ans eq '') ? $def : $ans;
77 use Cwd qw(cwd abs_path);
79 local @INC = map eval {abs_path($_) if -e} || $_, @INC;
80 push @INC, '.'; # '.' has to always be at the end of @INC
82 foreach my $dir (@{$self->{DIR}}){
83 my($abs) = $self->catdir($pwd,$dir);
84 $self->eval_in_x($abs);
91 chdir $dir or Carp::carp("Couldn't change to directory $dir: $!");
98 # if ($@ =~ /prerequisites/) {
99 # die "MakeMaker WARNING: $@";
101 # warn "WARNING from evaluation of $dir/Makefile.PL: $@";
103 warn "WARNING from evaluation of $dir/Makefile.PL: $@";
110 # package name for the classes into which the first object will be blessed
111 $PACKNAME = "PACK000";
113 my @attrib_help = qw/
115 AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION
116 C CAPI CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DL_FUNCS DL_VARS
117 EXCLUDE_EXT EXE_FILES FIRST_MAKEFILE
118 FULLPERL FULLPERLRUN FULLPERLRUNINST
120 INST_ARCHLIB INST_SCRIPT INST_BIN INST_LIB
122 PREFIX SITEPREFIX VENDORPREFIX
123 INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
124 INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
125 INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN INSTALLSCRIPT
126 PERL_LIB PERL_ARCHLIB
127 SITELIBEXP SITEARCHEXP
128 INC INCLUDE_EXT LDFROM LIB LIBPERL_A LIBS
129 LINKTYPE MAKEAPERL MAKEFILE MAN1PODS MAN3PODS MAP_TARGET MYEXTLIB
131 NAME NEEDS_LINKING NOECHO NORECURS NO_VC OBJECT OPTIMIZE PERL PERLMAINCC
132 PERLRUN PERLRUNINST PERL_CORE
133 PERL_SRC PERM_RW PERM_RWX
134 PL_FILES PM PM_FILTER PMLIBDIRS POLLUTE PPM_INSTALL_EXEC
135 PPM_INSTALL_SCRIPT PREREQ_FATAL PREREQ_PM PREREQ_PRINT PRINT_PREREQ
136 SKIP TYPEMAPS VERSION VERSION_FROM XS XSOPT XSPROTOARG
137 XS_VERSION clean depend dist dynamic_lib linkext macro realclean
139 MACPERL_SRC MACPERL_LIB MACLIBS_68K MACLIBS_PPC MACLIBS_SC MACLIBS_MRC
140 MACLIBS_ALL_68K MACLIBS_ALL_PPC MACLIBS_SHARED
143 # IMPORTS is used under OS/2 and Win32
145 # @Overridable is close to @MM_Sections but not identical. The
146 # order is important. Many subroutines declare macros. These
147 # depend on each other. Let's try to collect the macros up front,
148 # then pasthru, then the rules.
150 # MM_Sections are the sections we have to call explicitly
151 # in Overridable we have subroutines that are used indirectly
157 post_initialize const_config constants tool_autosplit tool_xsubpp
158 tools_other dist macro depend cflags const_loadlibs const_cccmd
163 c_o xs_c xs_o top_targets linkext dlsyms dynamic dynamic_bs
164 dynamic_lib static static_lib manifypods processPL
166 clean realclean dist_basics dist_core dist_dir dist_test dist_ci
167 install force perldepend makefile staticmake test ppd
169 ); # loses section ordering
171 @Overridable = @MM_Sections;
172 push @Overridable, qw[
174 dir_target libscan makeaperl needs_linking perm_rw perm_rwx
175 subdir_x test_via_harness test_via_script init_PERL
178 push @MM_Sections, qw[
180 pm_to_blib selfdocument
184 # Postamble needs to be the last that was always the case
185 push @MM_Sections, "postamble";
186 push @Overridable, "postamble";
188 # All sections are valid keys.
189 @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
191 # we will use all these variables in the Makefile
194 ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
195 lib_ext obj_ext osname osvers ranlib sitelibexp sitearchexp so
199 foreach my $item (@attrib_help){
200 $Recognized_Att_Keys{$item} = 1;
202 foreach my $item (@Get_from_Config) {
203 $Recognized_Att_Keys{uc $item} = $Config{$item};
204 print "Attribute '\U$item\E' => '$Config{$item}'\n"
209 # When we eval a Makefile.PL in a subdirectory, that one will ask
210 # us (the parent) for the values and will prepend "..", so that
211 # all files to be installed end up below OUR ./blib
213 @Prepend_parent = qw(
214 INST_BIN INST_LIB INST_ARCHLIB INST_SCRIPT
215 MAP_TARGET INST_MAN1DIR INST_MAN3DIR PERL_SRC
220 NEEDS_LINKING HAS_LINK_CODE
222 @Keep_after_flush{@keep} = (1) x @keep;
228 The extension you are trying to build apparently is rather old and
229 most probably outdated. We detect that from the fact, that a
230 subroutine "writeMakefile" is called, and this subroutine is not
231 supported anymore since about October 1994.
233 Please contact the author or look into CPAN (details about CPAN can be
234 found in the FAQ and at http:/www.perl.com) for a more recent version
235 of the extension. If you're really desperate, you can try to change
236 the subroutine name from writeMakefile to WriteMakefile and rerun
237 'perl Makefile.PL', but you're most probably left alone, when you do
246 my($class,$self) = @_;
249 if ("@ARGV" =~ /\bPREREQ_PRINT\b/) {
250 require Data::Dumper;
251 print Data::Dumper->Dump([$self->{PREREQ_PM}], [qw(PREREQ_PM)]);
254 # PRINT_PREREQ is RedHatism.
255 if ("@ARGV" =~ /\bPRINT_PREREQ\b/) {
256 print join(" ", map { "perl($_)>=$self->{PREREQ_PM}->{$_} " } sort keys %{$self->{PREREQ_PM}}), "\n";
260 print STDOUT "MakeMaker (v$VERSION)\n" if $Verbose;
261 if (-f "MANIFEST" && ! -f "Makefile"){
265 $self = {} unless (defined $self);
269 my %configure_att; # record &{$self->{CONFIGURE}} attributes
270 my(%initial_att) = %$self; # record initial attributes
272 my(%unsatisfied) = ();
273 foreach my $prereq (sort keys %{$self->{PREREQ_PM}}) {
274 eval "require $prereq";
276 my $pr_version = $prereq->VERSION || 0;
279 warn sprintf "Warning: prerequisite %s %s not found.\n",
280 $prereq, $self->{PREREQ_PM}{$prereq}
281 unless $self->{PREREQ_FATAL};
282 $unsatisfied{$prereq} = 'not installed';
283 } elsif ($pr_version < $self->{PREREQ_PM}->{$prereq} ){
284 warn "Warning: prerequisite %s %s not found. We have %s.\n",
285 $prereq, $self->{PREREQ_PM}{$prereq},
286 ($pr_version || 'unknown version')
287 unless $self->{PREREQ_FATAL};
288 $unsatisfied{$prereq} = $self->{PREREQ_PM}->{$prereq} ?
289 $self->{PREREQ_PM}->{$prereq} : 'unknown version' ;
292 if (%unsatisfied && $self->{PREREQ_FATAL}){
293 my $failedprereqs = join ', ', map {"$_ $unsatisfied{$_}"}
295 die qq{MakeMaker FATAL: prerequisites not found ($failedprereqs)\n
296 Please install these modules first and rerun 'perl Makefile.PL'.\n};
299 if (defined $self->{CONFIGURE}) {
300 if (ref $self->{CONFIGURE} eq 'CODE') {
301 %configure_att = %{&{$self->{CONFIGURE}}};
302 $self = { %$self, %configure_att };
304 Carp::croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
308 # This is for old Makefiles written pre 5.00, will go away
309 if ( Carp::longmess("") =~ /runsubdirpl/s ){
310 Carp::carp("WARNING: Please rerun 'perl Makefile.PL' to regenerate your Makefiles\n");
313 my $newclass = ++$PACKNAME;
314 local @Parent = @Parent; # Protect against non-local exits
317 print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
318 mv_all_methods("MY",$newclass);
319 bless $self, $newclass;
321 require ExtUtils::MY;
322 @{"$newclass\:\:ISA"} = 'MM';
325 if (defined $Parent[-2]){
326 $self->{PARENT} = $Parent[-2];
328 for $key (@Prepend_parent) {
329 next unless defined $self->{PARENT}{$key};
330 $self->{$key} = $self->{PARENT}{$key};
331 unless ($^O eq 'VMS' && $key =~ /PERL$/) {
332 $self->{$key} = $self->catdir("..",$self->{$key})
333 unless $self->file_name_is_absolute($self->{$key});
335 # PERL or FULLPERL will be a command verb or even a
336 # command with an argument instead of a full file
337 # specification under VMS. So, don't turn the command
338 # into a filespec, but do add a level to the path of
339 # the argument if not already absolute.
340 my @cmd = split /\s+/, $self->{$key};
341 $cmd[1] = $self->catfile('[-]',$cmd[1])
342 unless (@cmd < 2) || $self->file_name_is_absolute($cmd[1]);
343 $self->{$key} = join(' ', @cmd);
346 if ($self->{PARENT}) {
347 $self->{PARENT}->{CHILDREN}->{$newclass} = $self;
348 foreach my $opt (qw(POLLUTE PERL_CORE)) {
349 if (exists $self->{PARENT}->{$opt}
350 and not exists $self->{$opt})
352 # inherit, but only if already unspecified
353 $self->{$opt} = $self->{PARENT}->{$opt};
357 my @fm = grep /^FIRST_MAKEFILE=/, @ARGV;
358 parse_args($self,@fm) if @fm;
360 parse_args($self,split(' ', $ENV{PERL_MM_OPT} || ''),@ARGV);
363 $self->{NAME} ||= $self->guess_name;
365 ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
369 if (! $self->{PERL_SRC} ) {
370 require VMS::Filespec if $Is_VMS;
371 my($pthinks) = $self->canonpath($INC{'Config.pm'});
372 my($cthinks) = $self->catfile($Config{'archlibexp'},'Config.pm');
373 $pthinks = VMS::Filespec::vmsify($pthinks) if $Is_VMS;
374 if ($pthinks ne $cthinks &&
375 !($Is_Win32 and lc($pthinks) eq lc($cthinks))) {
376 print "Have $pthinks expected $cthinks\n";
378 $pthinks =~ s![/\\]Config\.pm$!!i; $pthinks =~ s!.*[/\\]!!;
381 $pthinks =~ s!/Config\.pm$!!; $pthinks =~ s!.*/!!;
383 print STDOUT <<END unless $self->{UNINSTALLED_PERL};
384 Your perl and your Config.pm seem to have different ideas about the
385 architecture they are running on.
386 Perl thinks: [$pthinks]
387 Config says: [$Config{archname}]
388 This may or may not cause problems. Please check your installation of perl
389 if you have problems building this extension.
394 $self->init_dirscan();
395 $self->init_others();
397 my($argv) = neatvalue(\@ARGV);
401 push @{$self->{RESULT}}, <<END;
402 # This Makefile is for the $self->{NAME} extension to perl.
404 # It was generated automatically by MakeMaker version
405 # $VERSION (Revision: $Revision) from the contents of
406 # Makefile.PL. Don't edit this file, edit Makefile.PL instead.
408 # ANY CHANGES MADE HERE WILL BE LOST!
410 # MakeMaker ARGV: $argv
412 # MakeMaker Parameters:
415 foreach my $key (sort keys %initial_att){
416 my($v) = neatvalue($initial_att{$key});
417 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
419 push @{$self->{RESULT}}, "# $key => $v";
421 undef %initial_att; # free memory
423 if (defined $self->{CONFIGURE}) {
424 push @{$self->{RESULT}}, <<END;
426 # MakeMaker 'CONFIGURE' Parameters:
428 if (scalar(keys %configure_att) > 0) {
429 foreach my $key (sort keys %configure_att){
430 my($v) = neatvalue($configure_att{$key});
431 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
433 push @{$self->{RESULT}}, "# $key => $v";
438 push @{$self->{RESULT}}, "# no values returned";
440 undef %configure_att; # free memory
443 # turn the SKIP array into a SKIPHASH hash
445 for $skip (@{$self->{SKIP} || []}) {
446 $self->{SKIPHASH}{$skip} = 1;
448 delete $self->{SKIP}; # free memory
450 if ($self->{PARENT}) {
451 for (qw/install dist dist_basics dist_core dist_dir dist_test dist_ci/) {
452 $self->{SKIPHASH}{$_} = 1;
456 # We run all the subdirectories now. They don't have much to query
457 # from the parent, but the parent has to query them: if they need linking!
458 unless ($self->{NORECURS}) {
459 $self->eval_in_subdirs if @{$self->{DIR}};
462 foreach my $section ( @MM_Sections ){
463 print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
464 my($skipit) = $self->skipcheck($section);
466 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
468 my(%a) = %{$self->{$section} || {}};
469 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
470 push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
471 push @{$self->{RESULT}}, $self->nicetext($self->$section( %a ));
475 push @{$self->{RESULT}}, "\n# End.";
480 sub WriteEmptyMakefile {
481 Carp::croak "WriteEmptyMakefile: Need even number of args" if @_ % 2;
484 my $self = MM->new(\%att);
485 if (-f "$self->{MAKEFILE}.old") {
486 chmod 0666, "$self->{MAKEFILE}.old";
487 unlink "$self->{MAKEFILE}.old" or warn "unlink $self->{MAKEFILE}.old: $!";
489 rename $self->{MAKEFILE}, "$self->{MAKEFILE}.old"
490 or warn "rename $self->{MAKEFILE} $self->{MAKEFILE}.old: $!"
491 if -f $self->{MAKEFILE};
492 open MF, '>', $self->{MAKEFILE} or die "open $self->{MAKEFILE} for write: $!";
505 close MF or die "close $self->{MAKEFILE} for write: $!";
509 print STDOUT "Checking if your kit is complete...\n";
510 require ExtUtils::Manifest;
512 $ExtUtils::Manifest::Quiet = $ExtUtils::Manifest::Quiet = 1;
513 my(@missed) = ExtUtils::Manifest::manicheck();
515 print STDOUT "Warning: the following files are missing in your kit:\n";
516 print "\t", join "\n\t", @missed;
518 print STDOUT "Please inform the author.\n";
520 print STDOUT "Looks good\n";
525 my($self, @args) = @_;
527 unless (m/(.*?)=(.*)/) {
528 help(),exit 1 if m/^help$/;
529 ++$Verbose if m/^verb/;
532 my($name, $value) = ($1, $2);
533 if ($value =~ m/^~(\w+)?/) { # tilde with optional username
534 $value =~ s [^~(\w*)]
536 ((getpwnam($1))[7] || "~$1") :
540 $self->{uc($name)} = $value;
543 # catch old-style 'potential_libs' and inform user how to 'upgrade'
544 if (defined $self->{potential_libs}){
545 my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
546 if ($self->{potential_libs}){
547 print STDOUT "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
549 print STDOUT "$msg deleted.\n";
551 $self->{LIBS} = [$self->{potential_libs}];
552 delete $self->{potential_libs};
554 # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
555 if (defined $self->{ARMAYBE}){
556 my($armaybe) = $self->{ARMAYBE};
557 print STDOUT "ARMAYBE => '$armaybe' should be changed to:\n",
558 "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
559 my(%dl) = %{$self->{dynamic_lib} || {}};
560 $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
561 delete $self->{ARMAYBE};
563 if (defined $self->{LDTARGET}){
564 print STDOUT "LDTARGET should be changed to LDFROM\n";
565 $self->{LDFROM} = $self->{LDTARGET};
566 delete $self->{LDTARGET};
568 # Turn a DIR argument on the command line into an array
569 if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
570 # So they can choose from the command line, which extensions they want
571 # the grep enables them to have some colons too much in case they
572 # have to build a list with the shell
573 $self->{DIR} = [grep $_, split ":", $self->{DIR}];
575 # Turn a INCLUDE_EXT argument on the command line into an array
576 if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
577 $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
579 # Turn a EXCLUDE_EXT argument on the command line into an array
580 if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
581 $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
584 foreach my $mmkey (sort keys %$self){
585 print STDOUT " $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
586 print STDOUT "'$mmkey' is not a known MakeMaker parameter name.\n"
587 unless exists $Recognized_Att_Keys{$mmkey};
594 # We allow extension-specific hints files.
596 return unless -d "hints";
598 # First we look for the best hintsfile we have
599 my($hint)="${^O}_$Config{osvers}";
604 # Also try without trailing minor version numbers.
606 last if -f "hints/$hint.pl"; # found
608 last unless $hint =~ s/_[^_]*$//; # nothing to cut off
610 my $hint_file = "hints/$hint.pl";
612 return unless -f $hint_file; # really there
614 _run_hintfile($self, $hint_file);
619 local($self) = shift; # make $self available to the hint file.
620 my($hint_file) = shift;
623 print STDERR "Processing hints file $hint_file\n";
624 my $ret = do "./$hint_file";
625 unless( defined $ret ) {
626 print STDERR $@ if $@;
633 my($symtab) = \%{"${from}::"};
635 # Here you see the *current* list of methods that are overridable
636 # from Makefile.PL via MY:: subroutines. As of VERSION 5.07 I'm
637 # still trying to reduce the list to some reasonable minimum --
638 # because I want to make it easier for the user. A.K.
640 no warnings 'redefine';
641 foreach my $method (@Overridable) {
643 # We cannot say "next" here. Nick might call MY->makeaperl
644 # which isn't defined right now
646 # Above statement was written at 4.23 time when Tk-b8 was
647 # around. As Tk-b9 only builds with 5.002something and MM 5 is
648 # standard, we try to enable the next line again. It was
649 # commented out until MM 5.23
651 next unless defined &{"${from}::$method"};
653 *{"${to}::$method"} = \&{"${from}::$method"};
655 # delete would do, if we were sure, nobody ever called
656 # MY->makeaperl directly
658 # delete $symtab->{$method};
660 # If we delete a method, then it will be undefined and cannot
661 # be called. But as long as we have Makefile.PLs that rely on
662 # %MY:: being intact, we have to fill the hole with an
665 eval "package MY; sub $method { shift->SUPER::$method(\@_); }";
668 # We have to clean out %INC also, because the current directory is
669 # changed frequently and Graham Barr prefers to get his version
670 # out of a History.pl file which is "required" so woudn't get
671 # loaded again in another extension requiring a History.pl
673 # With perl5.002_01 the deletion of entries in %INC caused Tk-b11
674 # to core dump in the middle of a require statement. The required
675 # file was Tk/MMutil.pm. The consequence is, we have to be
676 # extremely careful when we try to give perl a reason to reload a
677 # library with same name. The workaround prefers to drop nothing
678 # from %INC and teach the writers not to use such libraries.
681 # foreach $inc (keys %INC) {
682 # #warn "***$inc*** deleted";
690 if ($section eq 'dynamic') {
691 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
692 "in skipped section 'dynamic_bs'\n"
693 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
694 print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
695 "in skipped section 'dynamic_lib'\n"
696 if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
698 if ($section eq 'dynamic_lib') {
699 print STDOUT "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
700 "targets in skipped section 'dynamic_bs'\n"
701 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
703 if ($section eq 'static') {
704 print STDOUT "Warning (non-fatal): Target 'static' depends on targets ",
705 "in skipped section 'static_lib'\n"
706 if $self->{SKIPHASH}{static_lib} && $Verbose;
708 return 'skipped' if $self->{SKIPHASH}{$section};
716 # my $fh = new FileHandle;
718 print STDOUT "Writing $self->{MAKEFILE} for $self->{NAME}\n";
720 unlink($self->{MAKEFILE}, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : '');
721 # $fh->open(">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
722 open(FH,">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
724 for $chunk (@{$self->{RESULT}}) {
725 # print $fh "$chunk\n";
731 my($finalname) = $self->{MAKEFILE};
732 rename("MakeMaker.tmp", $finalname);
733 chmod 0644, $finalname unless $Is_VMS;
735 if ($self->{PARENT} && !$self->{_KEEP_AFTER_FLUSH}) {
736 foreach (keys %$self) { # safe memory
737 delete $self->{$_} unless $Keep_after_flush{$_};
741 system("$Config::Config{eunicefix} $finalname") unless $Config::Config{eunicefix} eq ":";
744 # The following mkbootstrap() is only for installations that are calling
745 # the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
746 # writes Makefiles, that use ExtUtils::Mkbootstrap directly.
749 !!! Your Makefile has been built such a long time ago, !!!
750 !!! that is unlikely to work with current MakeMaker. !!!
751 !!! Please rebuild your Makefile !!!
755 # Ditto for mksymlists() as of MakeMaker 5.17
758 !!! Your Makefile has been built such a long time ago, !!!
759 !!! that is unlikely to work with current MakeMaker. !!!
760 !!! Please rebuild your Makefile !!!
766 return "undef" unless defined $v;
768 return "q[$v]" unless $t;
772 foreach my $elem (@$v) {
773 push @neat, "q[$elem]";
775 push @m, join ", ", @neat;
779 return "$v" unless $t eq 'HASH';
781 while (($key,$val) = each %$v){
782 last unless defined $key; # cautious programming in case (undef,undef) is true
783 push(@m,"$key=>".neatvalue($val)) ;
785 return "{ ".join(', ',@m)." }";
792 push @m, "\n# Full list of MakeMaker attribute values:";
793 foreach my $key (sort keys %$self){
794 next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
795 my($v) = neatvalue($self->{$key});
796 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
798 push @m, "# $key => $v";
810 ExtUtils::MakeMaker - create an extension Makefile
814 use ExtUtils::MakeMaker;
816 WriteMakefile( ATTRIBUTE => VALUE [, ...] );
820 This utility is designed to write a Makefile for an extension module
821 from a Makefile.PL. It is based on the Makefile.SH model provided by
822 Andy Dougherty and the perl5-porters.
824 It splits the task of generating the Makefile into several subroutines
825 that can be individually overridden. Each subroutine returns the text
826 it wishes to have written to the Makefile.
828 MakeMaker is object oriented. Each directory below the current
829 directory that contains a Makefile.PL is treated as a separate
830 object. This makes it possible to write an unlimited number of
831 Makefiles with a single invocation of WriteMakefile().
833 =head2 How To Write A Makefile.PL
835 The short answer is: Don't.
837 Always begin with h2xs.
838 Always begin with h2xs!
839 ALWAYS BEGIN WITH H2XS!
841 even if you're not building around a header file, and even if you
842 don't have an XS component.
844 Run h2xs(1) before you start thinking about writing a module. For so
845 called pm-only modules that consist of C<*.pm> files only, h2xs has
846 the C<-X> switch. This will generate dummy files of all kinds that are
847 useful for the module developer.
849 The medium answer is:
851 use ExtUtils::MakeMaker;
852 WriteMakefile( NAME => "Foo::Bar" );
854 The long answer is the rest of the manpage :-)
856 =head2 Default Makefile Behaviour
858 The generated Makefile enables the user of the extension to invoke
860 perl Makefile.PL # optionally "perl Makefile.PL verbose"
862 make test # optionally set TEST_VERBOSE=1
863 make install # See below
865 The Makefile to be produced may be altered by adding arguments of the
866 form C<KEY=VALUE>. E.g.
868 perl Makefile.PL PREFIX=/tmp/myperl5
870 Other interesting targets in the generated Makefile are
872 make config # to check if the Makefile is up-to-date
873 make clean # delete local temp files (Makefile gets renamed)
874 make realclean # delete derived files (including ./blib)
875 make ci # check in all the files in the MANIFEST file
876 make dist # see below the Distribution Support section
880 MakeMaker checks for the existence of a file named F<test.pl> in the
881 current directory and if it exists it adds commands to the test target
882 of the generated Makefile that will execute the script with the proper
883 set of perl C<-I> options.
885 MakeMaker also checks for any files matching glob("t/*.t"). It will
886 add commands to the test target of the generated Makefile that execute
887 all matching files via the L<Test::Harness> module with the C<-I>
888 switches set correctly.
892 A useful variation of the above is the target C<testdb>. It runs the
893 test under the Perl debugger (see L<perldebug>). If the file
894 F<test.pl> exists in the current directory, it is used for the test.
896 If you want to debug some other testfile, set C<TEST_FILE> variable
899 make testdb TEST_FILE=t/mytest.t
901 By default the debugger is called using C<-d> option to perl. If you
902 want to specify some other option, set C<TESTDB_SW> variable:
904 make testdb TESTDB_SW=-Dx
908 make alone puts all relevant files into directories that are named by
909 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
910 INST_MAN3DIR. All these default to something below ./blib if you are
911 I<not> building below the perl source directory. If you I<are>
912 building below the perl source, INST_LIB and INST_ARCHLIB default to
913 ../../lib, and INST_SCRIPT is not defined.
915 The I<install> target of the generated Makefile copies the files found
916 below each of the INST_* directories to their INSTALL*
917 counterparts. Which counterparts are chosen depends on the setting of
918 INSTALLDIRS according to the following table:
923 PREFIX SITEPREFIX VENDORPREFIX
924 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
925 INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
926 INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
927 INST_SCRIPT INSTALLSCRIPT INSTALLSCRIPT INSTALLSCRIPT
928 INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
929 INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
931 The INSTALL... macros in turn default to their %Config
932 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
934 You can check the values of these variables on your system with
938 And to check the sequence in which the library directories are
939 searched by perl, run
941 perl -le 'print join $/, @INC'
944 =head2 PREFIX and LIB attribute
946 PREFIX and LIB can be used to set several INSTALL* attributes in one
947 go. The quickest way to install a module in a non-standard place might
950 perl Makefile.PL PREFIX=~
952 This will install all files in the module under your home directory,
953 with man pages and libraries going into an appropriate place (usually
956 Another way to specify many INSTALL directories with a single
959 perl Makefile.PL LIB=~/lib
961 This will install the module's architecture-independent files into
962 ~/lib, the architecture-dependent files into ~/lib/$archname.
964 Note, that in both cases the tilde expansion is done by MakeMaker, not
965 by perl by default, nor by make.
967 Conflicts between parameters LIB, PREFIX and the various INSTALL*
968 arguments are resolved so that:
974 setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
975 INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
979 without LIB, setting PREFIX replaces the initial C<$Config{prefix}>
980 part of those INSTALL* arguments, even if the latter are explicitly
981 set (but are set to still start with C<$Config{prefix}>).
985 If the user has superuser privileges, and is not working on AFS or
986 relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
987 INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
995 make install per default writes some documentation of what has been
996 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
997 can be bypassed by calling make pure_install.
1001 will have to specify the installation directories as these most
1002 probably have changed since perl itself has been installed. They will
1003 have to do this by calling
1005 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
1006 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
1009 Be careful to repeat this procedure every time you recompile an
1010 extension, unless you are sure the AFS installation directories are
1013 =head2 Static Linking of a new Perl Binary
1015 An extension that is built with the above steps is ready to use on
1016 systems supporting dynamic loading. On systems that do not support
1017 dynamic loading, any newly created extension has to be linked together
1018 with the available resources. MakeMaker supports the linking process
1019 by creating appropriate targets in the Makefile whenever an extension
1020 is built. You can invoke the corresponding section of the makefile with
1024 That produces a new perl binary in the current directory with all
1025 extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP,
1026 and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1027 UNIX, this is called Makefile.aperl (may be system dependent). If you
1028 want to force the creation of a new perl, it is recommended, that you
1029 delete this Makefile.aperl, so the directories are searched-through
1030 for linkable libraries again.
1032 The binary can be installed into the directory where perl normally
1033 resides on your machine with
1037 To produce a perl binary with a different name than C<perl>, either say
1039 perl Makefile.PL MAP_TARGET=myperl
1046 make myperl MAP_TARGET=myperl
1047 make inst_perl MAP_TARGET=myperl
1049 In any case you will be prompted with the correct invocation of the
1050 C<inst_perl> target that installs the new binary into INSTALLBIN.
1052 make inst_perl per default writes some documentation of what has been
1053 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1054 can be bypassed by calling make pure_inst_perl.
1056 Warning: the inst_perl: target will most probably overwrite your
1057 existing perl binary. Use with care!
1059 Sometimes you might want to build a statically linked perl although
1060 your system supports dynamic loading. In this case you may explicitly
1061 set the linktype with the invocation of the Makefile.PL or make:
1063 perl Makefile.PL LINKTYPE=static # recommended
1067 make LINKTYPE=static # works on most systems
1069 =head2 Determination of Perl Library and Installation Locations
1071 MakeMaker needs to know, or to guess, where certain things are
1072 located. Especially INST_LIB and INST_ARCHLIB (where to put the files
1073 during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1074 existing modules from), and PERL_INC (header files and C<libperl*.*>).
1076 Extensions may be built either using the contents of the perl source
1077 directory tree or from the installed perl library. The recommended way
1078 is to build extensions after you have run 'make install' on perl
1079 itself. You can do that in any directory on your hard disk that is not
1080 below the perl source tree. The support for extensions below the ext
1081 directory of the perl distribution is only good for the standard
1082 extensions that come with perl.
1084 If an extension is being built below the C<ext/> directory of the perl
1085 source then MakeMaker will set PERL_SRC automatically (e.g.,
1086 C<../..>). If PERL_SRC is defined and the extension is recognized as
1087 a standard extension, then other variables default to the following:
1090 PERL_LIB = PERL_SRC/lib
1091 PERL_ARCHLIB = PERL_SRC/lib
1093 INST_ARCHLIB = PERL_ARCHLIB
1095 If an extension is being built away from the perl source then MakeMaker
1096 will leave PERL_SRC undefined and default to using the installed copy
1097 of the perl library. The other variables default to the following:
1099 PERL_INC = $archlibexp/CORE
1100 PERL_LIB = $privlibexp
1101 PERL_ARCHLIB = $archlibexp
1102 INST_LIB = ./blib/lib
1103 INST_ARCHLIB = ./blib/arch
1105 If perl has not yet been installed then PERL_SRC can be defined on the
1106 command line as shown in the previous section.
1109 =head2 Which architecture dependent directory?
1111 If you don't want to keep the defaults for the INSTALL* macros,
1112 MakeMaker helps you to minimize the typing needed: the usual
1113 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1114 by Configure at perl compilation time. MakeMaker supports the user who
1115 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1116 then MakeMaker defaults the latter to be the same subdirectory of
1117 INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
1118 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1119 for INSTALLSITELIB and INSTALLSITEARCH.
1121 MakeMaker gives you much more freedom than needed to configure
1122 internal variables and get different results. It is worth to mention,
1123 that make(1) also lets you configure most of the variables that are
1124 used in the Makefile. But in the majority of situations this will not
1125 be necessary, and should only be done if the author of a package
1126 recommends it (or you know what you're doing).
1128 =head2 Using Attributes and Parameters
1130 The following attributes can be specified as arguments to WriteMakefile()
1131 or as NAME=VALUE pairs on the command line:
1137 One line description of the module. Will be included in PPD file.
1141 Name of the file that contains the package description. MakeMaker looks
1142 for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1143 the first line in the "=head1 NAME" section. $2 becomes the abstract.
1147 String containing name (and email address) of package author(s). Is used
1148 in PPD (Perl Package Description) files for PPM (Perl Package Manager).
1150 =item BINARY_LOCATION
1152 Used when creating PPD files for binary packages. It can be set to a
1153 full or relative path or URL to the binary archive for a particular
1154 architecture. For example:
1156 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
1158 builds a PPD package that references a binary of the C<Agent> package,
1159 located in the C<x86> directory relative to the PPD itself.
1163 Ref to array of *.c file names. Initialised from a directory scan
1164 and the values portion of the XS attribute hash. This is not
1165 currently used by MakeMaker but may be handy in Makefile.PLs.
1169 String that will be included in the compiler call command line between
1170 the arguments INC and OPTIMIZE.
1174 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1175 config.sh. MakeMaker will add to CONFIG the following values anyway:
1195 CODE reference. The subroutine should return a hash reference. The
1196 hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
1197 be determined by some evaluation method.
1201 Something like C<"-DHAVE_UNISTD_H">
1205 Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
1210 Your name for distributing the package (by tar file). This defaults to
1215 Hashref of symbol names for routines to be made available as universal
1216 symbols. Each key/value pair consists of the package name and an
1217 array of routine names in that package. Used only under AIX, OS/2,
1218 VMS and Win32 at present. The routine names supplied will be expanded
1219 in the same way as XSUB names are expanded by the XS() macro.
1222 {"$(NAME)" => ["boot_$(NAME)" ] }
1226 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1227 "NetconfigPtr" => [ 'DESTROY'] }
1229 Please see the L<ExtUtils::Mksymlists> documentation for more information
1230 about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1234 Array of symbol names for variables to be made available as universal symbols.
1235 Used only under AIX, OS/2, VMS and Win32 at present. Defaults to [].
1236 (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
1240 Array of extension names to exclude when doing a static build. This
1241 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
1242 details. (e.g. [ qw( Socket POSIX ) ] )
1244 This attribute may be most useful when specified as a string on the
1245 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
1249 Ref to array of executable files. The files will be copied to the
1250 INST_SCRIPT directory. Make realclean will delete them from there
1253 =item FIRST_MAKEFILE
1255 The name of the Makefile to be produced. Defaults to the contents of
1256 MAKEFILE, but can be overridden. This is used for the second Makefile
1257 that will be produced for the MAP_TARGET.
1261 Perl binary able to run this extension, load XS modules, etc...
1265 Like PERLRUN, except it uses FULLPERL.
1267 =item FULLPERLRUNINST
1269 Like PERLRUNINST, except it uses FULLPERL.
1273 This provides an alternate means to specify function names to be
1274 exported from the extension. Its value is a reference to an
1275 array of function names to be exported by the extension. These
1276 names are passed through unaltered to the linker options file.
1280 Ref to array of *.h file names. Similar to C.
1284 This attribute is used to specify names to be imported into the
1285 extension. It is only used on OS/2 and Win32.
1289 Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
1293 Array of extension names to be included when doing a static build.
1294 MakeMaker will normally build with all of the installed extensions when
1295 doing a static build, and that is usually the desired behavior. If
1296 INCLUDE_EXT is present then MakeMaker will build only with those extensions
1297 which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])
1299 It is not necessary to mention DynaLoader or the current extension when
1300 filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then
1301 only DynaLoader and the current extension will be included in the build.
1303 This attribute may be most useful when specified as a string on the
1304 command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
1306 =item INSTALLARCHLIB
1308 Used by 'make install', which copies files from INST_ARCHLIB to this
1309 directory if INSTALLDIRS is set to perl.
1313 Directory to install binary files (e.g. tkperl) into if
1318 Determines which of the sets of installation directories to choose:
1319 perl, site or vendor. Defaults to site.
1321 =item INSTALLMAN1DIR
1323 =item INSTALLMAN3DIR
1325 These directories get the man pages at 'make install' time if
1326 INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
1328 If set to 'none', no man pages will be installed.
1330 =item INSTALLPRIVLIB
1332 Used by 'make install', which copies files from INST_LIB to this
1333 directory if INSTALLDIRS is set to perl.
1335 Defaults to $Config{installprivlib}.
1339 Used by 'make install' which copies files from INST_SCRIPT to this
1342 =item INSTALLSITEARCH
1344 Used by 'make install', which copies files from INST_ARCHLIB to this
1345 directory if INSTALLDIRS is set to site (default).
1347 =item INSTALLSITEBIN
1349 Used by 'make install', which copies files from INST_BIN to this
1350 directory if INSTALLDIRS is set to site (default).
1352 =item INSTALLSITELIB
1354 Used by 'make install', which copies files from INST_LIB to this
1355 directory if INSTALLDIRS is set to site (default).
1357 =item INSTALLSITEMAN1DIR
1359 =item INSTALLSITEMAN3DIR
1361 These directories get the man pages at 'make install' time if
1362 INSTALLDIRS=site (default). Defaults to
1363 $(SITEPREFIX)/man/man$(MAN*EXT).
1365 If set to 'none', no man pages will be installed.
1367 =item INSTALLVENDORARCH
1369 Used by 'make install', which copies files from INST_ARCHLIB to this
1370 directory if INSTALLDIRS is set to vendor.
1372 =item INSTALLVENDORBIN
1374 Used by 'make install', which copies files from INST_BIN to this
1375 directory if INSTALLDIRS is set to vendor.
1377 =item INSTALLVENDORLIB
1379 Used by 'make install', which copies files from INST_LIB to this
1380 directory if INSTALLDIRS is set to vendor.
1382 =item INSTALLVENDORMAN1DIR
1384 =item INSTALLVENDORMAN3DIR
1386 These directories get the man pages at 'make install' time if
1387 INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
1389 If set to 'none', no man pages will be installed.
1393 Same as INST_LIB for architecture dependent files.
1397 Directory to put real binary files during 'make'. These will be copied
1398 to INSTALLBIN during 'make install'
1402 Directory where we put library files of this extension while building
1407 Directory to hold the man pages at 'make' time
1411 Directory to hold the man pages at 'make' time
1415 Directory, where executable files should be installed during
1416 'make'. Defaults to "./blib/script", just to have a dummy location during
1417 testing. make install will copy the files in INST_SCRIPT to
1422 defaults to "$(OBJECT)" and is used in the ld command to specify
1423 what files to link/load from (also see dynamic_lib below for how to
1428 LIB should only be set at C<perl Makefile.PL> time but is allowed as a
1429 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
1430 and INSTALLSITELIB to that value regardless any explicit setting of
1431 those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
1432 are set to the corresponding architecture subdirectory.
1436 The filename of the perllibrary that will be used together with this
1437 extension. Defaults to libperl.a.
1441 An anonymous array of alternative library
1442 specifications to be searched for (in order) until
1443 at least one library is found. E.g.
1445 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
1447 Mind, that any element of the array
1448 contains a complete set of arguments for the ld
1449 command. So do not specify
1451 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
1453 See ODBM_File/Makefile.PL for an example, where an array is needed. If
1454 you specify a scalar as in
1456 'LIBS' => "-ltcl -ltk -lX11"
1458 MakeMaker will turn it into an array with one element.
1462 'static' or 'dynamic' (default unless usedl=undef in
1463 config.sh). Should only be used to force static linking (also see
1468 Boolean which tells MakeMaker, that it should include the rules to
1469 make a perl. This is handled automatically as a switch by
1470 MakeMaker. The user normally does not need it.
1474 The name of the Makefile to be produced.
1478 Hashref of pod-containing files. MakeMaker will default this to all
1479 EXE_FILES files that include POD directives. The files listed
1480 here will be converted to man pages and installed as was requested
1485 Hashref that assigns to *.pm and *.pod files the files into which the
1486 manpages are to be written. MakeMaker parses all *.pod and *.pm files
1487 for POD directives. Files that contain POD will be the default keys of
1488 the MAN3PODS hashref. These will then be converted to man pages during
1489 C<make> and will be installed during C<make install>.
1493 If it is intended, that a new perl binary be produced, this variable
1494 may hold a name for that binary. Defaults to perl
1498 If the extension links to a library that it builds set this to the
1499 name of the library (see SDBM_File)
1503 Perl module name for this extension (DBD::Oracle). This will default
1504 to the directory name but should be explicitly defined in the
1509 MakeMaker will figure out if an extension contains linkable code
1510 anywhere down the directory tree, and will set this variable
1511 accordingly, but you can speed it up a very little bit if you define
1512 this boolean variable yourself.
1516 Defaults to C<@>. By setting it to an empty string you can generate a
1517 Makefile that echos all commands. Mainly used in debugging MakeMaker
1522 Boolean. Attribute to inhibit descending into subdirectories.
1526 In general, any generated Makefile checks for the current version of
1527 MakeMaker and the version the Makefile was built under. If NO_VC is
1528 set, the version check is neglected. Do not write this into your
1529 Makefile.PL, use it interactively instead.
1533 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
1534 string containing all object files, e.g. "tkpBind.o
1535 tkpButton.o tkpCanvas.o"
1537 (Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)
1541 Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
1542 passed to subdirectory makes.
1546 Perl binary for tasks that can be done by miniperl
1550 Set only when MakeMaker is building the extensions of the Perl core
1555 The call to the program that is able to compile perlmain.c. Defaults
1560 Same as for PERL_LIB, but for architecture dependent files.
1562 Used only when MakeMaker is building the extensions of the Perl core
1563 distribution (because normally $(PERL_ARCHLIB) is automatically in @INC,
1564 and adding it would get in the way of PERL5LIB).
1568 Directory containing the Perl library to use.
1570 Used only when MakeMaker is building the extensions of the Perl core
1571 distribution (because normally $(PERL_LIB) is automatically in @INC,
1572 and adding it would get in the way of PERL5LIB).
1574 =item PERL_MALLOC_OK
1576 defaults to 0. Should be set to TRUE if the extension can work with
1577 the memory allocation routines substituted by the Perl malloc() subsystem.
1578 This should be applicable to most extensions with exceptions of those
1584 with bugs in memory allocations which are caught by Perl's malloc();
1588 which interact with the memory allocator in other ways than via
1589 malloc(), realloc(), free(), calloc(), sbrk() and brk();
1593 which rely on special alignment which is not provided by Perl's malloc().
1597 B<NOTE.> Negligence to set this flag in I<any one> of loaded extension
1598 nullifies many advantages of Perl's malloc(), such as better usage of
1599 system resources, error detection, memory usage reporting, catchable failure
1600 of memory allocations, etc.
1604 Use this instead of $(PERL) when you wish to run perl. It will set up
1605 extra necessary flags for you.
1609 Use this instead of $(PERL) when you wish to run perl to work with
1610 modules. It will add things like -I$(INST_ARCH) and other necessary
1611 flags so perl can see the modules you're about to install.
1615 Directory containing the Perl source code (use of this should be
1616 avoided, it may be undefined)
1620 Desired permission for read/writable files. Defaults to C<644>.
1621 See also L<MM_Unix/perm_rw>.
1625 Desired permission for executable files. Defaults to C<755>.
1626 See also L<MM_Unix/perm_rwx>.
1630 Ref to hash of files to be processed as perl programs. MakeMaker
1631 will default to any found *.PL file (except Makefile.PL) being keys
1632 and the basename of the file being the value. E.g.
1634 {'foobar.PL' => 'foobar'}
1636 The *.PL files are expected to produce output to the target files
1637 themselves. If multiple files can be generated from the same *.PL
1638 file then the value in the hash can be a reference to an array of
1639 target file names. E.g.
1641 {'foobar.PL' => ['foobar1','foobar2']}
1645 Hashref of .pm files and *.pl files to be installed. e.g.
1647 {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
1649 By default this will include *.pm and *.pl and the files found in
1650 the PMLIBDIRS directories. Defining PM in the
1651 Makefile.PL will override PMLIBDIRS.
1655 Ref to array of subdirectories containing library files. Defaults to
1656 [ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
1657 they contain will be installed in the corresponding location in the
1658 library. A libscan() method can be used to alter the behaviour.
1659 Defining PM in the Makefile.PL will override PMLIBDIRS.
1661 (Where BASEEXT is the last component of NAME.)
1665 A filter program, in the traditional Unix sense (input from stdin, output
1666 to stdout) that is passed on each .pm file during the build (in the
1667 pm_to_blib() phase). It is empty by default, meaning no filtering is done.
1669 Great care is necessary when defining the command if quoting needs to be
1670 done. For instance, you would need to say:
1672 {'PM_FILTER' => 'grep -v \\"^\\#\\"'}
1674 to remove all the leading coments on the fly during the build. The
1675 extra \\ are necessary, unfortunately, because this variable is interpolated
1676 within the context of a Perl program built on the command line, and double
1677 quotes are what is used with the -e switch to build that command line. The
1678 # is escaped for the Makefile, since what is going to be generated will then
1681 PM_FILTER = grep -v \"^\#\"
1683 Without the \\ before the #, we'd have the start of a Makefile comment,
1684 and the macro would be incorrectly defined.
1688 Release 5.005 grandfathered old global symbol names by providing preprocessor
1689 macros for extension source compatibility. As of release 5.6, these
1690 preprocessor definitions are not available by default. The POLLUTE flag
1691 specifies that the old names should still be defined:
1693 perl Makefile.PL POLLUTE=1
1695 Please inform the module author if this is necessary to successfully install
1696 a module under 5.6 or later.
1698 =item PPM_INSTALL_EXEC
1700 Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
1702 =item PPM_INSTALL_SCRIPT
1704 Name of the script that gets executed by the Perl Package Manager after
1705 the installation of a package.
1709 This overrides all the default install locations. Man pages,
1710 libraries, scripts, etc... MakeMaker will try to make an educated
1711 guess about where to place things under the new PREFIX based on your
1712 Config defaults. Failing that, it will fall back to a structure
1713 which should be sensible for your platform.
1715 If you specify LIB or any INSTALL* variables they will not be effected
1718 Defaults to $Config{installprefixexp}.
1722 Hashref: Names of modules that need to be available to run this
1723 extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
1724 desired version is the value. If the required version number is 0, we
1725 only check if any version is installed already.
1729 Bool. If this parameter is true, failing to have the required modules
1730 (or the right versions thereof) will be fatal. perl Makefile.PL will die
1731 with the proper message.
1733 Note: see L<Test::Harness> for a shortcut for stopping tests early if
1734 you are missing dependencies.
1736 Do I<not> use this parameter for simple requirements, which could be resolved
1737 at a later time, e.g. after an unsuccessful B<make test> of your module.
1739 It is I<extremely> rare to have to use C<PREREQ_FATAL> at all!
1743 Bool. If this parameter is true, the prerequisites will be printed to
1744 stdout and MakeMaker will exit. The output format is
1754 RedHatism for C<PREREQ_PRINT>. The output format is different, though:
1756 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1760 Like PREFIX, but only for the site install locations.
1762 Defaults to PREFIX (if set) or $Config{siteprefixexp}
1766 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1767 Makefile. Caution! Do not use the SKIP attribute for the negligible
1768 speedup. It may seriously damage the resulting Makefile. Only use it
1769 if you really need it.
1773 Ref to array of typemap file names. Use this when the typemaps are
1774 in some directory other than the current directory or when they are
1775 not named B<typemap>. The last typemap in the list takes
1776 precedence. A typemap in the current directory has highest
1777 precedence, even if it isn't listed in TYPEMAPS. The default system
1778 typemap has lowest precedence.
1782 Like PREFIX, but only for the vendor install locations.
1784 Defaults to PREFIX (if set) or $Config{vendorprefixexp}
1788 Your version number for distributing the package. This defaults to
1793 Instead of specifying the VERSION in the Makefile.PL you can let
1794 MakeMaker parse a file to determine the version number. The parsing
1795 routine requires that the file named by VERSION_FROM contains one
1796 single line to compute the version number. The first line in the file
1797 that contains the regular expression
1799 /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
1801 will be evaluated with eval() and the value of the named variable
1802 B<after> the eval() will be assigned to the VERSION attribute of the
1803 MakeMaker object. The following lines will be parsed o.k.:
1807 ( $VERSION ) = '$Revision: 1.37 $ ' =~ /\$Revision:\s+([^\s]+)/;
1808 $FOO::VERSION = '1.10';
1809 *FOO::VERSION = \'1.11';
1810 our $VERSION = 1.2.3; # new for perl5.6.0
1812 but these will fail:
1814 my $VERSION = '1.01';
1815 local $VERSION = '1.02';
1816 local $FOO::VERSION = '1.30';
1818 (Putting C<my> or C<local> on the preceding line will work o.k.)
1820 The file named in VERSION_FROM is not added as a dependency to
1821 Makefile. This is not really correct, but it would be a major pain
1822 during development to have to rewrite the Makefile for any smallish
1823 change in that file. If you want to make sure that the Makefile
1824 contains the correct VERSION macro after any change of the file, you
1825 would have to do something like
1827 depend => { Makefile => '$(VERSION_FROM)' }
1829 See attribute C<depend> below.
1833 Hashref of .xs files. MakeMaker will default this. e.g.
1835 {'name_of_file.xs' => 'name_of_file.c'}
1837 The .c files will automatically be included in the list of files
1838 deleted by a make clean.
1842 String of options to pass to xsubpp. This might include C<-C++> or
1843 C<-extern>. Do not include typemaps here; the TYPEMAP parameter exists for
1848 May be set to an empty string, which is identical to C<-prototypes>, or
1849 C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
1850 defaults to the empty string.
1854 Your version number for the .xs file of this package. This defaults
1855 to the value of the VERSION attribute.
1859 =head2 Additional lowercase attributes
1861 can be used to pass parameters to the methods which implement that
1862 part of the Makefile.
1868 {FILES => "*.xyz foo"}
1872 {ANY_TARGET => ANY_DEPENDECY, ...}
1874 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1878 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1879 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1880 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1882 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1883 needed to tell make the target file of the compression. Setting
1884 DIST_CP to ln can be useful, if you need to preserve the timestamps on
1885 your files. DIST_CP can take the values 'cp', which copies the file,
1886 'ln', which links the file, and 'best' which copies symbolic links and
1887 links the rest. Default is 'best'.
1891 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1895 {LINKTYPE => 'static', 'dynamic' or ''}
1897 NB: Extensions that have nothing but *.pm files had to say
1901 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1902 can be deleted safely. MakeMaker recognizes when there's nothing to
1907 {ANY_MACRO => ANY_VALUE, ...}
1911 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1917 =item tool_autosplit
1923 =head2 Overriding MakeMaker Methods
1925 If you cannot achieve the desired Makefile behaviour by specifying
1926 attributes you may define private subroutines in the Makefile.PL.
1927 Each subroutine returns the text it wishes to have written to
1928 the Makefile. To override a section of the Makefile you can
1931 sub MY::c_o { "new literal text" }
1933 or you can edit the default by saying something like:
1935 package MY; # so that "SUPER" works right
1937 my $inherited = shift->SUPER::c_o(@_);
1938 $inherited =~ s/old text/new text/;
1942 If you are running experiments with embedding perl as a library into
1943 other applications, you might find MakeMaker is not sufficient. You'd
1944 better have a look at ExtUtils::Embed which is a collection of utilities
1947 If you still need a different solution, try to develop another
1948 subroutine that fits your needs and submit the diffs to
1949 F<makemaker@perl.org>
1951 For a complete description of all MakeMaker methods see
1952 L<ExtUtils::MM_Unix>.
1954 Here is a simple example of how to add a new target to the generated
1958 return <<'MAKE_FRAG';
1959 $(MYEXTLIB): sdbm/Makefile
1960 cd sdbm && $(MAKE) all
1966 =head2 Hintsfile support
1968 MakeMaker.pm uses the architecture specific information from
1969 Config.pm. In addition it evaluates architecture specific hints files
1970 in a C<hints/> directory. The hints files are expected to be named
1971 like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
1972 name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
1973 MakeMaker within the WriteMakefile() subroutine, and can be used to
1974 execute commands as well as to include special variables. The rules
1975 which hintsfile is chosen are the same as in Configure.
1977 The hintsfile is eval()ed immediately after the arguments given to
1978 WriteMakefile are stuffed into a hash reference $self but before this
1979 reference becomes blessed. So if you want to do the equivalent to
1980 override or create an attribute you would say something like
1982 $self->{LIBS} = ['-ldbm -lucb -lc'];
1984 =head2 Distribution Support
1986 For authors of extensions MakeMaker provides several Makefile
1987 targets. Most of the support comes from the ExtUtils::Manifest module,
1988 where additional documentation can be found.
1992 =item make distcheck
1994 reports which files are below the build directory but not in the
1995 MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
1998 =item make skipcheck
2000 reports which files are skipped due to the entries in the
2001 C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
2004 =item make distclean
2006 does a realclean first and then the distcheck. Note that this is not
2007 needed to build a new distribution as long as you are sure that the
2008 MANIFEST file is ok.
2012 rewrites the MANIFEST file, adding all remaining files found (See
2013 ExtUtils::Manifest::mkmanifest() for details)
2017 Copies all the files that are in the MANIFEST file to a newly created
2018 directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
2019 exists, it will be removed first.
2023 Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
2024 a make test in that directory.
2028 First does a distdir. Then a command $(PREOP) which defaults to a null
2029 command, followed by $(TOUNIX), which defaults to a null command under
2030 UNIX, and will convert files in distribution directory to UNIX format
2031 otherwise. Next it runs C<tar> on that directory into a tarfile and
2032 deletes the directory. Finishes with a command $(POSTOP) which
2033 defaults to a null command.
2037 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
2039 =item make uutardist
2041 Runs a tardist first and uuencodes the tarfile.
2045 First does a distdir. Then a command $(PREOP) which defaults to a null
2046 command. Next it runs C<shar> on that directory into a sharfile and
2047 deletes the intermediate directory again. Finishes with a command
2048 $(POSTOP) which defaults to a null command. Note: For shdist to work
2049 properly a C<shar> program that can handle directories is mandatory.
2053 First does a distdir. Then a command $(PREOP) which defaults to a null
2054 command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
2055 zipfile. Then deletes that directory. Finishes with a command
2056 $(POSTOP) which defaults to a null command.
2060 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
2064 Customization of the dist targets can be done by specifying a hash
2065 reference to the dist attribute of the WriteMakefile call. The
2066 following parameters are recognized:
2069 COMPRESS ('gzip --best')
2072 TO_UNIX (depends on the system)
2073 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
2083 WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
2085 =head2 Disabling an extension
2087 If some events detected in F<Makefile.PL> imply that there is no way
2088 to create the Module, but this is a normal state of things, then you
2089 can create a F<Makefile> which does nothing, but succeeds on all the
2090 "usual" build targets. To do so, use
2092 ExtUtils::MakeMaker::WriteEmptyMakefile();
2094 instead of WriteMakefile().
2096 This may be useful if other modules expect this module to be I<built>
2097 OK, as opposed to I<work> OK (say, this system-dependent module builds
2098 in a subdirectory of some other distribution, or is listed as a
2099 dependency in a CPAN::Bundle, but the functionality is supported by
2100 different means on the current architecture).
2108 Command line options used by C<MakeMaker-E<gt>new()>, and thus by
2109 C<WriteMakefile()>. The string is split on whitespace, and the result
2110 is processed before any actual command line arguments are processed.
2112 =item PERL_MM_USE_DEFAULT
2114 If set to a true value then MakeMaker's prompt function will
2115 always return the default without waiting for user input.
2121 ExtUtils::MM_Unix, ExtUtils::Manifest ExtUtils::Install,
2126 Andy Dougherty <F<doughera@lafayette.edu>>, Andreas KE<ouml>nig
2127 <F<andreas.koenig@mind.de>>, Tim Bunce <F<timb@cpan.org>>. VMS
2128 support by Charles Bailey <F<bailey@newman.upenn.edu>>. OS/2 support
2129 by Ilya Zakharevich <F<ilya@math.ohio-state.edu>>.
2131 Currently maintained by Michael G Schwern <F<schwern@pobox.com>>
2133 Send patches and ideas to <F<makemaker@perl.org>>.
2135 Send bug reports via http://rt.cpan.org/. Please send your
2136 generated Makefile along with your report.
2138 For more up-to-date information, see http://www.makemaker.org.