Commit | Line | Data |
---|---|---|
e8cd7eae GS |
1 | =head1 NAME |
2 | ||
3 | perlhack - How to hack at the Perl internals | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | This document attempts to explain how Perl development takes place, | |
8 | and ends with some suggestions for people wanting to become bona fide | |
9 | porters. | |
10 | ||
11 | The perl5-porters mailing list is where the Perl standard distribution | |
12 | is maintained and developed. The list can get anywhere from 10 to 150 | |
13 | messages a day, depending on the heatedness of the debate. Most days | |
14 | there are two or three patches, extensions, features, or bugs being | |
15 | discussed at a time. | |
16 | ||
17 | A searchable archive of the list is at: | |
18 | ||
19 | http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/ | |
20 | ||
21 | The list is also archived under the usenet group name | |
22 | C<perl.porters-gw> at: | |
23 | ||
24 | http://www.deja.com/ | |
25 | ||
26 | List subscribers (the porters themselves) come in several flavours. | |
27 | Some are quiet curious lurkers, who rarely pitch in and instead watch | |
28 | the ongoing development to ensure they're forewarned of new changes or | |
29 | features in Perl. Some are representatives of vendors, who are there | |
30 | to make sure that Perl continues to compile and work on their | |
31 | platforms. Some patch any reported bug that they know how to fix, | |
32 | some are actively patching their pet area (threads, Win32, the regexp | |
33 | engine), while others seem to do nothing but complain. In other | |
34 | words, it's your usual mix of technical people. | |
35 | ||
36 | Over this group of porters presides Larry Wall. He has the final word | |
f6c51b38 GS |
37 | in what does and does not change in the Perl language. Various |
38 | releases of Perl are shepherded by a ``pumpking'', a porter | |
39 | responsible for gathering patches, deciding on a patch-by-patch | |
40 | feature-by-feature basis what will and will not go into the release. | |
41 | For instance, Gurusamy Sarathy is the pumpking for the 5.6 release of | |
42 | Perl. | |
e8cd7eae GS |
43 | |
44 | In addition, various people are pumpkings for different things. For | |
45 | instance, Andy Dougherty and Jarkko Hietaniemi share the I<Configure> | |
46 | pumpkin, and Tom Christiansen is the documentation pumpking. | |
47 | ||
48 | Larry sees Perl development along the lines of the US government: | |
49 | there's the Legislature (the porters), the Executive branch (the | |
50 | pumpkings), and the Supreme Court (Larry). The legislature can | |
51 | discuss and submit patches to the executive branch all they like, but | |
52 | the executive branch is free to veto them. Rarely, the Supreme Court | |
53 | will side with the executive branch over the legislature, or the | |
54 | legislature over the executive branch. Mostly, however, the | |
55 | legislature and the executive branch are supposed to get along and | |
56 | work out their differences without impeachment or court cases. | |
57 | ||
58 | You might sometimes see reference to Rule 1 and Rule 2. Larry's power | |
59 | as Supreme Court is expressed in The Rules: | |
60 | ||
61 | =over 4 | |
62 | ||
63 | =item 1 | |
64 | ||
65 | Larry is always by definition right about how Perl should behave. | |
66 | This means he has final veto power on the core functionality. | |
67 | ||
68 | =item 2 | |
69 | ||
70 | Larry is allowed to change his mind about any matter at a later date, | |
71 | regardless of whether he previously invoked Rule 1. | |
72 | ||
73 | =back | |
74 | ||
75 | Got that? Larry is always right, even when he was wrong. It's rare | |
76 | to see either Rule exercised, but they are often alluded to. | |
77 | ||
78 | New features and extensions to the language are contentious, because | |
79 | the criteria used by the pumpkings, Larry, and other porters to decide | |
80 | which features should be implemented and incorporated are not codified | |
81 | in a few small design goals as with some other languages. Instead, | |
82 | the heuristics are flexible and often difficult to fathom. Here is | |
83 | one person's list, roughly in decreasing order of importance, of | |
84 | heuristics that new features have to be weighed against: | |
85 | ||
86 | =over 4 | |
87 | ||
88 | =item Does concept match the general goals of Perl? | |
89 | ||
90 | These haven't been written anywhere in stone, but one approximation | |
91 | is: | |
92 | ||
93 | 1. Keep it fast, simple, and useful. | |
94 | 2. Keep features/concepts as orthogonal as possible. | |
95 | 3. No arbitrary limits (platforms, data sizes, cultures). | |
96 | 4. Keep it open and exciting to use/patch/advocate Perl everywhere. | |
97 | 5. Either assimilate new technologies, or build bridges to them. | |
98 | ||
99 | =item Where is the implementation? | |
100 | ||
101 | All the talk in the world is useless without an implementation. In | |
102 | almost every case, the person or people who argue for a new feature | |
103 | will be expected to be the ones who implement it. Porters capable | |
104 | of coding new features have their own agendas, and are not available | |
105 | to implement your (possibly good) idea. | |
106 | ||
107 | =item Backwards compatibility | |
108 | ||
109 | It's a cardinal sin to break existing Perl programs. New warnings are | |
110 | contentious--some say that a program that emits warnings is not | |
111 | broken, while others say it is. Adding keywords has the potential to | |
112 | break programs, changing the meaning of existing token sequences or | |
113 | functions might break programs. | |
114 | ||
115 | =item Could it be a module instead? | |
116 | ||
117 | Perl 5 has extension mechanisms, modules and XS, specifically to avoid | |
118 | the need to keep changing the Perl interpreter. You can write modules | |
119 | that export functions, you can give those functions prototypes so they | |
120 | can be called like built-in functions, you can even write XS code to | |
121 | mess with the runtime data structures of the Perl interpreter if you | |
122 | want to implement really complicated things. If it can be done in a | |
123 | module instead of in the core, it's highly unlikely to be added. | |
124 | ||
125 | =item Is the feature generic enough? | |
126 | ||
127 | Is this something that only the submitter wants added to the language, | |
128 | or would it be broadly useful? Sometimes, instead of adding a feature | |
129 | with a tight focus, the porters might decide to wait until someone | |
130 | implements the more generalized feature. For instance, instead of | |
131 | implementing a ``delayed evaluation'' feature, the porters are waiting | |
132 | for a macro system that would permit delayed evaluation and much more. | |
133 | ||
134 | =item Does it potentially introduce new bugs? | |
135 | ||
136 | Radical rewrites of large chunks of the Perl interpreter have the | |
137 | potential to introduce new bugs. The smaller and more localized the | |
138 | change, the better. | |
139 | ||
140 | =item Does it preclude other desirable features? | |
141 | ||
142 | A patch is likely to be rejected if it closes off future avenues of | |
143 | development. For instance, a patch that placed a true and final | |
144 | interpretation on prototypes is likely to be rejected because there | |
145 | are still options for the future of prototypes that haven't been | |
146 | addressed. | |
147 | ||
148 | =item Is the implementation robust? | |
149 | ||
150 | Good patches (tight code, complete, correct) stand more chance of | |
151 | going in. Sloppy or incorrect patches might be placed on the back | |
152 | burner until the pumpking has time to fix, or might be discarded | |
153 | altogether without further notice. | |
154 | ||
155 | =item Is the implementation generic enough to be portable? | |
156 | ||
157 | The worst patches make use of a system-specific features. It's highly | |
158 | unlikely that nonportable additions to the Perl language will be | |
159 | accepted. | |
160 | ||
161 | =item Is there enough documentation? | |
162 | ||
163 | Patches without documentation are probably ill-thought out or | |
164 | incomplete. Nothing can be added without documentation, so submitting | |
165 | a patch for the appropriate manpages as well as the source code is | |
166 | always a good idea. If appropriate, patches should add to the test | |
167 | suite as well. | |
168 | ||
169 | =item Is there another way to do it? | |
170 | ||
171 | Larry said ``Although the Perl Slogan is I<There's More Than One Way | |
172 | to Do It>, I hesitate to make 10 ways to do something''. This is a | |
173 | tricky heuristic to navigate, though--one man's essential addition is | |
174 | another man's pointless cruft. | |
175 | ||
176 | =item Does it create too much work? | |
177 | ||
178 | Work for the pumpking, work for Perl programmers, work for module | |
179 | authors, ... Perl is supposed to be easy. | |
180 | ||
f6c51b38 GS |
181 | =item Patches speak louder than words |
182 | ||
183 | Working code is always preferred to pie-in-the-sky ideas. A patch to | |
184 | add a feature stands a much higher chance of making it to the language | |
185 | than does a random feature request, no matter how fervently argued the | |
186 | request might be. This ties into ``Will it be useful?'', as the fact | |
187 | that someone took the time to make the patch demonstrates a strong | |
188 | desire for the feature. | |
189 | ||
e8cd7eae GS |
190 | =back |
191 | ||
192 | If you're on the list, you might hear the word ``core'' bandied | |
193 | around. It refers to the standard distribution. ``Hacking on the | |
194 | core'' means you're changing the C source code to the Perl | |
195 | interpreter. ``A core module'' is one that ships with Perl. | |
196 | ||
197 | The source code to the Perl interpreter, in its different versions, is | |
198 | kept in a repository managed by a revision control system (which is | |
199 | currently the Perforce program, see http://perforce.com/). The | |
200 | pumpkings and a few others have access to the repository to check in | |
201 | changes. Periodically the pumpking for the development version of Perl | |
202 | will release a new version, so the rest of the porters can see what's | |
2be4c08b GS |
203 | changed. The current state of the main trunk of repository, and patches |
204 | that describe the individual changes that have happened since the last | |
205 | public release are available at this location: | |
206 | ||
207 | ftp://ftp.linux.activestate.com/pub/staff/gsar/APC/ | |
208 | ||
209 | Selective parts are also visible via the rsync protocol. To get all | |
210 | the individual changes to the mainline since the last development | |
211 | release, use the following command: | |
212 | ||
213 | rsync -avuz rsync://ftp.linux.activestate.com/perl-diffs perl-diffs | |
214 | ||
215 | Use this to get the latest source tree in full: | |
216 | ||
217 | rsync -avuz rsync://ftp.linux.activestate.com/perl-current perl-current | |
218 | ||
219 | Needless to say, the source code in perl-current is usually in a perpetual | |
220 | state of evolution. You should expect it to be very buggy. Do B<not> use | |
221 | it for any purpose other than testing and development. | |
e8cd7eae GS |
222 | |
223 | Always submit patches to I<perl5-porters@perl.org>. This lets other | |
224 | porters review your patch, which catches a surprising number of errors | |
f6c51b38 GS |
225 | in patches. Either use the diff program (available in source code |
226 | form from I<ftp://ftp.gnu.org/pub/gnu/>), or use Johan Vromans' | |
227 | I<makepatch> (available from I<CPAN/authors/id/JV/>). Unified diffs | |
228 | are preferred, but context diffs are accepted. Do not send RCS-style | |
229 | diffs or diffs without context lines. More information is given in | |
230 | the I<Porting/patching.pod> file in the Perl source distribution. | |
231 | Please patch against the latest B<development> version (e.g., if | |
232 | you're fixing a bug in the 5.005 track, patch against the latest | |
233 | 5.005_5x version). Only patches that survive the heat of the | |
234 | development branch get applied to maintenance versions. | |
e8cd7eae GS |
235 | |
236 | Your patch should update the documentation and test suite. | |
237 | ||
238 | To report a bug in Perl, use the program I<perlbug> which comes with | |
239 | Perl (if you can't get Perl to work, send mail to the address | |
240 | I<perlbug@perl.com> or I<perlbug@perl.org>). Reporting bugs through | |
241 | I<perlbug> feeds into the automated bug-tracking system, access to | |
242 | which is provided through the web at I<http://bugs.perl.org/>. It | |
243 | often pays to check the archives of the perl5-porters mailing list to | |
244 | see whether the bug you're reporting has been reported before, and if | |
245 | so whether it was considered a bug. See above for the location of | |
246 | the searchable archives. | |
247 | ||
248 | The CPAN testers (I<http://testers.cpan.org/>) are a group of | |
249 | volunteers who test CPAN modules on a variety of platforms. Perl Labs | |
f6c51b38 GS |
250 | (I<http://labs.perl.org/>) automatically tests Perl source releases on |
251 | platforms and gives feedback to the CPAN testers mailing list. Both | |
252 | efforts welcome volunteers. | |
e8cd7eae GS |
253 | |
254 | To become an active and patching Perl porter, you'll need to learn how | |
255 | Perl works on the inside. Chip Salzenberg, a pumpking, has written | |
256 | articles on Perl internals for The Perl Journal | |
257 | (I<http://www.tpj.com/>) which explain how various parts of the Perl | |
258 | interpreter work. The C<perlguts> manpage explains the internal data | |
259 | structures. And, of course, the C source code (sometimes sparsely | |
260 | commented, sometimes commented well) is a great place to start (begin | |
f6c51b38 GS |
261 | with C<perl.c> and see where it goes from there). A lot of the style |
262 | of the Perl source is explained in the I<Porting/pumpkin.pod> file in | |
263 | the source distribution. | |
e8cd7eae GS |
264 | |
265 | It is essential that you be comfortable using a good debugger | |
266 | (e.g. gdb, dbx) before you can patch perl. Stepping through perl | |
267 | as it executes a script is perhaps the best (if sometimes tedious) | |
268 | way to gain a precise understanding of the overall architecture of | |
269 | the language. | |
270 | ||
271 | If you build a version of the Perl interpreter with C<-DDEBUGGING>, | |
85add8c2 | 272 | Perl's B<-D> command line flag will cause copious debugging information |
e8cd7eae GS |
273 | to be emitted (see the C<perlrun> manpage). If you build a version of |
274 | Perl with compiler debugging information (e.g. with the C compiler's | |
275 | C<-g> option instead of C<-O>) then you can step through the execution | |
276 | of the interpreter with your favourite C symbolic debugger, setting | |
277 | breakpoints on particular functions. | |
278 | ||
279 | It's a good idea to read and lurk for a while before chipping in. | |
280 | That way you'll get to see the dynamic of the conversations, learn the | |
281 | personalities of the players, and hopefully be better prepared to make | |
282 | a useful contribution when do you speak up. | |
283 | ||
284 | If after all this you still think you want to join the perl5-porters | |
f6c51b38 GS |
285 | mailing list, send mail to I<perl5-porters-subscribe@perl.org>. To |
286 | unsubscribe, send mail to I<perl5-porters-unsubscribe@perl.org>. | |
e8cd7eae GS |
287 | |
288 | =head1 AUTHOR | |
289 | ||
290 | This document was written by Nathan Torkington, and is maintained by | |
291 | the perl5-porters mailing list. | |
292 |