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 metafile_addtomanifest_target
612 my $target = $mm->metafile_addtomanifest_target
614 Adds the META.yml file to the MANIFEST.
618 sub metafile_addtomanifest_target {
621 return <<'MAKE_FRAG' if $self->{NO_META};
622 metafile_addtomanifest:
626 my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
627 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) }
628 or print "Could not add META.yml to MANIFEST: $${'@'}\n"
631 return sprintf <<'MAKE_FRAG', $add_meta;
632 metafile_addtomanifest:
641 =head2 Abstract methods
643 Methods which cannot be made cross-platform and each subclass will
644 have to do their own implementation.
650 my $oneliner = $MM->oneliner($perl_code);
651 my $oneliner = $MM->oneliner($perl_code, \@switches);
653 This will generate a perl one-liner safe for the particular platform
654 you're on based on the given $perl_code and @switches (a -e is
655 assumed) suitable for using in a make target. It will use the proper
656 shell quoting and escapes.
658 $(PERLRUN) will be used as perl.
660 Any newlines in $perl_code will be escaped. Leading and trailing
661 newlines will be stripped. Makes this idiom much easier:
663 my $code = $MM->oneliner(<<'CODE', [...switches...]);
668 Usage might be something like:
671 $oneliner = $MM->oneliner('print "Foo\n"');
672 $make = '$oneliner > somefile';
674 All dollar signs must be doubled in the $perl_code if you expect them
675 to be interpreted normally, otherwise it will be considered a make
676 macro. Also remember to quote make macros else it might be used as a
677 bareword. For example:
679 # Assign the value of the $(VERSION_FROM) make macro to $vf.
680 $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
682 Its currently very simple and may be expanded sometime in the figure
683 to include more flexible code and switches.
686 =item B<quote_literal>
688 my $safe_text = $MM->quote_literal($text);
690 This will quote $text so it is interpreted literally in the shell.
692 For example, on Unix this would escape any single-quotes in $text and
693 put single-quotes around the whole thing.
696 =item B<escape_newlines>
698 my $escaped_text = $MM->escape_newlines($text);
700 Shell escapes newlines in $text.
705 my $max_exec_len = $MM->max_exec_len;
707 Calculates the maximum command size the OS can exec. Effectively,
708 this is the max size of a shell command line.
711 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
717 Initializes the macro definitions used by tools_other() and places them
720 If there is no description, its the same as the parameter to
721 WriteMakefile() documented in ExtUtils::MakeMaker.
723 Defines at least these macros.
728 NOECHO Tell make not to display the command itself
733 MAKE_APERL_FILE File used by MAKE_APERL
735 SHELL Program used to run
738 ECHO Print text adding a newline on the end
740 RM_RF Remove a directory
741 TOUCH Update a file's timestamp
742 TEST_F Test for a file's existence
745 CHMOD Change permissions on a
748 UMASK_NULL Nullify umask
749 DEV_NULL Supress all command output
751 =item init_DIRFILESEP
753 $MM->init_DIRFILESEP;
754 my $dirfilesep = $MM->{DIRFILESEP};
756 Initializes the DIRFILESEP macro which is the seperator between the
757 directory and filename in a filepath. ie. / on Unix, \ on Win32 and
762 # instead of $(INST_ARCHAUTODIR)/extralibs.ld
763 $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
765 Something of a hack but it prevents a lot of code duplication between
768 Do not use this as a seperator between directories. Some operating
769 systems use different seperators between subdirectories as between
770 directories and filenames (for example: VOLUME:[dir1.dir2]file on VMS).
776 Initialize macros which have to do with linking.
778 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
781 PERL_ARCHIVE_AFTER: path to a library which should be put on the
782 linker command line I<after> the external libraries to be linked to
783 dynamic extensions. This may be needed if the linker is one-pass, and
784 Perl includes some overrides for C RTL functions, such as malloc().
786 EXPORT_LIST: name of a file that is passed to linker to define symbols
789 Some OSes do not need these in which case leave it blank.
796 Initialize any macros which are for platform specific use only.
798 A typical one is the version number of your OS specific mocule.
799 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
801 =item platform_constants
803 my $make_frag = $mm->platform_constants
805 Returns a make fragment defining all the macros initialized in
806 init_platform() rather than put them in constants().
814 sub platform_constants {
820 my @os_flavor = $mm->os_flavor;
822 @os_flavor is the style of operating system this is, usually
823 corresponding to the MM_*.pm file we're using.
825 The first element of @os_flavor is the major family (ie. Unix,
826 Windows, VMS, OS/2, MacOS, etc...) and the rest are sub families.
830 Cygwin98 ('Unix', 'Cygwin', 'Cygwin9x')
831 Windows NT ('Win32', 'WinNT')
832 Win98 ('Win32', 'Win9x')
833 Linux ('Unix', 'Linux')
834 MacOS Classic ('MacOS', 'MacOS Classic')
835 MacOS X ('Unix', 'Darwin', 'MacOS', 'MacOS X')
838 This is used to write code for styles of operating system.
839 See os_flavor_is() for use.
846 Michael G Schwern <schwern@pobox.com> and the denizens of
847 makemaker@perl.org with code from ExtUtils::MM_Unix and