[Summary view] [Print] [Text view]

   1  # $Id: /mirror/svn.schwern.org/CPAN/ExtUtils-MakeMaker/trunk/lib/ExtUtils/MakeMaker.pm 41145 2007-12-08T01:01:11.051959Z schwern  $
   2  package ExtUtils::MakeMaker;
   3  
   4  BEGIN {require 5.005_03;}
   5  
   6  require Exporter;
   7  use ExtUtils::MakeMaker::Config;
   8  use Carp ();
   9  use File::Path;
  10  
  11  use vars qw(
  12              @ISA @EXPORT @EXPORT_OK
  13              $VERSION $Verbose %Config
  14              @Prepend_parent @Parent
  15              %Recognized_Att_Keys @Get_from_Config @MM_Sections @Overridable
  16              $Filename
  17             );
  18  
  19  # Has to be on its own line with no $ after it to avoid being noticed by
  20  # the version control system
  21  use vars qw($Revision);
  22  use strict;
  23  
  24  $VERSION = '6.42';
  25  ($Revision) = q$Revision: 41145 $ =~ /Revision:\s+(\S+)/;
  26  
  27  @ISA = qw(Exporter);
  28  @EXPORT = qw(&WriteMakefile &writeMakefile $Verbose &prompt);
  29  @EXPORT_OK = qw($VERSION &neatvalue &mkbootstrap &mksymlists
  30                  &WriteEmptyMakefile);
  31  
  32  # These will go away once the last of the Win32 & VMS specific code is 
  33  # purged.
  34  my $Is_VMS     = $^O eq 'VMS';
  35  my $Is_Win32   = $^O eq 'MSWin32';
  36  
  37  # Our filename for diagnostic and debugging purposes.  More reliable
  38  # than %INC (think caseless filesystems)
  39  $Filename = __FILE__;
  40  
  41  full_setup();
  42  
  43  require ExtUtils::MM;  # Things like CPAN assume loading ExtUtils::MakeMaker
  44                         # will give them MM.
  45  
  46  require ExtUtils::MY;  # XXX pre-5.8 versions of ExtUtils::Embed expect
  47                         # loading ExtUtils::MakeMaker will give them MY.
  48                         # This will go when Embed is it's own CPAN module.
  49  
  50  
  51  sub WriteMakefile {
  52      Carp::croak "WriteMakefile: Need even number of args" if @_ % 2;
  53  
  54      require ExtUtils::MY;
  55      my %att = @_;
  56  
  57      _verify_att(\%att);
  58  
  59      my $mm = MM->new(\%att);
  60      $mm->flush;
  61  
  62      return $mm;
  63  }
  64  
  65  
  66  # Basic signatures of the attributes WriteMakefile takes.  Each is the
  67  # reference type.  Empty value indicate it takes a non-reference
  68  # scalar.
  69  my %Att_Sigs;
  70  my %Special_Sigs = (
  71   C                  => 'ARRAY',
  72   CONFIG             => 'ARRAY',
  73   CONFIGURE          => 'CODE',
  74   DIR                => 'ARRAY',
  75   DL_FUNCS           => 'HASH',
  76   DL_VARS            => 'ARRAY',
  77   EXCLUDE_EXT        => 'ARRAY',
  78   EXE_FILES          => 'ARRAY',
  79   FUNCLIST           => 'ARRAY',
  80   H                  => 'ARRAY',
  81   IMPORTS            => 'HASH',
  82   INCLUDE_EXT        => 'ARRAY',
  83   LIBS               => ['ARRAY',''],
  84   MAN1PODS           => 'HASH',
  85   MAN3PODS           => 'HASH',
  86   PL_FILES           => 'HASH',
  87   PM                 => 'HASH',
  88   PMLIBDIRS          => 'ARRAY',
  89   PMLIBPARENTDIRS    => 'ARRAY',
  90   PREREQ_PM          => 'HASH',
  91   SKIP               => 'ARRAY',
  92   TYPEMAPS           => 'ARRAY',
  93   XS                 => 'HASH',
  94   VERSION            => ['version',''],
  95   _KEEP_AFTER_FLUSH  => '',
  96  
  97   clean      => 'HASH',
  98   depend     => 'HASH',
  99   dist       => 'HASH',
 100   dynamic_lib=> 'HASH',
 101   linkext    => 'HASH',
 102   macro      => 'HASH',
 103   postamble  => 'HASH',
 104   realclean  => 'HASH',
 105   test       => 'HASH',
 106   tool_autosplit => 'HASH',
 107  );
 108  
 109  @Att_Sigs{keys %Recognized_Att_Keys} = ('') x keys %Recognized_Att_Keys;
 110  @Att_Sigs{keys %Special_Sigs} = values %Special_Sigs;
 111  
 112  
 113  sub _verify_att {
 114      my($att) = @_;
 115  
 116      while( my($key, $val) = each %$att ) {
 117          my $sig = $Att_Sigs{$key};
 118          unless( defined $sig ) {
 119              warn "WARNING: $key is not a known parameter.\n";
 120              next;
 121          }
 122  
 123          my @sigs   = ref $sig ? @$sig : $sig;
 124          my $given  = ref $val;
 125          unless( grep { $given eq $_ || ($_ && eval{$val->isa($_)}) } @sigs ) {
 126              my $takes = join " or ", map { _format_att($_) } @sigs;
 127  
 128              my $has = _format_att($given);
 129              warn "WARNING: $key takes a $takes not a $has.\n".
 130                   "         Please inform the author.\n";
 131          }
 132      }
 133  }
 134  
 135  
 136  sub _format_att {
 137      my $given = shift;
 138      
 139      return $given eq ''        ? "string/number"
 140           : uc $given eq $given ? "$given reference"
 141           :                       "$given object"
 142           ;
 143  }
 144  
 145  
 146  sub prompt ($;$) {
 147      my($mess, $def) = @_;
 148      Carp::confess("prompt function called without an argument") 
 149          unless defined $mess;
 150  
 151      my $isa_tty = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ;
 152  
 153      my $dispdef = defined $def ? "[$def] " : " ";
 154      $def = defined $def ? $def : "";
 155  
 156      local $|=1;
 157      local $\;
 158      print "$mess $dispdef";
 159  
 160      my $ans;
 161      if ($ENV{PERL_MM_USE_DEFAULT} || (!$isa_tty && eof STDIN)) {
 162          print "$def\n";
 163      }
 164      else {
 165          $ans = <STDIN>;
 166          if( defined $ans ) {
 167              chomp $ans;
 168          }
 169          else { # user hit ctrl-D
 170              print "\n";
 171          }
 172      }
 173  
 174      return (!defined $ans || $ans eq '') ? $def : $ans;
 175  }
 176  
 177  sub eval_in_subdirs {
 178      my($self) = @_;
 179      use Cwd qw(cwd abs_path);
 180      my $pwd = cwd() || die "Can't figure out your cwd!";
 181  
 182      local @INC = map eval {abs_path($_) if -e} || $_, @INC;
 183      push @INC, '.';     # '.' has to always be at the end of @INC
 184  
 185      foreach my $dir (@{$self->{DIR}}){
 186          my($abs) = $self->catdir($pwd,$dir);
 187          eval { $self->eval_in_x($abs); };
 188          last if $@;
 189      }
 190      chdir $pwd;
 191      die $@ if $@;
 192  }
 193  
 194  sub eval_in_x {
 195      my($self,$dir) = @_;
 196      chdir $dir or Carp::carp("Couldn't change to directory $dir: $!");
 197  
 198      {
 199          package main;
 200          do './Makefile.PL';
 201      };
 202      if ($@) {
 203  #         if ($@ =~ /prerequisites/) {
 204  #             die "MakeMaker WARNING: $@";
 205  #         } else {
 206  #             warn "WARNING from evaluation of $dir/Makefile.PL: $@";
 207  #         }
 208          die "ERROR from evaluation of $dir/Makefile.PL: $@";
 209      }
 210  }
 211  
 212  
 213  # package name for the classes into which the first object will be blessed
 214  my $PACKNAME = 'PACK000';
 215  
 216  sub full_setup {
 217      $Verbose ||= 0;
 218  
 219      my @attrib_help = qw/
 220  
 221      AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION
 222      C CAPI CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DL_FUNCS DL_VARS
 223      EXCLUDE_EXT EXE_FILES EXTRA_META FIRST_MAKEFILE
 224      FULLPERL FULLPERLRUN FULLPERLRUNINST
 225      FUNCLIST H IMPORTS
 226  
 227      INST_ARCHLIB INST_SCRIPT INST_BIN INST_LIB INST_MAN1DIR INST_MAN3DIR
 228      INSTALLDIRS
 229      DESTDIR PREFIX INSTALL_BASE
 230      PERLPREFIX      SITEPREFIX      VENDORPREFIX
 231      INSTALLPRIVLIB  INSTALLSITELIB  INSTALLVENDORLIB
 232      INSTALLARCHLIB  INSTALLSITEARCH INSTALLVENDORARCH
 233      INSTALLBIN      INSTALLSITEBIN  INSTALLVENDORBIN
 234      INSTALLMAN1DIR          INSTALLMAN3DIR
 235      INSTALLSITEMAN1DIR      INSTALLSITEMAN3DIR
 236      INSTALLVENDORMAN1DIR    INSTALLVENDORMAN3DIR
 237      INSTALLSCRIPT   INSTALLSITESCRIPT  INSTALLVENDORSCRIPT
 238      PERL_LIB        PERL_ARCHLIB 
 239      SITELIBEXP      SITEARCHEXP 
 240  
 241      INC INCLUDE_EXT LDFROM LIB LIBPERL_A LIBS LICENSE
 242      LINKTYPE MAKE MAKEAPERL MAKEFILE MAKEFILE_OLD MAN1PODS MAN3PODS MAP_TARGET 
 243      MYEXTLIB NAME NEEDS_LINKING NOECHO NO_META NORECURS NO_VC OBJECT OPTIMIZE 
 244      PERL_MALLOC_OK PERL PERLMAINCC PERLRUN PERLRUNINST PERL_CORE
 245      PERL_SRC PERM_RW PERM_RWX
 246      PL_FILES PM PM_FILTER PMLIBDIRS PMLIBPARENTDIRS POLLUTE PPM_INSTALL_EXEC
 247      PPM_INSTALL_SCRIPT PREREQ_FATAL PREREQ_PM PREREQ_PRINT PRINT_PREREQ
 248      SIGN SKIP TYPEMAPS VERSION VERSION_FROM XS XSOPT XSPROTOARG
 249      XS_VERSION clean depend dist dynamic_lib linkext macro realclean
 250      tool_autosplit
 251  
 252      MACPERL_SRC MACPERL_LIB MACLIBS_68K MACLIBS_PPC MACLIBS_SC MACLIBS_MRC
 253      MACLIBS_ALL_68K MACLIBS_ALL_PPC MACLIBS_SHARED
 254          /;
 255  
 256      # IMPORTS is used under OS/2 and Win32
 257  
 258      # @Overridable is close to @MM_Sections but not identical.  The
 259      # order is important. Many subroutines declare macros. These
 260      # depend on each other. Let's try to collect the macros up front,
 261      # then pasthru, then the rules.
 262  
 263      # MM_Sections are the sections we have to call explicitly
 264      # in Overridable we have subroutines that are used indirectly
 265  
 266  
 267      @MM_Sections = 
 268          qw(
 269  
 270   post_initialize const_config constants platform_constants 
 271   tool_autosplit tool_xsubpp tools_other 
 272  
 273   makemakerdflt
 274  
 275   dist macro depend cflags const_loadlibs const_cccmd
 276   post_constants
 277  
 278   pasthru
 279  
 280   special_targets
 281   c_o xs_c xs_o
 282   top_targets blibdirs linkext dlsyms dynamic dynamic_bs
 283   dynamic_lib static static_lib manifypods processPL
 284   installbin subdirs
 285   clean_subdirs clean realclean_subdirs realclean 
 286   metafile signature
 287   dist_basics dist_core distdir dist_test dist_ci distmeta distsignature
 288   install force perldepend makefile staticmake test ppd
 289  
 290            ); # loses section ordering
 291  
 292      @Overridable = @MM_Sections;
 293      push @Overridable, qw[
 294  
 295   libscan makeaperl needs_linking perm_rw perm_rwx
 296   subdir_x test_via_harness test_via_script 
 297  
 298   init_VERSION init_dist init_INST init_INSTALL init_DEST init_dirscan
 299   init_PM init_MANPODS init_xs init_PERL init_DIRFILESEP init_linker
 300                           ];
 301  
 302      push @MM_Sections, qw[
 303  
 304   pm_to_blib selfdocument
 305  
 306                           ];
 307  
 308      # Postamble needs to be the last that was always the case
 309      push @MM_Sections, "postamble";
 310      push @Overridable, "postamble";
 311  
 312      # All sections are valid keys.
 313      @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
 314  
 315      # we will use all these variables in the Makefile
 316      @Get_from_Config = 
 317          qw(
 318             ar cc cccdlflags ccdlflags dlext dlsrc exe_ext full_ar ld 
 319             lddlflags ldflags libc lib_ext obj_ext osname osvers ranlib 
 320             sitelibexp sitearchexp so
 321            );
 322  
 323      # 5.5.3 doesn't have any concept of vendor libs
 324      push @Get_from_Config, qw( vendorarchexp vendorlibexp ) if $] >= 5.006;
 325  
 326      foreach my $item (@attrib_help){
 327          $Recognized_Att_Keys{$item} = 1;
 328      }
 329      foreach my $item (@Get_from_Config) {
 330          $Recognized_Att_Keys{uc $item} = $Config{$item};
 331          print "Attribute '\U$item\E' => '$Config{$item}'\n"
 332              if ($Verbose >= 2);
 333      }
 334  
 335      #
 336      # When we eval a Makefile.PL in a subdirectory, that one will ask
 337      # us (the parent) for the values and will prepend "..", so that
 338      # all files to be installed end up below OUR ./blib
 339      #
 340      @Prepend_parent = qw(
 341             INST_BIN INST_LIB INST_ARCHLIB INST_SCRIPT
 342             MAP_TARGET INST_MAN1DIR INST_MAN3DIR PERL_SRC
 343             PERL FULLPERL
 344      );
 345  }
 346  
 347  sub writeMakefile {
 348      die <<END;
 349  
 350  The extension you are trying to build apparently is rather old and
 351  most probably outdated. We detect that from the fact, that a
 352  subroutine "writeMakefile" is called, and this subroutine is not
 353  supported anymore since about October 1994.
 354  
 355  Please contact the author or look into CPAN (details about CPAN can be
 356  found in the FAQ and at http:/www.perl.com) for a more recent version
 357  of the extension. If you're really desperate, you can try to change
 358  the subroutine name from writeMakefile to WriteMakefile and rerun
 359  'perl Makefile.PL', but you're most probably left alone, when you do
 360  so.
 361  
 362  The MakeMaker team
 363  
 364  END
 365  }
 366  
 367  sub new {
 368      my($class,$self) = @_;
 369      my($key);
 370  
 371      # Store the original args passed to WriteMakefile()
 372      foreach my $k (keys %$self) {
 373          $self->{ARGS}{$k} = $self->{$k};
 374      }
 375  
 376      if ("@ARGV" =~ /\bPREREQ_PRINT\b/) {
 377          require Data::Dumper;
 378          print Data::Dumper->Dump([$self->{PREREQ_PM}], [qw(PREREQ_PM)]);
 379          exit 0;
 380      }
 381  
 382      # PRINT_PREREQ is RedHatism.
 383      if ("@ARGV" =~ /\bPRINT_PREREQ\b/) {
 384          print join(" ", map { "perl($_)>=$self->{PREREQ_PM}->{$_} " } 
 385                          sort keys %{$self->{PREREQ_PM}}), "\n";
 386          exit 0;
 387     }
 388  
 389      print STDOUT "MakeMaker (v$VERSION)\n" if $Verbose;
 390      if (-f "MANIFEST" && ! -f "Makefile"){
 391          check_manifest();
 392      }
 393  
 394      $self = {} unless (defined $self);
 395  
 396      check_hints($self);
 397  
 398      my %configure_att;         # record &{$self->{CONFIGURE}} attributes
 399      my(%initial_att) = %$self; # record initial attributes
 400  
 401      my(%unsatisfied) = ();
 402      foreach my $prereq (sort keys %{$self->{PREREQ_PM}}) {
 403          # 5.8.0 has a bug with require Foo::Bar alone in an eval, so an
 404          # extra statement is a workaround.
 405          my $file = "$prereq.pm";
 406          $file =~ s{::}{/}g;
 407          eval { require $file };
 408  
 409          my $pr_version = $prereq->VERSION || 0;
 410  
 411          # convert X.Y_Z alpha version #s to X.YZ for easier comparisons
 412          $pr_version =~ s/(\d+)\.(\d+)_(\d+)/$1.$2$3/;
 413  
 414          if ($@) {
 415              warn sprintf "Warning: prerequisite %s %s not found.\n", 
 416                $prereq, $self->{PREREQ_PM}{$prereq} 
 417                     unless $self->{PREREQ_FATAL};
 418              $unsatisfied{$prereq} = 'not installed';
 419          } elsif ($pr_version < $self->{PREREQ_PM}->{$prereq} ){
 420              warn sprintf "Warning: prerequisite %s %s not found. We have %s.\n",
 421                $prereq, $self->{PREREQ_PM}{$prereq}, 
 422                  ($pr_version || 'unknown version') 
 423                    unless $self->{PREREQ_FATAL};
 424              $unsatisfied{$prereq} = $self->{PREREQ_PM}->{$prereq} ? 
 425                $self->{PREREQ_PM}->{$prereq} : 'unknown version' ;
 426          }
 427      }
 428      
 429       if (%unsatisfied && $self->{PREREQ_FATAL}){
 430          my $failedprereqs = join "\n", map {"    $_ $unsatisfied{$_}"} 
 431                              sort { $a cmp $b } keys %unsatisfied;
 432          die <<"END";
 433  MakeMaker FATAL: prerequisites not found.
 434  $failedprereqs
 435  
 436  Please install these modules first and rerun 'perl Makefile.PL'.
 437  END
 438      }
 439      
 440      if (defined $self->{CONFIGURE}) {
 441          if (ref $self->{CONFIGURE} eq 'CODE') {
 442              %configure_att = %{&{$self->{CONFIGURE}}};
 443              $self = { %$self, %configure_att };
 444          } else {
 445              Carp::croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
 446          }
 447      }
 448  
 449      # This is for old Makefiles written pre 5.00, will go away
 450      if ( Carp::longmess("") =~ /runsubdirpl/s ){
 451          Carp::carp("WARNING: Please rerun 'perl Makefile.PL' to regenerate your Makefiles\n");
 452      }
 453  
 454      my $newclass = ++$PACKNAME;
 455      local @Parent = @Parent;    # Protect against non-local exits
 456      {
 457          no strict 'refs';
 458          print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
 459          mv_all_methods("MY",$newclass);
 460          bless $self, $newclass;
 461          push @Parent, $self;
 462          require ExtUtils::MY;
 463          @{"$newclass\:\:ISA"} = 'MM';
 464      }
 465  
 466      if (defined $Parent[-2]){
 467          $self->{PARENT} = $Parent[-2];
 468          my $key;
 469          for $key (@Prepend_parent) {
 470              next unless defined $self->{PARENT}{$key};
 471  
 472              # Don't stomp on WriteMakefile() args.
 473              next if defined $self->{ARGS}{$key} and
 474                      $self->{ARGS}{$key} eq $self->{$key};
 475  
 476              $self->{$key} = $self->{PARENT}{$key};
 477  
 478              unless ($Is_VMS && $key =~ /PERL$/) {
 479                  $self->{$key} = $self->catdir("..",$self->{$key})
 480                    unless $self->file_name_is_absolute($self->{$key});
 481              } else {
 482                  # PERL or FULLPERL will be a command verb or even a
 483                  # command with an argument instead of a full file
 484                  # specification under VMS.  So, don't turn the command
 485                  # into a filespec, but do add a level to the path of
 486                  # the argument if not already absolute.
 487                  my @cmd = split /\s+/, $self->{$key};
 488                  $cmd[1] = $self->catfile('[-]',$cmd[1])
 489                    unless (@cmd < 2) || $self->file_name_is_absolute($cmd[1]);
 490                  $self->{$key} = join(' ', @cmd);
 491              }
 492          }
 493          if ($self->{PARENT}) {
 494              $self->{PARENT}->{CHILDREN}->{$newclass} = $self;
 495              foreach my $opt (qw(POLLUTE PERL_CORE LINKTYPE)) {
 496                  if (exists $self->{PARENT}->{$opt}
 497                      and not exists $self->{$opt})
 498                      {
 499                          # inherit, but only if already unspecified
 500                          $self->{$opt} = $self->{PARENT}->{$opt};
 501                      }
 502              }
 503          }
 504          my @fm = grep /^FIRST_MAKEFILE=/, @ARGV;
 505          parse_args($self,@fm) if @fm;
 506      } else {
 507          parse_args($self,split(' ', $ENV{PERL_MM_OPT} || ''),@ARGV);
 508      }
 509  
 510  
 511      $self->{NAME} ||= $self->guess_name;
 512  
 513      ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
 514  
 515      $self->init_MAKE;
 516      $self->init_main;
 517      $self->init_VERSION;
 518      $self->init_dist;
 519      $self->init_INST;
 520      $self->init_INSTALL;
 521      $self->init_DEST;
 522      $self->init_dirscan;
 523      $self->init_PM;
 524      $self->init_MANPODS;
 525      $self->init_xs;
 526      $self->init_PERL;
 527      $self->init_DIRFILESEP;
 528      $self->init_linker;
 529      $self->init_ABSTRACT;
 530  
 531      if (! $self->{PERL_SRC} ) {
 532          require VMS::Filespec if $Is_VMS;
 533          my($pthinks) = $self->canonpath($INC{'Config.pm'});
 534          my($cthinks) = $self->catfile($Config{'archlibexp'},'Config.pm');
 535          $pthinks = VMS::Filespec::vmsify($pthinks) if $Is_VMS;
 536          if ($pthinks ne $cthinks &&
 537              !($Is_Win32 and lc($pthinks) eq lc($cthinks))) {
 538              print "Have $pthinks expected $cthinks\n";
 539              if ($Is_Win32) {
 540                  $pthinks =~ s![/\\]Config\.pm$!!i; $pthinks =~ s!.*[/\\]!!;
 541              }
 542              else {
 543                  $pthinks =~ s!/Config\.pm$!!; $pthinks =~ s!.*/!!;
 544              }
 545              print STDOUT <<END unless $self->{UNINSTALLED_PERL};
 546  Your perl and your Config.pm seem to have different ideas about the 
 547  architecture they are running on.
 548  Perl thinks: [$pthinks]
 549  Config says: [$Config{archname}]
 550  This may or may not cause problems. Please check your installation of perl 
 551  if you have problems building this extension.
 552  END
 553          }
 554      }
 555  
 556      $self->init_others();
 557      $self->init_platform();
 558      $self->init_PERM();
 559      my($argv) = neatvalue(\@ARGV);
 560      $argv =~ s/^\[/(/;
 561      $argv =~ s/\]$/)/;
 562  
 563      push @{$self->{RESULT}}, <<END;
 564  # This Makefile is for the $self->{NAME} extension to perl.
 565  #
 566  # It was generated automatically by MakeMaker version
 567  # $VERSION (Revision: $Revision) from the contents of
 568  # Makefile.PL. Don't edit this file, edit Makefile.PL instead.
 569  #
 570  #       ANY CHANGES MADE HERE WILL BE LOST!
 571  #
 572  #   MakeMaker ARGV: $argv
 573  #
 574  #   MakeMaker Parameters:
 575  END
 576  
 577      foreach my $key (sort keys %initial_att){
 578          next if $key eq 'ARGS';
 579  
 580          my($v) = neatvalue($initial_att{$key});
 581          $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
 582          $v =~ tr/\n/ /s;
 583          push @{$self->{RESULT}}, "#     $key => $v";
 584      }
 585      undef %initial_att;        # free memory
 586  
 587      if (defined $self->{CONFIGURE}) {
 588         push @{$self->{RESULT}}, <<END;
 589  
 590  #   MakeMaker 'CONFIGURE' Parameters:
 591  END
 592          if (scalar(keys %configure_att) > 0) {
 593              foreach my $key (sort keys %configure_att){
 594                 next if $key eq 'ARGS';
 595                 my($v) = neatvalue($configure_att{$key});
 596                 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
 597                 $v =~ tr/\n/ /s;
 598                 push @{$self->{RESULT}}, "#     $key => $v";
 599              }
 600          }
 601          else
 602          {
 603             push @{$self->{RESULT}}, "# no values returned";
 604          }
 605          undef %configure_att;  # free memory
 606      }
 607  
 608      # turn the SKIP array into a SKIPHASH hash
 609      my (%skip,$skip);
 610      for $skip (@{$self->{SKIP} || []}) {
 611          $self->{SKIPHASH}{$skip} = 1;
 612      }
 613      delete $self->{SKIP}; # free memory
 614  
 615      if ($self->{PARENT}) {
 616          for (qw/install dist dist_basics dist_core distdir dist_test dist_ci/) {
 617              $self->{SKIPHASH}{$_} = 1;
 618          }
 619      }
 620  
 621      # We run all the subdirectories now. They don't have much to query
 622      # from the parent, but the parent has to query them: if they need linking!
 623      unless ($self->{NORECURS}) {
 624          $self->eval_in_subdirs if @{$self->{DIR}};
 625      }
 626  
 627      foreach my $section ( @MM_Sections ){
 628          # Support for new foo_target() methods.
 629          my $method = $section;
 630          $method .= '_target' unless $self->can($method);
 631  
 632          print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
 633          my($skipit) = $self->skipcheck($section);
 634          if ($skipit){
 635              push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
 636          } else {
 637              my(%a) = %{$self->{$section} || {}};
 638              push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
 639              push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
 640              push @{$self->{RESULT}}, $self->maketext_filter(
 641                  $self->$method( %a )
 642              );
 643          }
 644      }
 645  
 646      push @{$self->{RESULT}}, "\n# End.";
 647  
 648      $self;
 649  }
 650  
 651  sub WriteEmptyMakefile {
 652      Carp::croak "WriteEmptyMakefile: Need an even number of args" if @_ % 2;
 653  
 654      my %att = @_;
 655      my $self = MM->new(\%att);
 656      
 657      my $new = $self->{MAKEFILE};
 658      my $old = $self->{MAKEFILE_OLD};
 659      if (-f $old) {
 660          _unlink($old) or warn "unlink $old: $!";
 661      }
 662      if ( -f $new ) {
 663          _rename($new, $old) or warn "rename $new => $old: $!"
 664      }
 665      open MF, '>'.$new or die "open $new for write: $!";
 666      print MF <<'EOP';
 667  all :
 668  
 669  clean :
 670  
 671  install :
 672  
 673  makemakerdflt :
 674  
 675  test :
 676  
 677  EOP
 678      close MF or die "close $new for write: $!";
 679  }
 680  
 681  sub check_manifest {
 682      print STDOUT "Checking if your kit is complete...\n";
 683      require ExtUtils::Manifest;
 684      # avoid warning
 685      $ExtUtils::Manifest::Quiet = $ExtUtils::Manifest::Quiet = 1;
 686      my(@missed) = ExtUtils::Manifest::manicheck();
 687      if (@missed) {
 688          print STDOUT "Warning: the following files are missing in your kit:\n";
 689          print "\t", join "\n\t", @missed;
 690          print STDOUT "\n";
 691          print STDOUT "Please inform the author.\n";
 692      } else {
 693          print STDOUT "Looks good\n";
 694      }
 695  }
 696  
 697  sub parse_args{
 698      my($self, @args) = @_;
 699      foreach (@args) {
 700          unless (m/(.*?)=(.*)/) {
 701              ++$Verbose if m/^verb/;
 702              next;
 703          }
 704          my($name, $value) = ($1, $2);
 705          if ($value =~ m/^~(\w+)?/) { # tilde with optional username
 706              $value =~ s [^~(\w*)]
 707                  [$1 ?
 708                   ((getpwnam($1))[7] || "~$1") :
 709                   (getpwuid($>))[7]
 710                   ]ex;
 711          }
 712  
 713          # Remember the original args passed it.  It will be useful later.
 714          $self->{ARGS}{uc $name} = $self->{uc $name} = $value;
 715      }
 716  
 717      # catch old-style 'potential_libs' and inform user how to 'upgrade'
 718      if (defined $self->{potential_libs}){
 719          my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
 720          if ($self->{potential_libs}){
 721              print STDOUT "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
 722          } else {
 723              print STDOUT "$msg deleted.\n";
 724          }
 725          $self->{LIBS} = [$self->{potential_libs}];
 726          delete $self->{potential_libs};
 727      }
 728      # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
 729      if (defined $self->{ARMAYBE}){
 730          my($armaybe) = $self->{ARMAYBE};
 731          print STDOUT "ARMAYBE => '$armaybe' should be changed to:\n",
 732                          "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
 733          my(%dl) = %{$self->{dynamic_lib} || {}};
 734          $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
 735          delete $self->{ARMAYBE};
 736      }
 737      if (defined $self->{LDTARGET}){
 738          print STDOUT "LDTARGET should be changed to LDFROM\n";
 739          $self->{LDFROM} = $self->{LDTARGET};
 740          delete $self->{LDTARGET};
 741      }
 742      # Turn a DIR argument on the command line into an array
 743      if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
 744          # So they can choose from the command line, which extensions they want
 745          # the grep enables them to have some colons too much in case they
 746          # have to build a list with the shell
 747          $self->{DIR} = [grep $_, split ":", $self->{DIR}];
 748      }
 749      # Turn a INCLUDE_EXT argument on the command line into an array
 750      if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
 751          $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
 752      }
 753      # Turn a EXCLUDE_EXT argument on the command line into an array
 754      if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
 755          $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
 756      }
 757  
 758      foreach my $mmkey (sort keys %$self){
 759          next if $mmkey eq 'ARGS';
 760          print STDOUT "  $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
 761          print STDOUT "'$mmkey' is not a known MakeMaker parameter name.\n"
 762              unless exists $Recognized_Att_Keys{$mmkey};
 763      }
 764      $| = 1 if $Verbose;
 765  }
 766  
 767  sub check_hints {
 768      my($self) = @_;
 769      # We allow extension-specific hints files.
 770  
 771      require File::Spec;
 772      my $curdir = File::Spec->curdir;
 773  
 774      my $hint_dir = File::Spec->catdir($curdir, "hints");
 775      return unless -d $hint_dir;
 776  
 777      # First we look for the best hintsfile we have
 778      my($hint)="${^O}_$Config{osvers}";
 779      $hint =~ s/\./_/g;
 780      $hint =~ s/_$//;
 781      return unless $hint;
 782  
 783      # Also try without trailing minor version numbers.
 784      while (1) {
 785          last if -f File::Spec->catfile($hint_dir, "$hint.pl");  # found
 786      } continue {
 787          last unless $hint =~ s/_[^_]*$//; # nothing to cut off
 788      }
 789      my $hint_file = File::Spec->catfile($hint_dir, "$hint.pl");
 790  
 791      return unless -f $hint_file;    # really there
 792  
 793      _run_hintfile($self, $hint_file);
 794  }
 795  
 796  sub _run_hintfile {
 797      no strict 'vars';
 798      local($self) = shift;       # make $self available to the hint file.
 799      my($hint_file) = shift;
 800  
 801      local($@, $!);
 802      print STDERR "Processing hints file $hint_file\n";
 803  
 804      # Just in case the ./ isn't on the hint file, which File::Spec can
 805      # often strip off, we bung the curdir into @INC
 806      local @INC = (File::Spec->curdir, @INC);
 807      my $ret = do $hint_file;
 808      if( !defined $ret ) {
 809          my $error = $@ || $!;
 810          print STDERR $error;
 811      }
 812  }
 813  
 814  sub mv_all_methods {
 815      my($from,$to) = @_;
 816      no strict 'refs';
 817      my($symtab) = \%{"$from}::"};
 818  
 819      # Here you see the *current* list of methods that are overridable
 820      # from Makefile.PL via MY:: subroutines. As of VERSION 5.07 I'm
 821      # still trying to reduce the list to some reasonable minimum --
 822      # because I want to make it easier for the user. A.K.
 823  
 824      local $SIG{__WARN__} = sub { 
 825          # can't use 'no warnings redefined', 5.6 only
 826          warn @_ unless $_[0] =~ /^Subroutine .* redefined/ 
 827      };
 828      foreach my $method (@Overridable) {
 829  
 830          # We cannot say "next" here. Nick might call MY->makeaperl
 831          # which isn't defined right now
 832  
 833          # Above statement was written at 4.23 time when Tk-b8 was
 834          # around. As Tk-b9 only builds with 5.002something and MM 5 is
 835          # standard, we try to enable the next line again. It was
 836          # commented out until MM 5.23
 837  
 838          next unless defined &{"$from}::$method"};
 839  
 840          *{"$to}::$method"} = \&{"$from}::$method"};
 841  
 842          # delete would do, if we were sure, nobody ever called
 843          # MY->makeaperl directly
 844  
 845          # delete $symtab->{$method};
 846  
 847          # If we delete a method, then it will be undefined and cannot
 848          # be called.  But as long as we have Makefile.PLs that rely on
 849          # %MY:: being intact, we have to fill the hole with an
 850          # inheriting method:
 851  
 852          eval "package MY; sub $method { shift->SUPER::$method(\@_); }";
 853      }
 854  
 855      # We have to clean out %INC also, because the current directory is
 856      # changed frequently and Graham Barr prefers to get his version
 857      # out of a History.pl file which is "required" so woudn't get
 858      # loaded again in another extension requiring a History.pl
 859  
 860      # With perl5.002_01 the deletion of entries in %INC caused Tk-b11
 861      # to core dump in the middle of a require statement. The required
 862      # file was Tk/MMutil.pm.  The consequence is, we have to be
 863      # extremely careful when we try to give perl a reason to reload a
 864      # library with same name.  The workaround prefers to drop nothing
 865      # from %INC and teach the writers not to use such libraries.
 866  
 867  #    my $inc;
 868  #    foreach $inc (keys %INC) {
 869  #       #warn "***$inc*** deleted";
 870  #       delete $INC{$inc};
 871  #    }
 872  }
 873  
 874  sub skipcheck {
 875      my($self) = shift;
 876      my($section) = @_;
 877      if ($section eq 'dynamic') {
 878          print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
 879          "in skipped section 'dynamic_bs'\n"
 880              if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
 881          print STDOUT "Warning (non-fatal): Target 'dynamic' depends on targets ",
 882          "in skipped section 'dynamic_lib'\n"
 883              if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
 884      }
 885      if ($section eq 'dynamic_lib') {
 886          print STDOUT "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
 887          "targets in skipped section 'dynamic_bs'\n"
 888              if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
 889      }
 890      if ($section eq 'static') {
 891          print STDOUT "Warning (non-fatal): Target 'static' depends on targets ",
 892          "in skipped section 'static_lib'\n"
 893              if $self->{SKIPHASH}{static_lib} && $Verbose;
 894      }
 895      return 'skipped' if $self->{SKIPHASH}{$section};
 896      return '';
 897  }
 898  
 899  sub flush {
 900      my $self = shift;
 901      my($chunk);
 902      local *FH;
 903  
 904      my $finalname = $self->{MAKEFILE};
 905      print STDOUT "Writing $finalname for $self->{NAME}\n";
 906  
 907      unlink($finalname, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : ());
 908      open(FH,">MakeMaker.tmp") or die "Unable to open MakeMaker.tmp: $!";
 909  
 910      for $chunk (@{$self->{RESULT}}) {
 911          print FH "$chunk\n";
 912      }
 913  
 914      close FH;
 915      _rename("MakeMaker.tmp", $finalname) or
 916        warn "rename MakeMaker.tmp => $finalname: $!";
 917      chmod 0644, $finalname unless $Is_VMS;
 918  
 919      my %keep = map { ($_ => 1) } qw(NEEDS_LINKING HAS_LINK_CODE);
 920  
 921      if ($self->{PARENT} && !$self->{_KEEP_AFTER_FLUSH}) {
 922          foreach (keys %$self) { # safe memory
 923              delete $self->{$_} unless $keep{$_};
 924          }
 925      }
 926  
 927      system("$Config::Config{eunicefix} $finalname") unless $Config::Config{eunicefix} eq ":";
 928  }
 929  
 930  
 931  # This is a rename for OS's where the target must be unlinked first.
 932  sub _rename {
 933      my($src, $dest) = @_;
 934      chmod 0666, $dest;
 935      unlink $dest;
 936      return rename $src, $dest;
 937  }
 938  
 939  # This is an unlink for OS's where the target must be writable first.
 940  sub _unlink {
 941      my @files = @_;
 942      chmod 0666, @files;
 943      return unlink @files;
 944  }
 945  
 946  
 947  # The following mkbootstrap() is only for installations that are calling
 948  # the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
 949  # writes Makefiles, that use ExtUtils::Mkbootstrap directly.
 950  sub mkbootstrap {
 951      die <<END;
 952  !!! Your Makefile has been built such a long time ago, !!!
 953  !!! that is unlikely to work with current MakeMaker.   !!!
 954  !!! Please rebuild your Makefile                       !!!
 955  END
 956  }
 957  
 958  # Ditto for mksymlists() as of MakeMaker 5.17
 959  sub mksymlists {
 960      die <<END;
 961  !!! Your Makefile has been built such a long time ago, !!!
 962  !!! that is unlikely to work with current MakeMaker.   !!!
 963  !!! Please rebuild your Makefile                       !!!
 964  END
 965  }
 966  
 967  sub neatvalue {
 968      my($v) = @_;
 969      return "undef" unless defined $v;
 970      my($t) = ref $v;
 971      return "q[$v]" unless $t;
 972      if ($t eq 'ARRAY') {
 973          my(@m, @neat);
 974          push @m, "[";
 975          foreach my $elem (@$v) {
 976              push @neat, "q[$elem]";
 977          }
 978          push @m, join ", ", @neat;
 979          push @m, "]";
 980          return join "", @m;
 981      }
 982      return "$v" unless $t eq 'HASH';
 983      my(@m, $key, $val);
 984      while (($key,$val) = each %$v){
 985          last unless defined $key; # cautious programming in case (undef,undef) is true
 986          push(@m,"$key=>".neatvalue($val)) ;
 987      }
 988      return "{ ".join(', ',@m)." }";
 989  }
 990  
 991  sub selfdocument {
 992      my($self) = @_;
 993      my(@m);
 994      if ($Verbose){
 995          push @m, "\n# Full list of MakeMaker attribute values:";
 996          foreach my $key (sort keys %$self){
 997              next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
 998              my($v) = neatvalue($self->{$key});
 999              $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
1000              $v =~ tr/\n/ /s;
1001              push @m, "# $key => $v";
1002          }
1003      }
1004      join "\n", @m;
1005  }
1006  
1007  1;
1008  
1009  __END__
1010  
1011  =head1 NAME
1012  
1013  ExtUtils::MakeMaker - Create a module Makefile
1014  
1015  =head1 SYNOPSIS
1016  
1017    use ExtUtils::MakeMaker;
1018  
1019    WriteMakefile( ATTRIBUTE => VALUE [, ...] );
1020  
1021  =head1 DESCRIPTION
1022  
1023  This utility is designed to write a Makefile for an extension module
1024  from a Makefile.PL. It is based on the Makefile.SH model provided by
1025  Andy Dougherty and the perl5-porters.
1026  
1027  It splits the task of generating the Makefile into several subroutines
1028  that can be individually overridden.  Each subroutine returns the text
1029  it wishes to have written to the Makefile.
1030  
1031  MakeMaker is object oriented. Each directory below the current
1032  directory that contains a Makefile.PL is treated as a separate
1033  object. This makes it possible to write an unlimited number of
1034  Makefiles with a single invocation of WriteMakefile().
1035  
1036  =head2 How To Write A Makefile.PL
1037  
1038  See ExtUtils::MakeMaker::Tutorial.
1039  
1040  The long answer is the rest of the manpage :-)
1041  
1042  =head2 Default Makefile Behaviour
1043  
1044  The generated Makefile enables the user of the extension to invoke
1045  
1046    perl Makefile.PL # optionally "perl Makefile.PL verbose"
1047    make
1048    make test        # optionally set TEST_VERBOSE=1
1049    make install     # See below
1050  
1051  The Makefile to be produced may be altered by adding arguments of the
1052  form C<KEY=VALUE>. E.g.
1053  
1054    perl Makefile.PL INSTALL_BASE=~
1055  
1056  Other interesting targets in the generated Makefile are
1057  
1058    make config     # to check if the Makefile is up-to-date
1059    make clean      # delete local temp files (Makefile gets renamed)
1060    make realclean  # delete derived files (including ./blib)
1061    make ci         # check in all the files in the MANIFEST file
1062    make dist       # see below the Distribution Support section
1063  
1064  =head2 make test
1065  
1066  MakeMaker checks for the existence of a file named F<test.pl> in the
1067  current directory and if it exists it execute the script with the
1068  proper set of perl C<-I> options.
1069  
1070  MakeMaker also checks for any files matching glob("t/*.t"). It will
1071  execute all matching files in alphabetical order via the
1072  L<Test::Harness> module with the C<-I> switches set correctly.
1073  
1074  If you'd like to see the raw output of your tests, set the
1075  C<TEST_VERBOSE> variable to true.
1076  
1077    make test TEST_VERBOSE=1
1078  
1079  =head2 make testdb
1080  
1081  A useful variation of the above is the target C<testdb>. It runs the
1082  test under the Perl debugger (see L<perldebug>). If the file
1083  F<test.pl> exists in the current directory, it is used for the test.
1084  
1085  If you want to debug some other testfile, set the C<TEST_FILE> variable
1086  thusly:
1087  
1088    make testdb TEST_FILE=t/mytest.t
1089  
1090  By default the debugger is called using C<-d> option to perl. If you
1091  want to specify some other option, set the C<TESTDB_SW> variable:
1092  
1093    make testdb TESTDB_SW=-Dx
1094  
1095  =head2 make install
1096  
1097  make alone puts all relevant files into directories that are named by
1098  the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
1099  INST_MAN3DIR.  All these default to something below ./blib if you are
1100  I<not> building below the perl source directory. If you I<are>
1101  building below the perl source, INST_LIB and INST_ARCHLIB default to
1102  ../../lib, and INST_SCRIPT is not defined.
1103  
1104  The I<install> target of the generated Makefile copies the files found
1105  below each of the INST_* directories to their INSTALL*
1106  counterparts. Which counterparts are chosen depends on the setting of
1107  INSTALLDIRS according to the following table:
1108  
1109                                   INSTALLDIRS set to
1110                             perl        site          vendor
1111  
1112                   PERLPREFIX      SITEPREFIX          VENDORPREFIX
1113    INST_ARCHLIB   INSTALLARCHLIB  INSTALLSITEARCH     INSTALLVENDORARCH
1114    INST_LIB       INSTALLPRIVLIB  INSTALLSITELIB      INSTALLVENDORLIB
1115    INST_BIN       INSTALLBIN      INSTALLSITEBIN      INSTALLVENDORBIN
1116    INST_SCRIPT    INSTALLSCRIPT   INSTALLSITESCRIPT   INSTALLVENDORSCRIPT
1117    INST_MAN1DIR   INSTALLMAN1DIR  INSTALLSITEMAN1DIR  INSTALLVENDORMAN1DIR
1118    INST_MAN3DIR   INSTALLMAN3DIR  INSTALLSITEMAN3DIR  INSTALLVENDORMAN3DIR
1119  
1120  The INSTALL... macros in turn default to their %Config
1121  ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
1122  
1123  You can check the values of these variables on your system with
1124  
1125      perl '-V:install.*'
1126  
1127  And to check the sequence in which the library directories are
1128  searched by perl, run
1129  
1130      perl -le 'print join $/, @INC'
1131  
1132  Sometimes older versions of the module you're installing live in other
1133  directories in @INC.  Because Perl loads the first version of a module it 
1134  finds, not the newest, you might accidentally get one of these older
1135  versions even after installing a brand new version.  To delete I<all other
1136  versions of the module you're installing> (not simply older ones) set the
1137  C<UNINST> variable.
1138  
1139      make install UNINST=1
1140  
1141  
1142  =head2 INSTALL_BASE
1143  
1144  INSTALL_BASE can be passed into Makefile.PL to change where your
1145  module will be installed.  INSTALL_BASE is more like what everyone
1146  else calls "prefix" than PREFIX is.
1147  
1148  To have everything installed in your home directory, do the following.
1149  
1150      # Unix users, INSTALL_BASE=~ works fine
1151      perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
1152  
1153  Like PREFIX, it sets several INSTALL* attributes at once.  Unlike
1154  PREFIX it is easy to predict where the module will end up.  The
1155  installation pattern looks like this:
1156  
1157      INSTALLARCHLIB     INSTALL_BASE/lib/perl5/$Config{archname}
1158      INSTALLPRIVLIB     INSTALL_BASE/lib/perl5
1159      INSTALLBIN         INSTALL_BASE/bin
1160      INSTALLSCRIPT      INSTALL_BASE/bin
1161      INSTALLMAN1DIR     INSTALL_BASE/man/man1
1162      INSTALLMAN3DIR     INSTALL_BASE/man/man3
1163  
1164  INSTALL_BASE in MakeMaker and C<--install_base> in Module::Build (as
1165  of 0.28) install to the same location.  If you want MakeMaker and
1166  Module::Build to install to the same location simply set INSTALL_BASE
1167  and C<--install_base> to the same location.
1168  
1169  INSTALL_BASE was added in 6.31.
1170  
1171  
1172  =head2 PREFIX and LIB attribute
1173  
1174  PREFIX and LIB can be used to set several INSTALL* attributes in one
1175  go.  Here's an example for installing into your home directory.
1176  
1177      # Unix users, PREFIX=~ works fine
1178      perl Makefile.PL PREFIX=/path/to/your/home/dir
1179  
1180  This will install all files in the module under your home directory,
1181  with man pages and libraries going into an appropriate place (usually
1182  ~/man and ~/lib).  How the exact location is determined is complicated
1183  and depends on how your Perl was configured.  INSTALL_BASE works more
1184  like what other build systems call "prefix" than PREFIX and we
1185  recommend you use that instead.
1186  
1187  Another way to specify many INSTALL directories with a single
1188  parameter is LIB.
1189  
1190      perl Makefile.PL LIB=~/lib
1191  
1192  This will install the module's architecture-independent files into
1193  ~/lib, the architecture-dependent files into ~/lib/$archname.
1194  
1195  Note, that in both cases the tilde expansion is done by MakeMaker, not
1196  by perl by default, nor by make.
1197  
1198  Conflicts between parameters LIB, PREFIX and the various INSTALL*
1199  arguments are resolved so that:
1200  
1201  =over 4
1202  
1203  =item *
1204  
1205  setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
1206  INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
1207  
1208  =item *
1209  
1210  without LIB, setting PREFIX replaces the initial C<$Config{prefix}>
1211  part of those INSTALL* arguments, even if the latter are explicitly
1212  set (but are set to still start with C<$Config{prefix}>).
1213  
1214  =back
1215  
1216  If the user has superuser privileges, and is not working on AFS or
1217  relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
1218  INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
1219  the best:
1220  
1221      perl Makefile.PL; 
1222      make; 
1223      make test
1224      make install
1225  
1226  make install per default writes some documentation of what has been
1227  done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
1228  can be bypassed by calling make pure_install.
1229  
1230  =head2 AFS users
1231  
1232  will have to specify the installation directories as these most
1233  probably have changed since perl itself has been installed. They will
1234  have to do this by calling
1235  
1236      perl Makefile.PL INSTALLSITELIB=/afs/here/today \
1237          INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
1238      make
1239  
1240  Be careful to repeat this procedure every time you recompile an
1241  extension, unless you are sure the AFS installation directories are
1242  still valid.
1243  
1244  =head2 Static Linking of a new Perl Binary
1245  
1246  An extension that is built with the above steps is ready to use on
1247  systems supporting dynamic loading. On systems that do not support
1248  dynamic loading, any newly created extension has to be linked together
1249  with the available resources. MakeMaker supports the linking process
1250  by creating appropriate targets in the Makefile whenever an extension
1251  is built. You can invoke the corresponding section of the makefile with
1252  
1253      make perl
1254  
1255  That produces a new perl binary in the current directory with all
1256  extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP,
1257  and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1258  UNIX, this is called Makefile.aperl (may be system dependent). If you
1259  want to force the creation of a new perl, it is recommended, that you
1260  delete this Makefile.aperl, so the directories are searched-through
1261  for linkable libraries again.
1262  
1263  The binary can be installed into the directory where perl normally
1264  resides on your machine with
1265  
1266      make inst_perl
1267  
1268  To produce a perl binary with a different name than C<perl>, either say
1269  
1270      perl Makefile.PL MAP_TARGET=myperl
1271      make myperl
1272      make inst_perl
1273  
1274  or say
1275  
1276      perl Makefile.PL
1277      make myperl MAP_TARGET=myperl
1278      make inst_perl MAP_TARGET=myperl
1279  
1280  In any case you will be prompted with the correct invocation of the
1281  C<inst_perl> target that installs the new binary into INSTALLBIN.
1282  
1283  make inst_perl per default writes some documentation of what has been
1284  done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1285  can be bypassed by calling make pure_inst_perl.
1286  
1287  Warning: the inst_perl: target will most probably overwrite your
1288  existing perl binary. Use with care!
1289  
1290  Sometimes you might want to build a statically linked perl although
1291  your system supports dynamic loading. In this case you may explicitly
1292  set the linktype with the invocation of the Makefile.PL or make:
1293  
1294      perl Makefile.PL LINKTYPE=static    # recommended
1295  
1296  or
1297  
1298      make LINKTYPE=static                # works on most systems
1299  
1300  =head2 Determination of Perl Library and Installation Locations
1301  
1302  MakeMaker needs to know, or to guess, where certain things are
1303  located.  Especially INST_LIB and INST_ARCHLIB (where to put the files
1304  during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1305  existing modules from), and PERL_INC (header files and C<libperl*.*>).
1306  
1307  Extensions may be built either using the contents of the perl source
1308  directory tree or from the installed perl library. The recommended way
1309  is to build extensions after you have run 'make install' on perl
1310  itself. You can do that in any directory on your hard disk that is not
1311  below the perl source tree. The support for extensions below the ext
1312  directory of the perl distribution is only good for the standard
1313  extensions that come with perl.
1314  
1315  If an extension is being built below the C<ext/> directory of the perl
1316  source then MakeMaker will set PERL_SRC automatically (e.g.,
1317  C<../..>).  If PERL_SRC is defined and the extension is recognized as
1318  a standard extension, then other variables default to the following:
1319  
1320    PERL_INC     = PERL_SRC
1321    PERL_LIB     = PERL_SRC/lib
1322    PERL_ARCHLIB = PERL_SRC/lib
1323    INST_LIB     = PERL_LIB
1324    INST_ARCHLIB = PERL_ARCHLIB
1325  
1326  If an extension is being built away from the perl source then MakeMaker
1327  will leave PERL_SRC undefined and default to using the installed copy
1328  of the perl library. The other variables default to the following:
1329  
1330    PERL_INC     = $archlibexp/CORE
1331    PERL_LIB     = $privlibexp
1332    PERL_ARCHLIB = $archlibexp
1333    INST_LIB     = ./blib/lib
1334    INST_ARCHLIB = ./blib/arch
1335  
1336  If perl has not yet been installed then PERL_SRC can be defined on the
1337  command line as shown in the previous section.
1338  
1339  
1340  =head2 Which architecture dependent directory?
1341  
1342  If you don't want to keep the defaults for the INSTALL* macros,
1343  MakeMaker helps you to minimize the typing needed: the usual
1344  relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1345  by Configure at perl compilation time. MakeMaker supports the user who
1346  sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1347  then MakeMaker defaults the latter to be the same subdirectory of
1348  INSTALLPRIVLIB as Configure decided for the counterparts in %Config ,
1349  otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1350  for INSTALLSITELIB and INSTALLSITEARCH.
1351  
1352  MakeMaker gives you much more freedom than needed to configure
1353  internal variables and get different results. It is worth to mention,
1354  that make(1) also lets you configure most of the variables that are
1355  used in the Makefile. But in the majority of situations this will not
1356  be necessary, and should only be done if the author of a package
1357  recommends it (or you know what you're doing).
1358  
1359  =head2 Using Attributes and Parameters
1360  
1361  The following attributes may be specified as arguments to WriteMakefile()
1362  or as NAME=VALUE pairs on the command line.
1363  
1364  =over 2
1365  
1366  =item ABSTRACT
1367  
1368  One line description of the module. Will be included in PPD file.
1369  
1370  =item ABSTRACT_FROM
1371  
1372  Name of the file that contains the package description. MakeMaker looks
1373  for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1374  the first line in the "=head1 NAME" section. $2 becomes the abstract.
1375  
1376  =item AUTHOR
1377  
1378  String containing name (and email address) of package author(s). Is used
1379  in PPD (Perl Package Description) files for PPM (Perl Package Manager).
1380  
1381  =item BINARY_LOCATION
1382  
1383  Used when creating PPD files for binary packages.  It can be set to a
1384  full or relative path or URL to the binary archive for a particular
1385  architecture.  For example:
1386  
1387          perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
1388  
1389  builds a PPD package that references a binary of the C<Agent> package,
1390  located in the C<x86> directory relative to the PPD itself.
1391  
1392  =item C
1393  
1394  Ref to array of *.c file names. Initialised from a directory scan
1395  and the values portion of the XS attribute hash. This is not
1396  currently used by MakeMaker but may be handy in Makefile.PLs.
1397  
1398  =item CCFLAGS
1399  
1400  String that will be included in the compiler call command line between
1401  the arguments INC and OPTIMIZE.
1402  
1403  =item CONFIG
1404  
1405  Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1406  config.sh. MakeMaker will add to CONFIG the following values anyway:
1407  ar
1408  cc
1409  cccdlflags
1410  ccdlflags
1411  dlext
1412  dlsrc
1413  ld
1414  lddlflags
1415  ldflags
1416  libc
1417  lib_ext
1418  obj_ext
1419  ranlib
1420  sitelibexp
1421  sitearchexp
1422  so
1423  
1424  =item CONFIGURE
1425  
1426  CODE reference. The subroutine should return a hash reference. The
1427  hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
1428  be determined by some evaluation method.
1429  
1430  =item DEFINE
1431  
1432  Something like C<"-DHAVE_UNISTD_H">
1433  
1434  =item DESTDIR
1435  
1436  This is the root directory into which the code will be installed.  It
1437  I<prepends itself to the normal prefix>.  For example, if your code
1438  would normally go into F</usr/local/lib/perl> you could set DESTDIR=~/tmp/
1439  and installation would go into F<~/tmp/usr/local/lib/perl>.
1440  
1441  This is primarily of use for people who repackage Perl modules.
1442  
1443  NOTE: Due to the nature of make, it is important that you put the trailing
1444  slash on your DESTDIR.  F<~/tmp/> not F<~/tmp>.
1445  
1446  =item DIR
1447  
1448  Ref to array of subdirectories containing Makefile.PLs e.g. [ 'sdbm'
1449  ] in ext/SDBM_File
1450  
1451  =item DISTNAME
1452  
1453  A safe filename for the package. 
1454  
1455  Defaults to NAME above but with :: replaced with -.
1456  
1457  For example, Foo::Bar becomes Foo-Bar.
1458  
1459  =item DISTVNAME
1460  
1461  Your name for distributing the package with the version number
1462  included.  This is used by 'make dist' to name the resulting archive
1463  file.
1464  
1465  Defaults to DISTNAME-VERSION.
1466  
1467  For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
1468  
1469  On some OS's where . has special meaning VERSION_SYM may be used in
1470  place of VERSION.
1471  
1472  =item DL_FUNCS
1473  
1474  Hashref of symbol names for routines to be made available as universal
1475  symbols.  Each key/value pair consists of the package name and an
1476  array of routine names in that package.  Used only under AIX, OS/2,
1477  VMS and Win32 at present.  The routine names supplied will be expanded
1478  in the same way as XSUB names are expanded by the XS() macro.
1479  Defaults to
1480  
1481    {"$(NAME)" => ["boot_$(NAME)" ] }
1482  
1483  e.g.
1484  
1485    {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1486     "NetconfigPtr" => [ 'DESTROY'] }
1487  
1488  Please see the L<ExtUtils::Mksymlists> documentation for more information
1489  about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1490  
1491  =item DL_VARS
1492  
1493  Array of symbol names for variables to be made available as universal symbols.
1494  Used only under AIX, OS/2, VMS and Win32 at present.  Defaults to [].
1495  (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
1496  
1497  =item EXCLUDE_EXT
1498  
1499  Array of extension names to exclude when doing a static build.  This
1500  is ignored if INCLUDE_EXT is present.  Consult INCLUDE_EXT for more
1501  details.  (e.g.  [ qw( Socket POSIX ) ] )
1502  
1503  This attribute may be most useful when specified as a string on the
1504  command line:  perl Makefile.PL EXCLUDE_EXT='Socket Safe'
1505  
1506  =item EXE_FILES
1507  
1508  Ref to array of executable files. The files will be copied to the
1509  INST_SCRIPT directory. Make realclean will delete them from there
1510  again.
1511  
1512  If your executables start with something like #!perl or
1513  #!/usr/bin/perl MakeMaker will change this to the path of the perl
1514  'Makefile.PL' was invoked with so the programs will be sure to run
1515  properly even if perl is not in /usr/bin/perl.
1516  
1517  =item FIRST_MAKEFILE
1518  
1519  The name of the Makefile to be produced.  This is used for the second
1520  Makefile that will be produced for the MAP_TARGET.
1521  
1522  Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
1523  
1524  (Note: we couldn't use MAKEFILE because dmake uses this for something
1525  else).
1526  
1527  =item FULLPERL
1528  
1529  Perl binary able to run this extension, load XS modules, etc...
1530  
1531  =item FULLPERLRUN
1532  
1533  Like PERLRUN, except it uses FULLPERL.
1534  
1535  =item FULLPERLRUNINST
1536  
1537  Like PERLRUNINST, except it uses FULLPERL.
1538  
1539  =item FUNCLIST
1540  
1541  This provides an alternate means to specify function names to be
1542  exported from the extension.  Its value is a reference to an
1543  array of function names to be exported by the extension.  These
1544  names are passed through unaltered to the linker options file.
1545  
1546  =item H
1547  
1548  Ref to array of *.h file names. Similar to C.
1549  
1550  =item IMPORTS
1551  
1552  This attribute is used to specify names to be imported into the
1553  extension. Takes a hash ref.
1554  
1555  It is only used on OS/2 and Win32.
1556  
1557  =item INC
1558  
1559  Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
1560  
1561  =item INCLUDE_EXT
1562  
1563  Array of extension names to be included when doing a static build.
1564  MakeMaker will normally build with all of the installed extensions when
1565  doing a static build, and that is usually the desired behavior.  If
1566  INCLUDE_EXT is present then MakeMaker will build only with those extensions
1567  which are explicitly mentioned. (e.g.  [ qw( Socket POSIX ) ])
1568  
1569  It is not necessary to mention DynaLoader or the current extension when
1570  filling in INCLUDE_EXT.  If the INCLUDE_EXT is mentioned but is empty then
1571  only DynaLoader and the current extension will be included in the build.
1572  
1573  This attribute may be most useful when specified as a string on the
1574  command line:  perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
1575  
1576  =item INSTALLARCHLIB
1577  
1578  Used by 'make install', which copies files from INST_ARCHLIB to this
1579  directory if INSTALLDIRS is set to perl.
1580  
1581  =item INSTALLBIN
1582  
1583  Directory to install binary files (e.g. tkperl) into if
1584  INSTALLDIRS=perl.
1585  
1586  =item INSTALLDIRS
1587  
1588  Determines which of the sets of installation directories to choose:
1589  perl, site or vendor.  Defaults to site.
1590  
1591  =item INSTALLMAN1DIR
1592  
1593  =item INSTALLMAN3DIR
1594  
1595  These directories get the man pages at 'make install' time if
1596  INSTALLDIRS=perl.  Defaults to $Config{installman*dir}.
1597  
1598  If set to 'none', no man pages will be installed.
1599  
1600  =item INSTALLPRIVLIB
1601  
1602  Used by 'make install', which copies files from INST_LIB to this
1603  directory if INSTALLDIRS is set to perl.
1604  
1605  Defaults to $Config{installprivlib}.
1606  
1607  =item INSTALLSCRIPT
1608  
1609  Used by 'make install' which copies files from INST_SCRIPT to this
1610  directory if INSTALLDIRS=perl.
1611  
1612  =item INSTALLSITEARCH
1613  
1614  Used by 'make install', which copies files from INST_ARCHLIB to this
1615  directory if INSTALLDIRS is set to site (default).
1616  
1617  =item INSTALLSITEBIN
1618  
1619  Used by 'make install', which copies files from INST_BIN to this
1620  directory if INSTALLDIRS is set to site (default).
1621  
1622  =item INSTALLSITELIB
1623  
1624  Used by 'make install', which copies files from INST_LIB to this
1625  directory if INSTALLDIRS is set to site (default).
1626  
1627  =item INSTALLSITEMAN1DIR
1628  
1629  =item INSTALLSITEMAN3DIR
1630  
1631  These directories get the man pages at 'make install' time if
1632  INSTALLDIRS=site (default).  Defaults to 
1633  $(SITEPREFIX)/man/man$(MAN*EXT).
1634  
1635  If set to 'none', no man pages will be installed.
1636  
1637  =item INSTALLSITESCRIPT
1638  
1639  Used by 'make install' which copies files from INST_SCRIPT to this
1640  directory if INSTALLDIRS is set to site (default).
1641  
1642  =item INSTALLVENDORARCH
1643  
1644  Used by 'make install', which copies files from INST_ARCHLIB to this
1645  directory if INSTALLDIRS is set to vendor.
1646  
1647  =item INSTALLVENDORBIN
1648  
1649  Used by 'make install', which copies files from INST_BIN to this
1650  directory if INSTALLDIRS is set to vendor.
1651  
1652  =item INSTALLVENDORLIB
1653  
1654  Used by 'make install', which copies files from INST_LIB to this
1655  directory if INSTALLDIRS is set to vendor.
1656  
1657  =item INSTALLVENDORMAN1DIR
1658  
1659  =item INSTALLVENDORMAN3DIR
1660  
1661  These directories get the man pages at 'make install' time if
1662  INSTALLDIRS=vendor.  Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
1663  
1664  If set to 'none', no man pages will be installed.
1665  
1666  =item INSTALLVENDORSCRIPT
1667  
1668  Used by 'make install' which copies files from INST_SCRIPT to this
1669  directory if INSTALLDIRS is set to is set to vendor.
1670  
1671  =item INST_ARCHLIB
1672  
1673  Same as INST_LIB for architecture dependent files.
1674  
1675  =item INST_BIN
1676  
1677  Directory to put real binary files during 'make'. These will be copied
1678  to INSTALLBIN during 'make install'
1679  
1680  =item INST_LIB
1681  
1682  Directory where we put library files of this extension while building
1683  it.
1684  
1685  =item INST_MAN1DIR
1686  
1687  Directory to hold the man pages at 'make' time
1688  
1689  =item INST_MAN3DIR
1690  
1691  Directory to hold the man pages at 'make' time
1692  
1693  =item INST_SCRIPT
1694  
1695  Directory, where executable files should be installed during
1696  'make'. Defaults to "./blib/script", just to have a dummy location during
1697  testing. make install will copy the files in INST_SCRIPT to
1698  INSTALLSCRIPT.
1699  
1700  =item LD
1701  
1702  Program to be used to link libraries for dynamic loading.
1703  
1704  Defaults to $Config{ld}.
1705  
1706  =item LDDLFLAGS
1707  
1708  Any special flags that might need to be passed to ld to create a
1709  shared library suitable for dynamic loading.  It is up to the makefile
1710  to use it.  (See L<Config/lddlflags>)
1711  
1712  Defaults to $Config{lddlflags}.
1713  
1714  =item LDFROM
1715  
1716  Defaults to "$(OBJECT)" and is used in the ld command to specify
1717  what files to link/load from (also see dynamic_lib below for how to
1718  specify ld flags)
1719  
1720  =item LIB
1721  
1722  LIB should only be set at C<perl Makefile.PL> time but is allowed as a
1723  MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
1724  and INSTALLSITELIB to that value regardless any explicit setting of
1725  those arguments (or of PREFIX).  INSTALLARCHLIB and INSTALLSITEARCH
1726  are set to the corresponding architecture subdirectory.
1727  
1728  =item LIBPERL_A
1729  
1730  The filename of the perllibrary that will be used together with this
1731  extension. Defaults to libperl.a.
1732  
1733  =item LIBS
1734  
1735  An anonymous array of alternative library
1736  specifications to be searched for (in order) until
1737  at least one library is found. E.g.
1738  
1739    'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
1740  
1741  Mind, that any element of the array
1742  contains a complete set of arguments for the ld
1743  command. So do not specify
1744  
1745    'LIBS' => ["-ltcl", "-ltk", "-lX11"]
1746  
1747  See ODBM_File/Makefile.PL for an example, where an array is needed. If
1748  you specify a scalar as in
1749  
1750    'LIBS' => "-ltcl -ltk -lX11"
1751  
1752  MakeMaker will turn it into an array with one element.
1753  
1754  =item LICENSE
1755  
1756  The licensing terms of your distribution.  Generally its "perl" for the
1757  same license as Perl itself.
1758  
1759  See L<Module::Build::Authoring> for the list of options.
1760  
1761  Defaults to "unknown".
1762  
1763  =item LINKTYPE
1764  
1765  'static' or 'dynamic' (default unless usedl=undef in
1766  config.sh). Should only be used to force static linking (also see
1767  linkext below).
1768  
1769  =item MAKE
1770  
1771  Variant of make you intend to run the generated Makefile with.  This
1772  parameter lets Makefile.PL know what make quirks to account for when
1773  generating the Makefile.
1774  
1775  MakeMaker also honors the MAKE environment variable.  This parameter
1776  takes precedent.
1777  
1778  Currently the only significant values are 'dmake' and 'nmake' for Windows
1779  users.
1780  
1781  Defaults to $Config{make}.
1782  
1783  =item MAKEAPERL
1784  
1785  Boolean which tells MakeMaker, that it should include the rules to
1786  make a perl. This is handled automatically as a switch by
1787  MakeMaker. The user normally does not need it.
1788  
1789  =item MAKEFILE_OLD
1790  
1791  When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
1792  backed up at this location.
1793  
1794  Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
1795  
1796  =item MAN1PODS
1797  
1798  Hashref of pod-containing files. MakeMaker will default this to all
1799  EXE_FILES files that include POD directives. The files listed
1800  here will be converted to man pages and installed as was requested
1801  at Configure time.
1802  
1803  =item MAN3PODS
1804  
1805  Hashref that assigns to *.pm and *.pod files the files into which the
1806  manpages are to be written. MakeMaker parses all *.pod and *.pm files
1807  for POD directives. Files that contain POD will be the default keys of
1808  the MAN3PODS hashref. These will then be converted to man pages during
1809  C<make> and will be installed during C<make install>.
1810  
1811  =item MAP_TARGET
1812  
1813  If it is intended, that a new perl binary be produced, this variable
1814  may hold a name for that binary. Defaults to perl
1815  
1816  =item MYEXTLIB
1817  
1818  If the extension links to a library that it builds set this to the
1819  name of the library (see SDBM_File)
1820  
1821  =item NAME
1822  
1823  Perl module name for this extension (DBD::Oracle). This will default
1824  to the directory name but should be explicitly defined in the
1825  Makefile.PL.
1826  
1827  =item NEEDS_LINKING
1828  
1829  MakeMaker will figure out if an extension contains linkable code
1830  anywhere down the directory tree, and will set this variable
1831  accordingly, but you can speed it up a very little bit if you define
1832  this boolean variable yourself.
1833  
1834  =item NOECHO
1835  
1836  Command so make does not print the literal commands its running.
1837  
1838  By setting it to an empty string you can generate a Makefile that
1839  prints all commands. Mainly used in debugging MakeMaker itself.
1840  
1841  Defaults to C<@>.
1842  
1843  =item NORECURS
1844  
1845  Boolean.  Attribute to inhibit descending into subdirectories.
1846  
1847  =item NO_META
1848  
1849  When true, suppresses the generation and addition to the MANIFEST of
1850  the META.yml module meta-data file during 'make distdir'.
1851  
1852  Defaults to false.
1853  
1854  =item NO_VC
1855  
1856  In general, any generated Makefile checks for the current version of
1857  MakeMaker and the version the Makefile was built under. If NO_VC is
1858  set, the version check is neglected. Do not write this into your
1859  Makefile.PL, use it interactively instead.
1860  
1861  =item OBJECT
1862  
1863  List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
1864  string containing all object files, e.g. "tkpBind.o
1865  tkpButton.o tkpCanvas.o"
1866  
1867  (Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)
1868  
1869  =item OPTIMIZE
1870  
1871  Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
1872  passed to subdirectory makes.
1873  
1874  =item PERL
1875  
1876  Perl binary for tasks that can be done by miniperl
1877  
1878  =item PERL_CORE
1879  
1880  Set only when MakeMaker is building the extensions of the Perl core
1881  distribution.
1882  
1883  =item PERLMAINCC
1884  
1885  The call to the program that is able to compile perlmain.c. Defaults
1886  to $(CC).
1887  
1888  =item PERL_ARCHLIB
1889  
1890  Same as for PERL_LIB, but for architecture dependent files.
1891  
1892  Used only when MakeMaker is building the extensions of the Perl core
1893  distribution (because normally $(PERL_ARCHLIB) is automatically in @INC,
1894  and adding it would get in the way of PERL5LIB).
1895  
1896  =item PERL_LIB
1897  
1898  Directory containing the Perl library to use.
1899  
1900  Used only when MakeMaker is building the extensions of the Perl core
1901  distribution (because normally $(PERL_LIB) is automatically in @INC,
1902  and adding it would get in the way of PERL5LIB).
1903  
1904  =item PERL_MALLOC_OK
1905  
1906  defaults to 0.  Should be set to TRUE if the extension can work with
1907  the memory allocation routines substituted by the Perl malloc() subsystem.
1908  This should be applicable to most extensions with exceptions of those
1909  
1910  =over 4
1911  
1912  =item *
1913  
1914  with bugs in memory allocations which are caught by Perl's malloc();
1915  
1916  =item *
1917  
1918  which interact with the memory allocator in other ways than via
1919  malloc(), realloc(), free(), calloc(), sbrk() and brk();
1920  
1921  =item *
1922  
1923  which rely on special alignment which is not provided by Perl's malloc().
1924  
1925  =back
1926  
1927  B<NOTE.>  Negligence to set this flag in I<any one> of loaded extension
1928  nullifies many advantages of Perl's malloc(), such as better usage of
1929  system resources, error detection, memory usage reporting, catchable failure
1930  of memory allocations, etc.
1931  
1932  =item PERLPREFIX
1933  
1934  Directory under which core modules are to be installed.
1935  
1936  Defaults to $Config{installprefixexp} falling back to
1937  $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
1938  $Config{installprefixexp} not exist.
1939  
1940  Overridden by PREFIX.
1941  
1942  =item PERLRUN
1943  
1944  Use this instead of $(PERL) when you wish to run perl.  It will set up
1945  extra necessary flags for you.
1946  
1947  =item PERLRUNINST
1948  
1949  Use this instead of $(PERL) when you wish to run perl to work with
1950  modules.  It will add things like -I$(INST_ARCH) and other necessary
1951  flags so perl can see the modules you're about to install.
1952  
1953  =item PERL_SRC
1954  
1955  Directory containing the Perl source code (use of this should be
1956  avoided, it may be undefined)
1957  
1958  =item PERM_RW
1959  
1960  Desired permission for read/writable files. Defaults to C<644>.
1961  See also L<MM_Unix/perm_rw>.
1962  
1963  =item PERM_RWX
1964  
1965  Desired permission for executable files. Defaults to C<755>.
1966  See also L<MM_Unix/perm_rwx>.
1967  
1968  =item PL_FILES
1969  
1970  MakeMaker can run programs to generate files for you at build time.
1971  By default any file named *.PL (except Makefile.PL and Build.PL) in
1972  the top level directory will be assumed to be a Perl program and run
1973  passing its own basename in as an argument.  For example...
1974  
1975      perl foo.PL foo
1976  
1977  This behavior can be overridden by supplying your own set of files to
1978  search.  PL_FILES accepts a hash ref, the key being the file to run
1979  and the value is passed in as the first argument when the PL file is run.
1980  
1981      PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
1982  
1983  Would run bin/foobar.PL like this:
1984  
1985      perl bin/foobar.PL bin/foobar
1986  
1987  If multiple files from one program are desired an array ref can be used.
1988  
1989      PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
1990  
1991  In this case the program will be run multiple times using each target file.
1992  
1993      perl bin/foobar.PL bin/foobar1
1994      perl bin/foobar.PL bin/foobar2
1995  
1996  PL files are normally run B<after> pm_to_blib and include INST_LIB and
1997  INST_ARCH in its C<@INC> so the just built modules can be
1998  accessed... unless the PL file is making a module (or anything else in
1999  PM) in which case it is run B<before> pm_to_blib and does not include
2000  INST_LIB and INST_ARCH in its C<@INC>.  This apparently odd behavior
2001  is there for backwards compatibility (and its somewhat DWIM).
2002  
2003  
2004  =item PM
2005  
2006  Hashref of .pm files and *.pl files to be installed.  e.g.
2007  
2008    {'name_of_file.pm' => '$(INST_LIBDIR)/install_as.pm'}
2009  
2010  By default this will include *.pm and *.pl and the files found in
2011  the PMLIBDIRS directories.  Defining PM in the
2012  Makefile.PL will override PMLIBDIRS.
2013  
2014  =item PMLIBDIRS
2015  
2016  Ref to array of subdirectories containing library files.  Defaults to
2017  [ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
2018  they contain will be installed in the corresponding location in the
2019  library.  A libscan() method can be used to alter the behaviour.
2020  Defining PM in the Makefile.PL will override PMLIBDIRS.
2021  
2022  (Where BASEEXT is the last component of NAME.)
2023  
2024  =item PM_FILTER
2025  
2026  A filter program, in the traditional Unix sense (input from stdin, output
2027  to stdout) that is passed on each .pm file during the build (in the
2028  pm_to_blib() phase).  It is empty by default, meaning no filtering is done.
2029  
2030  Great care is necessary when defining the command if quoting needs to be
2031  done.  For instance, you would need to say:
2032  
2033    {'PM_FILTER' => 'grep -v \\"^\\#\\"'}
2034  
2035  to remove all the leading comments on the fly during the build.  The
2036  extra \\ are necessary, unfortunately, because this variable is interpolated
2037  within the context of a Perl program built on the command line, and double
2038  quotes are what is used with the -e switch to build that command line.  The
2039  # is escaped for the Makefile, since what is going to be generated will then
2040  be:
2041  
2042    PM_FILTER = grep -v \"^\#\"
2043  
2044  Without the \\ before the #, we'd have the start of a Makefile comment,
2045  and the macro would be incorrectly defined.
2046  
2047  =item POLLUTE
2048  
2049  Release 5.005 grandfathered old global symbol names by providing preprocessor
2050  macros for extension source compatibility.  As of release 5.6, these
2051  preprocessor definitions are not available by default.  The POLLUTE flag
2052  specifies that the old names should still be defined:
2053  
2054    perl Makefile.PL POLLUTE=1
2055  
2056  Please inform the module author if this is necessary to successfully install
2057  a module under 5.6 or later.
2058  
2059  =item PPM_INSTALL_EXEC
2060  
2061  Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
2062  
2063  =item PPM_INSTALL_SCRIPT
2064  
2065  Name of the script that gets executed by the Perl Package Manager after
2066  the installation of a package.
2067  
2068  =item PREFIX
2069  
2070  This overrides all the default install locations.  Man pages,
2071  libraries, scripts, etc...  MakeMaker will try to make an educated
2072  guess about where to place things under the new PREFIX based on your
2073  Config defaults.  Failing that, it will fall back to a structure
2074  which should be sensible for your platform.
2075  
2076  If you specify LIB or any INSTALL* variables they will not be effected
2077  by the PREFIX.
2078  
2079  =item PREREQ_FATAL
2080  
2081  Bool. If this parameter is true, failing to have the required modules
2082  (or the right versions thereof) will be fatal. C<perl Makefile.PL>
2083  will C<die> instead of simply informing the user of the missing dependencies.
2084  
2085  It is I<extremely> rare to have to use C<PREREQ_FATAL>. Its use by module
2086  authors is I<strongly discouraged> and should never be used lightly.
2087  Module installation tools have ways of resolving umet dependencies but
2088  to do that they need a F<Makefile>.  Using C<PREREQ_FATAL> breaks this.
2089  That's bad.
2090  
2091  The only situation where it is appropriate is when you have
2092  dependencies that are indispensible to actually I<write> a
2093  F<Makefile>. For example, MakeMaker's F<Makefile.PL> needs L<File::Spec>.
2094  If its not available it cannot write the F<Makefile>.
2095  
2096  Note: see L<Test::Harness> for a shortcut for stopping tests early
2097  if you are missing dependencies and are afraid that users might
2098  use your module with an incomplete environment.
2099  
2100  =item PREREQ_PM
2101  
2102  Hashref: Names of modules that need to be available to run this
2103  extension (e.g. Fcntl for SDBM_File) are the keys of the hash and the
2104  desired version is the value. If the required version number is 0, we
2105  only check if any version is installed already.
2106  
2107  =item PREREQ_PRINT
2108  
2109  Bool.  If this parameter is true, the prerequisites will be printed to
2110  stdout and MakeMaker will exit.  The output format is an evalable hash
2111  ref.
2112  
2113  $PREREQ_PM = {
2114                 'A::B' => Vers1,
2115                 'C::D' => Vers2,
2116                 ...
2117               };
2118  
2119  =item PRINT_PREREQ
2120  
2121  RedHatism for C<PREREQ_PRINT>.  The output format is different, though:
2122  
2123      perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
2124  
2125  =item SITEPREFIX
2126  
2127  Like PERLPREFIX, but only for the site install locations.
2128  
2129  Defaults to $Config{siteprefixexp}.  Perls prior to 5.6.0 didn't have
2130  an explicit siteprefix in the Config.  In those cases
2131  $Config{installprefix} will be used.
2132  
2133  Overridable by PREFIX
2134  
2135  =item SIGN
2136  
2137  When true, perform the generation and addition to the MANIFEST of the
2138  SIGNATURE file in the distdir during 'make distdir', via 'cpansign
2139  -s'.
2140  
2141  Note that you need to install the Module::Signature module to
2142  perform this operation.
2143  
2144  Defaults to false.
2145  
2146  =item SKIP
2147  
2148  Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
2149  Makefile. Caution! Do not use the SKIP attribute for the negligible
2150  speedup. It may seriously damage the resulting Makefile. Only use it
2151  if you really need it.
2152  
2153  =item TYPEMAPS
2154  
2155  Ref to array of typemap file names.  Use this when the typemaps are
2156  in some directory other than the current directory or when they are
2157  not named B<typemap>.  The last typemap in the list takes
2158  precedence.  A typemap in the current directory has highest
2159  precedence, even if it isn't listed in TYPEMAPS.  The default system
2160  typemap has lowest precedence.
2161  
2162  =item VENDORPREFIX
2163  
2164  Like PERLPREFIX, but only for the vendor install locations.
2165  
2166  Defaults to $Config{vendorprefixexp}.
2167  
2168  Overridable by PREFIX
2169  
2170  =item VERBINST
2171  
2172  If true, make install will be verbose
2173  
2174  =item VERSION
2175  
2176  Your version number for distributing the package.  This defaults to
2177  0.1.
2178  
2179  =item VERSION_FROM
2180  
2181  Instead of specifying the VERSION in the Makefile.PL you can let
2182  MakeMaker parse a file to determine the version number. The parsing
2183  routine requires that the file named by VERSION_FROM contains one
2184  single line to compute the version number. The first line in the file
2185  that contains the regular expression
2186  
2187      /([\$*])(([\w\:\']*)\bVERSION)\b.*\=/
2188  
2189  will be evaluated with eval() and the value of the named variable
2190  B<after> the eval() will be assigned to the VERSION attribute of the
2191  MakeMaker object. The following lines will be parsed o.k.:
2192  
2193      $VERSION = '1.00';
2194      *VERSION = \'1.01';
2195      ($VERSION) = q$Revision: 41145 $ =~ /(\d+)/g;
2196      $FOO::VERSION = '1.10';
2197      *FOO::VERSION = \'1.11';
2198      our $VERSION = 1.2.3;       # new for perl5.6.0
2199  
2200  but these will fail:
2201  
2202      my $VERSION = '1.01';
2203      local $VERSION = '1.02';
2204      local $FOO::VERSION = '1.30';
2205  
2206  L<version> will be loaded, if available, so this will work.
2207  
2208      our $VERSION = qv(1.2.3);   # version.pm will be loaded if available
2209  
2210  Its up to you to declare a dependency on C<version>.  Also note that this
2211  feature was introduced in MakeMaker 6.35.  Earlier versions of MakeMaker
2212  require this:
2213  
2214      # All on one line
2215      use version; our $VERSION = qv(1.2.3);
2216  
2217  (Putting C<my> or C<local> on the preceding line will work o.k.)
2218  
2219  The file named in VERSION_FROM is not added as a dependency to
2220  Makefile. This is not really correct, but it would be a major pain
2221  during development to have to rewrite the Makefile for any smallish
2222  change in that file. If you want to make sure that the Makefile
2223  contains the correct VERSION macro after any change of the file, you
2224  would have to do something like
2225  
2226      depend => { Makefile => '$(VERSION_FROM)' }
2227  
2228  See attribute C<depend> below.
2229  
2230  =item VERSION_SYM
2231  
2232  A sanitized VERSION with . replaced by _.  For places where . has
2233  special meaning (some filesystems, RCS labels, etc...)
2234  
2235  =item XS
2236  
2237  Hashref of .xs files. MakeMaker will default this.  e.g.
2238  
2239    {'name_of_file.xs' => 'name_of_file.c'}
2240  
2241  The .c files will automatically be included in the list of files
2242  deleted by a make clean.
2243  
2244  =item XSOPT
2245  
2246  String of options to pass to xsubpp.  This might include C<-C++> or
2247  C<-extern>.  Do not include typemaps here; the TYPEMAP parameter exists for
2248  that purpose.
2249  
2250  =item XSPROTOARG
2251  
2252  May be set to an empty string, which is identical to C<-prototypes>, or
2253  C<-noprototypes>. See the xsubpp documentation for details. MakeMaker
2254  defaults to the empty string.
2255  
2256  =item XS_VERSION
2257  
2258  Your version number for the .xs file of this package.  This defaults
2259  to the value of the VERSION attribute.
2260  
2261  =back
2262  
2263  =head2 Additional lowercase attributes
2264  
2265  can be used to pass parameters to the methods which implement that
2266  part of the Makefile.  Parameters are specified as a hash ref but are
2267  passed to the method as a hash.
2268  
2269  =over 2
2270  
2271  =item clean
2272  
2273    {FILES => "*.xyz foo"}
2274  
2275  =item depend
2276  
2277    {ANY_TARGET => ANY_DEPENDENCY, ...}
2278  
2279  (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
2280  
2281  =item dist
2282  
2283    {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
2284    SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
2285    ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
2286  
2287  If you specify COMPRESS, then SUFFIX should also be altered, as it is
2288  needed to tell make the target file of the compression. Setting
2289  DIST_CP to ln can be useful, if you need to preserve the timestamps on
2290  your files. DIST_CP can take the values 'cp', which copies the file,
2291  'ln', which links the file, and 'best' which copies symbolic links and
2292  links the rest. Default is 'best'.
2293  
2294  =item dynamic_lib
2295  
2296    {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
2297  
2298  =item linkext
2299  
2300    {LINKTYPE => 'static', 'dynamic' or ''}
2301  
2302  NB: Extensions that have nothing but *.pm files had to say
2303  
2304    {LINKTYPE => ''}
2305  
2306  with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
2307  can be deleted safely. MakeMaker recognizes when there's nothing to
2308  be linked.
2309  
2310  =item macro
2311  
2312    {ANY_MACRO => ANY_VALUE, ...}
2313  
2314  =item postamble
2315  
2316  Anything put here will be passed to MY::postamble() if you have one.
2317  
2318  =item realclean
2319  
2320    {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
2321  
2322  =item test
2323  
2324    {TESTS => 't/*.t'}
2325  
2326  =item tool_autosplit
2327  
2328    {MAXLEN => 8}
2329  
2330  =back
2331  
2332  =head2 Overriding MakeMaker Methods
2333  
2334  If you cannot achieve the desired Makefile behaviour by specifying
2335  attributes you may define private subroutines in the Makefile.PL.
2336  Each subroutine returns the text it wishes to have written to
2337  the Makefile. To override a section of the Makefile you can
2338  either say:
2339  
2340          sub MY::c_o { "new literal text" }
2341  
2342  or you can edit the default by saying something like:
2343  
2344          package MY; # so that "SUPER" works right
2345          sub c_o {
2346              my $inherited = shift->SUPER::c_o(@_);
2347              $inherited =~ s/old text/new text/;
2348              $inherited;
2349          }
2350  
2351  If you are running experiments with embedding perl as a library into
2352  other applications, you might find MakeMaker is not sufficient. You'd
2353  better have a look at ExtUtils::Embed which is a collection of utilities
2354  for embedding.
2355  
2356  If you still need a different solution, try to develop another
2357  subroutine that fits your needs and submit the diffs to
2358  C<makemaker@perl.org>
2359  
2360  For a complete description of all MakeMaker methods see
2361  L<ExtUtils::MM_Unix>.
2362  
2363  Here is a simple example of how to add a new target to the generated
2364  Makefile:
2365  
2366      sub MY::postamble {
2367          return <<'MAKE_FRAG';
2368      $(MYEXTLIB): sdbm/Makefile
2369              cd sdbm && $(MAKE) all
2370  
2371      MAKE_FRAG
2372      }
2373  
2374  =head2 The End Of Cargo Cult Programming
2375  
2376  WriteMakefile() now does some basic sanity checks on its parameters to
2377  protect against typos and malformatted values.  This means some things
2378  which happened to work in the past will now throw warnings and
2379  possibly produce internal errors.
2380  
2381  Some of the most common mistakes:
2382  
2383  =over 2
2384  
2385  =item C<< MAN3PODS => ' ' >>
2386  
2387  This is commonly used to suppress the creation of man pages.  MAN3PODS
2388  takes a hash ref not a string, but the above worked by accident in old
2389  versions of MakeMaker.
2390  
2391  The correct code is C<< MAN3PODS => { } >>.
2392  
2393  =back
2394  
2395  
2396  =head2 Hintsfile support
2397  
2398  MakeMaker.pm uses the architecture specific information from
2399  Config.pm. In addition it evaluates architecture specific hints files
2400  in a C<hints/> directory. The hints files are expected to be named
2401  like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
2402  name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
2403  MakeMaker within the WriteMakefile() subroutine, and can be used to
2404  execute commands as well as to include special variables. The rules
2405  which hintsfile is chosen are the same as in Configure.
2406  
2407  The hintsfile is eval()ed immediately after the arguments given to
2408  WriteMakefile are stuffed into a hash reference $self but before this
2409  reference becomes blessed. So if you want to do the equivalent to
2410  override or create an attribute you would say something like
2411  
2412      $self->{LIBS} = ['-ldbm -lucb -lc'];
2413  
2414  =head2 Distribution Support
2415  
2416  For authors of extensions MakeMaker provides several Makefile
2417  targets. Most of the support comes from the ExtUtils::Manifest module,
2418  where additional documentation can be found.
2419  
2420  =over 4
2421  
2422  =item    make distcheck
2423  
2424  reports which files are below the build directory but not in the
2425  MANIFEST file and vice versa. (See ExtUtils::Manifest::fullcheck() for
2426  details)
2427  
2428  =item    make skipcheck
2429  
2430  reports which files are skipped due to the entries in the
2431  C<MANIFEST.SKIP> file (See ExtUtils::Manifest::skipcheck() for
2432  details)
2433  
2434  =item    make distclean
2435  
2436  does a realclean first and then the distcheck. Note that this is not
2437  needed to build a new distribution as long as you are sure that the
2438  MANIFEST file is ok.
2439  
2440  =item    make manifest
2441  
2442  rewrites the MANIFEST file, adding all remaining files found (See
2443  ExtUtils::Manifest::mkmanifest() for details)
2444  
2445  =item    make distdir
2446  
2447  Copies all the files that are in the MANIFEST file to a newly created
2448  directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
2449  exists, it will be removed first.
2450  
2451  Additionally, it will create a META.yml module meta-data file in the
2452  distdir and add this to the distdir's MANIFEST.  You can shut this
2453  behavior off with the NO_META flag.
2454  
2455  =item   make disttest
2456  
2457  Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
2458  a make test in that directory.
2459  
2460  =item    make tardist
2461  
2462  First does a distdir. Then a command $(PREOP) which defaults to a null
2463  command, followed by $(TO_UNIX), which defaults to a null command under
2464  UNIX, and will convert files in distribution directory to UNIX format
2465  otherwise. Next it runs C<tar> on that directory into a tarfile and
2466  deletes the directory. Finishes with a command $(POSTOP) which
2467  defaults to a null command.
2468  
2469  =item    make dist
2470  
2471  Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
2472  
2473  =item    make uutardist
2474  
2475  Runs a tardist first and uuencodes the tarfile.
2476  
2477  =item    make shdist
2478  
2479  First does a distdir. Then a command $(PREOP) which defaults to a null
2480  command. Next it runs C<shar> on that directory into a sharfile and
2481  deletes the intermediate directory again. Finishes with a command
2482  $(POSTOP) which defaults to a null command.  Note: For shdist to work
2483  properly a C<shar> program that can handle directories is mandatory.
2484  
2485  =item    make zipdist
2486  
2487  First does a distdir. Then a command $(PREOP) which defaults to a null
2488  command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
2489  zipfile. Then deletes that directory. Finishes with a command
2490  $(POSTOP) which defaults to a null command.
2491  
2492  =item    make ci
2493  
2494  Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
2495  
2496  =back
2497  
2498  Customization of the dist targets can be done by specifying a hash
2499  reference to the dist attribute of the WriteMakefile call. The
2500  following parameters are recognized:
2501  
2502      CI           ('ci -u')
2503      COMPRESS     ('gzip --best')
2504      POSTOP       ('@ :')
2505      PREOP        ('@ :')
2506      TO_UNIX      (depends on the system)
2507      RCS_LABEL    ('rcs -q -Nv$(VERSION_SYM):')
2508      SHAR         ('shar')
2509      SUFFIX       ('.gz')
2510      TAR          ('tar')
2511      TARFLAGS     ('cvf')
2512      ZIP          ('zip')
2513      ZIPFLAGS     ('-r')
2514  
2515  An example:
2516  
2517      WriteMakefile( 'dist' => { COMPRESS=>"bzip2", SUFFIX=>".bz2" })
2518  
2519  
2520  =head2 Module Meta-Data
2521  
2522  Long plaguing users of MakeMaker based modules has been the problem of
2523  getting basic information about the module out of the sources
2524  I<without> running the F<Makefile.PL> and doing a bunch of messy
2525  heuristics on the resulting F<Makefile>.  To this end a simple module
2526  meta-data file has been introduced, F<META.yml>.
2527  
2528  F<META.yml> is a YAML document (see http://www.yaml.org) containing
2529  basic information about the module (name, version, prerequisites...)
2530  in an easy to read format.  The format is developed and defined by the
2531  Module::Build developers (see 
2532  http://module-build.sourceforge.net/META-spec.html)
2533  
2534  MakeMaker will automatically generate a F<META.yml> file for you and
2535  add it to your F<MANIFEST> as part of the 'distdir' target (and thus
2536  the 'dist' target).  This is intended to seamlessly and rapidly
2537  populate CPAN with module meta-data.  If you wish to shut this feature
2538  off, set the C<NO_META> C<WriteMakefile()> flag to true.
2539  
2540  
2541  =head2 Disabling an extension
2542  
2543  If some events detected in F<Makefile.PL> imply that there is no way
2544  to create the Module, but this is a normal state of things, then you
2545  can create a F<Makefile> which does nothing, but succeeds on all the
2546  "usual" build targets.  To do so, use
2547  
2548      use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
2549      WriteEmptyMakefile();
2550  
2551  instead of WriteMakefile().
2552  
2553  This may be useful if other modules expect this module to be I<built>
2554  OK, as opposed to I<work> OK (say, this system-dependent module builds
2555  in a subdirectory of some other distribution, or is listed as a
2556  dependency in a CPAN::Bundle, but the functionality is supported by
2557  different means on the current architecture).
2558  
2559  =head2 Other Handy Functions
2560  
2561  =over 4
2562  
2563  =item prompt
2564  
2565      my $value = prompt($message);
2566      my $value = prompt($message, $default);
2567  
2568  The C<prompt()> function provides an easy way to request user input
2569  used to write a makefile.  It displays the $message as a prompt for
2570  input.  If a $default is provided it will be used as a default.  The
2571  function returns the $value selected by the user.
2572  
2573  If C<prompt()> detects that it is not running interactively and there
2574  is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
2575  is set to true, the $default will be used without prompting.  This
2576  prevents automated processes from blocking on user input. 
2577  
2578  If no $default is provided an empty string will be used instead.
2579  
2580  =back
2581  
2582  
2583  =head1 ENVIRONMENT
2584  
2585  =over 4
2586  
2587  =item PERL_MM_OPT
2588  
2589  Command line options used by C<MakeMaker-E<gt>new()>, and thus by
2590  C<WriteMakefile()>.  The string is split on whitespace, and the result
2591  is processed before any actual command line arguments are processed.
2592  
2593  =item PERL_MM_USE_DEFAULT
2594  
2595  If set to a true value then MakeMaker's prompt function will
2596  always return the default without waiting for user input.
2597  
2598  =item PERL_CORE
2599  
2600  Same as the PERL_CORE parameter.  The parameter overrides this.
2601  
2602  =back
2603  
2604  =head1 SEE ALSO
2605  
2606  L<Module::Build> is a pure-Perl alternative to MakeMaker which does
2607  not rely on make or any other external utility.  It is easier to
2608  extend to suit your needs.
2609  
2610  L<Module::Install> is a wrapper around MakeMaker which adds features
2611  not normally available.
2612  
2613  L<ExtUtils::ModuleMaker> and L<Module::Starter> are both modules to
2614  help you setup your distribution.
2615  
2616  =head1 AUTHORS
2617  
2618  Andy Dougherty C<doughera@lafayette.edu>, Andreas KE<ouml>nig
2619  C<andreas.koenig@mind.de>, Tim Bunce C<timb@cpan.org>.  VMS
2620  support by Charles Bailey C<bailey@newman.upenn.edu>.  OS/2 support
2621  by Ilya Zakharevich C<ilya@math.ohio-state.edu>.
2622  
2623  Currently maintained by Michael G Schwern C<schwern@pobox.com>
2624  
2625  Send patches and ideas to C<makemaker@perl.org>.
2626  
2627  Send bug reports via http://rt.cpan.org/.  Please send your
2628  generated Makefile along with your report.
2629  
2630  For more up-to-date information, see L<http://www.makemaker.org>.
2631  
2632  =head1 LICENSE
2633  
2634  This program is free software; you can redistribute it and/or 
2635  modify it under the same terms as Perl itself.
2636  
2637  See L<http://www.perl.com/perl/misc/Artistic.html>
2638  
2639  
2640  =cut