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