This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
ExtUtils::MakeMaker 6.10_06 (plus FAQ update)
[perl5.git] / lib / ExtUtils / MM_Any.pm
1 package ExtUtils::MM_Any;
2
3 use strict;
4 use vars qw($VERSION @ISA);
5 $VERSION = 0.06;
6 @ISA = qw(File::Spec);
7
8 use Config;
9 use File::Spec;
10
11
12 =head1 NAME
13
14 ExtUtils::MM_Any - Platform agnostic MM methods
15
16 =head1 SYNOPSIS
17
18   FOR INTERNAL USE ONLY!
19
20   package ExtUtils::MM_SomeOS;
21
22   # Temporarily, you have to subclass both.  Put MM_Any first.
23   require ExtUtils::MM_Any;
24   require ExtUtils::MM_Unix;
25   @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
26
27 =head1 DESCRIPTION
28
29 B<FOR INTERNAL USE ONLY!>
30
31 ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
32 modules.  It contains methods which are either inherently
33 cross-platform or are written in a cross-platform manner.
34
35 Subclass off of ExtUtils::MM_Any I<and> ExtUtils::MM_Unix.  This is a
36 temporary solution.
37
38 B<THIS MAY BE TEMPORARY!>
39
40 =head1 Inherently Cross-Platform Methods
41
42 These are methods which are by their nature cross-platform and should
43 always be cross-platform.
44
45 =over 4
46
47 =item os_flavor_is
48
49     $mm->os_flavor_is($this_flavor);
50     $mm->os_flavor_is(@one_of_these_flavors);
51
52 Checks to see if the current operating system is one of the given flavors.
53
54 This is useful for code like:
55
56     if( $mm->os_flavor_is('Unix') ) {
57         $out = `foo 2>&1`;
58     }
59     else {
60         $out = `foo`;
61     }
62
63 =cut
64
65 sub os_flavor_is {
66     my $self = shift;
67     my %flavors = map { ($_ => 1) } $self->os_flavor;
68     return (grep { $flavors{$_} } @_) ? 1 : 0;
69 }
70
71 =back
72
73 =head2 File::Spec wrappers
74
75 ExtUtils::MM_Any is a subclass of File::Spec.  The methods noted here
76 override File::Spec.
77
78 =over 4
79
80 =item catfile
81
82 File::Spec <= 0.83 has a bug where the file part of catfile is not
83 canonicalized.  This override fixes that bug.
84
85 =cut
86
87 sub catfile {
88     my $self = shift;
89     return $self->canonpath($self->SUPER::catfile(@_));
90 }
91
92 =back
93
94 =head1 Thought To Be Cross-Platform Methods
95
96 These are methods which are thought to be cross-platform by virtue of
97 having been written in a way to avoid incompatibilities.  They may
98 require partial overrides.
99
100 =over 4
101
102 =item B<split_command>
103
104     my @cmds = $MM->split_command($cmd, @args);
105
106 Most OS have a maximum command length they can execute at once.  Large
107 modules can easily generate commands well past that limit.  Its
108 necessary to split long commands up into a series of shorter commands.
109
110 split_command() will return a series of @cmds each processing part of
111 the args.  Collectively they will process all the arguments.  Each
112 individual line in @cmds will not be longer than the
113 $self->max_exec_len being careful to take into account macro expansion.
114
115 $cmd should include any switches and repeated initial arguments.
116
117 If no @args are given, no @cmds will be returned.
118
119 Pairs of arguments will always be preserved in a single command, this
120 is a heuristic for things like pm_to_blib and pod2man which work on
121 pairs of arguments.  This makes things like this safe:
122
123     $self->split_command($cmd, %pod2man);
124
125
126 =cut
127
128 sub split_command {
129     my($self, $cmd, @args) = @_;
130
131     my @cmds = ();
132     return(@cmds) unless @args;
133
134     # If the command was given as a here-doc, there's probably a trailing
135     # newline.
136     chomp $cmd;
137
138     # set aside 20% for macro expansion.
139     my $len_left = int($self->max_exec_len * 0.80);
140     $len_left -= length $self->_expand_macros($cmd);
141
142     do {
143         my $arg_str = '';
144         my @next_args;
145         while( @next_args = splice(@args, 0, 2) ) {
146             # Two at a time to preserve pairs.
147             my $next_arg_str = "\t  ". join ' ', @next_args, "\n";
148
149             if( !length $arg_str ) {
150                 $arg_str .= $next_arg_str
151             }
152             elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
153                 unshift @args, @next_args;
154                 last;
155             }
156             else {
157                 $arg_str .= $next_arg_str;
158             }
159         }
160         chop $arg_str;
161
162         push @cmds, $self->escape_newlines("$cmd\n$arg_str");
163     } while @args;
164
165     return @cmds;
166 }
167
168
169 sub _expand_macros {
170     my($self, $cmd) = @_;
171
172     $cmd =~ s{\$\((\w+)\)}{
173         defined $self->{$1} ? $self->{$1} : "\$($1)"
174     }e;
175     return $cmd;
176 }
177
178
179 =item B<echo>
180
181     my @commands = $MM->echo($text);
182     my @commands = $MM->echo($text, $file);
183     my @commands = $MM->echo($text, $file, $appending);
184
185 Generates a set of @commands which print the $text to a $file.
186
187 If $file is not given, output goes to STDOUT.
188
189 If $appending is true the $file will be appended to rather than
190 overwritten.
191
192 =cut
193
194 sub echo {
195     my($self, $text, $file, $appending) = @_;
196     $appending ||= 0;
197
198     my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_) } 
199                split /\n/, $text;
200     if( $file ) {
201         my $redirect = $appending ? '>>' : '>';
202         $cmds[0] .= " $redirect $file";
203         $_ .= " >> $file" foreach @cmds[1..$#cmds];
204     }
205
206     return @cmds;
207 }
208
209
210 =item init_VERSION
211
212     $mm->init_VERSION
213
214 Initialize macros representing versions of MakeMaker and other tools
215
216 MAKEMAKER: path to the MakeMaker module.
217
218 MM_VERSION: ExtUtils::MakeMaker Version
219
220 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards 
221              compat)
222
223 VERSION: version of your module
224
225 VERSION_MACRO: which macro represents the version (usually 'VERSION')
226
227 VERSION_SYM: like version but safe for use as an RCS revision number
228
229 DEFINE_VERSION: -D line to set the module version when compiling
230
231 XS_VERSION: version in your .xs file.  Defaults to $(VERSION)
232
233 XS_VERSION_MACRO: which macro represents the XS version.
234
235 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
236
237 Called by init_main.
238
239 =cut
240
241 sub init_VERSION {
242     my($self) = shift;
243
244     $self->{MAKEMAKER}  = $ExtUtils::MakeMaker::Filename;
245     $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
246     $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
247     $self->{VERSION_FROM} ||= '';
248
249     if ($self->{VERSION_FROM}){
250         $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
251         if( $self->{VERSION} eq 'undef' ) {
252             require Carp;
253             Carp::carp("WARNING: Setting VERSION via file ".
254                        "'$self->{VERSION_FROM}' failed\n");
255         }
256     }
257
258     # strip blanks
259     if (defined $self->{VERSION}) {
260         $self->{VERSION} =~ s/^\s+//;
261         $self->{VERSION} =~ s/\s+$//;
262     }
263     else {
264         $self->{VERSION} = '';
265     }
266
267
268     $self->{VERSION_MACRO}  = 'VERSION';
269     ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
270     $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
271
272
273     # Graham Barr and Paul Marquess had some ideas how to ensure
274     # version compatibility between the *.pm file and the
275     # corresponding *.xs file. The bottomline was, that we need an
276     # XS_VERSION macro that defaults to VERSION:
277     $self->{XS_VERSION} ||= $self->{VERSION};
278
279     $self->{XS_VERSION_MACRO}  = 'XS_VERSION';
280     $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
281
282 }
283
284 =item wraplist
285
286 Takes an array of items and turns them into a well-formatted list of
287 arguments.  In most cases this is simply something like:
288
289     FOO \
290     BAR \
291     BAZ
292
293 =cut
294
295 sub wraplist {
296     my $self = shift;
297     return join " \\\n\t", @_;
298 }
299
300 =item manifypods
301
302 Defines targets and routines to translate the pods into manpages and
303 put them into the INST_* directories.
304
305 =cut
306
307 sub manifypods {
308     my $self          = shift;
309
310     my $POD2MAN_EXE_macro = $self->POD2MAN_EXE_macro();
311     my $manifypods_target = $self->manifypods_target();
312
313     return <<END_OF_TARGET;
314
315 # --- Begin manifypods section:
316 $POD2MAN_EXE_macro
317
318 $manifypods_target
319
320 # --- End manifypods section --- #
321
322 END_OF_TARGET
323
324 }
325
326
327 =item manifypods_target
328
329   my $manifypods_target = $self->manifypods_target;
330
331 Generates the manifypods target.  This target generates man pages from
332 all POD files in MAN1PODS and MAN3PODS.
333
334 =cut
335
336 sub manifypods_target {
337     my($self) = shift;
338
339     my $man1pods      = '';
340     my $man3pods      = '';
341     my $dependencies  = '';
342
343     # populate manXpods & dependencies:
344     foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
345         $dependencies .= " \\\n\t$name";
346     }
347
348     foreach my $name (keys %{$self->{MAN3PODS}}) {
349         $dependencies .= " \\\n\t$name"
350     }
351
352     my $manify = <<END;
353 manifypods : pure_all $dependencies
354 END
355
356     my @man_cmds;
357     foreach my $section (qw(1 3)) {
358         my $pods = $self->{"MAN${section}PODS"};
359         push @man_cmds, $self->split_command(<<CMD, %$pods);
360         \$(NOECHO) \$(POD2MAN_EXE) --section=$section --perm_rw=\$(PERM_RW)
361 CMD
362     }
363
364     $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
365     $manify .= join '', map { "$_\n" } @man_cmds;
366
367     return $manify;
368 }
369
370
371 =item makemakerdflt_target
372
373   my $make_frag = $mm->makemakerdflt_target
374
375 Returns a make fragment with the makemakerdeflt_target specified.
376 This target is the first target in the Makefile, is the default target
377 and simply points off to 'all' just in case any make variant gets
378 confused or something gets snuck in before the real 'all' target.
379
380 =cut
381
382 sub makemakerdflt_target {
383     return <<'MAKE_FRAG';
384 makemakerdflt: all
385         $(NOECHO) $(NOOP)
386 MAKE_FRAG
387
388 }
389
390
391 =item special_targets
392
393   my $make_frag = $mm->special_targets
394
395 Returns a make fragment containing any targets which have special
396 meaning to make.  For example, .SUFFIXES and .PHONY.
397
398 =cut
399
400 sub special_targets {
401     my $make_frag = <<'MAKE_FRAG';
402 .SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
403
404 .PHONY: all config static dynamic test linkext manifest
405
406 MAKE_FRAG
407
408     $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
409 .NO_CONFIG_REC: Makefile
410
411 MAKE_FRAG
412
413     return $make_frag;
414 }
415
416 =item POD2MAN_EXE_macro
417
418   my $pod2man_exe_macro = $self->POD2MAN_EXE_macro
419
420 Returns a definition for the POD2MAN_EXE macro.  This is a program
421 which emulates the pod2man utility.  You can add more switches to the
422 command by simply appending them on the macro.
423
424 Typical usage:
425
426     $(POD2MAN_EXE) --section=3 --perm_rw=$(PERM_RW) podfile man_page
427
428 =cut
429
430 sub POD2MAN_EXE_macro {
431     my $self = shift;
432
433 # Need the trailing '--' so perl stops gobbling arguments and - happens
434 # to be an alternative end of line seperator on VMS so we quote it
435     return <<'END_OF_DEF';
436 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
437 END_OF_DEF
438 }
439
440
441 =item test_via_harness
442
443   my $command = $mm->test_via_harness($perl, $tests);
444
445 Returns a $command line which runs the given set of $tests with
446 Test::Harness and the given $perl.
447
448 Used on the t/*.t files.
449
450 =cut
451
452 sub test_via_harness {
453     my($self, $perl, $tests) = @_;
454
455     return qq{\t$perl "-MExtUtils::Command::MM" }.
456            qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
457 }
458
459 =item test_via_script
460
461   my $command = $mm->test_via_script($perl, $script);
462
463 Returns a $command line which just runs a single test without
464 Test::Harness.  No checks are done on the results, they're just
465 printed.
466
467 Used for test.pl, since they don't always follow Test::Harness
468 formatting.
469
470 =cut
471
472 sub test_via_script {
473     my($self, $perl, $script) = @_;
474     return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
475 }
476
477 =item libscan
478
479   my $wanted = $self->libscan($path);
480
481 Takes a path to a file or dir and returns an empty string if we don't
482 want to include this file in the library.  Otherwise it returns the
483 the $path unchanged.
484
485 Mainly used to exclude RCS, CVS, and SCCS directories from
486 installation.
487
488 =cut
489
490 sub libscan {
491     my($self,$path) = @_;
492     my($dirs,$file) = ($self->splitpath($path))[1,2];
493     return '' if grep /^RCS|CVS|SCCS|\.svn$/, 
494                      $self->splitdir($dirs), $file;
495
496     return $path;
497 }
498
499 =item tool_autosplit
500
501 Defines a simple perl call that runs autosplit. May be deprecated by
502 pm_to_blib soon.
503
504 =cut
505
506 sub tool_autosplit {
507     my($self, %attribs) = @_;
508
509     my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};' 
510                                   : '';
511
512     my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
513 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
514 PERL_CODE
515
516     return sprintf <<'MAKE_FRAG', $asplit;
517 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
518 AUTOSPLITFILE = %s
519
520 MAKE_FRAG
521
522 }
523
524
525 =item all_target
526
527 Generate the default target 'all'.
528
529 =cut
530
531 sub all_target {
532     my $self = shift;
533
534     return <<'MAKE_EXT';
535 all :: pure_all
536         $(NOECHO) $(NOOP)
537 MAKE_EXT
538
539 }
540
541
542 =item metafile_target
543
544     my $target = $mm->metafile_target;
545
546 Generate the metafile target.
547
548 Writes the file META.yml, YAML encoded meta-data about the module.  The
549 format follows Module::Build's as closely as possible.  Additionally, we
550 include:
551
552     version_from
553     installdirs
554
555 =cut
556
557 sub metafile_target {
558     my $self = shift;
559
560     return <<'MAKE_FRAG' if $self->{NO_META};
561 metafile:
562         $(NOECHO) $(NOOP)
563 MAKE_FRAG
564
565     my $prereq_pm = '';
566     while( my($mod, $ver) = each %{$self->{PREREQ_PM}} ) {
567         $prereq_pm .= sprintf "    %-30s %s\n", "$mod:", $ver;
568     }
569     
570     my $meta = <<YAML;
571 #XXXXXXX This is a prototype!!!  It will change in the future!!! XXXXX#
572 name:         $self->{DISTNAME}
573 version:      $self->{VERSION}
574 version_from: $self->{VERSION_FROM}
575 installdirs:  $self->{INSTALLDIRS}
576 requires:
577 $prereq_pm
578 distribution_type: module
579 generated_by: ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION
580 YAML
581
582     my @write_meta = $self->echo($meta, 'META.yml');
583     return sprintf <<'MAKE_FRAG', join "\n\t", @write_meta;
584 metafile :
585         %s
586 MAKE_FRAG
587
588 }
589
590
591 =item metafile_addtomanifest_target
592
593   my $target = $mm->metafile_addtomanifest_target
594
595 Adds the META.yml file to the MANIFEST.
596
597 =cut
598
599 sub metafile_addtomanifest_target {
600     my $self = shift;
601
602     return <<'MAKE_FRAG' if $self->{NO_META};
603 metafile_addtomanifest:
604         $(NOECHO) $(NOOP)
605 MAKE_FRAG
606
607     my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
608 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) } 
609     or print "Could not add META.yml to MANIFEST: $${'@'}\n"
610 CODE
611
612     return sprintf <<'MAKE_FRAG', $add_meta;
613 metafile_addtomanifest:
614         $(NOECHO) %s
615 MAKE_FRAG
616
617 }
618
619
620 =back
621
622 =head2 Abstract methods
623
624 Methods which cannot be made cross-platform and each subclass will
625 have to do their own implementation.
626
627 =over 4
628
629 =item oneliner
630
631   my $oneliner = $MM->oneliner($perl_code);
632   my $oneliner = $MM->oneliner($perl_code, \@switches);
633
634 This will generate a perl one-liner safe for the particular platform
635 you're on based on the given $perl_code and @switches (a -e is
636 assumed) suitable for using in a make target.  It will use the proper
637 shell quoting and escapes.
638
639 $(PERLRUN) will be used as perl.
640
641 Any newlines in $perl_code will be escaped.  Leading and trailing
642 newlines will be stripped.  Makes this idiom much easier:
643
644     my $code = $MM->oneliner(<<'CODE', [...switches...]);
645 some code here
646 another line here
647 CODE
648
649 Usage might be something like:
650
651     # an echo emulation
652     $oneliner = $MM->oneliner('print "Foo\n"');
653     $make = '$oneliner > somefile';
654
655 All dollar signs must be doubled in the $perl_code if you expect them
656 to be interpreted normally, otherwise it will be considered a make
657 macro.  Also remember to quote make macros else it might be used as a
658 bareword.  For example:
659
660     # Assign the value of the $(VERSION_FROM) make macro to $vf.
661     $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
662
663 Its currently very simple and may be expanded sometime in the figure
664 to include more flexible code and switches.
665
666
667 =item B<quote_literal>
668
669     my $safe_text = $MM->quote_literal($text);
670
671 This will quote $text so it is interpreted literally in the shell.
672
673 For example, on Unix this would escape any single-quotes in $text and
674 put single-quotes around the whole thing.
675
676
677 =item B<escape_newlines>
678
679     my $escaped_text = $MM->escape_newlines($text);
680
681 Shell escapes newlines in $text.
682
683
684 =item max_exec_len
685
686     my $max_exec_len = $MM->max_exec_len;
687
688 Calculates the maximum command size the OS can exec.  Effectively,
689 this is the max size of a shell command line.
690
691 =for _private
692 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
693
694 =item B<init_others>
695
696     $MM->init_others();
697
698 Initializes the macro definitions used by tools_other() and places them
699 in the $MM object.
700
701 If there is no description, its the same as the parameter to
702 WriteMakefile() documented in ExtUtils::MakeMaker.
703
704 Defines at least these macros.
705
706   Macro             Description
707
708   NOOP              Do nothing
709   NOECHO            Tell make not to display the command itself
710
711   MAKEFILE
712   FIRST_MAKEFILE
713   MAKEFILE_OLD
714   MAKE_APERL_FILE   File used by MAKE_APERL
715
716   SHELL             Program used to run
717                     shell commands
718
719   ECHO              Print text adding a newline on the end
720   RM_F              Remove a file 
721   RM_RF             Remove a directory          
722   TOUCH             Update a file's timestamp   
723   TEST_F            Test for a file's existence 
724   CP                Copy a file                 
725   MV                Move a file                 
726   CHMOD             Change permissions on a     
727                     file
728
729   UMASK_NULL        Nullify umask
730   DEV_NULL          Supress all command output
731
732 =item init_DIRFILESEP
733
734   $MM->init_DIRFILESEP;
735   my $dirfilesep = $MM->{DIRFILESEP};
736
737 Initializes the DIRFILESEP macro which is the seperator between the
738 directory and filename in a filepath.  ie. / on Unix, \ on Win32 and
739 nothing on VMS.
740
741 For example:
742
743     # instead of $(INST_ARCHAUTODIR)/extralibs.ld
744     $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
745
746 Something of a hack but it prevents a lot of code duplication between
747 MM_* variants.
748
749 Do not use this as a seperator between directories.  Some operating
750 systems use different seperators between subdirectories as between
751 directories and filenames (for example:  VOLUME:[dir1.dir2]file on VMS).
752
753 =item init_linker
754
755     $mm->init_linker;
756
757 Initialize macros which have to do with linking.
758
759 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
760 extensions.
761
762 PERL_ARCHIVE_AFTER: path to a library which should be put on the
763 linker command line I<after> the external libraries to be linked to
764 dynamic extensions.  This may be needed if the linker is one-pass, and
765 Perl includes some overrides for C RTL functions, such as malloc().
766
767 EXPORT_LIST: name of a file that is passed to linker to define symbols
768 to be exported.
769
770 Some OSes do not need these in which case leave it blank.
771
772
773 =item init_platform
774
775     $mm->init_platform
776
777 Initialize any macros which are for platform specific use only.
778
779 A typical one is the version number of your OS specific mocule.
780 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
781
782 =item platform_constants
783
784     my $make_frag = $mm->platform_constants
785
786 Returns a make fragment defining all the macros initialized in
787 init_platform() rather than put them in constants().
788
789 =cut
790
791 sub init_platform {
792     return '';
793 }
794
795 sub platform_constants {
796     return '';
797 }
798
799 =item os_flavor
800
801     my @os_flavor = $mm->os_flavor;
802
803 @os_flavor is the style of operating system this is, usually
804 corresponding to the MM_*.pm file we're using.  
805
806 The first element of @os_flavor is the major family (ie. Unix,
807 Windows, VMS, OS/2, MacOS, etc...) and the rest are sub families.
808
809 Some examples:
810
811     Cygwin98       ('Unix',  'Cygwin', 'Cygwin9x')
812     Windows NT     ('Win32', 'WinNT')
813     Win98          ('Win32', 'Win9x')
814     Linux          ('Unix',  'Linux')
815     MacOS Classic  ('MacOS', 'MacOS Classic')
816     MacOS X        ('Unix',  'Darwin', 'MacOS', 'MacOS X')
817     OS/2           ('OS/2')
818
819 This is used to write code for styles of operating system.  
820 See os_flavor_is() for use.
821
822
823 =back
824
825 =head1 AUTHOR
826
827 Michael G Schwern <schwern@pobox.com> and the denizens of
828 makemaker@perl.org with code from ExtUtils::MM_Unix and
829 ExtUtils::MM_Win32.
830
831
832 =cut
833
834 1;