1This is a short set of guidelines for those patching
2ExtUtils::MakeMaker.  Its not an iron-clad set of rules, but just
3things which make life easier when reading and integrating a patch.
4
5Lots of information can be found in makemaker.org.
6
7MakerMaker is being maintained until something else can replace it.
8Bugs will be fixed and compatibility improved, but I would like to
9avoid new features.  If you want to add something to MakeMaker,
10consider instead working on Module::Build, MakeMaker's heir apparent.
11
12
13Reporting bugs
14
15- Often the only information we have for fixing a bug is contained in your
16  report.  So...
17
18- Please report your bugs via http://rt.cpan.org or by mailing to
19  makemaker@perl.org.  RT is preferred.
20
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.
24
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.
29
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.
34
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.
38
39
40Patching details
41
42- Please use unified diffs.  (diff -u)
43
44- Patches against the latest development snapshot from makemaker.org are
45  preferred.  Patches against the latest CPAN version are ok, too.
46
47- Post your patch to makemaker@perl.org.
48
49
50Code formatting
51
52- No literal tabs (except where necessary inside Makefile code, obviously).
53
54- 4 character indentation.
55
56- this_style is prefered instead of studlyCaps.
57
58- Private subroutine names (ie. those used only in the same package
59  they're declared in) should start with an underscore (_sekret_method).
60
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).
64
65- Do not use indirect object syntax (ie. new Foo::Bar (@args))
66
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:
71
72    return <<EOT;
73subdirs ::
74	\$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
75
76EOT
77
78  or are switching quoting contexts:
79
80    return q{
81subdirs ::
82	$(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
83
84};
85
86  consider using sprintf instead.
87
88    return sprintf <<'EOT', $subdir;
89subdirs ::
90	$(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
91
92EOT
93
94
95Refactoring and Cleanup
96
97- MakeMaker is a mess.  We like patches which clean things up.
98
99
100Backwards Compatibility
101
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...).
105
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.
109
110
111Cross-Platform Compatibility
112
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.
116
117- Use the available macros rather than shell commands $(MV), $(CP),
118  $(TOUCH), etc...
119
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
122  possible.
123
124- Avoid special variables (even $@).
125
126- Format targets as "target : dependency", the spacing is important.
127
128- Use $(NOECHO) instead of @.
129
130- Always put a space between $(NOECHO) and the command.
131
132- Always put a space between - (ignore) and the command.
133
134- Always put $(NOECHO) and - together, no space between them.
135
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.
139
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.
143
144- If nothing else, at least try it on two different Unixen or Windows
145  machines (ie. Linux and IRIX or WinNT and Win95).
146
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
150  free.
151
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.
156
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.
162
163- Most shells quote differently.  If you need to put a perl one-liner
164  in the Makefile, please use oneliner() to generate it.
165
166
167Tests
168
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
171  hand.
172
173
174Documentation
175
176- Documentation would be nice.
177
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
181  to display).
182
183    =begin private
184
185    =head3 _foo_bar
186
187       $mm->_foo_bar
188
189    Blah blah blah
190
191    =end private
192
193    =cut
194
195    sub _foo_bar {
196       ...
197
198- If you're overriding a method, document that its an override and
199  *why* its being overridden.  Don't repeat the original documentation.
200