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