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