2 package ExtUtils::MakeMaker;
10 use ExtUtils::MakeMaker::Config;
11 use ExtUtils::MakeMaker::version; # ensure we always have our fake version.pm
14 my $CAN_DECODE = eval { require ExtUtils::MakeMaker::Locale; }; # 2 birds, 1 stone
15 eval { ExtUtils::MakeMaker::Locale::reinit('UTF-8') }
16 if $CAN_DECODE and Encode::find_encoding('locale')->name eq 'ascii';
18 our $Verbose = 0; # exported
19 our @Parent; # needs to be localized
20 our @Get_from_Config; # referenced by MM_Unix
24 my %Recognized_Att_Keys;
25 our %macro_fsentity; # whether a macro is a filesystem name
26 our %macro_dep; # whether a macro is a dependency
28 our $VERSION = '7.70';
31 # Emulate something resembling CVS $Revision$
32 (our $Revision = $VERSION) =~ s{_}{};
33 $Revision = int $Revision * 10000;
35 our $Filename = __FILE__; # referenced outside MakeMaker
37 our @ISA = qw(Exporter);
38 our @EXPORT = qw(&WriteMakefile $Verbose &prompt &os_unsupported);
39 our @EXPORT_OK = qw($VERSION &neatvalue &mkbootstrap &mksymlists
40 &WriteEmptyMakefile &open_for_writing &write_file_via_tmp
43 # These will go away once the last of the Win32 & VMS specific code is
45 my $Is_VMS = $^O eq 'VMS';
46 my $Is_Win32 = $^O eq 'MSWin32';
47 our $UNDER_CORE = $ENV{PERL_CORE}; # needs to be our
51 require ExtUtils::MM; # Things like CPAN assume loading ExtUtils::MakeMaker
54 require ExtUtils::MY; # XXX pre-5.8 versions of ExtUtils::Embed expect
55 # loading ExtUtils::MakeMaker will give them MY.
56 # This will go when Embed is its own CPAN module.
59 # 5.6.2 can't do sprintf "%1$s" - this can only do %s
61 my ($format, @args) = @_;
62 for (my $i = 1; $i <= @args; $i++) {
63 $format =~ s#%$i\$s#$args[$i-1]#g;
69 croak "WriteMakefile: Need even number of args" if @_ % 2;
74 _convert_compat_attrs(\%att);
78 my $mm = MM->new(\%att);
85 # Basic signatures of the attributes WriteMakefile takes. Each is the
86 # reference type. Empty value indicate it takes a non-reference
97 EXCLUDE_EXT => 'ARRAY',
102 INCLUDE_EXT => 'ARRAY',
103 LIBS => ['ARRAY',''],
107 META_MERGE => 'HASH',
108 OBJECT => ['ARRAY', ''],
111 PMLIBDIRS => 'ARRAY',
112 PMLIBPARENTDIRS => 'ARRAY',
114 BUILD_REQUIRES => 'HASH',
115 CONFIGURE_REQUIRES => 'HASH',
116 TEST_REQUIRES => 'HASH',
121 VERSION => ['version',''],
122 _KEEP_AFTER_FLUSH => '',
127 dynamic_lib=> 'HASH',
133 tool_autosplit => 'HASH',
136 @Att_Sigs{keys %Recognized_Att_Keys} = ('') x keys %Recognized_Att_Keys;
137 @Att_Sigs{keys %Special_Sigs} = values %Special_Sigs;
139 sub _convert_compat_attrs { #result of running several times should be same
141 if (exists $att->{AUTHOR}) {
142 if ($att->{AUTHOR}) {
143 if (!ref($att->{AUTHOR})) {
144 my $t = $att->{AUTHOR};
145 $att->{AUTHOR} = [$t];
156 foreach my $key (sort keys %$att) {
157 my $val = $att->{$key};
158 my $sig = $Att_Sigs{$key};
159 unless( defined $sig ) {
160 warn "WARNING: $key is not a known parameter.\n";
164 my @sigs = ref $sig ? @$sig : $sig;
165 my $given = ref $val;
166 unless( grep { _is_of_type($val, $_) } @sigs ) {
167 my $takes = join " or ", map { _format_att($_) } @sigs;
169 my $has = _format_att($given);
170 warn "WARNING: $key takes a $takes not a $has.\n".
171 " Please inform the author.\n";
177 # Check if a given thing is a reference or instance of $type
179 my($thing, $type) = @_;
181 return 1 if ref $thing eq $type;
184 return 1 if eval{ $thing->isa($type) };
193 return $given eq '' ? "string/number"
194 : uc $given eq $given ? "$given reference"
200 sub prompt ($;$) { ## no critic
201 my($mess, $def) = @_;
202 confess("prompt function called without an argument")
203 unless defined $mess;
205 my $isa_tty = -t STDIN && (-t STDOUT || !(-f STDOUT || -c STDOUT)) ;
207 my $dispdef = defined $def ? "[$def] " : " ";
208 $def = defined $def ? $def : "";
212 print "$mess $dispdef";
215 if ($ENV{PERL_MM_USE_DEFAULT} || (!$isa_tty && eof STDIN)) {
221 $ans =~ s{\015?\012$}{};
223 else { # user hit ctrl-D
228 return (!defined $ans || $ans eq '') ? $def : $ans;
232 die "OS unsupported\n";
235 sub eval_in_subdirs {
237 use Cwd qw(cwd abs_path);
238 my $pwd = cwd() || die "Can't figure out your cwd!";
240 local @INC = map eval {abs_path($_) if -e} || $_, @INC;
241 push @INC, '.'; # '.' has to always be at the end of @INC
243 foreach my $dir (@{$self->{DIR}}){
244 my($abs) = $self->catdir($pwd,$dir);
245 eval { $self->eval_in_x($abs); };
254 chdir $dir or carp("Couldn't change to directory $dir: $!");
261 # if ($@ =~ /prerequisites/) {
262 # die "MakeMaker WARNING: $@";
264 # warn "WARNING from evaluation of $dir/Makefile.PL: $@";
266 die "ERROR from evaluation of $dir/Makefile.PL: $@";
271 # package name for the classes into which the first object will be blessed
272 my $PACKNAME = 'PACK000';
278 PERL_INCDEP PERL_ARCHLIBDEP PERL_ARCHIVEDEP
284 INST_ARCHLIB INST_SCRIPT INST_BIN INST_LIB INST_MAN1DIR INST_MAN3DIR
286 DESTDIR PREFIX INSTALL_BASE
287 PERLPREFIX SITEPREFIX VENDORPREFIX
288 INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
289 INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
290 INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
291 INSTALLMAN1DIR INSTALLMAN3DIR
292 INSTALLSITEMAN1DIR INSTALLSITEMAN3DIR
293 INSTALLVENDORMAN1DIR INSTALLVENDORMAN3DIR
294 INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
295 PERL_LIB PERL_ARCHLIB
296 SITELIBEXP SITEARCHEXP
298 MAKE LIBPERL_A LIB PERL_SRC PERL_INC
299 PPM_INSTALL_EXEC PPM_UNINSTALL_EXEC
300 PPM_INSTALL_SCRIPT PPM_UNINSTALL_SCRIPT
303 my @attrib_help = qw/
305 AUTHOR ABSTRACT ABSTRACT_FROM BINARY_LOCATION
306 C CAPI CCFLAGS CONFIG CONFIGURE DEFINE DIR DISTNAME DISTVNAME
308 EXCLUDE_EXT EXE_FILES FIRST_MAKEFILE
309 FULLPERLRUN FULLPERLRUNINST
312 INC INCLUDE_EXT LDFROM LIBS LICENSE
313 LINKTYPE MAKEAPERL MAKEFILE MAKEFILE_OLD MAN1PODS MAN3PODS MAP_TARGET
314 META_ADD META_MERGE MIN_PERL_VERSION BUILD_REQUIRES CONFIGURE_REQUIRES
315 MYEXTLIB NAME NEEDS_LINKING NOECHO NO_META NO_MYMETA NO_PACKLIST NO_PERLLOCAL
316 NORECURS NO_VC OBJECT OPTIMIZE PERL_MALLOC_OK PERL PERLMAINCC PERLRUN
317 PERLRUNINST PERL_CORE
318 PERM_DIR PERM_RW PERM_RWX MAGICXS
319 PL_FILES PM PM_FILTER PMLIBDIRS PMLIBPARENTDIRS POLLUTE
320 PREREQ_FATAL PREREQ_PM PREREQ_PRINT PRINT_PREREQ PUREPERL_ONLY
321 SIGN SKIP TEST_REQUIRES TYPEMAPS UNINST VERSION VERSION_FROM XS
322 XSBUILD XSMULTI XSOPT XSPROTOARG XS_VERSION
323 clean depend dist dynamic_lib linkext macro realclean tool_autosplit
327 MACPERL_SRC MACPERL_LIB MACLIBS_68K MACLIBS_PPC MACLIBS_SC MACLIBS_MRC
328 MACLIBS_ALL_68K MACLIBS_ALL_PPC MACLIBS_SHARED
330 push @attrib_help, @fs_macros;
331 @macro_fsentity{@fs_macros, @dep_macros} = (1) x (@fs_macros+@dep_macros);
332 @macro_dep{@dep_macros} = (1) x @dep_macros;
334 # IMPORTS is used under OS/2 and Win32
336 # @Overridable is close to @MM_Sections but not identical. The
337 # order is important. Many subroutines declare macros. These
338 # depend on each other. Let's try to collect the macros up front,
339 # then pasthru, then the rules.
341 # MM_Sections are the sections we have to call explicitly
342 # in Overridable we have subroutines that are used indirectly
348 post_initialize const_config constants platform_constants
349 tool_autosplit tool_xsubpp tools_other
353 dist macro depend cflags const_loadlibs const_cccmd
360 top_targets blibdirs linkext dlsyms dynamic_bs dynamic
361 dynamic_lib static static_lib manifypods processPL
363 clean_subdirs clean realclean_subdirs realclean
365 dist_basics dist_core distdir dist_test dist_ci distmeta distsignature
366 install force perldepend makefile staticmake test ppd
368 ); # loses section ordering
370 @Overridable = @MM_Sections;
371 push @Overridable, qw[
373 libscan makeaperl needs_linking
374 subdir_x test_via_harness test_via_script
376 init_VERSION init_dist init_INST init_INSTALL init_DEST init_dirscan
377 init_PM init_MANPODS init_xs init_PERL init_DIRFILESEP init_linker
380 push @MM_Sections, qw[
382 pm_to_blib selfdocument
386 # Postamble needs to be the last that was always the case
387 push @MM_Sections, "postamble";
388 push @Overridable, "postamble";
390 # All sections are valid keys.
391 @Recognized_Att_Keys{@MM_Sections} = (1) x @MM_Sections;
393 # we will use all these variables in the Makefile
396 ar cc cccdlflags ccdlflags cpprun dlext dlsrc exe_ext full_ar ld
397 lddlflags ldflags libc lib_ext obj_ext osname osvers ranlib
398 sitelibexp sitearchexp so
401 # 5.5.3 doesn't have any concept of vendor libs
402 push @Get_from_Config, qw( vendorarchexp vendorlibexp ) if "$]" >= 5.006;
404 foreach my $item (@attrib_help){
405 $Recognized_Att_Keys{$item} = 1;
407 foreach my $item (@Get_from_Config) {
408 $Recognized_Att_Keys{uc $item} = $Config{$item};
409 print "Attribute '\U$item\E' => '$Config{$item}'\n"
414 # When we eval a Makefile.PL in a subdirectory, that one will ask
415 # us (the parent) for the values and will prepend "..", so that
416 # all files to be installed end up below OUR ./blib
418 @Prepend_parent = qw(
419 INST_BIN INST_LIB INST_ARCHLIB INST_SCRIPT
420 MAP_TARGET INST_MAN1DIR INST_MAN3DIR PERL_SRC
425 sub _has_cpan_meta_requirements {
427 require CPAN::Meta::Requirements;
428 CPAN::Meta::Requirements->VERSION(2.130);
429 # Make sure vstrings can be handled. Some versions of CMR require B to
430 # do this, which won't be available in miniperl.
431 CPAN::Meta::Requirements->new->add_string_requirement('Module' => v1.2);
437 my($class,$self) = @_;
440 _convert_compat_attrs($self) if defined $self && $self;
442 # Store the original args passed to WriteMakefile()
443 foreach my $k (keys %$self) {
444 $self->{ARGS}{$k} = $self->{$k};
447 $self = {} unless defined $self;
449 # Temporarily bless it into MM so it can be used as an
450 # object. It will be blessed into a temp package later.
453 # Cleanup all the module requirement bits
455 for my $key (qw(PREREQ_PM BUILD_REQUIRES CONFIGURE_REQUIRES TEST_REQUIRES)) {
456 $self->{$key} ||= {};
457 if (_has_cpan_meta_requirements) {
458 my $cmr = CPAN::Meta::Requirements->from_string_hash(
461 bad_version_hook => sub {
462 #no warnings 'numeric'; # module doesn't use warnings
464 if ( $_[0] =~ m!^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$! ) {
465 $fallback = sprintf "%f", $_[0];
467 ($fallback) = $_[0] ? ($_[0] =~ /^([0-9.]+)/) : 0;
469 carp "Unparsable version '$_[0]' for prerequisite $_[1] treated as $fallback";
471 version->new($fallback);
475 $self->{$key} = $cmr->as_string_hash;
476 $key2cmr{$key} = $cmr;
478 for my $module (sort keys %{ $self->{$key} }) {
479 my $version = $self->{$key}->{$module};
481 if (!defined($version) or !length($version)) {
482 carp "Undefined requirement for $module treated as '0' (CPAN::Meta::Requirements not available)";
484 elsif ($version =~ /^\d+(?:\.\d+(?:_\d+)*)?$/) {
488 if ( $version =~ m!^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$! ) {
489 $fallback = sprintf "%f", $version;
491 ($fallback) = $version ? ($version =~ /^([0-9.]+)/) : 0;
493 carp "Unparsable version '$version' for prerequisite $module treated as $fallback (CPAN::Meta::Requirements not available)";
496 $self->{$key}->{$module} = $fallback;
501 if ("@ARGV" =~ /\bPREREQ_PRINT\b/) {
502 $self->_PREREQ_PRINT;
505 # PRINT_PREREQ is RedHatism.
506 if ("@ARGV" =~ /\bPRINT_PREREQ\b/) {
507 $self->_PRINT_PREREQ;
510 print "MakeMaker (v$VERSION)\n" if $Verbose;
511 if (-f "MANIFEST" && ! -f "Makefile" && ! $UNDER_CORE){
517 if ( $self->{MIN_PERL_VERSION}) {
518 my $perl_version = $self->{MIN_PERL_VERSION};
519 if (ref $perl_version) {
520 # assume a version object
523 $perl_version = eval {
524 local $SIG{__WARN__} = sub {
525 # simulate "use warnings FATAL => 'all'" for vintage perls
528 my $v = version->new($perl_version);
529 # we care about parse issues, not numify warnings
533 $perl_version =~ tr/_//d
534 if defined $perl_version;
537 if (!defined $perl_version) {
538 # should this be a warning?
539 die sprintf <<'END', $self->{MIN_PERL_VERSION};
540 MakeMaker FATAL: MIN_PERL_VERSION (%s) is not in a recognized format.
541 Recommended is a quoted numerical value like '5.005' or '5.008001'.
544 elsif ($perl_version > "$]") {
545 my $message = sprintf <<'END', $perl_version, $];
546 Perl version %s or higher required. We run %s.
548 if ($self->{PREREQ_FATAL}) {
549 die "MakeMaker FATAL: $message";
552 warn "Warning: $message";
556 $self->{MIN_PERL_VERSION} = $perl_version;
559 my %configure_att; # record &{$self->{CONFIGURE}} attributes
560 my(%initial_att) = %$self; # record initial attributes
562 my(%unsatisfied) = ();
565 if (_has_cpan_meta_requirements) {
566 $cmr = CPAN::Meta::Requirements->new;
567 for my $key (qw(PREREQ_PM BUILD_REQUIRES CONFIGURE_REQUIRES TEST_REQUIRES)) {
568 $cmr->add_requirements($key2cmr{$key}) if $key2cmr{$key};
570 foreach my $prereq ($cmr->required_modules) {
571 $prereq2version{$prereq} = $cmr->requirements_for_module($prereq);
574 for my $key (qw(PREREQ_PM BUILD_REQUIRES CONFIGURE_REQUIRES TEST_REQUIRES)) {
575 next unless my $module2version = $self->{$key};
576 $prereq2version{$_} = $module2version->{$_} for keys %$module2version;
579 foreach my $prereq (sort keys %prereq2version) {
580 my $required_version = $prereq2version{$prereq};
585 if ( $prereq eq 'perl' ) {
586 if ( defined $required_version && $required_version =~ /^v?[\d_\.]+$/
587 || $required_version !~ /^v?[\d_\.]+$/ ) {
589 my $normal = eval { version->new( $required_version ) };
590 $required_version = $normal if defined $normal;
592 $installed_file = $prereq;
596 $installed_file = MM->_installed_file_for_module($prereq);
597 $pr_version = MM->parse_version($installed_file) if $installed_file;
598 $pr_version = 0 if $pr_version eq 'undef';
599 if ( !eval { version->new( $pr_version ); 1 } ) {
600 #no warnings 'numeric'; # module doesn't use warnings
602 if ( $pr_version =~ m!^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$! ) {
603 $fallback = sprintf '%f', $pr_version;
605 ($fallback) = $pr_version ? ($pr_version =~ /^([0-9.]+)/) : 0;
607 carp "Unparsable version '$pr_version' for installed prerequisite $prereq treated as $fallback";
609 $pr_version = $fallback;
613 # convert X.Y_Z alpha version #s to X.YZ for easier comparisons
614 $pr_version =~ s/(\d+)\.(\d+)_(\d+)/$1.$2$3/;
616 if (!$installed_file) {
617 warn sprintf "Warning: prerequisite %s %s not found.\n",
618 $prereq, $required_version
619 unless $self->{PREREQ_FATAL}
622 $unsatisfied{$prereq} = 'not installed';
626 ? !$cmr->accepts_module($prereq, $pr_version)
627 : $required_version > $pr_version
629 warn sprintf "Warning: prerequisite %s %s not found. We have %s.\n",
630 $prereq, $required_version, ($pr_version || 'unknown version')
631 unless $self->{PREREQ_FATAL}
634 $unsatisfied{$prereq} = $required_version || 'unknown version' ;
638 if (%unsatisfied && $self->{PREREQ_FATAL}){
639 my $failedprereqs = join "\n", map {" $_ $unsatisfied{$_}"}
640 sort { lc $a cmp lc $b } keys %unsatisfied;
642 MakeMaker FATAL: prerequisites not found.
645 Please install these modules first and rerun 'perl Makefile.PL'.
649 if (defined $self->{CONFIGURE}) {
650 if (ref $self->{CONFIGURE} eq 'CODE') {
651 %configure_att = %{&{$self->{CONFIGURE}}};
652 _convert_compat_attrs(\%configure_att);
653 $self = { %$self, %configure_att };
655 croak "Attribute 'CONFIGURE' to WriteMakefile() not a code reference\n";
659 my $newclass = ++$PACKNAME;
660 local @Parent = @Parent; # Protect against non-local exits
662 print "Blessing Object into class [$newclass]\n" if $Verbose>=2;
663 mv_all_methods("MY",$newclass);
664 bless $self, $newclass;
666 require ExtUtils::MY;
668 no strict 'refs'; ## no critic;
669 @{"$newclass\:\:ISA"} = 'MM';
672 if (defined $Parent[-2]){
673 $self->{PARENT} = $Parent[-2];
674 for my $key (@Prepend_parent) {
675 next unless defined $self->{PARENT}{$key};
677 # Don't stomp on WriteMakefile() args.
678 next if defined $self->{ARGS}{$key} and
679 $self->{ARGS}{$key} eq $self->{$key};
681 $self->{$key} = $self->{PARENT}{$key};
683 if ($Is_VMS && $key =~ /PERL$/) {
684 # PERL or FULLPERL will be a command verb or even a
685 # command with an argument instead of a full file
686 # specification under VMS. So, don't turn the command
687 # into a filespec, but do add a level to the path of
688 # the argument if not already absolute.
689 my @cmd = split /\s+/, $self->{$key};
690 $cmd[1] = $self->catfile('[-]',$cmd[1])
691 unless (@cmd < 2) || $self->file_name_is_absolute($cmd[1]);
692 $self->{$key} = join(' ', @cmd);
694 my $value = $self->{$key};
695 # not going to test in FS so only stripping start
696 $value =~ s/"// if $key =~ /PERL$/ and $self->is_make_type('dmake');
697 $value =~ s/^"// if $key =~ /PERL$/;
698 $value = $self->catdir("..", $value)
699 unless $self->file_name_is_absolute($value);
700 $value = qq{"$value} if $key =~ /PERL$/;
701 $self->{$key} = $value;
704 if ($self->{PARENT}) {
705 $self->{PARENT}->{CHILDREN}->{$newclass} = $self;
706 foreach my $opt (qw(POLLUTE PERL_CORE LINKTYPE AR FULL_AR CC CCFLAGS
707 OPTIMIZE LD LDDLFLAGS LDFLAGS PERL_ARCHLIB DESTDIR)) {
708 if (exists $self->{PARENT}->{$opt}
709 and not exists $self->{$opt})
711 # inherit, but only if already unspecified
712 $self->{$opt} = $self->{PARENT}->{$opt};
716 my @fm = grep /^FIRST_MAKEFILE=/, @ARGV;
717 parse_args($self,@fm) if @fm;
720 parse_args($self, _shellwords($ENV{PERL_MM_OPT} || ''),@ARGV);
723 # RT#91540 PREREQ_FATAL not recognized on command line
724 if (%unsatisfied && $self->{PREREQ_FATAL}){
725 my $failedprereqs = join "\n", map {" $_ $unsatisfied{$_}"}
726 sort { lc $a cmp lc $b } keys %unsatisfied;
728 MakeMaker FATAL: prerequisites not found.
731 Please install these modules first and rerun 'perl Makefile.PL'.
735 $self->{NAME} ||= $self->guess_name;
737 warn "Warning: NAME must be a package name\n"
738 unless $self->{NAME} =~ m!^[A-Z_a-z][0-9A-Z_a-z]*(?:::[0-9A-Z_a-z]+)*$!;
740 ($self->{NAME_SYM} = $self->{NAME}) =~ s/\W+/_/g;
754 $self->init_DIRFILESEP;
756 $self->init_ABSTRACT;
760 $self->catfile($Config{'archlibexp'}, "Config.pm")
764 $self->init_others();
765 $self->init_platform();
768 @args = map { Encode::decode(locale => $_) } @args if $CAN_DECODE;
769 my($argv) = neatvalue(\@args);
773 push @{$self->{RESULT}}, <<END;
774 # This Makefile is for the $self->{NAME} extension to perl.
776 # It was generated automatically by MakeMaker version
777 # $VERSION (Revision: $Revision) from the contents of
778 # Makefile.PL. Don't edit this file, edit Makefile.PL instead.
780 # ANY CHANGES MADE HERE WILL BE LOST!
782 # MakeMaker ARGV: $argv
786 push @{$self->{RESULT}}, $self->_MakeMaker_Parameters_section(\%initial_att);
788 if (defined $self->{CONFIGURE}) {
789 push @{$self->{RESULT}}, <<END;
791 # MakeMaker 'CONFIGURE' Parameters:
793 if (scalar(keys %configure_att) > 0) {
794 foreach my $key (sort keys %configure_att){
795 next if $key eq 'ARGS';
796 my($v) = neatvalue($configure_att{$key});
797 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
799 push @{$self->{RESULT}}, "# $key => $v";
804 push @{$self->{RESULT}}, "# no values returned";
806 undef %configure_att; # free memory
809 # turn the SKIP array into a SKIPHASH hash
810 for my $skip (@{$self->{SKIP} || []}) {
811 $self->{SKIPHASH}{$skip} = 1;
813 delete $self->{SKIP}; # free memory
815 if ($self->{PARENT}) {
816 for (qw/install dist dist_basics dist_core distdir dist_test dist_ci/) {
817 $self->{SKIPHASH}{$_} = 1;
821 # We run all the subdirectories now. They don't have much to query
822 # from the parent, but the parent has to query them: if they need linking!
823 unless ($self->{NORECURS}) {
824 $self->eval_in_subdirs if @{$self->{DIR}};
827 foreach my $section ( @MM_Sections ){
828 # Support for new foo_target() methods.
829 my $method = $section;
830 $method .= '_target' unless $self->can($method);
832 print "Processing Makefile '$section' section\n" if ($Verbose >= 2);
833 my($skipit) = $self->skipcheck($section);
835 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section $skipit.";
837 my(%a) = %{$self->{$section} || {}};
838 push @{$self->{RESULT}}, "\n# --- MakeMaker $section section:";
839 push @{$self->{RESULT}}, "# " . join ", ", %a if $Verbose && %a;
840 push @{$self->{RESULT}}, $self->maketext_filter(
846 push @{$self->{RESULT}}, "\n# End.";
851 sub WriteEmptyMakefile {
852 croak "WriteEmptyMakefile: Need an even number of args" if @_ % 2;
855 $att{DIR} = [] unless $att{DIR}; # don't recurse by default
856 my $self = MM->new(\%att);
858 my $new = $self->{MAKEFILE};
859 my $old = $self->{MAKEFILE_OLD};
861 _unlink($old) or warn "unlink $old: $!";
864 _rename($new, $old) or warn "rename $new => $old: $!"
866 open my $mfh, '>', $new or die "open $new for write: $!";
891 close $mfh or die "close $new for write: $!";
897 =head3 _installed_file_for_module
899 my $file = MM->_installed_file_for_module($module);
901 Return the first installed .pm $file associated with the $module. The
902 one which will show up when you C<use $module>.
904 $module is something like "strict" or "Test::More".
910 sub _installed_file_for_module {
914 my $file = "$prereq.pm";
919 my $tmp = File::Spec->catfile($dir, $file);
930 # Extracted from MakeMaker->new so we can test it
931 sub _MakeMaker_Parameters_section {
935 my @result = <<'END';
936 # MakeMaker Parameters:
939 foreach my $key (sort keys %$att){
940 next if $key eq 'ARGS';
942 if ($key eq 'PREREQ_PM') {
943 # CPAN.pm takes prereqs from this field in 'Makefile'
944 # and does not know about BUILD_REQUIRES
946 %{ $att->{PREREQ_PM} || {} },
947 %{ $att->{BUILD_REQUIRES} || {} },
948 %{ $att->{TEST_REQUIRES} || {} },
951 $v = neatvalue($att->{$key});
954 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
956 push @result, "# $key => $v";
962 # _shellwords and _parseline borrowed from Text::ParseWords
967 foreach my $line (@lines) {
969 my @words = _parse_line('\s+', 0, $line);
970 pop @words if (@words and !defined $words[-1]);
971 return() unless (@words || !length($line));
972 push(@allwords, @words);
978 my($delimiter, $keep, $line) = @_;
981 no warnings 'uninitialized'; # we will be testing undef strings
983 while (length($line)) {
984 # This pattern is optimised to be stack conservative on older perls.
985 # Do not refactor without being careful and testing it on very long strings.
986 # See Perl bug #42980 for an example of a stack busting input.
989 # double quoted string
991 ((?>[^\\"]*(?:\\.[^\\"]*)*))" # $quoted
993 # singe quoted string
995 ((?>[^\\']*(?:\\.[^\\']*)*))' # $quoted
1005 (?-x:$delimiter) # delimiter
1007 (?!^)(?=["']) # a quote
1009 )//xs or return; # extended layout
1010 my ($quote, $quoted, $unquoted, $delim) = (($1 ? ($1,$2) : ($3,$4)), $5, $6);
1013 return() unless( defined($quote) || length($unquoted) || length($delim));
1016 $quoted = "$quote$quoted$quote";
1019 $unquoted =~ s/\\(.)/$1/sg;
1020 if (defined $quote) {
1021 $quoted =~ s/\\(.)/$1/sg if ($quote eq '"');
1022 #$quoted =~ s/\\([\\'])/$1/g if ( $PERL_SINGLE_QUOTE && $quote eq "'");
1025 $word .= substr($line, 0, 0); # leave results tainted
1026 $word .= defined $quote ? $quoted : $unquoted;
1028 if (length($delim)) {
1029 push(@pieces, $word);
1030 push(@pieces, $delim) if ($keep eq 'delimiters');
1033 if (!length($line)) {
1034 push(@pieces, $word);
1040 sub check_manifest {
1041 print STDOUT "Checking if your kit is complete...\n";
1042 require ExtUtils::Manifest;
1044 $ExtUtils::Manifest::Quiet = $ExtUtils::Manifest::Quiet = 1;
1045 my(@missed) = ExtUtils::Manifest::manicheck();
1047 print "Warning: the following files are missing in your kit:\n";
1048 print "\t", join "\n\t", @missed;
1050 print "Please inform the author.\n";
1052 print "Looks good\n";
1057 my($self, @args) = @_;
1058 @args = map { Encode::decode(locale => $_) } @args if $CAN_DECODE;
1060 unless (m/(.*?)=(.*)/) {
1061 ++$Verbose if m/^verb/;
1064 my($name, $value) = ($1, $2);
1065 if ($value =~ m/^~(\w+)?/) { # tilde with optional username
1066 $value =~ s [^~(\w*)]
1068 ((getpwnam($1))[7] || "~$1") :
1073 # Remember the original args passed it. It will be useful later.
1074 $self->{ARGS}{uc $name} = $self->{uc $name} = $value;
1077 # catch old-style 'potential_libs' and inform user how to 'upgrade'
1078 if (defined $self->{potential_libs}){
1079 my($msg)="'potential_libs' => '$self->{potential_libs}' should be";
1080 if ($self->{potential_libs}){
1081 print "$msg changed to:\n\t'LIBS' => ['$self->{potential_libs}']\n";
1083 print "$msg deleted.\n";
1085 $self->{LIBS} = [$self->{potential_libs}];
1086 delete $self->{potential_libs};
1088 # catch old-style 'ARMAYBE' and inform user how to 'upgrade'
1089 if (defined $self->{ARMAYBE}){
1090 my($armaybe) = $self->{ARMAYBE};
1091 print "ARMAYBE => '$armaybe' should be changed to:\n",
1092 "\t'dynamic_lib' => {ARMAYBE => '$armaybe'}\n";
1093 my(%dl) = %{$self->{dynamic_lib} || {}};
1094 $self->{dynamic_lib} = { %dl, ARMAYBE => $armaybe};
1095 delete $self->{ARMAYBE};
1097 if (defined $self->{LDTARGET}){
1098 print "LDTARGET should be changed to LDFROM\n";
1099 $self->{LDFROM} = $self->{LDTARGET};
1100 delete $self->{LDTARGET};
1102 # Turn a DIR argument on the command line into an array
1103 if (defined $self->{DIR} && ref \$self->{DIR} eq 'SCALAR') {
1104 # So they can choose from the command line, which extensions they want
1105 # the grep enables them to have some colons too much in case they
1106 # have to build a list with the shell
1107 $self->{DIR} = [grep $_, split ":", $self->{DIR}];
1109 # Turn a INCLUDE_EXT argument on the command line into an array
1110 if (defined $self->{INCLUDE_EXT} && ref \$self->{INCLUDE_EXT} eq 'SCALAR') {
1111 $self->{INCLUDE_EXT} = [grep $_, split '\s+', $self->{INCLUDE_EXT}];
1113 # Turn a EXCLUDE_EXT argument on the command line into an array
1114 if (defined $self->{EXCLUDE_EXT} && ref \$self->{EXCLUDE_EXT} eq 'SCALAR') {
1115 $self->{EXCLUDE_EXT} = [grep $_, split '\s+', $self->{EXCLUDE_EXT}];
1118 foreach my $mmkey (sort keys %$self){
1119 next if $mmkey eq 'ARGS';
1120 print " $mmkey => ", neatvalue($self->{$mmkey}), "\n" if $Verbose;
1121 print "'$mmkey' is not a known MakeMaker parameter name.\n"
1122 unless exists $Recognized_Att_Keys{$mmkey};
1129 # We allow extension-specific hints files.
1132 my $curdir = File::Spec->curdir;
1134 my $hint_dir = File::Spec->catdir($curdir, "hints");
1135 return unless -d $hint_dir;
1137 # First we look for the best hintsfile we have
1138 my($hint)="${^O}_$Config{osvers}";
1141 return unless $hint;
1143 # Also try without trailing minor version numbers.
1145 last if -f File::Spec->catfile($hint_dir, "$hint.pl"); # found
1147 last unless $hint =~ s/_[^_]*$//; # nothing to cut off
1149 my $hint_file = File::Spec->catfile($hint_dir, "$hint.pl");
1151 return unless -f $hint_file; # really there
1153 _run_hintfile($self, $hint_file);
1158 local($self) = shift; # make $self available to the hint file.
1159 my($hint_file) = shift;
1162 print "Processing hints file $hint_file\n" if $Verbose;
1164 # Just in case the ./ isn't on the hint file, which File::Spec can
1165 # often strip off, we bung the curdir into @INC
1166 local @INC = (File::Spec->curdir, @INC);
1167 my $ret = do $hint_file;
1168 if( !defined $ret ) {
1169 my $error = $@ || $!;
1174 sub mv_all_methods {
1176 local $SIG{__WARN__} = sub {
1177 # can't use 'no warnings redefined', 5.6 only
1178 warn @_ unless $_[0] =~ /^Subroutine .* redefined/
1180 foreach my $method (@Overridable) {
1181 next unless defined &{"${from}::$method"};
1182 no strict 'refs'; ## no critic
1183 *{"${to}::$method"} = \&{"${from}::$method"};
1185 # If we delete a method, then it will be undefined and cannot
1186 # be called. But as long as we have Makefile.PLs that rely on
1187 # %MY:: being intact, we have to fill the hole with an
1188 # inheriting method:
1192 my $super = "SUPER::".$method;
1203 return 'skipped' if $section eq 'metafile' && $UNDER_CORE;
1204 if ($section eq 'dynamic') {
1205 print "Warning (non-fatal): Target 'dynamic' depends on targets ",
1206 "in skipped section 'dynamic_bs'\n"
1207 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
1208 print "Warning (non-fatal): Target 'dynamic' depends on targets ",
1209 "in skipped section 'dynamic_lib'\n"
1210 if $self->{SKIPHASH}{dynamic_lib} && $Verbose;
1212 if ($section eq 'dynamic_lib') {
1213 print "Warning (non-fatal): Target '\$(INST_DYNAMIC)' depends on ",
1214 "targets in skipped section 'dynamic_bs'\n"
1215 if $self->{SKIPHASH}{dynamic_bs} && $Verbose;
1217 if ($section eq 'static') {
1218 print "Warning (non-fatal): Target 'static' depends on targets ",
1219 "in skipped section 'static_lib'\n"
1220 if $self->{SKIPHASH}{static_lib} && $Verbose;
1222 return 'skipped' if $self->{SKIPHASH}{$section};
1226 # returns filehandle, dies on fail. :raw so no :crlf
1227 sub open_for_writing {
1229 open my $fh ,">", $file or die "Unable to open $file: $!";
1230 my @layers = ':raw';
1231 push @layers, join ' ', ':encoding(locale)' if $CAN_DECODE;
1232 binmode $fh, join ' ', @layers;
1239 my $finalname = $self->{MAKEFILE};
1240 printf STDOUT "Generating a %s %s\n", $self->make_type, $finalname if $Verbose || !$self->{PARENT};
1241 print STDOUT "Writing $finalname for $self->{NAME}\n" if $Verbose || !$self->{PARENT};
1243 unlink($finalname, "MakeMaker.tmp", $Is_VMS ? 'Descrip.MMS' : ());
1245 write_file_via_tmp($finalname, $self->{RESULT});
1247 # Write MYMETA.yml to communicate metadata up to the CPAN clients
1248 print STDOUT "Writing MYMETA.yml and MYMETA.json\n"
1249 if !$self->{NO_MYMETA} and $self->write_mymeta( $self->mymeta );
1252 if ($self->{PARENT} && !$self->{_KEEP_AFTER_FLUSH}) {
1253 my %keep = map { ($_ => 1) } qw(NEEDS_LINKING HAS_LINK_CODE);
1254 delete $self->{$_} for grep !$keep{$_}, keys %$self;
1257 system("$Config::Config{eunicefix} $finalname")
1258 if $Config::Config{eunicefix} ne ":";
1263 sub write_file_via_tmp {
1264 my ($finalname, $contents) = @_;
1265 my $fh = open_for_writing("MakeMaker.tmp");
1266 die "write_file_via_tmp: 2nd arg must be ref" unless ref $contents;
1267 for my $chunk (@$contents) {
1268 my $to_write = $chunk;
1269 $to_write = '' unless defined $to_write;
1270 utf8::encode $to_write if !$CAN_DECODE && "$]" > 5.008;
1271 print $fh "$to_write\n" or die "Can't write to MakeMaker.tmp: $!";
1273 close $fh or die "Can't write to MakeMaker.tmp: $!";
1274 _rename("MakeMaker.tmp", $finalname) or
1275 warn "rename MakeMaker.tmp => $finalname: $!";
1276 chmod 0644, $finalname if !$Is_VMS;
1280 # This is a rename for OS's where the target must be unlinked first.
1282 my($src, $dest) = @_;
1284 return rename $src, $dest;
1287 # This is an unlink for OS's where the target must be writable first.
1291 return unlink @files;
1295 # The following mkbootstrap() is only for installations that are calling
1296 # the pre-4.1 mkbootstrap() from their old Makefiles. This MakeMaker
1297 # writes Makefiles, that use ExtUtils::Mkbootstrap directly.
1300 !!! Your Makefile has been built such a long time ago, !!!
1301 !!! that is unlikely to work with current MakeMaker. !!!
1302 !!! Please rebuild your Makefile !!!
1306 # Ditto for mksymlists() as of MakeMaker 5.17
1309 !!! Your Makefile has been built such a long time ago, !!!
1310 !!! that is unlikely to work with current MakeMaker. !!!
1311 !!! Please rebuild your Makefile !!!
1317 return "undef" unless defined $v;
1319 return "q[$v]" unless $t;
1320 if ($t eq 'ARRAY') {
1323 foreach my $elem (@$v) {
1324 push @neat, "q[$elem]";
1326 push @m, join ", ", @neat;
1330 return $v unless $t eq 'HASH';
1332 for my $key (sort keys %$v) {
1333 last unless defined $key; # cautious programming in case (undef,undef) is true
1334 push @m,"$key=>".neatvalue($v->{$key});
1336 return "{ ".join(', ',@m)." }";
1343 push @m, "\n# Full list of MakeMaker attribute values:";
1344 foreach my $key (sort keys %$self){
1345 next if $key eq 'RESULT' || $key =~ /^[A-Z][a-z]/;
1346 my($v) = neatvalue($self->{$key});
1347 $v =~ s/(CODE|HASH|ARRAY|SCALAR)\([\dxa-f]+\)/$1\(...\)/;
1349 push @m, "# $key => $v";
1352 # added here as selfdocument is not overridable
1355 # here so even if top_targets is overridden, these will still be defined
1356 # gmake will silently still work if any are .PHONY-ed but nmake won't
1358 push @m, join "\n", map "$_ ::\n\t\$(NOECHO) \$(NOOP)\n",
1359 # config is so manifypods won't puke if no subdirs
1360 grep !$self->{SKIPHASH}{$_},
1361 qw(static dynamic config);
1371 ExtUtils::MakeMaker - Create a module Makefile
1375 use ExtUtils::MakeMaker;
1379 VERSION_FROM => "lib/Foo/Bar.pm",
1384 This utility is designed to write a Makefile for an extension module
1385 from a Makefile.PL. It is based on the Makefile.SH model provided by
1386 Andy Dougherty and the perl5-porters.
1388 It splits the task of generating the Makefile into several subroutines
1389 that can be individually overridden. Each subroutine returns the text
1390 it wishes to have written to the Makefile.
1392 As there are various Make programs with incompatible syntax, which
1393 use operating system shells, again with incompatible syntax, it is
1394 important for users of this module to know which flavour of Make
1395 a Makefile has been written for so they'll use the correct one and
1396 won't have to face the possibly bewildering errors resulting from
1397 using the wrong one.
1399 On POSIX systems, that program will likely be GNU Make; on Microsoft
1400 Windows, it will be either Microsoft NMake, DMake or GNU Make.
1401 See the section on the L</"MAKE"> parameter for details.
1403 ExtUtils::MakeMaker (EUMM) is object oriented. Each directory below the current
1404 directory that contains a Makefile.PL is treated as a separate
1405 object. This makes it possible to write an unlimited number of
1406 Makefiles with a single invocation of WriteMakefile().
1408 All inputs to WriteMakefile are Unicode characters, not just octets. EUMM
1409 seeks to handle all of these correctly. It is currently still not possible
1410 to portably use Unicode characters in module names, because this requires
1411 Perl to handle Unicode filenames, which is not yet the case on Windows.
1413 See L<ExtUtils::MakeMaker::FAQ> for details of the design and usage.
1415 =head2 How To Write A Makefile.PL
1417 See L<ExtUtils::MakeMaker::Tutorial>.
1419 The long answer is the rest of the manpage :-)
1421 =head2 Default Makefile Behaviour
1423 The generated Makefile enables the user of the extension to invoke
1425 perl Makefile.PL # optionally "perl Makefile.PL verbose"
1427 make test # optionally set TEST_VERBOSE=1
1428 make install # See below
1430 The Makefile to be produced may be altered by adding arguments of the
1431 form C<KEY=VALUE>. E.g.
1433 perl Makefile.PL INSTALL_BASE=~
1435 Other interesting targets in the generated Makefile are
1437 make config # to check if the Makefile is up-to-date
1438 make clean # delete local temp files (Makefile gets renamed)
1439 make realclean # delete derived files (including ./blib)
1440 make ci # check in all the files in the MANIFEST file
1441 make dist # see below the Distribution Support section
1445 MakeMaker checks for the existence of a file named F<test.pl> in the
1446 current directory, and if it exists it executes the script with the
1447 proper set of perl C<-I> options.
1449 MakeMaker also checks for any files matching glob("t/*.t"). It will
1450 execute all matching files in alphabetical order via the
1451 L<Test::Harness> module with the C<-I> switches set correctly.
1453 You can also organize your tests within subdirectories in the F<t/> directory.
1454 To do so, use the F<test> directive in your I<Makefile.PL>. For example, if you
1460 You could tell make to run tests in both of those directories with the
1461 following directives:
1463 test => {TESTS => 't/*/*.t t/*/*/*.t'}
1464 test => {TESTS => 't/foo/*.t t/foo/bar/*.t'}
1466 The first will run all test files in all first-level subdirectories and all
1467 subdirectories they contain. The second will run tests in only the F<t/foo>
1470 If you'd like to see the raw output of your tests, set the
1471 C<TEST_VERBOSE> variable to true.
1473 make test TEST_VERBOSE=1
1475 If you want to run particular test files, set the C<TEST_FILES> variable.
1476 It is possible to use globbing with this mechanism.
1478 make test TEST_FILES='t/foobar.t t/dagobah*.t'
1480 Windows users who are using C<nmake> should note that due to a bug in C<nmake>,
1481 when specifying C<TEST_FILES> you must use back-slashes instead of forward-slashes.
1483 nmake test TEST_FILES='t\foobar.t t\dagobah*.t'
1487 A useful variation of the above is the target C<testdb>. It runs the
1488 test under the Perl debugger (see L<perldebug>). If the file
1489 F<test.pl> exists in the current directory, it is used for the test.
1491 If you want to debug some other testfile, set the C<TEST_FILE> variable
1494 make testdb TEST_FILE=t/mytest.t
1496 By default the debugger is called using C<-d> option to perl. If you
1497 want to specify some other option, set the C<TESTDB_SW> variable:
1499 make testdb TESTDB_SW=-Dx
1503 make alone puts all relevant files into directories that are named by
1504 the macros INST_LIB, INST_ARCHLIB, INST_SCRIPT, INST_MAN1DIR and
1505 INST_MAN3DIR. All these default to something below ./blib if you are
1506 I<not> building below the perl source directory. If you I<are>
1507 building below the perl source, INST_LIB and INST_ARCHLIB default to
1508 ../../lib, and INST_SCRIPT is not defined.
1510 The I<install> target of the generated Makefile copies the files found
1511 below each of the INST_* directories to their INSTALL*
1512 counterparts. Which counterparts are chosen depends on the setting of
1513 INSTALLDIRS according to the following table:
1518 PERLPREFIX SITEPREFIX VENDORPREFIX
1519 INST_ARCHLIB INSTALLARCHLIB INSTALLSITEARCH INSTALLVENDORARCH
1520 INST_LIB INSTALLPRIVLIB INSTALLSITELIB INSTALLVENDORLIB
1521 INST_BIN INSTALLBIN INSTALLSITEBIN INSTALLVENDORBIN
1522 INST_SCRIPT INSTALLSCRIPT INSTALLSITESCRIPT INSTALLVENDORSCRIPT
1523 INST_MAN1DIR INSTALLMAN1DIR INSTALLSITEMAN1DIR INSTALLVENDORMAN1DIR
1524 INST_MAN3DIR INSTALLMAN3DIR INSTALLSITEMAN3DIR INSTALLVENDORMAN3DIR
1526 The INSTALL... macros in turn default to their %Config
1527 ($Config{installprivlib}, $Config{installarchlib}, etc.) counterparts.
1529 You can check the values of these variables on your system with
1533 And to check the sequence in which the library directories are
1534 searched by perl, run
1536 perl -le 'print join $/, @INC'
1538 Sometimes older versions of the module you're installing live in other
1539 directories in @INC. Because Perl loads the first version of a module it
1540 finds, not the newest, you might accidentally get one of these older
1541 versions even after installing a brand new version. To delete I<all other
1542 versions of the module you're installing> (not simply older ones) set the
1545 make install UNINST=1
1550 INSTALL_BASE can be passed into Makefile.PL to change where your
1551 module will be installed. INSTALL_BASE is more like what everyone
1552 else calls "prefix" than PREFIX is.
1554 To have everything installed in your home directory, do the following.
1556 # Unix users, INSTALL_BASE=~ works fine
1557 perl Makefile.PL INSTALL_BASE=/path/to/your/home/dir
1559 Like PREFIX, it sets several INSTALL* attributes at once. Unlike
1560 PREFIX it is easy to predict where the module will end up. The
1561 installation pattern looks like this:
1563 INSTALLARCHLIB INSTALL_BASE/lib/perl5/$Config{archname}
1564 INSTALLPRIVLIB INSTALL_BASE/lib/perl5
1565 INSTALLBIN INSTALL_BASE/bin
1566 INSTALLSCRIPT INSTALL_BASE/bin
1567 INSTALLMAN1DIR INSTALL_BASE/man/man1
1568 INSTALLMAN3DIR INSTALL_BASE/man/man3
1570 INSTALL_BASE in MakeMaker and C<--install_base> in Module::Build (as
1571 of 0.28) install to the same location. If you want MakeMaker and
1572 Module::Build to install to the same location simply set INSTALL_BASE
1573 and C<--install_base> to the same location.
1575 INSTALL_BASE was added in 6.31.
1578 =head2 PREFIX and LIB attribute
1580 PREFIX and LIB can be used to set several INSTALL* attributes in one
1581 go. Here's an example for installing into your home directory.
1583 # Unix users, PREFIX=~ works fine
1584 perl Makefile.PL PREFIX=/path/to/your/home/dir
1586 This will install all files in the module under your home directory,
1587 with man pages and libraries going into an appropriate place (usually
1588 ~/man and ~/lib). How the exact location is determined is complicated
1589 and depends on how your Perl was configured. INSTALL_BASE works more
1590 like what other build systems call "prefix" than PREFIX and we
1591 recommend you use that instead.
1593 Another way to specify many INSTALL directories with a single
1596 perl Makefile.PL LIB=~/lib
1598 This will install the module's architecture-independent files into
1599 ~/lib, the architecture-dependent files into ~/lib/$archname.
1601 Note, that in both cases the tilde expansion is done by MakeMaker, not
1602 by perl by default, nor by make.
1604 Conflicts between parameters LIB, PREFIX and the various INSTALL*
1605 arguments are resolved so that:
1611 setting LIB overrides any setting of INSTALLPRIVLIB, INSTALLARCHLIB,
1612 INSTALLSITELIB, INSTALLSITEARCH (and they are not affected by PREFIX);
1616 without LIB, setting PREFIX replaces the initial C<$Config{prefix}>
1617 part of those INSTALL* arguments, even if the latter are explicitly
1618 set (but are set to still start with C<$Config{prefix}>).
1622 If the user has superuser privileges, and is not working on AFS or
1623 relatives, then the defaults for INSTALLPRIVLIB, INSTALLARCHLIB,
1624 INSTALLSCRIPT, etc. will be appropriate, and this incantation will be
1632 make install by default writes some documentation of what has been
1633 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This feature
1634 can be bypassed by calling make pure_install.
1638 will have to specify the installation directories as these most
1639 probably have changed since perl itself has been installed. They will
1640 have to do this by calling
1642 perl Makefile.PL INSTALLSITELIB=/afs/here/today \
1643 INSTALLSCRIPT=/afs/there/now INSTALLMAN3DIR=/afs/for/manpages
1646 Be careful to repeat this procedure every time you recompile an
1647 extension, unless you are sure the AFS installation directories are
1650 =head2 Static Linking of a new Perl Binary
1652 An extension that is built with the above steps is ready to use on
1653 systems supporting dynamic loading. On systems that do not support
1654 dynamic loading, any newly created extension has to be linked together
1655 with the available resources. MakeMaker supports the linking process
1656 by creating appropriate targets in the Makefile whenever an extension
1657 is built. You can invoke the corresponding section of the makefile with
1661 That produces a new perl binary in the current directory with all
1662 extensions linked in that can be found in INST_ARCHLIB, SITELIBEXP,
1663 and PERL_ARCHLIB. To do that, MakeMaker writes a new Makefile, on
1664 UNIX, this is called F<Makefile.aperl> (may be system dependent). If you
1665 want to force the creation of a new perl, it is recommended that you
1666 delete this F<Makefile.aperl>, so the directories are searched through
1667 for linkable libraries again.
1669 The binary can be installed into the directory where perl normally
1670 resides on your machine with
1674 To produce a perl binary with a different name than C<perl>, either say
1676 perl Makefile.PL MAP_TARGET=myperl
1683 make myperl MAP_TARGET=myperl
1684 make inst_perl MAP_TARGET=myperl
1686 In any case you will be prompted with the correct invocation of the
1687 C<inst_perl> target that installs the new binary into INSTALLBIN.
1689 make inst_perl by default writes some documentation of what has been
1690 done into the file C<$(INSTALLARCHLIB)/perllocal.pod>. This
1691 can be bypassed by calling make pure_inst_perl.
1693 Warning: the inst_perl: target will most probably overwrite your
1694 existing perl binary. Use with care!
1696 Sometimes you might want to build a statically linked perl although
1697 your system supports dynamic loading. In this case you may explicitly
1698 set the linktype with the invocation of the Makefile.PL or make:
1700 perl Makefile.PL LINKTYPE=static # recommended
1704 make LINKTYPE=static # works on most systems
1706 =head2 Determination of Perl Library and Installation Locations
1708 MakeMaker needs to know, or to guess, where certain things are
1709 located. Especially INST_LIB and INST_ARCHLIB (where to put the files
1710 during the make(1) run), PERL_LIB and PERL_ARCHLIB (where to read
1711 existing modules from), and PERL_INC (header files and C<libperl*.*>).
1713 Extensions may be built either using the contents of the perl source
1714 directory tree or from the installed perl library. The recommended way
1715 is to build extensions after you have run 'make install' on perl
1716 itself. You can do that in any directory on your hard disk that is not
1717 below the perl source tree. The support for extensions below the ext
1718 directory of the perl distribution is only good for the standard
1719 extensions that come with perl.
1721 If an extension is being built below the C<ext/> directory of the perl
1722 source then MakeMaker will set PERL_SRC automatically (e.g.,
1723 C<../..>). If PERL_SRC is defined and the extension is recognized as
1724 a standard extension, then other variables default to the following:
1727 PERL_LIB = PERL_SRC/lib
1728 PERL_ARCHLIB = PERL_SRC/lib
1730 INST_ARCHLIB = PERL_ARCHLIB
1732 If an extension is being built away from the perl source then MakeMaker
1733 will leave PERL_SRC undefined and default to using the installed copy
1734 of the perl library. The other variables default to the following:
1736 PERL_INC = $archlibexp/CORE
1737 PERL_LIB = $privlibexp
1738 PERL_ARCHLIB = $archlibexp
1739 INST_LIB = ./blib/lib
1740 INST_ARCHLIB = ./blib/arch
1742 If perl has not yet been installed then PERL_SRC can be defined on the
1743 command line as shown in the previous section.
1746 =head2 Which architecture dependent directory?
1748 If you don't want to keep the defaults for the INSTALL* macros,
1749 MakeMaker helps you to minimize the typing needed: the usual
1750 relationship between INSTALLPRIVLIB and INSTALLARCHLIB is determined
1751 by Configure at perl compilation time. MakeMaker supports the user who
1752 sets INSTALLPRIVLIB. If INSTALLPRIVLIB is set, but INSTALLARCHLIB not,
1753 then MakeMaker defaults the latter to be the same subdirectory of
1754 INSTALLPRIVLIB as Configure decided for the counterparts in %Config,
1755 otherwise it defaults to INSTALLPRIVLIB. The same relationship holds
1756 for INSTALLSITELIB and INSTALLSITEARCH.
1758 MakeMaker gives you much more freedom than needed to configure
1759 internal variables and get different results. It is worth mentioning
1760 that make(1) also lets you configure most of the variables that are
1761 used in the Makefile. But in the majority of situations this will not
1762 be necessary, and should only be done if the author of a package
1763 recommends it (or you know what you're doing).
1765 =head2 Using Attributes and Parameters
1767 The following attributes may be specified as arguments to WriteMakefile()
1768 or as NAME=VALUE pairs on the command line. Attributes that became
1769 available with later versions of MakeMaker are indicated.
1771 In order to maintain portability of attributes with older versions of
1772 MakeMaker you may want to use L<App::EUMM::Upgrade> with your C<Makefile.PL>.
1778 One line description of the module. Will be included in PPD file.
1782 Name of the file that contains the package description. MakeMaker looks
1783 for a line in the POD matching /^($package\s-\s)(.*)/. This is typically
1784 the first line in the "=head1 NAME" section. $2 becomes the abstract.
1788 Array of strings containing name (and email address) of package author(s).
1789 Is used in CPAN Meta files (META.yml or META.json) and PPD
1790 (Perl Package Description) files for PPM (Perl Package Manager).
1792 =item BINARY_LOCATION
1794 Used when creating PPD files for binary packages. It can be set to a
1795 full or relative path or URL to the binary archive for a particular
1796 architecture. For example:
1798 perl Makefile.PL BINARY_LOCATION=x86/Agent.tar.gz
1800 builds a PPD package that references a binary of the C<Agent> package,
1801 located in the C<x86> directory relative to the PPD itself.
1803 =item BUILD_REQUIRES
1805 Available in version 6.55_03 and above.
1807 A hash of modules that are needed to build your module but not run it.
1809 This will go into the C<build_requires> field of your F<META.yml> and the C<build> of the C<prereqs> field of your F<META.json>.
1811 Defaults to C<<< { "ExtUtils::MakeMaker" => 0 } >>> if this attribute is not specified.
1813 The format is the same as PREREQ_PM.
1817 Ref to array of *.c file names. Initialised from a directory scan
1818 and the values portion of the XS attribute hash. This is not
1819 currently used by MakeMaker but may be handy in Makefile.PLs.
1823 String that will be included in the compiler call command line between
1824 the arguments INC and OPTIMIZE. Note that setting this will overwrite its
1825 default value (C<$Config::Config{ccflags}>); to preserve that, include
1826 the default value directly, e.g.:
1828 CCFLAGS => "$Config::Config{ccflags} ..."
1832 Arrayref. E.g. [qw(archname manext)] defines ARCHNAME & MANEXT from
1833 config.sh. MakeMaker will add to CONFIG the following values anyway:
1854 CODE reference. The subroutine should return a hash reference. The
1855 hash may contain further attributes, e.g. {LIBS =E<gt> ...}, that have to
1856 be determined by some evaluation method.
1858 =item CONFIGURE_REQUIRES
1860 Available in version 6.52 and above.
1862 A hash of modules that are required to run Makefile.PL itself, but not
1863 to run your distribution.
1865 This will go into the C<configure_requires> field of your F<META.yml> and the C<configure> of the C<prereqs> field of your F<META.json>.
1867 Defaults to C<<< { "ExtUtils::MakeMaker" => 0 } >>> if this attribute is not specified.
1869 The format is the same as PREREQ_PM.
1873 Something like C<"-DHAVE_UNISTD_H">
1877 This is the root directory into which the code will be installed. It
1878 I<prepends itself to the normal prefix>. For example, if your code
1879 would normally go into F</usr/local/lib/perl> you could set DESTDIR=~/tmp/
1880 and installation would go into F<~/tmp/usr/local/lib/perl>.
1882 This is primarily of use for people who repackage Perl modules.
1884 NOTE: Due to the nature of make, it is important that you put the trailing
1885 slash on your DESTDIR. F<~/tmp/> not F<~/tmp>.
1889 Ref to array of subdirectories containing Makefile.PLs e.g. ['sdbm']
1894 A safe filename for the package.
1896 Defaults to NAME below but with :: replaced with -.
1898 For example, Foo::Bar becomes Foo-Bar.
1902 Your name for distributing the package with the version number
1903 included. This is used by 'make dist' to name the resulting archive
1906 Defaults to DISTNAME-VERSION.
1908 For example, version 1.04 of Foo::Bar becomes Foo-Bar-1.04.
1910 On some OS's where . has special meaning VERSION_SYM may be used in
1915 Specifies the extension of the module's loadable object. For example:
1917 DLEXT => 'unusual_ext', # Default value is $Config{so}
1919 NOTE: When using this option to alter the extension of a module's
1920 loadable object, it is also necessary that the module's pm file
1921 specifies the same change:
1923 local $DynaLoader::dl_dlext = 'unusual_ext';
1927 Hashref of symbol names for routines to be made available as universal
1928 symbols. Each key/value pair consists of the package name and an
1929 array of routine names in that package. Used only under AIX, OS/2,
1930 VMS and Win32 at present. The routine names supplied will be expanded
1931 in the same way as XSUB names are expanded by the XS() macro.
1934 {"$(NAME)" => ["boot_$(NAME)" ] }
1938 {"RPC" => [qw( boot_rpcb rpcb_gettime getnetconfigent )],
1939 "NetconfigPtr" => [ 'DESTROY'] }
1941 Please see the L<ExtUtils::Mksymlists> documentation for more information
1942 about the DL_FUNCS, DL_VARS and FUNCLIST attributes.
1946 Array of symbol names for variables to be made available as universal symbols.
1947 Used only under AIX, OS/2, VMS and Win32 at present. Defaults to [].
1948 (e.g. [ qw(Foo_version Foo_numstreams Foo_tree ) ])
1952 Array of extension names to exclude when doing a static build. This
1953 is ignored if INCLUDE_EXT is present. Consult INCLUDE_EXT for more
1954 details. (e.g. [ qw( Socket POSIX ) ] )
1956 This attribute may be most useful when specified as a string on the
1957 command line: perl Makefile.PL EXCLUDE_EXT='Socket Safe'
1961 Ref to array of executable files. The files will be copied to the
1962 INST_SCRIPT directory. Make realclean will delete them from there
1965 If your executables start with something like #!perl or
1966 #!/usr/bin/perl MakeMaker will change this to the path of the perl
1967 'Makefile.PL' was invoked with so the programs will be sure to run
1968 properly even if perl is not in /usr/bin/perl.
1970 =item FIRST_MAKEFILE
1972 The name of the Makefile to be produced. This is used for the second
1973 Makefile that will be produced for the MAP_TARGET.
1975 Defaults to 'Makefile' or 'Descrip.MMS' on VMS.
1977 (Note: we couldn't use MAKEFILE because dmake uses this for something
1982 Perl binary able to run this extension, load XS modules, etc...
1986 Like PERLRUN, except it uses FULLPERL.
1988 =item FULLPERLRUNINST
1990 Like PERLRUNINST, except it uses FULLPERL.
1994 This provides an alternate means to specify function names to be
1995 exported from the extension. Its value is a reference to an
1996 array of function names to be exported by the extension. These
1997 names are passed through unaltered to the linker options file.
2001 Ref to array of *.h file names. Similar to C.
2005 This attribute is used to specify names to be imported into the
2006 extension. Takes a hash ref.
2008 It is only used on OS/2 and Win32.
2012 Include file dirs eg: C<"-I/usr/5include -I/path/to/inc">
2016 Array of extension names to be included when doing a static build.
2017 MakeMaker will normally build with all of the installed extensions when
2018 doing a static build, and that is usually the desired behavior. If
2019 INCLUDE_EXT is present then MakeMaker will build only with those extensions
2020 which are explicitly mentioned. (e.g. [ qw( Socket POSIX ) ])
2022 It is not necessary to mention DynaLoader or the current extension when
2023 filling in INCLUDE_EXT. If the INCLUDE_EXT is mentioned but is empty then
2024 only DynaLoader and the current extension will be included in the build.
2026 This attribute may be most useful when specified as a string on the
2027 command line: perl Makefile.PL INCLUDE_EXT='POSIX Socket Devel::Peek'
2029 =item INSTALLARCHLIB
2031 Used by 'make install', which copies files from INST_ARCHLIB to this
2032 directory if INSTALLDIRS is set to perl.
2036 Directory to install binary files (e.g. tkperl) into if
2041 Determines which of the sets of installation directories to choose:
2042 perl, site or vendor. Defaults to site.
2044 =item INSTALLMAN1DIR
2046 =item INSTALLMAN3DIR
2048 These directories get the man pages at 'make install' time if
2049 INSTALLDIRS=perl. Defaults to $Config{installman*dir}.
2051 If set to 'none', no man pages will be installed.
2053 =item INSTALLPRIVLIB
2055 Used by 'make install', which copies files from INST_LIB to this
2056 directory if INSTALLDIRS is set to perl.
2058 Defaults to $Config{installprivlib}.
2062 Available in version 6.30_02 and above.
2064 Used by 'make install' which copies files from INST_SCRIPT to this
2065 directory if INSTALLDIRS=perl.
2067 =item INSTALLSITEARCH
2069 Used by 'make install', which copies files from INST_ARCHLIB to this
2070 directory if INSTALLDIRS is set to site (default).
2072 =item INSTALLSITEBIN
2074 Used by 'make install', which copies files from INST_BIN to this
2075 directory if INSTALLDIRS is set to site (default).
2077 =item INSTALLSITELIB
2079 Used by 'make install', which copies files from INST_LIB to this
2080 directory if INSTALLDIRS is set to site (default).
2082 =item INSTALLSITEMAN1DIR
2084 =item INSTALLSITEMAN3DIR
2086 These directories get the man pages at 'make install' time if
2087 INSTALLDIRS=site (default). Defaults to
2088 $(SITEPREFIX)/man/man$(MAN*EXT).
2090 If set to 'none', no man pages will be installed.
2092 =item INSTALLSITESCRIPT
2094 Used by 'make install' which copies files from INST_SCRIPT to this
2095 directory if INSTALLDIRS is set to site (default).
2097 =item INSTALLVENDORARCH
2099 Used by 'make install', which copies files from INST_ARCHLIB to this
2100 directory if INSTALLDIRS is set to vendor. Note that if you do not set
2101 this, the value of INSTALLVENDORLIB will be used, which is probably not
2104 =item INSTALLVENDORBIN
2106 Used by 'make install', which copies files from INST_BIN to this
2107 directory if INSTALLDIRS is set to vendor.
2109 =item INSTALLVENDORLIB
2111 Used by 'make install', which copies files from INST_LIB to this
2112 directory if INSTALLDIRS is set to vendor.
2114 =item INSTALLVENDORMAN1DIR
2116 =item INSTALLVENDORMAN3DIR
2118 These directories get the man pages at 'make install' time if
2119 INSTALLDIRS=vendor. Defaults to $(VENDORPREFIX)/man/man$(MAN*EXT).
2121 If set to 'none', no man pages will be installed.
2123 =item INSTALLVENDORSCRIPT
2125 Available in version 6.30_02 and above.
2127 Used by 'make install' which copies files from INST_SCRIPT to this
2128 directory if INSTALLDIRS is set to vendor.
2132 Same as INST_LIB for architecture dependent files.
2136 Directory to put real binary files during 'make'. These will be copied
2137 to INSTALLBIN during 'make install'
2141 Directory where we put library files of this extension while building
2146 Directory to hold the man pages at 'make' time
2150 Directory to hold the man pages at 'make' time
2154 Directory where executable files should be installed during
2155 'make'. Defaults to "./blib/script", just to have a dummy location during
2156 testing. make install will copy the files in INST_SCRIPT to
2161 Program to be used to link libraries for dynamic loading.
2163 Defaults to $Config{ld}.
2167 Any special flags that might need to be passed to ld to create a
2168 shared library suitable for dynamic loading. It is up to the makefile
2169 to use it. (See L<Config/lddlflags>)
2171 Defaults to $Config{lddlflags}.
2175 Defaults to "$(OBJECT)" and is used in the ld command to specify
2176 what files to link/load from (also see dynamic_lib below for how to
2181 LIB should only be set at C<perl Makefile.PL> time but is allowed as a
2182 MakeMaker argument. It has the effect of setting both INSTALLPRIVLIB
2183 and INSTALLSITELIB to that value regardless any explicit setting of
2184 those arguments (or of PREFIX). INSTALLARCHLIB and INSTALLSITEARCH
2185 are set to the corresponding architecture subdirectory.
2189 The filename of the perllibrary that will be used together with this
2190 extension. Defaults to libperl.a.
2194 An anonymous array of alternative library
2195 specifications to be searched for (in order) until
2196 at least one library is found. E.g.
2198 'LIBS' => ["-lgdbm", "-ldbm -lfoo", "-L/path -ldbm.nfs"]
2200 Mind, that any element of the array
2201 contains a complete set of arguments for the ld
2202 command. So do not specify
2204 'LIBS' => ["-ltcl", "-ltk", "-lX11"]
2206 See ODBM_File/Makefile.PL for an example, where an array is needed. If
2207 you specify a scalar as in
2209 'LIBS' => "-ltcl -ltk -lX11"
2211 MakeMaker will turn it into an array with one element.
2215 Available in version 6.31 and above.
2217 The licensing terms of your distribution. Generally it's "perl_5" for the
2218 same license as Perl itself.
2220 See L<CPAN::Meta::Spec> for the list of options.
2222 Defaults to "unknown".
2226 'static' or 'dynamic' (default unless usedl=undef in
2227 config.sh). Should only be used to force static linking (also see
2232 Available in version 6.8305 and above.
2234 When this is set to C<1>, C<OBJECT> will be automagically derived from
2239 Available in version 6.30_01 and above.
2241 Variant of make you intend to run the generated Makefile with. This
2242 parameter lets Makefile.PL know what make quirks to account for when
2243 generating the Makefile.
2245 MakeMaker also honors the MAKE environment variable. This parameter
2248 Currently the only significant values are 'dmake' and 'nmake' for Windows
2249 users, instructing MakeMaker to generate a Makefile in the flavour of
2250 DMake ("Dennis Vadura's Make") or Microsoft NMake respectively.
2252 Defaults to $Config{make}, which may go looking for a Make program
2253 in your environment.
2255 How are you supposed to know what flavour of Make a Makefile has
2256 been generated for if you didn't specify a value explicitly? Search
2257 the generated Makefile for the definition of the MAKE variable,
2258 which is used to recursively invoke the Make utility. That will tell
2259 you what Make you're supposed to invoke the Makefile with.
2263 Boolean which tells MakeMaker that it should include the rules to
2264 make a perl. This is handled automatically as a switch by
2265 MakeMaker. The user normally does not need it.
2269 When 'make clean' or similar is run, the $(FIRST_MAKEFILE) will be
2270 backed up at this location.
2272 Defaults to $(FIRST_MAKEFILE).old or $(FIRST_MAKEFILE)_old on VMS.
2276 Hashref of pod-containing files. MakeMaker will default this to all
2277 EXE_FILES files that include POD directives. The files listed
2278 here will be converted to man pages and installed as was requested
2281 This hash should map POD files (or scripts containing POD) to the
2282 man file names under the C<blib/man1/> directory, as in the following
2286 'doc/command.pod' => 'blib/man1/command.1',
2287 'scripts/script.pl' => 'blib/man1/script.1',
2292 Hashref that assigns to *.pm and *.pod files the files into which the
2293 manpages are to be written. MakeMaker parses all *.pod and *.pm files
2294 for POD directives. Files that contain POD will be the default keys of
2295 the MAN3PODS hashref. These will then be converted to man pages during
2296 C<make> and will be installed during C<make install>.
2298 Example similar to MAN1PODS.
2302 If it is intended that a new perl binary be produced, this variable
2303 may hold a name for that binary. Defaults to perl
2309 Available in version 6.46 and above.
2311 A hashref of items to add to the CPAN Meta file (F<META.yml> or
2314 They differ in how they behave if they have the same key as the
2315 default metadata. META_ADD will override the default value with its
2316 own. META_MERGE will merge its value with the default.
2318 Unless you want to override the defaults, prefer META_MERGE so as to
2319 get the advantage of any future defaults.
2321 Where prereqs are concerned, if META_MERGE is used, prerequisites are merged
2322 with their counterpart C<WriteMakefile()> argument
2323 (PREREQ_PM is merged into {prereqs}{runtime}{requires},
2324 BUILD_REQUIRES into C<{prereqs}{build}{requires}>,
2325 CONFIGURE_REQUIRES into C<{prereqs}{configure}{requires}>,
2326 and TEST_REQUIRES into C<{prereqs}{test}{requires})>.
2327 When prereqs are specified with META_ADD, the only prerequisites added to the
2328 file come from the metadata, not C<WriteMakefile()> arguments.
2330 Note that these configuration options are only used for generating F<META.yml>
2331 and F<META.json> -- they are NOT used for F<MYMETA.yml> and F<MYMETA.json>.
2332 Therefore data in these fields should NOT be used for dynamic (user-side)
2335 By default CPAN Meta specification C<1.4> is used. In order to use
2336 CPAN Meta specification C<2.0>, indicate with C<meta-spec> the version
2341 "meta-spec" => { version => 2 },
2347 url => 'git://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker.git',
2348 web => 'https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker',
2355 =item MIN_PERL_VERSION
2357 Available in version 6.48 and above.
2359 The minimum required version of Perl for this distribution.
2361 Either the 5.006001 or the 5.6.1 format is acceptable.
2365 If the extension links to a library that it builds, set this to the
2366 name of the library (see SDBM_File)
2370 The package representing the distribution. For example, C<Test::More>
2371 or C<ExtUtils::MakeMaker>. It will be used to derive information about
2372 the distribution such as the L</DISTNAME>, installation locations
2373 within the Perl library and where XS files will be looked for by
2374 default (see L</XS>).
2376 C<NAME> I<must> be a valid Perl package name and it I<must> have an
2377 associated C<.pm> file. For example, C<Foo::Bar> is a valid C<NAME>
2378 and there must exist F<Foo/Bar.pm>. Any XS code should be in
2379 F<Bar.xs> unless stated otherwise.
2381 Your distribution B<must> have a C<NAME>.
2385 MakeMaker will figure out if an extension contains linkable code
2386 anywhere down the directory tree, and will set this variable
2387 accordingly, but you can speed it up a very little bit if you define
2388 this boolean variable yourself.
2392 Command so make does not print the literal commands it's running.
2394 By setting it to an empty string you can generate a Makefile that
2395 prints all commands. Mainly used in debugging MakeMaker itself.
2401 Boolean. Attribute to inhibit descending into subdirectories.
2405 When true, suppresses the generation and addition to the MANIFEST of
2406 the META.yml and META.json module meta-data files during 'make distdir'.
2412 Available in version 6.57_02 and above.
2414 When true, suppresses the generation of MYMETA.yml and MYMETA.json module
2415 meta-data files during 'perl Makefile.PL'.
2421 Available in version 6.7501 and above.
2423 When true, suppresses the writing of C<packlist> files for installs.
2429 Available in version 6.7501 and above.
2431 When true, suppresses the appending of installations to C<perllocal>.
2437 In general, any generated Makefile checks for the current version of
2438 MakeMaker and the version the Makefile was built under. If NO_VC is
2439 set, the version check is neglected. Do not write this into your
2440 Makefile.PL, use it interactively instead.
2444 List of object files, defaults to '$(BASEEXT)$(OBJ_EXT)', but can be a long
2445 string or an array containing all object files, e.g. "tkpBind.o
2446 tkpButton.o tkpCanvas.o" or ["tkpBind.o", "tkpButton.o", "tkpCanvas.o"]
2448 (Where BASEEXT is the last component of NAME, and OBJ_EXT is $Config{obj_ext}.)
2452 Defaults to C<-O>. Set it to C<-g> to turn debugging on. The flag is
2453 passed to subdirectory makes.
2457 Perl binary for tasks that can be done by miniperl. If it contains
2458 spaces or other shell metacharacters, it needs to be quoted in a way
2459 that protects them, since this value is intended to be inserted in a
2460 shell command line in the Makefile. E.g.:
2462 # Perl executable lives in "C:/Program Files/Perl/bin"
2463 # Normally you don't need to set this yourself!
2464 $ perl Makefile.PL PERL='"C:/Program Files/Perl/bin/perl.exe" -w'
2468 Set only when MakeMaker is building the extensions of the Perl core
2473 The call to the program that is able to compile perlmain.c. Defaults
2478 Same as for PERL_LIB, but for architecture dependent files.
2480 Used only when MakeMaker is building the extensions of the Perl core
2481 distribution (because normally $(PERL_ARCHLIB) is automatically in @INC,
2482 and adding it would get in the way of PERL5LIB).
2486 Directory containing the Perl library to use.
2488 Used only when MakeMaker is building the extensions of the Perl core
2489 distribution (because normally $(PERL_LIB) is automatically in @INC,
2490 and adding it would get in the way of PERL5LIB).
2492 =item PERL_MALLOC_OK
2494 defaults to 0. Should be set to TRUE if the extension can work with
2495 the memory allocation routines substituted by the Perl malloc() subsystem.
2496 This should be applicable to most extensions with exceptions of those
2502 with bugs in memory allocations which are caught by Perl's malloc();
2506 which interact with the memory allocator in other ways than via
2507 malloc(), realloc(), free(), calloc(), sbrk() and brk();
2511 which rely on special alignment which is not provided by Perl's malloc().
2515 B<NOTE.> Neglecting to set this flag in I<any one> of the loaded extension
2516 nullifies many advantages of Perl's malloc(), such as better usage of
2517 system resources, error detection, memory usage reporting, catchable failure
2518 of memory allocations, etc.
2522 Directory under which core modules are to be installed.
2524 Defaults to $Config{installprefixexp}, falling back to
2525 $Config{installprefix}, $Config{prefixexp} or $Config{prefix} should
2526 $Config{installprefixexp} not exist.
2528 Overridden by PREFIX.
2532 Use this instead of $(PERL) when you wish to run perl. It will set up
2533 extra necessary flags for you.
2537 Use this instead of $(PERL) when you wish to run perl to work with
2538 modules. It will add things like -I$(INST_ARCH) and other necessary
2539 flags so perl can see the modules you're about to install.
2543 Directory containing the Perl source code (use of this should be
2544 avoided, it may be undefined)
2548 Available in version 6.51_01 and above.
2550 Desired permission for directories. Defaults to C<755>.
2554 Desired permission for read/writable files. Defaults to C<644>.
2558 Desired permission for executable files. Defaults to C<755>.
2562 MakeMaker can run programs to generate files for you at build time.
2563 By default any file named *.PL (except Makefile.PL and Build.PL) in
2564 the top level directory will be assumed to be a Perl program and run
2565 passing its own basename in as an argument. This basename is actually a build
2566 target, and there is an intention, but not a requirement, that the *.PL file
2567 make the file passed to to as an argument. For example...
2571 This behavior can be overridden by supplying your own set of files to
2572 search. PL_FILES accepts a hash ref, the key being the file to run
2573 and the value is passed in as the first argument when the PL file is run.
2575 PL_FILES => {'bin/foobar.PL' => 'bin/foobar'}
2577 PL_FILES => {'foo.PL' => 'foo.c'}
2579 Would run bin/foobar.PL like this:
2581 perl bin/foobar.PL bin/foobar
2583 If multiple files from one program are desired an array ref can be used.
2585 PL_FILES => {'bin/foobar.PL' => [qw(bin/foobar1 bin/foobar2)]}
2587 In this case the program will be run multiple times using each target file.
2589 perl bin/foobar.PL bin/foobar1
2590 perl bin/foobar.PL bin/foobar2
2592 If an output file depends on extra input files beside the script itself,
2593 a hash ref can be used in version 7.36 and above:
2595 PL_FILES => { 'foo.PL' => {
2596 'foo.out' => 'foo.in',
2597 'bar.out' => [qw(bar1.in bar2.in)],
2600 In this case the extra input files will be passed to the program after
2603 perl foo.PL foo.out foo.in
2604 perl foo.PL bar.out bar1.in bar2.in
2606 PL files are normally run B<after> pm_to_blib and include INST_LIB and
2607 INST_ARCH in their C<@INC>, so the just built modules can be
2608 accessed... unless the PL file is making a module (or anything else in
2609 PM) in which case it is run B<before> pm_to_blib and does not include
2610 INST_LIB and INST_ARCH in its C<@INC>. This apparently odd behavior
2611 is there for backwards compatibility (and it's somewhat DWIM). The argument
2612 passed to the .PL is set up as a target to build in the Makefile. In other
2613 sections such as C<postamble> you can specify a dependency on the
2614 filename/argument that the .PL is supposed (or will have, now that that is
2615 is a dependency) to generate. Note the file to be generated will still be
2616 generated and the .PL will still run even without an explicit dependency created
2617 by you, since the C<all> target still depends on running all eligible to run.PL
2622 Hashref of .pm files and *.pl files to be installed. e.g.
2624 {'name_of_file.pm' => '$(INST_LIB)/install_as.pm'}
2626 By default this will include *.pm and *.pl and the files found in
2627 the PMLIBDIRS directories. Defining PM in the
2628 Makefile.PL will override PMLIBDIRS.
2632 Ref to array of subdirectories containing library files. Defaults to
2633 [ 'lib', $(BASEEXT) ]. The directories will be scanned and I<any> files
2634 they contain will be installed in the corresponding location in the
2635 library. A libscan() method can be used to alter the behaviour.
2636 Defining PM in the Makefile.PL will override PMLIBDIRS.
2638 (Where BASEEXT is the last component of NAME.)
2642 A filter program, in the traditional Unix sense (input from stdin, output
2643 to stdout) that is passed on each .pm file during the build (in the
2644 pm_to_blib() phase). It is empty by default, meaning no filtering is done.
2647 PM_FILTER => 'perl -ne "print unless /^\\#/"',
2649 to remove all the leading comments on the fly during the build. In order
2650 to be as portable as possible, please consider using a Perl one-liner
2651 rather than Unix (or other) utilities, as above. The # is escaped for
2652 the Makefile, since what is going to be generated will then be:
2654 PM_FILTER = perl -ne "print unless /^\#/"
2656 Without the \ before the #, we'd have the start of a Makefile comment,
2657 and the macro would be incorrectly defined.
2659 You will almost certainly be better off using the C<PL_FILES> system,
2660 instead. See above, or the L<ExtUtils::MakeMaker::FAQ> entry.
2664 Prior to 5.6 various interpreter variables were available without a C<PL_>
2665 prefix, eg. C<PL_undef> was available as C<undef>. As of release 5.6, these
2666 are only defined if the POLLUTE flag is enabled:
2668 perl Makefile.PL POLLUTE=1
2670 Please inform the module author if this is necessary to successfully install
2671 a module under 5.6 or later.
2673 =item PPM_INSTALL_EXEC
2675 Name of the executable used to run C<PPM_INSTALL_SCRIPT> below. (e.g. perl)
2677 =item PPM_INSTALL_SCRIPT
2679 Name of the script that gets executed by the Perl Package Manager after
2680 the installation of a package.
2682 =item PPM_UNINSTALL_EXEC
2684 Available in version 6.8502 and above.
2686 Name of the executable used to run C<PPM_UNINSTALL_SCRIPT> below. (e.g. perl)
2688 =item PPM_UNINSTALL_SCRIPT
2690 Available in version 6.8502 and above.
2692 Name of the script that gets executed by the Perl Package Manager before
2693 the removal of a package.
2697 This overrides all the default install locations. Man pages,
2698 libraries, scripts, etc... MakeMaker will try to make an educated
2699 guess about where to place things under the new PREFIX based on your
2700 Config defaults. Failing that, it will fall back to a structure
2701 which should be sensible for your platform.
2703 If you specify LIB or any INSTALL* variables they will not be affected
2708 Bool. If this parameter is true, failing to have the required modules
2709 (or the right versions thereof) will be fatal. C<perl Makefile.PL>
2710 will C<die> instead of simply informing the user of the missing dependencies.
2712 It is I<extremely> rare to have to use C<PREREQ_FATAL>. Its use by module
2713 authors is I<strongly discouraged> and should never be used lightly.
2715 For dependencies that are required in order to run C<Makefile.PL>,
2716 see C<CONFIGURE_REQUIRES>.
2718 Module installation tools have ways of resolving unmet dependencies but
2719 to do that they need a F<Makefile>. Using C<PREREQ_FATAL> breaks this.
2722 Assuming you have good test coverage, your tests should fail with
2723 missing dependencies informing the user more strongly that something
2724 is wrong. You can write a F<t/00compile.t> test which will simply
2725 check that your code compiles and stop "make test" prematurely if it
2726 doesn't. See L<Test::More/BAIL_OUT> for more details.
2731 A hash of modules that are needed to run your module. The keys are
2732 the module names ie. Test::More, and the minimum version is the
2733 value. If the required version number is 0 any version will do.
2734 The versions given may be a Perl v-string (see L<version>) or a range
2735 (see L<CPAN::Meta::Requirements>).
2737 This will go into the C<requires> field of your F<META.yml> and the
2738 C<runtime> of the C<prereqs> field of your F<META.json>.
2741 # Require Test::More at least 0.47
2742 "Test::More" => "0.47",
2744 # Require any version of Acme::Buffy
2750 Bool. If this parameter is true, the prerequisites will be printed to
2751 stdout and MakeMaker will exit. The output format is an evalable hash
2760 If a distribution defines a minimal required perl version, this is
2761 added to the output as an additional line of the form:
2763 $MIN_PERL_VERSION = '5.008001';
2765 If BUILD_REQUIRES is not empty, it will be dumped as $BUILD_REQUIRES hashref.
2769 RedHatism for C<PREREQ_PRINT>. The output format is different, though:
2771 perl(A::B)>=Vers1 perl(C::D)>=Vers2 ...
2773 A minimal required perl version, if present, will look like this:
2775 perl(perl)>=5.008001
2779 Like PERLPREFIX, but only for the site install locations.
2781 Defaults to $Config{siteprefixexp}. Perls prior to 5.6.0 didn't have
2782 an explicit siteprefix in the Config. In those cases
2783 $Config{installprefix} will be used.
2785 Overridable by PREFIX
2789 Available in version 6.18 and above.
2791 When true, perform the generation and addition to the MANIFEST of the
2792 SIGNATURE file in the distdir during 'make distdir', via 'cpansign
2795 Note that you need to install the Module::Signature module to
2796 perform this operation.
2802 Arrayref. E.g. [qw(name1 name2)] skip (do not write) sections of the
2803 Makefile. Caution! Do not use the SKIP attribute for the negligible
2804 speedup. It may seriously damage the resulting Makefile. Only use it
2805 if you really need it.
2809 Available in version 6.64 and above.
2811 A hash of modules that are needed to test your module but not run or
2814 This will go into the C<build_requires> field of your F<META.yml> and the C<test> of the C<prereqs> field of your F<META.json>.
2816 The format is the same as PREREQ_PM.
2820 Ref to array of typemap file names. Use this when the typemaps are
2821 in some directory other than the current directory or when they are
2822 not named B<typemap>. The last typemap in the list takes
2823 precedence. A typemap in the current directory has highest
2824 precedence, even if it isn't listed in TYPEMAPS. The default system
2825 typemap has lowest precedence.
2829 Like PERLPREFIX, but only for the vendor install locations.
2831 Defaults to $Config{vendorprefixexp}.
2833 Overridable by PREFIX
2837 If true, make install will be verbose
2841 Your version number for distributing the package. This defaults to
2846 Instead of specifying the VERSION in the Makefile.PL you can let
2847 MakeMaker parse a file to determine the version number. The parsing
2848 routine requires that the file named by VERSION_FROM contains one
2849 single line to compute the version number. The first line in the file
2850 that contains something like a $VERSION assignment or C<package Name
2851 VERSION> will be used. The following lines will be parsed o.k.:
2854 package Foo::Bar 1.23; # 1.23
2855 $VERSION = '1.00'; # 1.00
2856 *VERSION = \'1.01'; # 1.01
2857 ($VERSION) = q$Revision$ =~ /(\d+)/g; # The digits in $Revision$
2858 $FOO::VERSION = '1.10'; # 1.10
2859 *FOO::VERSION = \'1.11'; # 1.11
2861 but these will fail:
2864 my $VERSION = '1.01';
2865 local $VERSION = '1.02';
2866 local $FOO::VERSION = '1.30';
2868 (Putting C<my> or C<local> on the preceding line will work o.k.)
2870 "Version strings" are incompatible and should not be used.
2876 L<version> objects are fine. As of MakeMaker 6.35 version.pm will be
2877 automatically loaded, but you must declare the dependency on version.pm.
2878 For compatibility with older MakeMaker you should load on the same line
2879 as $VERSION is declared.
2882 use version; our $VERSION = qv(1.2.3);
2884 The file named in VERSION_FROM is not added as a dependency to
2885 Makefile. This is not really correct, but it would be a major pain
2886 during development to have to rewrite the Makefile for any smallish
2887 change in that file. If you want to make sure that the Makefile
2888 contains the correct VERSION macro after any change of the file, you
2889 would have to do something like
2891 depend => { Makefile => '$(VERSION_FROM)' }
2893 See attribute C<depend> below.
2897 A sanitized VERSION with . replaced by _. For places where . has
2898 special meaning (some filesystems, RCS labels, etc...)
2902 Hashref of .xs files. MakeMaker will default this. e.g.
2904 {'name_of_file.xs' => 'name_of_file.c'}
2906 The .c files will automatically be included in the list of files
2907 deleted by a make clean.
2911 Available in version 7.12 and above.
2913 Hashref with options controlling the operation of C<XSMULTI>:
2918 # options applying to all .xs files for this distribution
2920 'lib/Class/Name/File' => { # specifically for this file
2921 DEFINE => '-Dfunktastic', # defines for only this file
2922 INC => "-I$funkyliblocation", # include flags for only this file
2923 # OBJECT => 'lib/Class/Name/File$(OBJ_EXT)', # default
2924 LDFROM => "lib/Class/Name/File\$(OBJ_EXT) $otherfile\$(OBJ_EXT)", # what's linked
2929 Note C<xs> is the file-extension. More possibilities may arise in the
2930 future. Note that object names are specified without their XS extension.
2932 C<LDFROM> defaults to the same as C<OBJECT>. C<OBJECT> defaults to,
2933 for C<XSMULTI>, just the XS filename with the extension replaced with
2934 the compiler-specific object-file extension.
2936 The distinction between C<OBJECT> and C<LDFROM>: C<OBJECT> is the make
2937 target, so make will try to build it. However, C<LDFROM> is what will
2938 actually be linked together to make the shared object or static library
2939 (SO/SL), so if you override it, make sure it includes what you want to
2940 make the final SO/SL, almost certainly including the XS basename with
2941 C<$(OBJ_EXT)> appended.
2945 Available in version 7.12 and above.
2947 When this is set to C<1>, multiple XS files may be placed under F<lib/>
2948 next to their corresponding C<*.pm> files (this is essential for compiling
2949 with the correct C<VERSION> values). This feature should be considered
2950 experimental, and details of it may change.
2952 This feature was inspired by, and small portions of code copied from,
2953 L<ExtUtils::MakeMaker::BigHelper>. Hopefully this feature will render
2954 that module mainly obsolete.
2958 String of options to pass to xsubpp. This might include C<-C++> or
2959 C<-extern>. Do not include typemaps here; the TYPEMAP parameter exists for
2964 May be set to C<-prototypes>, C<-noprototypes> or the empty string. The
2965 empty string is equivalent to the xsubpp default, or C<-noprototypes>.
2966 See the xsubpp documentation for details. MakeMaker
2967 defaults to the empty string.
2971 Your version number for the .xs file of this package. This defaults
2972 to the value of the VERSION attribute.
2976 =head2 Additional lowercase attributes
2978 can be used to pass parameters to the methods which implement that
2979 part of the Makefile. Parameters are specified as a hash ref but are
2980 passed to the method as a hash.
2986 {FILES => "*.xyz foo"}
2990 {ANY_TARGET => ANY_DEPENDENCY, ...}
2992 (ANY_TARGET must not be given a double-colon rule by MakeMaker.)
2996 {TARFLAGS => 'cvfF', COMPRESS => 'gzip', SUFFIX => '.gz',
2997 SHAR => 'shar -m', DIST_CP => 'ln', ZIP => '/bin/zip',
2998 ZIPFLAGS => '-rl', DIST_DEFAULT => 'private tardist' }
3000 If you specify COMPRESS, then SUFFIX should also be altered, as it is
3001 needed to tell make the target file of the compression. Setting
3002 DIST_CP to ln can be useful, if you need to preserve the timestamps on
3003 your files. DIST_CP can take the values 'cp', which copies the file,
3004 'ln', which links the file, and 'best' which copies symbolic links and
3005 links the rest. Default is 'best'.
3009 {ARMAYBE => 'ar', OTHERLDFLAGS => '...', INST_DYNAMIC_DEP => '...'}
3013 {LINKTYPE => 'static', 'dynamic' or ''}
3015 NB: Extensions that have nothing but *.pm files had to say
3019 with Pre-5.0 MakeMakers. Since version 5.00 of MakeMaker such a line
3020 can be deleted safely. MakeMaker recognizes when there's nothing to
3025 {ANY_MACRO => ANY_VALUE, ...}
3029 Anything put here will be passed to
3030 L<MY::postamble()|ExtUtils::MM_Any/postamble (o)> if you have one.
3034 {FILES => '$(INST_ARCHAUTODIR)/*.xyz'}
3038 Specify the targets for testing.
3042 C<RECURSIVE_TEST_FILES> can be used to include all directories
3043 recursively under C<t> that contain C<.t> files. It will be ignored if
3044 you provide your own C<TESTS> attribute, defaults to false.
3046 {RECURSIVE_TEST_FILES=>1}
3048 This is supported since 6.76
3050 =item tool_autosplit
3056 =head2 Overriding MakeMaker Methods
3058 If you cannot achieve the desired Makefile behaviour by specifying
3059 attributes you may define private subroutines in the Makefile.PL.
3060 Each subroutine returns the text it wishes to have written to
3061 the Makefile. To override a section of the Makefile you can
3064 sub MY::c_o { "new literal text" }
3066 or you can edit the default by saying something like:
3068 package MY; # so that "SUPER" works right
3070 my $inherited = shift->SUPER::c_o(@_);
3071 $inherited =~ s/old text/new text/;
3075 If you are running experiments with embedding perl as a library into
3076 other applications, you might find MakeMaker is not sufficient. You'd
3077 better have a look at L<ExtUtils::Embed> which is a collection of utilities
3080 If you still need a different solution, try to develop another
3081 subroutine that fits your needs and submit the diffs to
3082 C<makemaker@perl.org>
3084 For a complete description of all MakeMaker methods see
3085 L<ExtUtils::MM_Unix>.
3087 Here is a simple example of how to add a new target to the generated
3091 return <<'MAKE_FRAG';
3092 $(MYEXTLIB): sdbm/Makefile
3093 cd sdbm && $(MAKE) all
3098 =head2 The End Of Cargo Cult Programming
3100 WriteMakefile() now does some basic sanity checks on its parameters to
3101 protect against typos and malformatted values. This means some things
3102 which happened to work in the past will now throw warnings and
3103 possibly produce internal errors.
3105 Some of the most common mistakes:
3109 =item C<< MAN3PODS => ' ' >>
3111 This is commonly used to suppress the creation of man pages. MAN3PODS
3112 takes a hash ref not a string, but the above worked by accident in old
3113 versions of MakeMaker.
3115 The correct code is C<< MAN3PODS => { } >>.
3120 =head2 Hintsfile support
3122 MakeMaker.pm uses the architecture-specific information from
3123 Config.pm. In addition it evaluates architecture specific hints files
3124 in a C<hints/> directory. The hints files are expected to be named
3125 like their counterparts in C<PERL_SRC/hints>, but with an C<.pl> file
3126 name extension (eg. C<next_3_2.pl>). They are simply C<eval>ed by
3127 MakeMaker within the WriteMakefile() subroutine, and can be used to
3128 execute commands as well as to include special variables. The rules
3129 which hintsfile is chosen are the same as in Configure.
3131 The hintsfile is eval()ed immediately after the arguments given to
3132 WriteMakefile are stuffed into a hash reference $self but before this
3133 reference becomes blessed. So if you want to do the equivalent to
3134 override or create an attribute you would say something like
3136 $self->{LIBS} = ['-ldbm -lucb -lc'];
3138 =head2 Distribution Support
3140 For authors of extensions MakeMaker provides several Makefile
3141 targets. Most of the support comes from the L<ExtUtils::Manifest> module,
3142 where additional documentation can be found.
3146 =item make distcheck
3148 reports which files are below the build directory but not in the
3149 MANIFEST file and vice versa. (See L<ExtUtils::Manifest/fullcheck> for
3152 =item make skipcheck
3154 reports which files are skipped due to the entries in the
3155 C<MANIFEST.SKIP> file (See L<ExtUtils::Manifest/skipcheck> for
3158 =item make distclean
3160 does a realclean first and then the distcheck. Note that this is not
3161 needed to build a new distribution as long as you are sure that the
3162 MANIFEST file is ok.
3164 =item make veryclean
3166 does a realclean first and then removes backup files such as C<*~>,
3167 C<*.bak>, C<*.old> and C<*.orig>
3171 rewrites the MANIFEST file, adding all remaining files found (See
3172 L<ExtUtils::Manifest/mkmanifest> for details)
3176 Copies all the files that are in the MANIFEST file to a newly created
3177 directory with the name C<$(DISTNAME)-$(VERSION)>. If that directory
3178 exists, it will be removed first.
3180 Additionally, it will create META.yml and META.json module meta-data file
3181 in the distdir and add this to the distdir's MANIFEST. You can shut this
3182 behavior off with the NO_META flag.
3186 Makes a distdir first, and runs a C<perl Makefile.PL>, a make, and
3187 a make test in that directory.
3191 First does a distdir. Then a command $(PREOP) which defaults to a null
3192 command, followed by $(TO_UNIX), which defaults to a null command under
3193 UNIX, and will convert files in distribution directory to UNIX format
3194 otherwise. Next it runs C<tar> on that directory into a tarfile and
3195 deletes the directory. Finishes with a command $(POSTOP) which
3196 defaults to a null command.
3200 Defaults to $(DIST_DEFAULT) which in turn defaults to tardist.
3202 =item make uutardist
3204 Runs a tardist first and uuencodes the tarfile.
3208 First does a distdir. Then a command $(PREOP) which defaults to a null
3209 command. Next it runs C<shar> on that directory into a sharfile and
3210 deletes the intermediate directory again. Finishes with a command
3211 $(POSTOP) which defaults to a null command. Note: For shdist to work
3212 properly a C<shar> program that can handle directories is mandatory.
3216 First does a distdir. Then a command $(PREOP) which defaults to a null
3217 command. Runs C<$(ZIP) $(ZIPFLAGS)> on that directory into a
3218 zipfile. Then deletes that directory. Finishes with a command
3219 $(POSTOP) which defaults to a null command.
3223 Does a $(CI) and a $(RCS_LABEL) on all files in the MANIFEST file.
3227 Customization of the dist targets can be done by specifying a hash
3228 reference to the dist attribute of the WriteMakefile call. The
3229 following parameters are recognized:
3232 COMPRESS ('gzip --best')
3235 TO_UNIX (depends on the system)
3236 RCS_LABEL ('rcs -q -Nv$(VERSION_SYM):')
3249 COMPRESS => "bzip2",
3255 =head2 Module Meta-Data (META and MYMETA)
3257 Long plaguing users of MakeMaker based modules has been the problem of
3258 getting basic information about the module out of the sources
3259 I<without> running the F<Makefile.PL> and doing a bunch of messy
3260 heuristics on the resulting F<Makefile>. Over the years, it has become
3261 standard to keep this information in one or more CPAN Meta files
3262 distributed with each distribution.
3264 The original format of CPAN Meta files was L<YAML> and the corresponding
3265 file was called F<META.yml>. In 2010, version 2 of the L<CPAN::Meta::Spec>
3266 was released, which mandates JSON format for the metadata in order to
3267 overcome certain compatibility issues between YAML serializers and to
3268 avoid breaking older clients unable to handle a new version of the spec.
3269 The L<CPAN::Meta> library is now standard for accessing old and new-style
3272 If L<CPAN::Meta> is installed, MakeMaker will automatically generate
3273 F<META.json> and F<META.yml> files for you and add them to your F<MANIFEST> as
3274 part of the 'distdir' target (and thus the 'dist' target). This is intended to
3275 seamlessly and rapidly populate CPAN with module meta-data. If you wish to
3276 shut this feature off, set the C<NO_META> C<WriteMakefile()> flag to true.
3278 At the 2008 QA Hackathon in Oslo, Perl module toolchain maintainers agreed
3279 to use the CPAN Meta format to communicate post-configuration requirements
3280 between toolchain components. These files, F<MYMETA.json> and F<MYMETA.yml>,
3281 are generated when F<Makefile.PL> generates a F<Makefile> (if L<CPAN::Meta>
3282 is installed). Clients like L<CPAN> or L<CPANPLUS> will read these
3283 files to see what prerequisites must be fulfilled before building or testing
3284 the distribution. If you wish to shut this feature off, set the C<NO_MYMETA>
3285 C<WriteMakefile()> flag to true.
3287 =head2 Disabling an extension
3289 If some events detected in F<Makefile.PL> imply that there is no way
3290 to create the Module, but this is a normal state of things, then you
3291 can create a F<Makefile> which does nothing, but succeeds on all the
3292 "usual" build targets. To do so, use
3294 use ExtUtils::MakeMaker qw(WriteEmptyMakefile);
3295 WriteEmptyMakefile();
3297 instead of WriteMakefile().
3299 This may be useful if other modules expect this module to be I<built>
3300 OK, as opposed to I<work> OK (say, this system-dependent module builds
3301 in a subdirectory of some other distribution, or is listed as a
3302 dependency in a CPAN::Bundle, but the functionality is supported by
3303 different means on the current architecture).
3305 =head2 Other Handy Functions
3311 my $value = prompt($message);
3312 my $value = prompt($message, $default);
3314 The C<prompt()> function provides an easy way to request user input
3315 used to write a makefile. It displays the $message as a prompt for
3316 input. If a $default is provided it will be used as a default. The
3317 function returns the $value selected by the user.
3319 If C<prompt()> detects that it is not running interactively and there
3320 is nothing on STDIN or if the PERL_MM_USE_DEFAULT environment variable
3321 is set to true, the $default will be used without prompting. This
3322 prevents automated processes from blocking on user input.
3324 If no $default is provided an empty string will be used instead.
3326 =item os_unsupported
3329 os_unsupported if $^O eq 'MSWin32';
3331 The C<os_unsupported()> function provides a way to correctly exit your
3332 C<Makefile.PL> before calling C<WriteMakefile>. It is essentially a
3333 C<die> with the message "OS unsupported".
3335 This is supported since 7.26
3339 =head2 Supported versions of Perl
3341 Please note that while this module works on Perl 5.6, it is no longer
3342 being routinely tested on 5.6 - the earliest Perl version being routinely
3343 tested, and expressly supported, is 5.8.1. However, patches to repair
3344 any breakage on 5.6 are still being accepted.
3352 Command line options used by C<MakeMaker-E<gt>new()>, and thus by
3353 C<WriteMakefile()>. The string is split as the shell would, and the result
3354 is processed before any actual command line arguments are processed.
3356 PERL_MM_OPT='CCFLAGS="-Wl,-rpath -Wl,/foo/bar/lib" LIBS="-lwibble -lwobble"'
3358 =item PERL_MM_USE_DEFAULT
3360 If set to a true value then MakeMaker's prompt function will
3361 always return the default without waiting for user input.
3365 Same as the PERL_CORE parameter. The parameter overrides this.
3371 L<Module::Build> is a pure-Perl alternative to MakeMaker which does
3372 not rely on make or any other external utility. It may be easier to
3373 extend to suit your needs.
3375 L<Module::Build::Tiny> is a minimal pure-Perl alternative to MakeMaker
3376 that follows the Build.PL protocol of Module::Build but without its
3377 complexity and cruft, implementing only the installation of the module
3378 and leaving authoring to L<mbtiny> or other authoring tools.
3380 L<Module::Install> is a (now discouraged) wrapper around MakeMaker which
3381 adds features not normally available.
3383 L<ExtUtils::ModuleMaker> and L<Module::Starter> are both modules to
3384 help you setup your distribution.
3386 L<CPAN::Meta> and L<CPAN::Meta::Spec> explain CPAN Meta files in detail.
3388 L<File::ShareDir::Install> makes it easy to install static, sometimes
3389 also referred to as 'shared' files. L<File::ShareDir> helps accessing
3390 the shared files after installation. L<Test::File::ShareDir> helps when
3391 writing tests to use the shared files both before and after installation.
3393 L<Dist::Zilla> is an authoring tool which allows great customization and
3394 extensibility of the author experience, relying on the existing install
3395 tools like ExtUtils::MakeMaker only for installation.
3397 L<Dist::Milla> is a Dist::Zilla bundle that greatly simplifies common
3400 L<Minilla> is a minimal authoring tool that does the same things as
3401 Dist::Milla without the overhead of Dist::Zilla.
3405 Andy Dougherty C<doughera@lafayette.edu>, Andreas KE<ouml>nig
3406 C<andreas.koenig@mind.de>, Tim Bunce C<timb@cpan.org>. VMS
3407 support by Charles Bailey C<bailey@newman.upenn.edu>. OS/2 support
3408 by Ilya Zakharevich C<ilya@math.ohio-state.edu>.
3410 Currently maintained by Michael G Schwern C<schwern@pobox.com>
3412 Send patches and ideas to C<makemaker@perl.org>.
3414 Send bug reports via http://rt.cpan.org/. Please send your
3415 generated Makefile along with your report.
3417 For more up-to-date information, see L<https://metacpan.org/release/ExtUtils-MakeMaker>.
3419 Repository available at L<https://github.com/Perl-Toolchain-Gang/ExtUtils-MakeMaker>.
3423 This program is free software; you can redistribute it and/or
3424 modify it under the same terms as Perl itself.
3426 See L<http://www.perl.com/perl/misc/Artistic.html>