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