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;
90 =item blibdirs_target (o)
92 my $make_frag = $mm->blibdirs_target;
94 Creates the blibdirs target which creates all the directories we use in
102 my @dirs = map { uc "\$(INST_$_)" } qw(libdir
107 my @mkpath = $self->split_command('$(NOECHO) $(MKPATH)', @dirs);
108 my @chmod = $self->split_command('$(NOECHO) $(CHMOD) 755', @dirs);
110 my $make = "\nblibdirs :: Makefile.PL \n";
111 $make .= join "", map { "\t$_\n" } @mkpath, @chmod;
112 $make .= "\t\$(NOECHO) \$(TOUCH) blibdirs\n\n";
120 =head2 File::Spec wrappers
122 ExtUtils::MM_Any is a subclass of File::Spec. The methods noted here
129 File::Spec <= 0.83 has a bug where the file part of catfile is not
130 canonicalized. This override fixes that bug.
136 return $self->canonpath($self->SUPER::catfile(@_));
141 =head1 Thought To Be Cross-Platform Methods
143 These are methods which are thought to be cross-platform by virtue of
144 having been written in a way to avoid incompatibilities. They may
145 require partial overrides.
149 =item B<split_command>
151 my @cmds = $MM->split_command($cmd, @args);
153 Most OS have a maximum command length they can execute at once. Large
154 modules can easily generate commands well past that limit. Its
155 necessary to split long commands up into a series of shorter commands.
157 split_command() will return a series of @cmds each processing part of
158 the args. Collectively they will process all the arguments. Each
159 individual line in @cmds will not be longer than the
160 $self->max_exec_len being careful to take into account macro expansion.
162 $cmd should include any switches and repeated initial arguments.
164 If no @args are given, no @cmds will be returned.
166 Pairs of arguments will always be preserved in a single command, this
167 is a heuristic for things like pm_to_blib and pod2man which work on
168 pairs of arguments. This makes things like this safe:
170 $self->split_command($cmd, %pod2man);
176 my($self, $cmd, @args) = @_;
179 return(@cmds) unless @args;
181 # If the command was given as a here-doc, there's probably a trailing
185 # set aside 20% for macro expansion.
186 my $len_left = int($self->max_exec_len * 0.80);
187 $len_left -= length $self->_expand_macros($cmd);
192 while( @next_args = splice(@args, 0, 2) ) {
193 # Two at a time to preserve pairs.
194 my $next_arg_str = "\t ". join ' ', @next_args, "\n";
196 if( !length $arg_str ) {
197 $arg_str .= $next_arg_str
199 elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
200 unshift @args, @next_args;
204 $arg_str .= $next_arg_str;
209 push @cmds, $self->escape_newlines("$cmd \n$arg_str");
217 my($self, $cmd) = @_;
219 $cmd =~ s{\$\((\w+)\)}{
220 defined $self->{$1} ? $self->{$1} : "\$($1)"
228 my @commands = $MM->echo($text);
229 my @commands = $MM->echo($text, $file);
230 my @commands = $MM->echo($text, $file, $appending);
232 Generates a set of @commands which print the $text to a $file.
234 If $file is not given, output goes to STDOUT.
236 If $appending is true the $file will be appended to rather than
242 my($self, $text, $file, $appending) = @_;
245 my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_) }
248 my $redirect = $appending ? '>>' : '>';
249 $cmds[0] .= " $redirect $file";
250 $_ .= " >> $file" foreach @cmds[1..$#cmds];
261 Initialize macros representing versions of MakeMaker and other tools
263 MAKEMAKER: path to the MakeMaker module.
265 MM_VERSION: ExtUtils::MakeMaker Version
267 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
270 VERSION: version of your module
272 VERSION_MACRO: which macro represents the version (usually 'VERSION')
274 VERSION_SYM: like version but safe for use as an RCS revision number
276 DEFINE_VERSION: -D line to set the module version when compiling
278 XS_VERSION: version in your .xs file. Defaults to $(VERSION)
280 XS_VERSION_MACRO: which macro represents the XS version.
282 XS_DEFINE_VERSION: -D line to set the xs version when compiling.
291 $self->{MAKEMAKER} = $ExtUtils::MakeMaker::Filename;
292 $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
293 $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
294 $self->{VERSION_FROM} ||= '';
296 if ($self->{VERSION_FROM}){
297 $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
298 if( $self->{VERSION} eq 'undef' ) {
300 Carp::carp("WARNING: Setting VERSION via file ".
301 "'$self->{VERSION_FROM}' failed\n");
306 if (defined $self->{VERSION}) {
307 $self->{VERSION} =~ s/^\s+//;
308 $self->{VERSION} =~ s/\s+$//;
311 $self->{VERSION} = '';
315 $self->{VERSION_MACRO} = 'VERSION';
316 ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
317 $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
320 # Graham Barr and Paul Marquess had some ideas how to ensure
321 # version compatibility between the *.pm file and the
322 # corresponding *.xs file. The bottomline was, that we need an
323 # XS_VERSION macro that defaults to VERSION:
324 $self->{XS_VERSION} ||= $self->{VERSION};
326 $self->{XS_VERSION_MACRO} = 'XS_VERSION';
327 $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
333 Takes an array of items and turns them into a well-formatted list of
334 arguments. In most cases this is simply something like:
344 return join " \\\n\t", @_;
349 Defines targets and routines to translate the pods into manpages and
350 put them into the INST_* directories.
357 my $POD2MAN_macro = $self->POD2MAN_macro();
358 my $manifypods_target = $self->manifypods_target();
360 return <<END_OF_TARGET;
371 =item manifypods_target
373 my $manifypods_target = $self->manifypods_target;
375 Generates the manifypods target. This target generates man pages from
376 all POD files in MAN1PODS and MAN3PODS.
380 sub manifypods_target {
385 my $dependencies = '';
387 # populate manXpods & dependencies:
388 foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
389 $dependencies .= " \\\n\t$name";
392 foreach my $name (keys %{$self->{MAN3PODS}}) {
393 $dependencies .= " \\\n\t$name"
397 manifypods : pure_all $dependencies
401 foreach my $section (qw(1 3)) {
402 my $pods = $self->{"MAN${section}PODS"};
403 push @man_cmds, $self->split_command(<<CMD, %$pods);
404 \$(NOECHO) \$(POD2MAN) --section=$section --perm_rw=\$(PERM_RW)
408 $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
409 $manify .= join '', map { "$_\n" } @man_cmds;
415 =item makemakerdflt_target
417 my $make_frag = $mm->makemakerdflt_target
419 Returns a make fragment with the makemakerdeflt_target specified.
420 This target is the first target in the Makefile, is the default target
421 and simply points off to 'all' just in case any make variant gets
422 confused or something gets snuck in before the real 'all' target.
426 sub makemakerdflt_target {
427 return <<'MAKE_FRAG';
435 =item special_targets
437 my $make_frag = $mm->special_targets
439 Returns a make fragment containing any targets which have special
440 meaning to make. For example, .SUFFIXES and .PHONY.
444 sub special_targets {
445 my $make_frag = <<'MAKE_FRAG';
446 .SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
448 .PHONY: all config static dynamic test linkext manifest
452 $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
453 .NO_CONFIG_REC: Makefile
462 my $pod2man_macro = $self->POD2MAN_macro
464 Returns a definition for the POD2MAN macro. This is a program
465 which emulates the pod2man utility. You can add more switches to the
466 command by simply appending them on the macro.
470 $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
477 # Need the trailing '--' so perl stops gobbling arguments and - happens
478 # to be an alternative end of line seperator on VMS so we quote it
479 return <<'END_OF_DEF';
480 POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
481 POD2MAN = $(POD2MAN_EXE)
486 =item test_via_harness
488 my $command = $mm->test_via_harness($perl, $tests);
490 Returns a $command line which runs the given set of $tests with
491 Test::Harness and the given $perl.
493 Used on the t/*.t files.
497 sub test_via_harness {
498 my($self, $perl, $tests) = @_;
500 return qq{\t$perl "-MExtUtils::Command::MM" }.
501 qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
504 =item test_via_script
506 my $command = $mm->test_via_script($perl, $script);
508 Returns a $command line which just runs a single test without
509 Test::Harness. No checks are done on the results, they're just
512 Used for test.pl, since they don't always follow Test::Harness
517 sub test_via_script {
518 my($self, $perl, $script) = @_;
519 return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
524 my $wanted = $self->libscan($path);
526 Takes a path to a file or dir and returns an empty string if we don't
527 want to include this file in the library. Otherwise it returns the
530 Mainly used to exclude RCS, CVS, and SCCS directories from
536 my($self,$path) = @_;
537 my($dirs,$file) = ($self->splitpath($path))[1,2];
538 return '' if grep /^(?:RCS|CVS|SCCS|\.svn)$/,
539 $self->splitdir($dirs), $file;
546 Defines a simple perl call that runs autosplit. May be deprecated by
552 my($self, %attribs) = @_;
554 my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
557 my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
558 use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
561 return sprintf <<'MAKE_FRAG', $asplit;
562 # Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
572 Generate the default target 'all'.
587 =item metafile_target
589 my $target = $mm->metafile_target;
591 Generate the metafile target.
593 Writes the file META.yml, YAML encoded meta-data about the module. The
594 format follows Module::Build's as closely as possible. Additionally, we
602 sub metafile_target {
605 return <<'MAKE_FRAG' if $self->{NO_META};
611 foreach my $mod ( sort { lc $a cmp lc $b } keys %{$self->{PREREQ_PM}} ) {
612 my $ver = $self->{PREREQ_PM}{$mod};
613 $prereq_pm .= sprintf " %-30s %s\n", "$mod:", $ver;
617 # http://module-build.sourceforge.net/META-spec.html
618 #XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
619 name: $self->{DISTNAME}
620 version: $self->{VERSION}
621 version_from: $self->{VERSION_FROM}
622 installdirs: $self->{INSTALLDIRS}
625 distribution_type: module
626 generated_by: ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION
629 my @write_meta = $self->echo($meta, 'META_new.yml');
630 my $move = $self->oneliner(<<'CODE', ['-MExtUtils::Command', '-MFile::Compare']);
631 compare(@ARGV) != 0 ? (mv or warn "Cannot move @ARGV: $$!\n") : unlink(shift);
634 return sprintf <<'MAKE_FRAG', join("\n\t", @write_meta), $move;
636 $(NOECHO) $(ECHO) Generating META.yml
638 -$(NOECHO) %s META_new.yml META.yml
644 =item signature_target
646 my $target = $mm->signature_target;
648 Generate the signature target.
650 Writes the file SIGNATURE with "cpansign -s".
654 sub signature_target {
657 return <<'MAKE_FRAG' if !$self->{SIGN};
662 return <<'MAKE_FRAG';
663 signature : signature_addtomanifest
670 =item metafile_addtomanifest_target
672 my $target = $mm->metafile_addtomanifest_target
674 Adds the META.yml file to the MANIFEST.
678 sub metafile_addtomanifest_target {
681 return <<'MAKE_FRAG' if $self->{NO_META};
682 metafile_addtomanifest:
686 my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
687 eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) }
688 or print "Could not add META.yml to MANIFEST: $${'@'}\n"
691 return sprintf <<'MAKE_FRAG', $add_meta;
692 metafile_addtomanifest:
693 $(NOECHO) $(ECHO) Adding META.yml to MANIFEST
700 =item signature_addtomanifest_target
702 my $target = $mm->signature_addtomanifest_target
704 Adds the META.yml file to the MANIFEST.
708 sub signature_addtomanifest_target {
711 return <<'MAKE_FRAG' if !$self->{SIGN};
712 signature_addtomanifest :
716 my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
717 eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) }
718 or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
721 return sprintf <<'MAKE_FRAG', $add_sign;
722 signature_addtomanifest :
723 $(NOECHO) $(ECHO) Adding SIGNATURE to MANIFEST
732 =head2 Abstract methods
734 Methods which cannot be made cross-platform and each subclass will
735 have to do their own implementation.
741 my $oneliner = $MM->oneliner($perl_code);
742 my $oneliner = $MM->oneliner($perl_code, \@switches);
744 This will generate a perl one-liner safe for the particular platform
745 you're on based on the given $perl_code and @switches (a -e is
746 assumed) suitable for using in a make target. It will use the proper
747 shell quoting and escapes.
749 $(PERLRUN) will be used as perl.
751 Any newlines in $perl_code will be escaped. Leading and trailing
752 newlines will be stripped. Makes this idiom much easier:
754 my $code = $MM->oneliner(<<'CODE', [...switches...]);
759 Usage might be something like:
762 $oneliner = $MM->oneliner('print "Foo\n"');
763 $make = '$oneliner > somefile';
765 All dollar signs must be doubled in the $perl_code if you expect them
766 to be interpreted normally, otherwise it will be considered a make
767 macro. Also remember to quote make macros else it might be used as a
768 bareword. For example:
770 # Assign the value of the $(VERSION_FROM) make macro to $vf.
771 $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
773 Its currently very simple and may be expanded sometime in the figure
774 to include more flexible code and switches.
777 =item B<quote_literal>
779 my $safe_text = $MM->quote_literal($text);
781 This will quote $text so it is interpreted literally in the shell.
783 For example, on Unix this would escape any single-quotes in $text and
784 put single-quotes around the whole thing.
787 =item B<escape_newlines>
789 my $escaped_text = $MM->escape_newlines($text);
791 Shell escapes newlines in $text.
796 my $max_exec_len = $MM->max_exec_len;
798 Calculates the maximum command size the OS can exec. Effectively,
799 this is the max size of a shell command line.
802 $self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
808 Initializes the macro definitions used by tools_other() and places them
811 If there is no description, its the same as the parameter to
812 WriteMakefile() documented in ExtUtils::MakeMaker.
814 Defines at least these macros.
819 NOECHO Tell make not to display the command itself
824 MAKE_APERL_FILE File used by MAKE_APERL
826 SHELL Program used to run
829 ECHO Print text adding a newline on the end
831 RM_RF Remove a directory
832 TOUCH Update a file's timestamp
833 TEST_F Test for a file's existence
836 CHMOD Change permissions on a
839 UMASK_NULL Nullify umask
840 DEV_NULL Supress all command output
842 =item init_DIRFILESEP
844 $MM->init_DIRFILESEP;
845 my $dirfilesep = $MM->{DIRFILESEP};
847 Initializes the DIRFILESEP macro which is the seperator between the
848 directory and filename in a filepath. ie. / on Unix, \ on Win32 and
853 # instead of $(INST_ARCHAUTODIR)/extralibs.ld
854 $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
856 Something of a hack but it prevents a lot of code duplication between
859 Do not use this as a seperator between directories. Some operating
860 systems use different seperators between subdirectories as between
861 directories and filenames (for example: VOLUME:[dir1.dir2]file on VMS).
867 Initialize macros which have to do with linking.
869 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
872 PERL_ARCHIVE_AFTER: path to a library which should be put on the
873 linker command line I<after> the external libraries to be linked to
874 dynamic extensions. This may be needed if the linker is one-pass, and
875 Perl includes some overrides for C RTL functions, such as malloc().
877 EXPORT_LIST: name of a file that is passed to linker to define symbols
880 Some OSes do not need these in which case leave it blank.
887 Initialize any macros which are for platform specific use only.
889 A typical one is the version number of your OS specific mocule.
890 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
892 =item platform_constants
894 my $make_frag = $mm->platform_constants
896 Returns a make fragment defining all the macros initialized in
897 init_platform() rather than put them in constants().
905 sub platform_constants {
911 my @os_flavor = $mm->os_flavor;
913 @os_flavor is the style of operating system this is, usually
914 corresponding to the MM_*.pm file we're using.
916 The first element of @os_flavor is the major family (ie. Unix,
917 Windows, VMS, OS/2, MacOS, etc...) and the rest are sub families.
921 Cygwin98 ('Unix', 'Cygwin', 'Cygwin9x')
922 Windows NT ('Win32', 'WinNT')
923 Win98 ('Win32', 'Win9x')
924 Linux ('Unix', 'Linux')
925 MacOS Classic ('MacOS', 'MacOS Classic')
926 MacOS X ('Unix', 'Darwin', 'MacOS', 'MacOS X')
929 This is used to write code for styles of operating system.
930 See os_flavor_is() for use.
937 Michael G Schwern <schwern@pobox.com> and the denizens of
938 makemaker@perl.org with code from ExtUtils::MM_Unix and