[Chapter 7] 7.2.24 ExtUtils::MM_Unix - Methods Used by ExtUtils::MakeMaker

7.2.24 ExtUtils::MM_Unix - Methods Used by ExtUtils::MakeMaker

require ExtUtils::MM_Unix;

The methods provided by this package (and by the other MM_* packages) are designed to be used in conjunction with ExtUtils::MakeMaker. You will never require this module yourself. You would only define methods in this or a similar module if you're working on improving the porting capabilities of MakeMaker. Nevertheless, this is a laudable goal, so we'll talk about it here.

When MakeMaker writes a Makefile, it creates one or more objects that inherit their methods from package MM. MM itself doesn't provide any methods, but it inherits from the ExtUtils::MM_Unix class. However, for certain platforms, it also inherits from an OS-specific module such as MM_VMS, and it does this before it inherits from the MM_Unix module in the @ISA list. The inheritance tree of MM therefore lets the OS-specific package override any of the methods listed here. In a sense, the MM_Unix package is slightly misnamed, since it provides fundamental methods on non-UNIX systems too, to the extent that the system is like UNIX.

7.2.24.1 MM methods

We've avoided listing deprecated methods here, as well as any private methods you're unlikely to want to override.

catdir LIST: Concatenates two or more directory names to form a complete path ending with a directory. On UNIX it just glues it together with a / character.
catfile LIST: Concatenates one or more directory names and a filename to form a complete path ending with a filename. Also uses / on UNIX.
dir_target: Takes an array of directories that need to exist and returns a Makefile entry for a .exists file in these directories. Returns nothing if the entry has already been processed. We're helpless, though, if the same directory comes as $(FOO) and as bar. Both of them get an entry; that's why we use "::".
file_name_is_absolute FILENAME: Takes as argument a path and returns true if it is an absolute path.
find_perl VERSION, NAMES, DIRS, TRACE: Searches for an executable Perl that is at least the specified VERSION, named by one of the entries in NAMES (an array reference), and located in one of the entries of DIRS (also an array reference). It prints debugging info if TRACE is true.
guess_name: Guesses the name of this package by examining the working directory's name. MakeMaker calls this only if the developer has not supplied a NAME attribute. Shame on you.
has_link_code: Returns true if C, XS, MYEXTLIB or similar objects exist within this object that need a compiler. Does not descend into subdirectories as needs_linking() does.
libscan FILENAME: Takes a path to a file that is found by init_dirscan() and returns false if we don't want to include this file in the library. It is mainly used to exclude RCS/, CVS/, and SCCS/ directories from installation.
lsdir DIR, REGEXP: Takes as arguments a directory name and a regular expression. Returns all entries in the directory that match the regular expression.
maybe_command_in_dirs: Method under development. Not yet used.
maybe_command FILENAME: Returns true if the argument is likely to be a command.
needs_linking: Does this module need linking? Looks into subdirectory objects, if any. (See also has_link_code().)
nicetext TARGET: (A misnamed method.) The MM_Unix version of the method just returns the argument without further processing. On VMS, this method ensures that colons marking targets are preceded by space. Most UNIX makes don't need this, but it's necessary under VMS to distinguish the target delimiter from a colon appearing as part of a filespec.
path: Takes no argument. Returns the environment variable PATH as an array.
perl_script FILENAME: Returns true if the argument is likely to be a Perl script. With MM_Unix this is true for any ordinary, readable file.
prefixify ATTRNAME, OLDPREFIX, NEWPREFIX: Processes a path attribute in $self->{ ATTRNAME }. First it looks it up for you in %Config if it doesn't have a value yet. Then it replaces (in-place) the OLDPREFIX with the NEWPREFIX (if it matches).
replace_manpage_separator FILENAME: Takes the filename of a package, which if it's a nested package will have a name of the form "Foo/Bar" (under UNIX), and replaces the subdirectory delimiter with "::". Returns the altered name.

7.2.24.2 Methods to produce chunks of text for the Makefile

When MakeMaker thinks it has all its ducks in a row, it calls a special sequence of methods to produce the Makefile for a given MakeMaker object. The list of methods it calls is specified in the array @ExtUtils::MakeMaker::MM_Sections, one method per section. Since these routines are all called the same way, we won't document each of them separately, except to list them.

By far the most accurate and up-to-date documentation for what each method does is actually the Makefile that MakeMaker produces. Each section of the file is labeled with the name of the method that produces it, so once you see how you want to change the Makefile, it's a trivial matter to work back from the proposed change and find the method responsible for it.

You've plowed through a lot of ugly things to get here, but since you've read this far, we'll reward you by pointing out something incredibly beautiful in MakeMaker. The arguments (if any) that are passed to each method are simply the pseudo-attributes of the same name that you already saw documented under "Additional Lowercase Attributes" in the section on ExtUtils::MakeMaker. You'll recall that those pseudo-attributes were specified as anonymous hashes, which Just Happen to have exactly the same syntax inside as named parameters. Fancy that. So the arguments just come right into your method as ordinary named parameters. Assign the arguments to a hash, and off you go. And it's completely forward and backward compatible. Even if you override a method that didn't have arguments before, there's no problem. Since it's all driven off the method name, just name your new pseudo-attribute after your method, and your method will get its arguments.

The return values are also easy to understand: each method simply returns the string it wants to put into its section of the Makefile.

Two special methods are post_initialize() and postamble(), each of which returns an empty string by default. You can define them in your Makefile.PL to insert customized text near the beginning or end of the Makefile.

Here are the methods. They're called in this order (reading down the columns):

`post_initialize()`	`top_targets()`	`realclean()`
`const_config()`	`linkext()`	`dist_basics()`
`constants()`	`dlsyms()`	`dist_core()`
`const_loadlibs()`	`dynamic()`	`dist_dir()`
`const_cccmd()`	`dynamic_bs()`	`dist_test()`
`tool_autosplit()`	`dynamic_lib()`	`dist_ci()`
`tool_xsubpp()`	`static()`	`install()`
`tools_other()`	`static_lib()`	`force()`
`dist()`	`installpm()`	`perldepend()`
`macro()`	`installpm_x()`	`makefile()`
`depend()`	`manifypods()`	`staticmake()`
`post_constants()`	`processPL()`	`test()`
`pasthru()`	`installbin()`	`test_via_harness()`
`c_o()`	`subdirs()`	`test_via_script()`
`xs_c()`	`subdir_x()`	`postamble()`
`xs_o()`	`clean()`

7.2.24.3 See also

ExtUtils::MakeMaker library module.