home *** CD-ROM | disk | FTP | other *** search
/ Netrunner 2004 October / NETRUNNER0410.ISO / regular / ActivePerl-5.8.4.810-MSWin32-x86.msi / _7fee91f3448dc056fb3bf6eb82e99ef0 < prev    next >
Encoding:
Text File  |  2004-06-01  |  6.1 KB  |  181 lines
  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.
  181.