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.
|
---|
4 |
|
---|
5 | Lots of information can be found in makemaker.org.
|
---|
6 |
|
---|
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.
|
---|
11 |
|
---|
12 |
|
---|
13 | Reporting 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 | [email protected]. 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 |
|
---|
40 | Patching 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 [email protected].
|
---|
48 |
|
---|
49 |
|
---|
50 | Code 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;
|
---|
73 | subdirs ::
|
---|
74 | \$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
|
---|
75 |
|
---|
76 | EOT
|
---|
77 |
|
---|
78 | or are switching quoting contexts:
|
---|
79 |
|
---|
80 | return q{
|
---|
81 | subdirs ::
|
---|
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;
|
---|
89 | subdirs ::
|
---|
90 | $(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
|
---|
91 |
|
---|
92 | EOT
|
---|
93 |
|
---|
94 |
|
---|
95 | Refactoring and Cleanup
|
---|
96 |
|
---|
97 | - MakeMaker is a mess. We like patches which clean things up.
|
---|
98 |
|
---|
99 |
|
---|
100 | Backwards 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 |
|
---|
111 | Cross-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 |
|
---|
167 | Tests
|
---|
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 |
|
---|
174 | Documentation
|
---|
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.
|
---|