212 lines
6.8 KiB
Text
212 lines
6.8 KiB
Text
"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.
|