lib/ExtUtils/PATCHING

   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 Patching details
  14
  15 - Please use unified diffs.  (diff -u)
  16
  17 - Patches against the latest development snapshot from makemaker.org are
  18   preferred.  Patches against the latest CPAN version are ok, too.
  19
  20 - Post your patch to makemaker@perl.org.
  21
  22
  23 Code formatting
  24
  25 - No literal tabs (except where necessary inside Makefile code, obviously).
  26
  27 - 4 character indentation.
  28
  29 - this_style is prefered instead of studlyCaps.
  30
  31 - Private subroutine names (ie. those used only in the same package
  32   they're declared in) should start with an underscore (_sekret_method).
  33
  34 - Protected subroutines (ie. ones intended to be used by other modules in
  35   ExtUtils::*) should be named normally (no leading underscore) but
  36   documented as protected (see Documentation below).
  37
  38 - Do not use indirect object syntax (ie. new Foo::Bar (@args))
  39
  40 - make variables use dollar signs like Perl scalars.  This causes problems
  41   when you have to mix them both in a string.  If you find yourself
  42   backwacking lots of dollar signs because you have one interpolated
  43   perl variable, like this:
  44
  45     return <<'EOT'
  46
  47 subdirs ::
  48         \$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
  49 EOT
  50
  51   or are switching quoting contexts:
  52
  53     return <<q{
  54 subdirs ::
  55         $(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
  56 };
  57
  58   consider using sprintf instead.
  59
  60     return sprintf <<'EOT', $subdir;
  61
  62 subdirs ::
  63         $(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
  64 EOT
  65
  66
  67 Refactoring and Cleanup
  68
  69 - MakeMaker is a mess.  We like patches which clean things up.
  70
  71
  72 Backwards Compatibility
  73
  74 - MakeMaker must be backwards compatible to 5.5.3 (5.005_03).  Avoid any
  75   obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes
  76   open my $fh, lvalue subroutines, any new core modules, etc...).
  77
  78 - MakeMaker should avoid having module dependencies.  Avoid using modules
  79   which didn't come with 5.5.3 and avoid using features from newer
  80   versions.  Sometimes this is unavoidable.
  81
  82
  83 Cross-Platform Compatibility
  84
  85 - MakeMaker must work on all architectures Perl works on (see perlport.pod)
  86   and with many different versions of make.  This means all Unixen
  87   (including Cygwin and MacOS X), Windows (including DOS), MacOS Classic
  88   and VMS.
  89
  90 - Often when you patch ExtUtils::MM_Unix, similar patches must be done
  91   to the other MM_* modules.  If you can, please do this extra work
  92   otherwise I have to.  If you can't, that's ok.  We can help.
  93
  94 - If possible, please test your patch on two Very Different architectures.
  95   Unix, Windows, MacOS Classic and VMS being Very Different.  Note: Cygwin
  96   and OS X are Unixen for our purposes.
  97
  98 - If nothing else, at least try it on two different Unixen or Windows
  99   machines (ie. Linux and IRIX or WinNT and Win95).
 100
 101 - HP's TestDrive (www.testdrive.compaq.com) and SourceForge's
 102   compile farm (www.sourceforge.net) are good sources of testing
 103   machines of many different architectures and platforms.  Accounts are
 104   free.
 105
 106 - If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on
 107   the OS type) perhaps your code belongs in one of the non-Unix MM_*
 108   modules (ie. MM_Win32, MM_VMS, etc...).  If one does not exist, consider
 109   creating one.  Its ok to have an MM_* module with only one method.
 110
 111 - Some shells have very small buffers.  This means command lines must
 112   be as small as possible.  20K is the upper limit for Unixen, and 256
 113   for VMS.  Not sure what Windows and DOS are limited to, probably 1K.
 114   This limit *includes* any files passed into it.  Some modules (such as
 115   bioperl) generate enourmous commands because of their large number of
 116   files.  If your command is just too long, consider making it an
 117   ExtUtils::Command::MM function.
 118
 119 - Most shells quote differently.  If you need to put a perl one-liner
 120   in the Makefile, please use oneliner() to generate it.
 121
 122
 123 Tests
 124
 125 - Tests would be nice, but I'm not going to pretend testing MakeMaker
 126   is easy.  If nothing else, let us know how you tested your patch by
 127   hand.
 128
 129
 130 Documentation
 131
 132 - Documentation would be nice.
 133
 134 - If the new feature/method is private, please document it with POD
 135   wrapped in "=begin/end private" tags.  That way it will be documented,
 136   but won't be displayed (future versions of perldoc may have options
 137   to display).
 138
 139     =begin private
 140
 141     =item _foo_bar
 142
 143        $mm->_foo_bar
 144
 145     Blah blah blah
 146
 147     =end private
 148
 149     =cut
 150
 151     sub _foo_bar {
 152        ...
 153
 154 - If you're overriding a method, document that its an override and
 155   *why* its being overridden.  Don't repeat the original documentation.