| 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 |
|
| 74 |
subdirs :: |
| 75 |
\$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU) |
| 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 |
consider using sprintf instead. |
| 86 |
|
| 87 |
return sprintf <<'EOT', $subdir; |
| 88 |
|
| 89 |
subdirs :: |
| 90 |
$(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU) |
| 91 |
EOT |
| 92 |
|
| 93 |
|
| 94 |
Refactoring and Cleanup |
| 95 |
|
| 96 |
- MakeMaker is a mess. We like patches which clean things up. |
| 97 |
|
| 98 |
|
| 99 |
Backwards Compatibility |
| 100 |
|
| 101 |
- MakeMaker must be backwards compatible to 5.5.3 (5.005_03). Avoid any |
| 102 |
obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes |
| 103 |
open my $fh, lvalue subroutines, any new core modules, etc...). |
| 104 |
|
| 105 |
- MakeMaker should avoid having module dependencies. Avoid using modules |
| 106 |
which didn't come with 5.5.3 and avoid using features from newer |
| 107 |
versions. Sometimes this is unavoidable. |
| 108 |
|
| 109 |
|
| 110 |
Cross-Platform Compatibility |
| 111 |
|
| 112 |
- MakeMaker must work on all architectures Perl works on (see perlport.pod) |
| 113 |
and with many different versions of make. This means all Unixen |
| 114 |
(including Cygwin and MacOS X), Windows (including DOS), MacOS Classic |
| 115 |
and VMS. |
| 116 |
|
| 117 |
- Often when you patch ExtUtils::MM_Unix, similar patches must be done |
| 118 |
to the other MM_* modules. If you can, please do this extra work |
| 119 |
otherwise I have to. If you can't, that's ok. We can help. |
| 120 |
|
| 121 |
- If possible, please test your patch on two Very Different architectures. |
| 122 |
Unix, Windows, MacOS Classic and VMS being Very Different. Note: Cygwin |
| 123 |
and OS X are Unixen for our purposes. |
| 124 |
|
| 125 |
- If nothing else, at least try it on two different Unixen or Windows |
| 126 |
machines (ie. Linux and IRIX or WinNT and Win95). |
| 127 |
|
| 128 |
- HP's TestDrive (www.testdrive.compaq.com) and SourceForge's |
| 129 |
compile farm (www.sourceforge.net) are good sources of testing |
| 130 |
machines of many different architectures and platforms. Accounts are |
| 131 |
free. |
| 132 |
|
| 133 |
- If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on |
| 134 |
the OS type) perhaps your code belongs in one of the non-Unix MM_* |
| 135 |
modules (ie. MM_Win32, MM_VMS, etc...). If one does not exist, consider |
| 136 |
creating one. Its ok to have an MM_* module with only one method. |
| 137 |
|
| 138 |
- Some shells have very small buffers. This means command lines must |
| 139 |
be as small as possible. If your command is just too long, consider |
| 140 |
making it an ExtUtils::Command::MM function. If your command might |
| 141 |
receive many arguments (such as pod2man or pm_to_blib) consider |
| 142 |
using split_command() to split it into several, shorter calls. |
| 143 |
|
| 144 |
- Most shells quote differently. If you need to put a perl one-liner |
| 145 |
in the Makefile, please use oneliner() to generate it. |
| 146 |
|
| 147 |
|
| 148 |
Tests |
| 149 |
|
| 150 |
- Tests would be nice, but I'm not going to pretend testing MakeMaker |
| 151 |
is easy. If nothing else, let us know how you tested your patch by |
| 152 |
hand. |
| 153 |
|
| 154 |
|
| 155 |
Documentation |
| 156 |
|
| 157 |
- Documentation would be nice. |
| 158 |
|
| 159 |
- If the new feature/method is private, please document it with POD |
| 160 |
wrapped in "=begin/end private" tags. That way it will be documented, |
| 161 |
but won't be displayed (future versions of perldoc may have options |
| 162 |
to display). |
| 163 |
|
| 164 |
=begin private |
| 165 |
|
| 166 |
=item _foo_bar |
| 167 |
|
| 168 |
$mm->_foo_bar |
| 169 |
|
| 170 |
Blah blah blah |
| 171 |
|
| 172 |
=end private |
| 173 |
|
| 174 |
=cut |
| 175 |
|
| 176 |
sub _foo_bar { |
| 177 |
... |
| 178 |
|
| 179 |
- If you're overriding a method, document that its an override and |
| 180 |
*why* its being overridden. Don't repeat the original documentation. |
