Commit | Line | Data |
---|---|---|
04c692a8 | 1 | =encoding utf8 |
35c336e6 | 2 | |
04c692a8 DR |
3 | =for comment |
4 | Consistent formatting of this file is achieved with: | |
5 | perl ./Porting/podtidy pod/perlhack.pod | |
35c336e6 | 6 | |
04c692a8 | 7 | =head1 NAME |
35c336e6 | 8 | |
04c692a8 | 9 | perlhack - How to hack on Perl |
35c336e6 | 10 | |
04c692a8 | 11 | =head1 DESCRIPTION |
35c336e6 | 12 | |
04c692a8 DR |
13 | This document explains how Perl development works. It includes details |
14 | about the Perl 5 Porters email list, the Perl repository, the Perlbug | |
15 | bug tracker, patch guidelines, and commentary on Perl development | |
16 | philosophy. | |
f7e1e956 | 17 | |
04c692a8 | 18 | =head1 SUPER QUICK PATCH GUIDE |
f7e1e956 | 19 | |
04c692a8 DR |
20 | If you just want to submit a single small patch like a pod fix, a test |
21 | for a bug, comment fixes, etc., it's easy! Here's how: | |
f7e1e956 | 22 | |
04c692a8 | 23 | =over 4 |
e018f8be | 24 | |
04c692a8 | 25 | =item * Check out the source repository |
e018f8be | 26 | |
04c692a8 DR |
27 | The perl source is in a git repository. You can clone the repository |
28 | with the following command: | |
e018f8be | 29 | |
04c692a8 | 30 | % git clone git://perl5.git.perl.org/perl.git perl |
e018f8be | 31 | |
04c692a8 | 32 | =item * Make your change |
e018f8be | 33 | |
04c692a8 | 34 | Hack, hack, hack. |
7205a85d | 35 | |
04c692a8 | 36 | =item * Test your change |
e018f8be | 37 | |
04c692a8 | 38 | You can run all the tests with the following commands: |
b26492ee | 39 | |
04c692a8 DR |
40 | % ./Configure -des -Dusedevel |
41 | % make test | |
7205a85d | 42 | |
04c692a8 | 43 | Keep hacking until the tests pass. |
b26492ee | 44 | |
04c692a8 | 45 | =item * Commit your change |
e018f8be | 46 | |
04c692a8 | 47 | Commiting your work will save the change I<on your local system>: |
7205a85d | 48 | |
04c692a8 | 49 | % git commit -a -m 'Commit message goes here' |
e018f8be | 50 | |
04c692a8 DR |
51 | Make sure the commit message describes your change in a single |
52 | sentence. For example, "Fixed spelling errors in perlhack.pod". | |
e018f8be | 53 | |
04c692a8 | 54 | =item * Send your change to perlbug |
7a834142 | 55 | |
04c692a8 DR |
56 | The next step is to submit your patch to the Perl core ticket system |
57 | via email. | |
7a834142 | 58 | |
04c692a8 DR |
59 | Assuming your patch consists of a single git commit, you can send it to |
60 | perlbug with this command line: | |
e018f8be | 61 | |
04c692a8 DR |
62 | % git format-patch HEAD^1..HEAD |
63 | % perlbug -s '[PATCH] `git log --pretty=format:%s HEAD^1..HEAD`' -f 0001-*.patch | |
e018f8be | 64 | |
04c692a8 DR |
65 | The perlbug program will ask you a few questions about your email |
66 | address and the patch you're submitting. Once you've answered them you | |
67 | can submit your patch. | |
e018f8be | 68 | |
04c692a8 | 69 | =item * Thank you |
e018f8be | 70 | |
04c692a8 DR |
71 | The porters appreciate the time you spent helping to make Perl better. |
72 | Thank you! | |
e018f8be | 73 | |
cce04beb | 74 | =back |
e018f8be | 75 | |
04c692a8 | 76 | =head1 BUG REPORTING |
cc0710ff | 77 | |
04c692a8 DR |
78 | If you want to report a bug in Perl you must use the F<perlbug> command |
79 | line tool. This tool will ensure that your bug report includes all the | |
80 | relevant system and configuration information. | |
7205a85d | 81 | |
04c692a8 DR |
82 | To browse existing Perl bugs and patches, you can use the web interface |
83 | at L<http://rt.perl.org>. | |
244d9cb7 | 84 | |
04c692a8 DR |
85 | Please check the archive of the perl5-porters list (see below) and/or |
86 | the bug tracking system before submitting a bug report. Often, you'll | |
87 | find that the bug has been reported already. | |
244d9cb7 | 88 | |
04c692a8 DR |
89 | You can log in to the bug tracking system and comment on existing bug |
90 | reports. If you have additional information regarding an existing bug, | |
91 | please add it. This will help the porters fix the bug. | |
7205a85d | 92 | |
04c692a8 | 93 | =head1 PERL 5 PORTERS |
7205a85d | 94 | |
04c692a8 DR |
95 | The perl5-porters (p5p) mailing list is where the Perl standard |
96 | distribution is maintained and developed. The people who maintain Perl | |
97 | are also referred to as the "Perl 5 Porters", or just the "porters". | |
a75f557c | 98 | |
04c692a8 DR |
99 | A searchable archive of the list is available at |
100 | L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is | |
101 | also another archive at | |
102 | L<http://archive.develooper.com/perl5-porters@perl.org/>. | |
7205a85d | 103 | |
04c692a8 | 104 | =head2 perl-changes mailing list |
7205a85d | 105 | |
04c692a8 DR |
106 | The perl5-changes mailing list receives a copy of each patch that gets |
107 | submitted to the maintenance and development branches of the perl | |
108 | repository. See L<http://lists.perl.org/list/perl5-changes.html> for | |
109 | subscription and archive information. | |
244d9cb7 | 110 | |
04c692a8 | 111 | =head1 GETTING THE PERL SOURCE |
244d9cb7 | 112 | |
04c692a8 DR |
113 | All of Perl's source code is kept centrally in a Git repository at |
114 | I<perl5.git.perl.org>. The repository contains many Perl revisions from | |
115 | Perl 1 onwards and all the revisions from Perforce, the previous | |
116 | version control system. | |
244d9cb7 | 117 | |
04c692a8 DR |
118 | For much more detail on using git with the Perl repository, please see |
119 | L<perlgit>. | |
244d9cb7 | 120 | |
04c692a8 | 121 | =head2 Read access via Git |
244d9cb7 | 122 | |
04c692a8 DR |
123 | You will need a copy of Git for your computer. You can fetch a copy of |
124 | the repository using the git protocol: | |
244d9cb7 | 125 | |
04c692a8 | 126 | % git clone git://perl5.git.perl.org/perl.git perl |
244d9cb7 | 127 | |
04c692a8 DR |
128 | This clones the repository and makes a local copy in the F<perl> |
129 | directory. | |
7205a85d | 130 | |
04c692a8 DR |
131 | If you cannot use the git protocol for firewall reasons, you can also |
132 | clone via http, though this is much slower: | |
7205a85d | 133 | |
04c692a8 | 134 | % git clone http://perl5.git.perl.org/perl.git perl |
7205a85d | 135 | |
04c692a8 | 136 | =head2 Read access via the web |
7205a85d | 137 | |
04c692a8 DR |
138 | You may access the repository over the web. This allows you to browse |
139 | the tree, see recent commits, subscribe to RSS feeds for the changes, | |
140 | search for particular commits and more. You may access it at | |
141 | L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is | |
142 | found at L<http://github.com/mirrors/perl> | |
7205a85d | 143 | |
04c692a8 | 144 | =head2 Read access via rsync |
7205a85d | 145 | |
04c692a8 DR |
146 | You can also choose to use rsync to get a copy of the current source |
147 | tree for the bleadperl branch and all maintenance branches: | |
7205a85d | 148 | |
04c692a8 DR |
149 | $ rsync -avz rsync://perl5.git.perl.org/perl-current . |
150 | $ rsync -avz rsync://perl5.git.perl.org/perl-5.12.x . | |
151 | $ rsync -avz rsync://perl5.git.perl.org/perl-5.10.x . | |
152 | $ rsync -avz rsync://perl5.git.perl.org/perl-5.8.x . | |
153 | $ rsync -avz rsync://perl5.git.perl.org/perl-5.6.x . | |
154 | $ rsync -avz rsync://perl5.git.perl.org/perl-5.005xx . | |
7205a85d | 155 | |
04c692a8 | 156 | (Add the C<--delete> option to remove leftover files) |
7205a85d | 157 | |
04c692a8 | 158 | To get a full list of the available sync points: |
7205a85d | 159 | |
04c692a8 | 160 | $ rsync perl5.git.perl.org:: |
7205a85d | 161 | |
04c692a8 | 162 | =head2 Write access via git |
7205a85d | 163 | |
04c692a8 DR |
164 | If you have a commit bit, please see L<perlgit> for more details on |
165 | using git. | |
7205a85d | 166 | |
04c692a8 | 167 | =head1 PATCHING PERL |
7205a85d | 168 | |
04c692a8 DR |
169 | If you're planning to do more extensive work than a single small fix, |
170 | we encourage you to read the documentation below. This will help you | |
171 | focus your work and make your patches easier to incorporate into the | |
172 | Perl source. | |
244d9cb7 | 173 | |
04c692a8 | 174 | =head2 Submitting patches |
244d9cb7 | 175 | |
04c692a8 DR |
176 | If you have a small patch to submit, please submit it via perlbug. You |
177 | can also send email directly to perlbug@perl.org. Please note that | |
178 | messages sent to perlbug may be held in a moderation queue, so you | |
179 | won't receive a response immediately. | |
244d9cb7 | 180 | |
04c692a8 DR |
181 | You'll know your submission has been processed when you receive an |
182 | email from our ticket tracking system. This email will give you a | |
183 | ticket number. Once your patch has made it to the ticket tracking | |
184 | system, it will also be sent to the perl5-porters@perl.org list. | |
244d9cb7 | 185 | |
04c692a8 DR |
186 | Patches are reviewed and discussed on the p5p list. Simple, |
187 | uncontroversial patches will usually be applied without any discussion. | |
188 | When the patch is applied, the ticket will be updated and you will | |
189 | receive email. In addition, an email will be sent to the p5p list. | |
244d9cb7 | 190 | |
04c692a8 DR |
191 | In other cases, the patch will need more work or discussion. That will |
192 | happen on the p5p list. | |
244d9cb7 | 193 | |
04c692a8 DR |
194 | You are encouraged to participate in the discussion and advocate for |
195 | your patch. Sometimes your patch may get lost in the shuffle. It's | |
196 | appropriate to send a reminder email to p5p if no action has been taken | |
197 | in a month. Please remember that the Perl 5 developers are all | |
198 | volunteers, and be polite. | |
244d9cb7 | 199 | |
04c692a8 DR |
200 | Changes are always applied directly to the main development branch, |
201 | called "blead". Some patches may be backported to a maintenance branch. | |
202 | If you think your patch is appropriate for the maintenance branch, | |
203 | please explain why when you submit it. | |
244d9cb7 | 204 | |
04c692a8 | 205 | =head2 Getting your patch accepted |
244d9cb7 | 206 | |
04c692a8 DR |
207 | If you are submitting a code patch there are several things that you |
208 | can do to help the Perl 5 Porters accept your patch. | |
244d9cb7 | 209 | |
04c692a8 | 210 | =head3 Commit message |
244d9cb7 | 211 | |
04c692a8 DR |
212 | As you craft each patch you intend to submit to the Perl core, it's |
213 | important to write a good commit message. This is especially important | |
214 | if your submission will consist of a series of commits. | |
244d9cb7 | 215 | |
04c692a8 DR |
216 | The first line of the commit message should be a short description |
217 | without a period. It should be no longer than the subject line of an | |
218 | E-Mail, 50 characters being a good rule of thumb. | |
f7e1e956 | 219 | |
04c692a8 DR |
220 | A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ..) will |
221 | only display the first line (cut off at 50 characters) when presenting | |
222 | commit summaries. | |
7cd58830 | 223 | |
04c692a8 DR |
224 | The commit message should include a description of the problem that the |
225 | patch corrects or new functionality that the patch adds. | |
7cd58830 | 226 | |
04c692a8 DR |
227 | As a general rule of thumb, your commit message should help a |
228 | programmer who knows the Perl core quickly understand what you were | |
229 | trying to do, how you were trying to do it, and why the change matters | |
230 | to Perl. | |
7cd58830 | 231 | |
04c692a8 | 232 | =over 4 |
7cd58830 | 233 | |
04c692a8 | 234 | =item * Why |
7cd58830 | 235 | |
04c692a8 DR |
236 | Your commit message should describe why the change you are making is |
237 | important. When someone looks at your change in six months or six | |
238 | years, your intent should be clear. | |
7cd58830 | 239 | |
04c692a8 DR |
240 | If you're deprecating a feature with the intent of later simplifying |
241 | another bit of code, say so. If you're fixing a performance problem or | |
242 | adding a new feature to support some other bit of the core, mention | |
243 | that. | |
7cd58830 | 244 | |
04c692a8 | 245 | =item * What |
7cd58830 | 246 | |
04c692a8 DR |
247 | Your commit message should describe what part of the Perl core you're |
248 | changing and what you expect your patch to do. | |
7cd58830 | 249 | |
04c692a8 | 250 | =item * How |
7cd58830 | 251 | |
04c692a8 DR |
252 | While it's not necessary for documentation changes, new tests or |
253 | trivial patches, it's often worth explaining how your change works. | |
254 | Even if it's clear to you today, it may not be clear to a porter next | |
255 | month or next year. | |
d7889f52 | 256 | |
04c692a8 | 257 | =back |
d7889f52 | 258 | |
04c692a8 DR |
259 | A commit message isn't intended to take the place of comments in your |
260 | code. Commit messages should describe the change you made, while code | |
261 | comments should describe the current state of the code. | |
d7889f52 | 262 | |
04c692a8 DR |
263 | If you've just implemented a new feature, complete with doc, tests and |
264 | well-commented code, a brief commit message will often suffice. If, | |
265 | however, you've just changed a single character deep in the parser or | |
266 | lexer, you might need to write a small novel to ensure that future | |
267 | readers understand what you did and why you did it. | |
d7889f52 | 268 | |
04c692a8 | 269 | =head3 Comments, Comments, Comments |
d7889f52 | 270 | |
04c692a8 DR |
271 | Be sure to adequately comment your code. While commenting every line is |
272 | unnecessary, anything that takes advantage of side effects of | |
273 | operators, that creates changes that will be felt outside of the | |
274 | function being patched, or that others may find confusing should be | |
275 | documented. If you are going to err, it is better to err on the side of | |
276 | adding too many comments than too few. | |
d7889f52 | 277 | |
04c692a8 DR |
278 | The best comments explain I<why> the code does what it does, not I<what |
279 | it does>. | |
d7889f52 | 280 | |
04c692a8 | 281 | =head3 Style |
d7889f52 | 282 | |
04c692a8 DR |
283 | In general, please follow the particular style of the code you are |
284 | patching. | |
d7889f52 | 285 | |
04c692a8 DR |
286 | In particular, follow these general guidelines for patching Perl |
287 | sources: | |
cce04beb | 288 | |
04c692a8 | 289 | =over 4 |
d7889f52 JH |
290 | |
291 | =item * | |
292 | ||
04c692a8 | 293 | 8-wide tabs (no exceptions!) |
d7889f52 JH |
294 | |
295 | =item * | |
296 | ||
04c692a8 | 297 | 4-wide indents for code, 2-wide indents for nested CPP #defines |
ee9468a2 | 298 | |
cce04beb | 299 | =item * |
ee9468a2 | 300 | |
04c692a8 | 301 | Try hard not to exceed 79-columns |
bc028b6b | 302 | |
ee9468a2 RGS |
303 | =item * |
304 | ||
04c692a8 | 305 | ANSI C prototypes |
d7889f52 JH |
306 | |
307 | =item * | |
308 | ||
04c692a8 | 309 | Uncuddled elses and "K&R" style for indenting control constructs |
0bec6c03 | 310 | |
04c692a8 | 311 | =item * |
d7889f52 | 312 | |
04c692a8 | 313 | No C++ style (//) comments |
d7889f52 JH |
314 | |
315 | =item * | |
316 | ||
04c692a8 | 317 | Mark places that need to be revisited with XXX (and revisit often!) |
27565cb6 JH |
318 | |
319 | =item * | |
320 | ||
04c692a8 DR |
321 | Opening brace lines up with "if" when conditional spans multiple lines; |
322 | should be at end-of-line otherwise | |
27565cb6 | 323 | |
04c692a8 | 324 | =item * |
27565cb6 | 325 | |
04c692a8 DR |
326 | In function definitions, name starts in column 0 (return value is on |
327 | previous line) | |
27565cb6 | 328 | |
04c692a8 | 329 | =item * |
27565cb6 | 330 | |
04c692a8 DR |
331 | Single space after keywords that are followed by parens, no space |
332 | between function name and following paren | |
606fd33d | 333 | |
27565cb6 JH |
334 | =item * |
335 | ||
04c692a8 DR |
336 | Avoid assignments in conditionals, but if they're unavoidable, use |
337 | extra paren, e.g. "if (a && (b = c)) ..." | |
27565cb6 JH |
338 | |
339 | =item * | |
340 | ||
04c692a8 | 341 | "return foo;" rather than "return(foo);" |
27565cb6 JH |
342 | |
343 | =item * | |
344 | ||
04c692a8 | 345 | "if (!foo) ..." rather than "if (foo == FALSE) ..." etc. |
606fd33d JH |
346 | |
347 | =back | |
27565cb6 | 348 | |
04c692a8 | 349 | =head3 Test suite |
d7889f52 | 350 | |
04c692a8 DR |
351 | If your patch changes code (rather than just changing documentation) |
352 | you should also include one or more test cases which illustrate the bug | |
353 | you're fixing or validate the new functionality you're adding. In | |
354 | general, you should update an existing test file rather than create a | |
355 | new one. | |
2bbc8d55 | 356 | |
04c692a8 DR |
357 | Your test suite additions should generally follow these guidelines |
358 | (courtesy of Gurusamy Sarathy <gsar@activestate.com>): | |
2bbc8d55 | 359 | |
04c692a8 | 360 | =over 4 |
0bec6c03 | 361 | |
04c692a8 | 362 | =item * |
0bec6c03 | 363 | |
04c692a8 | 364 | Know what you're testing. Read the docs, and the source. |
ee9468a2 RGS |
365 | |
366 | =item * | |
367 | ||
04c692a8 | 368 | Tend to fail, not succeed. |
0bec6c03 | 369 | |
04c692a8 | 370 | =item * |
0bec6c03 | 371 | |
04c692a8 | 372 | Interpret results strictly. |
27565cb6 | 373 | |
04c692a8 | 374 | =item * |
27565cb6 | 375 | |
04c692a8 | 376 | Use unrelated features (this will flush out bizarre interactions). |
27565cb6 | 377 | |
04c692a8 | 378 | =item * |
27565cb6 | 379 | |
04c692a8 | 380 | Use non-standard idioms (otherwise you are not testing TIMTOWTDI). |
27565cb6 | 381 | |
04c692a8 | 382 | =item * |
d7889f52 | 383 | |
04c692a8 DR |
384 | Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT |
385 | found in t/op/tie.t is much more maintainable, and gives better failure | |
386 | reports). | |
d7889f52 | 387 | |
04c692a8 | 388 | =item * |
d7889f52 | 389 | |
04c692a8 | 390 | Give meaningful error messages when a test fails. |
d7889f52 | 391 | |
04c692a8 | 392 | =item * |
d7889f52 | 393 | |
04c692a8 DR |
394 | Avoid using qx// and system() unless you are testing for them. If you |
395 | do use them, make sure that you cover _all_ perl platforms. | |
d7889f52 | 396 | |
04c692a8 | 397 | =item * |
0bec6c03 | 398 | |
04c692a8 | 399 | Unlink any temporary files you create. |
63796a85 | 400 | |
04c692a8 | 401 | =item * |
0bec6c03 | 402 | |
04c692a8 | 403 | Promote unforeseen warnings to errors with $SIG{__WARN__}. |
0bec6c03 | 404 | |
04c692a8 | 405 | =item * |
0bec6c03 | 406 | |
04c692a8 DR |
407 | Be sure to use the libraries and modules shipped with the version being |
408 | tested, not those that were already installed. | |
d7889f52 | 409 | |
04c692a8 | 410 | =item * |
d7889f52 | 411 | |
04c692a8 | 412 | Add comments to the code explaining what you are testing for. |
d7889f52 | 413 | |
04c692a8 | 414 | =item * |
d7889f52 | 415 | |
04c692a8 DR |
416 | Make updating the '1..42' string unnecessary. Or make sure that you |
417 | update it. | |
d7889f52 | 418 | |
04c692a8 | 419 | =item * |
d7889f52 | 420 | |
04c692a8 | 421 | Test _all_ behaviors of a given operator, library, or function. |
d7889f52 | 422 | |
04c692a8 | 423 | Test all optional arguments. |
d7889f52 | 424 | |
04c692a8 | 425 | Test return values in various contexts (boolean, scalar, list, lvalue). |
d7889f52 | 426 | |
04c692a8 | 427 | Use both global and lexical variables. |
d7889f52 | 428 | |
04c692a8 | 429 | Don't forget the exceptional, pathological cases. |
0bec6c03 | 430 | |
cce04beb | 431 | =back |
0bec6c03 | 432 | |
04c692a8 | 433 | =head2 Patching a core module |
ee9468a2 | 434 | |
04c692a8 DR |
435 | This works just like patching anything else, with one extra |
436 | consideration. | |
63796a85 | 437 | |
04c692a8 DR |
438 | Some core modules also live on CPAN and are maintained outside of the |
439 | Perl core. When the author updates the module, the updates are simply | |
440 | copied into the core. | |
63796a85 | 441 | |
04c692a8 DR |
442 | Module in the F<cpan/> directory of the source tree are maintained |
443 | outside of the Perl core. See that module's listing on documentation or | |
444 | its listing on L<http://search.cpan.org/> for more information on | |
445 | reporting bugs and submitting patches. | |
63796a85 | 446 | |
04c692a8 DR |
447 | In contrast, modules in the F<dist/> directory are maintained in the |
448 | core. | |
63796a85 | 449 | |
04c692a8 | 450 | =head2 Updating perldelta |
63796a85 | 451 | |
04c692a8 DR |
452 | For changes significant enough to warrant a F<pod/perldelta.pod> entry, |
453 | the porters will greatly appreciate it if you submit a delta entry | |
454 | along with your actual change. Significant changes include, but are not | |
455 | limited to: | |
63796a85 | 456 | |
04c692a8 | 457 | =over 4 |
63796a85 | 458 | |
04c692a8 | 459 | =item * |
63796a85 | 460 | |
04c692a8 | 461 | Adding, deprecating, or removing core features |
ee9468a2 | 462 | |
04c692a8 | 463 | =item * |
ee9468a2 | 464 | |
04c692a8 | 465 | Adding, deprecating, removing, or upgrading core or dual-life modules |
ee9468a2 | 466 | |
04c692a8 | 467 | =item * |
ee9468a2 | 468 | |
04c692a8 | 469 | Adding new core tests |
ee9468a2 | 470 | |
04c692a8 | 471 | =item * |
ee9468a2 | 472 | |
04c692a8 | 473 | Fixing security issues and user-visible bugs in the core |
cce04beb | 474 | |
04c692a8 | 475 | =item * |
ad7244db | 476 | |
04c692a8 | 477 | Changes that might break existing code, either on the perl or C level |
ad7244db JH |
478 | |
479 | =item * | |
480 | ||
04c692a8 | 481 | Significant performance improvements |
ad7244db JH |
482 | |
483 | =item * | |
484 | ||
04c692a8 DR |
485 | Adding, removing, or significantly changing documentation in the |
486 | F<pod/> directory | |
ad7244db | 487 | |
cce04beb | 488 | =item * |
ad7244db | 489 | |
04c692a8 | 490 | Important platform-specific changes |
d7889f52 | 491 | |
cce04beb DG |
492 | =back |
493 | ||
04c692a8 DR |
494 | Please make sure you add the perldelta entry to the right section |
495 | within F<pod/perldelta.pod>. More information on how to write good | |
496 | perldelta entries is available in the C<Style> section of | |
497 | F<Porting/how_to_write_a_perldelta.pod>. | |
d7889f52 | 498 | |
04c692a8 | 499 | =head2 What makes for a good patch? |
d7889f52 | 500 | |
04c692a8 DR |
501 | New features and extensions to the language can be contentious. There |
502 | is no specific set of criteria which determine what features get added, | |
503 | but here are some questions to consider when developing a patch: | |
d7889f52 | 504 | |
04c692a8 | 505 | =head3 Does the concept match the general goals of Perl? |
d7889f52 | 506 | |
04c692a8 | 507 | Our goals include, but are not limited to: |
d7889f52 | 508 | |
04c692a8 | 509 | =over 4 |
d7889f52 | 510 | |
04c692a8 | 511 | =item 1. |
d7889f52 | 512 | |
04c692a8 | 513 | Keep it fast, simple, and useful. |
cce04beb | 514 | |
04c692a8 | 515 | =item 2. |
cce04beb | 516 | |
04c692a8 | 517 | Keep features/concepts as orthogonal as possible. |
902b9dbf | 518 | |
04c692a8 | 519 | =item 3. |
902b9dbf | 520 | |
04c692a8 | 521 | No arbitrary limits (platforms, data sizes, cultures). |
a958818a | 522 | |
04c692a8 | 523 | =item 4. |
ac036724 | 524 | |
04c692a8 | 525 | Keep it open and exciting to use/patch/advocate Perl everywhere. |
a958818a | 526 | |
04c692a8 | 527 | =item 5. |
a958818a | 528 | |
04c692a8 | 529 | Either assimilate new technologies, or build bridges to them. |
a958818a | 530 | |
04c692a8 | 531 | =back |
a958818a | 532 | |
04c692a8 | 533 | =head3 Where is the implementation? |
a958818a | 534 | |
04c692a8 DR |
535 | All the talk in the world is useless without an implementation. In |
536 | almost every case, the person or people who argue for a new feature | |
537 | will be expected to be the ones who implement it. Porters capable of | |
538 | coding new features have their own agendas, and are not available to | |
539 | implement your (possibly good) idea. | |
a1b65709 | 540 | |
04c692a8 | 541 | =head3 Backwards compatibility |
37c0adeb | 542 | |
04c692a8 DR |
543 | It's a cardinal sin to break existing Perl programs. New warnings can |
544 | be contentious--some say that a program that emits warnings is not | |
545 | broken, while others say it is. Adding keywords has the potential to | |
546 | break programs, changing the meaning of existing token sequences or | |
547 | functions might break programs. | |
f50e5b73 | 548 | |
04c692a8 DR |
549 | The Perl 5 core includes mechanisms to help porters make backwards |
550 | incompatible changes more compatible such as the L<feature> and | |
551 | L<deprecate> modules. Please use them when appropriate. | |
902b9dbf | 552 | |
04c692a8 | 553 | =head3 Could it be a module instead? |
902b9dbf | 554 | |
04c692a8 DR |
555 | Perl 5 has extension mechanisms, modules and XS, specifically to avoid |
556 | the need to keep changing the Perl interpreter. You can write modules | |
557 | that export functions, you can give those functions prototypes so they | |
558 | can be called like built-in functions, you can even write XS code to | |
559 | mess with the runtime data structures of the Perl interpreter if you | |
560 | want to implement really complicated things. | |
902b9dbf | 561 | |
04c692a8 DR |
562 | Whenever possible, new features should be prototyped in a CPAN module |
563 | before they will be considered for the core. | |
902b9dbf | 564 | |
04c692a8 | 565 | =head3 Is the feature generic enough? |
902b9dbf | 566 | |
04c692a8 DR |
567 | Is this something that only the submitter wants added to the language, |
568 | or is it broadly useful? Sometimes, instead of adding a feature with a | |
569 | tight focus, the porters might decide to wait until someone implements | |
570 | the more generalized feature. | |
902b9dbf | 571 | |
04c692a8 | 572 | =head3 Does it potentially introduce new bugs? |
902b9dbf | 573 | |
04c692a8 DR |
574 | Radical rewrites of large chunks of the Perl interpreter have the |
575 | potential to introduce new bugs. | |
902b9dbf | 576 | |
04c692a8 | 577 | =head3 How big is it? |
902b9dbf | 578 | |
04c692a8 DR |
579 | The smaller and more localized the change, the better. Similarly, a |
580 | series of small patches is greatly preferred over a single large patch. | |
902b9dbf | 581 | |
04c692a8 | 582 | =head3 Does it preclude other desirable features? |
902b9dbf | 583 | |
04c692a8 DR |
584 | A patch is likely to be rejected if it closes off future avenues of |
585 | development. For instance, a patch that placed a true and final | |
586 | interpretation on prototypes is likely to be rejected because there are | |
587 | still options for the future of prototypes that haven't been addressed. | |
902b9dbf | 588 | |
04c692a8 | 589 | =head3 Is the implementation robust? |
902b9dbf | 590 | |
04c692a8 DR |
591 | Good patches (tight code, complete, correct) stand more chance of going |
592 | in. Sloppy or incorrect patches might be placed on the back burner | |
593 | until the pumpking has time to fix, or might be discarded altogether | |
594 | without further notice. | |
902b9dbf | 595 | |
04c692a8 | 596 | =head3 Is the implementation generic enough to be portable? |
902b9dbf | 597 | |
04c692a8 DR |
598 | The worst patches make use of a system-specific features. It's highly |
599 | unlikely that non-portable additions to the Perl language will be | |
600 | accepted. | |
902b9dbf | 601 | |
04c692a8 | 602 | =head3 Is the implementation tested? |
902b9dbf | 603 | |
04c692a8 DR |
604 | Patches which change behaviour (fixing bugs or introducing new |
605 | features) must include regression tests to verify that everything works | |
606 | as expected. | |
902b9dbf | 607 | |
04c692a8 DR |
608 | Without tests provided by the original author, how can anyone else |
609 | changing perl in the future be sure that they haven't unwittingly | |
610 | broken the behaviour the patch implements? And without tests, how can | |
611 | the patch's author be confident that his/her hard work put into the | |
612 | patch won't be accidentally thrown away by someone in the future? | |
902b9dbf | 613 | |
04c692a8 | 614 | =head3 Is there enough documentation? |
902b9dbf | 615 | |
04c692a8 DR |
616 | Patches without documentation are probably ill-thought out or |
617 | incomplete. No features can be added or changed without documentation, | |
618 | so submitting a patch for the appropriate pod docs as well as the | |
619 | source code is important. | |
902b9dbf | 620 | |
04c692a8 | 621 | =head3 Is there another way to do it? |
902b9dbf | 622 | |
04c692a8 DR |
623 | Larry said "Although the Perl Slogan is I<There's More Than One Way to |
624 | Do It>, I hesitate to make 10 ways to do something". This is a tricky | |
625 | heuristic to navigate, though--one man's essential addition is another | |
626 | man's pointless cruft. | |
902b9dbf | 627 | |
04c692a8 | 628 | =head3 Does it create too much work? |
902b9dbf | 629 | |
04c692a8 DR |
630 | Work for the pumpking, work for Perl programmers, work for module |
631 | authors, ... Perl is supposed to be easy. | |
902b9dbf | 632 | |
04c692a8 | 633 | =head3 Patches speak louder than words |
902b9dbf | 634 | |
04c692a8 DR |
635 | Working code is always preferred to pie-in-the-sky ideas. A patch to |
636 | add a feature stands a much higher chance of making it to the language | |
637 | than does a random feature request, no matter how fervently argued the | |
638 | request might be. This ties into "Will it be useful?", as the fact that | |
639 | someone took the time to make the patch demonstrates a strong desire | |
640 | for the feature. | |
c406981e | 641 | |
04c692a8 | 642 | =head1 TESTING |
c406981e | 643 | |
04c692a8 DR |
644 | The core uses the same testing style as the rest of Perl, a simple |
645 | "ok/not ok" run through Test::Harness, but there are a few special | |
646 | considerations. | |
c406981e | 647 | |
04c692a8 DR |
648 | There are three ways to write a test in the core. L<Test::More>, |
649 | F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. The | |
650 | decision of which to use depends on what part of the test suite you're | |
651 | working on. This is a measure to prevent a high-level failure (such as | |
652 | Config.pm breaking) from causing basic functionality tests to fail. | |
c406981e | 653 | |
04c692a8 DR |
654 | The F<t/test.pl> library provides some of the features of |
655 | L<Test::More>, but avoids loading most modules and uses as few core | |
656 | features as possible. | |
902b9dbf | 657 | |
04c692a8 | 658 | If you write your own test, use the L<Test Anything Protocol|TAP>. |
902b9dbf MLF |
659 | |
660 | =over 4 | |
661 | ||
04c692a8 | 662 | =item * F<t/base> and F<t/comp> |
902b9dbf | 663 | |
04c692a8 DR |
664 | Since we don't know if require works, or even subroutines, use ad hoc |
665 | tests for these two. Step carefully to avoid using the feature being | |
666 | tested. | |
902b9dbf | 667 | |
04c692a8 | 668 | =item * F<t/cmd>, F<t/run> F<t/io>, and F<t/op> |
902b9dbf | 669 | |
04c692a8 DR |
670 | Now that basic require() and subroutines are tested, you can use the |
671 | F<t/test.pl> library. | |
902b9dbf | 672 | |
04c692a8 DR |
673 | You can also use certain libraries like Config conditionally , but be |
674 | sure to skip the test gracefully if it's not there. | |
902b9dbf | 675 | |
04c692a8 | 676 | =item * Everything else |
902b9dbf | 677 | |
04c692a8 DR |
678 | Now that the core of Perl is tested, L<Test::More> can and should be |
679 | used. You can also use the full suite of core modules in the tests. | |
902b9dbf MLF |
680 | |
681 | =back | |
682 | ||
04c692a8 DR |
683 | When you say "make test" Perl uses the F<t/TEST> program to run the |
684 | test suite (except under Win32 where it uses F<t/harness> instead.) All | |
685 | tests are run from the F<t/> directory, B<not> the directory which | |
686 | contains the test. This causes some problems with the tests in F<lib/>, | |
687 | so here's some opportunity for some patching. | |
902b9dbf | 688 | |
04c692a8 DR |
689 | You must be triply conscious of cross-platform concerns. This usually |
690 | boils down to using L<File::Spec> and avoiding things like C<fork()> | |
691 | and C<system()> unless absolutely necessary. | |
7a834142 | 692 | |
04c692a8 | 693 | =head2 Special C<make test> targets |
07aa3531 | 694 | |
04c692a8 DR |
695 | There are various special make targets that can be used to test Perl |
696 | slightly differently than the standard "test" target. Not all them are | |
697 | expected to give a 100% success rate. Many of them have several | |
698 | aliases, and many of them are not available on certain operating | |
699 | systems. | |
07aa3531 | 700 | |
04c692a8 | 701 | =over 4 |
d44161bf | 702 | |
04c692a8 | 703 | =item * test_porting |
7a834142 | 704 | |
04c692a8 DR |
705 | This runs some basic sanity tests on the source tree and helps catch |
706 | basic errors before you submit a patch. | |
7a834142 | 707 | |
04c692a8 | 708 | =item * coretest |
7a834142 | 709 | |
04c692a8 | 710 | Run F<perl> on all core tests (F<t/*> and F<lib/[a-z]*> pragma tests). |
09187cb1 | 711 | |
04c692a8 | 712 | (Not available on Win32) |
09187cb1 | 713 | |
04c692a8 | 714 | =item * test.deparse |
09187cb1 | 715 | |
04c692a8 | 716 | Run all the tests through L<B::Deparse>. Not all tests will succeed. |
64cea5fd | 717 | |
04c692a8 | 718 | (Not available on Win32) |
64cea5fd | 719 | |
04c692a8 | 720 | =item * test.taintwarn |
64cea5fd | 721 | |
04c692a8 DR |
722 | Run all tests with the B<-t> command-line switch. Not all tests are |
723 | expected to succeed (until they're specifically fixed, of course). | |
51a35ef1 | 724 | |
04c692a8 | 725 | (Not available on Win32) |
51a35ef1 | 726 | |
04c692a8 | 727 | =item * minitest |
51a35ef1 | 728 | |
04c692a8 DR |
729 | Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>, |
730 | F<t/op>, F<t/uni> and F<t/mro> tests. | |
51a35ef1 | 731 | |
04c692a8 | 732 | =item * test.valgrind check.valgrind utest.valgrind ucheck.valgrind |
51a35ef1 | 733 | |
04c692a8 DR |
734 | (Only in Linux) Run all the tests using the memory leak + naughty |
735 | memory access tool "valgrind". The log files will be named | |
736 | F<testname.valgrind>. | |
83f0ef60 | 737 | |
04c692a8 | 738 | =item * test.torture torturetest |
83f0ef60 | 739 | |
04c692a8 DR |
740 | Run all the usual tests and some extra tests. As of Perl 5.8.0 the only |
741 | extra tests are Abigail's JAPHs, F<t/japh/abigail.t>. | |
83f0ef60 | 742 | |
04c692a8 DR |
743 | You can also run the torture test with F<t/harness> by giving |
744 | C<-torture> argument to F<t/harness>. | |
83f0ef60 | 745 | |
04c692a8 | 746 | =item * utest ucheck test.utf8 check.utf8 |
83f0ef60 | 747 | |
04c692a8 | 748 | Run all the tests with -Mutf8. Not all tests will succeed. |
83f0ef60 | 749 | |
04c692a8 | 750 | (Not available on Win32) |
83f0ef60 | 751 | |
04c692a8 | 752 | =item * minitest.utf16 test.utf16 |
83f0ef60 | 753 | |
04c692a8 DR |
754 | Runs the tests with UTF-16 encoded scripts, encoded with different |
755 | versions of this encoding. | |
83f0ef60 | 756 | |
04c692a8 DR |
757 | C<make utest.utf16> runs the test suite with a combination of C<-utf8> |
758 | and C<-utf16> arguments to F<t/TEST>. | |
83f0ef60 | 759 | |
04c692a8 | 760 | (Not available on Win32) |
83f0ef60 | 761 | |
04c692a8 | 762 | =item * test_harness |
83f0ef60 | 763 | |
04c692a8 DR |
764 | Run the test suite with the F<t/harness> controlling program, instead |
765 | of F<t/TEST>. F<t/harness> is more sophisticated, and uses the | |
766 | L<Test::Harness> module, thus using this test target supposes that perl | |
767 | mostly works. The main advantage for our purposes is that it prints a | |
768 | detailed summary of failed tests at the end. Also, unlike F<t/TEST>, it | |
769 | doesn't redirect stderr to stdout. | |
83f0ef60 | 770 | |
04c692a8 DR |
771 | Note that under Win32 F<t/harness> is always used instead of F<t/TEST>, |
772 | so there is no special "test_harness" target. | |
83f0ef60 | 773 | |
04c692a8 DR |
774 | Under Win32's "test" target you may use the TEST_SWITCHES and |
775 | TEST_FILES environment variables to control the behaviour of | |
776 | F<t/harness>. This means you can say | |
83f0ef60 | 777 | |
04c692a8 DR |
778 | nmake test TEST_FILES="op/*.t" |
779 | nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t" | |
83f0ef60 JH |
780 | |
781 | =back | |
782 | ||
04c692a8 | 783 | =head2 Parallel tests |
83f0ef60 | 784 | |
04c692a8 DR |
785 | The core distribution can now run its regression tests in parallel on |
786 | Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> | |
787 | in your environment to the number of tests to run in parallel, and run | |
788 | C<make test_harness>. On a Bourne-like shell, this can be done as | |
07aa3531 | 789 | |
04c692a8 | 790 | TEST_JOBS=3 make test_harness # Run 3 tests in parallel |
07aa3531 | 791 | |
04c692a8 DR |
792 | An environment variable is used, rather than parallel make itself, |
793 | because L<TAP::Harness> needs to be able to schedule individual | |
794 | non-conflicting test scripts itself, and there is no standard interface | |
795 | to C<make> utilities to interact with their job schedulers. | |
51a35ef1 | 796 | |
04c692a8 DR |
797 | Note that currently some test scripts may fail when run in parallel (most |
798 | notably C<ext/IO/t/io_dir.t>). If necessary run just the failing scripts | |
799 | again sequentially and see if the failures go away. | |
800 | =item * test-notty test_notty | |
51a35ef1 | 801 | |
04c692a8 | 802 | Sets PERL_SKIP_TTY_TEST to true before running normal test. |
51a35ef1 | 803 | |
04c692a8 | 804 | =head2 Running tests by hand |
51a35ef1 | 805 | |
04c692a8 DR |
806 | You can run part of the test suite by hand by using one the following |
807 | commands from the F<t/> directory : | |
51a35ef1 | 808 | |
04c692a8 | 809 | ./perl -I../lib TEST list-of-.t-files |
51a35ef1 | 810 | |
04c692a8 | 811 | or |
51a35ef1 | 812 | |
04c692a8 | 813 | ./perl -I../lib harness list-of-.t-files |
51a35ef1 | 814 | |
04c692a8 | 815 | (if you don't specify test scripts, the whole test suite will be run.) |
51a35ef1 | 816 | |
04c692a8 | 817 | =head2 Using F<t/harness> for testing |
51a35ef1 | 818 | |
04c692a8 DR |
819 | If you use C<harness> for testing you have several command line options |
820 | available to you. The arguments are as follows, and are in the order | |
821 | that they must appear if used together. | |
51a35ef1 | 822 | |
04c692a8 DR |
823 | harness -v -torture -re=pattern LIST OF FILES TO TEST |
824 | harness -v -torture -re LIST OF PATTERNS TO MATCH | |
07aa3531 | 825 | |
04c692a8 DR |
826 | If C<LIST OF FILES TO TEST> is omitted the file list is obtained from |
827 | the manifest. The file list may include shell wildcards which will be | |
828 | expanded out. | |
07aa3531 | 829 | |
04c692a8 | 830 | =over 4 |
4ae3d70a | 831 | |
04c692a8 | 832 | =item * -v |
4ae3d70a | 833 | |
04c692a8 DR |
834 | Run the tests under verbose mode so you can see what tests were run, |
835 | and debug output. | |
51a35ef1 | 836 | |
04c692a8 | 837 | =item * -torture |
4ae3d70a | 838 | |
04c692a8 | 839 | Run the torture tests as well as the normal set. |
4ae3d70a | 840 | |
04c692a8 | 841 | =item * -re=PATTERN |
6c41479b | 842 | |
04c692a8 DR |
843 | Filter the file list so that all the test files run match PATTERN. Note |
844 | that this form is distinct from the B<-re LIST OF PATTERNS> form below | |
845 | in that it allows the file list to be provided as well. | |
6c41479b | 846 | |
04c692a8 | 847 | =item * -re LIST OF PATTERNS |
6c41479b | 848 | |
04c692a8 DR |
849 | Filter the file list so that all the test files run match |
850 | /(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined | |
851 | by '|' and you cannot supply a list of files, instead the test files | |
852 | are obtained from the MANIFEST. | |
6c41479b | 853 | |
04c692a8 | 854 | =back |
6c41479b | 855 | |
04c692a8 | 856 | You can run an individual test by a command similar to |
6c41479b | 857 | |
04c692a8 | 858 | ./perl -I../lib patho/to/foo.t |
6c41479b | 859 | |
04c692a8 DR |
860 | except that the harnesses set up some environment variables that may |
861 | affect the execution of the test: | |
6c41479b JH |
862 | |
863 | =over 4 | |
864 | ||
04c692a8 | 865 | =item * PERL_CORE=1 |
6c41479b | 866 | |
04c692a8 DR |
867 | indicates that we're running this test part of the perl core test |
868 | suite. This is useful for modules that have a dual life on CPAN. | |
6c41479b | 869 | |
04c692a8 | 870 | =item * PERL_DESTRUCT_LEVEL=2 |
6c41479b | 871 | |
04c692a8 DR |
872 | is set to 2 if it isn't set already (see |
873 | L<perlhacktips/PERL_DESTRUCT_LEVEL>) | |
6c41479b | 874 | |
04c692a8 | 875 | =item * PERL |
6c41479b | 876 | |
04c692a8 DR |
877 | (used only by F<t/TEST>) if set, overrides the path to the perl |
878 | executable that should be used to run the tests (the default being | |
879 | F<./perl>). | |
6c41479b | 880 | |
04c692a8 | 881 | =item * PERL_SKIP_TTY_TEST |
6c41479b | 882 | |
04c692a8 DR |
883 | if set, tells to skip the tests that need a terminal. It's actually set |
884 | automatically by the Makefile, but can also be forced artificially by | |
885 | running 'make test_notty'. | |
6c41479b | 886 | |
04c692a8 | 887 | =back |
6c41479b | 888 | |
04c692a8 | 889 | =head3 Other environment variables that may influence tests |
6c41479b | 890 | |
04c692a8 | 891 | =over 4 |
6c41479b | 892 | |
04c692a8 | 893 | =item * PERL_TEST_Net_Ping |
6c41479b | 894 | |
04c692a8 DR |
895 | Setting this variable runs all the Net::Ping modules tests, otherwise |
896 | some tests that interact with the outside world are skipped. See | |
897 | L<perl58delta>. | |
6c41479b | 898 | |
04c692a8 | 899 | =item * PERL_TEST_NOVREXX |
cce04beb | 900 | |
04c692a8 | 901 | Setting this variable skips the vrexx.t tests for OS2::REXX. |
cce04beb | 902 | |
04c692a8 | 903 | =item * PERL_TEST_NUMCONVERTS |
cce04beb | 904 | |
04c692a8 | 905 | This sets a variable in op/numconvert.t. |
cce04beb | 906 | |
04c692a8 | 907 | =back |
cce04beb | 908 | |
04c692a8 DR |
909 | See also the documentation for the Test and Test::Harness modules, for |
910 | more environment variables that affect testing. | |
cce04beb | 911 | |
04c692a8 | 912 | =head1 MORE READING FOR GUTS HACKERS |
cce04beb | 913 | |
04c692a8 | 914 | To hack on the Perl guts, you'll need to read the following things: |
cce04beb | 915 | |
04c692a8 | 916 | =over 4 |
cce04beb | 917 | |
04c692a8 | 918 | =item * L<perlsource> |
b8ddf6b3 | 919 | |
04c692a8 DR |
920 | An overview of the Perl source tree. This will help you find the files |
921 | you're looking for. | |
b8ddf6b3 | 922 | |
04c692a8 | 923 | =item * L<perlinterp> |
b8ddf6b3 | 924 | |
04c692a8 DR |
925 | An overview of the Perl interpreter source code and some details on how |
926 | Perl does what it does. | |
b8ddf6b3 | 927 | |
04c692a8 | 928 | =item * L<perlhacktut> |
b8ddf6b3 | 929 | |
04c692a8 DR |
930 | This document walks through the creation of a small patch to Perl's C |
931 | code. If you're just getting started with Perl core hacking, this will | |
932 | help you understand how it works. | |
b8ddf6b3 | 933 | |
04c692a8 | 934 | =item * L<perlhacktips> |
b8ddf6b3 | 935 | |
04c692a8 DR |
936 | More details on hacking the Perl core. This document focuses on lower |
937 | level details such as how to write tests, compilation issues, | |
938 | portability, debugging, etc. | |
b8ddf6b3 | 939 | |
04c692a8 | 940 | If you plan on doing serious C hacking, make sure to read this. |
b8ddf6b3 | 941 | |
04c692a8 | 942 | =item * L<perlguts> |
b8ddf6b3 | 943 | |
04c692a8 DR |
944 | This is of paramount importance, since it's the documentation of what |
945 | goes where in the Perl source. Read it over a couple of times and it | |
946 | might start to make sense - don't worry if it doesn't yet, because the | |
947 | best way to study it is to read it in conjunction with poking at Perl | |
948 | source, and we'll do that later on. | |
b8ddf6b3 | 949 | |
04c692a8 DR |
950 | Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very |
951 | helpful pictures: | |
9965345d | 952 | |
04c692a8 | 953 | L<http://search.cpan.org/dist/illguts/> |
9965345d | 954 | |
04c692a8 | 955 | =item * L<perlxstut> and L<perlxs> |
f1fac472 | 956 | |
04c692a8 DR |
957 | A working knowledge of XSUB programming is incredibly useful for core |
958 | hacking; XSUBs use techniques drawn from the PP code, the portion of | |
959 | the guts that actually executes a Perl program. It's a lot gentler to | |
960 | learn those techniques from simple examples and explanation than from | |
961 | the core itself. | |
f1fac472 | 962 | |
04c692a8 | 963 | =item * L<perlapi> |
f1fac472 | 964 | |
04c692a8 DR |
965 | The documentation for the Perl API explains what some of the internal |
966 | functions do, as well as the many macros used in the source. | |
f1fac472 | 967 | |
04c692a8 | 968 | =item * F<Porting/pumpkin.pod> |
f1fac472 | 969 | |
04c692a8 DR |
970 | This is a collection of words of wisdom for a Perl porter; some of it |
971 | is only useful to the pumpkin holder, but most of it applies to anyone | |
972 | wanting to go about Perl development. | |
f1fac472 | 973 | |
04c692a8 | 974 | =item * The perl5-porters FAQ |
f1fac472 | 975 | |
04c692a8 DR |
976 | This should be available from |
977 | http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on | |
978 | reading perl5-porters, information on how perl5-porters works and how | |
979 | Perl development in general works. | |
f1fac472 | 980 | |
04c692a8 | 981 | =back |
f1fac472 | 982 | |
04c692a8 | 983 | =head1 CPAN TESTERS AND PERL SMOKERS |
f1fac472 | 984 | |
04c692a8 DR |
985 | The CPAN testers ( http://testers.cpan.org/ ) are a group of volunteers |
986 | who test CPAN modules on a variety of platforms. | |
b8ddf6b3 | 987 | |
04c692a8 DR |
988 | Perl Smokers (http://www.nntp.perl.org/group/perl.daily-build and |
989 | http://www.nntp.perl.org/group/perl.daily-build.reports/ ) | |
990 | automatically test Perl source releases on platforms with various | |
991 | configurations. | |
f1fac472 | 992 | |
04c692a8 DR |
993 | Both efforts welcome volunteers. In order to get involved in smoke |
994 | testing of the perl itself visit | |
995 | L<http://search.cpan.org/dist/Test-Smoke>. In order to start smoke | |
996 | testing CPAN modules visit | |
997 | L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or | |
998 | L<http://search.cpan.org/dist/minismokebox/> or | |
999 | L<http://search.cpan.org/dist/CPAN-Reporter/>. | |
f1fac472 | 1000 | |
04c692a8 | 1001 | =head1 WHAT NEXT? |
a422fd2d | 1002 | |
04c692a8 DR |
1003 | If you've read all the documentation in the document and the ones |
1004 | listed above, you're more than ready to hack on Perl. | |
a422fd2d | 1005 | |
04c692a8 | 1006 | Here's some more recommendations |
a422fd2d | 1007 | |
04c692a8 | 1008 | =over 4 |
a422fd2d SC |
1009 | |
1010 | =item * | |
1011 | ||
1012 | Subscribe to perl5-porters, follow the patches and try and understand | |
1013 | them; don't be afraid to ask if there's a portion you're not clear on - | |
1014 | who knows, you may unearth a bug in the patch... | |
1015 | ||
1016 | =item * | |
1017 | ||
04c692a8 DR |
1018 | Do read the README associated with your operating system, e.g. |
1019 | README.aix on the IBM AIX OS. Don't hesitate to supply patches to that | |
1020 | README if you find anything missing or changed over a new OS release. | |
a1f349fd MB |
1021 | |
1022 | =item * | |
1023 | ||
a422fd2d SC |
1024 | Find an area of Perl that seems interesting to you, and see if you can |
1025 | work out how it works. Scan through the source, and step over it in the | |
1026 | debugger. Play, poke, investigate, fiddle! You'll probably get to | |
04c692a8 DR |
1027 | understand not just your chosen area but a much wider range of |
1028 | F<perl>'s activity as well, and probably sooner than you'd think. | |
a422fd2d SC |
1029 | |
1030 | =back | |
1031 | ||
04c692a8 | 1032 | =head2 "The Road goes ever on and on, down from the door where it began." |
a422fd2d | 1033 | |
04c692a8 DR |
1034 | If you can do these things, you've started on the long road to Perl |
1035 | porting. Thanks for wanting to help make Perl better - and happy | |
1036 | hacking! | |
a422fd2d | 1037 | |
4ac71550 TC |
1038 | =head2 Metaphoric Quotations |
1039 | ||
1040 | If you recognized the quote about the Road above, you're in luck. | |
1041 | ||
04c692a8 DR |
1042 | Most software projects begin each file with a literal description of |
1043 | each file's purpose. Perl instead begins each with a literary allusion | |
1044 | to that file's purpose. | |
4ac71550 | 1045 | |
04c692a8 DR |
1046 | Like chapters in many books, all top-level Perl source files (along |
1047 | with a few others here and there) begin with an epigramic inscription | |
1048 | that alludes, indirectly and metaphorically, to the material you're | |
1049 | about to read. | |
4ac71550 TC |
1050 | |
1051 | Quotations are taken from writings of J.R.R Tolkien pertaining to his | |
04c692a8 | 1052 | Legendarium, almost always from I<The Lord of the Rings>. Chapters and |
4ac71550 TC |
1053 | page numbers are given using the following editions: |
1054 | ||
1055 | =over 4 | |
1056 | ||
04c692a8 | 1057 | =item * |
4ac71550 | 1058 | |
04c692a8 DR |
1059 | I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary |
1060 | edition of 2007 was used, published in the UK by Harper Collins | |
1061 | Publishers and in the US by the Houghton Mifflin Company. | |
4ac71550 TC |
1062 | |
1063 | =item * | |
1064 | ||
04c692a8 DR |
1065 | I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover, |
1066 | 50th-anniversary edition of 2004 was used, published in the UK by | |
1067 | Harper Collins Publishers and in the US by the Houghton Mifflin | |
1068 | Company. | |
4ac71550 TC |
1069 | |
1070 | =item * | |
1071 | ||
04c692a8 DR |
1072 | I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously |
1073 | by his son and literary executor, C.J.R. Tolkien, being the 3rd of the | |
1074 | 12 volumes in Christopher's mammoth I<History of Middle Earth>. Page | |
1075 | numbers derive from the hardcover edition, first published in 1983 by | |
1076 | George Allen & Unwin; no page numbers changed for the special 3-volume | |
1077 | omnibus edition of 2002 or the various trade-paper editions, all again | |
1078 | now by Harper Collins or Houghton Mifflin. | |
4ac71550 TC |
1079 | |
1080 | =back | |
1081 | ||
04c692a8 DR |
1082 | Other JRRT books fair game for quotes would thus include I<The |
1083 | Adventures of Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>, | |
1084 | and I<The Tale of the Children of Hurin>, all but the first | |
1085 | posthumously assembled by CJRT. But I<The Lord of the Rings> itself is | |
1086 | perfectly fine and probably best to quote from, provided you can find a | |
1087 | suitable quote there. | |
4ac71550 | 1088 | |
04c692a8 DR |
1089 | So if you were to supply a new, complete, top-level source file to add |
1090 | to Perl, you should conform to this peculiar practice by yourself | |
1091 | selecting an appropriate quotation from Tolkien, retaining the original | |
1092 | spelling and punctuation and using the same format the rest of the | |
1093 | quotes are in. Indirect and oblique is just fine; remember, it's a | |
1094 | metaphor, so being meta is, after all, what it's for. | |
4ac71550 | 1095 | |
e8cd7eae GS |
1096 | =head1 AUTHOR |
1097 | ||
04c692a8 DR |
1098 | This document was originally written by Nathan Torkington, and is |
1099 | maintained by the perl5-porters mailing list. | |
b16c2e4a | 1100 |