| "The easy way is always mined. |
| The important things are always simple. |
| The simple things are always hard." |
| -- Some of Murphy's Laws of Combat |
| |
| This is a short set of guidelines for those patching |
| ExtUtils::MakeMaker. Its not an iron-clad set of rules, but just |
| things which make life easier when reading and integrating a patch. |
| |
| Lots of information can be found in makemaker.org. |
| |
| MakerMaker is being maintained until something else can replace it. |
| Bugs will be fixed and compatibility improved, but I would like to |
| avoid new features. If you want to add something to MakeMaker, |
| consider instead working on Module::Build, MakeMaker's heir apparent. |
| |
| |
| Reporting bugs |
| |
| - Often the only information we have for fixing a bug is contained in your |
| report. So... |
| |
| - Please report your bugs via http://rt.cpan.org or by mailing to |
| makemaker@perl.org. RT is preferred. |
| |
| - Please report your bug immediately upon encountering it. Do not wait |
| until you have a patch to fix the bug. Patches are good, but not at |
| the expense of timely bug reports. |
| |
| - Please be as verbose as possible. Include the complete output of |
| your 'make test' or even 'make test TEST_VERBOSE=1' and a copy of the |
| generated Makefile. Err on the side of verbosity. The more data we |
| have to work with, the faster we can diagnose the problem. |
| |
| - If you find an undocumented feature, or if a feature has changed/been |
| added which causes a problem, report it. Do not assume it was done |
| deliberately. Even if it was done deliberately, we still want to hear |
| if it caused problems. |
| |
| - If you're testing MakeMaker against a development version of Perl, |
| please also check it against the latest stable version. This makes it |
| easier to figure out if its MakeMaker or Perl at fault. |
| |
| |
| Patching details |
| |
| - Please use unified diffs. (diff -u) |
| |
| - Patches against the latest development snapshot from makemaker.org are |
| preferred. Patches against the latest CPAN version are ok, too. |
| |
| - Post your patch to makemaker@perl.org. |
| |
| |
| Code formatting |
| |
| - No literal tabs (except where necessary inside Makefile code, obviously). |
| |
| - 4 character indentation. |
| |
| - this_style is prefered instead of studlyCaps. |
| |
| - Private subroutine names (ie. those used only in the same package |
| they're declared in) should start with an underscore (_sekret_method). |
| |
| - Protected subroutines (ie. ones intended to be used by other modules in |
| ExtUtils::*) should be named normally (no leading underscore) but |
| documented as protected (see Documentation below). |
| |
| - Do not use indirect object syntax (ie. new Foo::Bar (@args)) |
| |
| - make variables use dollar signs like Perl scalars. This causes problems |
| when you have to mix them both in a string. If you find yourself |
| backwacking lots of dollar signs because you have one interpolated |
| perl variable, like this: |
| |
| return <<EOT; |
| subdirs :: |
| \$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU) |
| |
| EOT |
| |
| or are switching quoting contexts: |
| |
| return q{ |
| subdirs :: |
| $(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU) |
| |
| }; |
| |
| consider using sprintf instead. |
| |
| return sprintf <<'EOT', $subdir; |
| subdirs :: |
| $(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU) |
| |
| EOT |
| |
| |
| Refactoring and Cleanup |
| |
| - MakeMaker is a mess. We like patches which clean things up. |
| |
| |
| Backwards Compatibility |
| |
| - MakeMaker must be backwards compatible to 5.5.4 (5.005_04). Avoid any |
| obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes |
| open my $fh, lvalue subroutines, qr//, any new core modules, etc...). |
| |
| - MakeMaker should avoid having module dependencies. Avoid using modules |
| which didn't come with 5.5.4 and avoid using features from newer |
| versions. Sometimes this is unavoidable. |
| |
| |
| Cross-Platform Compatibility |
| |
| - With the exception of MacOS Classic, MakeMaker must work on all |
| architectures Perl works on (see perlport.pod). This means all Unixen |
| (including Cygwin and MacOS X), Windows (including Win9x and DOS), and VMS. |
| |
| - Use the available macros rather than shell commands $(MV), $(CP), |
| $(TOUCH), etc... |
| |
| - MakeMaker must work on many makes. GNU, BSD, Solaris, nmake, dmake, MMS |
| and MMK to name the most common. Keep your make code as simple as |
| possible. |
| |
| - Avoid special make variables (even $@). |
| |
| - Format targets as "target : dependency", the spacing is important. |
| |
| - Use $(NOECHO) instead of @. |
| |
| - Use - to tell make to ignore the exit code of a command. (Unfortunately, |
| some make variants don't honor an $(IGNORE) macro). |
| |
| - Always put a space between $(NOECHO) and the command. |
| |
| - Always put a space between - (ignore) and the command. |
| |
| - Always put $(NOECHO) and - together, no space between them. |
| |
| # Right |
| -$(NOECHO) command |
| $(NOECHO) command |
| - command |
| |
| - Often when you patch ExtUtils::MM_Unix, similar patches must be done |
| to the other MM_* modules. If you can, please do this extra work |
| otherwise I have to. If you can't, that's ok. We can help. |
| |
| - If possible, please test your patch on two Very Different architectures. |
| Unix, Windows and VMS being Very Different. Note: Cygwin and OS X are |
| Unixen for our purposes. |
| |
| - If nothing else, at least try it on two different Unixen or Windows |
| machines (ie. Linux and IRIX or WinNT and Win95). |
| |
| - HP's TestDrive (www.testdrive.compaq.com) and SourceForge's |
| compile farm (www.sourceforge.net) are good sources of testing |
| machines of many different architectures and platforms. Accounts are |
| free. |
| |
| - If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on |
| the OS type) perhaps your code belongs in one of the non-Unix MM_* |
| modules (ie. MM_Win32, MM_VMS, etc...). If one does not exist, consider |
| creating one. Its ok to have an MM_* module with only one method. |
| |
| - Some shells have very small buffers. This means command lines must |
| be as small as possible. If your command is just too long, consider |
| making it an ExtUtils::Command::MM function. If your command might |
| receive many arguments (such as pod2man or pm_to_blib) consider |
| using split_command() to split it into several, shorter calls. |
| |
| - Most shells quote differently. If you need to put a perl one-liner |
| in the Makefile, please use oneliner() to generate it. |
| |
| |
| Tests |
| |
| - Tests would be nice, but I'm not going to pretend testing MakeMaker |
| is easy. If nothing else, let us know how you tested your patch by |
| hand. |
| |
| |
| Documentation |
| |
| - Documentation would be nice. |
| |
| - If the new feature/method is private, please document it with POD |
| wrapped in "=begin/end private" tags. That way it will be documented, |
| but won't be displayed (future versions of perldoc may have options |
| to display). |
| |
| =begin private |
| |
| =head3 _foo_bar |
| |
| $mm->_foo_bar |
| |
| Blah blah blah |
| |
| =end private |
| |
| =cut |
| |
| sub _foo_bar { |
| ... |
| |
| - If you're overriding a method, document that its an override and |
| *why* its being overridden. Don't repeat the original documentation. |
