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