Commit | Line | Data |
---|---|---|
920dae64 AT |
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 | 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 | ||
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 makemaker@perl.org. | |
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. |