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