[ViewVC] Annotation of: cvs/staticperl/perl/lib/ExtUtils/PATCHING

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.3 (5.005_03).  Avoid any
  obvious 5.6-isms (threads, warnings.pm, Unicode, our, v1.2.3, attributes
  open my $fh, lvalue subroutines, any new core modules, etc...).

- MakeMaker should avoid having module dependencies.  Avoid using modules
  which didn't come with 5.5.3 and avoid using features from newer 
  versions.  Sometimes this is unavoidable.


Cross-Platform Compatibility

- MakeMaker must work on all architectures Perl works on (see perlport.pod)
  and with many different versions of make.  This means all Unixen 
  (including Cygwin and MacOS X), Windows (including DOS), MacOS Classic 
  and VMS.  

- 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, MacOS Classic 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

    =item _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.
Revision:	1.1
Committed:	Thu Jun 30 14:27:11 2005 UTC (21 years, 3 months ago) by root
Branch:	MAIN
CVS Tags:	PERL-5-8-7, HEAD
Branch point for:	PERL
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.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.