Commit | Line | Data |
e8cd7eae |
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 |