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 | |
531e2078 | 13 | This document explains how Perl development works. It includes details |
04c692a8 DR |
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 | |
531e2078 | 27 | The perl source is in a git repository. You can clone the repository |
04c692a8 | 28 | with the following command: |
e018f8be | 29 | |
04c692a8 | 30 | % git clone git://perl5.git.perl.org/perl.git perl |
e018f8be | 31 | |
69434957 S |
32 | =item * Ensure you're following the latest advice |
33 | ||
34 | In case the advice in this guide has been updated recently, read the | |
35 | latest version directly from the perl source: | |
36 | ||
37 | % perldoc pod/perlhack.pod | |
38 | ||
04c692a8 | 39 | =item * Make your change |
e018f8be | 40 | |
eb9df707 KW |
41 | Hack, hack, hack. Keep in mind that Perl runs on many different |
42 | platforms, with different operating systems that have different | |
43 | capabilities, different filesystem organizations, and even different | |
44 | character sets. L<perlhacktips> gives advice on this. | |
7205a85d | 45 | |
04c692a8 | 46 | =item * Test your change |
e018f8be | 47 | |
04c692a8 | 48 | You can run all the tests with the following commands: |
b26492ee | 49 | |
04c692a8 DR |
50 | % ./Configure -des -Dusedevel |
51 | % make test | |
7205a85d | 52 | |
04c692a8 | 53 | Keep hacking until the tests pass. |
b26492ee | 54 | |
04c692a8 | 55 | =item * Commit your change |
e018f8be | 56 | |
b6538e4f | 57 | Committing your work will save the change I<on your local system>: |
7205a85d | 58 | |
04c692a8 | 59 | % git commit -a -m 'Commit message goes here' |
e018f8be | 60 | |
04c692a8 | 61 | Make sure the commit message describes your change in a single |
531e2078 | 62 | sentence. For example, "Fixed spelling errors in perlhack.pod". |
e018f8be | 63 | |
04c692a8 | 64 | =item * Send your change to perlbug |
7a834142 | 65 | |
04c692a8 DR |
66 | The next step is to submit your patch to the Perl core ticket system |
67 | via email. | |
7a834142 | 68 | |
84788b0a | 69 | If your changes are in a single git commit, run the following commands |
e7769b3e | 70 | to generate the patch file and attach it to your bug report: |
e018f8be | 71 | |
e7769b3e CB |
72 | % git format-patch -1 |
73 | % ./perl -Ilib utils/perlbug -p 0001-*.patch | |
e018f8be | 74 | |
04c692a8 | 75 | The perlbug program will ask you a few questions about your email |
531e2078 | 76 | address and the patch you're submitting. Once you've answered them it |
84b19098 | 77 | will submit your patch via email. |
e018f8be | 78 | |
e7769b3e CB |
79 | If your changes are in multiple commits, generate a patch file for each |
80 | one and provide them to perlbug's C<-p> option separated by commas: | |
2d1c9392 | 81 | |
e7769b3e CB |
82 | % git format-patch -3 |
83 | % ./perl -Ilib utils/perlbug -p 0001-fix1.patch,0002-fix2.patch,\ | |
84 | > 0003-fix3.patch | |
2d1c9392 | 85 | |
e7769b3e | 86 | When prompted, pick a subject that summarizes your changes. |
2d1c9392 | 87 | |
04c692a8 | 88 | =item * Thank you |
e018f8be | 89 | |
04c692a8 DR |
90 | The porters appreciate the time you spent helping to make Perl better. |
91 | Thank you! | |
e018f8be | 92 | |
bb288857 S |
93 | =item * Acknowledgement |
94 | ||
95 | All contributors are credited (by name and email address) in the | |
6cb72a3d S |
96 | AUTHORS file, which is part of the perl distribution, as well as the |
97 | Git commit history. | |
bb288857 S |
98 | |
99 | If you don’t want to be included in the AUTHORS file, just let us | |
100 | know. Otherwise we will take your submission of a patch as permission | |
101 | to credit you in the AUTHORS file. | |
102 | ||
e99cf3f0 S |
103 | =item * Next time |
104 | ||
105 | The next time you wish to make a patch, you need to start from the | |
30454452 | 106 | latest perl in a pristine state. Check you don't have any local changes |
e99cf3f0 S |
107 | or added files in your perl check-out which you wish to keep, then run |
108 | these commands: | |
109 | ||
110 | % git pull | |
111 | % git reset --hard origin/blead | |
112 | % git clean -dxf | |
113 | ||
cce04beb | 114 | =back |
e018f8be | 115 | |
04c692a8 | 116 | =head1 BUG REPORTING |
cc0710ff | 117 | |
9e6670f3 | 118 | If you want to report a bug in Perl, you must use the F<perlbug> |
531e2078 | 119 | command line tool. This tool will ensure that your bug report includes |
9e6670f3 | 120 | all the relevant system and configuration information. |
7205a85d | 121 | |
04c692a8 | 122 | To browse existing Perl bugs and patches, you can use the web interface |
a8d15a22 | 123 | at L<http://rt.perl.org/>. |
244d9cb7 | 124 | |
04c692a8 | 125 | Please check the archive of the perl5-porters list (see below) and/or |
531e2078 | 126 | the bug tracking system before submitting a bug report. Often, you'll |
04c692a8 | 127 | find that the bug has been reported already. |
244d9cb7 | 128 | |
04c692a8 | 129 | You can log in to the bug tracking system and comment on existing bug |
531e2078 FC |
130 | reports. If you have additional information regarding an existing bug, |
131 | please add it. This will help the porters fix the bug. | |
7205a85d | 132 | |
04c692a8 | 133 | =head1 PERL 5 PORTERS |
7205a85d | 134 | |
04c692a8 | 135 | The perl5-porters (p5p) mailing list is where the Perl standard |
531e2078 | 136 | distribution is maintained and developed. The people who maintain Perl |
9e6670f3 DR |
137 | are also referred to as the "Perl 5 Porters", "p5p" or just the |
138 | "porters". | |
a75f557c | 139 | |
04c692a8 | 140 | A searchable archive of the list is available at |
586e992d | 141 | L<http://markmail.org/search/?q=perl5-porters>. There is also an archive at |
04c692a8 | 142 | L<http://archive.develooper.com/perl5-porters@perl.org/>. |
7205a85d | 143 | |
04c692a8 | 144 | =head2 perl-changes mailing list |
7205a85d | 145 | |
04c692a8 DR |
146 | The perl5-changes mailing list receives a copy of each patch that gets |
147 | submitted to the maintenance and development branches of the perl | |
531e2078 | 148 | repository. See L<http://lists.perl.org/list/perl5-changes.html> for |
04c692a8 | 149 | subscription and archive information. |
244d9cb7 | 150 | |
37bf3a91 DR |
151 | =head2 #p5p on IRC |
152 | ||
153 | Many porters are also active on the L<irc://irc.perl.org/#p5p> channel. | |
154 | Feel free to join the channel and ask questions about hacking on the | |
155 | Perl core. | |
156 | ||
04c692a8 | 157 | =head1 GETTING THE PERL SOURCE |
244d9cb7 | 158 | |
04c692a8 | 159 | All of Perl's source code is kept centrally in a Git repository at |
a44b8c28 S |
160 | I<perl5.git.perl.org>. The repository contains many Perl revisions |
161 | from Perl 1 onwards and all the revisions from Perforce, the previous | |
04c692a8 | 162 | version control system. |
244d9cb7 | 163 | |
04c692a8 DR |
164 | For much more detail on using git with the Perl repository, please see |
165 | L<perlgit>. | |
244d9cb7 | 166 | |
04c692a8 | 167 | =head2 Read access via Git |
244d9cb7 | 168 | |
531e2078 | 169 | You will need a copy of Git for your computer. You can fetch a copy of |
04c692a8 | 170 | the repository using the git protocol: |
244d9cb7 | 171 | |
04c692a8 | 172 | % git clone git://perl5.git.perl.org/perl.git perl |
244d9cb7 | 173 | |
04c692a8 DR |
174 | This clones the repository and makes a local copy in the F<perl> |
175 | directory. | |
7205a85d | 176 | |
04c692a8 DR |
177 | If you cannot use the git protocol for firewall reasons, you can also |
178 | clone via http, though this is much slower: | |
7205a85d | 179 | |
04c692a8 | 180 | % git clone http://perl5.git.perl.org/perl.git perl |
7205a85d | 181 | |
04c692a8 | 182 | =head2 Read access via the web |
7205a85d | 183 | |
531e2078 | 184 | You may access the repository over the web. This allows you to browse |
04c692a8 | 185 | the tree, see recent commits, subscribe to RSS feeds for the changes, |
531e2078 FC |
186 | search for particular commits and more. You may access it at |
187 | L<http://perl5.git.perl.org/perl.git>. A mirror of the repository is | |
b0959619 | 188 | found at L<https://github.com/Perl/perl5>. |
7205a85d | 189 | |
04c692a8 | 190 | =head2 Read access via rsync |
7205a85d | 191 | |
04c692a8 DR |
192 | You can also choose to use rsync to get a copy of the current source |
193 | tree for the bleadperl branch and all maintenance branches: | |
7205a85d | 194 | |
7eac65da S |
195 | % rsync -avz rsync://perl5.git.perl.org/perl-current . |
196 | % rsync -avz rsync://perl5.git.perl.org/perl-5.12.x . | |
197 | % rsync -avz rsync://perl5.git.perl.org/perl-5.10.x . | |
198 | % rsync -avz rsync://perl5.git.perl.org/perl-5.8.x . | |
199 | % rsync -avz rsync://perl5.git.perl.org/perl-5.6.x . | |
200 | % rsync -avz rsync://perl5.git.perl.org/perl-5.005xx . | |
7205a85d | 201 | |
a8d15a22 | 202 | (Add the C<--delete> option to remove leftover files.) |
7205a85d | 203 | |
04c692a8 | 204 | To get a full list of the available sync points: |
7205a85d | 205 | |
7eac65da | 206 | % rsync perl5.git.perl.org:: |
7205a85d | 207 | |
04c692a8 | 208 | =head2 Write access via git |
7205a85d | 209 | |
04c692a8 DR |
210 | If you have a commit bit, please see L<perlgit> for more details on |
211 | using git. | |
7205a85d | 212 | |
04c692a8 | 213 | =head1 PATCHING PERL |
7205a85d | 214 | |
04c692a8 | 215 | If you're planning to do more extensive work than a single small fix, |
531e2078 | 216 | we encourage you to read the documentation below. This will help you |
04c692a8 DR |
217 | focus your work and make your patches easier to incorporate into the |
218 | Perl source. | |
244d9cb7 | 219 | |
04c692a8 | 220 | =head2 Submitting patches |
244d9cb7 | 221 | |
531e2078 FC |
222 | If you have a small patch to submit, please submit it via perlbug. You |
223 | can also send email directly to perlbug@perl.org. Please note that | |
04c692a8 DR |
224 | messages sent to perlbug may be held in a moderation queue, so you |
225 | won't receive a response immediately. | |
244d9cb7 | 226 | |
04c692a8 | 227 | You'll know your submission has been processed when you receive an |
531e2078 FC |
228 | email from our ticket tracking system. This email will give you a |
229 | ticket number. Once your patch has made it to the ticket tracking | |
04c692a8 | 230 | system, it will also be sent to the perl5-porters@perl.org list. |
244d9cb7 | 231 | |
c1c824fc MF |
232 | If your patch is related to an already-opened ticket you can also |
233 | attach your patch to that ticket, without having to use perlbug. | |
234 | ||
531e2078 | 235 | Patches are reviewed and discussed on the p5p list. Simple, |
04c692a8 DR |
236 | uncontroversial patches will usually be applied without any discussion. |
237 | When the patch is applied, the ticket will be updated and you will | |
531e2078 | 238 | receive email. In addition, an email will be sent to the p5p list. |
244d9cb7 | 239 | |
531e2078 | 240 | In other cases, the patch will need more work or discussion. That will |
04c692a8 | 241 | happen on the p5p list. |
244d9cb7 | 242 | |
04c692a8 | 243 | You are encouraged to participate in the discussion and advocate for |
531e2078 | 244 | your patch. Sometimes your patch may get lost in the shuffle. It's |
04c692a8 | 245 | appropriate to send a reminder email to p5p if no action has been taken |
531e2078 | 246 | in a month. Please remember that the Perl 5 developers are all |
04c692a8 | 247 | volunteers, and be polite. |
244d9cb7 | 248 | |
04c692a8 | 249 | Changes are always applied directly to the main development branch, |
a44b8c28 | 250 | called "blead". Some patches may be backported to a maintenance |
30454452 | 251 | branch. If you think your patch is appropriate for the maintenance |
839a0e5a | 252 | branch (see L<perlpolicy/MAINTENANCE BRANCHES>), please explain why |
d0bba22e | 253 | when you submit it. |
244d9cb7 | 254 | |
04c692a8 | 255 | =head2 Getting your patch accepted |
244d9cb7 | 256 | |
84c2f6fd DR |
257 | If you are submitting a code patch there are several things that you |
258 | can do to help the Perl 5 Porters accept your patch. | |
244d9cb7 | 259 | |
a126fb62 DR |
260 | =head3 Patch style |
261 | ||
262 | If you used git to check out the Perl source, then using C<git | |
531e2078 | 263 | format-patch> will produce a patch in a style suitable for Perl. The |
a126fb62 | 264 | C<format-patch> command produces one patch file for each commit you |
a44b8c28 S |
265 | made. If you prefer to send a single patch for all commits, you can |
266 | use C<git diff>. | |
a126fb62 | 267 | |
9d440a18 | 268 | % git checkout blead |
a126fb62 DR |
269 | % git pull |
270 | % git diff blead my-branch-name | |
271 | ||
272 | This produces a patch based on the difference between blead and your | |
531e2078 | 273 | current branch. It's important to make sure that blead is up to date |
a126fb62 DR |
274 | before producing the diff, that's why we call C<git pull> first. |
275 | ||
531e2078 | 276 | We strongly recommend that you use git if possible. It will make your |
a126fb62 DR |
277 | life easier, and ours as well. |
278 | ||
279 | However, if you're not using git, you can still produce a suitable | |
531e2078 FC |
280 | patch. You'll need a pristine copy of the Perl source to diff against. |
281 | The porters prefer unified diffs. Using GNU C<diff>, you can produce a | |
a126fb62 DR |
282 | diff like this: |
283 | ||
284 | % diff -Npurd perl.pristine perl.mine | |
285 | ||
286 | Make sure that you C<make realclean> in your copy of Perl to remove any | |
287 | build artifacts, or you may get a confusing result. | |
288 | ||
04c692a8 | 289 | =head3 Commit message |
244d9cb7 | 290 | |
04c692a8 | 291 | As you craft each patch you intend to submit to the Perl core, it's |
531e2078 | 292 | important to write a good commit message. This is especially important |
04c692a8 | 293 | if your submission will consist of a series of commits. |
244d9cb7 | 294 | |
04c692a8 | 295 | The first line of the commit message should be a short description |
531e2078 | 296 | without a period. It should be no longer than the subject line of an |
a8d15a22 | 297 | email, 50 characters being a good rule of thumb. |
f7e1e956 | 298 | |
a8d15a22 | 299 | A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will |
04c692a8 DR |
300 | only display the first line (cut off at 50 characters) when presenting |
301 | commit summaries. | |
7cd58830 | 302 | |
04c692a8 DR |
303 | The commit message should include a description of the problem that the |
304 | patch corrects or new functionality that the patch adds. | |
7cd58830 | 305 | |
04c692a8 DR |
306 | As a general rule of thumb, your commit message should help a |
307 | programmer who knows the Perl core quickly understand what you were | |
308 | trying to do, how you were trying to do it, and why the change matters | |
309 | to Perl. | |
7cd58830 | 310 | |
04c692a8 | 311 | =over 4 |
7cd58830 | 312 | |
04c692a8 | 313 | =item * Why |
7cd58830 | 314 | |
04c692a8 | 315 | Your commit message should describe why the change you are making is |
531e2078 | 316 | important. When someone looks at your change in six months or six |
04c692a8 | 317 | years, your intent should be clear. |
7cd58830 | 318 | |
04c692a8 | 319 | If you're deprecating a feature with the intent of later simplifying |
531e2078 | 320 | another bit of code, say so. If you're fixing a performance problem or |
04c692a8 DR |
321 | adding a new feature to support some other bit of the core, mention |
322 | that. | |
7cd58830 | 323 | |
04c692a8 | 324 | =item * What |
7cd58830 | 325 | |
04c692a8 DR |
326 | Your commit message should describe what part of the Perl core you're |
327 | changing and what you expect your patch to do. | |
7cd58830 | 328 | |
04c692a8 | 329 | =item * How |
7cd58830 | 330 | |
04c692a8 DR |
331 | While it's not necessary for documentation changes, new tests or |
332 | trivial patches, it's often worth explaining how your change works. | |
333 | Even if it's clear to you today, it may not be clear to a porter next | |
334 | month or next year. | |
d7889f52 | 335 | |
04c692a8 | 336 | =back |
d7889f52 | 337 | |
04c692a8 | 338 | A commit message isn't intended to take the place of comments in your |
531e2078 | 339 | code. Commit messages should describe the change you made, while code |
04c692a8 | 340 | comments should describe the current state of the code. |
d7889f52 | 341 | |
04c692a8 | 342 | If you've just implemented a new feature, complete with doc, tests and |
531e2078 | 343 | well-commented code, a brief commit message will often suffice. If, |
04c692a8 DR |
344 | however, you've just changed a single character deep in the parser or |
345 | lexer, you might need to write a small novel to ensure that future | |
346 | readers understand what you did and why you did it. | |
d7889f52 | 347 | |
04c692a8 | 348 | =head3 Comments, Comments, Comments |
d7889f52 | 349 | |
a44b8c28 S |
350 | Be sure to adequately comment your code. While commenting every line |
351 | is unnecessary, anything that takes advantage of side effects of | |
04c692a8 DR |
352 | operators, that creates changes that will be felt outside of the |
353 | function being patched, or that others may find confusing should be | |
a44b8c28 S |
354 | documented. If you are going to err, it is better to err on the side |
355 | of adding too many comments than too few. | |
d7889f52 | 356 | |
04c692a8 DR |
357 | The best comments explain I<why> the code does what it does, not I<what |
358 | it does>. | |
d7889f52 | 359 | |
04c692a8 | 360 | =head3 Style |
d7889f52 | 361 | |
04c692a8 DR |
362 | In general, please follow the particular style of the code you are |
363 | patching. | |
d7889f52 | 364 | |
04c692a8 DR |
365 | In particular, follow these general guidelines for patching Perl |
366 | sources: | |
cce04beb | 367 | |
04c692a8 | 368 | =over 4 |
d7889f52 JH |
369 | |
370 | =item * | |
371 | ||
0529658c AL |
372 | 4-wide indents for code, 2-wide indents for nested CPP C<#define>s, |
373 | with 8-wide tabstops. | |
d7889f52 JH |
374 | |
375 | =item * | |
376 | ||
0529658c AL |
377 | Use spaces for indentation, not tab characters. |
378 | ||
379 | The codebase is a mixture of tabs and spaces for indentation, and we | |
380 | are moving to spaces only. Converting lines you're patching from 8-wide | |
381 | tabs to spaces will help this migration. | |
ee9468a2 | 382 | |
cce04beb | 383 | =item * |
ee9468a2 | 384 | |
04c692a8 | 385 | Try hard not to exceed 79-columns |
bc028b6b | 386 | |
ee9468a2 RGS |
387 | =item * |
388 | ||
04c692a8 | 389 | ANSI C prototypes |
d7889f52 JH |
390 | |
391 | =item * | |
392 | ||
04c692a8 | 393 | Uncuddled elses and "K&R" style for indenting control constructs |
0bec6c03 | 394 | |
04c692a8 | 395 | =item * |
d7889f52 | 396 | |
04c692a8 | 397 | No C++ style (//) comments |
d7889f52 JH |
398 | |
399 | =item * | |
400 | ||
04c692a8 | 401 | Mark places that need to be revisited with XXX (and revisit often!) |
27565cb6 JH |
402 | |
403 | =item * | |
404 | ||
04c692a8 DR |
405 | Opening brace lines up with "if" when conditional spans multiple lines; |
406 | should be at end-of-line otherwise | |
27565cb6 | 407 | |
04c692a8 | 408 | =item * |
27565cb6 | 409 | |
15c526cb | 410 | In function definitions, name starts in column 0 (return value-type is on |
04c692a8 | 411 | previous line) |
27565cb6 | 412 | |
04c692a8 | 413 | =item * |
27565cb6 | 414 | |
04c692a8 DR |
415 | Single space after keywords that are followed by parens, no space |
416 | between function name and following paren | |
606fd33d | 417 | |
27565cb6 JH |
418 | =item * |
419 | ||
04c692a8 DR |
420 | Avoid assignments in conditionals, but if they're unavoidable, use |
421 | extra paren, e.g. "if (a && (b = c)) ..." | |
27565cb6 JH |
422 | |
423 | =item * | |
424 | ||
04c692a8 | 425 | "return foo;" rather than "return(foo);" |
27565cb6 JH |
426 | |
427 | =item * | |
428 | ||
04c692a8 | 429 | "if (!foo) ..." rather than "if (foo == FALSE) ..." etc. |
606fd33d | 430 | |
a8bd0d47 KW |
431 | =item * |
432 | ||
433 | Do not declare variables using "register". It may be counterproductive | |
434 | with modern compilers, and is deprecated in C++, under which the Perl | |
435 | source is regularly compiled. | |
436 | ||
5b48d9bb KW |
437 | =item * |
438 | ||
439 | In-line functions that are in headers that are accessible to XS code | |
440 | need to be able to compile without warnings with commonly used extra | |
441 | compilation flags, such as gcc's C<-Wswitch-default> which warns | |
442 | whenever a switch statement does not have a "default" case. The use of | |
a44b8c28 S |
443 | these extra flags is to catch potential problems in legal C code, and |
444 | is often used by Perl aggregators, such as Linux distributors. | |
5b48d9bb | 445 | |
606fd33d | 446 | =back |
27565cb6 | 447 | |
04c692a8 | 448 | =head3 Test suite |
d7889f52 | 449 | |
a8d15a22 | 450 | If your patch changes code (rather than just changing documentation), |
04c692a8 | 451 | you should also include one or more test cases which illustrate the bug |
531e2078 | 452 | you're fixing or validate the new functionality you're adding. In |
04c692a8 DR |
453 | general, you should update an existing test file rather than create a |
454 | new one. | |
2bbc8d55 | 455 | |
04c692a8 DR |
456 | Your test suite additions should generally follow these guidelines |
457 | (courtesy of Gurusamy Sarathy <gsar@activestate.com>): | |
2bbc8d55 | 458 | |
04c692a8 | 459 | =over 4 |
0bec6c03 | 460 | |
04c692a8 | 461 | =item * |
0bec6c03 | 462 | |
531e2078 | 463 | Know what you're testing. Read the docs, and the source. |
ee9468a2 RGS |
464 | |
465 | =item * | |
466 | ||
04c692a8 | 467 | Tend to fail, not succeed. |
0bec6c03 | 468 | |
04c692a8 | 469 | =item * |
0bec6c03 | 470 | |
04c692a8 | 471 | Interpret results strictly. |
27565cb6 | 472 | |
04c692a8 | 473 | =item * |
27565cb6 | 474 | |
04c692a8 | 475 | Use unrelated features (this will flush out bizarre interactions). |
27565cb6 | 476 | |
04c692a8 | 477 | =item * |
27565cb6 | 478 | |
04c692a8 | 479 | Use non-standard idioms (otherwise you are not testing TIMTOWTDI). |
27565cb6 | 480 | |
04c692a8 | 481 | =item * |
d7889f52 | 482 | |
04c692a8 DR |
483 | Avoid using hardcoded test numbers whenever possible (the EXPECTED/GOT |
484 | found in t/op/tie.t is much more maintainable, and gives better failure | |
485 | reports). | |
d7889f52 | 486 | |
04c692a8 | 487 | =item * |
d7889f52 | 488 | |
04c692a8 | 489 | Give meaningful error messages when a test fails. |
d7889f52 | 490 | |
04c692a8 | 491 | =item * |
d7889f52 | 492 | |
531e2078 | 493 | Avoid using qx// and system() unless you are testing for them. If you |
04c692a8 | 494 | do use them, make sure that you cover _all_ perl platforms. |
d7889f52 | 495 | |
04c692a8 | 496 | =item * |
0bec6c03 | 497 | |
04c692a8 | 498 | Unlink any temporary files you create. |
63796a85 | 499 | |
04c692a8 | 500 | =item * |
0bec6c03 | 501 | |
04c692a8 | 502 | Promote unforeseen warnings to errors with $SIG{__WARN__}. |
0bec6c03 | 503 | |
04c692a8 | 504 | =item * |
0bec6c03 | 505 | |
04c692a8 DR |
506 | Be sure to use the libraries and modules shipped with the version being |
507 | tested, not those that were already installed. | |
d7889f52 | 508 | |
04c692a8 | 509 | =item * |
d7889f52 | 510 | |
04c692a8 | 511 | Add comments to the code explaining what you are testing for. |
d7889f52 | 512 | |
04c692a8 | 513 | =item * |
d7889f52 | 514 | |
531e2078 | 515 | Make updating the '1..42' string unnecessary. Or make sure that you |
04c692a8 | 516 | update it. |
d7889f52 | 517 | |
04c692a8 | 518 | =item * |
d7889f52 | 519 | |
04c692a8 | 520 | Test _all_ behaviors of a given operator, library, or function. |
d7889f52 | 521 | |
04c692a8 | 522 | Test all optional arguments. |
d7889f52 | 523 | |
04c692a8 | 524 | Test return values in various contexts (boolean, scalar, list, lvalue). |
d7889f52 | 525 | |
04c692a8 | 526 | Use both global and lexical variables. |
d7889f52 | 527 | |
04c692a8 | 528 | Don't forget the exceptional, pathological cases. |
0bec6c03 | 529 | |
cce04beb | 530 | =back |
0bec6c03 | 531 | |
04c692a8 | 532 | =head2 Patching a core module |
ee9468a2 | 533 | |
04c692a8 DR |
534 | This works just like patching anything else, with one extra |
535 | consideration. | |
63796a85 | 536 | |
a8d15a22 | 537 | Modules in the F<cpan/> directory of the source tree are maintained |
531e2078 | 538 | outside of the Perl core. When the author updates the module, the |
24b68a05 DG |
539 | updates are simply copied into the core. See that module's |
540 | documentation or its listing on L<http://search.cpan.org/> for more | |
541 | information on reporting bugs and submitting patches. | |
542 | ||
543 | In most cases, patches to modules in F<cpan/> should be sent upstream | |
9e6670f3 DR |
544 | and should not be applied to the Perl core individually. If a patch to |
545 | a file in F<cpan/> absolutely cannot wait for the fix to be made | |
7e5887a1 DG |
546 | upstream, released to CPAN and copied to blead, you must add (or |
547 | update) a C<CUSTOMIZED> entry in the F<"Porting/Maintainers.pl"> file | |
548 | to flag that a local modification has been made. See | |
549 | F<"Porting/Maintainers.pl"> for more details. | |
63796a85 | 550 | |
04c692a8 DR |
551 | In contrast, modules in the F<dist/> directory are maintained in the |
552 | core. | |
63796a85 | 553 | |
04c692a8 | 554 | =head2 Updating perldelta |
63796a85 | 555 | |
04c692a8 DR |
556 | For changes significant enough to warrant a F<pod/perldelta.pod> entry, |
557 | the porters will greatly appreciate it if you submit a delta entry | |
a44b8c28 S |
558 | along with your actual change. Significant changes include, but are |
559 | not limited to: | |
63796a85 | 560 | |
04c692a8 | 561 | =over 4 |
63796a85 | 562 | |
04c692a8 | 563 | =item * |
63796a85 | 564 | |
04c692a8 | 565 | Adding, deprecating, or removing core features |
ee9468a2 | 566 | |
04c692a8 | 567 | =item * |
ee9468a2 | 568 | |
04c692a8 | 569 | Adding, deprecating, removing, or upgrading core or dual-life modules |
ee9468a2 | 570 | |
04c692a8 | 571 | =item * |
ee9468a2 | 572 | |
04c692a8 | 573 | Adding new core tests |
ee9468a2 | 574 | |
04c692a8 | 575 | =item * |
ee9468a2 | 576 | |
04c692a8 | 577 | Fixing security issues and user-visible bugs in the core |
cce04beb | 578 | |
04c692a8 | 579 | =item * |
ad7244db | 580 | |
04c692a8 | 581 | Changes that might break existing code, either on the perl or C level |
ad7244db JH |
582 | |
583 | =item * | |
584 | ||
04c692a8 | 585 | Significant performance improvements |
ad7244db JH |
586 | |
587 | =item * | |
588 | ||
04c692a8 DR |
589 | Adding, removing, or significantly changing documentation in the |
590 | F<pod/> directory | |
ad7244db | 591 | |
cce04beb | 592 | =item * |
ad7244db | 593 | |
04c692a8 | 594 | Important platform-specific changes |
d7889f52 | 595 | |
cce04beb DG |
596 | =back |
597 | ||
04c692a8 | 598 | Please make sure you add the perldelta entry to the right section |
531e2078 | 599 | within F<pod/perldelta.pod>. More information on how to write good |
04c692a8 DR |
600 | perldelta entries is available in the C<Style> section of |
601 | F<Porting/how_to_write_a_perldelta.pod>. | |
d7889f52 | 602 | |
04c692a8 | 603 | =head2 What makes for a good patch? |
d7889f52 | 604 | |
531e2078 | 605 | New features and extensions to the language can be contentious. There |
04c692a8 DR |
606 | is no specific set of criteria which determine what features get added, |
607 | but here are some questions to consider when developing a patch: | |
d7889f52 | 608 | |
04c692a8 | 609 | =head3 Does the concept match the general goals of Perl? |
d7889f52 | 610 | |
04c692a8 | 611 | Our goals include, but are not limited to: |
d7889f52 | 612 | |
04c692a8 | 613 | =over 4 |
d7889f52 | 614 | |
04c692a8 | 615 | =item 1. |
d7889f52 | 616 | |
04c692a8 | 617 | Keep it fast, simple, and useful. |
cce04beb | 618 | |
04c692a8 | 619 | =item 2. |
cce04beb | 620 | |
04c692a8 | 621 | Keep features/concepts as orthogonal as possible. |
902b9dbf | 622 | |
04c692a8 | 623 | =item 3. |
902b9dbf | 624 | |
04c692a8 | 625 | No arbitrary limits (platforms, data sizes, cultures). |
a958818a | 626 | |
04c692a8 | 627 | =item 4. |
ac036724 | 628 | |
04c692a8 | 629 | Keep it open and exciting to use/patch/advocate Perl everywhere. |
a958818a | 630 | |
04c692a8 | 631 | =item 5. |
a958818a | 632 | |
04c692a8 | 633 | Either assimilate new technologies, or build bridges to them. |
a958818a | 634 | |
04c692a8 | 635 | =back |
a958818a | 636 | |
04c692a8 | 637 | =head3 Where is the implementation? |
a958818a | 638 | |
531e2078 | 639 | All the talk in the world is useless without an implementation. In |
04c692a8 | 640 | almost every case, the person or people who argue for a new feature |
531e2078 | 641 | will be expected to be the ones who implement it. Porters capable of |
04c692a8 DR |
642 | coding new features have their own agendas, and are not available to |
643 | implement your (possibly good) idea. | |
a1b65709 | 644 | |
04c692a8 | 645 | =head3 Backwards compatibility |
37c0adeb | 646 | |
531e2078 | 647 | It's a cardinal sin to break existing Perl programs. New warnings can |
04c692a8 | 648 | be contentious--some say that a program that emits warnings is not |
531e2078 | 649 | broken, while others say it is. Adding keywords has the potential to |
04c692a8 DR |
650 | break programs, changing the meaning of existing token sequences or |
651 | functions might break programs. | |
f50e5b73 | 652 | |
04c692a8 DR |
653 | The Perl 5 core includes mechanisms to help porters make backwards |
654 | incompatible changes more compatible such as the L<feature> and | |
531e2078 | 655 | L<deprecate> modules. Please use them when appropriate. |
902b9dbf | 656 | |
04c692a8 | 657 | =head3 Could it be a module instead? |
902b9dbf | 658 | |
04c692a8 | 659 | Perl 5 has extension mechanisms, modules and XS, specifically to avoid |
531e2078 | 660 | the need to keep changing the Perl interpreter. You can write modules |
04c692a8 DR |
661 | that export functions, you can give those functions prototypes so they |
662 | can be called like built-in functions, you can even write XS code to | |
663 | mess with the runtime data structures of the Perl interpreter if you | |
664 | want to implement really complicated things. | |
902b9dbf | 665 | |
04c692a8 DR |
666 | Whenever possible, new features should be prototyped in a CPAN module |
667 | before they will be considered for the core. | |
902b9dbf | 668 | |
04c692a8 | 669 | =head3 Is the feature generic enough? |
902b9dbf | 670 | |
04c692a8 DR |
671 | Is this something that only the submitter wants added to the language, |
672 | or is it broadly useful? Sometimes, instead of adding a feature with a | |
673 | tight focus, the porters might decide to wait until someone implements | |
674 | the more generalized feature. | |
902b9dbf | 675 | |
04c692a8 | 676 | =head3 Does it potentially introduce new bugs? |
902b9dbf | 677 | |
04c692a8 DR |
678 | Radical rewrites of large chunks of the Perl interpreter have the |
679 | potential to introduce new bugs. | |
902b9dbf | 680 | |
04c692a8 | 681 | =head3 How big is it? |
902b9dbf | 682 | |
531e2078 | 683 | The smaller and more localized the change, the better. Similarly, a |
04c692a8 | 684 | series of small patches is greatly preferred over a single large patch. |
902b9dbf | 685 | |
04c692a8 | 686 | =head3 Does it preclude other desirable features? |
902b9dbf | 687 | |
04c692a8 | 688 | A patch is likely to be rejected if it closes off future avenues of |
531e2078 | 689 | development. For instance, a patch that placed a true and final |
04c692a8 DR |
690 | interpretation on prototypes is likely to be rejected because there are |
691 | still options for the future of prototypes that haven't been addressed. | |
902b9dbf | 692 | |
04c692a8 | 693 | =head3 Is the implementation robust? |
902b9dbf | 694 | |
04c692a8 | 695 | Good patches (tight code, complete, correct) stand more chance of going |
531e2078 | 696 | in. Sloppy or incorrect patches might be placed on the back burner |
04c692a8 DR |
697 | until the pumpking has time to fix, or might be discarded altogether |
698 | without further notice. | |
902b9dbf | 699 | |
04c692a8 | 700 | =head3 Is the implementation generic enough to be portable? |
902b9dbf | 701 | |
531e2078 | 702 | The worst patches make use of system-specific features. It's highly |
04c692a8 DR |
703 | unlikely that non-portable additions to the Perl language will be |
704 | accepted. | |
902b9dbf | 705 | |
04c692a8 | 706 | =head3 Is the implementation tested? |
902b9dbf | 707 | |
04c692a8 DR |
708 | Patches which change behaviour (fixing bugs or introducing new |
709 | features) must include regression tests to verify that everything works | |
710 | as expected. | |
902b9dbf | 711 | |
04c692a8 DR |
712 | Without tests provided by the original author, how can anyone else |
713 | changing perl in the future be sure that they haven't unwittingly | |
714 | broken the behaviour the patch implements? And without tests, how can | |
715 | the patch's author be confident that his/her hard work put into the | |
716 | patch won't be accidentally thrown away by someone in the future? | |
902b9dbf | 717 | |
04c692a8 | 718 | =head3 Is there enough documentation? |
902b9dbf | 719 | |
04c692a8 | 720 | Patches without documentation are probably ill-thought out or |
531e2078 | 721 | incomplete. No features can be added or changed without documentation, |
04c692a8 DR |
722 | so submitting a patch for the appropriate pod docs as well as the |
723 | source code is important. | |
902b9dbf | 724 | |
04c692a8 | 725 | =head3 Is there another way to do it? |
902b9dbf | 726 | |
04c692a8 | 727 | Larry said "Although the Perl Slogan is I<There's More Than One Way to |
531e2078 | 728 | Do It>, I hesitate to make 10 ways to do something". This is a tricky |
04c692a8 DR |
729 | heuristic to navigate, though--one man's essential addition is another |
730 | man's pointless cruft. | |
902b9dbf | 731 | |
04c692a8 | 732 | =head3 Does it create too much work? |
902b9dbf | 733 | |
04c692a8 DR |
734 | Work for the pumpking, work for Perl programmers, work for module |
735 | authors, ... Perl is supposed to be easy. | |
902b9dbf | 736 | |
04c692a8 | 737 | =head3 Patches speak louder than words |
902b9dbf | 738 | |
531e2078 | 739 | Working code is always preferred to pie-in-the-sky ideas. A patch to |
04c692a8 DR |
740 | add a feature stands a much higher chance of making it to the language |
741 | than does a random feature request, no matter how fervently argued the | |
a44b8c28 S |
742 | request might be. This ties into "Will it be useful?", as the fact |
743 | that someone took the time to make the patch demonstrates a strong | |
744 | desire for the feature. | |
c406981e | 745 | |
04c692a8 | 746 | =head1 TESTING |
c406981e | 747 | |
04c692a8 DR |
748 | The core uses the same testing style as the rest of Perl, a simple |
749 | "ok/not ok" run through Test::Harness, but there are a few special | |
750 | considerations. | |
c406981e | 751 | |
531e2078 | 752 | There are three ways to write a test in the core: L<Test::More>, |
a44b8c28 S |
753 | F<t/test.pl> and ad hoc C<print $test ? "ok 42\n" : "not ok 42\n">. |
754 | The decision of which to use depends on what part of the test suite | |
755 | you're working on. This is a measure to prevent a high-level failure | |
756 | (such as Config.pm breaking) from causing basic functionality tests to | |
757 | fail. | |
c406981e | 758 | |
04c692a8 DR |
759 | The F<t/test.pl> library provides some of the features of |
760 | L<Test::More>, but avoids loading most modules and uses as few core | |
761 | features as possible. | |
902b9dbf | 762 | |
9e6670f3 DR |
763 | If you write your own test, use the L<Test Anything |
764 | Protocol|http://testanything.org>. | |
902b9dbf MLF |
765 | |
766 | =over 4 | |
767 | ||
bb52f720 | 768 | =item * F<t/base>, F<t/comp> and F<t/opbasic> |
902b9dbf | 769 | |
15c526cb | 770 | Since we don't know if C<require> works, or even subroutines, use ad hoc |
531e2078 | 771 | tests for these three. Step carefully to avoid using the feature being |
a44b8c28 S |
772 | tested. Tests in F<t/opbasic>, for instance, have been placed there |
773 | rather than in F<t/op> because they test functionality which | |
774 | F<t/test.pl> presumes has already been demonstrated to work. | |
902b9dbf | 775 | |
a8d15a22 | 776 | =item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op> |
902b9dbf | 777 | |
04c692a8 DR |
778 | Now that basic require() and subroutines are tested, you can use the |
779 | F<t/test.pl> library. | |
902b9dbf | 780 | |
a8d15a22 | 781 | You can also use certain libraries like Config conditionally, but be |
04c692a8 | 782 | sure to skip the test gracefully if it's not there. |
902b9dbf | 783 | |
04c692a8 | 784 | =item * Everything else |
902b9dbf | 785 | |
04c692a8 | 786 | Now that the core of Perl is tested, L<Test::More> can and should be |
531e2078 | 787 | used. You can also use the full suite of core modules in the tests. |
902b9dbf MLF |
788 | |
789 | =back | |
790 | ||
a8d15a22 | 791 | When you say "make test", Perl uses the F<t/TEST> program to run the |
a44b8c28 S |
792 | test suite (except under Win32 where it uses F<t/harness> instead). |
793 | All tests are run from the F<t/> directory, B<not> the directory which | |
794 | contains the test. This causes some problems with the tests in | |
795 | F<lib/>, so here's some opportunity for some patching. | |
902b9dbf | 796 | |
531e2078 | 797 | You must be triply conscious of cross-platform concerns. This usually |
eb9df707 KW |
798 | boils down to using L<File::Spec>, avoiding things like C<fork()> |
799 | and C<system()> unless absolutely necessary, and not assuming that a | |
800 | given character has a particular ordinal value (code point) or that its | |
801 | UTF-8 representation is composed of particular bytes. | |
802 | ||
803 | There are several functions available to specify characters and code | |
804 | points portably in tests. The always-preloaded functions | |
805 | C<utf8::unicode_to_native()> and its inverse | |
806 | C<utf8::native_to_unicode()> take code points and translate | |
807 | appropriately. The file F<t/charset_tools.pl> has several functions | |
808 | that can be useful. It has versions of the previous two functions | |
809 | that take strings as inputs -- not single numeric code points: | |
810 | C<uni_to_native()> and C<native_to_uni()>. If you must look at the | |
811 | individual bytes comprising a UTF-8 encoded string, | |
812 | C<byte_utf8a_to_utf8n()> takes as input a string of those bytes encoded | |
813 | for an ASCII platform, and returns the equivalent string in the native | |
814 | platform. For example, C<byte_utf8a_to_utf8n("\xC2\xA0")> returns the | |
815 | byte sequence on the current platform that form the UTF-8 for C<U+00A0>, | |
816 | since C<"\xC2\xA0"> are the UTF-8 bytes on an ASCII platform for that | |
817 | code point. This function returns C<"\xC2\xA0"> on an ASCII platform, and | |
818 | C<"\x80\x41"> on an EBCDIC 1047 one. | |
819 | ||
15c526cb KW |
820 | But easiest is, if the character is specifiable as a literal, like |
821 | C<"A"> or C<"%">, to use that; if not so specificable, you can use use | |
822 | C<\N{}> , if the side effects aren't troublesome. Simply specify all | |
823 | your characters in hex, using C<\N{U+ZZ}> instead of C<\xZZ>. C<\N{}> | |
824 | is the Unicode name, and so it | |
eb9df707 KW |
825 | always gives you the Unicode character. C<\N{U+41}> is the character |
826 | whose Unicode code point is C<0x41>, hence is C<'A'> on all platforms. | |
827 | The side effects are: | |
828 | ||
829 | =over 4 | |
830 | ||
3f9568ff | 831 | =item * |
eb9df707 KW |
832 | |
833 | These select Unicode rules. That means that in double-quotish strings, | |
834 | the string is always converted to UTF-8 to force a Unicode | |
835 | interpretation (you can C<utf8::downgrade()> afterwards to convert back | |
836 | to non-UTF8, if possible). In regular expression patterns, the | |
837 | conversion isn't done, but if the character set modifier would | |
838 | otherwise be C</d>, it is changed to C</u>. | |
839 | ||
3f9568ff | 840 | =item * |
eb9df707 KW |
841 | |
842 | If you use the form C<\N{I<character name>}>, the L<charnames> module | |
843 | gets automatically loaded. This may not be suitable for the test level | |
844 | you are doing. | |
845 | ||
846 | =back | |
7a834142 | 847 | |
15c526cb KW |
848 | If you are testing locales (see L<perllocale>), there are helper |
849 | functions in F<t/loc_tools.pl> to enable you to see what locales there | |
850 | are on the current platform. | |
851 | ||
04c692a8 | 852 | =head2 Special C<make test> targets |
07aa3531 | 853 | |
04c692a8 | 854 | There are various special make targets that can be used to test Perl |
531e2078 FC |
855 | slightly differently than the standard "test" target. Not all them are |
856 | expected to give a 100% success rate. Many of them have several | |
04c692a8 DR |
857 | aliases, and many of them are not available on certain operating |
858 | systems. | |
07aa3531 | 859 | |
04c692a8 | 860 | =over 4 |
d44161bf | 861 | |
04c692a8 | 862 | =item * test_porting |
7a834142 | 863 | |
04c692a8 DR |
864 | This runs some basic sanity tests on the source tree and helps catch |
865 | basic errors before you submit a patch. | |
7a834142 | 866 | |
04c692a8 | 867 | =item * minitest |
51a35ef1 | 868 | |
04c692a8 DR |
869 | Run F<miniperl> on F<t/base>, F<t/comp>, F<t/cmd>, F<t/run>, F<t/io>, |
870 | F<t/op>, F<t/uni> and F<t/mro> tests. | |
51a35ef1 | 871 | |
499cea6b | 872 | =item * test.valgrind check.valgrind |
51a35ef1 | 873 | |
04c692a8 | 874 | (Only in Linux) Run all the tests using the memory leak + naughty |
531e2078 | 875 | memory access tool "valgrind". The log files will be named |
04c692a8 | 876 | F<testname.valgrind>. |
83f0ef60 | 877 | |
04c692a8 | 878 | =item * test_harness |
83f0ef60 | 879 | |
04c692a8 | 880 | Run the test suite with the F<t/harness> controlling program, instead |
531e2078 | 881 | of F<t/TEST>. F<t/harness> is more sophisticated, and uses the |
04c692a8 | 882 | L<Test::Harness> module, thus using this test target supposes that perl |
531e2078 | 883 | mostly works. The main advantage for our purposes is that it prints a |
a44b8c28 S |
884 | detailed summary of failed tests at the end. Also, unlike F<t/TEST>, |
885 | it doesn't redirect stderr to stdout. | |
83f0ef60 | 886 | |
04c692a8 DR |
887 | Note that under Win32 F<t/harness> is always used instead of F<t/TEST>, |
888 | so there is no special "test_harness" target. | |
83f0ef60 | 889 | |
04c692a8 DR |
890 | Under Win32's "test" target you may use the TEST_SWITCHES and |
891 | TEST_FILES environment variables to control the behaviour of | |
531e2078 | 892 | F<t/harness>. This means you can say |
83f0ef60 | 893 | |
04c692a8 DR |
894 | nmake test TEST_FILES="op/*.t" |
895 | nmake test TEST_SWITCHES="-torture" TEST_FILES="op/*.t" | |
83f0ef60 | 896 | |
78087e0a R |
897 | =item * test-notty test_notty |
898 | ||
899 | Sets PERL_SKIP_TTY_TEST to true before running normal test. | |
900 | ||
83f0ef60 JH |
901 | =back |
902 | ||
04c692a8 | 903 | =head2 Parallel tests |
83f0ef60 | 904 | |
04c692a8 | 905 | The core distribution can now run its regression tests in parallel on |
531e2078 | 906 | Unix-like platforms. Instead of running C<make test>, set C<TEST_JOBS> |
04c692a8 | 907 | in your environment to the number of tests to run in parallel, and run |
531e2078 | 908 | C<make test_harness>. On a Bourne-like shell, this can be done as |
07aa3531 | 909 | |
04c692a8 | 910 | TEST_JOBS=3 make test_harness # Run 3 tests in parallel |
07aa3531 | 911 | |
04c692a8 DR |
912 | An environment variable is used, rather than parallel make itself, |
913 | because L<TAP::Harness> needs to be able to schedule individual | |
914 | non-conflicting test scripts itself, and there is no standard interface | |
915 | to C<make> utilities to interact with their job schedulers. | |
51a35ef1 | 916 | |
9e6670f3 | 917 | Note that currently some test scripts may fail when run in parallel |
cb0ee57a | 918 | (most notably F<dist/IO/t/io_dir.t>). If necessary, run just the |
a44b8c28 | 919 | failing scripts again sequentially and see if the failures go away. |
51a35ef1 | 920 | |
04c692a8 | 921 | =head2 Running tests by hand |
51a35ef1 | 922 | |
9e6670f3 DR |
923 | You can run part of the test suite by hand by using one of the |
924 | following commands from the F<t/> directory: | |
51a35ef1 | 925 | |
04c692a8 | 926 | ./perl -I../lib TEST list-of-.t-files |
51a35ef1 | 927 | |
04c692a8 | 928 | or |
51a35ef1 | 929 | |
04c692a8 | 930 | ./perl -I../lib harness list-of-.t-files |
51a35ef1 | 931 | |
a8d15a22 | 932 | (If you don't specify test scripts, the whole test suite will be run.) |
51a35ef1 | 933 | |
04c692a8 | 934 | =head2 Using F<t/harness> for testing |
51a35ef1 | 935 | |
9e6670f3 | 936 | If you use C<harness> for testing, you have several command line |
531e2078 | 937 | options available to you. The arguments are as follows, and are in the |
9e6670f3 | 938 | order that they must appear if used together. |
51a35ef1 | 939 | |
04c692a8 DR |
940 | harness -v -torture -re=pattern LIST OF FILES TO TEST |
941 | harness -v -torture -re LIST OF PATTERNS TO MATCH | |
07aa3531 | 942 | |
a8d15a22 | 943 | If C<LIST OF FILES TO TEST> is omitted, the file list is obtained from |
531e2078 | 944 | the manifest. The file list may include shell wildcards which will be |
04c692a8 | 945 | expanded out. |
07aa3531 | 946 | |
04c692a8 | 947 | =over 4 |
4ae3d70a | 948 | |
04c692a8 | 949 | =item * -v |
4ae3d70a | 950 | |
04c692a8 DR |
951 | Run the tests under verbose mode so you can see what tests were run, |
952 | and debug output. | |
51a35ef1 | 953 | |
04c692a8 | 954 | =item * -torture |
4ae3d70a | 955 | |
04c692a8 | 956 | Run the torture tests as well as the normal set. |
4ae3d70a | 957 | |
04c692a8 | 958 | =item * -re=PATTERN |
6c41479b | 959 | |
a44b8c28 S |
960 | Filter the file list so that all the test files run match PATTERN. |
961 | Note that this form is distinct from the B<-re LIST OF PATTERNS> form | |
962 | below in that it allows the file list to be provided as well. | |
6c41479b | 963 | |
04c692a8 | 964 | =item * -re LIST OF PATTERNS |
6c41479b | 965 | |
04c692a8 | 966 | Filter the file list so that all the test files run match |
531e2078 | 967 | /(LIST|OF|PATTERNS)/. Note that with this form the patterns are joined |
04c692a8 DR |
968 | by '|' and you cannot supply a list of files, instead the test files |
969 | are obtained from the MANIFEST. | |
6c41479b | 970 | |
04c692a8 | 971 | =back |
6c41479b | 972 | |
04c692a8 | 973 | You can run an individual test by a command similar to |
6c41479b | 974 | |
a8d15a22 | 975 | ./perl -I../lib path/to/foo.t |
6c41479b | 976 | |
04c692a8 DR |
977 | except that the harnesses set up some environment variables that may |
978 | affect the execution of the test: | |
6c41479b JH |
979 | |
980 | =over 4 | |
981 | ||
04c692a8 | 982 | =item * PERL_CORE=1 |
6c41479b | 983 | |
a8d15a22 | 984 | indicates that we're running this test as part of the perl core test |
531e2078 | 985 | suite. This is useful for modules that have a dual life on CPAN. |
6c41479b | 986 | |
04c692a8 | 987 | =item * PERL_DESTRUCT_LEVEL=2 |
6c41479b | 988 | |
04c692a8 | 989 | is set to 2 if it isn't set already (see |
a8d15a22 | 990 | L<perlhacktips/PERL_DESTRUCT_LEVEL>). |
6c41479b | 991 | |
04c692a8 | 992 | =item * PERL |
6c41479b | 993 | |
04c692a8 DR |
994 | (used only by F<t/TEST>) if set, overrides the path to the perl |
995 | executable that should be used to run the tests (the default being | |
996 | F<./perl>). | |
6c41479b | 997 | |
04c692a8 | 998 | =item * PERL_SKIP_TTY_TEST |
6c41479b | 999 | |
a44b8c28 S |
1000 | if set, tells to skip the tests that need a terminal. It's actually |
1001 | set automatically by the Makefile, but can also be forced artificially | |
1002 | by running 'make test_notty'. | |
6c41479b | 1003 | |
04c692a8 | 1004 | =back |
6c41479b | 1005 | |
04c692a8 | 1006 | =head3 Other environment variables that may influence tests |
6c41479b | 1007 | |
04c692a8 | 1008 | =over 4 |
6c41479b | 1009 | |
04c692a8 | 1010 | =item * PERL_TEST_Net_Ping |
6c41479b | 1011 | |
04c692a8 | 1012 | Setting this variable runs all the Net::Ping modules tests, otherwise |
531e2078 | 1013 | some tests that interact with the outside world are skipped. See |
04c692a8 | 1014 | L<perl58delta>. |
6c41479b | 1015 | |
04c692a8 | 1016 | =item * PERL_TEST_NOVREXX |
cce04beb | 1017 | |
04c692a8 | 1018 | Setting this variable skips the vrexx.t tests for OS2::REXX. |
cce04beb | 1019 | |
04c692a8 | 1020 | =item * PERL_TEST_NUMCONVERTS |
cce04beb | 1021 | |
04c692a8 | 1022 | This sets a variable in op/numconvert.t. |
cce04beb | 1023 | |
ff5db609 TC |
1024 | =item * PERL_TEST_MEMORY |
1025 | ||
1026 | Setting this variable includes the tests in F<t/bigmem/>. This should | |
a44b8c28 S |
1027 | be set to the number of gigabytes of memory available for testing, eg. |
1028 | C<PERL_TEST_MEMORY=4> indicates that tests that require 4GiB of | |
ff5db609 TC |
1029 | available memory can be run safely. |
1030 | ||
04c692a8 | 1031 | =back |
cce04beb | 1032 | |
04c692a8 DR |
1033 | See also the documentation for the Test and Test::Harness modules, for |
1034 | more environment variables that affect testing. | |
cce04beb | 1035 | |
9e7973fa DM |
1036 | =head2 Performance testing |
1037 | ||
1038 | The file F<t/perf/benchmarks> contains snippets of perl code which are | |
1039 | intended to be benchmarked across a range of perls by the | |
1040 | F<Porting/bench.pl> tool. If you fix or enhance a performance issue, you | |
1041 | may want to add a representative code sample to the file, then run | |
1042 | F<bench.pl> against the previous and current perls to see what difference | |
1043 | it has made, and whether anything else has slowed down as a consequence. | |
1044 | ||
1045 | The file F<t/perf/opcount.t> is designed to test whether a particular | |
1046 | code snippet has been compiled into an optree containing specified | |
1047 | numbers of particular op types. This is good for testing whether | |
1048 | optimisations which alter ops, such as converting an C<aelem> op into an | |
1049 | C<aelemfast> op, are really doing that. | |
1050 | ||
1051 | The files F<t/perf/speed.t> and F<t/re/speed.t> are designed to test | |
1052 | things that run thousands of times slower if a particular optimisation | |
1053 | is broken (for example, the utf8 length cache on long utf8 strings). | |
1054 | Add a test that will take a fraction of a second normally, and minutes | |
1055 | otherwise, causing the test file to time out on failure. | |
1056 | ||
ca31f56c JK |
1057 | =head2 Building perl at older commits |
1058 | ||
1059 | In the course of hacking on the Perl core distribution, you may have occasion | |
1060 | to configure, build and test perl at an old commit. Sometimes C<make> will | |
1061 | fail during this process. If that happens, you may be able to salvage the | |
1062 | situation by using the Devel::PatchPerl library from CPAN (not included in the | |
1063 | core) to bring the source code at that commit to a buildable state. | |
1064 | ||
1065 | Here's a real world example, taken from work done to resolve | |
1066 | L<perl #72414|https://rt.perl.org/Ticket/Display.html?id=72414>. | |
1067 | Use of F<Porting/bisect.pl> had identified commit | |
1068 | C<ba77e4cc9d1ceebf472c9c5c18b2377ee47062e6> as the commit in which a bug was | |
1069 | corrected. To confirm, a P5P developer wanted to configure and build perl at | |
1070 | commit C<ba77e4c^> (presumably "bad") and then at C<ba77e4c> (presumably | |
1071 | "good"). Normal configuration and build was attempted: | |
1072 | ||
1073 | $ sh ./Configure -des -Dusedevel | |
1074 | $ make test_prep | |
1075 | ||
1076 | C<make>, however, failed with output (excerpted) like this: | |
1077 | ||
1078 | cc -fstack-protector -L/usr/local/lib -o miniperl \ | |
1079 | gv.o toke.o perly.o pad.o regcomp.o dump.o util.o \ | |
1080 | mg.o reentr.o mro.o hv.o av.o run.o pp_hot.o sv.o \ | |
1081 | pp.o scope.o pp_ctl.o pp_sys.o doop.o doio.o regexec.o \ | |
1082 | utf8.o taint.o deb.o universal.o globals.o perlio.o \ | |
1083 | perlapi.o numeric.o mathoms.o locale.o pp_pack.o pp_sort.o \ | |
1084 | miniperlmain.o opmini.o perlmini.o | |
1085 | pp.o: In function `Perl_pp_pow': | |
1086 | pp.c:(.text+0x2db9): undefined reference to `pow' | |
1087 | ... | |
1088 | collect2: error: ld returned 1 exit status | |
1089 | makefile:348: recipe for target 'miniperl' failed | |
1090 | make: *** [miniperl] Error 1 | |
1091 | ||
1092 | Another P5P contributor recommended installation and use of Devel::PatchPerl | |
1093 | for this situation, first to determine the version of perl at the commit in | |
1094 | question, then to patch the source code at that point to facilitate a build. | |
1095 | ||
1096 | $ perl -MDevel::PatchPerl -e \ | |
1097 | 'print Devel::PatchPerl->determine_version("/path/to/sourcecode"), "\n";' | |
1098 | 5.11.1 | |
1099 | $ perl -MDevel::PatchPerl -e \ | |
1100 | 'Devel::PatchPerl->patch_source("5.11.1", "/path/to/sourcecode");' | |
1101 | ||
1102 | Once the source was patched, C<./Configure> and C<make test_prep> were called | |
1103 | and completed successfully, enabling confirmation of the findings in RT | |
1104 | #72414. | |
1105 | ||
04c692a8 | 1106 | =head1 MORE READING FOR GUTS HACKERS |
cce04beb | 1107 | |
04c692a8 | 1108 | To hack on the Perl guts, you'll need to read the following things: |
cce04beb | 1109 | |
04c692a8 | 1110 | =over 4 |
cce04beb | 1111 | |
04c692a8 | 1112 | =item * L<perlsource> |
b8ddf6b3 | 1113 | |
531e2078 | 1114 | An overview of the Perl source tree. This will help you find the files |
04c692a8 | 1115 | you're looking for. |
b8ddf6b3 | 1116 | |
04c692a8 | 1117 | =item * L<perlinterp> |
b8ddf6b3 | 1118 | |
04c692a8 DR |
1119 | An overview of the Perl interpreter source code and some details on how |
1120 | Perl does what it does. | |
b8ddf6b3 | 1121 | |
04c692a8 | 1122 | =item * L<perlhacktut> |
b8ddf6b3 | 1123 | |
04c692a8 | 1124 | This document walks through the creation of a small patch to Perl's C |
531e2078 | 1125 | code. If you're just getting started with Perl core hacking, this will |
04c692a8 | 1126 | help you understand how it works. |
b8ddf6b3 | 1127 | |
04c692a8 | 1128 | =item * L<perlhacktips> |
b8ddf6b3 | 1129 | |
531e2078 | 1130 | More details on hacking the Perl core. This document focuses on lower |
04c692a8 DR |
1131 | level details such as how to write tests, compilation issues, |
1132 | portability, debugging, etc. | |
b8ddf6b3 | 1133 | |
04c692a8 | 1134 | If you plan on doing serious C hacking, make sure to read this. |
b8ddf6b3 | 1135 | |
04c692a8 | 1136 | =item * L<perlguts> |
b8ddf6b3 | 1137 | |
04c692a8 | 1138 | This is of paramount importance, since it's the documentation of what |
531e2078 | 1139 | goes where in the Perl source. Read it over a couple of times and it |
04c692a8 DR |
1140 | might start to make sense - don't worry if it doesn't yet, because the |
1141 | best way to study it is to read it in conjunction with poking at Perl | |
1142 | source, and we'll do that later on. | |
b8ddf6b3 | 1143 | |
04c692a8 DR |
1144 | Gisle Aas's "illustrated perlguts", also known as I<illguts>, has very |
1145 | helpful pictures: | |
9965345d | 1146 | |
04c692a8 | 1147 | L<http://search.cpan.org/dist/illguts/> |
9965345d | 1148 | |
04c692a8 | 1149 | =item * L<perlxstut> and L<perlxs> |
f1fac472 | 1150 | |
04c692a8 DR |
1151 | A working knowledge of XSUB programming is incredibly useful for core |
1152 | hacking; XSUBs use techniques drawn from the PP code, the portion of | |
531e2078 | 1153 | the guts that actually executes a Perl program. It's a lot gentler to |
04c692a8 DR |
1154 | learn those techniques from simple examples and explanation than from |
1155 | the core itself. | |
f1fac472 | 1156 | |
04c692a8 | 1157 | =item * L<perlapi> |
f1fac472 | 1158 | |
04c692a8 DR |
1159 | The documentation for the Perl API explains what some of the internal |
1160 | functions do, as well as the many macros used in the source. | |
f1fac472 | 1161 | |
04c692a8 | 1162 | =item * F<Porting/pumpkin.pod> |
f1fac472 | 1163 | |
04c692a8 DR |
1164 | This is a collection of words of wisdom for a Perl porter; some of it |
1165 | is only useful to the pumpkin holder, but most of it applies to anyone | |
1166 | wanting to go about Perl development. | |
f1fac472 | 1167 | |
04c692a8 | 1168 | =back |
f1fac472 | 1169 | |
04c692a8 | 1170 | =head1 CPAN TESTERS AND PERL SMOKERS |
f1fac472 | 1171 | |
4b05bc8e | 1172 | The CPAN testers ( L<http://testers.cpan.org/> ) are a group of volunteers |
04c692a8 | 1173 | who test CPAN modules on a variety of platforms. |
b8ddf6b3 | 1174 | |
4b05bc8e KW |
1175 | Perl Smokers ( L<http://www.nntp.perl.org/group/perl.daily-build/> and |
1176 | L<http://www.nntp.perl.org/group/perl.daily-build.reports/> ) | |
04c692a8 DR |
1177 | automatically test Perl source releases on platforms with various |
1178 | configurations. | |
f1fac472 | 1179 | |
531e2078 | 1180 | Both efforts welcome volunteers. In order to get involved in smoke |
04c692a8 | 1181 | testing of the perl itself visit |
531e2078 | 1182 | L<http://search.cpan.org/dist/Test-Smoke/>. In order to start smoke |
04c692a8 DR |
1183 | testing CPAN modules visit |
1184 | L<http://search.cpan.org/dist/CPANPLUS-YACSmoke/> or | |
1185 | L<http://search.cpan.org/dist/minismokebox/> or | |
1186 | L<http://search.cpan.org/dist/CPAN-Reporter/>. | |
f1fac472 | 1187 | |
04c692a8 | 1188 | =head1 WHAT NEXT? |
a422fd2d | 1189 | |
04c692a8 DR |
1190 | If you've read all the documentation in the document and the ones |
1191 | listed above, you're more than ready to hack on Perl. | |
a422fd2d | 1192 | |
04c692a8 | 1193 | Here's some more recommendations |
a422fd2d | 1194 | |
04c692a8 | 1195 | =over 4 |
a422fd2d SC |
1196 | |
1197 | =item * | |
1198 | ||
1199 | Subscribe to perl5-porters, follow the patches and try and understand | |
1200 | them; don't be afraid to ask if there's a portion you're not clear on - | |
1201 | who knows, you may unearth a bug in the patch... | |
1202 | ||
1203 | =item * | |
1204 | ||
04c692a8 | 1205 | Do read the README associated with your operating system, e.g. |
531e2078 | 1206 | README.aix on the IBM AIX OS. Don't hesitate to supply patches to that |
04c692a8 | 1207 | README if you find anything missing or changed over a new OS release. |
a1f349fd MB |
1208 | |
1209 | =item * | |
1210 | ||
a422fd2d | 1211 | Find an area of Perl that seems interesting to you, and see if you can |
a44b8c28 S |
1212 | work out how it works. Scan through the source, and step over it in |
1213 | the debugger. Play, poke, investigate, fiddle! You'll probably get to | |
04c692a8 DR |
1214 | understand not just your chosen area but a much wider range of |
1215 | F<perl>'s activity as well, and probably sooner than you'd think. | |
a422fd2d SC |
1216 | |
1217 | =back | |
1218 | ||
04c692a8 | 1219 | =head2 "The Road goes ever on and on, down from the door where it began." |
a422fd2d | 1220 | |
04c692a8 | 1221 | If you can do these things, you've started on the long road to Perl |
531e2078 | 1222 | porting. Thanks for wanting to help make Perl better - and happy |
04c692a8 | 1223 | hacking! |
a422fd2d | 1224 | |
4ac71550 TC |
1225 | =head2 Metaphoric Quotations |
1226 | ||
1227 | If you recognized the quote about the Road above, you're in luck. | |
1228 | ||
04c692a8 | 1229 | Most software projects begin each file with a literal description of |
531e2078 | 1230 | each file's purpose. Perl instead begins each with a literary allusion |
04c692a8 | 1231 | to that file's purpose. |
4ac71550 | 1232 | |
04c692a8 | 1233 | Like chapters in many books, all top-level Perl source files (along |
9e6670f3 DR |
1234 | with a few others here and there) begin with an epigrammatic |
1235 | inscription that alludes, indirectly and metaphorically, to the | |
1236 | material you're about to read. | |
4ac71550 | 1237 | |
a8d15a22 | 1238 | Quotations are taken from writings of J.R.R. Tolkien pertaining to his |
531e2078 | 1239 | Legendarium, almost always from I<The Lord of the Rings>. Chapters and |
4ac71550 TC |
1240 | page numbers are given using the following editions: |
1241 | ||
1242 | =over 4 | |
1243 | ||
04c692a8 | 1244 | =item * |
4ac71550 | 1245 | |
531e2078 | 1246 | I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary |
04c692a8 DR |
1247 | edition of 2007 was used, published in the UK by Harper Collins |
1248 | Publishers and in the US by the Houghton Mifflin Company. | |
4ac71550 TC |
1249 | |
1250 | =item * | |
1251 | ||
531e2078 | 1252 | I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover, |
04c692a8 DR |
1253 | 50th-anniversary edition of 2004 was used, published in the UK by |
1254 | Harper Collins Publishers and in the US by the Houghton Mifflin | |
1255 | Company. | |
4ac71550 TC |
1256 | |
1257 | =item * | |
1258 | ||
04c692a8 DR |
1259 | I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously |
1260 | by his son and literary executor, C.J.R. Tolkien, being the 3rd of the | |
531e2078 | 1261 | 12 volumes in Christopher's mammoth I<History of Middle Earth>. Page |
04c692a8 DR |
1262 | numbers derive from the hardcover edition, first published in 1983 by |
1263 | George Allen & Unwin; no page numbers changed for the special 3-volume | |
1264 | omnibus edition of 2002 or the various trade-paper editions, all again | |
1265 | now by Harper Collins or Houghton Mifflin. | |
4ac71550 TC |
1266 | |
1267 | =back | |
1268 | ||
04c692a8 DR |
1269 | Other JRRT books fair game for quotes would thus include I<The |
1270 | Adventures of Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>, | |
1271 | and I<The Tale of the Children of Hurin>, all but the first | |
531e2078 | 1272 | posthumously assembled by CJRT. But I<The Lord of the Rings> itself is |
04c692a8 DR |
1273 | perfectly fine and probably best to quote from, provided you can find a |
1274 | suitable quote there. | |
4ac71550 | 1275 | |
04c692a8 DR |
1276 | So if you were to supply a new, complete, top-level source file to add |
1277 | to Perl, you should conform to this peculiar practice by yourself | |
1278 | selecting an appropriate quotation from Tolkien, retaining the original | |
1279 | spelling and punctuation and using the same format the rest of the | |
531e2078 | 1280 | quotes are in. Indirect and oblique is just fine; remember, it's a |
04c692a8 | 1281 | metaphor, so being meta is, after all, what it's for. |
4ac71550 | 1282 | |
e8cd7eae GS |
1283 | =head1 AUTHOR |
1284 | ||
04c692a8 DR |
1285 | This document was originally written by Nathan Torkington, and is |
1286 | maintained by the perl5-porters mailing list. |