lib/ExtUtils/MakeMaker.pm

   1 BEGIN {require 5.004;}
   2
   3 package ExtUtils::MakeMaker;
   4
   5 $VERSION = "5.54_01";
   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.23 $, 10)) =~ s/\s+$//;
   9
  10 require Exporter;
  11 use Config;
  12 use Carp ();
  13
  14 use vars qw(
  15             @ISA @EXPORT @EXPORT_OK
  16             $ISA_TTY $Revision $VERSION $Verbose $Version_OK %Config
  17             %Keep_after_flush %MM_Sections @Prepend_dot_dot
  18             %Recognized_Att_Keys @Get_from_Config @MM_Sections @Overridable
  19             @Parent $PACKNAME
  20            );
  21 use strict;
  22
  23 @ISA = qw(Exporter);
  24 @EXPORT = qw(&WriteMakefile &writeMakefile $Verbose &prompt);
  25 @EXPORT_OK = qw($VERSION &neatvalue &mkbootstrap &mksymlists);
  26
  27 # These will go away once the last of the Win32 & VMS specific code is
  28 # purged.
  29 my $Is_VMS     = $^O eq 'VMS';
  30 my $Is_Win32   = $^O eq 'MSWin32';
  31
  32 full_setup();
  33
  34 require ExtUtils::MM;  # Things like CPAN assume loading ExtUtils::MakeMaker
  35                        # will give them MM.
  36
  37 sub warnhandler {
  38     $_[0] =~ /^Use of uninitialized value/ && return;
  39     $_[0] =~ /used only once/ && return;
  40     $_[0] =~ /^Subroutine\s+[\w:]+\s+redefined/ && return;
  41     warn @_;
  42 }
  43
  44 sub WriteMakefile {
  45     Carp::croak "WriteMakefile: Need even number of args" if @_ % 2;
  46     local $SIG{__WARN__} = \&warnhandler;
  47
  48     require ExtUtils::MY;
  49     my %att = @_;
  50     MM->new(\%att)->flush;
  51 }
  52
  53 sub prompt ($;$) {
  54     my($mess,$def)=@_;
  55     $ISA_TTY = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ;   # Pipe?
  56     Carp::confess("prompt function called without an argument") unless defined $mess;
  57     my $dispdef = defined $def ? "[$def] " : " ";
  58     $def = defined $def ? $def : "";
  59     my $ans;
  60     local $|=1;
  61     local $\;
  62     print "$mess $dispdef";
  63     if ($ISA_TTY && !$ENV{PERL_MM_USE_DEFAULT}) {
  64         $ans = <STDIN>;
  65         if( defined $ans ) {
  66             chomp $ans;
  67         }
  68         else { # user hit ctrl-D
  69             print "\n";
  70         }
  71     }
  72     else {
  73         print "$def\n";
  74     }
  75     return (!defined $ans || $ans eq '') ? $def : $ans;
  76 }
  77
  78 sub eval_in_subdirs {
  79     my($self) = @_;
  80     use Cwd qw(cwd abs_path);
  81     my $pwd = cwd();
  82     local @INC = map eval {abs_path($_) if -e} || $_, @INC;
  83     push @INC, '.';     # '.' has to always be at the end of @INC
  84
  85     foreach my $dir (@{$self->{DIR}}){
  86         my($abs) = $self->catdir($pwd,$dir);
  87         $self->eval_in_x($abs);
  88     }
  89     chdir $pwd;
  90 }
  91
  92 sub eval_in_x {
  93     my($self,$dir) = @_;
  94     chdir $dir or Carp::carp("Couldn't change to directory $dir: $!");
  95
  96     {
  97         package main;
  98         do './Makefile.PL';
  99     };
 100     if ($@) {
 101 #         if ($@ =~ /prerequisites/) {
 102 #             die "MakeMaker WARNING: $@";
 103 #         } else {
 104 #             warn "WARNING from evaluation of $dir/Makefile.PL: $@";
 105 #         }
 106         warn "WARNING from evaluation of $dir/Makefile.PL: $@";
 107     }
 108 }
 109
 110 sub full_setup {
 111     $Verbose ||= 0;
 112
 113     # package name for the classes into which the first object will be blessed
 114     $PACKNAME = "PACK000";
 115
 116     my @attrib_help = qw/
 117
 118     AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION
 119     C CAPI CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DL_FUNCS DL_VARS
 120     EXCLUDE_EXT EXE_FILES FIRST_MAKEFILE
 121     FULLPERL FULLPERLRUN FULLPERLRUNINST
 122     FUNCLIST H IMPORTS
 123     INC INCLUDE_EXT INSTALLARCHLIB INSTALLBIN INSTALLDIRS
 124     INSTALLMAN1DIR
 125     INSTALLMAN3DIR INSTALLPRIVLIB INSTALLSCRIPT INSTALLSITEARCH
 126     INSTALLSITELIB INST_ARCHLIB INST_BIN INST_EXE INST_LIB
 127     INST_MAN1DIR INST_MAN3DIR INST_SCRIPT LDFROM LIB LIBPERL_A LIBS
 128     LINKTYPE MAKEAPERL MAKEFILE MAN1PODS MAN3PODS MAP_TARGET MYEXTLIB
 129     PERL_MALLOC_OK
 130     NAME NEEDS_LINKING NOECHO NORECURS NO_VC OBJECT OPTIMIZE PERL PERLMAINCC
 131     PERLRUN PERLRUNINST PERL_ARCHLIB PERL_CORE
 132     PERL_LIB PERL_SRC PERM_RW PERM_RWX
 133     PL_FILES PM PM_FILTER PMLIBDIRS POLLUTE PPM_INSTALL_EXEC
 134     PPM_INSTALL_SCRIPT PREFIX
 135     PREREQ_FATAL PREREQ_PM PREREQ_PRINT PRINT_PREREQ
 136     SKIP TEST_LIBS TYPEMAPS VERSION VERSION_FROM XS XSOPT XSPROTOARG
 137     XS_VERSION clean depend dist dynamic_lib linkext macro realclean
 138     tool_autosplit
 139     MACPERL_SRC MACPERL_LIB MACLIBS_68K MACLIBS_PPC MACLIBS_SC MACLIBS_MRC
 140     MACLIBS_ALL_68K MACLIBS_ALL_PPC MACLIBS_SHARED
 141         /;
 142
 143     # IMPORTS is used under OS/2 and Win32
 144
 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.
 149
 150     # MM_Sections are the sections we have to call explicitly
 151     # in Overridable we have subroutines that are used indirectly
 152
 153
 154     @MM_Sections =
 155         qw(
 156
 157  post_initialize const_config constants tool_autosplit tool_xsubpp
 158  tools_other dist macro depend cflags const_loadlibs const_cccmd
 159  post_constants
 160
 161  pasthru
 162
 163  c_o xs_c xs_o top_targets linkext dlsyms dynamic dynamic_bs
 164  dynamic_lib static static_lib manifypods processPL
 165  installbin subdirs
 166  clean realclean dist_basics dist_core dist_dir dist_test dist_ci
 167  install force perldepend makefile staticmake test ppd
 168
 169           ); # loses section ordering
 170
 171     @Overridable = @MM_Sections;
 172     push @Overridable, qw[
 173
 174  dir_target libscan makeaperl needs_linking perm_rw perm_rwx
 175  subdir_x test_via_harness test_via_script init_PERL
 176                          ];
 177
 178     push @MM_Sections, qw[
 179
 180  pm_to_blib selfdocument
 181
 182                          ];
 183
 184     # Postamble needs to be the last that was always the case
 185     push @MM_Sections, "postamble";
 186     push @Overridable, "postamble";
 187
 188     # All sections are valid keys.
 189     @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
 190
 191     # we will use all these variables in the Makefile
 192     @Get_from_Config =
 193         qw(
 194            ar cc cccdlflags ccdlflags dlext dlsrc ld lddlflags ldflags libc
 195            lib_ext obj_ext osname osvers ranlib sitelibexp sitearchexp so
 196            exe_ext full_ar
 197           );
 198
 199     foreach my $item (@attrib_help){
 200         $Recognized_Att_Keys{$item} = 1;
 201     }
 202     foreach my $item (@Get_from_Config) {
 203         $Recognized_Att_Keys{uc $item} = $Config{$item};
 204         print "Attribute '\U$item\E' => '$Config{$item}'\n"
 205             if ($Verbose >= 2);
 206     }
 207
 208     #
 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
 212     #
 213     @Prepend_dot_dot = qw(
 214            INST_BIN INST_EXE INST_LIB INST_ARCHLIB INST_SCRIPT
 215            MAP_TARGET INST_MAN1DIR INST_MAN3DIR PERL_SRC
 216            PERL FULLPERL
 217     );
 218
 219     my @keep = qw/
 220         NEEDS_LINKING HAS_LINK_CODE
 221         /;
 222     @Keep_after_flush{@keep} = (1) x @keep;
 223 }
 224
 225 sub writeMakefile {
 226     die <<END;
 227
 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.
 232
 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
 238 so.
 239
 240 The MakeMaker team
 241
 242 END
 243 }
 244
 245 sub new {
 246     my($class,$self) = @_;
 247     my($key);
 248
 249     if ("@ARGV" =~ /\bPREREQ_PRINT\b/) {
 250         require Data::Dumper;
 251         print Data::Dumper->Dump([$self->{PREREQ_PM}], [qw(PREREQ_PM)]);
 252     }
 253
 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";
 257         exit 0;
 258    }
 259
 260     print STDOUT "MakeMaker (v$VERSION)\n" if $Verbose;
 261     if (-f "MANIFEST" && ! -f "Makefile"){
 262         check_manifest();
 263     }
 264
 265     $self = {} unless (defined $self);
 266
 267     check_hints($self);
 268
 269     my %configure_att;         # record &{$self->{CONFIGURE}} attributes
 270     my(%initial_att) = %$self; # record initial attributes
 271
 272     my(%unsatisfied) = ();
 273     foreach my $prereq (sort keys %{$self->{PREREQ_PM}}) {
 274         eval "require $prereq";
 275
 276         if ($@) {
 277             warn sprintf "Warning: prerequisite %s %s not found.\n",
 278               $prereq, $self->{PREREQ_PM}{$prereq}
 279                    unless $self->{PREREQ_FATAL};
 280             $unsatisfied{$prereq} = 'not installed';
 281         } elsif ($prereq->VERSION < $self->{PREREQ_PM}->{$prereq} ){
 282             warn "Warning: prerequisite %s %s not found. We have %s.\n",
 283               $prereq, $self->{PREREQ_PM}{$prereq},
 284                 ($prereq->VERSION || 'unknown version')
 285                   unless $self->{PREREQ_FATAL};
 286             $unsatisfied{$prereq} = $self->{PREREQ_PM}->{$prereq} ?
 287               $self->{PREREQ_PM}->{$prereq} : 'unknown version' ;
 288         }
 289     }
 290     if (%unsatisfied && $self->{PREREQ_FATAL}){
 291         my $failedprereqs = join ', ', map {"$_ $unsatisfied{$_}"}
 292                             keys %unsatisfied;
 293         die qq{MakeMaker FATAL: prerequisites not found ($failedprereqs)\n
 294                Please install these modules first and rerun 'perl Makefile.PL'.\n};
 295     }
 296
 297     if (defined $self->{CONFIGURE}) {
 298         if (ref $self->{CONFIGURE} eq 'CODE') {
 299             %configure_att = %{&{$self->{CONFIGURE}}};
 300             $self = { %$self, %configure_att };
 301         } else {
 302             Carp::croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
 303         }
 304     }
 305
 306     # This is for old Makefiles written pre 5.00, will go away
 307     if ( Carp::longmess("") =~ /runsubdirpl/s ){
 308         Carp::carp("WARNING: Please rerun 'perl Makefile.PL' to regenerate your Makefiles\n");
 309     }
 310
 311     my $newclass = ++$PACKNAME;
 312     local @Parent = @Parent;    # Protect against non-local exits
 313     {
 314         no strict 'refs';
 315         print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
 316         mv_all_methods("MY",$newclass);
 317         bless $self, $newclass;
 318         push @Parent, $self;
 319         require ExtUtils::MY;
 320         @{"$newclass\:\:ISA"} = 'MM';
 321     }
 322
 323     if (defined $Parent[-2]){
 324         $self->{PARENT} = $Parent[-2];
 325         my $key;
 326         for $key (@Prepend_dot_dot) {
 327             next unless defined $self->{PARENT}{$key};
 328             $self->{$key} = $self->{PARENT}{$key};
 329             unless ($^O eq 'VMS' && $key =~ /PERL$/) {
 330                 $self->{$key} = $self->catdir("..",$self->{$key})
 331                   unless $self->file_name_is_absolute($self->{$key});
 332             } else {
 333                 # PERL or FULLPERL will be a command verb or even a
 334                 # command with an argument instead of a full file
 335                 # specification under VMS.  So, don't turn the command
 336                 # into a filespec, but do add a level to the path of
 337                 # the argument if not already absolute.
 338                 my @cmd = split /\s+/, $self->{$key};
 339                 $cmd[1] = $self->catfile('[-]',$cmd[1])
 340                   unless (@cmd < 2) || $self->file_name_is_absolute($cmd[1]);
 341                 $self->{$key} = join(' ', @cmd);
 342             }
 343         }
 344         if ($self->{PARENT}) {
 345             $self->{PARENT}->{CHILDREN}->{$newclass} = $self;
 346             foreach my $opt (qw(POLLUTE PERL_CORE)) {
 347                 if (exists $self->{PARENT}->{$opt}
 348                     and not exists $self->{$opt})
 349                     {
 350                         # inherit, but only if already unspecified
 351                         $self->{$opt} = $self->{PARENT}->{$opt};
 352                     }
 353             }
 354         }
 355         my @fm = grep /^FIRST_MAKEFILE=/, @ARGV;
 356         parse_args($self,@fm) if @fm;
 357     } else {
 358         parse_args($self,split(' ', $ENV{PERL_MM_OPT} || ''),@ARGV);
 359     }
 360
 361     $self->{NAME} ||= $self->guess_name;
 362
 363     ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
 364
 365     $self->init_main();
 366
 367     if (! $self->{PERL_SRC} ) {
 368         require VMS::Filespec if $Is_VMS;
 369         my($pthinks) = $self->canonpath($INC{'Config.pm'});
 370         my($cthinks) = $self->catfile($Config{'archlibexp'},'Config.pm');
 371         $pthinks = VMS::Filespec::vmsify($pthinks) if $Is_VMS;
 372         if ($pthinks ne $cthinks &&
 373             !($Is_Win32 and lc($pthinks) eq lc($cthinks))) {
 374             print "Have $pthinks expected $cthinks\n";
 375             if ($Is_Win32) {
 376                 $pthinks =~ s![/\\]Config\.pm$!!i; $pthinks =~ s!.*[/\\]!!;
 377             }
 378             else {
 379                 $pthinks =~ s!/Config\.pm$!!; $pthinks =~ s!.*/!!;
 380             }
 381             print STDOUT <<END unless $self->{UNINSTALLED_PERL};
 382 Your perl and your Config.pm seem to have different ideas about the
 383 architecture they are running on.
 384 Perl thinks: [$pthinks]
 385 Config says: [$Config{archname}]
 386 This may or may not cause problems. Please check your installation of perl
 387 if you have problems building this extension.
 388 END
 389         }
 390     }
 391
 392     $self->init_dirscan();
 393     $self->init_others();
 394     my($argv) = neatvalue(\@ARGV);
 395     $argv =~ s/^\[/(/;
 396     $argv =~ s/\]$/)/;
 397
 398     push @{$self->{RESULT}}, <<END;
 399 # This Makefile is for the $self->{NAME} extension to perl.
 400 #
 401 # It was generated automatically by MakeMaker version
 402 # $VERSION (Revision: $Revision) from the contents of
 403 # Makefile.PL. Don't edit this file, edit Makefile.PL instead.
 404 #
 405 #       ANY CHANGES MADE HERE WILL BE LOST!
 406 #
 407 #   MakeMaker ARGV: $argv
 408 #
 409 #   MakeMaker Parameters:
 410 END
 411
 412     foreach my $key (sort keys %initial_att){
 413         my($v) = neatvalue($initial_att{$key});
 414         $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
 415         $v =~ tr/\n/ /s;
 416         push @{$self->{RESULT}}, "#     $key => $v";
 417     }
 418     undef %initial_att;        # free memory
 419
 420     if (defined $self->{CONFIGURE}) {
 421        push @{$self->{RESULT}}, <<END;
 422
 423 #   MakeMaker 'CONFIGURE' Parameters:
 424 END
 425         if (scalar(keys %configure_att) > 0) {
 426             foreach my $key (sort keys %configure_att){
 427                my($v) = neatvalue($configure_att{$key});
 428                $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
 429                $v =~ tr/\n/ /s;
 430                push @{$self->{RESULT}}, "#     $key => $v";
 431             }
 432         }
 433         else
 434         {
 435            push @{$self->{RESULT}}, "# no values returned";
 436         }
 437         undef %configure_att;  # free memory
 438     }
 439
 440     # turn the SKIP array into a SKIPHASH hash
 441     my (%skip,$skip);
 442     for $skip (@{$self->{SKIP} || []}) {
 443         $self->{SKIPHASH}{$skip} = 1;
 444     }
 445     delete $self->{SKIP}; # free memory
 446
 447     if ($self->{PARENT}) {
 448         for (qw/install dist dist_basics dist_core dist_dir dist_test dist_ci/) {
 449             $self->{SKIPHASH}{$_} = 1;
 450         }
 451     }
 452
 453     # We run all the subdirectories now. They don't have much to query
 454     # from the parent, but the parent has to query them: if they need linking!
 455     unless ($self->{NORECURS}) {
 456         $self->eval_in_subdirs if @{$self->{DIR}};
 457     }
 458
 459     foreach my $section ( @MM_Sections ){
 460         print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
 461         my($skipit) = $self->skipcheck($section);
 462         if ($skipit){
 463             push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
 464         } else {
 465             my(%a) = %{$self->{$section} || {}};
 466             push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
 467             push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
 468             push @{$self->{RESULT}}, $self->nicetext($self->$section( %a ));
 469         }
 470     }
 471
 472     push @{$self->{RESULT}}, "\n# End.";
 473
 474     $self;
 475 }
 476
 477 sub WriteEmptyMakefile {
 478     Carp::croak "WriteEmptyMakefile: Need even number of args" if @_ % 2;
 479     local $SIG{__WARN__} = \&warnhandler;
 480
 481     my %att = @_;
 482     my $self = MM->new(\%att);
 483     if (-f "$self->{MAKEFILE}.old") {
 484       chmod 0666, "$self->{MAKEFILE}.old";
 485       unlink "$self->{MAKEFILE}.old" or warn "unlink $self->{MAKEFILE}.old: $!";
 486     }
 487     rename $self->{MAKEFILE}, "$self->{MAKEFILE}.old"
 488       or warn "rename $self->{MAKEFILE} $self->{MAKEFILE}.old: $!"
 489         if -f $self->{MAKEFILE};
 490     open MF, '>', $self->{MAKEFILE} or die "open $self->{MAKEFILE} for write: $!";
 491     print MF <<'EOP';
 492 all:
 493
 494 clean:
 495
 496 install:
 497
 498 makemakerdflt:
 499
 500 test:
 501
 502 EOP
 503     close MF or die "close $self->{MAKEFILE} for write: $!";
 504 }
 505
 506 sub check_manifest {
 507     print STDOUT "Checking if your kit is complete...\n";
 508     require ExtUtils::Manifest;
 509     # avoid warning
 510     $ExtUtils::Manifest::Quiet = $ExtUtils::Manifest::Quiet = 1;
 511     my(@missed) = ExtUtils::Manifest::manicheck();
 512     if (@missed) {
 513         print STDOUT "Warning: the following files are missing in your kit:\n";
 514         print "\t", join "\n\t", @missed;
 515         print STDOUT "\n";
 516         print STDOUT "Please inform the author.\n";
 517     } else {
 518         print STDOUT "Looks good\n";
 519     }
 520 }
 521
 522 sub parse_args{
 523     my($self, @args) = @_;
 524     foreach (@args) {
 525         unless (m/(.*?)=(.*)/) {
 526             help(),exit 1 if m/^help$/;
 527             ++$Verbose if m/^verb/;
 528             next;
 529         }
 530         my($name, $value) = ($1, $2);
 531         if ($value =~ m/^~(\w+)?/) { # tilde with optional username
 532             $value =~ s [^~(\w*)]
 533                 [$1 ?
 534                  ((getpwnam($1))[7] || "~$1") :
 535                  (getpwuid($>))[7]
 536                  ]ex;
 537         }
 538         $self->{uc($name)} = $value;
 539     }
 540
 541     # catch old-style 'potential_libs' and inform user how to 'upgrade'
 542     if (defined $self->{potential_libs}){
 543         my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
 544         if ($self->{potential_libs}){
 545             print STDOUT "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
 546         } else {
 547             print STDOUT "$msg deleted.\n";
 548         }
 549         $self->{LIBS} = [$self->{potential_libs}];
 550         delete $self->{potential_libs};
 551     }
 552     # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
 553     if (defined $self->{ARMAYBE}){
 554         my($armaybe) = $self->{ARMAYBE};
 555         print STDOUT "ARMAYBE => '$armaybe' should be changed to:\n",
 556                         "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
 557         my(%dl) = %{$self->{dynamic_lib} || {}};
 558         $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
 559         delete $self->{ARMAYBE};
 560     }
 561     if (defined $self->{LDTARGET}){
 562         print STDOUT "LDTARGET should be changed to LDFROM\n";
 563         $self->{LDFROM} = $self->{LDTARGET};
 564         delete $self->{LDTARGET};
 565     }
 566     # Turn a DIR argument on the command line into an array
 567     if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
 568         # So they can choose from the command line, which extensions they want
 569         # the grep enables them to have some colons too much in case they
 570         # have to build a list with the shell
 571         $self->{DIR} = [grep $_, split ":", $self->{DIR}];
 572     }
 573     # Turn a INCLUDE_EXT argument on the command line into an array
 574     if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
 575         $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
 576     }
 577     # Turn a EXCLUDE_EXT argument on the command line into an array
 578     if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
 579         $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
 580     }
 581
 582     foreach my $mmkey (sort keys %$self){
 583         print STDOUT "  $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
 584         print STDOUT "'$mmkey' is not a known MakeMaker parameter name.\n"
 585             unless exists $Recognized_Att_Keys{$mmkey};
 586     }
 587     $| = 1 if $Verbose;
 588 }
 589
 590 sub check_hints {
 591     my($self) = @_;
 592     # We allow extension-specific hints files.
 593
 594     return unless -d "hints";
 595
 596     # First we look for the best hintsfile we have
 597     my($hint)="${^O}_$Config{osvers}";
 598     $hint =~ s/\./_/g;
 599     $hint =~ s/_$//;
 600     return unless $hint;
 601
 602     # Also try without trailing minor version numbers.
 603     while (1) {
 604         last if -f "hints/$hint.pl";      # found
 605     } continue {
 606         last unless $hint =~ s/_[^_]*$//; # nothing to cut off
 607     }
 608     my $hint_file = "hints/$hint.pl";
 609
 610     return unless -f $hint_file;    # really there
 611
 612     _run_hintfile($self, $hint_file);
 613 }
 614
 615 sub _run_hintfile {
 616     our $self;
 617     local($self) = shift;       # make $self available to the hint file.
 618     my($hint_file) = shift;
 619
 620     local $@;
 621     print STDERR "Processing hints file $hint_file\n";
 622     my $ret = do "./$hint_file";
 623     unless( defined $ret ) {
 624         print STDERR $@ if $@;
 625     }
 626 }
 627
 628 sub mv_all_methods {
 629     my($from,$to) = @_;
 630     no strict 'refs';
 631     my($symtab) = \%{"${from}::"};
 632
 633     # Here you see the *current* list of methods that are overridable
 634     # from Makefile.PL via MY:: subroutines. As of VERSION 5.07 I'm
 635     # still trying to reduce the list to some reasonable minimum --
 636     # because I want to make it easier for the user. A.K.
 637
 638     foreach my $method (@Overridable) {
 639
 640         # We cannot say "next" here. Nick might call MY->makeaperl
 641         # which isn't defined right now
 642
 643         # Above statement was written at 4.23 time when Tk-b8 was
 644         # around. As Tk-b9 only builds with 5.002something and MM 5 is
 645         # standard, we try to enable the next line again. It was
 646         # commented out until MM 5.23
 647
 648         next unless defined &{"${from}::$method"};
 649
 650         *{"${to}::$method"} = \&{"${from}::$method"};
 651
 652         # delete would do, if we were sure, nobody ever called
 653         # MY->makeaperl directly
 654
 655         # delete $symtab->{$method};
 656
 657         # If we delete a method, then it will be undefined and cannot
 658         # be called.  But as long as we have Makefile.PLs that rely on
 659         # %MY:: being intact, we have to fill the hole with an
 660         # inheriting method:
 661
 662         eval "package MY; sub $method { shift->SUPER::$method(\@_); }";
 663     }
 664
 665     # We have to clean out %INC also, because the current directory is
 666     # changed frequently and Graham Barr prefers to get his version
 667     # out of a History.pl file which is "required" so woudn't get
 668     # loaded again in another extension requiring a History.pl
 669
 670     # With perl5.002_01 the deletion of entries in %INC caused Tk-b11
 671     # to core dump in the middle of a require statement. The required
 672     # file was Tk/MMutil.pm.  The consequence is, we have to be
 673     # extremely careful when we try to give perl a reason to reload a
 674     # library with same name.  The workaround prefers to drop nothing
 675     # from %INC and teach the writers not to use such libraries.
 676
 677 #    my $inc;
 678 #    foreach $inc (keys %INC) {
 679 #       #warn "***$inc*** deleted";
 680 #       delete $INC{$inc};
 681 #    }
 682 }
 683
 684 sub skipcheck {
 685     my($self) = shift;
 686     my($section) = @_;
 687     if ($section eq 'dynamic') {
 688         print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
 689         "in skipped section 'dynamic_bs'\n"
 690             if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
 691         print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
 692         "in skipped section 'dynamic_lib'\n"
 693             if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
 694     }
 695     if ($section eq 'dynamic_lib') {
 696         print STDOUT "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
 697         "targets in skipped section 'dynamic_bs'\n"
 698             if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
 699     }
 700     if ($section eq 'static') {
 701         print STDOUT "Warning (non-fatal): Target 'static' depends on targets ",
 702         "in skipped section 'static_lib'\n"
 703             if $self->{SKIPHASH}{static_lib} && $Verbose;
 704     }
 705     return 'skipped' if $self->{SKIPHASH}{$section};
 706     return '';
 707 }
 708
 709 sub flush {
 710     my $self = shift;
 711     my($chunk);
 712 #    use FileHandle ();
 713 #    my $fh = new FileHandle;
 714     local *FH;
 715     print STDOUT "Writing $self->{MAKEFILE} for $self->{NAME}\n";
 716
 717     unlink($self->{MAKEFILE}, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : '');
 718 #    $fh->open(">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
 719     open(FH,">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
 720
 721     for $chunk (@{$self->{RESULT}}) {
 722 #       print $fh "$chunk\n";
 723         print FH "$chunk\n";
 724     }
 725
 726 #    $fh->close;
 727     close FH;
 728     my($finalname) = $self->{MAKEFILE};
 729     rename("MakeMaker.tmp", $finalname);
 730     chmod 0644, $finalname unless $Is_VMS;
 731
 732     if ($self->{PARENT}) {
 733         foreach (keys %$self) { # safe memory
 734             delete $self->{$_} unless $Keep_after_flush{$_};
 735         }
 736     }
 737
 738     system("$Config::Config{eunicefix} $finalname") unless $Config::Config{eunicefix} eq ":";
 739 }
 740
 741 # The following mkbootstrap() is only for installations that are calling
 742 # the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
 743 # writes Makefiles, that use ExtUtils::Mkbootstrap directly.
 744 sub mkbootstrap {
 745     die <<END;
 746 !!! Your Makefile has been built such a long time ago, !!!
 747 !!! that is unlikely to work with current MakeMaker.   !!!
 748 !!! Please rebuild your Makefile                       !!!
 749 END
 750 }
 751
 752 # Ditto for mksymlists() as of MakeMaker 5.17
 753 sub mksymlists {
 754     die <<END;
 755 !!! Your Makefile has been built such a long time ago, !!!
 756 !!! that is unlikely to work with current MakeMaker.   !!!
 757 !!! Please rebuild your Makefile                       !!!
 758 END
 759 }
 760
 761 sub neatvalue {
 762     my($v) = @_;
 763     return "undef" unless defined $v;
 764     my($t) = ref $v;
 765     return "q[$v]" unless $t;
 766     if ($t eq 'ARRAY') {
 767         my(@m, @neat);
 768         push @m, "[";
 769         foreach my $elem (@$v) {
 770             push @neat, "q[$elem]";
 771         }
 772         push @m, join ", ", @neat;
 773         push @m, "]";
 774         return join "", @m;
 775     }
 776     return "$v" unless $t eq 'HASH';
 777     my(@m, $key, $val);
 778     while (($key,$val) = each %$v){
 779         last unless defined $key; # cautious programming in case (undef,undef) is true
 780         push(@m,"$key=>".neatvalue($val)) ;
 781     }
 782     return "{ ".join(', ',@m)." }";
 783 }
 784
 785 sub selfdocument {
 786     my($self) = @_;
 787     my(@m);
 788     if ($Verbose){
 789         push @m, "\n# Full list of MakeMaker attribute values:";
 790         foreach my $key (sort keys %$self){
 791             next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
 792             my($v) = neatvalue($self->{$key});
 793             $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
 794             $v =~ tr/\n/ /s;
 795             push @m, "# $key => $v";
 796         }
 797     }
 798     join "\n", @m;
 799 }
 800
 801 1;
 802
 803 __END__
 804
 805 =head1 NAME
 806
 807 ExtUtils::MakeMaker - create an extension Makefile
 808
 809 =head1 SYNOPSIS
 810
 811 C<use ExtUtils::MakeMaker;>
 812
 813 C<WriteMakefile( ATTRIBUTE =E<gt> VALUE [, ...] );>
 814
 815 which is really
 816
 817 C<MM-E<gt>new(\%att)-E<gt>flush;>
 818
 819 =head1 DESCRIPTION
 820
 821 This utility is designed to write a Makefile for an extension module
 822 from a Makefile.PL. It is based on the Makefile.SH model provided by
 823 Andy Dougherty and the perl5-porters.
 824
 825 It splits the task of generating the Makefile into several subroutines
 826 that can be individually overridden.  Each subroutine returns the text
 827 it wishes to have written to the Makefile.
 828
 829 MakeMaker is object oriented. Each directory below the current
 830 directory that contains a Makefile.PL. Is treated as a separate
 831 object. This makes it possible to write an unlimited number of
 832 Makefiles with a single invocation of WriteMakefile().
 833
 834 =head2 How To Write A Makefile.PL
 835
 836 The short answer is: Don't.
 837
 838         Always begin with h2xs.
 839         Always begin with h2xs!
 840         ALWAYS BEGIN WITH H2XS!
 841
 842 even if you're not building around a header file, and even if you
 843 don't have an XS component.
 844
 845 Run h2xs(1) before you start thinking about writing a module. For so
 846 called pm-only modules that consist of C<*.pm> files only, h2xs has
 847 the C<-X> switch. This will generate dummy files of all kinds that are
 848 useful for the module developer.
 849
 850 The medium answer is:
 851
 852     use ExtUtils::MakeMaker;
 853     WriteMakefile( NAME => "Foo::Bar" );
 854
 855 The long answer is the rest of the manpage :-)
 856
 857 =head2 Default Makefile Behaviour
 858
 859 The generated Makefile enables the user of the extension to invoke
 860
 861   perl Makefile.PL # optionally "perl Makefile.PL verbose"
 862   make
 863   make test        # optionally set TEST_VERBOSE=1
 864   make install     # See below
 865
 866 The Makefile to be produced may be altered by adding arguments of the
 867 form C<KEY=VALUE>. E.g.
 868
 869   perl Makefile.PL PREFIX=/tmp/myperl5
 870
 871 Other interesting targets in the generated Makefile are
 872
 873   make config     # to check if the Makefile is up-to-date
 874   make clean      # delete local temp files (Makefile gets renamed)
 875   make realclean  # delete derived files (including ./blib)
 876   make ci         # check in all the files in the MANIFEST file
 877   make dist       # see below the Distribution Support section
 878
 879 =head2 make test
 880
 881 MakeMaker checks for the existence of a file named F<test.pl> in the
 882 current directory and if it exists it adds commands to the test target
 883 of the generated Makefile that will execute the script with the proper
 884 set of perl C<-I> options.
 885
 886 MakeMaker also checks for any files matching glob("t/*.t"). It will
 887 add commands to the test target of the generated Makefile that execute
 888 all matching files via the L<Test::Harness> module with the C<-I>
 889 switches set correctly.
 890
 891 =head2 make testdb
 892
 893 A useful variation of the above is the target C<testdb>. It runs the
 894 test under the Perl debugger (see L<perldebug>). If the file
 895 F<test.pl> exists in the current directory, it is used for the test.
 896
 897 If you want to debug some other testfile, set C<TEST_FILE> variable
 898 thusly:
 899
 900   make testdb TEST_FILE=t/mytest.t
 901
 902 By default the debugger is called using C<-d> option to perl. If you
 903 want to specify some other option, set C<TESTDB_SW> variable:
 904
 905   make testdb TESTDB_SW=-Dx
 906
 907 =head2 make install
 908
 909 make alone puts all relevant files into directories that are named by
 910 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
 911 INST_MAN3DIR.  All these default to something below ./blib if you are
 912 I<not> building below the perl source directory. If you I<are>
 913 building below the perl source, INST_LIB and INST_ARCHLIB default to
 914 ../../lib, and INST_SCRIPT is not defined.
 915
 916 The I<install> target of the generated Makefile copies the files found
 917 below each of the INST_* directories to their INSTALL*
 918 counterparts. Which counterparts are chosen depends on the setting of
 919 INSTALLDIRS according to the following table:
 920
 921                                  INSTALLDIRS set to
 922                               perl                site
 923
 924     INST_ARCHLIB        INSTALLARCHLIB        INSTALLSITEARCH
 925     INST_LIB            INSTALLPRIVLIB        INSTALLSITELIB
 926     INST_BIN                      INSTALLBIN
 927     INST_SCRIPT                   INSTALLSCRIPT
 928     INST_MAN1DIR                  INSTALLMAN1DIR
 929     INST_MAN3DIR                  INSTALLMAN3DIR
 930
 931 The INSTALL... macros in turn default to their %Config
 932 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
 933
 934 You can check the values of these variables on your system with
 935
 936     perl '-V:install.*'
 937
 938 And to check the sequence in which the library directories are
 939 searched by perl, run
 940
 941     perl -le 'print join $/, @INC'
 942
 943
 944 =head2 PREFIX and LIB attribute
 945
 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
 948 be
 949
 950     perl Makefile.PL PREFIX=~
 951
 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
 954 ~/man and ~/lib).
 955
 956 Another way to specify many INSTALL directories with a single
 957 parameter is LIB.
 958
 959     perl Makefile.PL LIB=~/lib
 960
 961 This will install the module's architecture-independent files into
 962 ~/lib, the architecture-dependent files into ~/lib/$archname.
 963
 964 Note, that in both cases the tilde expansion is done by MakeMaker, not
 965 by perl by default, nor by make.
 966
 967 Conflicts between parameters LIB, PREFIX and the various INSTALL*
 968 arguments are resolved so that:
 969
 970 =over 4
 971
 972 =item *
 973
 974 setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
 975 INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
 976
 977 =item *
 978
 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}>).
 982
 983 =back
 984
 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
 988 the best:
 989
 990     perl Makefile.PL; make; make test
 991     make install
 992
 993 make install per default writes some documentation of what has been
 994 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
 995 can be bypassed by calling make pure_install.
 996
 997 =head2 AFS users
 998
 999 will have to specify the installation directories as these most
1000 probably have changed since perl itself has been installed. They will
1001 have to do this by calling
1002
1003     perl Makefile.PL INSTALLSITELIB=/afs/here/today \
1004         INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
1005     make
1006
1007 Be careful to repeat this procedure every time you recompile an
1008 extension, unless you are sure the AFS installation directories are
1009 still valid.
1010
1011 =head2 Static Linking of a new Perl Binary
1012
1013 An extension that is built with the above steps is ready to use on
1014 systems supporting dynamic loading. On systems that do not support
1015 dynamic loading, any newly created extension has to be linked together
1016 with the available resources. MakeMaker supports the linking process
1017 by creating appropriate targets in the Makefile whenever an extension
1018 is built. You can invoke the corresponding section of the makefile with
1019
1020     make perl
1021
1022 That produces a new perl binary in the current directory with all
1023 extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP,
1024 and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1025 UNIX, this is called Makefile.aperl (may be system dependent). If you
1026 want to force the creation of a new perl, it is recommended, that you
1027 delete this Makefile.aperl, so the directories are searched-through
1028 for linkable libraries again.
1029
1030 The binary can be installed into the directory where perl normally
1031 resides on your machine with
1032
1033     make inst_perl
1034
1035 To produce a perl binary with a different name than C<perl>, either say
1036
1037     perl Makefile.PL MAP_TARGET=myperl
1038     make myperl
1039     make inst_perl
1040
1041 or say
1042
1043     perl Makefile.PL
1044     make myperl MAP_TARGET=myperl
1045     make inst_perl MAP_TARGET=myperl
1046
1047 In any case you will be prompted with the correct invocation of the
1048 C<inst_perl> target that installs the new binary into INSTALLBIN.
1049
1050 make inst_perl per default writes some documentation of what has been
1051 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1052 can be bypassed by calling make pure_inst_perl.
1053
1054 Warning: the inst_perl: target will most probably overwrite your
1055 existing perl binary. Use with care!
1056
1057 Sometimes you might want to build a statically linked perl although
1058 your system supports dynamic loading. In this case you may explicitly
1059 set the linktype with the invocation of the Makefile.PL or make:
1060
1061     perl Makefile.PL LINKTYPE=static    # recommended
1062
1063 or
1064
1065     make LINKTYPE=static                # works on most systems
1066
1067 =head2 Determination of Perl Library and Installation Locations
1068
1069 MakeMaker needs to know, or to guess, where certain things are
1070 located.  Especially INST_LIB and INST_ARCHLIB (where to put the files
1071 during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1072 existing modules from), and PERL_INC (header files and C<libperl*.*>).
1073
1074 Extensions may be built either using the contents of the perl source
1075 directory tree or from the installed perl library. The recommended way
1076 is to build extensions after you have run 'make install' on perl
1077 itself. You can do that in any directory on your hard disk that is not
1078 below the perl source tree. The support for extensions below the ext
1079 directory of the perl distribution is only good for the standard
1080 extensions that come with perl.
1081
1082 If an extension is being built below the C<ext/> directory of the perl
1083 source then MakeMaker will set PERL_SRC automatically (e.g.,
1084 C<../..>).  If PERL_SRC is defined and the extension is recognized as
1085 a standard extension, then other variables default to the following:
1086
1087   PERL_INC     = PERL_SRC
1088   PERL_LIB     = PERL_SRC/lib
1089   PERL_ARCHLIB = PERL_SRC/lib
1090   INST_LIB     = PERL_LIB
1091   INST_ARCHLIB = PERL_ARCHLIB
1092
1093 If an extension is being built away from the perl source then MakeMaker
1094 will leave PERL_SRC undefined and default to using the installed copy
1095 of the perl library. The other variables default to the following:
1096
1097   PERL_INC     = $archlibexp/CORE
1098   PERL_LIB     = $privlibexp
1099   PERL_ARCHLIB = $archlibexp
1100   INST_LIB     = ./blib/lib
1101   INST_ARCHLIB = ./blib/arch
1102
1103 If perl has not yet been installed then PERL_SRC can be defined on the
1104 command line as shown in the previous section.
1105
1106
1107 =head2 Which architecture dependent directory?
1108
1109 If you don't want to keep the defaults for the INSTALL* macros,
1110 MakeMaker helps you to minimize the typing needed: the usual
1111 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1112 by Configure at perl compilation time. MakeMaker supports the user who
1113 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1114 then MakeMaker defaults the latter to be the same subdirectory of
1115 INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
1116 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1117 for INSTALLSITELIB and INSTALLSITEARCH.
1118
1119 MakeMaker gives you much more freedom than needed to configure
1120 internal variables and get different results. It is worth to mention,
1121 that make(1) also lets you configure most of the variables that are
1122 used in the Makefile. But in the majority of situations this will not
1123 be necessary, and should only be done if the author of a package
1124 recommends it (or you know what you're doing).
1125
1126 =head2 Using Attributes and Parameters
1127
1128 The following attributes can be specified as arguments to WriteMakefile()
1129 or as NAME=VALUE pairs on the command line:
1130
1131 =over 2
1132
1133 =item ABSTRACT
1134
1135 One line description of the module. Will be included in PPD file.
1136
1137 =item ABSTRACT_FROM
1138
1139 Name of the file that contains the package description. MakeMaker looks
1140 for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1141 the first line in the "=head1 NAME" section. $2 becomes the abstract.
1142
1143 =item AUTHOR
1144
1145 String containing name (and email address) of package author(s). Is used
1146 in PPD (Perl Package Description) files for PPM (Perl Package Manager).
1147
1148 =item BINARY_LOCATION
1149
1150 Used when creating PPD files for binary packages.  It can be set to a
1151 full or relative path or URL to the binary archive for a particular
1152 architecture.  For example:
1153
1154         perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
1155
1156 builds a PPD package that references a binary of the C<Agent> package,
1157 located in the C<x86> directory relative to the PPD itself.
1158
1159 =item C
1160
1161 Ref to array of *.c file names. Initialised from a directory scan
1162 and the values portion of the XS attribute hash. This is not
1163 currently used by MakeMaker but may be handy in Makefile.PLs.
1164
1165 =item CCFLAGS
1166
1167 String that will be included in the compiler call command line between
1168 the arguments INC and OPTIMIZE.
1169
1170 =item CONFIG
1171
1172 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1173 config.sh. MakeMaker will add to CONFIG the following values anyway:
1174 ar
1175 cc
1176 cccdlflags
1177 ccdlflags
1178 dlext
1179 dlsrc
1180 ld
1181 lddlflags
1182 ldflags
1183 libc
1184 lib_ext
1185 obj_ext
1186 ranlib
1187 sitelibexp
1188 sitearchexp
1189 so
1190
1191 =item CONFIGURE
1192
1193 CODE reference. The subroutine should return a hash reference. The
1194 hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
1195 be determined by some evaluation method.
1196
1197 =item DEFINE
1198
1199 Something like C<"-DHAVE_UNISTD_H">
1200
1201 =item DIR
1202
1203 Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
1204 ] in ext/SDBM_File
1205
1206 =item DISTNAME
1207
1208 Your name for distributing the package (by tar file). This defaults to
1209 NAME above.
1210
1211 =item DL_FUNCS
1212
1213 Hashref of symbol names for routines to be made available as universal
1214 symbols.  Each key/value pair consists of the package name and an
1215 array of routine names in that package.  Used only under AIX, OS/2,
1216 VMS and Win32 at present.  The routine names supplied will be expanded
1217 in the same way as XSUB names are expanded by the XS() macro.
1218 Defaults to
1219
1220   {"$(NAME)" => ["boot_$(NAME)" ] }
1221
1222 e.g.
1223
1224   {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1225    "NetconfigPtr" => [ 'DESTROY'] }
1226
1227 Please see the L<ExtUtils::Mksymlists> documentation for more information
1228 about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1229
1230 =item DL_VARS
1231
1232 Array of symbol names for variables to be made available as universal symbols.
1233 Used only under AIX, OS/2, VMS and Win32 at present.  Defaults to [].
1234 (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
1235
1236 =item EXCLUDE_EXT
1237
1238 Array of extension names to exclude when doing a static build.  This
1239 is ignored if INCLUDE_EXT is present.  Consult INCLUDE_EXT for more
1240 details.  (e.g.  [ qw( Socket POSIX ) ] )
1241
1242 This attribute may be most useful when specified as a string on the
1243 command line:  perl Makefile.PL EXCLUDE_EXT='Socket Safe'
1244
1245 =item EXE_FILES
1246
1247 Ref to array of executable files. The files will be copied to the
1248 INST_SCRIPT directory. Make realclean will delete them from there
1249 again.
1250
1251 =item FIRST_MAKEFILE
1252
1253 The name of the Makefile to be produced. Defaults to the contents of
1254 MAKEFILE, but can be overridden. This is used for the second Makefile
1255 that will be produced for the MAP_TARGET.
1256
1257 =item FULLPERL
1258
1259 Perl binary able to run this extension, load XS modules, etc...
1260
1261 =item FULLPERLRUN
1262
1263 Like PERLRUN, except it uses FULLPERL.
1264
1265 =item FULLPERLRUNINST
1266
1267 Like PERLRUNINST, except it uses FULLPERL.
1268
1269 =item FUNCLIST
1270
1271 This provides an alternate means to specify function names to be
1272 exported from the extension.  Its value is a reference to an
1273 array of function names to be exported by the extension.  These
1274 names are passed through unaltered to the linker options file.
1275
1276 =item H
1277
1278 Ref to array of *.h file names. Similar to C.
1279
1280 =item IMPORTS
1281
1282 This attribute is used to specify names to be imported into the
1283 extension. It is only used on OS/2 and Win32.
1284
1285 =item INC
1286
1287 Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
1288
1289 =item INCLUDE_EXT
1290
1291 Array of extension names to be included when doing a static build.
1292 MakeMaker will normally build with all of the installed extensions when
1293 doing a static build, and that is usually the desired behavior.  If
1294 INCLUDE_EXT is present then MakeMaker will build only with those extensions
1295 which are explicitly mentioned. (e.g.  [ qw( Socket POSIX ) ])
1296
1297 It is not necessary to mention DynaLoader or the current extension when
1298 filling in INCLUDE_EXT.  If the INCLUDE_EXT is mentioned but is empty then
1299 only DynaLoader and the current extension will be included in the build.
1300
1301 This attribute may be most useful when specified as a string on the
1302 command line:  perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
1303
1304 =item INSTALLARCHLIB
1305
1306 Used by 'make install', which copies files from INST_ARCHLIB to this
1307 directory if INSTALLDIRS is set to perl.
1308
1309 =item INSTALLBIN
1310
1311 Directory to install binary files (e.g. tkperl) into.
1312
1313 =item INSTALLDIRS
1314
1315 Determines which of the two sets of installation directories to
1316 choose: installprivlib and installarchlib versus installsitelib and
1317 installsitearch. The first pair is chosen with INSTALLDIRS=perl, the
1318 second with INSTALLDIRS=site. Default is site.
1319
1320 =item INSTALLMAN1DIR
1321
1322 This directory gets the man pages at 'make install' time. Defaults to
1323 $Config{installman1dir}.
1324
1325 =item INSTALLMAN3DIR
1326
1327 This directory gets the man pages at 'make install' time. Defaults to
1328 $Config{installman3dir}.
1329
1330 =item INSTALLPRIVLIB
1331
1332 Used by 'make install', which copies files from INST_LIB to this
1333 directory if INSTALLDIRS is set to perl.
1334
1335 =item INSTALLSCRIPT
1336
1337 Used by 'make install' which copies files from INST_SCRIPT to this
1338 directory.
1339
1340 =item INSTALLSITEARCH
1341
1342 Used by 'make install', which copies files from INST_ARCHLIB to this
1343 directory if INSTALLDIRS is set to site (default).
1344
1345 =item INSTALLSITELIB
1346
1347 Used by 'make install', which copies files from INST_LIB to this
1348 directory if INSTALLDIRS is set to site (default).
1349
1350 =item INST_ARCHLIB
1351
1352 Same as INST_LIB for architecture dependent files.
1353
1354 =item INST_BIN
1355
1356 Directory to put real binary files during 'make'. These will be copied
1357 to INSTALLBIN during 'make install'
1358
1359 =item INST_EXE
1360
1361 Old name for INST_SCRIPT. Deprecated. Please use INST_SCRIPT if you
1362 need to use it.
1363
1364 =item INST_LIB
1365
1366 Directory where we put library files of this extension while building
1367 it.
1368
1369 =item INST_MAN1DIR
1370
1371 Directory to hold the man pages at 'make' time
1372
1373 =item INST_MAN3DIR
1374
1375 Directory to hold the man pages at 'make' time
1376
1377 =item INST_SCRIPT
1378
1379 Directory, where executable files should be installed during
1380 'make'. Defaults to "./blib/script", just to have a dummy location during
1381 testing. make install will copy the files in INST_SCRIPT to
1382 INSTALLSCRIPT.
1383
1384 =item LDFROM
1385
1386 defaults to "$(OBJECT)" and is used in the ld command to specify
1387 what files to link/load from (also see dynamic_lib below for how to
1388 specify ld flags)
1389
1390 =item LIB
1391
1392 LIB should only be set at C<perl Makefile.PL> time but is allowed as a
1393 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
1394 and INSTALLSITELIB to that value regardless any explicit setting of
1395 those arguments (or of PREFIX).  INSTALLARCHLIB and INSTALLSITEARCH
1396 are set to the corresponding architecture subdirectory.
1397
1398 =item LIBPERL_A
1399
1400 The filename of the perllibrary that will be used together with this
1401 extension. Defaults to libperl.a.
1402
1403 =item LIBS
1404
1405 An anonymous array of alternative library
1406 specifications to be searched for (in order) until
1407 at least one library is found. E.g.
1408
1409   'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
1410
1411 Mind, that any element of the array
1412 contains a complete set of arguments for the ld
1413 command. So do not specify
1414
1415   'LIBS' => ["-ltcl", "-ltk", "-lX11"]
1416
1417 See ODBM_File/Makefile.PL for an example, where an array is needed. If
1418 you specify a scalar as in
1419
1420   'LIBS' => "-ltcl -ltk -lX11"
1421
1422 MakeMaker will turn it into an array with one element.
1423
1424 =item LINKTYPE
1425
1426 'static' or 'dynamic' (default unless usedl=undef in
1427 config.sh). Should only be used to force static linking (also see
1428 linkext below).
1429
1430 =item MAKEAPERL
1431
1432 Boolean which tells MakeMaker, that it should include the rules to
1433 make a perl. This is handled automatically as a switch by
1434 MakeMaker. The user normally does not need it.
1435
1436 =item MAKEFILE
1437
1438 The name of the Makefile to be produced.
1439
1440 =item MAN1PODS
1441
1442 Hashref of pod-containing files. MakeMaker will default this to all
1443 EXE_FILES files that include POD directives. The files listed
1444 here will be converted to man pages and installed as was requested
1445 at Configure time.
1446
1447 =item MAN3PODS
1448
1449 Hashref that assigns to *.pm and *.pod files the files into which the
1450 manpages are to be written. MakeMaker parses all *.pod and *.pm files
1451 for POD directives. Files that contain POD will be the default keys of
1452 the MAN3PODS hashref. These will then be converted to man pages during
1453 C<make> and will be installed during C<make install>.
1454
1455 =item MAP_TARGET
1456
1457 If it is intended, that a new perl binary be produced, this variable
1458 may hold a name for that binary. Defaults to perl
1459
1460 =item MYEXTLIB
1461
1462 If the extension links to a library that it builds set this to the
1463 name of the library (see SDBM_File)
1464
1465 =item NAME
1466
1467 Perl module name for this extension (DBD::Oracle). This will default
1468 to the directory name but should be explicitly defined in the
1469 Makefile.PL.
1470
1471 =item NEEDS_LINKING
1472
1473 MakeMaker will figure out if an extension contains linkable code
1474 anywhere down the directory tree, and will set this variable
1475 accordingly, but you can speed it up a very little bit if you define
1476 this boolean variable yourself.
1477
1478 =item NOECHO
1479
1480 Defaults to C<@>. By setting it to an empty string you can generate a
1481 Makefile that echos all commands. Mainly used in debugging MakeMaker
1482 itself.
1483
1484 =item NORECURS
1485
1486 Boolean.  Attribute to inhibit descending into subdirectories.
1487
1488 =item NO_VC
1489
1490 In general, any generated Makefile checks for the current version of
1491 MakeMaker and the version the Makefile was built under. If NO_VC is
1492 set, the version check is neglected. Do not write this into your
1493 Makefile.PL, use it interactively instead.
1494
1495 =item OBJECT
1496
1497 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
1498 string containing all object files, e.g. "tkpBind.o
1499 tkpButton.o tkpCanvas.o"
1500
1501 (Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)
1502
1503 =item OPTIMIZE
1504
1505 Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
1506 passed to subdirectory makes.
1507
1508 =item PERL
1509
1510 Perl binary for tasks that can be done by miniperl
1511
1512 =item PERL_CORE
1513
1514 Set only when MakeMaker is building the extensions of the Perl core
1515 distribution.
1516
1517 =item PERLMAINCC
1518
1519 The call to the program that is able to compile perlmain.c. Defaults
1520 to $(CC).
1521
1522 =item PERL_ARCHLIB
1523
1524 Same as for PERL_LIB, but for architecture dependent files.
1525
1526 Used only when MakeMaker is building the extensions of the Perl core
1527 distribution (because normally $(PERL_ARCHLIB) is automatically in @INC,
1528 and adding it would get in the way of PERL5LIB).
1529
1530 =item PERL_LIB
1531
1532 Directory containing the Perl library to use.
1533
1534 Used only when MakeMaker is building the extensions of the Perl core
1535 distribution (because normally $(PERL_LIB) is automatically in @INC,
1536 and adding it would get in the way of PERL5LIB).
1537
1538 =item PERL_MALLOC_OK
1539
1540 defaults to 0.  Should be set to TRUE if the extension can work with
1541 the memory allocation routines substituted by the Perl malloc() subsystem.
1542 This should be applicable to most extensions with exceptions of those
1543
1544 =over 4
1545
1546 =item *
1547
1548 with bugs in memory allocations which are caught by Perl's malloc();
1549
1550 =item *
1551
1552 which interact with the memory allocator in other ways than via
1553 malloc(), realloc(), free(), calloc(), sbrk() and brk();
1554
1555 =item *
1556
1557 which rely on special alignment which is not provided by Perl's malloc().
1558
1559 =back
1560
1561 B<NOTE.>  Negligence to set this flag in I<any one> of loaded extension
1562 nullifies many advantages of Perl's malloc(), such as better usage of
1563 system resources, error detection, memory usage reporting, catchable failure
1564 of memory allocations, etc.
1565
1566 =item PERLRUN
1567
1568 Use this instead of $(PERL) when you wish to run perl.  It will set up
1569 extra necessary flags for you.
1570
1571 =item PERLRUNINST
1572
1573 Use this instead of $(PERL) when you wish to run perl to work with
1574 modules.  It will add things like -I$(INST_ARCH) and other necessary
1575 flags so perl can see the modules you're about to install.
1576
1577 =item PERL_SRC
1578
1579 Directory containing the Perl source code (use of this should be
1580 avoided, it may be undefined)
1581
1582 =item PERM_RW
1583
1584 Desired permission for read/writable files. Defaults to C<644>.
1585 See also L<MM_Unix/perm_rw>.
1586
1587 =item PERM_RWX
1588
1589 Desired permission for executable files. Defaults to C<755>.
1590 See also L<MM_Unix/perm_rwx>.
1591
1592 =item PL_FILES
1593
1594 Ref to hash of files to be processed as perl programs. MakeMaker
1595 will default to any found *.PL file (except Makefile.PL) being keys
1596 and the basename of the file being the value. E.g.
1597
1598   {'foobar.PL' => 'foobar'}
1599
1600 The *.PL files are expected to produce output to the target files
1601 themselves. If multiple files can be generated from the same *.PL
1602 file then the value in the hash can be a reference to an array of
1603 target file names. E.g.
1604
1605   {'foobar.PL' => ['foobar1','foobar2']}
1606
1607 =item PM
1608
1609 Hashref of .pm files and *.pl files to be installed.  e.g.
1610
1611   {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
1612
1613 By default this will include *.pm and *.pl and the files found in
1614 the PMLIBDIRS directories.  Defining PM in the
1615 Makefile.PL will override PMLIBDIRS.
1616
1617 =item PMLIBDIRS
1618
1619 Ref to array of subdirectories containing library files.  Defaults to
1620 [ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
1621 they contain will be installed in the corresponding location in the
1622 library.  A libscan() method can be used to alter the behaviour.
1623 Defining PM in the Makefile.PL will override PMLIBDIRS.
1624
1625 (Where BASEEXT is the last component of NAME.)
1626
1627 =item PM_FILTER
1628
1629 A filter program, in the traditional Unix sense (input from stdin, output
1630 to stdout) that is passed on each .pm file during the build (in the
1631 pm_to_blib() phase).  It is empty by default, meaning no filtering is done.
1632
1633 Great care is necessary when defining the command if quoting needs to be
1634 done.  For instance, you would need to say:
1635
1636   {'PM_FILTER' => 'grep -v \\"^\\#\\"'}
1637
1638 to remove all the leading coments on the fly during the build.  The
1639 extra \\ are necessary, unfortunately, because this variable is interpolated
1640 within the context of a Perl program built on the command line, and double
1641 quotes are what is used with the -e switch to build that command line.  The
1642 # is escaped for the Makefile, since what is going to be generated will then
1643 be:
1644
1645   PM_FILTER = grep -v \"^\#\"
1646
1647 Without the \\ before the #, we'd have the start of a Makefile comment,
1648 and the macro would be incorrectly defined.
1649
1650 =item POLLUTE
1651
1652 Release 5.005 grandfathered old global symbol names by providing preprocessor
1653 macros for extension source compatibility.  As of release 5.6, these
1654 preprocessor definitions are not available by default.  The POLLUTE flag
1655 specifies that the old names should still be defined:
1656
1657   perl Makefile.PL POLLUTE=1
1658
1659 Please inform the module author if this is necessary to successfully install
1660 a module under 5.6 or later.
1661
1662 =item PPM_INSTALL_EXEC
1663
1664 Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
1665
1666 =item PPM_INSTALL_SCRIPT
1667
1668 Name of the script that gets executed by the Perl Package Manager after
1669 the installation of a package.
1670
1671 =item PREFIX
1672
1673 This overrides all the default install locations.  Man pages,
1674 libraries, scripts, etc...  MakeMaker will try to make an educated
1675 guess about where to place things under the new PREFIX based on your
1676 Config defaults.  Failing that, it will fall back to a structure
1677 which should be sensible for your platform.
1678
1679 If you specify LIB or any INSTALL* variables they will not be effected
1680 by the PREFIX.
1681
1682 =item PREREQ_PM
1683
1684 Hashref: Names of modules that need to be available to run this
1685 extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
1686 desired version is the value. If the required version number is 0, we
1687 only check if any version is installed already.
1688
1689 =item PREREQ_FATAL
1690
1691 Bool. If this parameter is true, failing to have the required modules
1692 (or the right versions thereof) will be fatal. perl Makefile.PL will die
1693 with the proper message.
1694
1695 Note: see L<Test::Harness> for a shortcut for stopping tests early if
1696 you are missing dependencies.
1697
1698 Do I<not> use this parameter for simple requirements, which could be resolved
1699 at a later time, e.g. after an unsuccessful B<make test> of your module.
1700
1701 It is I<extremely> rare to have to use C<PREREQ_FATAL> at all!
1702
1703 =item PREREQ_PRINT
1704
1705 Bool.  If this parameter is true, the prerequisites will be printed to
1706 stdout and MakeMaker will exit.  The output format is
1707
1708 $PREREQ_PM = {
1709                'A::B' => Vers1,
1710                'C::D' => Vers2,
1711                ...
1712              };
1713
1714 =item PRINT_PREREQ
1715
1716 RedHatism for C<PREREQ_PRINT>.  The output format is different, though:
1717
1718     perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
1719
1720 =item SKIP
1721
1722 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
1723 Makefile. Caution! Do not use the SKIP attribute for the negligible
1724 speedup. It may seriously damage the resulting Makefile. Only use it
1725 if you really need it.
1726
1727 =item TEST_LIBS
1728
1729 The set of -I's necessary to run a "make test".  Use as:
1730 $(PERL) $(TEST_LIBS) -e '...' for example.
1731
1732 The paths will be absolute.
1733
1734 =item TYPEMAPS
1735
1736 Ref to array of typemap file names.  Use this when the typemaps are
1737 in some directory other than the current directory or when they are
1738 not named B<typemap>.  The last typemap in the list takes
1739 precedence.  A typemap in the current directory has highest
1740 precedence, even if it isn't listed in TYPEMAPS.  The default system
1741 typemap has lowest precedence.
1742
1743 =item VERSION
1744
1745 Your version number for distributing the package.  This defaults to
1746 0.1.
1747
1748 =item VERSION_FROM
1749
1750 Instead of specifying the VERSION in the Makefile.PL you can let
1751 MakeMaker parse a file to determine the version number. The parsing
1752 routine requires that the file named by VERSION_FROM contains one
1753 single line to compute the version number. The first line in the file
1754 that contains the regular expression
1755
1756     /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
1757
1758 will be evaluated with eval() and the value of the named variable
1759 B<after> the eval() will be assigned to the VERSION attribute of the
1760 MakeMaker object. The following lines will be parsed o.k.:
1761
1762     $VERSION = '1.00';
1763     *VERSION = \'1.01';
1764     ( $VERSION ) = '$Revision: 1.23 $ ' =~ /\$Revision:\s+([^\s]+)/;
1765     $FOO::VERSION = '1.10';
1766     *FOO::VERSION = \'1.11';
1767     our $VERSION = 1.2.3;       # new for perl5.6.0
1768
1769 but these will fail:
1770
1771     my $VERSION = '1.01';
1772     local $VERSION = '1.02';
1773     local $FOO::VERSION = '1.30';
1774
1775 (Putting C<my> or C<local> on the preceding line will work o.k.)
1776
1777 The file named in VERSION_FROM is not added as a dependency to
1778 Makefile. This is not really correct, but it would be a major pain
1779 during development to have to rewrite the Makefile for any smallish
1780 change in that file. If you want to make sure that the Makefile
1781 contains the correct VERSION macro after any change of the file, you
1782 would have to do something like
1783
1784     depend => { Makefile => '$(VERSION_FROM)' }
1785
1786 See attribute C<depend> below.
1787
1788 =item XS
1789
1790 Hashref of .xs files. MakeMaker will default this.  e.g.
1791
1792   {'name_of_file.xs' => 'name_of_file.c'}
1793
1794 The .c files will automatically be included in the list of files
1795 deleted by a make clean.
1796
1797 =item XSOPT
1798
1799 String of options to pass to xsubpp.  This might include C<-C++> or
1800 C<-extern>.  Do not include typemaps here; the TYPEMAP parameter exists for
1801 that purpose.
1802
1803 =item XSPROTOARG
1804
1805 May be set to an empty string, which is identical to C<-prototypes>, or
1806 C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
1807 defaults to the empty string.
1808
1809 =item XS_VERSION
1810
1811 Your version number for the .xs file of this package.  This defaults
1812 to the value of the VERSION attribute.
1813
1814 =back
1815
1816 =head2 Additional lowercase attributes
1817
1818 can be used to pass parameters to the methods which implement that
1819 part of the Makefile.
1820
1821 =over 2
1822
1823 =item clean
1824
1825   {FILES => "*.xyz foo"}
1826
1827 =item depend
1828
1829   {ANY_TARGET => ANY_DEPENDECY, ...}
1830
1831 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
1832
1833 =item dist
1834
1835   {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
1836   SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
1837   ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
1838
1839 If you specify COMPRESS, then SUFFIX should also be altered, as it is
1840 needed to tell make the target file of the compression. Setting
1841 DIST_CP to ln can be useful, if you need to preserve the timestamps on
1842 your files. DIST_CP can take the values 'cp', which copies the file,
1843 'ln', which links the file, and 'best' which copies symbolic links and
1844 links the rest. Default is 'best'.
1845
1846 =item dynamic_lib
1847
1848   {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
1849
1850 =item linkext
1851
1852   {LINKTYPE => 'static', 'dynamic' or ''}
1853
1854 NB: Extensions that have nothing but *.pm files had to say
1855
1856   {LINKTYPE => ''}
1857
1858 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
1859 can be deleted safely. MakeMaker recognizes when there's nothing to
1860 be linked.
1861
1862 =item macro
1863
1864   {ANY_MACRO => ANY_VALUE, ...}
1865
1866 =item realclean
1867
1868   {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
1869
1870 =item test
1871
1872   {TESTS => 't/*.t'}
1873
1874 =item tool_autosplit
1875
1876   {MAXLEN => 8}
1877
1878 =back
1879
1880 =head2 Overriding MakeMaker Methods
1881
1882 If you cannot achieve the desired Makefile behaviour by specifying
1883 attributes you may define private subroutines in the Makefile.PL.
1884 Each subroutines returns the text it wishes to have written to
1885 the Makefile. To override a section of the Makefile you can
1886 either say:
1887
1888         sub MY::c_o { "new literal text" }
1889
1890 or you can edit the default by saying something like:
1891
1892         sub MY::c_o {
1893             package MY; # so that "SUPER" works right
1894             my $inherited = shift->SUPER::c_o(@_);
1895             $inherited =~ s/old text/new text/;
1896             $inherited;
1897         }
1898
1899 If you are running experiments with embedding perl as a library into
1900 other applications, you might find MakeMaker is not sufficient. You'd
1901 better have a look at ExtUtils::Embed which is a collection of utilities
1902 for embedding.
1903
1904 If you still need a different solution, try to develop another
1905 subroutine that fits your needs and submit the diffs to
1906 F<perl5-porters@perl.org> or F<comp.lang.perl.moderated> as appropriate.
1907
1908 For a complete description of all MakeMaker methods see L<ExtUtils::MM_Unix>.
1909
1910 Here is a simple example of how to add a new target to the generated
1911 Makefile:
1912
1913     sub MY::postamble {
1914         '
1915     $(MYEXTLIB): sdbm/Makefile
1916             cd sdbm && $(MAKE) all
1917     ';
1918     }
1919
1920
1921 =head2 Hintsfile support
1922
1923 MakeMaker.pm uses the architecture specific information from
1924 Config.pm. In addition it evaluates architecture specific hints files
1925 in a C<hints/> directory. The hints files are expected to be named
1926 like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
1927 name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
1928 MakeMaker within the WriteMakefile() subroutine, and can be used to
1929 execute commands as well as to include special variables. The rules
1930 which hintsfile is chosen are the same as in Configure.
1931
1932 The hintsfile is eval()ed immediately after the arguments given to
1933 WriteMakefile are stuffed into a hash reference $self but before this
1934 reference becomes blessed. So if you want to do the equivalent to
1935 override or create an attribute you would say something like
1936
1937     $self->{LIBS} = ['-ldbm -lucb -lc'];
1938
1939 =head2 Distribution Support
1940
1941 For authors of extensions MakeMaker provides several Makefile
1942 targets. Most of the support comes from the ExtUtils::Manifest module,
1943 where additional documentation can be found.
1944
1945 =over 4
1946
1947 =item    make distcheck
1948
1949 reports which files are below the build directory but not in the
1950 MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
1951 details)
1952
1953 =item    make skipcheck
1954
1955 reports which files are skipped due to the entries in the
1956 C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
1957 details)
1958
1959 =item    make distclean
1960
1961 does a realclean first and then the distcheck. Note that this is not
1962 needed to build a new distribution as long as you are sure that the
1963 MANIFEST file is ok.
1964
1965 =item    make manifest
1966
1967 rewrites the MANIFEST file, adding all remaining files found (See
1968 ExtUtils::Manifest::mkmanifest() for details)
1969
1970 =item    make distdir
1971
1972 Copies all the files that are in the MANIFEST file to a newly created
1973 directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
1974 exists, it will be removed first.
1975
1976 =item   make disttest
1977
1978 Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
1979 a make test in that directory.
1980
1981 =item    make tardist
1982
1983 First does a distdir. Then a command $(PREOP) which defaults to a null
1984 command, followed by $(TOUNIX), which defaults to a null command under
1985 UNIX, and will convert files in distribution directory to UNIX format
1986 otherwise. Next it runs C<tar> on that directory into a tarfile and
1987 deletes the directory. Finishes with a command $(POSTOP) which
1988 defaults to a null command.
1989
1990 =item    make dist
1991
1992 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
1993
1994 =item    make uutardist
1995
1996 Runs a tardist first and uuencodes the tarfile.
1997
1998 =item    make shdist
1999
2000 First does a distdir. Then a command $(PREOP) which defaults to a null
2001 command. Next it runs C<shar> on that directory into a sharfile and
2002 deletes the intermediate directory again. Finishes with a command
2003 $(POSTOP) which defaults to a null command.  Note: For shdist to work
2004 properly a C<shar> program that can handle directories is mandatory.
2005
2006 =item    make zipdist
2007
2008 First does a distdir. Then a command $(PREOP) which defaults to a null
2009 command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
2010 zipfile. Then deletes that directory. Finishes with a command
2011 $(POSTOP) which defaults to a null command.
2012
2013 =item    make ci
2014
2015 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
2016
2017 =back
2018
2019 Customization of the dist targets can be done by specifying a hash
2020 reference to the dist attribute of the WriteMakefile call. The
2021 following parameters are recognized:
2022
2023     CI           ('ci -u')
2024     COMPRESS     ('gzip --best')
2025     POSTOP       ('@ :')
2026     PREOP        ('@ :')
2027     TO_UNIX      (depends on the system)
2028     RCS_LABEL    ('rcs -q -Nv$(VERSION_SYM):')
2029     SHAR         ('shar')
2030     SUFFIX       ('.gz')
2031     TAR          ('tar')
2032     TARFLAGS     ('cvf')
2033     ZIP          ('zip')
2034     ZIPFLAGS     ('-r')
2035
2036 An example:
2037
2038     WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
2039
2040 =head2 Disabling an extension
2041
2042 If some events detected in F<Makefile.PL> imply that there is no way
2043 to create the Module, but this is a normal state of things, then you
2044 can create a F<Makefile> which does nothing, but succeeds on all the
2045 "usual" build targets.  To do so, use
2046
2047    ExtUtils::MakeMaker::WriteEmptyMakefile();
2048
2049 instead of WriteMakefile().
2050
2051 This may be useful if other modules expect this module to be I<built>
2052 OK, as opposed to I<work> OK (say, this system-dependent module builds
2053 in a subdirectory of some other distribution, or is listed as a
2054 dependency in a CPAN::Bundle, but the functionality is supported by
2055 different means on the current architecture).
2056
2057 =head1 ENVIRONMENT
2058
2059 =over 8
2060
2061 =item PERL_MM_OPT
2062
2063 Command line options used by C<MakeMaker-E<gt>new()>, and thus by
2064 C<WriteMakefile()>.  The string is split on whitespace, and the result
2065 is processed before any actual command line arguments are processed.
2066
2067 =item PERL_MM_USE_DEFAULT
2068
2069 If set to a true value then MakeMaker's prompt function will
2070 always return the default without waiting for user input.
2071
2072 =back
2073
2074 =head1 SEE ALSO
2075
2076 ExtUtils::MM_Unix, ExtUtils::Manifest ExtUtils::Install,
2077 ExtUtils::Embed
2078
2079 =head1 AUTHORS
2080
2081 Andy Dougherty <F<doughera@lafcol.lafayette.edu>>, Andreas KE<ouml>nig
2082 <F<andreas.koenig@mind.de>>, Tim Bunce <F<Tim.Bunce@ig.co.uk>>.  VMS
2083 support by Charles Bailey <F<bailey@newman.upenn.edu>>.  OS/2 support
2084 by Ilya Zakharevich <F<ilya@math.ohio-state.edu>>.
2085
2086 Currently maintained by Michael G Schwern <F<schwern@pobox.com>>
2087
2088 Send patches and ideas to <F<makemaker@perl.org>>.
2089
2090 Send bug reports via http://rt.cpan.org/.
2091
2092 =cut