lib/ExtUtils/MakeMaker.pm

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