Debian Codegraph @

upstream/opensuse-tumbleweed/man3/ExtUtils::MM_Any.3pm

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