update ExtUtils-MakeMaker to github v6.65_01
[perl.git] / cpan / ExtUtils-MakeMaker / lib / ExtUtils / MM_Any.pm
1 package ExtUtils::MM_Any;
2
3 use strict;
4 our $VERSION = '6.65_01';
5
6 use Carp;
7 use File::Spec;
8 use File::Basename;
9 BEGIN { our @ISA = qw(File::Spec); }
10
11 # We need $Verbose
12 use ExtUtils::MakeMaker qw($Verbose);
13
14 use ExtUtils::MakeMaker::Config;
15
16
17 # So we don't have to keep calling the methods over and over again,
18 # we have these globals to cache the values.  Faster and shrtr.
19 my $Curdir  = __PACKAGE__->curdir;
20 my $Rootdir = __PACKAGE__->rootdir;
21 my $Updir   = __PACKAGE__->updir;
22
23
24 =head1 NAME
25
26 ExtUtils::MM_Any - Platform-agnostic MM methods
27
28 =head1 SYNOPSIS
29
30   FOR INTERNAL USE ONLY!
31
32   package ExtUtils::MM_SomeOS;
33
34   # Temporarily, you have to subclass both.  Put MM_Any first.
35   require ExtUtils::MM_Any;
36   require ExtUtils::MM_Unix;
37   @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
38
39 =head1 DESCRIPTION
40
41 B<FOR INTERNAL USE ONLY!>
42
43 ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
44 modules.  It contains methods which are either inherently
45 cross-platform or are written in a cross-platform manner.
46
47 Subclass off of ExtUtils::MM_Any I<and> ExtUtils::MM_Unix.  This is a
48 temporary solution.
49
50 B<THIS MAY BE TEMPORARY!>
51
52
53 =head1 METHODS
54
55 Any methods marked I<Abstract> must be implemented by subclasses.
56
57
58 =head2 Cross-platform helper methods
59
60 These are methods which help writing cross-platform code.
61
62
63
64 =head3 os_flavor  I<Abstract>
65
66     my @os_flavor = $mm->os_flavor;
67
68 @os_flavor is the style of operating system this is, usually
69 corresponding to the MM_*.pm file we're using.  
70
71 The first element of @os_flavor is the major family (ie. Unix,
72 Windows, VMS, OS/2, etc...) and the rest are sub families.
73
74 Some examples:
75
76     Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
77     Windows        ('Win32')
78     Win98          ('Win32', 'Win9x')
79     Linux          ('Unix',  'Linux')
80     MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
81     OS/2           ('OS/2')
82
83 This is used to write code for styles of operating system.  
84 See os_flavor_is() for use.
85
86
87 =head3 os_flavor_is
88
89     my $is_this_flavor = $mm->os_flavor_is($this_flavor);
90     my $is_this_flavor = $mm->os_flavor_is(@one_of_these_flavors);
91
92 Checks to see if the current operating system is one of the given flavors.
93
94 This is useful for code like:
95
96     if( $mm->os_flavor_is('Unix') ) {
97         $out = `foo 2>&1`;
98     }
99     else {
100         $out = `foo`;
101     }
102
103 =cut
104
105 sub os_flavor_is {
106     my $self = shift;
107     my %flavors = map { ($_ => 1) } $self->os_flavor;
108     return (grep { $flavors{$_} } @_) ? 1 : 0;
109 }
110
111
112 =head3 can_load_xs
113
114     my $can_load_xs = $self->can_load_xs;
115
116 Returns true if we have the ability to load XS.
117
118 This is important because miniperl, used to build XS modules in the
119 core, can not load XS.
120
121 =cut
122
123 sub can_load_xs {
124     return defined &DynaLoader::boot_DynaLoader ? 1 : 0;
125 }
126
127
128 =head3 split_command
129
130     my @cmds = $MM->split_command($cmd, @args);
131
132 Most OS have a maximum command length they can execute at once.  Large
133 modules can easily generate commands well past that limit.  Its
134 necessary to split long commands up into a series of shorter commands.
135
136 C<split_command> will return a series of @cmds each processing part of
137 the args.  Collectively they will process all the arguments.  Each
138 individual line in @cmds will not be longer than the
139 $self->max_exec_len being careful to take into account macro expansion.
140
141 $cmd should include any switches and repeated initial arguments.
142
143 If no @args are given, no @cmds will be returned.
144
145 Pairs of arguments will always be preserved in a single command, this
146 is a heuristic for things like pm_to_blib and pod2man which work on
147 pairs of arguments.  This makes things like this safe:
148
149     $self->split_command($cmd, %pod2man);
150
151
152 =cut
153
154 sub split_command {
155     my($self, $cmd, @args) = @_;
156
157     my @cmds = ();
158     return(@cmds) unless @args;
159
160     # If the command was given as a here-doc, there's probably a trailing
161     # newline.
162     chomp $cmd;
163
164     # set aside 30% for macro expansion.
165     my $len_left = int($self->max_exec_len * 0.70);
166     $len_left -= length $self->_expand_macros($cmd);
167
168     do {
169         my $arg_str = '';
170         my @next_args;
171         while( @next_args = splice(@args, 0, 2) ) {
172             # Two at a time to preserve pairs.
173             my $next_arg_str = "\t  ". join ' ', @next_args, "\n";
174
175             if( !length $arg_str ) {
176                 $arg_str .= $next_arg_str
177             }
178             elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
179                 unshift @args, @next_args;
180                 last;
181             }
182             else {
183                 $arg_str .= $next_arg_str;
184             }
185         }
186         chop $arg_str;
187
188         push @cmds, $self->escape_newlines("$cmd \n$arg_str");
189     } while @args;
190
191     return @cmds;
192 }
193
194
195 sub _expand_macros {
196     my($self, $cmd) = @_;
197
198     $cmd =~ s{\$\((\w+)\)}{
199         defined $self->{$1} ? $self->{$1} : "\$($1)"
200     }e;
201     return $cmd;
202 }
203
204
205 =head3 echo
206
207     my @commands = $MM->echo($text);
208     my @commands = $MM->echo($text, $file);
209     my @commands = $MM->echo($text, $file, \%opts);
210
211 Generates a set of @commands which print the $text to a $file.
212
213 If $file is not given, output goes to STDOUT.
214
215 If $opts{append} is true the $file will be appended to rather than
216 overwritten.  Default is to overwrite.
217
218 If $opts{allow_variables} is true, make variables of the form
219 C<$(...)> will not be escaped.  Other C<$> will.  Default is to escape
220 all C<$>.
221
222 Example of use:
223
224     my $make = map "\t$_\n", $MM->echo($text, $file);
225
226 =cut
227
228 sub echo {
229     my($self, $text, $file, $opts) = @_;
230
231     # Compatibility with old options
232     if( !ref $opts ) {
233         my $append = $opts;
234         $opts = { append => $append || 0 };
235     }
236     $opts->{allow_variables} = 0 unless defined $opts->{allow_variables};
237
238     my $ql_opts = { allow_variables => $opts->{allow_variables} };
239     my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_, $ql_opts) } 
240                split /\n/, $text;
241     if( $file ) {
242         my $redirect = $opts->{append} ? '>>' : '>';
243         $cmds[0] .= " $redirect $file";
244         $_ .= " >> $file" foreach @cmds[1..$#cmds];
245     }
246
247     return @cmds;
248 }
249
250
251 =head3 wraplist
252
253   my $args = $mm->wraplist(@list);
254
255 Takes an array of items and turns them into a well-formatted list of
256 arguments.  In most cases this is simply something like:
257
258     FOO \
259     BAR \
260     BAZ
261
262 =cut
263
264 sub wraplist {
265     my $self = shift;
266     return join " \\\n\t", @_;
267 }
268
269
270 =head3 maketext_filter
271
272     my $filter_make_text = $mm->maketext_filter($make_text);
273
274 The text of the Makefile is run through this method before writing to
275 disk.  It allows systems a chance to make portability fixes to the
276 Makefile.
277
278 By default it does nothing.
279
280 This method is protected and not intended to be called outside of
281 MakeMaker.
282
283 =cut
284
285 sub maketext_filter { return $_[1] }
286
287
288 =head3 cd  I<Abstract>
289
290   my $subdir_cmd = $MM->cd($subdir, @cmds);
291
292 This will generate a make fragment which runs the @cmds in the given
293 $dir.  The rough equivalent to this, except cross platform.
294
295   cd $subdir && $cmd
296
297 Currently $dir can only go down one level.  "foo" is fine.  "foo/bar" is
298 not.  "../foo" is right out.
299
300 The resulting $subdir_cmd has no leading tab nor trailing newline.  This
301 makes it easier to embed in a make string.  For example.
302
303       my $make = sprintf <<'CODE', $subdir_cmd;
304   foo :
305       $(ECHO) what
306       %s
307       $(ECHO) mouche
308   CODE
309
310
311 =head3 oneliner  I<Abstract>
312
313   my $oneliner = $MM->oneliner($perl_code);
314   my $oneliner = $MM->oneliner($perl_code, \@switches);
315
316 This will generate a perl one-liner safe for the particular platform
317 you're on based on the given $perl_code and @switches (a -e is
318 assumed) suitable for using in a make target.  It will use the proper
319 shell quoting and escapes.
320
321 $(PERLRUN) will be used as perl.
322
323 Any newlines in $perl_code will be escaped.  Leading and trailing
324 newlines will be stripped.  Makes this idiom much easier:
325
326     my $code = $MM->oneliner(<<'CODE', [...switches...]);
327 some code here
328 another line here
329 CODE
330
331 Usage might be something like:
332
333     # an echo emulation
334     $oneliner = $MM->oneliner('print "Foo\n"');
335     $make = '$oneliner > somefile';
336
337 All dollar signs must be doubled in the $perl_code if you expect them
338 to be interpreted normally, otherwise it will be considered a make
339 macro.  Also remember to quote make macros else it might be used as a
340 bareword.  For example:
341
342     # Assign the value of the $(VERSION_FROM) make macro to $vf.
343     $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
344
345 Its currently very simple and may be expanded sometime in the figure
346 to include more flexible code and switches.
347
348
349 =head3 quote_literal  I<Abstract>
350
351     my $safe_text = $MM->quote_literal($text);
352     my $safe_text = $MM->quote_literal($text, \%options);
353
354 This will quote $text so it is interpreted literally in the shell.
355
356 For example, on Unix this would escape any single-quotes in $text and
357 put single-quotes around the whole thing.
358
359 If $options{allow_variables} is true it will leave C<'$(FOO)'> make
360 variables untouched.  If false they will be escaped like any other
361 C<$>.  Defaults to true.
362
363 =head3 escape_dollarsigns
364
365     my $escaped_text = $MM->escape_dollarsigns($text);
366
367 Escapes stray C<$> so they are not interpreted as make variables.
368
369 It lets by C<$(...)>.
370
371 =cut
372
373 sub escape_dollarsigns {
374     my($self, $text) = @_;
375
376     # Escape dollar signs which are not starting a variable
377     $text =~ s{\$ (?!\() }{\$\$}gx;
378
379     return $text;
380 }
381
382
383 =head3 escape_all_dollarsigns
384
385     my $escaped_text = $MM->escape_all_dollarsigns($text);
386
387 Escapes all C<$> so they are not interpreted as make variables.
388
389 =cut
390
391 sub escape_all_dollarsigns {
392     my($self, $text) = @_;
393
394     # Escape dollar signs
395     $text =~ s{\$}{\$\$}gx;
396
397     return $text;
398 }
399
400
401 =head3 escape_newlines  I<Abstract>
402
403     my $escaped_text = $MM->escape_newlines($text);
404
405 Shell escapes newlines in $text.
406
407
408 =head3 max_exec_len  I<Abstract>
409
410     my $max_exec_len = $MM->max_exec_len;
411
412 Calculates the maximum command size the OS can exec.  Effectively,
413 this is the max size of a shell command line.
414
415 =for _private
416 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
417
418
419 =head3 make
420
421     my $make = $MM->make;
422
423 Returns the make variant we're generating the Makefile for.  This attempts
424 to do some normalization on the information from %Config or the user.
425
426 =cut
427
428 sub make {
429     my $self = shift;
430
431     my $make = lc $self->{MAKE};
432
433     # Truncate anything like foomake6 to just foomake.
434     $make =~ s/^(\w+make).*/$1/;
435
436     # Turn gnumake into gmake.
437     $make =~ s/^gnu/g/;
438
439     return $make;
440 }
441
442
443 =head2 Targets
444
445 These are methods which produce make targets.
446
447
448 =head3 all_target
449
450 Generate the default target 'all'.
451
452 =cut
453
454 sub all_target {
455     my $self = shift;
456
457     return <<'MAKE_EXT';
458 all :: pure_all
459         $(NOECHO) $(NOOP)
460 MAKE_EXT
461
462 }
463
464
465 =head3 blibdirs_target
466
467     my $make_frag = $mm->blibdirs_target;
468
469 Creates the blibdirs target which creates all the directories we use
470 in blib/.
471
472 The blibdirs.ts target is deprecated.  Depend on blibdirs instead.
473
474
475 =cut
476
477 sub blibdirs_target {
478     my $self = shift;
479
480     my @dirs = map { uc "\$(INST_$_)" } qw(libdir archlib
481                                            autodir archautodir
482                                            bin script
483                                            man1dir man3dir
484                                           );
485
486     my @exists = map { $_.'$(DFSEP).exists' } @dirs;
487
488     my $make = sprintf <<'MAKE', join(' ', @exists);
489 blibdirs : %s
490         $(NOECHO) $(NOOP)
491
492 # Backwards compat with 6.18 through 6.25
493 blibdirs.ts : blibdirs
494         $(NOECHO) $(NOOP)
495
496 MAKE
497
498     $make .= $self->dir_target(@dirs);
499
500     return $make;
501 }
502
503
504 =head3 clean (o)
505
506 Defines the clean target.
507
508 =cut
509
510 sub clean {
511 # --- Cleanup and Distribution Sections ---
512
513     my($self, %attribs) = @_;
514     my @m;
515     push(@m, '
516 # Delete temporary files but do not touch installed files. We don\'t delete
517 # the Makefile here so a later make realclean still has a makefile to use.
518
519 clean :: clean_subdirs
520 ');
521
522     my @files = values %{$self->{XS}}; # .c files from *.xs files
523     my @dirs  = qw(blib);
524
525     # Normally these are all under blib but they might have been
526     # redefined.
527     # XXX normally this would be a good idea, but the Perl core sets
528     # INST_LIB = ../../lib rather than actually installing the files.
529     # So a "make clean" in an ext/ directory would blow away lib.
530     # Until the core is adjusted let's leave this out.
531 #     push @dirs, qw($(INST_ARCHLIB) $(INST_LIB)
532 #                    $(INST_BIN) $(INST_SCRIPT)
533 #                    $(INST_MAN1DIR) $(INST_MAN3DIR)
534 #                    $(INST_LIBDIR) $(INST_ARCHLIBDIR) $(INST_AUTODIR) 
535 #                    $(INST_STATIC) $(INST_DYNAMIC) $(INST_BOOT)
536 #                 );
537                   
538
539     if( $attribs{FILES} ) {
540         # Use @dirs because we don't know what's in here.
541         push @dirs, ref $attribs{FILES}                ?
542                         @{$attribs{FILES}}             :
543                         split /\s+/, $attribs{FILES}   ;
544     }
545
546     push(@files, qw[$(MAKE_APERL_FILE) 
547                     MYMETA.json MYMETA.yml perlmain.c tmon.out mon.out so_locations
548                     blibdirs.ts pm_to_blib pm_to_blib.ts
549                     *$(OBJ_EXT) *$(LIB_EXT) perl.exe perl perl$(EXE_EXT)
550                     $(BOOTSTRAP) $(BASEEXT).bso
551                     $(BASEEXT).def lib$(BASEEXT).def
552                     $(BASEEXT).exp $(BASEEXT).x
553                    ]);
554
555     push(@files, $self->catfile('$(INST_ARCHAUTODIR)','extralibs.all'));
556     push(@files, $self->catfile('$(INST_ARCHAUTODIR)','extralibs.ld'));
557
558     # core files
559     push(@files, qw[core core.*perl.*.? *perl.core]);
560     push(@files, map { "core." . "[0-9]"x$_ } (1..5));
561
562     # OS specific things to clean up.  Use @dirs since we don't know
563     # what might be in here.
564     push @dirs, $self->extra_clean_files;
565
566     # Occasionally files are repeated several times from different sources
567     { my(%f) = map { ($_ => 1) } @files; @files = keys %f; }
568     { my(%d) = map { ($_ => 1) } @dirs;  @dirs  = keys %d; }
569
570     push @m, map "\t$_\n", $self->split_command('- $(RM_F)',  @files);
571     push @m, map "\t$_\n", $self->split_command('- $(RM_RF)', @dirs);
572
573     # Leave Makefile.old around for realclean
574     push @m, <<'MAKE';
575         - $(MV) $(FIRST_MAKEFILE) $(MAKEFILE_OLD) $(DEV_NULL)
576 MAKE
577
578     push(@m, "\t$attribs{POSTOP}\n")   if $attribs{POSTOP};
579
580     join("", @m);
581 }
582
583
584 =head3 clean_subdirs_target
585
586   my $make_frag = $MM->clean_subdirs_target;
587
588 Returns the clean_subdirs target.  This is used by the clean target to
589 call clean on any subdirectories which contain Makefiles.
590
591 =cut
592
593 sub clean_subdirs_target {
594     my($self) = shift;
595
596     # No subdirectories, no cleaning.
597     return <<'NOOP_FRAG' unless @{$self->{DIR}};
598 clean_subdirs :
599         $(NOECHO) $(NOOP)
600 NOOP_FRAG
601
602
603     my $clean = "clean_subdirs :\n";
604
605     for my $dir (@{$self->{DIR}}) {
606         my $subclean = $self->oneliner(sprintf <<'CODE', $dir);
607 chdir '%s';  system '$(MAKE) clean' if -f '$(FIRST_MAKEFILE)';
608 CODE
609
610         $clean .= "\t$subclean\n";
611     }
612
613     return $clean;
614 }
615
616
617 =head3 dir_target
618
619     my $make_frag = $mm->dir_target(@directories);
620
621 Generates targets to create the specified directories and set its
622 permission to PERM_DIR.
623
624 Because depending on a directory to just ensure it exists doesn't work
625 too well (the modified time changes too often) dir_target() creates a
626 .exists file in the created directory.  It is this you should depend on.
627 For portability purposes you should use the $(DIRFILESEP) macro rather
628 than a '/' to seperate the directory from the file.
629
630     yourdirectory$(DIRFILESEP).exists
631
632 =cut
633
634 sub dir_target {
635     my($self, @dirs) = @_;
636
637     my $make = '';
638     foreach my $dir (@dirs) {
639         $make .= sprintf <<'MAKE', ($dir) x 7;
640 %s$(DFSEP).exists :: Makefile.PL
641         $(NOECHO) $(MKPATH) %s
642         $(NOECHO) $(CHMOD) $(PERM_DIR) %s
643         $(NOECHO) $(TOUCH) %s$(DFSEP).exists
644
645 MAKE
646
647     }
648
649     return $make;
650 }
651
652
653 =head3 distdir
654
655 Defines the scratch directory target that will hold the distribution
656 before tar-ing (or shar-ing).
657
658 =cut
659
660 # For backwards compatibility.
661 *dist_dir = *distdir;
662
663 sub distdir {
664     my($self) = shift;
665
666     my $meta_target = $self->{NO_META} ? '' : 'distmeta';
667     my $sign_target = !$self->{SIGN}   ? '' : 'distsignature';
668
669     return sprintf <<'MAKE_FRAG', $meta_target, $sign_target;
670 create_distdir :
671         $(RM_RF) $(DISTVNAME)
672         $(PERLRUN) "-MExtUtils::Manifest=manicopy,maniread" \
673                 -e "manicopy(maniread(),'$(DISTVNAME)', '$(DIST_CP)');"
674
675 distdir : create_distdir %s %s
676         $(NOECHO) $(NOOP)
677
678 MAKE_FRAG
679
680 }
681
682
683 =head3 dist_test
684
685 Defines a target that produces the distribution in the
686 scratchdirectory, and runs 'perl Makefile.PL; make ;make test' in that
687 subdirectory.
688
689 =cut
690
691 sub dist_test {
692     my($self) = shift;
693
694     my $mpl_args = join " ", map qq["$_"], @ARGV;
695
696     my $test = $self->cd('$(DISTVNAME)',
697                          '$(ABSPERLRUN) Makefile.PL '.$mpl_args,
698                          '$(MAKE) $(PASTHRU)',
699                          '$(MAKE) test $(PASTHRU)'
700                         );
701
702     return sprintf <<'MAKE_FRAG', $test;
703 disttest : distdir
704         %s
705
706 MAKE_FRAG
707
708
709 }
710
711
712 =head3 dynamic (o)
713
714 Defines the dynamic target.
715
716 =cut
717
718 sub dynamic {
719 # --- Dynamic Loading Sections ---
720
721     my($self) = shift;
722     '
723 dynamic :: $(FIRST_MAKEFILE) $(INST_DYNAMIC) $(INST_BOOT)
724         $(NOECHO) $(NOOP)
725 ';
726 }
727
728
729 =head3 makemakerdflt_target
730
731   my $make_frag = $mm->makemakerdflt_target
732
733 Returns a make fragment with the makemakerdeflt_target specified.
734 This target is the first target in the Makefile, is the default target
735 and simply points off to 'all' just in case any make variant gets
736 confused or something gets snuck in before the real 'all' target.
737
738 =cut
739
740 sub makemakerdflt_target {
741     return <<'MAKE_FRAG';
742 makemakerdflt : all
743         $(NOECHO) $(NOOP)
744 MAKE_FRAG
745
746 }
747
748
749 =head3 manifypods_target
750
751   my $manifypods_target = $self->manifypods_target;
752
753 Generates the manifypods target.  This target generates man pages from
754 all POD files in MAN1PODS and MAN3PODS.
755
756 =cut
757
758 sub manifypods_target {
759     my($self) = shift;
760
761     my $man1pods      = '';
762     my $man3pods      = '';
763     my $dependencies  = '';
764
765     # populate manXpods & dependencies:
766     foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
767         $dependencies .= " \\\n\t$name";
768     }
769
770     my $manify = <<END;
771 manifypods : pure_all $dependencies
772 END
773
774     my @man_cmds;
775     foreach my $section (qw(1 3)) {
776         my $pods = $self->{"MAN${section}PODS"};
777         push @man_cmds, $self->split_command(<<CMD, %$pods);
778         \$(NOECHO) \$(POD2MAN) --section=$section --perm_rw=\$(PERM_RW)
779 CMD
780     }
781
782     $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
783     $manify .= join '', map { "$_\n" } @man_cmds;
784
785     return $manify;
786 }
787
788 sub _has_cpan_meta {
789     return eval {
790       require CPAN::Meta;
791       CPAN::Meta->VERSION(2.112150);
792       1;
793     };
794 }
795
796 =head3 metafile_target
797
798     my $target = $mm->metafile_target;
799
800 Generate the metafile target.
801
802 Writes the file META.yml YAML encoded meta-data about the module in
803 the distdir.  The format follows Module::Build's as closely as
804 possible.
805
806 =cut
807
808 sub metafile_target {
809     my $self = shift;
810     return <<'MAKE_FRAG' if $self->{NO_META} or ! _has_cpan_meta();
811 metafile :
812         $(NOECHO) $(NOOP)
813 MAKE_FRAG
814
815     my %metadata   = $self->metafile_data(
816         $self->{META_ADD}   || {},
817         $self->{META_MERGE} || {},
818     );
819     
820     _fix_metadata_before_conversion( \%metadata );
821
822     # paper over validation issues, but still complain, necessary because
823     # there's no guarantee that the above will fix ALL errors
824     my $meta = eval { CPAN::Meta->create( \%metadata, { lazy_validation => 1 } ) };
825     warn $@ if $@ and 
826                $@ !~ /encountered CODE.*, but JSON can only represent references to arrays or hashes/;
827
828     # use the original metadata straight if the conversion failed
829     # or if it can't be stringified.
830     if( !$meta                                                  ||
831         !eval { $meta->as_string( { version => "1.4" } ) }      ||
832         !eval { $meta->as_string }
833     )
834     {
835         $meta = bless \%metadata, 'CPAN::Meta';
836     }
837
838     my @write_metayml = $self->echo(
839       $meta->as_string({version => "1.4"}), 'META_new.yml'
840     );
841     my @write_metajson = $self->echo(
842       $meta->as_string(), 'META_new.json'
843     );
844
845     my $metayml = join("\n\t", @write_metayml);
846     my $metajson = join("\n\t", @write_metajson);
847     return sprintf <<'MAKE_FRAG', $metayml, $metajson;
848 metafile : create_distdir
849         $(NOECHO) $(ECHO) Generating META.yml
850         %s
851         -$(NOECHO) $(MV) META_new.yml $(DISTVNAME)/META.yml
852         $(NOECHO) $(ECHO) Generating META.json
853         %s
854         -$(NOECHO) $(MV) META_new.json $(DISTVNAME)/META.json
855 MAKE_FRAG
856
857 }
858
859 =begin private
860
861 =head3 _fix_metadata_before_conversion
862
863     _fix_metadata_before_conversion( \%metadata );
864
865 Fixes errors in the metadata before it's handed off to CPAN::Meta for
866 conversion. This hopefully results in something that can be used further
867 on, no guarantee is made though.
868
869 =end private
870
871 =cut
872
873 sub _fix_metadata_before_conversion {
874     my ( $metadata ) = @_;
875
876     # we should never be called unless this already passed but
877     # prefer to be defensive in case somebody else calls this
878
879     return unless _has_cpan_meta;
880
881     my $bad_version = $metadata->{version} &&
882                       !CPAN::Meta::Validator->new->version( 'version', $metadata->{version} );
883
884     # just delete all invalid versions
885     if( $bad_version ) {
886         warn "Can't parse version '$metadata->{version}'\n";
887         $metadata->{version} = '';
888     }
889
890     my $validator = CPAN::Meta::Validator->new( $metadata );
891     return if $validator->is_valid;
892
893     # fix non-camelcase custom resource keys (only other trick we know)
894     for my $error ( $validator->errors ) {
895         my ( $key ) = ( $error =~ /Custom resource '(.*)' must be in CamelCase./ );
896         next if !$key;
897
898         # first try to remove all non-alphabetic chars
899         ( my $new_key = $key ) =~ s/[^_a-zA-Z]//g;
900
901         # if that doesn't work, uppercase first one
902         $new_key = ucfirst $new_key if !$validator->custom_1( $new_key );
903
904         # copy to new key if that worked
905         $metadata->{resources}{$new_key} = $metadata->{resources}{$key}
906           if $validator->custom_1( $new_key );
907
908         # and delete old one in any case
909         delete $metadata->{resources}{$key};
910     }
911
912     return;
913 }
914
915
916 =begin private
917
918 =head3 _sort_pairs
919
920     my @pairs = _sort_pairs($sort_sub, \%hash);
921
922 Sorts the pairs of a hash based on keys ordered according 
923 to C<$sort_sub>.
924
925 =end private
926
927 =cut
928
929 sub _sort_pairs {
930     my $sort  = shift;
931     my $pairs = shift;
932     return map  { $_ => $pairs->{$_} }
933            sort $sort
934            keys %$pairs;
935 }
936
937
938 # Taken from Module::Build::Base
939 sub _hash_merge {
940     my ($self, $h, $k, $v) = @_;
941     if (ref $h->{$k} eq 'ARRAY') {
942         push @{$h->{$k}}, ref $v ? @$v : $v;
943     } elsif (ref $h->{$k} eq 'HASH') {
944         $self->_hash_merge($h->{$k}, $_, $v->{$_}) foreach keys %$v;
945     } else {
946         $h->{$k} = $v;
947     }
948 }
949
950
951 =head3 metafile_data
952
953     my @metadata_pairs = $mm->metafile_data(\%meta_add, \%meta_merge);
954
955 Returns the data which MakeMaker turns into the META.yml file.
956
957 Values of %meta_add will overwrite any existing metadata in those
958 keys.  %meta_merge will be merged with them.
959
960 =cut
961
962 sub metafile_data {
963     my $self = shift;
964     my($meta_add, $meta_merge) = @_;
965
966     my %meta = (
967         # required
968         name         => $self->{DISTNAME},
969         version      => _normalize_version($self->{VERSION}),
970         abstract     => $self->{ABSTRACT} || 'unknown',
971         license      => $self->{LICENSE} || 'unknown',
972         dynamic_config => 1,
973
974         # optional
975         distribution_type => $self->{PM} ? 'module' : 'script',
976
977         no_index     => {
978             directory   => [qw(t inc)]
979         },
980
981         generated_by => "ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION",
982         'meta-spec'  => {
983             url         => 'http://module-build.sourceforge.net/META-spec-v1.4.html', 
984             version     => 1.4
985         },
986     );
987
988     # The author key is required and it takes a list.
989     $meta{author}   = defined $self->{AUTHOR}    ? $self->{AUTHOR} : [];
990
991     # Check the original args so we can tell between the user setting it
992     # to an empty hash and it just being initialized.
993     if( $self->{ARGS}{CONFIGURE_REQUIRES} ) {
994         $meta{configure_requires}
995             = _normalize_prereqs($self->{CONFIGURE_REQUIRES});
996     } else {
997         $meta{configure_requires} = {
998             'ExtUtils::MakeMaker'       => 0,
999         };
1000     }
1001
1002     %meta = $self->_add_requirements_to_meta_v1_4( %meta );
1003
1004     while( my($key, $val) = each %$meta_add ) {
1005         $meta{$key} = $val;
1006     }
1007
1008     while( my($key, $val) = each %$meta_merge ) {
1009         $self->_hash_merge(\%meta, $key, $val);
1010     }
1011
1012     return %meta;
1013 }
1014
1015
1016 =begin private
1017
1018 =cut
1019
1020 sub _add_requirements_to_meta_v1_4 {
1021     my ( $self, %meta ) = @_;
1022
1023     # Check the original args so we can tell between the user setting it
1024     # to an empty hash and it just being initialized.
1025     if( $self->{ARGS}{BUILD_REQUIRES} ) {
1026         $meta{build_requires} = _normalize_prereqs($self->{BUILD_REQUIRES});
1027     } else {
1028         $meta{build_requires} = {
1029             'ExtUtils::MakeMaker'       => 0,
1030         };
1031     }
1032
1033     if( $self->{ARGS}{TEST_REQUIRES} ) {
1034         $meta{build_requires} = {
1035           %{ $meta{build_requires} },
1036           %{ _normalize_prereqs($self->{TEST_REQUIRES}) },
1037         };
1038     }
1039
1040     $meta{requires} = _normalize_prereqs($self->{PREREQ_PM})
1041         if defined $self->{PREREQ_PM};
1042     $meta{requires}{perl} = _normalize_version($self->{MIN_PERL_VERSION})
1043         if $self->{MIN_PERL_VERSION};
1044
1045     return %meta;
1046 }
1047
1048 sub _add_requirements_to_meta_v2 {
1049     my ( $self, %meta ) = @_;
1050
1051     # Check the original args so we can tell between the user setting it
1052     # to an empty hash and it just being initialized.
1053     if( $self->{ARGS}{BUILD_REQUIRES} ) {
1054         $meta{prereqs}{build}{requires} = _normalize_prereqs($self->{BUILD_REQUIRES});
1055     } else {
1056         $meta{prereqs}{build}{requires} = {
1057             'ExtUtils::MakeMaker'       => 0,
1058         };
1059     }
1060
1061     if( $self->{ARGS}{TEST_REQUIRES} ) {
1062         $meta{prereqs}{test}{requires} = _normalize_prereqs($self->{TEST_REQUIRES});
1063     }
1064
1065     $meta{prereqs}{runtime}{requires} = _normalize_prereqs($self->{PREREQ_PM})
1066         if defined $self->{PREREQ_PM};
1067     $meta{prereqs}{runtime}{requires}{perl} = _normalize_version($self->{MIN_PERL_VERSION})
1068         if $self->{MIN_PERL_VERSION};
1069
1070     return %meta;
1071 }
1072
1073 sub _normalize_prereqs {
1074   my ($hash) = @_;
1075   my %prereqs;
1076   while ( my ($k,$v) = each %$hash ) {
1077     $prereqs{$k} = _normalize_version($v);
1078   }
1079   return \%prereqs;
1080 }
1081
1082 # Adapted from Module::Build::Base
1083 sub _normalize_version {
1084   my ($version) = @_;
1085   $version = 0 unless defined $version;
1086
1087   if ( ref $version eq 'version' ) { # version objects
1088     $version = $version->is_qv ? $version->normal : $version->stringify;
1089   }
1090   elsif ( $version =~ /^[^v][^.]*\.[^.]+\./ ) { # no leading v, multiple dots
1091     # normalize string tuples without "v": "1.2.3" -> "v1.2.3"
1092     $version = "v$version";
1093   }
1094   else {
1095     # leave alone
1096   }
1097   return $version;
1098 }
1099
1100 =head3 _dump_hash
1101
1102     $yaml = _dump_hash(\%options, %hash);
1103
1104 Implements a fake YAML dumper for a hash given
1105 as a list of pairs. No quoting/escaping is done. Keys
1106 are supposed to be strings. Values are undef, strings, 
1107 hash refs or array refs of strings.
1108
1109 Supported options are:
1110
1111     delta => STR - indentation delta
1112     use_header => BOOL - whether to include a YAML header
1113     indent => STR - a string of spaces 
1114           default: ''
1115
1116     max_key_length => INT - maximum key length used to align
1117         keys and values of the same hash
1118         default: 20
1119     key_sort => CODE - a sort sub 
1120             It may be undef, which means no sorting by keys
1121         default: sub { lc $a cmp lc $b }
1122
1123     customs => HASH - special options for certain keys 
1124            (whose values are hashes themselves)
1125         may contain: max_key_length, key_sort, customs
1126
1127 =end private
1128
1129 =cut
1130
1131 sub _dump_hash {
1132     croak "first argument should be a hash ref" unless ref $_[0] eq 'HASH';
1133     my $options = shift;
1134     my %hash = @_;
1135
1136     # Use a list to preserve order.
1137     my @pairs;
1138
1139     my $k_sort 
1140         = exists $options->{key_sort} ? $options->{key_sort} 
1141                                       : sub { lc $a cmp lc $b };
1142     if ($k_sort) {
1143         croak "'key_sort' should be a coderef" unless ref $k_sort eq 'CODE';
1144         @pairs = _sort_pairs($k_sort, \%hash);
1145     } else { # list of pairs, no sorting
1146         @pairs = @_;
1147     }
1148
1149     my $yaml     = $options->{use_header} ? "--- #YAML:1.0\n" : '';
1150     my $indent   = $options->{indent} || '';
1151     my $k_length = min(
1152         ($options->{max_key_length} || 20),
1153         max(map { length($_) + 1 } grep { !ref $hash{$_} } keys %hash)
1154     );
1155     my $customs  = $options->{customs} || {};
1156
1157     # printf format for key
1158     my $k_format = "%-${k_length}s";
1159
1160     while( @pairs ) {
1161         my($key, $val) = splice @pairs, 0, 2;
1162         $val = '~' unless defined $val;
1163         if(ref $val eq 'HASH') {
1164             if ( keys %$val ) {
1165                 my %k_options = ( # options for recursive call
1166                     delta => $options->{delta},
1167                     use_header => 0,
1168                     indent => $indent . $options->{delta},
1169                 );
1170                 if (exists $customs->{$key}) {
1171                     my %k_custom = %{$customs->{$key}};
1172                     foreach my $k (qw(key_sort max_key_length customs)) {
1173                         $k_options{$k} = $k_custom{$k} if exists $k_custom{$k};
1174                     }
1175                 }
1176                 $yaml .= $indent . "$key:\n" 
1177                   . _dump_hash(\%k_options, %$val);
1178             }
1179             else {
1180                 $yaml .= $indent . "$key:  {}\n";
1181             }
1182         }
1183         elsif (ref $val eq 'ARRAY') {
1184             if( @$val ) {
1185                 $yaml .= $indent . "$key:\n";
1186
1187                 for (@$val) {
1188                     croak "only nested arrays of non-refs are supported" if ref $_;
1189                     $yaml .= $indent . $options->{delta} . "- $_\n";
1190                 }
1191             }
1192             else {
1193                 $yaml .= $indent . "$key:  []\n";
1194             }
1195         }
1196         elsif( ref $val and !blessed($val) ) {
1197             croak "only nested hashes, arrays and objects are supported";
1198         }
1199         else {  # if it's an object, just stringify it
1200             $yaml .= $indent . sprintf "$k_format  %s\n", "$key:", $val;
1201         }
1202     };
1203
1204     return $yaml;
1205
1206 }
1207
1208 sub blessed {
1209     return eval { $_[0]->isa("UNIVERSAL"); };
1210 }
1211
1212 sub max {
1213     return (sort { $b <=> $a } @_)[0];
1214 }
1215
1216 sub min {
1217     return (sort { $a <=> $b } @_)[0];
1218 }
1219
1220 =head3 metafile_file
1221
1222     my $meta_yml = $mm->metafile_file(@metadata_pairs);
1223
1224 Turns the @metadata_pairs into YAML.
1225
1226 This method does not implement a complete YAML dumper, being limited
1227 to dump a hash with values which are strings, undef's or nested hashes
1228 and arrays of strings. No quoting/escaping is done.
1229
1230 =cut
1231
1232 sub metafile_file {
1233     my $self = shift;
1234
1235     my %dump_options = (
1236         use_header => 1, 
1237         delta      => ' ' x 4, 
1238         key_sort   => undef,
1239     );
1240     return _dump_hash(\%dump_options, @_);
1241
1242 }
1243
1244
1245 =head3 distmeta_target
1246
1247     my $make_frag = $mm->distmeta_target;
1248
1249 Generates the distmeta target to add META.yml to the MANIFEST in the
1250 distdir.
1251
1252 =cut
1253
1254 sub distmeta_target {
1255     my $self = shift;
1256
1257     my @add_meta = (
1258       $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']),
1259 exit unless -e q{META.yml};
1260 eval { maniadd({q{META.yml} => q{Module YAML meta-data (added by MakeMaker)}}) }
1261     or print "Could not add META.yml to MANIFEST: $${'@'}\n"
1262 CODE
1263       $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd'])
1264 exit unless -f q{META.json};
1265 eval { maniadd({q{META.json} => q{Module JSON meta-data (added by MakeMaker)}}) }
1266     or print "Could not add META.json to MANIFEST: $${'@'}\n"
1267 CODE
1268     );
1269
1270     my @add_meta_to_distdir = map { $self->cd('$(DISTVNAME)', $_) } @add_meta;
1271
1272     return sprintf <<'MAKE', @add_meta_to_distdir;
1273 distmeta : create_distdir metafile
1274         $(NOECHO) %s
1275         $(NOECHO) %s
1276
1277 MAKE
1278
1279 }
1280
1281
1282 =head3 mymeta
1283
1284     my $mymeta = $mm->mymeta;
1285
1286 Generate MYMETA information as a hash either from an existing META.yml
1287 or from internal data.
1288
1289 =cut
1290
1291 sub mymeta {
1292     my $self = shift;
1293     my $file = shift || ''; # for testing
1294
1295     my $mymeta = $self->_mymeta_from_meta($file);
1296     my $v2 = 1;
1297
1298     unless ( $mymeta ) {
1299         my @metadata = $self->metafile_data(
1300             $self->{META_ADD}   || {},
1301             $self->{META_MERGE} || {},
1302         );
1303         $mymeta = {@metadata};
1304         $v2 = 0;
1305     }
1306
1307     # Overwrite the non-configure dependency hashes
1308
1309     my $method = $v2
1310                ? '_add_requirements_to_meta_v2'
1311                : '_add_requirements_to_meta_v1_4';
1312
1313     $mymeta = { $self->$method( %$mymeta ) };
1314
1315     $mymeta->{dynamic_config} = 0;
1316
1317     return $mymeta;
1318 }
1319
1320
1321 sub _mymeta_from_meta {
1322     my $self = shift;
1323     my $metafile = shift || ''; # for testing
1324
1325     return unless _has_cpan_meta();
1326
1327     my $meta;
1328     for my $file ( $metafile, "META.json", "META.yml" ) {
1329       next unless -e $file;
1330       eval {
1331           $meta = CPAN::Meta->load_file($file)->as_struct( { version => 2 } );
1332       };
1333       last if $meta;
1334     }
1335     return unless $meta;
1336
1337     # META.yml before 6.25_01 cannot be trusted.  META.yml lived in the source directory.
1338     # There was a good chance the author accidentally uploaded a stale META.yml if they
1339     # rolled their own tarball rather than using "make dist".
1340     if ($meta->{generated_by} &&
1341         $meta->{generated_by} =~ /ExtUtils::MakeMaker version ([\d\._]+)/) {
1342         my $eummv = do { local $^W = 0; $1+0; };
1343         if ($eummv < 6.2501) {
1344             return;
1345         }
1346     }
1347
1348     return $meta;
1349 }
1350
1351 =head3 write_mymeta
1352
1353     $self->write_mymeta( $mymeta );
1354
1355 Write MYMETA information to MYMETA.yml.
1356
1357 This will probably be refactored into a more generic YAML dumping method.
1358
1359 =cut
1360
1361 sub write_mymeta {
1362     my $self = shift;
1363     my $mymeta = shift;
1364
1365     return unless _has_cpan_meta();
1366
1367     _fix_metadata_before_conversion( $mymeta );
1368     
1369     # this can still blow up
1370     # not sure if i should just eval this and skip file creation if it
1371     # blows up
1372     my $meta_obj = CPAN::Meta->new( $mymeta, { lazy_validation => 1 } );
1373     $meta_obj->save( 'MYMETA.json' );
1374     $meta_obj->save( 'MYMETA.yml', { version => "1.4" } );
1375     return 1;
1376 }
1377
1378 =head3 realclean (o)
1379
1380 Defines the realclean target.
1381
1382 =cut
1383
1384 sub realclean {
1385     my($self, %attribs) = @_;
1386
1387     my @dirs  = qw($(DISTVNAME));
1388     my @files = qw($(FIRST_MAKEFILE) $(MAKEFILE_OLD));
1389
1390     # Special exception for the perl core where INST_* is not in blib.
1391     # This cleans up the files built from the ext/ directory (all XS).
1392     if( $self->{PERL_CORE} ) {
1393         push @dirs, qw($(INST_AUTODIR) $(INST_ARCHAUTODIR));
1394         push @files, values %{$self->{PM}};
1395     }
1396
1397     if( $self->has_link_code ){
1398         push @files, qw($(OBJECT));
1399     }
1400
1401     if( $attribs{FILES} ) {
1402         if( ref $attribs{FILES} ) {
1403             push @dirs, @{ $attribs{FILES} };
1404         }
1405         else {
1406             push @dirs, split /\s+/, $attribs{FILES};
1407         }
1408     }
1409
1410     # Occasionally files are repeated several times from different sources
1411     { my(%f) = map { ($_ => 1) } @files;  @files = keys %f; }
1412     { my(%d) = map { ($_ => 1) } @dirs;   @dirs  = keys %d; }
1413
1414     my $rm_cmd  = join "\n\t", map { "$_" } 
1415                     $self->split_command('- $(RM_F)',  @files);
1416     my $rmf_cmd = join "\n\t", map { "$_" } 
1417                     $self->split_command('- $(RM_RF)', @dirs);
1418
1419     my $m = sprintf <<'MAKE', $rm_cmd, $rmf_cmd;
1420 # Delete temporary files (via clean) and also delete dist files
1421 realclean purge ::  clean realclean_subdirs
1422         %s
1423         %s
1424 MAKE
1425
1426     $m .= "\t$attribs{POSTOP}\n" if $attribs{POSTOP};
1427
1428     return $m;
1429 }
1430
1431
1432 =head3 realclean_subdirs_target
1433
1434   my $make_frag = $MM->realclean_subdirs_target;
1435
1436 Returns the realclean_subdirs target.  This is used by the realclean
1437 target to call realclean on any subdirectories which contain Makefiles.
1438
1439 =cut
1440
1441 sub realclean_subdirs_target {
1442     my $self = shift;
1443
1444     return <<'NOOP_FRAG' unless @{$self->{DIR}};
1445 realclean_subdirs :
1446         $(NOECHO) $(NOOP)
1447 NOOP_FRAG
1448
1449     my $rclean = "realclean_subdirs :\n";
1450
1451     foreach my $dir (@{$self->{DIR}}) {
1452         foreach my $makefile ('$(MAKEFILE_OLD)', '$(FIRST_MAKEFILE)' ) {
1453             my $subrclean .= $self->oneliner(sprintf <<'CODE', $dir, ($makefile) x 2);
1454 chdir '%s';  system '$(MAKE) $(USEMAKEFILE) %s realclean' if -f '%s';
1455 CODE
1456
1457             $rclean .= sprintf <<'RCLEAN', $subrclean;
1458         - %s
1459 RCLEAN
1460
1461         }
1462     }
1463
1464     return $rclean;
1465 }
1466
1467
1468 =head3 signature_target
1469
1470     my $target = $mm->signature_target;
1471
1472 Generate the signature target.
1473
1474 Writes the file SIGNATURE with "cpansign -s".
1475
1476 =cut
1477
1478 sub signature_target {
1479     my $self = shift;
1480
1481     return <<'MAKE_FRAG';
1482 signature :
1483         cpansign -s
1484 MAKE_FRAG
1485
1486 }
1487
1488
1489 =head3 distsignature_target
1490
1491     my $make_frag = $mm->distsignature_target;
1492
1493 Generates the distsignature target to add SIGNATURE to the MANIFEST in the
1494 distdir.
1495
1496 =cut
1497
1498 sub distsignature_target {
1499     my $self = shift;
1500
1501     my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
1502 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) } 
1503     or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
1504 CODE
1505
1506     my $sign_dist        = $self->cd('$(DISTVNAME)' => 'cpansign -s');
1507
1508     # cpansign -s complains if SIGNATURE is in the MANIFEST yet does not
1509     # exist
1510     my $touch_sig        = $self->cd('$(DISTVNAME)' => '$(TOUCH) SIGNATURE');
1511     my $add_sign_to_dist = $self->cd('$(DISTVNAME)' => $add_sign );
1512
1513     return sprintf <<'MAKE', $add_sign_to_dist, $touch_sig, $sign_dist
1514 distsignature : create_distdir
1515         $(NOECHO) %s
1516         $(NOECHO) %s
1517         %s
1518
1519 MAKE
1520
1521 }
1522
1523
1524 =head3 special_targets
1525
1526   my $make_frag = $mm->special_targets
1527
1528 Returns a make fragment containing any targets which have special
1529 meaning to make.  For example, .SUFFIXES and .PHONY.
1530
1531 =cut
1532
1533 sub special_targets {
1534     my $make_frag = <<'MAKE_FRAG';
1535 .SUFFIXES : .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
1536
1537 .PHONY: all config static dynamic test linkext manifest blibdirs clean realclean disttest distdir
1538
1539 MAKE_FRAG
1540
1541     $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
1542 .NO_CONFIG_REC: Makefile
1543
1544 MAKE_FRAG
1545
1546     return $make_frag;
1547 }
1548
1549
1550
1551
1552 =head2 Init methods
1553
1554 Methods which help initialize the MakeMaker object and macros.
1555
1556
1557 =head3 init_ABSTRACT
1558
1559     $mm->init_ABSTRACT
1560
1561 =cut
1562
1563 sub init_ABSTRACT {
1564     my $self = shift;
1565
1566     if( $self->{ABSTRACT_FROM} and $self->{ABSTRACT} ) {
1567         warn "Both ABSTRACT_FROM and ABSTRACT are set.  ".
1568              "Ignoring ABSTRACT_FROM.\n";
1569         return;
1570     }
1571
1572     if ($self->{ABSTRACT_FROM}){
1573         $self->{ABSTRACT} = $self->parse_abstract($self->{ABSTRACT_FROM}) or
1574             carp "WARNING: Setting ABSTRACT via file ".
1575                  "'$self->{ABSTRACT_FROM}' failed\n";
1576     }
1577 }
1578
1579 =head3 init_INST
1580
1581     $mm->init_INST;
1582
1583 Called by init_main.  Sets up all INST_* variables except those related
1584 to XS code.  Those are handled in init_xs.
1585
1586 =cut
1587
1588 sub init_INST {
1589     my($self) = shift;
1590
1591     $self->{INST_ARCHLIB} ||= $self->catdir($Curdir,"blib","arch");
1592     $self->{INST_BIN}     ||= $self->catdir($Curdir,'blib','bin');
1593
1594     # INST_LIB typically pre-set if building an extension after
1595     # perl has been built and installed. Setting INST_LIB allows
1596     # you to build directly into, say $Config{privlibexp}.
1597     unless ($self->{INST_LIB}){
1598         if ($self->{PERL_CORE}) {
1599             if (defined $Cross::platform) {
1600                 $self->{INST_LIB} = $self->{INST_ARCHLIB} = 
1601                   $self->catdir($self->{PERL_LIB},"..","xlib",
1602                                      $Cross::platform);
1603             }
1604             else {
1605                 $self->{INST_LIB} = $self->{INST_ARCHLIB} = $self->{PERL_LIB};
1606             }
1607         } else {
1608             $self->{INST_LIB} = $self->catdir($Curdir,"blib","lib");
1609         }
1610     }
1611
1612     my @parentdir = split(/::/, $self->{PARENT_NAME});
1613     $self->{INST_LIBDIR}      = $self->catdir('$(INST_LIB)',     @parentdir);
1614     $self->{INST_ARCHLIBDIR}  = $self->catdir('$(INST_ARCHLIB)', @parentdir);
1615     $self->{INST_AUTODIR}     = $self->catdir('$(INST_LIB)', 'auto', 
1616                                               '$(FULLEXT)');
1617     $self->{INST_ARCHAUTODIR} = $self->catdir('$(INST_ARCHLIB)', 'auto',
1618                                               '$(FULLEXT)');
1619
1620     $self->{INST_SCRIPT}  ||= $self->catdir($Curdir,'blib','script');
1621
1622     $self->{INST_MAN1DIR} ||= $self->catdir($Curdir,'blib','man1');
1623     $self->{INST_MAN3DIR} ||= $self->catdir($Curdir,'blib','man3');
1624
1625     return 1;
1626 }
1627
1628
1629 =head3 init_INSTALL
1630
1631     $mm->init_INSTALL;
1632
1633 Called by init_main.  Sets up all INSTALL_* variables (except
1634 INSTALLDIRS) and *PREFIX.
1635
1636 =cut
1637
1638 sub init_INSTALL {
1639     my($self) = shift;
1640
1641     if( $self->{ARGS}{INSTALL_BASE} and $self->{ARGS}{PREFIX} ) {
1642         die "Only one of PREFIX or INSTALL_BASE can be given.  Not both.\n";
1643     }
1644
1645     if( $self->{ARGS}{INSTALL_BASE} ) {
1646         $self->init_INSTALL_from_INSTALL_BASE;
1647     }
1648     else {
1649         $self->init_INSTALL_from_PREFIX;
1650     }
1651 }
1652
1653
1654 =head3 init_INSTALL_from_PREFIX
1655
1656   $mm->init_INSTALL_from_PREFIX;
1657
1658 =cut
1659
1660 sub init_INSTALL_from_PREFIX {
1661     my $self = shift;
1662
1663     $self->init_lib2arch;
1664
1665     # There are often no Config.pm defaults for these new man variables so 
1666     # we fall back to the old behavior which is to use installman*dir
1667     foreach my $num (1, 3) {
1668         my $k = 'installsiteman'.$num.'dir';
1669
1670         $self->{uc $k} ||= uc "\$(installman${num}dir)"
1671           unless $Config{$k};
1672     }
1673
1674     foreach my $num (1, 3) {
1675         my $k = 'installvendorman'.$num.'dir';
1676
1677         unless( $Config{$k} ) {
1678             $self->{uc $k}  ||= $Config{usevendorprefix}
1679                               ? uc "\$(installman${num}dir)"
1680                               : '';
1681         }
1682     }
1683
1684     $self->{INSTALLSITEBIN} ||= '$(INSTALLBIN)'
1685       unless $Config{installsitebin};
1686     $self->{INSTALLSITESCRIPT} ||= '$(INSTALLSCRIPT)'
1687       unless $Config{installsitescript};
1688
1689     unless( $Config{installvendorbin} ) {
1690         $self->{INSTALLVENDORBIN} ||= $Config{usevendorprefix} 
1691                                     ? $Config{installbin}
1692                                     : '';
1693     }
1694     unless( $Config{installvendorscript} ) {
1695         $self->{INSTALLVENDORSCRIPT} ||= $Config{usevendorprefix}
1696                                        ? $Config{installscript}
1697                                        : '';
1698     }
1699
1700
1701     my $iprefix = $Config{installprefixexp} || $Config{installprefix} || 
1702                   $Config{prefixexp}        || $Config{prefix} || '';
1703     my $vprefix = $Config{usevendorprefix}  ? $Config{vendorprefixexp} : '';
1704     my $sprefix = $Config{siteprefixexp}    || '';
1705
1706     # 5.005_03 doesn't have a siteprefix.
1707     $sprefix = $iprefix unless $sprefix;
1708
1709
1710     $self->{PREFIX}       ||= '';
1711
1712     if( $self->{PREFIX} ) {
1713         @{$self}{qw(PERLPREFIX SITEPREFIX VENDORPREFIX)} =
1714           ('$(PREFIX)') x 3;
1715     }
1716     else {
1717         $self->{PERLPREFIX}   ||= $iprefix;
1718         $self->{SITEPREFIX}   ||= $sprefix;
1719         $self->{VENDORPREFIX} ||= $vprefix;
1720
1721         # Lots of MM extension authors like to use $(PREFIX) so we
1722         # put something sensible in there no matter what.
1723         $self->{PREFIX} = '$('.uc $self->{INSTALLDIRS}.'PREFIX)';
1724     }
1725
1726     my $arch    = $Config{archname};
1727     my $version = $Config{version};
1728
1729     # default style
1730     my $libstyle = $Config{installstyle} || 'lib/perl5';
1731     my $manstyle = '';
1732
1733     if( $self->{LIBSTYLE} ) {
1734         $libstyle = $self->{LIBSTYLE};
1735         $manstyle = $self->{LIBSTYLE} eq 'lib/perl5' ? 'lib/perl5' : '';
1736     }
1737
1738     # Some systems, like VOS, set installman*dir to '' if they can't
1739     # read man pages.
1740     for my $num (1, 3) {
1741         $self->{'INSTALLMAN'.$num.'DIR'} ||= 'none'
1742           unless $Config{'installman'.$num.'dir'};
1743     }
1744
1745     my %bin_layouts = 
1746     (
1747         bin         => { s => $iprefix,
1748                          t => 'perl',
1749                          d => 'bin' },
1750         vendorbin   => { s => $vprefix,
1751                          t => 'vendor',
1752                          d => 'bin' },
1753         sitebin     => { s => $sprefix,
1754                          t => 'site',
1755                          d => 'bin' },
1756         script      => { s => $iprefix,
1757                          t => 'perl',
1758                          d => 'bin' },
1759         vendorscript=> { s => $vprefix,
1760                          t => 'vendor',
1761                          d => 'bin' },
1762         sitescript  => { s => $sprefix,
1763                          t => 'site',
1764                          d => 'bin' },
1765     );
1766     
1767     my %man_layouts =
1768     (
1769         man1dir         => { s => $iprefix,
1770                              t => 'perl',
1771                              d => 'man/man1',
1772                              style => $manstyle, },
1773         siteman1dir     => { s => $sprefix,
1774                              t => 'site',
1775                              d => 'man/man1',
1776                              style => $manstyle, },
1777         vendorman1dir   => { s => $vprefix,
1778                              t => 'vendor',
1779                              d => 'man/man1',
1780                              style => $manstyle, },
1781
1782         man3dir         => { s => $iprefix,
1783                              t => 'perl',
1784                              d => 'man/man3',
1785                              style => $manstyle, },
1786         siteman3dir     => { s => $sprefix,
1787                              t => 'site',
1788                              d => 'man/man3',
1789                              style => $manstyle, },
1790         vendorman3dir   => { s => $vprefix,
1791                              t => 'vendor',
1792                              d => 'man/man3',
1793                              style => $manstyle, },
1794     );
1795
1796     my %lib_layouts =
1797     (
1798         privlib     => { s => $iprefix,
1799                          t => 'perl',
1800                          d => '',
1801                          style => $libstyle, },
1802         vendorlib   => { s => $vprefix,
1803                          t => 'vendor',
1804                          d => '',
1805                          style => $libstyle, },
1806         sitelib     => { s => $sprefix,
1807                          t => 'site',
1808                          d => 'site_perl',
1809                          style => $libstyle, },
1810         
1811         archlib     => { s => $iprefix,
1812                          t => 'perl',
1813                          d => "$version/$arch",
1814                          style => $libstyle },
1815         vendorarch  => { s => $vprefix,
1816                          t => 'vendor',
1817                          d => "$version/$arch",
1818                          style => $libstyle },
1819         sitearch    => { s => $sprefix,
1820                          t => 'site',
1821                          d => "site_perl/$version/$arch",
1822                          style => $libstyle },
1823     );
1824
1825
1826     # Special case for LIB.
1827     if( $self->{LIB} ) {
1828         foreach my $var (keys %lib_layouts) {
1829             my $Installvar = uc "install$var";
1830
1831             if( $var =~ /arch/ ) {
1832                 $self->{$Installvar} ||= 
1833                   $self->catdir($self->{LIB}, $Config{archname});
1834             }
1835             else {
1836                 $self->{$Installvar} ||= $self->{LIB};
1837             }
1838         }
1839     }
1840
1841     my %type2prefix = ( perl    => 'PERLPREFIX',
1842                         site    => 'SITEPREFIX',
1843                         vendor  => 'VENDORPREFIX'
1844                       );
1845
1846     my %layouts = (%bin_layouts, %man_layouts, %lib_layouts);
1847     while( my($var, $layout) = each(%layouts) ) {
1848         my($s, $t, $d, $style) = @{$layout}{qw(s t d style)};
1849         my $r = '$('.$type2prefix{$t}.')';
1850
1851         warn "Prefixing $var\n" if $Verbose >= 2;
1852
1853         my $installvar = "install$var";
1854         my $Installvar = uc $installvar;
1855         next if $self->{$Installvar};
1856
1857         $d = "$style/$d" if $style;
1858         $self->prefixify($installvar, $s, $r, $d);
1859
1860         warn "  $Installvar == $self->{$Installvar}\n" 
1861           if $Verbose >= 2;
1862     }
1863
1864     # Generate these if they weren't figured out.
1865     $self->{VENDORARCHEXP} ||= $self->{INSTALLVENDORARCH};
1866     $self->{VENDORLIBEXP}  ||= $self->{INSTALLVENDORLIB};
1867
1868     return 1;
1869 }
1870
1871
1872 =head3 init_from_INSTALL_BASE
1873
1874     $mm->init_from_INSTALL_BASE
1875
1876 =cut
1877
1878 my %map = (
1879            lib      => [qw(lib perl5)],
1880            arch     => [('lib', 'perl5', $Config{archname})],
1881            bin      => [qw(bin)],
1882            man1dir  => [qw(man man1)],
1883            man3dir  => [qw(man man3)]
1884           );
1885 $map{script} = $map{bin};
1886
1887 sub init_INSTALL_from_INSTALL_BASE {
1888     my $self = shift;
1889
1890     @{$self}{qw(PREFIX VENDORPREFIX SITEPREFIX PERLPREFIX)} = 
1891                                                          '$(INSTALL_BASE)';
1892
1893     my %install;
1894     foreach my $thing (keys %map) {
1895         foreach my $dir (('', 'SITE', 'VENDOR')) {
1896             my $uc_thing = uc $thing;
1897             my $key = "INSTALL".$dir.$uc_thing;
1898
1899             $install{$key} ||= 
1900               $self->catdir('$(INSTALL_BASE)', @{$map{$thing}});
1901         }
1902     }
1903
1904     # Adjust for variable quirks.
1905     $install{INSTALLARCHLIB} ||= delete $install{INSTALLARCH};
1906     $install{INSTALLPRIVLIB} ||= delete $install{INSTALLLIB};
1907
1908     foreach my $key (keys %install) {
1909         $self->{$key} ||= $install{$key};
1910     }
1911
1912     return 1;
1913 }
1914
1915
1916 =head3 init_VERSION  I<Abstract>
1917
1918     $mm->init_VERSION
1919
1920 Initialize macros representing versions of MakeMaker and other tools
1921
1922 MAKEMAKER: path to the MakeMaker module.
1923
1924 MM_VERSION: ExtUtils::MakeMaker Version
1925
1926 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards 
1927              compat)
1928
1929 VERSION: version of your module
1930
1931 VERSION_MACRO: which macro represents the version (usually 'VERSION')
1932
1933 VERSION_SYM: like version but safe for use as an RCS revision number
1934
1935 DEFINE_VERSION: -D line to set the module version when compiling
1936
1937 XS_VERSION: version in your .xs file.  Defaults to $(VERSION)
1938
1939 XS_VERSION_MACRO: which macro represents the XS version.
1940
1941 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
1942
1943 Called by init_main.
1944
1945 =cut
1946
1947 sub init_VERSION {
1948     my($self) = shift;
1949
1950     $self->{MAKEMAKER}  = $ExtUtils::MakeMaker::Filename;
1951     $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
1952     $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
1953     $self->{VERSION_FROM} ||= '';
1954
1955     if ($self->{VERSION_FROM}){
1956         $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
1957         if( $self->{VERSION} eq 'undef' ) {
1958             carp("WARNING: Setting VERSION via file ".
1959                  "'$self->{VERSION_FROM}' failed\n");
1960         }
1961     }
1962
1963     # strip blanks
1964     if (defined $self->{VERSION}) {
1965         $self->{VERSION} =~ s/^\s+//;
1966         $self->{VERSION} =~ s/\s+$//;
1967     }
1968     else {
1969         $self->{VERSION} = '';
1970     }
1971
1972
1973     $self->{VERSION_MACRO}  = 'VERSION';
1974     ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
1975     $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
1976
1977
1978     # Graham Barr and Paul Marquess had some ideas how to ensure
1979     # version compatibility between the *.pm file and the
1980     # corresponding *.xs file. The bottomline was, that we need an
1981     # XS_VERSION macro that defaults to VERSION:
1982     $self->{XS_VERSION} ||= $self->{VERSION};
1983
1984     $self->{XS_VERSION_MACRO}  = 'XS_VERSION';
1985     $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
1986
1987 }
1988
1989
1990 =head3 init_tools
1991
1992     $MM->init_tools();
1993
1994 Initializes the simple macro definitions used by tools_other() and
1995 places them in the $MM object.  These use conservative cross platform
1996 versions and should be overridden with platform specific versions for
1997 performance.
1998
1999 Defines at least these macros.
2000
2001   Macro             Description
2002
2003   NOOP              Do nothing
2004   NOECHO            Tell make not to display the command itself
2005
2006   SHELL             Program used to run shell commands
2007
2008   ECHO              Print text adding a newline on the end
2009   RM_F              Remove a file 
2010   RM_RF             Remove a directory          
2011   TOUCH             Update a file's timestamp   
2012   TEST_F            Test for a file's existence 
2013   CP                Copy a file                 
2014   MV                Move a file                 
2015   CHMOD             Change permissions on a file
2016   FALSE             Exit with non-zero
2017   TRUE              Exit with zero
2018
2019   UMASK_NULL        Nullify umask
2020   DEV_NULL          Suppress all command output
2021
2022 =cut
2023
2024 sub init_tools {
2025     my $self = shift;
2026
2027     $self->{ECHO}     ||= $self->oneliner('print qq{@ARGV}', ['-l']);
2028     $self->{ECHO_N}   ||= $self->oneliner('print qq{@ARGV}');
2029
2030     $self->{TOUCH}    ||= $self->oneliner('touch', ["-MExtUtils::Command"]);
2031     $self->{CHMOD}    ||= $self->oneliner('chmod', ["-MExtUtils::Command"]);
2032     $self->{RM_F}     ||= $self->oneliner('rm_f',  ["-MExtUtils::Command"]);
2033     $self->{RM_RF}    ||= $self->oneliner('rm_rf', ["-MExtUtils::Command"]);
2034     $self->{TEST_F}   ||= $self->oneliner('test_f', ["-MExtUtils::Command"]);
2035     $self->{FALSE}    ||= $self->oneliner('exit 1');
2036     $self->{TRUE}     ||= $self->oneliner('exit 0');
2037
2038     $self->{MKPATH}   ||= $self->oneliner('mkpath', ["-MExtUtils::Command"]);
2039
2040     $self->{CP}       ||= $self->oneliner('cp', ["-MExtUtils::Command"]);
2041     $self->{MV}       ||= $self->oneliner('mv', ["-MExtUtils::Command"]);
2042
2043     $self->{MOD_INSTALL} ||= 
2044       $self->oneliner(<<'CODE', ['-MExtUtils::Install']);
2045 install([ from_to => {@ARGV}, verbose => '$(VERBINST)', uninstall_shadows => '$(UNINST)', dir_mode => '$(PERM_DIR)' ]);
2046 CODE
2047     $self->{DOC_INSTALL} ||= $self->oneliner('perllocal_install', ["-MExtUtils::Command::MM"]);
2048     $self->{UNINSTALL}   ||= $self->oneliner('uninstall', ["-MExtUtils::Command::MM"]);
2049     $self->{WARN_IF_OLD_PACKLIST} ||= 
2050       $self->oneliner('warn_if_old_packlist', ["-MExtUtils::Command::MM"]);
2051     $self->{FIXIN}       ||= $self->oneliner('MY->fixin(shift)', ["-MExtUtils::MY"]);
2052     $self->{EQUALIZE_TIMESTAMP} ||= $self->oneliner('eqtime', ["-MExtUtils::Command"]);
2053
2054     $self->{UNINST}     ||= 0;
2055     $self->{VERBINST}   ||= 0;
2056
2057     $self->{SHELL}              ||= $Config{sh};
2058
2059     # UMASK_NULL is not used by MakeMaker but some CPAN modules
2060     # make use of it.
2061     $self->{UMASK_NULL}         ||= "umask 0";
2062
2063     # Not the greatest default, but its something.
2064     $self->{DEV_NULL}           ||= "> /dev/null 2>&1";
2065
2066     $self->{NOOP}               ||= '$(TRUE)';
2067     $self->{NOECHO}             = '@' unless defined $self->{NOECHO};
2068
2069     $self->{FIRST_MAKEFILE}     ||= $self->{MAKEFILE} || 'Makefile';
2070     $self->{MAKEFILE}           ||= $self->{FIRST_MAKEFILE};
2071     $self->{MAKEFILE_OLD}       ||= $self->{MAKEFILE}.'.old';
2072     $self->{MAKE_APERL_FILE}    ||= $self->{MAKEFILE}.'.aperl';
2073
2074     # Not everybody uses -f to indicate "use this Makefile instead"
2075     $self->{USEMAKEFILE}        ||= '-f';
2076
2077     # Some makes require a wrapper around macros passed in on the command 
2078     # line.
2079     $self->{MACROSTART}         ||= '';
2080     $self->{MACROEND}           ||= '';
2081
2082     return;
2083 }
2084
2085
2086 =head3 init_others
2087
2088     $MM->init_others();
2089
2090 Initializes the macro definitions having to do with compiling and
2091 linking used by tools_other() and places them in the $MM object.
2092
2093 If there is no description, its the same as the parameter to
2094 WriteMakefile() documented in ExtUtils::MakeMaker.
2095
2096 =cut
2097
2098 sub init_others {
2099     my $self = shift;
2100
2101     $self->{LD_RUN_PATH} = "";
2102
2103     $self->{LIBS} = $self->_fix_libs($self->{LIBS});
2104
2105     # Compute EXTRALIBS, BSLOADLIBS and LDLOADLIBS from $self->{LIBS}
2106     foreach my $libs ( @{$self->{LIBS}} ){
2107         $libs =~ s/^\s*(.*\S)\s*$/$1/; # remove leading and trailing whitespace
2108         my(@libs) = $self->extliblist($libs);
2109         if ($libs[0] or $libs[1] or $libs[2]){
2110             # LD_RUN_PATH now computed by ExtUtils::Liblist
2111             ($self->{EXTRALIBS},  $self->{BSLOADLIBS}, 
2112              $self->{LDLOADLIBS}, $self->{LD_RUN_PATH}) = @libs;
2113             last;
2114         }
2115     }
2116
2117     if ( $self->{OBJECT} ) {
2118         $self->{OBJECT} =~ s!\.o(bj)?\b!\$(OBJ_EXT)!g;
2119     } else {
2120         # init_dirscan should have found out, if we have C files
2121         $self->{OBJECT} = "";
2122         $self->{OBJECT} = '$(BASEEXT)$(OBJ_EXT)' if @{$self->{C}||[]};
2123     }
2124     $self->{OBJECT} =~ s/\n+/ \\\n\t/g;
2125
2126     $self->{BOOTDEP}  = (-f "$self->{BASEEXT}_BS") ? "$self->{BASEEXT}_BS" : "";
2127     $self->{PERLMAINCC} ||= '$(CC)';
2128     $self->{LDFROM} = '$(OBJECT)' unless $self->{LDFROM};
2129
2130     # Sanity check: don't define LINKTYPE = dynamic if we're skipping
2131     # the 'dynamic' section of MM.  We don't have this problem with
2132     # 'static', since we either must use it (%Config says we can't
2133     # use dynamic loading) or the caller asked for it explicitly.
2134     if (!$self->{LINKTYPE}) {
2135        $self->{LINKTYPE} = $self->{SKIPHASH}{'dynamic'}
2136                         ? 'static'
2137                         : ($Config{usedl} ? 'dynamic' : 'static');
2138     }
2139
2140     return;
2141 }
2142
2143
2144 # Lets look at $self->{LIBS} carefully: It may be an anon array, a string or
2145 # undefined. In any case we turn it into an anon array
2146 sub _fix_libs {
2147     my($self, $libs) = @_;
2148
2149     return !defined $libs       ? ['']          : 
2150            !ref $libs           ? [$libs]       :
2151            !defined $libs->[0]  ? ['']          :
2152                                   $libs         ;
2153 }
2154
2155
2156 =head3 tools_other
2157
2158     my $make_frag = $MM->tools_other;
2159
2160 Returns a make fragment containing definitions for the macros init_others() 
2161 initializes.
2162
2163 =cut
2164
2165 sub tools_other {
2166     my($self) = shift;
2167     my @m;
2168
2169     # We set PM_FILTER as late as possible so it can see all the earlier
2170     # on macro-order sensitive makes such as nmake.
2171     for my $tool (qw{ SHELL CHMOD CP MV NOOP NOECHO RM_F RM_RF TEST_F TOUCH 
2172                       UMASK_NULL DEV_NULL MKPATH EQUALIZE_TIMESTAMP
2173                       FALSE TRUE
2174                       ECHO ECHO_N
2175                       UNINST VERBINST
2176                       MOD_INSTALL DOC_INSTALL UNINSTALL
2177                       WARN_IF_OLD_PACKLIST
2178                       MACROSTART MACROEND
2179                       USEMAKEFILE
2180                       PM_FILTER
2181                       FIXIN
2182                     } ) 
2183     {
2184         next unless defined $self->{$tool};
2185         push @m, "$tool = $self->{$tool}\n";
2186     }
2187
2188     return join "", @m;
2189 }
2190
2191
2192 =head3 init_DIRFILESEP  I<Abstract>
2193
2194   $MM->init_DIRFILESEP;
2195   my $dirfilesep = $MM->{DIRFILESEP};
2196
2197 Initializes the DIRFILESEP macro which is the seperator between the
2198 directory and filename in a filepath.  ie. / on Unix, \ on Win32 and
2199 nothing on VMS.
2200
2201 For example:
2202
2203     # instead of $(INST_ARCHAUTODIR)/extralibs.ld
2204     $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
2205
2206 Something of a hack but it prevents a lot of code duplication between
2207 MM_* variants.
2208
2209 Do not use this as a seperator between directories.  Some operating
2210 systems use different seperators between subdirectories as between
2211 directories and filenames (for example:  VOLUME:[dir1.dir2]file on VMS).
2212
2213 =head3 init_linker  I<Abstract>
2214
2215     $mm->init_linker;
2216
2217 Initialize macros which have to do with linking.
2218
2219 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
2220 extensions.
2221
2222 PERL_ARCHIVE_AFTER: path to a library which should be put on the
2223 linker command line I<after> the external libraries to be linked to
2224 dynamic extensions.  This may be needed if the linker is one-pass, and
2225 Perl includes some overrides for C RTL functions, such as malloc().
2226
2227 EXPORT_LIST: name of a file that is passed to linker to define symbols
2228 to be exported.
2229
2230 Some OSes do not need these in which case leave it blank.
2231
2232
2233 =head3 init_platform
2234
2235     $mm->init_platform
2236
2237 Initialize any macros which are for platform specific use only.
2238
2239 A typical one is the version number of your OS specific mocule.
2240 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
2241
2242 =cut
2243
2244 sub init_platform {
2245     return '';
2246 }
2247
2248
2249 =head3 init_MAKE
2250
2251     $mm->init_MAKE
2252
2253 Initialize MAKE from either a MAKE environment variable or $Config{make}.
2254
2255 =cut
2256
2257 sub init_MAKE {
2258     my $self = shift;
2259
2260     $self->{MAKE} ||= $ENV{MAKE} || $Config{make};
2261 }
2262
2263
2264 =head2 Tools
2265
2266 A grab bag of methods to generate specific macros and commands.
2267
2268
2269
2270 =head3 manifypods
2271
2272 Defines targets and routines to translate the pods into manpages and
2273 put them into the INST_* directories.
2274
2275 =cut
2276
2277 sub manifypods {
2278     my $self          = shift;
2279
2280     my $POD2MAN_macro = $self->POD2MAN_macro();
2281     my $manifypods_target = $self->manifypods_target();
2282
2283     return <<END_OF_TARGET;
2284
2285 $POD2MAN_macro
2286
2287 $manifypods_target
2288
2289 END_OF_TARGET
2290
2291 }
2292
2293
2294 =head3 POD2MAN_macro
2295
2296   my $pod2man_macro = $self->POD2MAN_macro
2297
2298 Returns a definition for the POD2MAN macro.  This is a program
2299 which emulates the pod2man utility.  You can add more switches to the
2300 command by simply appending them on the macro.
2301
2302 Typical usage:
2303
2304     $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
2305
2306 =cut
2307
2308 sub POD2MAN_macro {
2309     my $self = shift;
2310
2311 # Need the trailing '--' so perl stops gobbling arguments and - happens
2312 # to be an alternative end of line seperator on VMS so we quote it
2313     return <<'END_OF_DEF';
2314 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
2315 POD2MAN = $(POD2MAN_EXE)
2316 END_OF_DEF
2317 }
2318
2319
2320 =head3 test_via_harness
2321
2322   my $command = $mm->test_via_harness($perl, $tests);
2323
2324 Returns a $command line which runs the given set of $tests with
2325 Test::Harness and the given $perl.
2326
2327 Used on the t/*.t files.
2328
2329 =cut
2330
2331 sub test_via_harness {
2332     my($self, $perl, $tests) = @_;
2333
2334     return qq{\t$perl "-MExtUtils::Command::MM" }.
2335            qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
2336 }
2337
2338 =head3 test_via_script
2339
2340   my $command = $mm->test_via_script($perl, $script);
2341
2342 Returns a $command line which just runs a single test without
2343 Test::Harness.  No checks are done on the results, they're just
2344 printed.
2345
2346 Used for test.pl, since they don't always follow Test::Harness
2347 formatting.
2348
2349 =cut
2350
2351 sub test_via_script {
2352     my($self, $perl, $script) = @_;
2353     return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
2354 }
2355
2356
2357 =head3 tool_autosplit
2358
2359 Defines a simple perl call that runs autosplit. May be deprecated by
2360 pm_to_blib soon.
2361
2362 =cut
2363
2364 sub tool_autosplit {
2365     my($self, %attribs) = @_;
2366
2367     my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};' 
2368                                   : '';
2369
2370     my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
2371 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
2372 PERL_CODE
2373
2374     return sprintf <<'MAKE_FRAG', $asplit;
2375 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
2376 AUTOSPLITFILE = %s
2377
2378 MAKE_FRAG
2379
2380 }
2381
2382
2383 =head3 arch_check
2384
2385     my $arch_ok = $mm->arch_check(
2386         $INC{"Config.pm"},
2387         File::Spec->catfile($Config{archlibexp}, "Config.pm")
2388     );
2389
2390 A sanity check that what Perl thinks the architecture is and what
2391 Config thinks the architecture is are the same.  If they're not it
2392 will return false and show a diagnostic message.
2393
2394 When building Perl it will always return true, as nothing is installed
2395 yet.
2396
2397 The interface is a bit odd because this is the result of a
2398 quick refactoring.  Don't rely on it.
2399
2400 =cut
2401
2402 sub arch_check {
2403     my $self = shift;
2404     my($pconfig, $cconfig) = @_;
2405
2406     return 1 if $self->{PERL_SRC};
2407
2408     my($pvol, $pthinks) = $self->splitpath($pconfig);
2409     my($cvol, $cthinks) = $self->splitpath($cconfig);
2410
2411     $pthinks = $self->canonpath($pthinks);
2412     $cthinks = $self->canonpath($cthinks);
2413
2414     my $ret = 1;
2415     if ($pthinks ne $cthinks) {
2416         print "Have $pthinks\n";
2417         print "Want $cthinks\n";
2418
2419         $ret = 0;
2420
2421         my $arch = (grep length, $self->splitdir($pthinks))[-1];
2422
2423         print <<END unless $self->{UNINSTALLED_PERL};
2424 Your perl and your Config.pm seem to have different ideas about the 
2425 architecture they are running on.
2426 Perl thinks: [$arch]
2427 Config says: [$Config{archname}]
2428 This may or may not cause problems. Please check your installation of perl 
2429 if you have problems building this extension.
2430 END
2431     }
2432
2433     return $ret;
2434 }
2435
2436
2437
2438 =head2 File::Spec wrappers
2439
2440 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
2441 override File::Spec.
2442
2443
2444
2445 =head3 catfile
2446
2447 File::Spec <= 0.83 has a bug where the file part of catfile is not
2448 canonicalized.  This override fixes that bug.
2449
2450 =cut
2451
2452 sub catfile {
2453     my $self = shift;
2454     return $self->canonpath($self->SUPER::catfile(@_));
2455 }
2456
2457
2458
2459 =head2 Misc
2460
2461 Methods I can't really figure out where they should go yet.
2462
2463
2464 =head3 find_tests
2465
2466   my $test = $mm->find_tests;
2467
2468 Returns a string suitable for feeding to the shell to return all
2469 tests in t/*.t.
2470
2471 =cut
2472
2473 sub find_tests {
2474     my($self) = shift;
2475     return -d 't' ? 't/*.t' : '';
2476 }
2477
2478
2479 =head3 extra_clean_files
2480
2481     my @files_to_clean = $MM->extra_clean_files;
2482
2483 Returns a list of OS specific files to be removed in the clean target in
2484 addition to the usual set.
2485
2486 =cut
2487
2488 # An empty method here tickled a perl 5.8.1 bug and would return its object.
2489 sub extra_clean_files { 
2490     return;
2491 }
2492
2493
2494 =head3 installvars
2495
2496     my @installvars = $mm->installvars;
2497
2498 A list of all the INSTALL* variables without the INSTALL prefix.  Useful
2499 for iteration or building related variable sets.
2500
2501 =cut
2502
2503 sub installvars {
2504     return qw(PRIVLIB SITELIB  VENDORLIB
2505               ARCHLIB SITEARCH VENDORARCH
2506               BIN     SITEBIN  VENDORBIN
2507               SCRIPT  SITESCRIPT  VENDORSCRIPT
2508               MAN1DIR SITEMAN1DIR VENDORMAN1DIR
2509               MAN3DIR SITEMAN3DIR VENDORMAN3DIR
2510              );
2511 }
2512
2513
2514 =head3 libscan
2515
2516   my $wanted = $self->libscan($path);
2517
2518 Takes a path to a file or dir and returns an empty string if we don't
2519 want to include this file in the library.  Otherwise it returns the
2520 the $path unchanged.
2521
2522 Mainly used to exclude version control administrative directories from
2523 installation.
2524
2525 =cut
2526
2527 sub libscan {
2528     my($self,$path) = @_;
2529     my($dirs,$file) = ($self->splitpath($path))[1,2];
2530     return '' if grep /^(?:RCS|CVS|SCCS|\.svn|_darcs)$/, 
2531                      $self->splitdir($dirs), $file;
2532
2533     return $path;
2534 }
2535
2536
2537 =head3 platform_constants
2538
2539     my $make_frag = $mm->platform_constants
2540
2541 Returns a make fragment defining all the macros initialized in
2542 init_platform() rather than put them in constants().
2543
2544 =cut
2545
2546 sub platform_constants {
2547     return '';
2548 }
2549
2550 =begin private
2551
2552 =head3 _PREREQ_PRINT
2553
2554     $self->_PREREQ_PRINT;
2555
2556 Implements PREREQ_PRINT.
2557
2558 Refactored out of MakeMaker->new().
2559
2560 =end private
2561
2562 =cut
2563
2564 sub _PREREQ_PRINT {
2565     my $self = shift;
2566
2567     require Data::Dumper;
2568     my @what = ('PREREQ_PM');
2569     push @what, 'MIN_PERL_VERSION' if $self->{MIN_PERL_VERSION};
2570     push @what, 'BUILD_REQUIRES'   if $self->{BUILD_REQUIRES};
2571     print Data::Dumper->Dump([@{$self}{@what}], \@what);
2572     exit 0;
2573 }
2574
2575
2576 =begin private
2577
2578 =head3 _PRINT_PREREQ
2579
2580   $mm->_PRINT_PREREQ;
2581
2582 Implements PRINT_PREREQ, a slightly different version of PREREQ_PRINT
2583 added by Redhat to, I think, support generating RPMs from Perl modules.
2584
2585 Should not include BUILD_REQUIRES as RPMs do not incluide them.
2586
2587 Refactored out of MakeMaker->new().
2588
2589 =end private
2590
2591 =cut
2592
2593 sub _PRINT_PREREQ {
2594     my $self = shift;
2595
2596     my $prereqs= $self->{PREREQ_PM};
2597     my @prereq = map { [$_, $prereqs->{$_}] } keys %$prereqs;
2598
2599     if ( $self->{MIN_PERL_VERSION} ) {
2600         push @prereq, ['perl' => $self->{MIN_PERL_VERSION}];
2601     }
2602
2603     print join(" ", map { "perl($_->[0])>=$_->[1] " }
2604                  sort { $a->[0] cmp $b->[0] } @prereq), "\n";
2605     exit 0;
2606 }
2607
2608
2609 =begin private
2610
2611 =head3 _all_prereqs
2612
2613   my $prereqs = $self->_all_prereqs;
2614
2615 Returns a hash ref of both PREREQ_PM and BUILD_REQUIRES.
2616
2617 =end private
2618
2619 =cut
2620
2621 sub _all_prereqs {
2622     my $self = shift;
2623
2624     return { %{$self->{PREREQ_PM}}, %{$self->{BUILD_REQUIRES}} };
2625 }
2626
2627 =begin private
2628
2629 =head3 _perl_header_files
2630
2631   my $perl_header_files= $self->_perl_header_files;
2632
2633 returns a sorted list of header files as found in PERL_SRC or $archlibexp/CORE.
2634
2635 Used by perldepend() in MM_Unix and MM_VMS via _perl_header_files_fragment()
2636
2637 =end private
2638
2639 =cut
2640
2641 sub _perl_header_files {
2642     my $self = shift;
2643
2644     my $header_dir = $self->{PERL_SRC} || $self->catdir($Config{archlibexp}, 'CORE');
2645     opendir my $dh, $header_dir
2646         or die "Failed to opendir '$header_dir' to find header files: $!";
2647
2648     # we need to use a temporary here as the sort in scalar context would have undefined results.
2649     my @perl_headers= sort grep { /\.h\z/ } readdir($dh);
2650
2651     closedir $dh;
2652
2653     return @perl_headers;
2654 }
2655
2656 =begin private
2657
2658 =head3 _perl_header_files_fragment ($o, $separator)
2659
2660   my $perl_header_files_fragment= $self->_perl_header_files_fragment("/");
2661
2662 return a Makefile fragment which holds the list of perl header files which
2663 XS code depends on $(PERL_INC), and sets up the dependency for the $(OBJECT) file.
2664
2665 The $separator argument defaults to "". MM_VMS will set it to "" and MM_UNIX to "/"
2666 in perldepend(). This reason child subclasses need to control this is that in
2667 VMS the $(PERL_INC) directory will already have delimiters in it, but in
2668 UNIX $(PERL_INC) will need a slash between it an the filename. Hypothetically
2669 win32 could use "\\" (but it doesn't need to).
2670
2671 =end private
2672
2673 =cut
2674
2675 sub _perl_header_files_fragment {
2676     my ($self, $separator)= @_;
2677     $separator ||= "";
2678     return join("\\\n",
2679                 "PERL_HDRS = ",
2680                 map {
2681                     sprintf( "        \$(PERL_INC)%s%s            ", $separator, $_ )
2682                 } $self->_perl_header_files()
2683            ) . "\n\n"
2684            . "\$(OBJECT) : \$(PERL_HDRS)\n";
2685 }
2686
2687
2688 =head1 AUTHOR
2689
2690 Michael G Schwern <schwern@pobox.com> and the denizens of
2691 makemaker@perl.org with code from ExtUtils::MM_Unix and
2692 ExtUtils::MM_Win32.
2693
2694
2695 =cut
2696
2697 1;