lib/ExtUtils/PATCHING

   1 "The easy way is always mined.
   2  The important things are always simple.
   3  The simple things are always hard."
   4         -- Some of Murphy's Laws of Combat
   5
   6 This is a short set of guidelines for those patching
   7 ExtUtils::MakeMaker.  Its not an iron-clad set of rules, but just
   8 things which make life easier when reading and integrating a patch.
   9
  10 Lots of information can be found in makemaker.org.
  11
  12 MakerMaker is being maintained until something else can replace it.
  13 Bugs will be fixed and compatibility improved, but I would like to
  14 avoid new features.  If you want to add something to MakeMaker,
  15 consider instead working on Module::Build, MakeMaker's heir apparent.
  16
  17
  18 Reporting bugs
  19
  20 - Often the only information we have for fixing a bug is contained in your
  21   report.  So...
  22
  23 - Please report your bugs via http://rt.cpan.org or by mailing to
  24   makemaker@perl.org.  RT is preferred.
  25
  26 - Please report your bug immediately upon encountering it.  Do not wait
  27   until you have a patch to fix the bug.  Patches are good, but not at
  28   the expense of timely bug reports.
  29
  30 - Please be as verbose as possible.  Include the complete output of
  31   your 'make test' or even 'make test TEST_VERBOSE=1' and a copy of the
  32   generated Makefile.  Err on the side of verbosity.  The more data we
  33   have to work with, the faster we can diagnose the problem.
  34
  35 - If you find an undocumented feature, or if a feature has changed/been
  36   added which causes a problem, report it.  Do not assume it was done
  37   deliberately.  Even if it was done deliberately, we still want to hear
  38   if it caused problems.
  39
  40 - If you're testing MakeMaker against a development version of Perl,
  41   please also check it against the latest stable version.  This makes it
  42   easier to figure out if its MakeMaker or Perl at fault.
  43
  44
  45 Patching details
  46
  47 - Please use unified diffs.  (diff -u)
  48
  49 - Patches against the latest development snapshot from makemaker.org are
  50   preferred.  Patches against the latest CPAN version are ok, too.
  51
  52 - Post your patch to makemaker@perl.org.
  53
  54
  55 Code formatting
  56
  57 - No literal tabs (except where necessary inside Makefile code, obviously).
  58
  59 - 4 character indentation.
  60
  61 - this_style is prefered instead of studlyCaps.
  62
  63 - Private subroutine names (ie. those used only in the same package
  64   they're declared in) should start with an underscore (_sekret_method).
  65
  66 - Protected subroutines (ie. ones intended to be used by other modules in
  67   ExtUtils::*) should be named normally (no leading underscore) but
  68   documented as protected (see Documentation below).
  69
  70 - Do not use indirect object syntax (ie. new Foo::Bar (@args))
  71
  72 - make variables use dollar signs like Perl scalars.  This causes problems
  73   when you have to mix them both in a string.  If you find yourself
  74   backwacking lots of dollar signs because you have one interpolated
  75   perl variable, like this:
  76
  77     return <<EOT;
  78 subdirs ::
  79         \$(NOECHO)cd $subdir && \$(MAKE) -f \$(FIRST_MAKEFILE) all \$(PASTHRU)
  80
  81 EOT
  82
  83   or are switching quoting contexts:
  84
  85     return q{
  86 subdirs ::
  87         $(NOECHO)cd }.$subdir.q{ && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
  88
  89 };
  90
  91   consider using sprintf instead.
  92
  93     return sprintf <<'EOT', $subdir;
  94 subdirs ::
  95         $(NOECHO)cd %s && $(MAKE) -f $(FIRST_MAKEFILE) all $(PASTHRU)
  96
  97 EOT
  98
  99
 100 Refactoring and Cleanup
 101
 102 - MakeMaker is a mess.  We like patches which clean things up.
 103
 104
 105 Backwards Compatibility
 106
 107 - MakeMaker must be backwards compatible to 5.5.4 (5.005_04).  Avoid any
 108   obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes
 109   open my $fh, lvalue subroutines, any new core modules, etc...).
 110
 111 - MakeMaker should avoid having module dependencies.  Avoid using modules
 112   which didn't come with 5.5.4 and avoid using features from newer
 113   versions.  Sometimes this is unavoidable.
 114
 115
 116 Cross-Platform Compatibility
 117
 118 - With the exception of MacOS Classic, MakeMaker must work on all
 119   architectures Perl works on (see perlport.pod).  This means all Unixen
 120   (including Cygwin and MacOS X), Windows (including Win9x and DOS), and VMS.
 121
 122 - Use the available macros rather than shell commands $(MV), $(CP),
 123   $(TOUCH), etc...
 124
 125 - MakeMaker must work on many makes.  GNU, BSD, Solaris, nmake, dmake, MMS
 126   and MMK to name the most common.  Keep your make code as simple as
 127   possible.
 128
 129 - Avoid special variables (even $@).
 130
 131 - Format targets as "target : dependency", the spacing is important.
 132
 133 - Use $(NOECHO) instead of @.
 134
 135 - Use - to tell make to ignore the exit code of a command.  (Unfortunately,
 136   some make variants don't honor an $(IGNORE) macro).
 137
 138 - Always put a space between $(NOECHO) and the command.
 139
 140 - Always put a space between - (ignore) and the command.
 141
 142 - Always put $(NOECHO) and - together, no space between them.
 143
 144         # Right
 145         -$(NOECHO) command
 146         $(NOECHO) command
 147         - command
 148
 149 - Often when you patch ExtUtils::MM_Unix, similar patches must be done
 150   to the other MM_* modules.  If you can, please do this extra work
 151   otherwise I have to.  If you can't, that's ok.  We can help.
 152
 153 - If possible, please test your patch on two Very Different architectures.
 154   Unix, Windows and VMS being Very Different.  Note: Cygwin and OS X are
 155   Unixen for our purposes.
 156
 157 - If nothing else, at least try it on two different Unixen or Windows
 158   machines (ie. Linux and IRIX or WinNT and Win95).
 159
 160 - HP's TestDrive (www.testdrive.compaq.com) and SourceForge's
 161   compile farm (www.sourceforge.net) are good sources of testing
 162   machines of many different architectures and platforms.  Accounts are
 163   free.
 164
 165 - If you find yourself writing "do_this if $^O eq 'That'" (ie. checks on
 166   the OS type) perhaps your code belongs in one of the non-Unix MM_*
 167   modules (ie. MM_Win32, MM_VMS, etc...).  If one does not exist, consider
 168   creating one.  Its ok to have an MM_* module with only one method.
 169
 170 - Some shells have very small buffers.  This means command lines must
 171   be as small as possible.  If your command is just too long, consider
 172   making it an ExtUtils::Command::MM function.  If your command might
 173   receive many arguments (such as pod2man or pm_to_blib) consider
 174   using split_command() to split it into several, shorter calls.
 175
 176 - Most shells quote differently.  If you need to put a perl one-liner
 177   in the Makefile, please use oneliner() to generate it.
 178
 179
 180 Tests
 181
 182 - Tests would be nice, but I'm not going to pretend testing MakeMaker
 183   is easy.  If nothing else, let us know how you tested your patch by
 184   hand.
 185
 186
 187 Documentation
 188
 189 - Documentation would be nice.
 190
 191 - If the new feature/method is private, please document it with POD
 192   wrapped in "=begin/end private" tags.  That way it will be documented,
 193   but won't be displayed (future versions of perldoc may have options
 194   to display).
 195
 196     =begin private
 197
 198     =head3 _foo_bar
 199
 200        $mm->_foo_bar
 201
 202     Blah blah blah
 203
 204     =end private
 205
 206     =cut
 207
 208     sub _foo_bar {
 209        ...
 210
 211 - If you're overriding a method, document that its an override and
 212   *why* its being overridden.  Don't repeat the original documentation.