Commit | Line | Data |
479d2113 |
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. |