lib/ExtUtils/MakeMaker.pm

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