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