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