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 $mm->os_flavor_is($this_flavor);
50 $mm->os_flavor_is(@one_of_these_flavors);
52 Checks to see if the current operating system is one of the given flavors.
54 This is useful for code like:
56 if( $mm->os_flavor_is('Unix') ) {
67 my %flavors = map { ($_ => 1) } $self->os_flavor;
68 return (grep { $flavors{$_} } @_) ? 1 : 0;
73 =head2 File::Spec wrappers
75 ExtUtils::MM_Any is a subclass of File::Spec. The methods noted here
82 File::Spec <= 0.83 has a bug where the file part of catfile is not
83 canonicalized. This override fixes that bug.
89 return $self->canonpath($self->SUPER::catfile(@_));
94 =head1 Thought To Be Cross-Platform Methods
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.
102 =item B<split_command>
104 my @cmds = $MM->split_command($cmd, @args);
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.
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.
115 $cmd should include any switches and repeated initial arguments.
117 If no @args are given, no @cmds will be returned.
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:
123 $self->split_command($cmd, %pod2man);
129 my($self, $cmd, @args) = @_;
132 return(@cmds) unless @args;
134 # If the command was given as a here-doc, there's probably a trailing
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);
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";
149 if( !length $arg_str ) {
150 $arg_str .= $next_arg_str
152 elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
153 unshift @args, @next_args;
157 $arg_str .= $next_arg_str;
162 push @cmds, $self->escape_newlines("$cmd\n$arg_str");
170 my($self, $cmd) = @_;
172 $cmd =~ s{\$\((\w+)\)}{
173 defined $self->{$1} ? $self->{$1} : "\$($1)"
181 my @commands = $MM->echo($text);
182 my @commands = $MM->echo($text, $file);
183 my @commands = $MM->echo($text, $file, $appending);
185 Generates a set of @commands which print the $text to a $file.
187 If $file is not given, output goes to STDOUT.
189 If $appending is true the $file will be appended to rather than
195 my($self, $text, $file, $appending) = @_;
198 my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_) }
201 my $redirect = $appending ? '>>' : '>';
202 $cmds[0] .= " $redirect $file";
203 $_ .= " >> $file" foreach @cmds[1..$#cmds];
214 Initialize macros representing versions of MakeMaker and other tools
216 MAKEMAKER: path to the MakeMaker module.
218 MM_VERSION: ExtUtils::MakeMaker Version
220 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
223 VERSION: version of your module
225 VERSION_MACRO: which macro represents the version (usually 'VERSION')
227 VERSION_SYM: like version but safe for use as an RCS revision number
229 DEFINE_VERSION: -D line to set the module version when compiling
231 XS_VERSION: version in your .xs file. Defaults to $(VERSION)
233 XS_VERSION_MACRO: which macro represents the XS version.
235 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
244 $self->{MAKEMAKER} = $ExtUtils::MakeMaker::Filename;
245 $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
246 $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
247 $self->{VERSION_FROM} ||= '';
249 if ($self->{VERSION_FROM}){
250 $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
251 if( $self->{VERSION} eq 'undef' ) {
253 Carp::carp("WARNING: Setting VERSION via file ".
254 "'$self->{VERSION_FROM}' failed\n");
259 if (defined $self->{VERSION}) {
260 $self->{VERSION} =~ s/^\s+//;
261 $self->{VERSION} =~ s/\s+$//;
264 $self->{VERSION} = '';
268 $self->{VERSION_MACRO} = 'VERSION';
269 ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
270 $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
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};
279 $self->{XS_VERSION_MACRO} = 'XS_VERSION';
280 $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
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:
297 return join " \\\n\t", @_;
302 Defines targets and routines to translate the pods into manpages and
303 put them into the INST_* directories.
310 my $POD2MAN_EXE_macro = $self->POD2MAN_EXE_macro();
311 my $manifypods_target = $self->manifypods_target();
313 return <<END_OF_TARGET;
315 # --- Begin manifypods section:
320 # --- End manifypods section --- #
327 =item manifypods_target
329 my $manifypods_target = $self->manifypods_target;
331 Generates the manifypods target. This target generates man pages from
332 all POD files in MAN1PODS and MAN3PODS.
336 sub manifypods_target {
341 my $dependencies = '';
343 # populate manXpods & dependencies:
344 foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
345 $dependencies .= " \\\n\t$name";
348 foreach my $name (keys %{$self->{MAN3PODS}}) {
349 $dependencies .= " \\\n\t$name"
353 manifypods : pure_all $dependencies
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)
364 $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
365 $manify .= join '', map { "$_\n" } @man_cmds;
371 =item makemakerdflt_target
373 my $make_frag = $mm->makemakerdflt_target
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.
382 sub makemakerdflt_target {
383 return <<'MAKE_FRAG';
391 =item special_targets
393 my $make_frag = $mm->special_targets
395 Returns a make fragment containing any targets which have special
396 meaning to make. For example, .SUFFIXES and .PHONY.
400 sub special_targets {
401 my $make_frag = <<'MAKE_FRAG';
402 .SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
404 .PHONY: all config static dynamic test linkext manifest
408 $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
409 .NO_CONFIG_REC: Makefile
416 =item POD2MAN_EXE_macro
418 my $pod2man_exe_macro = $self->POD2MAN_EXE_macro
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.
426 $(POD2MAN_EXE) --section=3 --perm_rw=$(PERM_RW) podfile man_page
430 sub POD2MAN_EXE_macro {
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 "--"
441 =item test_via_harness
443 my $command = $mm->test_via_harness($perl, $tests);
445 Returns a $command line which runs the given set of $tests with
446 Test::Harness and the given $perl.
448 Used on the t/*.t files.
452 sub test_via_harness {
453 my($self, $perl, $tests) = @_;
455 return qq{\t$perl "-MExtUtils::Command::MM" }.
456 qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
459 =item test_via_script
461 my $command = $mm->test_via_script($perl, $script);
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
467 Used for test.pl, since they don't always follow Test::Harness
472 sub test_via_script {
473 my($self, $perl, $script) = @_;
474 return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
479 my $wanted = $self->libscan($path);
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
485 Mainly used to exclude RCS, CVS, and SCCS directories from
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;
501 Defines a simple perl call that runs autosplit. May be deprecated by
507 my($self, %attribs) = @_;
509 my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
512 my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
513 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
516 return sprintf <<'MAKE_FRAG', $asplit;
517 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
527 Generate the default target 'all'.
542 =item metafile_target
544 my $target = $mm->metafile_target;
546 Generate the metafile target.
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
557 sub metafile_target {
560 return <<'MAKE_FRAG' if $self->{NO_META};
566 while( my($mod, $ver) = each %{$self->{PREREQ_PM}} ) {
567 $prereq_pm .= sprintf " %-30s %s\n", "$mod:", $ver;
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}
578 distribution_type: module
579 generated_by: ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION
582 my @write_meta = $self->echo($meta, 'META.yml');
583 return sprintf <<'MAKE_FRAG', join "\n\t", @write_meta;
591 =item metafile_addtomanifest_target
593 my $target = $mm->metafile_addtomanifest_target
595 Adds the META.yml file to the MANIFEST.
599 sub metafile_addtomanifest_target {
602 return <<'MAKE_FRAG' if $self->{NO_META};
603 metafile_addtomanifest:
607 my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
608 maniadd({q{META.yml} => q{Module meta-data in YAML}});
611 return sprintf <<'MAKE_FRAG', $add_meta;
612 metafile_addtomanifest:
621 =head2 Abstract methods
623 Methods which cannot be made cross-platform and each subclass will
624 have to do their own implementation.
630 my $oneliner = $MM->oneliner($perl_code);
631 my $oneliner = $MM->oneliner($perl_code, \@switches);
633 This will generate a perl one-liner safe for the particular platform
634 you're on based on the given $perl_code and @switches (a -e is
635 assumed) suitable for using in a make target. It will use the proper
636 shell quoting and escapes.
638 $(PERLRUN) will be used as perl.
640 Any newlines in $perl_code will be escaped. Leading and trailing
641 newlines will be stripped. Makes this idiom much easier:
643 my $code = $MM->oneliner(<<'CODE', [...switches...]);
648 Usage might be something like:
651 $oneliner = $MM->oneliner('print "Foo\n"');
652 $make = '$oneliner > somefile';
654 All dollar signs must be doubled in the $perl_code if you expect them
655 to be interpreted normally, otherwise it will be considered a make
656 macro. Also remember to quote make macros else it might be used as a
657 bareword. For example:
659 # Assign the value of the $(VERSION_FROM) make macro to $vf.
660 $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
662 Its currently very simple and may be expanded sometime in the figure
663 to include more flexible code and switches.
666 =item B<quote_literal>
668 my $safe_text = $MM->quote_literal($text);
670 This will quote $text so it is interpreted literally in the shell.
672 For example, on Unix this would escape any single-quotes in $text and
673 put single-quotes around the whole thing.
676 =item B<escape_newlines>
678 my $escaped_text = $MM->escape_newlines($text);
680 Shell escapes newlines in $text.
685 my $max_exec_len = $MM->max_exec_len;
687 Calculates the maximum command size the OS can exec. Effectively,
688 this is the max size of a shell command line.
691 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
697 Initializes the macro definitions used by tools_other() and places them
700 If there is no description, its the same as the parameter to
701 WriteMakefile() documented in ExtUtils::MakeMaker.
703 Defines at least these macros.
708 NOECHO Tell make not to display the command itself
713 MAKE_APERL_FILE File used by MAKE_APERL
715 SHELL Program used to run
718 ECHO Print text adding a newline on the end
720 RM_RF Remove a directory
721 TOUCH Update a file's timestamp
722 TEST_F Test for a file's existence
725 CHMOD Change permissions on a
728 UMASK_NULL Nullify umask
729 DEV_NULL Supress all command output
731 =item init_DIRFILESEP
733 $MM->init_DIRFILESEP;
734 my $dirfilesep = $MM->{DIRFILESEP};
736 Initializes the DIRFILESEP macro which is the seperator between the
737 directory and filename in a filepath. ie. / on Unix, \ on Win32 and
742 # instead of $(INST_ARCHAUTODIR)/extralibs.ld
743 $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
745 Something of a hack but it prevents a lot of code duplication between
748 Do not use this as a seperator between directories. Some operating
749 systems use different seperators between subdirectories as between
750 directories and filenames (for example: VOLUME:[dir1.dir2]file on VMS).
756 Initialize macros which have to do with linking.
758 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
761 PERL_ARCHIVE_AFTER: path to a library which should be put on the
762 linker command line I<after> the external libraries to be linked to
763 dynamic extensions. This may be needed if the linker is one-pass, and
764 Perl includes some overrides for C RTL functions, such as malloc().
766 EXPORT_LIST: name of a file that is passed to linker to define symbols
769 Some OSes do not need these in which case leave it blank.
776 Initialize any macros which are for platform specific use only.
778 A typical one is the version number of your OS specific mocule.
779 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
781 =item platform_constants
783 my $make_frag = $mm->platform_constants
785 Returns a make fragment defining all the macros initialized in
786 init_platform() rather than put them in constants().
794 sub platform_constants {
800 my @os_flavor = $mm->os_flavor;
802 @os_flavor is the style of operating system this is, usually
803 corresponding to the MM_*.pm file we're using.
805 The first element of @os_flavor is the major family (ie. Unix,
806 Windows, VMS, OS/2, MacOS, etc...) and the rest are sub families.
810 Cygwin98 ('Unix', 'Cygwin', 'Cygwin9x')
811 Windows NT ('Win32', 'WinNT')
812 Win98 ('Win32', 'Win9x')
813 Linux ('Unix', 'Linux')
814 MacOS Classic ('MacOS', 'MacOS Classic')
815 MacOS X ('Unix', 'Darwin', 'MacOS', 'MacOS X')
818 This is used to write code for styles of operating system.
819 See os_flavor_is() for use.
826 Michael G Schwern <schwern@pobox.com> and the denizens of
827 makemaker@perl.org with code from ExtUtils::MM_Unix and