1 package ExtUtils::MM_Any;
4 use vars qw($VERSION @ISA);
14 ExtUtils::MM_Any - Platform-agnostic MM methods
18 FOR INTERNAL USE ONLY!
20 package ExtUtils::MM_SomeOS;
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);
29 B<FOR INTERNAL USE ONLY!>
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.
35 Subclass off of ExtUtils::MM_Any I<and> ExtUtils::MM_Unix. This is a
38 B<THIS MAY BE TEMPORARY!>
40 =head1 Inherently Cross-Platform Methods
42 These are methods which are by their nature cross-platform and should
43 always be cross-platform.
49 my @installvars = $mm->installvars;
51 A list of all the INSTALL* variables without the INSTALL prefix. Useful
52 for iteration or building related variable sets.
57 return qw(PRIVLIB SITELIB VENDORLIB
58 ARCHLIB SITEARCH VENDORARCH
61 MAN1DIR SITEMAN1DIR VENDORMAN1DIR
62 MAN3DIR SITEMAN3DIR VENDORMAN3DIR
68 $mm->os_flavor_is($this_flavor);
69 $mm->os_flavor_is(@one_of_these_flavors);
71 Checks to see if the current operating system is one of the given flavors.
73 This is useful for code like:
75 if( $mm->os_flavor_is('Unix') ) {
86 my %flavors = map { ($_ => 1) } $self->os_flavor;
87 return (grep { $flavors{$_} } @_) ? 1 : 0;
92 =head2 File::Spec wrappers
94 ExtUtils::MM_Any is a subclass of File::Spec. The methods noted here
101 File::Spec <= 0.83 has a bug where the file part of catfile is not
102 canonicalized. This override fixes that bug.
108 return $self->canonpath($self->SUPER::catfile(@_));
113 =head1 Thought To Be Cross-Platform Methods
115 These are methods which are thought to be cross-platform by virtue of
116 having been written in a way to avoid incompatibilities. They may
117 require partial overrides.
121 =item B<split_command>
123 my @cmds = $MM->split_command($cmd, @args);
125 Most OS have a maximum command length they can execute at once. Large
126 modules can easily generate commands well past that limit. Its
127 necessary to split long commands up into a series of shorter commands.
129 split_command() will return a series of @cmds each processing part of
130 the args. Collectively they will process all the arguments. Each
131 individual line in @cmds will not be longer than the
132 $self->max_exec_len being careful to take into account macro expansion.
134 $cmd should include any switches and repeated initial arguments.
136 If no @args are given, no @cmds will be returned.
138 Pairs of arguments will always be preserved in a single command, this
139 is a heuristic for things like pm_to_blib and pod2man which work on
140 pairs of arguments. This makes things like this safe:
142 $self->split_command($cmd, %pod2man);
148 my($self, $cmd, @args) = @_;
151 return(@cmds) unless @args;
153 # If the command was given as a here-doc, there's probably a trailing
157 # set aside 20% for macro expansion.
158 my $len_left = int($self->max_exec_len * 0.80);
159 $len_left -= length $self->_expand_macros($cmd);
164 while( @next_args = splice(@args, 0, 2) ) {
165 # Two at a time to preserve pairs.
166 my $next_arg_str = "\t ". join ' ', @next_args, "\n";
168 if( !length $arg_str ) {
169 $arg_str .= $next_arg_str
171 elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
172 unshift @args, @next_args;
176 $arg_str .= $next_arg_str;
181 push @cmds, $self->escape_newlines("$cmd\n$arg_str");
189 my($self, $cmd) = @_;
191 $cmd =~ s{\$\((\w+)\)}{
192 defined $self->{$1} ? $self->{$1} : "\$($1)"
200 my @commands = $MM->echo($text);
201 my @commands = $MM->echo($text, $file);
202 my @commands = $MM->echo($text, $file, $appending);
204 Generates a set of @commands which print the $text to a $file.
206 If $file is not given, output goes to STDOUT.
208 If $appending is true the $file will be appended to rather than
214 my($self, $text, $file, $appending) = @_;
217 my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_) }
220 my $redirect = $appending ? '>>' : '>';
221 $cmds[0] .= " $redirect $file";
222 $_ .= " >> $file" foreach @cmds[1..$#cmds];
233 Initialize macros representing versions of MakeMaker and other tools
235 MAKEMAKER: path to the MakeMaker module.
237 MM_VERSION: ExtUtils::MakeMaker Version
239 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
242 VERSION: version of your module
244 VERSION_MACRO: which macro represents the version (usually 'VERSION')
246 VERSION_SYM: like version but safe for use as an RCS revision number
248 DEFINE_VERSION: -D line to set the module version when compiling
250 XS_VERSION: version in your .xs file. Defaults to $(VERSION)
252 XS_VERSION_MACRO: which macro represents the XS version.
254 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
263 $self->{MAKEMAKER} = $ExtUtils::MakeMaker::Filename;
264 $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
265 $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
266 $self->{VERSION_FROM} ||= '';
268 if ($self->{VERSION_FROM}){
269 $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
270 if( $self->{VERSION} eq 'undef' ) {
272 Carp::carp("WARNING: Setting VERSION via file ".
273 "'$self->{VERSION_FROM}' failed\n");
278 if (defined $self->{VERSION}) {
279 $self->{VERSION} =~ s/^\s+//;
280 $self->{VERSION} =~ s/\s+$//;
283 $self->{VERSION} = '';
287 $self->{VERSION_MACRO} = 'VERSION';
288 ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
289 $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
292 # Graham Barr and Paul Marquess had some ideas how to ensure
293 # version compatibility between the *.pm file and the
294 # corresponding *.xs file. The bottomline was, that we need an
295 # XS_VERSION macro that defaults to VERSION:
296 $self->{XS_VERSION} ||= $self->{VERSION};
298 $self->{XS_VERSION_MACRO} = 'XS_VERSION';
299 $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
305 Takes an array of items and turns them into a well-formatted list of
306 arguments. In most cases this is simply something like:
316 return join " \\\n\t", @_;
321 Defines targets and routines to translate the pods into manpages and
322 put them into the INST_* directories.
329 my $POD2MAN_macro = $self->POD2MAN_macro();
330 my $manifypods_target = $self->manifypods_target();
332 return <<END_OF_TARGET;
343 =item manifypods_target
345 my $manifypods_target = $self->manifypods_target;
347 Generates the manifypods target. This target generates man pages from
348 all POD files in MAN1PODS and MAN3PODS.
352 sub manifypods_target {
357 my $dependencies = '';
359 # populate manXpods & dependencies:
360 foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
361 $dependencies .= " \\\n\t$name";
364 foreach my $name (keys %{$self->{MAN3PODS}}) {
365 $dependencies .= " \\\n\t$name"
369 manifypods : pure_all $dependencies
373 foreach my $section (qw(1 3)) {
374 my $pods = $self->{"MAN${section}PODS"};
375 push @man_cmds, $self->split_command(<<CMD, %$pods);
376 \$(NOECHO) \$(POD2MAN) --section=$section --perm_rw=\$(PERM_RW)
380 $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
381 $manify .= join '', map { "$_\n" } @man_cmds;
387 =item makemakerdflt_target
389 my $make_frag = $mm->makemakerdflt_target
391 Returns a make fragment with the makemakerdeflt_target specified.
392 This target is the first target in the Makefile, is the default target
393 and simply points off to 'all' just in case any make variant gets
394 confused or something gets snuck in before the real 'all' target.
398 sub makemakerdflt_target {
399 return <<'MAKE_FRAG';
407 =item special_targets
409 my $make_frag = $mm->special_targets
411 Returns a make fragment containing any targets which have special
412 meaning to make. For example, .SUFFIXES and .PHONY.
416 sub special_targets {
417 my $make_frag = <<'MAKE_FRAG';
418 .SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
420 .PHONY: all config static dynamic test linkext manifest
424 $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
425 .NO_CONFIG_REC: Makefile
434 my $pod2man_macro = $self->POD2MAN_macro
436 Returns a definition for the POD2MAN macro. This is a program
437 which emulates the pod2man utility. You can add more switches to the
438 command by simply appending them on the macro.
442 $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
449 # Need the trailing '--' so perl stops gobbling arguments and - happens
450 # to be an alternative end of line seperator on VMS so we quote it
451 return <<'END_OF_DEF';
452 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
453 POD2MAN = $(POD2MAN_EXE)
458 =item test_via_harness
460 my $command = $mm->test_via_harness($perl, $tests);
462 Returns a $command line which runs the given set of $tests with
463 Test::Harness and the given $perl.
465 Used on the t/*.t files.
469 sub test_via_harness {
470 my($self, $perl, $tests) = @_;
472 return qq{\t$perl "-MExtUtils::Command::MM" }.
473 qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
476 =item test_via_script
478 my $command = $mm->test_via_script($perl, $script);
480 Returns a $command line which just runs a single test without
481 Test::Harness. No checks are done on the results, they're just
484 Used for test.pl, since they don't always follow Test::Harness
489 sub test_via_script {
490 my($self, $perl, $script) = @_;
491 return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
496 my $wanted = $self->libscan($path);
498 Takes a path to a file or dir and returns an empty string if we don't
499 want to include this file in the library. Otherwise it returns the
502 Mainly used to exclude RCS, CVS, and SCCS directories from
508 my($self,$path) = @_;
509 my($dirs,$file) = ($self->splitpath($path))[1,2];
510 return '' if grep /^(?:RCS|CVS|SCCS|\.svn)$/,
511 $self->splitdir($dirs), $file;
518 Defines a simple perl call that runs autosplit. May be deprecated by
524 my($self, %attribs) = @_;
526 my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
529 my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
530 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
533 return sprintf <<'MAKE_FRAG', $asplit;
534 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
544 Generate the default target 'all'.
559 =item metafile_target
561 my $target = $mm->metafile_target;
563 Generate the metafile target.
565 Writes the file META.yml, YAML encoded meta-data about the module. The
566 format follows Module::Build's as closely as possible. Additionally, we
574 sub metafile_target {
577 return <<'MAKE_FRAG' if $self->{NO_META};
583 foreach my $mod ( sort { lc $a cmp lc $b } keys %{$self->{PREREQ_PM}} ) {
584 my $ver = $self->{PREREQ_PM}{$mod};
585 $prereq_pm .= sprintf " %-30s %s\n", "$mod:", $ver;
589 # http://module-build.sourceforge.net/META-spec.html
590 #XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
591 name: $self->{DISTNAME}
592 version: $self->{VERSION}
593 version_from: $self->{VERSION_FROM}
594 installdirs: $self->{INSTALLDIRS}
597 distribution_type: module
598 generated_by: ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION
601 my @write_meta = $self->echo($meta, 'META.yml');
602 return sprintf <<'MAKE_FRAG', join "\n\t", @write_meta;
610 =item signature_target
612 my $target = $mm->signature_target;
614 Generate the signature target.
616 Writes the file SIGNATURE with "cpansign -s".
620 sub signature_target {
623 return <<'MAKE_FRAG' if !$self->{SIGN};
628 return <<'MAKE_FRAG';
636 =item metafile_addtomanifest_target
638 my $target = $mm->metafile_addtomanifest_target
640 Adds the META.yml file to the MANIFEST.
644 sub metafile_addtomanifest_target {
647 return <<'MAKE_FRAG' if $self->{NO_META};
648 metafile_addtomanifest:
652 my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
653 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) }
654 or print "Could not add META.yml to MANIFEST: $${'@'}\n"
657 return sprintf <<'MAKE_FRAG', $add_meta;
658 metafile_addtomanifest:
665 =item signature_addtomanifest_target
667 my $target = $mm->signature_addtomanifest_target
669 Adds the META.yml file to the MANIFEST.
673 sub signature_addtomanifest_target {
676 return <<'MAKE_FRAG' if !$self->{SIGN};
677 signature_addtomanifest:
681 my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
682 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) }
683 or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
686 return sprintf <<'MAKE_FRAG', $add_sign;
687 signature_addtomanifest:
696 =head2 Abstract methods
698 Methods which cannot be made cross-platform and each subclass will
699 have to do their own implementation.
705 my $oneliner = $MM->oneliner($perl_code);
706 my $oneliner = $MM->oneliner($perl_code, \@switches);
708 This will generate a perl one-liner safe for the particular platform
709 you're on based on the given $perl_code and @switches (a -e is
710 assumed) suitable for using in a make target. It will use the proper
711 shell quoting and escapes.
713 $(PERLRUN) will be used as perl.
715 Any newlines in $perl_code will be escaped. Leading and trailing
716 newlines will be stripped. Makes this idiom much easier:
718 my $code = $MM->oneliner(<<'CODE', [...switches...]);
723 Usage might be something like:
726 $oneliner = $MM->oneliner('print "Foo\n"');
727 $make = '$oneliner > somefile';
729 All dollar signs must be doubled in the $perl_code if you expect them
730 to be interpreted normally, otherwise it will be considered a make
731 macro. Also remember to quote make macros else it might be used as a
732 bareword. For example:
734 # Assign the value of the $(VERSION_FROM) make macro to $vf.
735 $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
737 Its currently very simple and may be expanded sometime in the figure
738 to include more flexible code and switches.
741 =item B<quote_literal>
743 my $safe_text = $MM->quote_literal($text);
745 This will quote $text so it is interpreted literally in the shell.
747 For example, on Unix this would escape any single-quotes in $text and
748 put single-quotes around the whole thing.
751 =item B<escape_newlines>
753 my $escaped_text = $MM->escape_newlines($text);
755 Shell escapes newlines in $text.
760 my $max_exec_len = $MM->max_exec_len;
762 Calculates the maximum command size the OS can exec. Effectively,
763 this is the max size of a shell command line.
766 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
772 Initializes the macro definitions used by tools_other() and places them
775 If there is no description, its the same as the parameter to
776 WriteMakefile() documented in ExtUtils::MakeMaker.
778 Defines at least these macros.
783 NOECHO Tell make not to display the command itself
788 MAKE_APERL_FILE File used by MAKE_APERL
790 SHELL Program used to run
793 ECHO Print text adding a newline on the end
795 RM_RF Remove a directory
796 TOUCH Update a file's timestamp
797 TEST_F Test for a file's existence
800 CHMOD Change permissions on a
803 UMASK_NULL Nullify umask
804 DEV_NULL Supress all command output
806 =item init_DIRFILESEP
808 $MM->init_DIRFILESEP;
809 my $dirfilesep = $MM->{DIRFILESEP};
811 Initializes the DIRFILESEP macro which is the seperator between the
812 directory and filename in a filepath. ie. / on Unix, \ on Win32 and
817 # instead of $(INST_ARCHAUTODIR)/extralibs.ld
818 $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
820 Something of a hack but it prevents a lot of code duplication between
823 Do not use this as a seperator between directories. Some operating
824 systems use different seperators between subdirectories as between
825 directories and filenames (for example: VOLUME:[dir1.dir2]file on VMS).
831 Initialize macros which have to do with linking.
833 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
836 PERL_ARCHIVE_AFTER: path to a library which should be put on the
837 linker command line I<after> the external libraries to be linked to
838 dynamic extensions. This may be needed if the linker is one-pass, and
839 Perl includes some overrides for C RTL functions, such as malloc().
841 EXPORT_LIST: name of a file that is passed to linker to define symbols
844 Some OSes do not need these in which case leave it blank.
851 Initialize any macros which are for platform specific use only.
853 A typical one is the version number of your OS specific mocule.
854 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
856 =item platform_constants
858 my $make_frag = $mm->platform_constants
860 Returns a make fragment defining all the macros initialized in
861 init_platform() rather than put them in constants().
869 sub platform_constants {
875 my @os_flavor = $mm->os_flavor;
877 @os_flavor is the style of operating system this is, usually
878 corresponding to the MM_*.pm file we're using.
880 The first element of @os_flavor is the major family (ie. Unix,
881 Windows, VMS, OS/2, MacOS, etc...) and the rest are sub families.
885 Cygwin98 ('Unix', 'Cygwin', 'Cygwin9x')
886 Windows NT ('Win32', 'WinNT')
887 Win98 ('Win32', 'Win9x')
888 Linux ('Unix', 'Linux')
889 MacOS Classic ('MacOS', 'MacOS Classic')
890 MacOS X ('Unix', 'Darwin', 'MacOS', 'MacOS X')
893 This is used to write code for styles of operating system.
894 See os_flavor_is() for use.
901 Michael G Schwern <schwern@pobox.com> and the denizens of
902 makemaker@perl.org with code from ExtUtils::MM_Unix and