cpan/ExtUtils-MakeMaker/lib/ExtUtils/MakeMaker.pm

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