lib/ExtUtils/MakeMaker.pm

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