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