This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Don't try to export symbols that don't exist
[perl5.git] / lib / ExtUtils / MM_Any.pm
CommitLineData
f6d6199c
MS
1package ExtUtils::MM_Any;
2
3use strict;
4use vars qw($VERSION @ISA);
5dca256e 5$VERSION = '0.10';
479d2113 6@ISA = qw(File::Spec);
f6d6199c
MS
7
8use Config;
9use File::Spec;
10
11
12=head1 NAME
13
30361541 14ExtUtils::MM_Any - Platform-agnostic MM methods
f6d6199c
MS
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
29B<FOR INTERNAL USE ONLY!>
30
31ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
32modules. It contains methods which are either inherently
33cross-platform or are written in a cross-platform manner.
34
35Subclass off of ExtUtils::MM_Any I<and> ExtUtils::MM_Unix. This is a
36temporary solution.
37
38B<THIS MAY BE TEMPORARY!>
39
40=head1 Inherently Cross-Platform Methods
41
42These are methods which are by their nature cross-platform and should
43always be cross-platform.
44
dedf98bc
MS
45=over 4
46
5e719f03
MS
47=item installvars
48
49 my @installvars = $mm->installvars;
50
51A list of all the INSTALL* variables without the INSTALL prefix. Useful
52for iteration or building related variable sets.
53
54=cut
55
56sub installvars {
57 return qw(PRIVLIB SITELIB VENDORLIB
58 ARCHLIB SITEARCH VENDORARCH
59 BIN SITEBIN VENDORBIN
60 SCRIPT
61 MAN1DIR SITEMAN1DIR VENDORMAN1DIR
62 MAN3DIR SITEMAN3DIR VENDORMAN3DIR
63 );
64}
65
dedf98bc
MS
66=item os_flavor_is
67
68 $mm->os_flavor_is($this_flavor);
69 $mm->os_flavor_is(@one_of_these_flavors);
70
71Checks to see if the current operating system is one of the given flavors.
72
73This is useful for code like:
74
75 if( $mm->os_flavor_is('Unix') ) {
76 $out = `foo 2>&1`;
77 }
78 else {
79 $out = `foo`;
80 }
81
82=cut
83
84sub os_flavor_is {
85 my $self = shift;
86 my %flavors = map { ($_ => 1) } $self->os_flavor;
87 return (grep { $flavors{$_} } @_) ? 1 : 0;
88}
89
5dca256e
RGS
90
91=item dir_target B<DEPRECATED>
92
93 my $make_frag = $mm->dir_target(@directories);
94
95I<This function is deprecated> its use is no longer necessary and is
96I<only provided for backwards compatibility>. It is now a no-op.
97blibdirs_target provides a much simpler mechanism and pm_to_blib() can
98create its own directories anyway.
99
100=cut
101
102sub dir_target {}
103
104
a7d1454b
RGS
105=item blibdirs_target (o)
106
107 my $make_frag = $mm->blibdirs_target;
108
5dca256e 109Creates the blibdirs.ts target which creates all the directories we use in
a7d1454b
RGS
110blib/.
111
112=cut
113
114sub blibdirs_target {
115 my $self = shift;
116
5dca256e
RGS
117 my @dirs = map { uc "\$(INST_$_)" } qw(libdir archlib
118 autodir archautodir
119 bin script
120 man1dir man3dir
121 );
a7d1454b
RGS
122 my @mkpath = $self->split_command('$(NOECHO) $(MKPATH)', @dirs);
123 my @chmod = $self->split_command('$(NOECHO) $(CHMOD) 755', @dirs);
124
5dca256e 125 my $make = "\nblibdirs.ts :\n";
a7d1454b 126 $make .= join "", map { "\t$_\n" } @mkpath, @chmod;
5dca256e
RGS
127 $make .= <<'MAKE';
128 $(NOECHO) $(TOUCH) $@
129
130MAKE
a7d1454b
RGS
131
132 return $make;
133}
134
135
dedf98bc
MS
136=back
137
479d2113 138=head2 File::Spec wrappers
f6d6199c 139
479d2113
MS
140ExtUtils::MM_Any is a subclass of File::Spec. The methods noted here
141override File::Spec.
f6d6199c 142
479d2113
MS
143=over 4
144
145=item catfile
146
147File::Spec <= 0.83 has a bug where the file part of catfile is not
148canonicalized. This override fixes that bug.
149
150=cut
151
152sub catfile {
153 my $self = shift;
154 return $self->canonpath($self->SUPER::catfile(@_));
155}
156
157=back
158
159=head1 Thought To Be Cross-Platform Methods
160
161These are methods which are thought to be cross-platform by virtue of
162having been written in a way to avoid incompatibilities. They may
163require partial overrides.
f6d6199c
MS
164
165=over 4
166
479d2113
MS
167=item B<split_command>
168
169 my @cmds = $MM->split_command($cmd, @args);
170
171Most OS have a maximum command length they can execute at once. Large
172modules can easily generate commands well past that limit. Its
173necessary to split long commands up into a series of shorter commands.
174
175split_command() will return a series of @cmds each processing part of
176the args. Collectively they will process all the arguments. Each
177individual line in @cmds will not be longer than the
178$self->max_exec_len being careful to take into account macro expansion.
179
180$cmd should include any switches and repeated initial arguments.
181
182If no @args are given, no @cmds will be returned.
183
184Pairs of arguments will always be preserved in a single command, this
185is a heuristic for things like pm_to_blib and pod2man which work on
186pairs of arguments. This makes things like this safe:
187
188 $self->split_command($cmd, %pod2man);
189
f6d6199c
MS
190
191=cut
192
479d2113
MS
193sub split_command {
194 my($self, $cmd, @args) = @_;
195
196 my @cmds = ();
197 return(@cmds) unless @args;
198
199 # If the command was given as a here-doc, there's probably a trailing
200 # newline.
201 chomp $cmd;
202
203 # set aside 20% for macro expansion.
204 my $len_left = int($self->max_exec_len * 0.80);
205 $len_left -= length $self->_expand_macros($cmd);
206
207 do {
208 my $arg_str = '';
209 my @next_args;
210 while( @next_args = splice(@args, 0, 2) ) {
211 # Two at a time to preserve pairs.
212 my $next_arg_str = "\t ". join ' ', @next_args, "\n";
213
214 if( !length $arg_str ) {
215 $arg_str .= $next_arg_str
216 }
217 elsif( length($arg_str) + length($next_arg_str) > $len_left ) {
218 unshift @args, @next_args;
219 last;
220 }
221 else {
222 $arg_str .= $next_arg_str;
223 }
224 }
225 chop $arg_str;
226
a7d1454b 227 push @cmds, $self->escape_newlines("$cmd \n$arg_str");
479d2113
MS
228 } while @args;
229
230 return @cmds;
f6d6199c
MS
231}
232
479d2113
MS
233
234sub _expand_macros {
235 my($self, $cmd) = @_;
236
237 $cmd =~ s{\$\((\w+)\)}{
238 defined $self->{$1} ? $self->{$1} : "\$($1)"
239 }e;
240 return $cmd;
241}
242
243
244=item B<echo>
245
246 my @commands = $MM->echo($text);
247 my @commands = $MM->echo($text, $file);
248 my @commands = $MM->echo($text, $file, $appending);
249
250Generates a set of @commands which print the $text to a $file.
251
252If $file is not given, output goes to STDOUT.
253
254If $appending is true the $file will be appended to rather than
255overwritten.
f6d6199c
MS
256
257=cut
258
479d2113
MS
259sub echo {
260 my($self, $text, $file, $appending) = @_;
261 $appending ||= 0;
262
263 my @cmds = map { '$(NOECHO) $(ECHO) '.$self->quote_literal($_) }
264 split /\n/, $text;
265 if( $file ) {
266 my $redirect = $appending ? '>>' : '>';
267 $cmds[0] .= " $redirect $file";
268 $_ .= " >> $file" foreach @cmds[1..$#cmds];
269 }
270
271 return @cmds;
f6d6199c
MS
272}
273
479d2113
MS
274
275=item init_VERSION
276
277 $mm->init_VERSION
278
279Initialize macros representing versions of MakeMaker and other tools
280
281MAKEMAKER: path to the MakeMaker module.
282
283MM_VERSION: ExtUtils::MakeMaker Version
284
285MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
286 compat)
287
288VERSION: version of your module
289
290VERSION_MACRO: which macro represents the version (usually 'VERSION')
291
292VERSION_SYM: like version but safe for use as an RCS revision number
293
294DEFINE_VERSION: -D line to set the module version when compiling
295
296XS_VERSION: version in your .xs file. Defaults to $(VERSION)
297
298XS_VERSION_MACRO: which macro represents the XS version.
299
300XS_DEFINE_VERSION: -D line to set the xs version when compiling.
301
302Called by init_main.
f6d6199c
MS
303
304=cut
305
479d2113
MS
306sub init_VERSION {
307 my($self) = shift;
308
dedf98bc 309 $self->{MAKEMAKER} = $ExtUtils::MakeMaker::Filename;
479d2113
MS
310 $self->{MM_VERSION} = $ExtUtils::MakeMaker::VERSION;
311 $self->{MM_REVISION}= $ExtUtils::MakeMaker::Revision;
312 $self->{VERSION_FROM} ||= '';
313
314 if ($self->{VERSION_FROM}){
315 $self->{VERSION} = $self->parse_version($self->{VERSION_FROM});
316 if( $self->{VERSION} eq 'undef' ) {
317 require Carp;
318 Carp::carp("WARNING: Setting VERSION via file ".
319 "'$self->{VERSION_FROM}' failed\n");
320 }
321 }
322
323 # strip blanks
324 if (defined $self->{VERSION}) {
325 $self->{VERSION} =~ s/^\s+//;
326 $self->{VERSION} =~ s/\s+$//;
327 }
328 else {
329 $self->{VERSION} = '';
330 }
331
332
333 $self->{VERSION_MACRO} = 'VERSION';
334 ($self->{VERSION_SYM} = $self->{VERSION}) =~ s/\W/_/g;
335 $self->{DEFINE_VERSION} = '-D$(VERSION_MACRO)=\"$(VERSION)\"';
336
337
338 # Graham Barr and Paul Marquess had some ideas how to ensure
339 # version compatibility between the *.pm file and the
340 # corresponding *.xs file. The bottomline was, that we need an
341 # XS_VERSION macro that defaults to VERSION:
342 $self->{XS_VERSION} ||= $self->{VERSION};
343
344 $self->{XS_VERSION_MACRO} = 'XS_VERSION';
345 $self->{XS_DEFINE_VERSION} = '-D$(XS_VERSION_MACRO)=\"$(XS_VERSION)\"';
346
f6d6199c
MS
347}
348
479d2113
MS
349=item wraplist
350
351Takes an array of items and turns them into a well-formatted list of
352arguments. In most cases this is simply something like:
353
354 FOO \
355 BAR \
356 BAZ
f6d6199c
MS
357
358=cut
359
479d2113
MS
360sub wraplist {
361 my $self = shift;
362 return join " \\\n\t", @_;
f6d6199c
MS
363}
364
479d2113
MS
365=item manifypods
366
367Defines targets and routines to translate the pods into manpages and
368put them into the INST_* directories.
f6d6199c
MS
369
370=cut
371
479d2113
MS
372sub manifypods {
373 my $self = shift;
374
64964e6d 375 my $POD2MAN_macro = $self->POD2MAN_macro();
479d2113
MS
376 my $manifypods_target = $self->manifypods_target();
377
378 return <<END_OF_TARGET;
379
64964e6d 380$POD2MAN_macro
479d2113
MS
381
382$manifypods_target
383
479d2113
MS
384END_OF_TARGET
385
f6d6199c
MS
386}
387
479d2113
MS
388
389=item manifypods_target
390
391 my $manifypods_target = $self->manifypods_target;
392
393Generates the manifypods target. This target generates man pages from
394all POD files in MAN1PODS and MAN3PODS.
f6d6199c
MS
395
396=cut
397
479d2113
MS
398sub manifypods_target {
399 my($self) = shift;
400
401 my $man1pods = '';
402 my $man3pods = '';
403 my $dependencies = '';
404
405 # populate manXpods & dependencies:
406 foreach my $name (keys %{$self->{MAN1PODS}}, keys %{$self->{MAN3PODS}}) {
407 $dependencies .= " \\\n\t$name";
408 }
409
410 foreach my $name (keys %{$self->{MAN3PODS}}) {
411 $dependencies .= " \\\n\t$name"
412 }
413
414 my $manify = <<END;
415manifypods : pure_all $dependencies
416END
417
418 my @man_cmds;
419 foreach my $section (qw(1 3)) {
420 my $pods = $self->{"MAN${section}PODS"};
421 push @man_cmds, $self->split_command(<<CMD, %$pods);
64964e6d 422 \$(NOECHO) \$(POD2MAN) --section=$section --perm_rw=\$(PERM_RW)
479d2113
MS
423CMD
424 }
425
dedf98bc 426 $manify .= "\t\$(NOECHO) \$(NOOP)\n" unless @man_cmds;
479d2113
MS
427 $manify .= join '', map { "$_\n" } @man_cmds;
428
429 return $manify;
f6d6199c
MS
430}
431
479d2113
MS
432
433=item makemakerdflt_target
434
435 my $make_frag = $mm->makemakerdflt_target
436
437Returns a make fragment with the makemakerdeflt_target specified.
438This target is the first target in the Makefile, is the default target
439and simply points off to 'all' just in case any make variant gets
440confused or something gets snuck in before the real 'all' target.
f6d6199c
MS
441
442=cut
443
479d2113
MS
444sub makemakerdflt_target {
445 return <<'MAKE_FRAG';
446makemakerdflt: all
447 $(NOECHO) $(NOOP)
448MAKE_FRAG
449
f6d6199c
MS
450}
451
479d2113
MS
452
453=item special_targets
454
455 my $make_frag = $mm->special_targets
456
457Returns a make fragment containing any targets which have special
458meaning to make. For example, .SUFFIXES and .PHONY.
f6d6199c
MS
459
460=cut
461
479d2113
MS
462sub special_targets {
463 my $make_frag = <<'MAKE_FRAG';
464.SUFFIXES: .xs .c .C .cpp .i .s .cxx .cc $(OBJ_EXT)
465
466.PHONY: all config static dynamic test linkext manifest
467
468MAKE_FRAG
469
470 $make_frag .= <<'MAKE_FRAG' if $ENV{CLEARCASE_ROOT};
471.NO_CONFIG_REC: Makefile
472
473MAKE_FRAG
474
475 return $make_frag;
f6d6199c
MS
476}
477
64964e6d 478=item POD2MAN_macro
f6d6199c 479
64964e6d 480 my $pod2man_macro = $self->POD2MAN_macro
f6d6199c 481
64964e6d 482Returns a definition for the POD2MAN macro. This is a program
479d2113
MS
483which emulates the pod2man utility. You can add more switches to the
484command by simply appending them on the macro.
485
486Typical usage:
487
64964e6d 488 $(POD2MAN) --section=3 --perm_rw=$(PERM_RW) podfile1 man_page1 ...
479d2113
MS
489
490=cut
491
64964e6d 492sub POD2MAN_macro {
479d2113
MS
493 my $self = shift;
494
495# Need the trailing '--' so perl stops gobbling arguments and - happens
496# to be an alternative end of line seperator on VMS so we quote it
497 return <<'END_OF_DEF';
498POD2MAN_EXE = $(PERLRUN) "-MExtUtils::Command::MM" -e pod2man "--"
64964e6d 499POD2MAN = $(POD2MAN_EXE)
479d2113
MS
500END_OF_DEF
501}
f6d6199c 502
f6d6199c
MS
503
504=item test_via_harness
505
506 my $command = $mm->test_via_harness($perl, $tests);
507
508Returns a $command line which runs the given set of $tests with
509Test::Harness and the given $perl.
510
511Used on the t/*.t files.
512
513=cut
514
515sub test_via_harness {
516 my($self, $perl, $tests) = @_;
517
e0678a30
MS
518 return qq{\t$perl "-MExtUtils::Command::MM" }.
519 qq{"-e" "test_harness(\$(TEST_VERBOSE), '\$(INST_LIB)', '\$(INST_ARCHLIB)')" $tests\n};
f6d6199c
MS
520}
521
522=item test_via_script
523
524 my $command = $mm->test_via_script($perl, $script);
525
526Returns a $command line which just runs a single test without
527Test::Harness. No checks are done on the results, they're just
528printed.
529
530Used for test.pl, since they don't always follow Test::Harness
531formatting.
532
533=cut
534
535sub test_via_script {
536 my($self, $perl, $script) = @_;
e0678a30 537 return qq{\t$perl "-I\$(INST_LIB)" "-I\$(INST_ARCHLIB)" $script\n};
f6d6199c
MS
538}
539
479d2113
MS
540=item libscan
541
542 my $wanted = $self->libscan($path);
543
544Takes a path to a file or dir and returns an empty string if we don't
545want to include this file in the library. Otherwise it returns the
546the $path unchanged.
547
548Mainly used to exclude RCS, CVS, and SCCS directories from
549installation.
550
551=cut
552
553sub libscan {
554 my($self,$path) = @_;
555 my($dirs,$file) = ($self->splitpath($path))[1,2];
ad2f23df 556 return '' if grep /^(?:RCS|CVS|SCCS|\.svn)$/,
479d2113
MS
557 $self->splitdir($dirs), $file;
558
559 return $path;
560}
561
562=item tool_autosplit
563
564Defines a simple perl call that runs autosplit. May be deprecated by
565pm_to_blib soon.
566
567=cut
568
569sub tool_autosplit {
570 my($self, %attribs) = @_;
571
572 my $maxlen = $attribs{MAXLEN} ? '$$AutoSplit::Maxlen=$attribs{MAXLEN};'
573 : '';
574
575 my $asplit = $self->oneliner(sprintf <<'PERL_CODE', $maxlen);
576use AutoSplit; %s autosplit($$ARGV[0], $$ARGV[1], 0, 1, 1)
577PERL_CODE
578
579 return sprintf <<'MAKE_FRAG', $asplit;
580# Usage: $(AUTOSPLITFILE) FileToSplit AutoDirToSplitInto
581AUTOSPLITFILE = %s
582
583MAKE_FRAG
584
585}
586
587
588=item all_target
589
590Generate the default target 'all'.
591
592=cut
593
594sub all_target {
595 my $self = shift;
596
597 return <<'MAKE_EXT';
598all :: pure_all
599 $(NOECHO) $(NOOP)
600MAKE_EXT
601
602}
603
604
605=item metafile_target
606
607 my $target = $mm->metafile_target;
608
609Generate the metafile target.
610
611Writes the file META.yml, YAML encoded meta-data about the module. The
612format follows Module::Build's as closely as possible. Additionally, we
613include:
614
615 version_from
616 installdirs
617
618=cut
619
620sub metafile_target {
621 my $self = shift;
622
431b0fc4
MS
623 return <<'MAKE_FRAG' if $self->{NO_META};
624metafile:
625 $(NOECHO) $(NOOP)
626MAKE_FRAG
627
479d2113 628 my $prereq_pm = '';
0fdc96ff
JH
629 foreach my $mod ( sort { lc $a cmp lc $b } keys %{$self->{PREREQ_PM}} ) {
630 my $ver = $self->{PREREQ_PM}{$mod};
479d2113
MS
631 $prereq_pm .= sprintf " %-30s %s\n", "$mod:", $ver;
632 }
a7d1454b 633
479d2113 634 my $meta = <<YAML;
64964e6d 635# http://module-build.sourceforge.net/META-spec.html
479d2113
MS
636#XXXXXXX This is a prototype!!! It will change in the future!!! XXXXX#
637name: $self->{DISTNAME}
638version: $self->{VERSION}
639version_from: $self->{VERSION_FROM}
640installdirs: $self->{INSTALLDIRS}
641requires:
642$prereq_pm
643distribution_type: module
644generated_by: ExtUtils::MakeMaker version $ExtUtils::MakeMaker::VERSION
645YAML
646
a7d1454b
RGS
647 my @write_meta = $self->echo($meta, 'META_new.yml');
648 my $move = $self->oneliner(<<'CODE', ['-MExtUtils::Command', '-MFile::Compare']);
dd0810f9 649compare(@ARGV) != 0 ? (mv or warn "Cannot move @ARGV: $$!\n") : unlink(shift);
a7d1454b
RGS
650CODE
651
652 return sprintf <<'MAKE_FRAG', join("\n\t", @write_meta), $move;
479d2113 653metafile :
a7d1454b 654 $(NOECHO) $(ECHO) Generating META.yml
479d2113 655 %s
a7d1454b 656 -$(NOECHO) %s META_new.yml META.yml
479d2113
MS
657MAKE_FRAG
658
659}
660
661
bb68fe9e
AT
662=item signature_target
663
664 my $target = $mm->signature_target;
665
666Generate the signature target.
667
668Writes the file SIGNATURE with "cpansign -s".
669
670=cut
671
672sub signature_target {
673 my $self = shift;
674
675 return <<'MAKE_FRAG' if !$self->{SIGN};
a7d1454b 676signature :
bb68fe9e
AT
677 $(NOECHO) $(NOOP)
678MAKE_FRAG
679
680 return <<'MAKE_FRAG';
a7d1454b 681signature : signature_addtomanifest
bb68fe9e
AT
682 cpansign -s
683MAKE_FRAG
684
685}
686
687
479d2113
MS
688=item metafile_addtomanifest_target
689
690 my $target = $mm->metafile_addtomanifest_target
691
692Adds the META.yml file to the MANIFEST.
693
694=cut
695
696sub metafile_addtomanifest_target {
697 my $self = shift;
698
431b0fc4
MS
699 return <<'MAKE_FRAG' if $self->{NO_META};
700metafile_addtomanifest:
701 $(NOECHO) $(NOOP)
702MAKE_FRAG
703
479d2113 704 my $add_meta = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
1df8d179 705eval { maniadd({q{META.yml} => q{Module meta-data (added by MakeMaker)}}) }
c2990482 706 or print "Could not add META.yml to MANIFEST: $${'@'}\n"
479d2113
MS
707CODE
708
709 return sprintf <<'MAKE_FRAG', $add_meta;
710metafile_addtomanifest:
a7d1454b 711 $(NOECHO) $(ECHO) Adding META.yml to MANIFEST
479d2113
MS
712 $(NOECHO) %s
713MAKE_FRAG
714
715}
716
717
bb68fe9e
AT
718=item signature_addtomanifest_target
719
720 my $target = $mm->signature_addtomanifest_target
721
722Adds the META.yml file to the MANIFEST.
723
724=cut
725
726sub signature_addtomanifest_target {
727 my $self = shift;
728
729 return <<'MAKE_FRAG' if !$self->{SIGN};
a7d1454b 730signature_addtomanifest :
bb68fe9e
AT
731 $(NOECHO) $(NOOP)
732MAKE_FRAG
733
734 my $add_sign = $self->oneliner(<<'CODE', ['-MExtUtils::Manifest=maniadd']);
735eval { maniadd({q{SIGNATURE} => q{Public-key signature (added by MakeMaker)}}) }
736 or print "Could not add SIGNATURE to MANIFEST: $${'@'}\n"
737CODE
738
739 return sprintf <<'MAKE_FRAG', $add_sign;
a7d1454b
RGS
740signature_addtomanifest :
741 $(NOECHO) $(ECHO) Adding SIGNATURE to MANIFEST
bb68fe9e
AT
742 $(NOECHO) %s
743MAKE_FRAG
744
745}
746
747
479d2113
MS
748=back
749
750=head2 Abstract methods
751
752Methods which cannot be made cross-platform and each subclass will
753have to do their own implementation.
754
755=over 4
756
757=item oneliner
758
759 my $oneliner = $MM->oneliner($perl_code);
760 my $oneliner = $MM->oneliner($perl_code, \@switches);
761
762This will generate a perl one-liner safe for the particular platform
763you're on based on the given $perl_code and @switches (a -e is
764assumed) suitable for using in a make target. It will use the proper
765shell quoting and escapes.
766
767$(PERLRUN) will be used as perl.
768
769Any newlines in $perl_code will be escaped. Leading and trailing
770newlines will be stripped. Makes this idiom much easier:
771
772 my $code = $MM->oneliner(<<'CODE', [...switches...]);
773some code here
774another line here
775CODE
776
777Usage might be something like:
778
779 # an echo emulation
780 $oneliner = $MM->oneliner('print "Foo\n"');
781 $make = '$oneliner > somefile';
782
783All dollar signs must be doubled in the $perl_code if you expect them
784to be interpreted normally, otherwise it will be considered a make
785macro. Also remember to quote make macros else it might be used as a
786bareword. For example:
787
788 # Assign the value of the $(VERSION_FROM) make macro to $vf.
789 $oneliner = $MM->oneliner('$$vf = "$(VERSION_FROM)"');
790
791Its currently very simple and may be expanded sometime in the figure
792to include more flexible code and switches.
793
794
795=item B<quote_literal>
796
797 my $safe_text = $MM->quote_literal($text);
798
799This will quote $text so it is interpreted literally in the shell.
800
801For example, on Unix this would escape any single-quotes in $text and
802put single-quotes around the whole thing.
803
804
805=item B<escape_newlines>
806
807 my $escaped_text = $MM->escape_newlines($text);
808
809Shell escapes newlines in $text.
810
811
812=item max_exec_len
813
814 my $max_exec_len = $MM->max_exec_len;
815
816Calculates the maximum command size the OS can exec. Effectively,
817this is the max size of a shell command line.
818
819=for _private
820$self->{_MAX_EXEC_LEN} is set by this method, but only for testing purposes.
821
822=item B<init_others>
823
824 $MM->init_others();
825
826Initializes the macro definitions used by tools_other() and places them
827in the $MM object.
828
829If there is no description, its the same as the parameter to
830WriteMakefile() documented in ExtUtils::MakeMaker.
831
832Defines at least these macros.
833
834 Macro Description
835
dedf98bc
MS
836 NOOP Do nothing
837 NOECHO Tell make not to display the command itself
479d2113
MS
838
839 MAKEFILE
840 FIRST_MAKEFILE
841 MAKEFILE_OLD
842 MAKE_APERL_FILE File used by MAKE_APERL
843
844 SHELL Program used to run
845 shell commands
846
dedf98bc 847 ECHO Print text adding a newline on the end
479d2113
MS
848 RM_F Remove a file
849 RM_RF Remove a directory
850 TOUCH Update a file's timestamp
851 TEST_F Test for a file's existence
852 CP Copy a file
853 MV Move a file
854 CHMOD Change permissions on a
855 file
856
857 UMASK_NULL Nullify umask
858 DEV_NULL Supress all command output
859
860=item init_DIRFILESEP
861
862 $MM->init_DIRFILESEP;
863 my $dirfilesep = $MM->{DIRFILESEP};
864
865Initializes the DIRFILESEP macro which is the seperator between the
866directory and filename in a filepath. ie. / on Unix, \ on Win32 and
867nothing on VMS.
868
869For example:
870
871 # instead of $(INST_ARCHAUTODIR)/extralibs.ld
872 $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
873
874Something of a hack but it prevents a lot of code duplication between
875MM_* variants.
876
877Do not use this as a seperator between directories. Some operating
878systems use different seperators between subdirectories as between
879directories and filenames (for example: VOLUME:[dir1.dir2]file on VMS).
880
881=item init_linker
882
883 $mm->init_linker;
884
885Initialize macros which have to do with linking.
886
887PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
888extensions.
889
890PERL_ARCHIVE_AFTER: path to a library which should be put on the
891linker command line I<after> the external libraries to be linked to
892dynamic extensions. This may be needed if the linker is one-pass, and
893Perl includes some overrides for C RTL functions, such as malloc().
894
895EXPORT_LIST: name of a file that is passed to linker to define symbols
896to be exported.
897
898Some OSes do not need these in which case leave it blank.
899
900
901=item init_platform
902
903 $mm->init_platform
904
905Initialize any macros which are for platform specific use only.
906
907A typical one is the version number of your OS specific mocule.
908(ie. MM_Unix_VERSION or MM_VMS_VERSION).
909
910=item platform_constants
911
912 my $make_frag = $mm->platform_constants
913
914Returns a make fragment defining all the macros initialized in
915init_platform() rather than put them in constants().
916
917=cut
918
919sub init_platform {
920 return '';
921}
922
923sub platform_constants {
924 return '';
925}
926
dedf98bc
MS
927=item os_flavor
928
929 my @os_flavor = $mm->os_flavor;
930
931@os_flavor is the style of operating system this is, usually
932corresponding to the MM_*.pm file we're using.
933
934The first element of @os_flavor is the major family (ie. Unix,
5dca256e 935Windows, VMS, OS/2, etc...) and the rest are sub families.
dedf98bc
MS
936
937Some examples:
938
939 Cygwin98 ('Unix', 'Cygwin', 'Cygwin9x')
940 Windows NT ('Win32', 'WinNT')
941 Win98 ('Win32', 'Win9x')
942 Linux ('Unix', 'Linux')
dedf98bc
MS
943 MacOS X ('Unix', 'Darwin', 'MacOS', 'MacOS X')
944 OS/2 ('OS/2')
945
946This is used to write code for styles of operating system.
947See os_flavor_is() for use.
948
479d2113 949
f6d6199c
MS
950=back
951
952=head1 AUTHOR
953
479d2113
MS
954Michael G Schwern <schwern@pobox.com> and the denizens of
955makemaker@perl.org with code from ExtUtils::MM_Unix and
956ExtUtils::MM_Win32.
f6d6199c
MS
957
958
959=cut
960
9611;