Commit | Line | Data |
2977d345 |
1 | "The easy way is always mined. |
2 | The important things are always simple. |
3 | The simple things are always hard." |
4 | -- Some of Murphy's Laws of Combat |
5 | |
479d2113 |
6 | This is a short set of guidelines for those patching |
7 | ExtUtils::MakeMaker. Its not an iron-clad set of rules, but just |
8 | things which make life easier when reading and integrating a patch. |
9 | |
10 | Lots of information can be found in makemaker.org. |
11 | |
12 | MakerMaker is being maintained until something else can replace it. |
13 | Bugs will be fixed and compatibility improved, but I would like to |
14 | avoid new features. If you want to add something to MakeMaker, |
15 | consider instead working on Module::Build, MakeMaker's heir apparent. |
16 | |
17 | |
dedf98bc |
18 | Reporting bugs |
19 | |
20 | - Often the only information we have for fixing a bug is contained in your |
21 | report. So... |
22 | |
23 | - Please report your bugs via http://rt.cpan.org or by mailing to |
24 | makemaker@perl.org. RT is preferred. |
25 | |
26 | - Please report your bug immediately upon encountering it. Do not wait |
27 | until you have a patch to fix the bug. Patches are good, but not at |
28 | the expense of timely bug reports. |
29 | |
30 | - Please be as verbose as possible. Include the complete output of |
31 | your 'make test' or even 'make test TEST_VERBOSE=1' and a copy of the |
32 | generated Makefile. Err on the side of verbosity. The more data we |
33 | have to work with, the faster we can diagnose the problem. |
34 | |
35 | - If you find an undocumented feature, or if a feature has changed/been |
36 | added which causes a problem, report it. Do not assume it was done |
37 | deliberately. Even if it was done deliberately, we still want to hear |
38 | if it caused problems. |
39 | |
5e719f03 |
40 | - If you're testing MakeMaker against a development version of Perl, |
41 | please also check it against the latest stable version. This makes it |
42 | easier to figure out if its MakeMaker or Perl at fault. |
43 | |
dedf98bc |
44 | |
479d2113 |
45 | Patching details |
46 | |
47 | - Please use unified diffs. (diff -u) |
48 | |
49 | - Patches against the latest development snapshot from makemaker.org are |
50 | preferred. Patches against the latest CPAN version are ok, too. |
51 | |
52 | - Post your patch to makemaker@perl.org. |
53 | |
54 | |
55 | Code formatting |
56 | |
57 | - No literal tabs (except where necessary inside Makefile code, obviously). |
58 | |
59 | - 4 character indentation. |
60 | |
61 | - this_style is prefered instead of studlyCaps. |
62 | |
63 | - Private subroutine names (ie. those used only in the same package |
64 | they're declared in) should start with an underscore (_sekret_method). |
65 | |
66 | - Protected subroutines (ie. ones intended to be used by other modules in |
67 | ExtUtils::*) should be named normally (no leading underscore) but |
68 | documented as protected (see Documentation below). |
69 | |
70 | - Do not use indirect object syntax (ie. new Foo::Bar (@args)) |
71 | |
72 | - make variables use dollar signs like Perl scalars. This causes problems |
73 | when you have to mix them both in a string. If you find yourself |
74 | backwacking lots of dollar signs because you have one interpolated |
75 | perl variable, like this: |
76 | |
7292dc67 |
77 | return <<EOT; |
479d2113 |
78 | subdirs :: |
79 | \$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU) |
7292dc67 |
80 | |
479d2113 |
81 | EOT |
82 | |
83 | or are switching quoting contexts: |
84 | |
7292dc67 |
85 | return q{ |
479d2113 |
86 | subdirs :: |
87 | $(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU) |
7292dc67 |
88 | |
479d2113 |
89 | }; |
90 | |
91 | consider using sprintf instead. |
92 | |
93 | return sprintf <<'EOT', $subdir; |
479d2113 |
94 | subdirs :: |
95 | $(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU) |
7292dc67 |
96 | |
479d2113 |
97 | EOT |
98 | |
99 | |
100 | Refactoring and Cleanup |
101 | |
102 | - MakeMaker is a mess. We like patches which clean things up. |
103 | |
104 | |
105 | Backwards Compatibility |
106 | |
7292dc67 |
107 | - MakeMaker must be backwards compatible to 5.5.4 (5.005_04). Avoid any |
479d2113 |
108 | obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes |
109 | open my $fh, lvalue subroutines, any new core modules, etc...). |
110 | |
111 | - MakeMaker should avoid having module dependencies. Avoid using modules |
7292dc67 |
112 | which didn't come with 5.5.4 and avoid using features from newer |
479d2113 |
113 | versions. Sometimes this is unavoidable. |
114 | |
115 | |
116 | Cross-Platform Compatibility |
117 | |
7292dc67 |
118 | - With the exception of MacOS Classic, MakeMaker must work on all |
119 | architectures Perl works on (see perlport.pod). This means all Unixen |
120 | (including Cygwin and MacOS X), Windows (including Win9x and DOS), and VMS. |
121 | |
122 | - Use the available macros rather than shell commands $(MV), $(CP), |
123 | $(TOUCH), etc... |
124 | |
125 | - MakeMaker must work on many makes. GNU, BSD, Solaris, nmake, dmake, MMS |
126 | and MMK to name the most common. Keep your make code as simple as |
127 | possible. |
128 | |
129 | - Avoid special variables (even $@). |
130 | |
131 | - Format targets as "target : dependency", the spacing is important. |
132 | |
133 | - Use $(NOECHO) instead of @. |
134 | |
2977d345 |
135 | - Use - to tell make to ignore the exit code of a command. (Unfortunately, |
136 | some make variants don't honor an $(IGNORE) macro). |
137 | |
7292dc67 |
138 | - Always put a space between $(NOECHO) and the command. |
139 | |
140 | - Always put a space between - (ignore) and the command. |
141 | |
142 | - Always put $(NOECHO) and - together, no space between them. |
479d2113 |
143 | |
2977d345 |
144 | # Right |
145 | -$(NOECHO) command |
146 | $(NOECHO) command |
147 | - command |
148 | |
479d2113 |
149 | - Often when you patch ExtUtils::MM_Unix, similar patches must be done |
150 | to the other MM_* modules. If you can, please do this extra work |
151 | otherwise I have to. If you can't, that's ok. We can help. |
152 | |
153 | - If possible, please test your patch on two Very Different architectures. |
7292dc67 |
154 | Unix, Windows and VMS being Very Different. Note: Cygwin and OS X are |
155 | Unixen for our purposes. |
479d2113 |
156 | |
157 | - If nothing else, at least try it on two different Unixen or Windows |
158 | machines (ie. Linux and IRIX or WinNT and Win95). |
159 | |
160 | - HP's TestDrive (www.testdrive.compaq.com) and SourceForge's |
161 | compile farm (www.sourceforge.net) are good sources of testing |
162 | machines of many different architectures and platforms. Accounts are |
163 | free. |
164 | |
165 | - If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on |
166 | the OS type) perhaps your code belongs in one of the non-Unix MM_* |
167 | modules (ie. MM_Win32, MM_VMS, etc...). If one does not exist, consider |
168 | creating one. Its ok to have an MM_* module with only one method. |
169 | |
170 | - Some shells have very small buffers. This means command lines must |
dedf98bc |
171 | be as small as possible. If your command is just too long, consider |
172 | making it an ExtUtils::Command::MM function. If your command might |
173 | receive many arguments (such as pod2man or pm_to_blib) consider |
174 | using split_command() to split it into several, shorter calls. |
479d2113 |
175 | |
176 | - Most shells quote differently. If you need to put a perl one-liner |
177 | in the Makefile, please use oneliner() to generate it. |
178 | |
179 | |
180 | Tests |
181 | |
182 | - Tests would be nice, but I'm not going to pretend testing MakeMaker |
183 | is easy. If nothing else, let us know how you tested your patch by |
184 | hand. |
185 | |
186 | |
187 | Documentation |
188 | |
189 | - Documentation would be nice. |
190 | |
191 | - If the new feature/method is private, please document it with POD |
192 | wrapped in "=begin/end private" tags. That way it will be documented, |
193 | but won't be displayed (future versions of perldoc may have options |
194 | to display). |
195 | |
196 | =begin private |
197 | |
7292dc67 |
198 | =head3 _foo_bar |
479d2113 |
199 | |
200 | $mm->_foo_bar |
201 | |
202 | Blah blah blah |
203 | |
204 | =end private |
205 | |
206 | =cut |
207 | |
208 | sub _foo_bar { |
209 | ... |
210 | |
211 | - If you're overriding a method, document that its an override and |
212 | *why* its being overridden. Don't repeat the original documentation. |