+"The easy way is always mined.
+ The important things are always simple.
+ The simple things are always hard."
+ -- Some of Murphy's Laws of Combat
+
This is a short set of guidelines for those patching
ExtUtils::MakeMaker. Its not an iron-clad set of rules, but just
things which make life easier when reading and integrating a patch.
consider instead working on Module::Build, MakeMaker's heir apparent.
+Reporting bugs
+
+- Often the only information we have for fixing a bug is contained in your
+ report. So...
+
+- Please report your bugs via http://rt.cpan.org or by mailing to
+ makemaker@perl.org. RT is preferred.
+
+- Please report your bug immediately upon encountering it. Do not wait
+ until you have a patch to fix the bug. Patches are good, but not at
+ the expense of timely bug reports.
+
+- Please be as verbose as possible. Include the complete output of
+ your 'make test' or even 'make test TEST_VERBOSE=1' and a copy of the
+ generated Makefile. Err on the side of verbosity. The more data we
+ have to work with, the faster we can diagnose the problem.
+
+- If you find an undocumented feature, or if a feature has changed/been
+ added which causes a problem, report it. Do not assume it was done
+ deliberately. Even if it was done deliberately, we still want to hear
+ if it caused problems.
+
+- If you're testing MakeMaker against a development version of Perl,
+ please also check it against the latest stable version. This makes it
+ easier to figure out if its MakeMaker or Perl at fault.
+
+
Patching details
- Please use unified diffs. (diff -u)
backwacking lots of dollar signs because you have one interpolated
perl variable, like this:
- return <<'EOT'
-
+ return <<EOT;
subdirs ::
\$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
+
EOT
or are switching quoting contexts:
- return <<q{
+ return q{
subdirs ::
$(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
+
};
consider using sprintf instead.
return sprintf <<'EOT', $subdir;
-
subdirs ::
$(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
+
EOT
Backwards Compatibility
-- MakeMaker must be backwards compatible to 5.5.3 (5.005_03). Avoid any
+- MakeMaker must be backwards compatible to 5.5.4 (5.005_04). Avoid any
obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes
open my $fh, lvalue subroutines, any new core modules, etc...).
- MakeMaker should avoid having module dependencies. Avoid using modules
- which didn't come with 5.5.3 and avoid using features from newer
+ which didn't come with 5.5.4 and avoid using features from newer
versions. Sometimes this is unavoidable.
Cross-Platform Compatibility
-- MakeMaker must work on all architectures Perl works on (see perlport.pod)
- and with many different versions of make. This means all Unixen
- (including Cygwin and MacOS X), Windows (including DOS), MacOS Classic
- and VMS.
+- With the exception of MacOS Classic, MakeMaker must work on all
+ architectures Perl works on (see perlport.pod). This means all Unixen
+ (including Cygwin and MacOS X), Windows (including Win9x and DOS), and VMS.
+
+- Use the available macros rather than shell commands $(MV), $(CP),
+ $(TOUCH), etc...
+
+- MakeMaker must work on many makes. GNU, BSD, Solaris, nmake, dmake, MMS
+ and MMK to name the most common. Keep your make code as simple as
+ possible.
+
+- Avoid special variables (even $@).
+
+- Format targets as "target : dependency", the spacing is important.
+
+- Use $(NOECHO) instead of @.
+
+- Use - to tell make to ignore the exit code of a command. (Unfortunately,
+ some make variants don't honor an $(IGNORE) macro).
+
+- Always put a space between $(NOECHO) and the command.
+
+- Always put a space between - (ignore) and the command.
+
+- Always put $(NOECHO) and - together, no space between them.
+
+ # Right
+ -$(NOECHO) command
+ $(NOECHO) command
+ - command
- Often when you patch ExtUtils::MM_Unix, similar patches must be done
to the other MM_* modules. If you can, please do this extra work
otherwise I have to. If you can't, that's ok. We can help.
- If possible, please test your patch on two Very Different architectures.
- Unix, Windows, MacOS Classic and VMS being Very Different. Note: Cygwin
- and OS X are Unixen for our purposes.
+ Unix, Windows and VMS being Very Different. Note: Cygwin and OS X are
+ Unixen for our purposes.
- If nothing else, at least try it on two different Unixen or Windows
machines (ie. Linux and IRIX or WinNT and Win95).
creating one. Its ok to have an MM_* module with only one method.
- Some shells have very small buffers. This means command lines must
- be as small as possible. 20K is the upper limit for Unixen, and 256
- for VMS. Not sure what Windows and DOS are limited to, probably 1K.
- This limit *includes* any files passed into it. Some modules (such as
- bioperl) generate enourmous commands because of their large number of
- files. If your command is just too long, consider making it an
- ExtUtils::Command::MM function.
+ be as small as possible. If your command is just too long, consider
+ making it an ExtUtils::Command::MM function. If your command might
+ receive many arguments (such as pod2man or pm_to_blib) consider
+ using split_command() to split it into several, shorter calls.
- Most shells quote differently. If you need to put a perl one-liner
in the Makefile, please use oneliner() to generate it.
=begin private
- =item _foo_bar
+ =head3 _foo_bar
$mm->_foo_bar
https://perl5.git.perl.org / perl5.git / blobdiff