Debian Codegraph @

upstream/debian-unstable/man3/ExtUtils::MM_Any.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "ExtUtils::MM_Any 3perl"
58 .TH ExtUtils::MM_Any 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 ExtUtils::MM_Any \- Platform\-agnostic MM methods
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& FOR INTERNAL USE ONLY!
69 \&
70 \& package ExtUtils::MM_SomeOS;
71 \&
72 \& # Temporarily, you have to subclass both. Put MM_Any first.
73 \& require ExtUtils::MM_Any;
74 \& require ExtUtils::MM_Unix;
75 \& @ISA = qw(ExtUtils::MM_Any ExtUtils::Unix);
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 \&\fBFOR INTERNAL USE ONLY!\fR
80 .PP
81 ExtUtils::MM_Any is a superclass for the ExtUtils::MM_* set of
82 modules. It contains methods which are either inherently
83 cross-platform or are written in a cross-platform manner.
84 .PP
85 Subclass off of ExtUtils::MM_Any \fIand\fR ExtUtils::MM_Unix. This is a
86 temporary solution.
87 .PP
88 \&\fBTHIS MAY BE TEMPORARY!\fR
89 .SH METHODS
90 .IX Header "METHODS"
91 Any methods marked \fIAbstract\fR must be implemented by subclasses.
92 .SS "Cross-platform helper methods"
93 .IX Subsection "Cross-platform helper methods"
94 These are methods which help writing cross-platform code.
95 .PP
96 \fIos_flavor Abstract\fR
97 .IX Subsection "os_flavor Abstract"
98 .PP
99 .Vb 1
100 \& my @os_flavor = $mm\->os_flavor;
101 .Ve
102 .PP
103 \&\f(CW@os_flavor\fR is the style of operating system this is, usually
104 corresponding to the MM_*.pm file we're using.
105 .PP
106 The first element of \f(CW@os_flavor\fR is the major family (ie. Unix,
107 Windows, VMS, OS/2, etc...) and the rest are sub families.
108 .PP
109 Some examples:
110 .PP
111 .Vb 6
112 \& Cygwin98 (\*(AqUnix\*(Aq, \*(AqCygwin\*(Aq, \*(AqCygwin9x\*(Aq)
113 \& Windows (\*(AqWin32\*(Aq)
114 \& Win98 (\*(AqWin32\*(Aq, \*(AqWin9x\*(Aq)
115 \& Linux (\*(AqUnix\*(Aq, \*(AqLinux\*(Aq)
116 \& MacOS X (\*(AqUnix\*(Aq, \*(AqDarwin\*(Aq, \*(AqMacOS\*(Aq, \*(AqMacOS X\*(Aq)
117 \& OS/2 (\*(AqOS/2\*(Aq)
118 .Ve
119 .PP
120 This is used to write code for styles of operating system.
121 See \fBos_flavor_is()\fR for use.
122 .PP
123 \fIos_flavor_is\fR
124 .IX Subsection "os_flavor_is"
125 .PP
126 .Vb 2
127 \& my $is_this_flavor = $mm\->os_flavor_is($this_flavor);
128 \& my $is_this_flavor = $mm\->os_flavor_is(@one_of_these_flavors);
129 .Ve
130 .PP
131 Checks to see if the current operating system is one of the given flavors.
132 .PP
133 This is useful for code like:
134 .PP
135 .Vb 6
136 \& if( $mm\->os_flavor_is(\*(AqUnix\*(Aq) ) {
137 \& $out = \`foo 2>&1\`;
138 \& }
139 \& else {
140 \& $out = \`foo\`;
141 \& }
142 .Ve
143 .PP
144 \fIcan_load_xs\fR
145 .IX Subsection "can_load_xs"
146 .PP
147 .Vb 1
148 \& my $can_load_xs = $self\->can_load_xs;
149 .Ve
150 .PP
151 Returns true if we have the ability to load XS.
152 .PP
153 This is important because miniperl, used to build XS modules in the
154 core, can not load XS.
155 .PP
156 \fIcan_run\fR
157 .IX Subsection "can_run"
158 .PP
159 .Vb 2
160 \& use ExtUtils::MM;
161 \& my $runnable = MM\->can_run($Config{make});
162 .Ve
163 .PP
164 If called in a scalar context it will return the full path to the binary
165 you asked for if it was found, or \f(CW\*(C`undef\*(C'\fR if it was not.
166 .PP
167 If called in a list context, it will return a list of the full paths to instances
168 of the binary where found in \f(CW\*(C`PATH\*(C'\fR, or an empty list if it was not found.
169 .PP
170 Copied from IPC::Cmd, but modified into
171 a method (and removed \f(CW$INSTANCES\fR capability).
172 .PP
173 \fIcan_redirect_error\fR
174 .IX Subsection "can_redirect_error"
175 .PP
176 .Vb 1
177 \& $useredirect = MM\->can_redirect_error;
178 .Ve
179 .PP
180 True if on an OS where qx operator (or backticks) can redirect \f(CW\*(C`STDERR\*(C'\fR
181 onto \f(CW\*(C`STDOUT\*(C'\fR.
182 .PP
183 \fIis_make_type\fR
184 .IX Subsection "is_make_type"
185 .PP
186 .Vb 1
187 \& my $is_dmake = $self\->is_make_type(\*(Aqdmake\*(Aq);
188 .Ve
189 .PP
190 Returns true if \f(CW\*(C`$self\->make\*(C'\fR is the given type; possibilities are:
191 .PP
192 .Vb 4
193 \& gmake GNU make
194 \& dmake
195 \& nmake
196 \& bsdmake BSD pmake\-derived
197 .Ve
198 .PP
199 \fIcan_dep_space\fR
200 .IX Subsection "can_dep_space"
201 .PP
202 .Vb 1
203 \& my $can_dep_space = $self\->can_dep_space;
204 .Ve
205 .PP
206 Returns true if \f(CW\*(C`make\*(C'\fR can handle (probably by quoting)
207 dependencies that contain a space. Currently known true for GNU make,
208 false for BSD pmake derivative.
209 .PP
210 \fIquote_dep\fR
211 .IX Subsection "quote_dep"
212 .PP
213 .Vb 1
214 \& $text = $mm\->quote_dep($text);
215 .Ve
216 .PP
217 Method that protects Makefile single-value constants (mainly filenames),
218 so that make will still treat them as single values even if they
219 inconveniently have spaces in. If the make program being used cannot
220 achieve such protection and the given text would need it, throws an
221 exception.
222 .PP
223 \fIsplit_command\fR
224 .IX Subsection "split_command"
225 .PP
226 .Vb 1
227 \& my @cmds = $MM\->split_command($cmd, @args);
228 .Ve
229 .PP
230 Most OS have a maximum command length they can execute at once. Large
231 modules can easily generate commands well past that limit. Its
232 necessary to split long commands up into a series of shorter commands.
233 .PP
234 \&\f(CW\*(C`split_command\*(C'\fR will return a series of \f(CW@cmds\fR each processing part of
235 the args. Collectively they will process all the arguments. Each
236 individual line in \f(CW@cmds\fR will not be longer than the
237 \&\f(CW$self\fR\->max_exec_len being careful to take into account macro expansion.
238 .PP
239 \&\f(CW$cmd\fR should include any switches and repeated initial arguments.
240 .PP
241 If no \f(CW@args\fR are given, no \f(CW@cmds\fR will be returned.
242 .PP
243 Pairs of arguments will always be preserved in a single command, this
244 is a heuristic for things like pm_to_blib and pod2man which work on
245 pairs of arguments. This makes things like this safe:
246 .PP
247 .Vb 1
248 \& $self\->split_command($cmd, %pod2man);
249 .Ve
250 .PP
251 \fImake_type\fR
252 .IX Subsection "make_type"
253 .PP
254 Returns a suitable string describing the type of makefile being written.
255 .PP
256 \fIstashmeta\fR
257 .IX Subsection "stashmeta"
258 .PP
259 .Vb 1
260 \& my @recipelines = $MM\->stashmeta($text, $file);
261 .Ve
262 .PP
263 Generates a set of \f(CW@recipelines\fR which will result in the literal
264 \&\f(CW$text\fR ending up in literal \f(CW$file\fR when the recipe is executed. Call
265 it once, with all the text you want in \f(CW$file\fR. Make macros will not
266 be expanded, so the locations will be fixed at configure-time, not
267 at build-time.
268 .PP
269 \fIecho\fR
270 .IX Subsection "echo"
271 .PP
272 .Vb 3
273 \& my @commands = $MM\->echo($text);
274 \& my @commands = $MM\->echo($text, $file);
275 \& my @commands = $MM\->echo($text, $file, \e%opts);
276 .Ve
277 .PP
278 Generates a set of \f(CW@commands\fR which print the \f(CW$text\fR to a \f(CW$file\fR.
279 .PP
280 If \f(CW$file\fR is not given, output goes to STDOUT.
281 .PP
282 If \f(CW$opts\fR{append} is true the \f(CW$file\fR will be appended to rather than
283 overwritten. Default is to overwrite.
284 .PP
285 If \f(CW$opts\fR{allow_variables} is true, make variables of the form
286 \&\f(CW\*(C`$(...)\*(C'\fR will not be escaped. Other \f(CW\*(C`$\*(C'\fR will. Default is to escape
287 all \f(CW\*(C`$\*(C'\fR.
288 .PP
289 Example of use:
290 .PP
291 .Vb 1
292 \& my $make = join \*(Aq\*(Aq, map "\et$_\en", $MM\->echo($text, $file);
293 .Ve
294 .PP
295 \fIwraplist\fR
296 .IX Subsection "wraplist"
297 .PP
298 .Vb 1
299 \& my $args = $mm\->wraplist(@list);
300 .Ve
301 .PP
302 Takes an array of items and turns them into a well-formatted list of
303 arguments. In most cases this is simply something like:
304 .PP
305 .Vb 3
306 \& FOO \e
307 \& BAR \e
308 \& BAZ
309 .Ve
310 .PP
311 \fImaketext_filter\fR
312 .IX Subsection "maketext_filter"
313 .PP
314 .Vb 1
315 \& my $filter_make_text = $mm\->maketext_filter($make_text);
316 .Ve
317 .PP
318 The text of the Makefile is run through this method before writing to
319 disk. It allows systems a chance to make portability fixes to the
320 Makefile.
321 .PP
322 By default it does nothing.
323 .PP
324 This method is protected and not intended to be called outside of
325 MakeMaker.
326 .PP
327 \fIcd Abstract\fR
328 .IX Subsection "cd Abstract"
329 .PP
330 .Vb 1
331 \& my $subdir_cmd = $MM\->cd($subdir, @cmds);
332 .Ve
333 .PP
334 This will generate a make fragment which runs the \f(CW@cmds\fR in the given
335 \&\f(CW$dir\fR. The rough equivalent to this, except cross platform.
336 .PP
337 .Vb 1
338 \& cd $subdir && $cmd
339 .Ve
340 .PP
341 Currently \f(CW$dir\fR can only go down one level. "foo" is fine. "foo/bar" is
342 not. "../foo" is right out.
343 .PP
344 The resulting \f(CW$subdir_cmd\fR has no leading tab nor trailing newline. This
345 makes it easier to embed in a make string. For example.
346 .PP
347 .Vb 6
348 \& my $make = sprintf <<\*(AqCODE\*(Aq, $subdir_cmd;
349 \& foo :
350 \& $(ECHO) what
351 \& %s
352 \& $(ECHO) mouche
353 \& CODE
354 .Ve
355 .PP
356 \fIoneliner Abstract\fR
357 .IX Subsection "oneliner Abstract"
358 .PP
359 .Vb 2
360 \& my $oneliner = $MM\->oneliner($perl_code);
361 \& my $oneliner = $MM\->oneliner($perl_code, \e@switches);
362 .Ve
363 .PP
364 This will generate a perl one-liner safe for the particular platform
365 you're on based on the given \f(CW$perl_code\fR and \f(CW@switches\fR (a \-e is
366 assumed) suitable for using in a make target. It will use the proper
367 shell quoting and escapes.
368 .PP
369 $(PERLRUN) will be used as perl.
370 .PP
371 Any newlines in \f(CW$perl_code\fR will be escaped. Leading and trailing
372 newlines will be stripped. Makes this idiom much easier:
373 .PP
374 .Vb 4
375 \& my $code = $MM\->oneliner(<<\*(AqCODE\*(Aq, [...switches...]);
376 \&some code here
377 \&another line here
378 \&CODE
379 .Ve
380 .PP
381 Usage might be something like:
382 .PP
383 .Vb 3
384 \& # an echo emulation
385 \& $oneliner = $MM\->oneliner(\*(Aqprint "Foo\en"\*(Aq);
386 \& $make = \*(Aq$oneliner > somefile\*(Aq;
387 .Ve
388 .PP
389 Dollar signs in the \f(CW$perl_code\fR will be protected from make using the
390 \&\f(CW\*(C`quote_literal\*(C'\fR method, unless they are recognised as being a make
391 variable, \f(CW\*(C`$(varname)\*(C'\fR, in which case they will be left for make
392 to expand. Remember to quote make macros else it might be used as a
393 bareword. For example:
394 .PP
395 .Vb 2
396 \& # Assign the value of the $(VERSION_FROM) make macro to $vf.
397 \& $oneliner = $MM\->oneliner(\*(Aq$vf = "$(VERSION_FROM)"\*(Aq);
398 .Ve
399 .PP
400 Its currently very simple and may be expanded sometime in the figure
401 to include more flexible code and switches.
402 .PP
403 \fIquote_literal Abstract\fR
404 .IX Subsection "quote_literal Abstract"
405 .PP
406 .Vb 2
407 \& my $safe_text = $MM\->quote_literal($text);
408 \& my $safe_text = $MM\->quote_literal($text, \e%options);
409 .Ve
410 .PP
411 This will quote \f(CW$text\fR so it is interpreted literally in the shell.
412 .PP
413 For example, on Unix this would escape any single-quotes in \f(CW$text\fR and
414 put single-quotes around the whole thing.
415 .PP
416 If \f(CW$options\fR{allow_variables} is true it will leave \f(CW\*(Aq$(FOO)\*(Aq\fR make
417 variables untouched. If false they will be escaped like any other
418 \&\f(CW\*(C`$\*(C'\fR. Defaults to true.
419 .PP
420 \fIescape_dollarsigns\fR
421 .IX Subsection "escape_dollarsigns"
422 .PP
423 .Vb 1
424 \& my $escaped_text = $MM\->escape_dollarsigns($text);
425 .Ve
426 .PP
427 Escapes stray \f(CW\*(C`$\*(C'\fR so they are not interpreted as make variables.
428 .PP
429 It lets by \f(CW\*(C`$(...)\*(C'\fR.
430 .PP
431 \fIescape_all_dollarsigns\fR
432 .IX Subsection "escape_all_dollarsigns"
433 .PP
434 .Vb 1
435 \& my $escaped_text = $MM\->escape_all_dollarsigns($text);
436 .Ve
437 .PP
438 Escapes all \f(CW\*(C`$\*(C'\fR so they are not interpreted as make variables.
439 .PP
440 \fIescape_newlines Abstract\fR
441 .IX Subsection "escape_newlines Abstract"
442 .PP
443 .Vb 1
444 \& my $escaped_text = $MM\->escape_newlines($text);
445 .Ve
446 .PP
447 Shell escapes newlines in \f(CW$text\fR.
448 .PP
449 \fImax_exec_len Abstract\fR
450 .IX Subsection "max_exec_len Abstract"
451 .PP
452 .Vb 1
453 \& my $max_exec_len = $MM\->max_exec_len;
454 .Ve
455 .PP
456 Calculates the maximum command size the OS can exec. Effectively,
457 this is the max size of a shell command line.
458 .PP
459 \fImake\fR
460 .IX Subsection "make"
461 .PP
462 .Vb 1
463 \& my $make = $MM\->make;
464 .Ve
465 .PP
466 Returns the make variant we're generating the Makefile for. This attempts
467 to do some normalization on the information from \f(CW%Config\fR or the user.
468 .SS Targets
469 .IX Subsection "Targets"
470 These are methods which produce make targets.
471 .PP
472 \fIall_target\fR
473 .IX Subsection "all_target"
474 .PP
475 Generate the default target 'all'.
476 .PP
477 \fIblibdirs_target\fR
478 .IX Subsection "blibdirs_target"
479 .PP
480 .Vb 1
481 \& my $make_frag = $mm\->blibdirs_target;
482 .Ve
483 .PP
484 Creates the blibdirs target which creates all the directories we use
485 in blib/.
486 .PP
487 The blibdirs.ts target is deprecated. Depend on blibdirs instead.
488 .PP
489 \fIclean (o)\fR
490 .IX Subsection "clean (o)"
491 .PP
492 Defines the clean target.
493 .PP
494 \fIclean_subdirs_target\fR
495 .IX Subsection "clean_subdirs_target"
496 .PP
497 .Vb 1
498 \& my $make_frag = $MM\->clean_subdirs_target;
499 .Ve
500 .PP
501 Returns the clean_subdirs target. This is used by the clean target to
502 call clean on any subdirectories which contain Makefiles.
503 .PP
504 \fIdir_target\fR
505 .IX Subsection "dir_target"
506 .PP
507 .Vb 1
508 \& my $make_frag = $mm\->dir_target(@directories);
509 .Ve
510 .PP
511 Generates targets to create the specified directories and set its
512 permission to PERM_DIR.
513 .PP
514 Because depending on a directory to just ensure it exists doesn't work
515 too well (the modified time changes too often) \fBdir_target()\fR creates a
516 \&.exists file in the created directory. It is this you should depend on.
517 For portability purposes you should use the $(DIRFILESEP) macro rather
518 than a '/' to separate the directory from the file.
519 .PP
520 .Vb 1
521 \& yourdirectory$(DIRFILESEP).exists
522 .Ve
523 .PP
524 \fIdistdir\fR
525 .IX Subsection "distdir"
526 .PP
527 Defines the scratch directory target that will hold the distribution
528 before tar-ing (or shar-ing).
529 .PP
530 \fIdist_test\fR
531 .IX Subsection "dist_test"
532 .PP
533 Defines a target that produces the distribution in the
534 scratch directory, and runs 'perl Makefile.PL; make ;make test' in that
535 subdirectory.
536 .PP
537 \fIxs_dlsyms_arg\fR
538 .IX Subsection "xs_dlsyms_arg"
539 .PP
540 Returns command-line arg(s) to linker for file listing dlsyms to export.
541 Defaults to returning empty string, can be overridden by e.g. AIX.
542 .PP
543 \fIxs_dlsyms_ext\fR
544 .IX Subsection "xs_dlsyms_ext"
545 .PP
546 Returns file-extension for \f(CW\*(C`xs_make_dlsyms\*(C'\fR method's output file,
547 including any "." character.
548 .PP
549 \fIxs_dlsyms_extra\fR
550 .IX Subsection "xs_dlsyms_extra"
551 .PP
552 Returns any extra text to be prepended to the \f(CW$extra\fR argument of
553 \&\f(CW\*(C`xs_make_dlsyms\*(C'\fR.
554 .PP
555 \fIxs_dlsyms_iterator\fR
556 .IX Subsection "xs_dlsyms_iterator"
557 .PP
558 Iterates over necessary shared objects, calling \f(CW\*(C`xs_make_dlsyms\*(C'\fR method
559 for each with appropriate arguments.
560 .PP
561 \fIxs_make_dlsyms\fR
562 .IX Subsection "xs_make_dlsyms"
563 .PP
564 .Vb 12
565 \& $self\->xs_make_dlsyms(
566 \& \e%attribs, # hashref from %attribs in caller
567 \& "$self\->{BASEEXT}.def", # output file for Makefile target
568 \& \*(AqMakefile.PL\*(Aq, # dependency
569 \& $self\->{NAME}, # shared object\*(Aqs "name"
570 \& $self\->{DLBASE}, # last ::\-separated part of name
571 \& $attribs{DL_FUNCS} || $self\->{DL_FUNCS} || {}, # various params
572 \& $attribs{FUNCLIST} || $self\->{FUNCLIST} || [],
573 \& $attribs{IMPORTS} || $self\->{IMPORTS} || {},
574 \& $attribs{DL_VARS} || $self\->{DL_VARS} || [],
575 \& # optional extra param that will be added as param to Mksymlists
576 \& );
577 .Ve
578 .PP
579 Utility method that returns Makefile snippet to call \f(CW\*(C`Mksymlists\*(C'\fR.
580 .PP
581 \fIdynamic (o)\fR
582 .IX Subsection "dynamic (o)"
583 .PP
584 Defines the dynamic target.
585 .PP
586 \fImakemakerdflt_target\fR
587 .IX Subsection "makemakerdflt_target"
588 .PP
589 .Vb 1
590 \& my $make_frag = $mm\->makemakerdflt_target
591 .Ve
592 .PP
593 Returns a make fragment with the makemakerdeflt_target specified.
594 This target is the first target in the Makefile, is the default target
595 and simply points off to 'all' just in case any make variant gets
596 confused or something gets snuck in before the real 'all' target.
597 .PP
598 \fImanifypods_target\fR
599 .IX Subsection "manifypods_target"
600 .PP
601 .Vb 1
602 \& my $manifypods_target = $self\->manifypods_target;
603 .Ve
604 .PP
605 Generates the manifypods target. This target generates man pages from
606 all POD files in MAN1PODS and MAN3PODS.
607 .PP
608 \fImetafile_target\fR
609 .IX Subsection "metafile_target"
610 .PP
611 .Vb 1
612 \& my $target = $mm\->metafile_target;
613 .Ve
614 .PP
615 Generate the metafile target.
616 .PP
617 Writes the file META.yml (YAML encoded meta-data) and META.json
618 (JSON encoded meta-data) about the module in the distdir.
619 The format follows Module::Build's as closely as possible.
620 .PP
621 \fImetafile_data\fR
622 .IX Subsection "metafile_data"
623 .PP
624 .Vb 1
625 \& my $metadata_hashref = $mm\->metafile_data(\e%meta_add, \e%meta_merge);
626 .Ve
627 .PP
628 Returns the data which MakeMaker turns into the META.yml file
629 and the META.json file. It is always in version 2.0 of the format.
630 .PP
631 Values of \f(CW%meta_add\fR will overwrite any existing metadata in those
632 keys. \f(CW%meta_merge\fR will be merged with them.
633 .PP
634 \fImetafile_file\fR
635 .IX Subsection "metafile_file"
636 .PP
637 .Vb 1
638 \& my $meta_yml = $mm\->metafile_file(@metadata_pairs);
639 .Ve
640 .PP
641 Turns the \f(CW@metadata_pairs\fR into YAML.
642 .PP
643 This method does not implement a complete YAML dumper, being limited
644 to dump a hash with values which are strings, undef's or nested hashes
645 and arrays of strings. No quoting/escaping is done.
646 .PP
647 \fIdistmeta_target\fR
648 .IX Subsection "distmeta_target"
649 .PP
650 .Vb 1
651 \& my $make_frag = $mm\->distmeta_target;
652 .Ve
653 .PP
654 Generates the distmeta target to add META.yml and META.json to the MANIFEST
655 in the distdir.
656 .PP
657 \fImymeta\fR
658 .IX Subsection "mymeta"
659 .PP
660 .Vb 1
661 \& my $mymeta = $mm\->mymeta;
662 .Ve
663 .PP
664 Generate MYMETA information as a hash either from an existing CPAN Meta file
665 (META.json or META.yml) or from internal data.
666 .PP
667 \fIwrite_mymeta\fR
668 .IX Subsection "write_mymeta"
669 .PP
670 .Vb 1
671 \& $self\->write_mymeta( $mymeta );
672 .Ve
673 .PP
674 Write MYMETA information to MYMETA.json and MYMETA.yml.
675 .PP
676 \fIrealclean (o)\fR
677 .IX Subsection "realclean (o)"
678 .PP
679 Defines the realclean target.
680 .PP
681 \fIrealclean_subdirs_target\fR
682 .IX Subsection "realclean_subdirs_target"
683 .PP
684 .Vb 1
685 \& my $make_frag = $MM\->realclean_subdirs_target;
686 .Ve
687 .PP
688 Returns the realclean_subdirs target. This is used by the realclean
689 target to call realclean on any subdirectories which contain Makefiles.
690 .PP
691 \fIsignature_target\fR
692 .IX Subsection "signature_target"
693 .PP
694 .Vb 1
695 \& my $target = $mm\->signature_target;
696 .Ve
697 .PP
698 Generate the signature target.
699 .PP
700 Writes the file SIGNATURE with "cpansign \-s".
701 .PP
702 \fIdistsignature_target\fR
703 .IX Subsection "distsignature_target"
704 .PP
705 .Vb 1
706 \& my $make_frag = $mm\->distsignature_target;
707 .Ve
708 .PP
709 Generates the distsignature target to add SIGNATURE to the MANIFEST in the
710 distdir.
711 .PP
712 \fIspecial_targets\fR
713 .IX Subsection "special_targets"
714 .PP
715 .Vb 1
716 \& my $make_frag = $mm\->special_targets
717 .Ve
718 .PP
719 Returns a make fragment containing any targets which have special
720 meaning to make. For example, .SUFFIXES and .PHONY.
721 .SS "Init methods"
722 .IX Subsection "Init methods"
723 Methods which help initialize the MakeMaker object and macros.
724 .PP
725 \fIinit_ABSTRACT\fR
726 .IX Subsection "init_ABSTRACT"
727 .PP
728 .Vb 1
729 \& $mm\->init_ABSTRACT
730 .Ve
731 .PP
732 \fIinit_INST\fR
733 .IX Subsection "init_INST"
734 .PP
735 .Vb 1
736 \& $mm\->init_INST;
737 .Ve
738 .PP
739 Called by init_main. Sets up all INST_* variables except those related
740 to XS code. Those are handled in init_xs.
741 .PP
742 \fIinit_INSTALL\fR
743 .IX Subsection "init_INSTALL"
744 .PP
745 .Vb 1
746 \& $mm\->init_INSTALL;
747 .Ve
748 .PP
749 Called by init_main. Sets up all INSTALL_* variables (except
750 INSTALLDIRS) and *PREFIX.
751 .PP
752 \fIinit_INSTALL_from_PREFIX\fR
753 .IX Subsection "init_INSTALL_from_PREFIX"
754 .PP
755 .Vb 1
756 \& $mm\->init_INSTALL_from_PREFIX;
757 .Ve
758 .PP
759 \fIinit_from_INSTALL_BASE\fR
760 .IX Subsection "init_from_INSTALL_BASE"
761 .PP
762 .Vb 1
763 \& $mm\->init_from_INSTALL_BASE
764 .Ve
765 .PP
766 \fIinit_VERSION Abstract\fR
767 .IX Subsection "init_VERSION Abstract"
768 .PP
769 .Vb 1
770 \& $mm\->init_VERSION
771 .Ve
772 .PP
773 Initialize macros representing versions of MakeMaker and other tools
774 .PP
775 MAKEMAKER: path to the MakeMaker module.
776 .PP
777 MM_VERSION: ExtUtils::MakeMaker Version
778 .PP
779 MM_REVISION: ExtUtils::MakeMaker version control revision (for backwards
780 compat)
781 .PP
782 VERSION: version of your module
783 .PP
784 VERSION_MACRO: which macro represents the version (usually 'VERSION')
785 .PP
786 VERSION_SYM: like version but safe for use as an RCS revision number
787 .PP
788 DEFINE_VERSION: \-D line to set the module version when compiling
789 .PP
790 XS_VERSION: version in your .xs file. Defaults to $(VERSION)
791 .PP
792 XS_VERSION_MACRO: which macro represents the XS version.
793 .PP
794 XS_DEFINE_VERSION: \-D line to set the xs version when compiling.
795 .PP
796 Called by init_main.
797 .PP
798 \fIinit_tools\fR
799 .IX Subsection "init_tools"
800 .PP
801 .Vb 1
802 \& $MM\->init_tools();
803 .Ve
804 .PP
805 Initializes the simple macro definitions used by \fBtools_other()\fR and
806 places them in the \f(CW$MM\fR object. These use conservative cross platform
807 versions and should be overridden with platform specific versions for
808 performance.
809 .PP
810 Defines at least these macros.
811 .PP
812 .Vb 1
813 \& Macro Description
814 \&
815 \& NOOP Do nothing
816 \& NOECHO Tell make not to display the command itself
817 \&
818 \& SHELL Program used to run shell commands
819 \&
820 \& ECHO Print text adding a newline on the end
821 \& RM_F Remove a file
822 \& RM_RF Remove a directory
823 \& TOUCH Update a file\*(Aqs timestamp
824 \& TEST_F Test for a file\*(Aqs existence
825 \& TEST_S Test the size of a file
826 \& CP Copy a file
827 \& CP_NONEMPTY Copy a file if it is not empty
828 \& MV Move a file
829 \& CHMOD Change permissions on a file
830 \& FALSE Exit with non\-zero
831 \& TRUE Exit with zero
832 \&
833 \& UMASK_NULL Nullify umask
834 \& DEV_NULL Suppress all command output
835 .Ve
836 .PP
837 \fIinit_others\fR
838 .IX Subsection "init_others"
839 .PP
840 .Vb 1
841 \& $MM\->init_others();
842 .Ve
843 .PP
844 Initializes the macro definitions having to do with compiling and
845 linking used by \fBtools_other()\fR and places them in the \f(CW$MM\fR object.
846 .PP
847 If there is no description, its the same as the parameter to
848 \&\fBWriteMakefile()\fR documented in ExtUtils::MakeMaker.
849 .PP
850 \fItools_other\fR
851 .IX Subsection "tools_other"
852 .PP
853 .Vb 1
854 \& my $make_frag = $MM\->tools_other;
855 .Ve
856 .PP
857 Returns a make fragment containing definitions for the macros \fBinit_others()\fR
858 initializes.
859 .PP
860 \fIinit_DIRFILESEP Abstract\fR
861 .IX Subsection "init_DIRFILESEP Abstract"
862 .PP
863 .Vb 2
864 \& $MM\->init_DIRFILESEP;
865 \& my $dirfilesep = $MM\->{DIRFILESEP};
866 .Ve
867 .PP
868 Initializes the DIRFILESEP macro which is the separator between the
869 directory and filename in a filepath. ie. / on Unix, \e on Win32 and
870 nothing on VMS.
871 .PP
872 For example:
873 .PP
874 .Vb 2
875 \& # instead of $(INST_ARCHAUTODIR)/extralibs.ld
876 \& $(INST_ARCHAUTODIR)$(DIRFILESEP)extralibs.ld
877 .Ve
878 .PP
879 Something of a hack but it prevents a lot of code duplication between
880 MM_* variants.
881 .PP
882 Do not use this as a separator between directories. Some operating
883 systems use different separators between subdirectories as between
884 directories and filenames (for example: VOLUME:[dir1.dir2]file on VMS).
885 .PP
886 \fIinit_linker Abstract\fR
887 .IX Subsection "init_linker Abstract"
888 .PP
889 .Vb 1
890 \& $mm\->init_linker;
891 .Ve
892 .PP
893 Initialize macros which have to do with linking.
894 .PP
895 PERL_ARCHIVE: path to libperl.a equivalent to be linked to dynamic
896 extensions.
897 .PP
898 PERL_ARCHIVE_AFTER: path to a library which should be put on the
899 linker command line \fIafter\fR the external libraries to be linked to
900 dynamic extensions. This may be needed if the linker is one-pass, and
901 Perl includes some overrides for C RTL functions, such as \fBmalloc()\fR.
902 .PP
903 EXPORT_LIST: name of a file that is passed to linker to define symbols
904 to be exported.
905 .PP
906 Some OSes do not need these in which case leave it blank.
907 .PP
908 \fIinit_platform\fR
909 .IX Subsection "init_platform"
910 .PP
911 .Vb 1
912 \& $mm\->init_platform
913 .Ve
914 .PP
915 Initialize any macros which are for platform specific use only.
916 .PP
917 A typical one is the version number of your OS specific module.
918 (ie. MM_Unix_VERSION or MM_VMS_VERSION).
919 .PP
920 \fIinit_MAKE\fR
921 .IX Subsection "init_MAKE"
922 .PP
923 .Vb 1
924 \& $mm\->init_MAKE
925 .Ve
926 .PP
927 Initialize MAKE from either a MAKE environment variable or \f(CW$Config\fR{make}.
928 .SS Tools
929 .IX Subsection "Tools"
930 A grab bag of methods to generate specific macros and commands.
931 .PP
932 \fImanifypods\fR
933 .IX Subsection "manifypods"
934 .PP
935 Defines targets and routines to translate the pods into manpages and
936 put them into the INST_* directories.
937 .PP
938 \fIPOD2MAN_macro\fR
939 .IX Subsection "POD2MAN_macro"
940 .PP
941 .Vb 1
942 \& my $pod2man_macro = $self\->POD2MAN_macro
943 .Ve
944 .PP
945 Returns a definition for the POD2MAN macro. This is a program
946 which emulates the pod2man utility. You can add more switches to the
947 command by simply appending them on the macro.
948 .PP
949 Typical usage:
950 .PP
951 .Vb 1
952 \& $(POD2MAN) \-\-section=3 \-\-perm_rw=$(PERM_RW) podfile1 man_page1 ...
953 .Ve
954 .PP
955 \fItest_via_harness\fR
956 .IX Subsection "test_via_harness"
957 .PP
958 .Vb 1
959 \& my $command = $mm\->test_via_harness($perl, $tests);
960 .Ve
961 .PP
962 Returns a \f(CW$command\fR line which runs the given set of \f(CW$tests\fR with
963 Test::Harness and the given \f(CW$perl\fR.
964 .PP
965 Used on the t/*.t files.
966 .PP
967 \fItest_via_script\fR
968 .IX Subsection "test_via_script"
969 .PP
970 .Vb 1
971 \& my $command = $mm\->test_via_script($perl, $script);
972 .Ve
973 .PP
974 Returns a \f(CW$command\fR line which just runs a single test without
975 Test::Harness. No checks are done on the results, they're just
976 printed.
977 .PP
978 Used for test.pl, since they don't always follow Test::Harness
979 formatting.
980 .PP
981 \fItool_autosplit\fR
982 .IX Subsection "tool_autosplit"
983 .PP
984 Defines a simple perl call that runs autosplit. May be deprecated by
985 pm_to_blib soon.
986 .PP
987 \fIarch_check\fR
988 .IX Subsection "arch_check"
989 .PP
990 .Vb 4
991 \& my $arch_ok = $mm\->arch_check(
992 \& $INC{"Config.pm"},
993 \& File::Spec\->catfile($Config{archlibexp}, "Config.pm")
994 \& );
995 .Ve
996 .PP
997 A sanity check that what Perl thinks the architecture is and what
998 Config thinks the architecture is are the same. If they're not it
999 will return false and show a diagnostic message.
1000 .PP
1001 When building Perl it will always return true, as nothing is installed
1002 yet.
1003 .PP
1004 The interface is a bit odd because this is the result of a
1005 quick refactoring. Don't rely on it.
1006 .SS "File::Spec wrappers"
1007 .IX Subsection "File::Spec wrappers"
1008 ExtUtils::MM_Any is a subclass of File::Spec. The methods noted here
1009 override File::Spec.
1010 .PP
1011 \fIcatfile\fR
1012 .IX Subsection "catfile"
1013 .PP
1014 File::Spec <= 0.83 has a bug where the file part of catfile is not
1015 canonicalized. This override fixes that bug.
1016 .SS Misc
1017 .IX Subsection "Misc"
1018 Methods I can't really figure out where they should go yet.
1019 .PP
1020 \fIfind_tests\fR
1021 .IX Subsection "find_tests"
1022 .PP
1023 .Vb 1
1024 \& my $test = $mm\->find_tests;
1025 .Ve
1026 .PP
1027 Returns a string suitable for feeding to the shell to return all
1028 tests in t/*.t.
1029 .PP
1030 \fIfind_tests_recursive\fR
1031 .IX Subsection "find_tests_recursive"
1032 .PP
1033 .Vb 1
1034 \& my $tests = $mm\->find_tests_recursive;
1035 .Ve
1036 .PP
1037 Returns a string suitable for feeding to the shell to return all
1038 tests in t/ but recursively. Equivalent to
1039 .PP
1040 .Vb 1
1041 \& my $tests = $mm\->find_tests_recursive_in(\*(Aqt\*(Aq);
1042 .Ve
1043 .PP
1044 \fIfind_tests_recursive_in\fR
1045 .IX Subsection "find_tests_recursive_in"
1046 .PP
1047 .Vb 1
1048 \& my $tests = $mm\->find_tests_recursive_in($dir);
1049 .Ve
1050 .PP
1051 Returns a string suitable for feeding to the shell to return all
1052 tests in \f(CW$dir\fR recursively.
1053 .PP
1054 \fIextra_clean_files\fR
1055 .IX Subsection "extra_clean_files"
1056 .PP
1057 .Vb 1
1058 \& my @files_to_clean = $MM\->extra_clean_files;
1059 .Ve
1060 .PP
1061 Returns a list of OS specific files to be removed in the clean target in
1062 addition to the usual set.
1063 .PP
1064 \fIinstallvars\fR
1065 .IX Subsection "installvars"
1066 .PP
1067 .Vb 1
1068 \& my @installvars = $mm\->installvars;
1069 .Ve
1070 .PP
1071 A list of all the INSTALL* variables without the INSTALL prefix. Useful
1072 for iteration or building related variable sets.
1073 .PP
1074 \fIlibscan\fR
1075 .IX Subsection "libscan"
1076 .PP
1077 .Vb 1
1078 \& my $wanted = $self\->libscan($path);
1079 .Ve
1080 .PP
1081 Takes a path to a file or dir and returns an empty string if we don't
1082 want to include this file in the library. Otherwise it returns the
1083 the \f(CW$path\fR unchanged.
1084 .PP
1085 Mainly used to exclude version control administrative directories
1086 and base-level \fIREADME.pod\fR from installation.
1087 .PP
1088 \fIplatform_constants\fR
1089 .IX Subsection "platform_constants"
1090 .PP
1091 .Vb 1
1092 \& my $make_frag = $mm\->platform_constants
1093 .Ve
1094 .PP
1095 Returns a make fragment defining all the macros initialized in
1096 \&\fBinit_platform()\fR rather than put them in \fBconstants()\fR.
1097 .PP
1098 \fIpost_constants (o)\fR
1099 .IX Subsection "post_constants (o)"
1100 .PP
1101 Returns an empty string per default. Dedicated to overrides from
1102 within Makefile.PL after all constants have been defined.
1103 .PP
1104 \fIpost_initialize (o)\fR
1105 .IX Subsection "post_initialize (o)"
1106 .PP
1107 Returns an empty string per default. Used in Makefile.PLs to add some
1108 chunk of text to the Makefile after the object is initialized.
1109 .PP
1110 \fIpostamble (o)\fR
1111 .IX Subsection "postamble (o)"
1112 .PP
1113 Returns an empty string. Can be used in Makefile.PLs to write some
1114 text to the Makefile at the end.
1115 .SH AUTHOR
1116 .IX Header "AUTHOR"
1117 Michael G Schwern <[email protected]> and the denizens of
1118 [email protected] with code from ExtUtils::MM_Unix and
1119 ExtUtils::MM_Win32.