schwern / extutils-makemaker

Perl module which drives "perl Makefile.PL" to make Makefiles.

This URL has Read+Write access

extutils-makemaker / PATCHING
raw normal view history
e63a6a2e » schwern 2005-07-23 r2454@windhund: schwern |... 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
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 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
4ba4dab2 » schwern 2002-11-19 Added notes about accepting... 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
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 17
1788c597 » schwern 2003-04-02 Adding "Reporting Bugs" sec... 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
4f215a27 » schwern 2003-07-21 Mentioning about testing ag... 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
1788c597 » schwern 2003-04-02 Adding "Reporting Bugs" sec... 44
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 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
ffd711d9 » schwern 2002-11-12 Noting that I hate indirect... 70 - Do not use indirect object syntax (ie. new Foo::Bar (@args))
71
b7528b73 » schwern 2002-11-13 Noting sprintf/here-doc trick. 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
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 77 return <<EOT;
b7528b73 » schwern 2002-11-13 Noting sprintf/here-doc trick. 78 subdirs ::
79 \$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 80
b7528b73 » schwern 2002-11-13 Noting sprintf/here-doc trick. 81 EOT
82
4ba4dab2 » schwern 2002-11-19 Added notes about accepting... 83 or are switching quoting contexts:
84
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 85 return q{
4ba4dab2 » schwern 2002-11-19 Added notes about accepting... 86 subdirs ::
87 $(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 88
4ba4dab2 » schwern 2002-11-19 Added notes about accepting... 89 };
90
b7528b73 » schwern 2002-11-13 Noting sprintf/here-doc trick. 91 consider using sprintf instead.
92
93 return sprintf <<'EOT', $subdir;
94 subdirs ::
95 $(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 96
b7528b73 » schwern 2002-11-13 Noting sprintf/here-doc trick. 97 EOT
98
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 99
100 Refactoring and Cleanup
101
102 - MakeMaker is a mess. We like patches which clean things up.
103
104
105 Backwards Compatibility
106
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 107 - MakeMaker must be backwards compatible to 5.5.4 (5.005_04). Avoid any
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 108 obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes
681e1ff5 » schwern 2006-09-11 r18085@Master-Windhund-IV:... 109 open my $fh, lvalue subroutines, qr//, any new core modules, etc...).
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 110
111 - MakeMaker should avoid having module dependencies. Avoid using modules
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 112 which didn't come with 5.5.4 and avoid using features from newer
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 113 versions. Sometimes this is unavoidable.
114
115
116 Cross-Platform Compatibility
117
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 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
5ff09b5c » schwern 2004-12-30 - No longer using $(IGN... 127 possible.
128
681e1ff5 » schwern 2006-09-11 r18085@Master-Windhund-IV:... 129 - Avoid special make variables (even $@).
5ff09b5c » schwern 2004-12-30 - No longer using $(IGN... 130
131 - Format targets as "target : dependency", the spacing is important.
132
133 - Use $(NOECHO) instead of @.
134
ed489084 » schwern 2005-07-23 r2455@windhund: schwern |... 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
5ff09b5c » schwern 2004-12-30 - No longer using $(IGN... 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.
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 143
ed489084 » schwern 2005-07-23 r2455@windhund: schwern |... 144 # Right
145 -$(NOECHO) command
146 $(NOECHO) command
147 - command
148
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 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.
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 154 Unix, Windows and VMS being Very Different. Note: Cygwin and OS X are
155 Unixen for our purposes.
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 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
1788c597 » schwern 2003-04-02 Adding "Reporting Bugs" sec... 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.
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 175
4ba4dab2 » schwern 2002-11-19 Added notes about accepting... 176 - Most shells quote differently. If you need to put a perl one-liner
c732ae3a » schwern 2002-11-25 Changing perl_oneliner() to... 177 in the Makefile, please use oneliner() to generate it.
4ba4dab2 » schwern 2002-11-19 Added notes about accepting... 178
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 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
f0a9a2a6 » schwern 2004-12-25 r4135@windhund: schwern |... 198 =head3 _foo_bar
bfd891ee » schwern 2002-11-12 Adding a PATCHING guideline... 199
200 $mm->_foo_bar
201
202 Blah blah blah
203
204 =end private
205
206 =cut
207
208 sub _foo_bar {
209 ...
4ba4dab2 » schwern 2002-11-19 Added notes about accepting... 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.