1 This is a short set of guidelines for those patching
2 ExtUtils::MakeMaker. Its not an iron-clad set of rules, but just
3 things which make life easier when reading and integrating a patch.
5 Lots of information can be found in makemaker.org.
7 MakerMaker is being maintained until something else can replace it.
8 Bugs will be fixed and compatibility improved, but I would like to
9 avoid new features. If you want to add something to MakeMaker,
10 consider instead working on Module::Build, MakeMaker's heir apparent.
15 - Often the only information we have for fixing a bug is contained in your
18 - Please report your bugs via http://rt.cpan.org or by mailing to
19 makemaker@perl.org. RT is preferred.
21 - Please report your bug immediately upon encountering it. Do not wait
22 until you have a patch to fix the bug. Patches are good, but not at
23 the expense of timely bug reports.
25 - Please be as verbose as possible. Include the complete output of
26 your 'make test' or even 'make test TEST_VERBOSE=1' and a copy of the
27 generated Makefile. Err on the side of verbosity. The more data we
28 have to work with, the faster we can diagnose the problem.
30 - If you find an undocumented feature, or if a feature has changed/been
31 added which causes a problem, report it. Do not assume it was done
32 deliberately. Even if it was done deliberately, we still want to hear
33 if it caused problems.
35 - If you're testing MakeMaker against a development version of Perl,
36 please also check it against the latest stable version. This makes it
37 easier to figure out if its MakeMaker or Perl at fault.
42 - Please use unified diffs. (diff -u)
44 - Patches against the latest development snapshot from makemaker.org are
45 preferred. Patches against the latest CPAN version are ok, too.
47 - Post your patch to makemaker@perl.org.
52 - No literal tabs (except where necessary inside Makefile code, obviously).
54 - 4 character indentation.
56 - this_style is prefered instead of studlyCaps.
58 - Private subroutine names (ie. those used only in the same package
59 they're declared in) should start with an underscore (_sekret_method).
61 - Protected subroutines (ie. ones intended to be used by other modules in
62 ExtUtils::*) should be named normally (no leading underscore) but
63 documented as protected (see Documentation below).
65 - Do not use indirect object syntax (ie. new Foo::Bar (@args))
67 - make variables use dollar signs like Perl scalars. This causes problems
68 when you have to mix them both in a string. If you find yourself
69 backwacking lots of dollar signs because you have one interpolated
70 perl variable, like this:
74 \$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
78 or are switching quoting contexts:
82 $(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
86 consider using sprintf instead.
88 return sprintf <<'EOT', $subdir;
90 $(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
95 Refactoring and Cleanup
97 - MakeMaker is a mess. We like patches which clean things up.
100 Backwards Compatibility
102 - MakeMaker must be backwards compatible to 5.5.4 (5.005_04). Avoid any
103 obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes
104 open my $fh, lvalue subroutines, any new core modules, etc...).
106 - MakeMaker should avoid having module dependencies. Avoid using modules
107 which didn't come with 5.5.4 and avoid using features from newer
108 versions. Sometimes this is unavoidable.
111 Cross-Platform Compatibility
113 - With the exception of MacOS Classic, MakeMaker must work on all
114 architectures Perl works on (see perlport.pod). This means all Unixen
115 (including Cygwin and MacOS X), Windows (including Win9x and DOS), and VMS.
117 - Use the available macros rather than shell commands $(MV), $(CP),
120 - MakeMaker must work on many makes. GNU, BSD, Solaris, nmake, dmake, MMS
121 and MMK to name the most common. Keep your make code as simple as
124 - Avoid special variables (even $@).
126 - Format targets as "target : dependency", the spacing is important.
128 - Use $(NOECHO) instead of @.
130 - Always put a space between $(NOECHO) and the command.
132 - Always put a space between - (ignore) and the command.
134 - Always put $(NOECHO) and - together, no space between them.
136 - Often when you patch ExtUtils::MM_Unix, similar patches must be done
137 to the other MM_* modules. If you can, please do this extra work
138 otherwise I have to. If you can't, that's ok. We can help.
140 - If possible, please test your patch on two Very Different architectures.
141 Unix, Windows and VMS being Very Different. Note: Cygwin and OS X are
142 Unixen for our purposes.
144 - If nothing else, at least try it on two different Unixen or Windows
145 machines (ie. Linux and IRIX or WinNT and Win95).
147 - HP's TestDrive (www.testdrive.compaq.com) and SourceForge's
148 compile farm (www.sourceforge.net) are good sources of testing
149 machines of many different architectures and platforms. Accounts are
152 - If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on
153 the OS type) perhaps your code belongs in one of the non-Unix MM_*
154 modules (ie. MM_Win32, MM_VMS, etc...). If one does not exist, consider
155 creating one. Its ok to have an MM_* module with only one method.
157 - Some shells have very small buffers. This means command lines must
158 be as small as possible. If your command is just too long, consider
159 making it an ExtUtils::Command::MM function. If your command might
160 receive many arguments (such as pod2man or pm_to_blib) consider
161 using split_command() to split it into several, shorter calls.
163 - Most shells quote differently. If you need to put a perl one-liner
164 in the Makefile, please use oneliner() to generate it.
169 - Tests would be nice, but I'm not going to pretend testing MakeMaker
170 is easy. If nothing else, let us know how you tested your patch by
176 - Documentation would be nice.
178 - If the new feature/method is private, please document it with POD
179 wrapped in "=begin/end private" tags. That way it will be documented,
180 but won't be displayed (future versions of perldoc may have options
198 - If you're overriding a method, document that its an override and
199 *why* its being overridden. Don't repeat the original documentation.