This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta - Modules and Pragmata
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
dad02c36
KE
5[ this is a template for a new perldelta file. Any text flagged as XXX needs
6to be processed before release. ]
7
8perldelta - what is new for perl v5.31.2
d407e309 9
862f380b 10=head1 DESCRIPTION
261e14b0 11
dad02c36 12This document describes differences between the 5.31.1 release and the 5.31.2
862f380b 13release.
261e14b0 14
dad02c36
KE
15If you are upgrading from an earlier release such as 5.31.0, first read
16L<perl5311delta>, which describes differences between 5.31.0 and 5.31.1.
8424e368 17
dad02c36 18=head1 Notice
8424e368 19
dad02c36 20XXX Any important notices here
8424e368 21
dad02c36 22=head1 Core Enhancements
8424e368 23
dad02c36
KE
24XXX New core language features go here. Summarize user-visible core language
25enhancements. Particularly prominent performance optimisations could go
26here, but most should go in the L</Performance Enhancements> section.
0240db1e 27
dad02c36 28[ List each enhancement as a =head2 entry ]
0240db1e 29
dad02c36 30=head1 Security
53f11efa 31
dad02c36
KE
32XXX Any security-related notices go here. In particular, any security
33vulnerabilities closed should be noted here rather than in the
34L</Selected Bug Fixes> section.
53f11efa 35
dad02c36 36[ List each security issue as a =head2 entry ]
d407e309 37
dad02c36 38=head1 Incompatible Changes
8424e368 39
dad02c36 40XXX For a release on a stable branch, this section aspires to be:
8424e368 41
dad02c36
KE
42 There are no changes intentionally incompatible with 5.XXX.XXX
43 If any exist, they are bugs, and we request that you submit a
44 report. See L</Reporting Bugs> below.
8424e368 45
dad02c36 46[ List each incompatible change as a =head2 entry ]
8424e368 47
dad02c36 48=head1 Deprecations
a0348300 49
dad02c36 50XXX Any deprecated features, syntax, modules etc. should be listed here.
8424e368 51
dad02c36 52=head2 Module removals
8424e368 53
dad02c36 54XXX Remove this section if not applicable.
8424e368 55
dad02c36
KE
56The following modules will be removed from the core distribution in a
57future release, and will at that time need to be installed from CPAN.
58Distributions on CPAN which require these modules will need to list them as
59prerequisites.
8424e368 60
dad02c36
KE
61The core versions of these modules will now issue C<"deprecated">-category
62warnings to alert you to this fact. To silence these deprecation warnings,
63install the modules in question from CPAN.
7b97bf55 64
dad02c36
KE
65Note that these are (with rare exceptions) fine modules that you are encouraged
66to continue to use. Their disinclusion from core primarily hinges on their
67necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
68not usually on concerns over their design.
a0348300 69
dad02c36 70=over
a0348300 71
dad02c36 72=item XXX
a0348300 73
dad02c36
KE
74XXX Note that deprecated modules should be listed here even if they are listed
75as an updated module in the L</Modules and Pragmata> section.
a0348300 76
dad02c36 77=back
a0348300 78
dad02c36 79[ List each other deprecation as a =head2 entry ]
a0348300 80
dad02c36 81=head1 Performance Enhancements
a0348300 82
dad02c36
KE
83XXX Changes which enhance performance without changing behaviour go here.
84There may well be none in a stable release.
a0348300 85
dad02c36 86[ List each enhancement as an =item entry ]
a0348300 87
dad02c36 88=over 4
7b97bf55 89
9409f532 90=item *
7b97bf55 91
dad02c36 92XXX
cc1cbb06 93
dad02c36 94=back
a0348300 95
dad02c36 96=head1 Modules and Pragmata
a0348300 97
9c600b76 98=head2 Updated Modules and Pragmata
a0348300 99
9c600b76 100=over 4
a0348300 101
9c600b76 102=item *
a0348300 103
9c600b76 104L<Devel::PPPort> has been upgraded from version 3.53 to 3.54.
a0348300 105
9c600b76
SH
106=item *
107
108L<Exporter> has been upgraded from version 5.73 to 5.74.
a0348300
KE
109
110=item *
111
9c600b76 112L<IPC::Cmd> has been upgraded from version 1.02 to 1.04.
a0348300 113
9c600b76 114=item *
a0348300 115
9c600b76 116L<JSON::PP> has been upgraded from version 4.02 to 4.04.
dad02c36 117
9c600b76
SH
118=item *
119
120L<Module::CoreList> has been upgraded from version 5.20190620 to 5.20190720.
a0348300
KE
121
122=item *
123
9c600b76 124L<Opcode> has been upgraded from version 1.43 to 1.44.
a0348300 125
9c600b76 126=item *
a0348300 127
9c600b76 128L<PerlIO::encoding> has been upgraded from version 0.27 to 0.28.
dad02c36 129
9c600b76 130=item *
dad02c36 131
9c600b76 132L<Pod::Simple> has been upgraded from version 3.38 to 3.39.
cc1cbb06
TC
133
134=item *
135
9c600b76 136L<threads::shared> has been upgraded from version 1.60 to 1.61.
8424e368 137
dad02c36 138=back
a0348300 139
dad02c36 140=head1 Documentation
a0348300 141
dad02c36
KE
142XXX Changes to files in F<pod/> go here. Consider grouping entries by
143file and be sure to link to the appropriate page, e.g. L<perlfunc>.
a0348300 144
dad02c36 145=head2 New Documentation
a0348300 146
dad02c36 147XXX Changes which create B<new> files in F<pod/> go here.
a0348300 148
dad02c36 149=head3 L<XXX>
a0348300 150
dad02c36 151XXX Description of the purpose of the new file here
a0348300 152
dad02c36 153=head2 Changes to Existing Documentation
a0348300 154
dad02c36
KE
155We have attempted to update the documentation to reflect the changes
156listed in this document. If you find any we have missed, send email
157to L<perlbug@perl.org|mailto:perlbug@perl.org>.
a0348300 158
dad02c36
KE
159XXX Changes which significantly change existing files in F<pod/> go here.
160However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
161section.
a0348300 162
dad02c36 163Additionally, the following selected changes have been made:
a0348300 164
dad02c36 165=head3 L<XXX>
a0348300 166
dad02c36 167=over 4
a0348300
KE
168
169=item *
170
dad02c36 171XXX Description of the change here
a0348300 172
dad02c36 173=back
a0348300 174
dad02c36 175=head1 Diagnostics
a0348300 176
dad02c36
KE
177The following additions or changes have been made to diagnostic output,
178including warnings and fatal error messages. For the complete list of
179diagnostic messages, see L<perldiag>.
a0348300 180
dad02c36
KE
181XXX New or changed warnings emitted by the core's C<C> code go here. Also
182include any changes in L<perldiag> that reconcile it to the C<C> code.
8424e368 183
dad02c36 184=head2 New Diagnostics
8424e368 185
dad02c36
KE
186XXX Newly added diagnostic messages go under here, separated into New Errors
187and New Warnings
188
189=head3 New Errors
8424e368
S
190
191=over 4
192
193=item *
194
dad02c36 195XXX L<message|perldiag/"message">
8424e368
S
196
197=back
198
dad02c36 199=head3 New Warnings
8424e368 200
dad02c36 201=over 4
8424e368 202
dad02c36 203=item *
8424e368 204
dad02c36 205XXX L<message|perldiag/"message">
8424e368 206
dad02c36
KE
207=back
208
209=head2 Changes to Existing Diagnostics
210
211XXX Changes (i.e. rewording) of diagnostic messages go here
860a458f
KE
212
213=over 4
214
215=item *
216
1a7108fe
KW
217C<\N{} here is restricted to one character> is now emitted in the same
218circumstances where previously C<\N{} in inverted character class or as
219a range end-point is restricted to one character> was.
220
221This is due to new circumstances having been added in perl v5.30 that
222weren't covered by the earlier wording.
860a458f
KE
223
224=back
225
dad02c36
KE
226=head1 Utility Changes
227
228XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
229Most of these are built within the directory F<utils>.
230
231[ List utility changes as a =head2 entry for each utility and =item
232entries for each change
233Use L<XXX> with program names to get proper documentation linking. ]
234
235=head2 L<XXX>
8424e368
S
236
237=over 4
d407e309 238
d407e309
S
239=item *
240
dad02c36 241XXX
8424e368
S
242
243=back
244
8424e368
S
245=head1 Configuration and Compilation
246
dad02c36
KE
247XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
248go here. Any other changes to the Perl build process should be listed here.
249However, any platform-specific changes should be listed in the
250L</Platform Support> section, instead.
251
252[ List changes as an =item entry ].
253
8424e368
S
254=over 4
255
256=item *
257
48988e37
TC
258The C<ECHO> macro is now defined. This is used in a C<dtrace> rule
259that was originally changed for FreeBSD, and the FreeBSD make
260apparently predefines it. The Solaris make does not predefine C<ECHO>
261which broke this rule on Solaris. [perl #134218]
8424e368 262
86b50d93
DIM
263=item *
264
265Bison versions 3.1 through 3.4 are now supported.
266
8424e368
S
267=back
268
dad02c36 269=head1 Testing
8424e368 270
dad02c36
KE
271XXX Any significant changes to the testing of a freshly built perl should be
272listed here. Changes which create B<new> files in F<t/> go here as do any
273large changes to the testing harness (e.g. when parallel testing was added).
274Changes to existing files in F<t/> aren't worth summarizing, although the bugs
275that they represent may be covered elsewhere.
8424e368 276
dad02c36 277XXX If there were no significant test changes, say this:
8424e368 278
dad02c36
KE
279Tests were added and changed to reflect the other additions and changes
280in this release.
8424e368 281
dad02c36 282XXX If instead there were significant changes, say this:
8424e368 283
dad02c36
KE
284Tests were added and changed to reflect the other additions and
285changes in this release. Furthermore, these significant changes were
286made:
8424e368 287
dad02c36 288[ List each test improvement as an =item entry ]
8424e368 289
8424e368
S
290=over 4
291
292=item *
293
dad02c36 294XXX
8424e368
S
295
296=back
297
dad02c36 298=head1 Platform Support
8424e368 299
dad02c36 300XXX Any changes to platform support should be listed in the sections below.
8424e368 301
dad02c36
KE
302[ Within the sections, list each platform as an =item entry with specific
303changes as paragraphs below it. ]
8424e368 304
dad02c36 305=head2 New Platforms
b9d9f9ab 306
dad02c36
KE
307XXX List any platforms that this version of perl compiles on, that previous
308versions did not. These will either be enabled by new files in the F<hints/>
309directories, or new subdirectories and F<README> files at the top level of the
310source tree.
b9d9f9ab 311
dad02c36 312=over 4
8424e368 313
dad02c36 314=item XXX-some-platform
ddf10889 315
dad02c36 316XXX
ddf10889 317
dad02c36 318=back
755e4cab 319
dad02c36 320=head2 Discontinued Platforms
755e4cab 321
dad02c36 322XXX List any platforms that this version of perl no longer compiles on.
fef47ada 323
dad02c36 324=over 4
09b83c41 325
dad02c36 326=item XXX-some-platform
09b83c41 327
dad02c36 328XXX
09b83c41 329
dad02c36 330=back
09b83c41 331
dad02c36 332=head2 Platform-Specific Notes
fef47ada 333
dad02c36
KE
334XXX List any changes for specific platforms. This could include configuration
335and compilation changes or changes in portability/compatibility. However,
336changes within modules for platforms should generally be listed in the
337L</Modules and Pragmata> section.
4ec3954c 338
dad02c36 339=over 4
4ec3954c 340
ec121dac
TC
341=item Linux
342
343C<cc> will be used to populate C<plibpth> if C<cc> is C<clang>. [perl
344#134189]
345
c6981b9a 346=item VMS
4ec3954c 347
c6981b9a 348C<-Duse64bitint> is now the default on VMS.
4ec3954c 349
dad02c36 350=back
4ec3954c 351
dad02c36 352=head1 Internal Changes
4ec3954c 353
dad02c36
KE
354XXX Changes which affect the interface available to C<XS> code go here. Other
355significant internal changes for future core maintainers should be noted as
356well.
4ec3954c 357
dad02c36 358[ List each change as an =item entry ]
4ec3954c 359
dad02c36 360=over 4
4ec3954c
TC
361
362=item *
363
26552905 364The PERL_DESTRUCT_LEVEL environment variable was formerly only honored on
06cc5386 365perl binaries built with DEBUGGING support. It is now checked on all perl
c22107ad 366builds. Its normal use is to force perl to individually free every block
26552905
DM
367of memory which it has allocated before exiting, which is useful when
368using automated leak detection tools such as valgrind.
4ec3954c 369
b870557c
TC
370=item *
371
372The API eval_sv() now accepts a C<G_RETHROW> flag. If this flag is
373set and an exception is thrown while compiling or executing the
374supplied code, it will be rethrown, and eval_sv() will not return.
375[perl #134177]
376
ed0cf058
TC
377=item *
378
379As part of the fix for [perl #2754] perl_parse() now returns non-zero
380if exit(0) is called in a C<BEGIN>, C<UNITCHECK> or C<CHECK> block.
381
4ec3954c
TC
382=back
383
dad02c36 384=head1 Selected Bug Fixes
4ec3954c 385
dad02c36
KE
386XXX Important bug fixes in the core language are summarized here. Bug fixes in
387files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
2dd5ef16 388
dad02c36
KE
389[ List each fix as an =item entry ]
390
391=over 4
2dd5ef16 392
5b2f1ba6
TC
393=item *
394
1bed9104
TC
395Parsing incomplete hex or binary literals was changed in 5.31.1 to
396treat such a literal as just the 0, leaving the following C<x> or C<b>
397to be parsed as part of the next token. This could lead to some
398silent changes in behaviour, so now incomplete hex or binary literals
399produce a fatal error. [perl #134125]
5b2f1ba6 400
b870557c
TC
401=item *
402
403eval_pv()'s I<croak_on_error> flag will now throw even if the
404exception is a false overloaded value. [perl #134177]
405
ed0cf058
TC
406=item *
407
408C<INIT> blocks and the program itself are no longer run if exit(0) is
409called within a C<BEGIN>, C<UNITCHECK> or C<CHECK> block. [perl
410#2754]
411
973ae088
TC
412=item *
413
414C<<< open my $fh, ">>+", undef >>> now opens the temporary file in
415append mode - writes will seek to the end of file before writing.
416[perl #134221]
417
dad02c36 418=back
5b2f1ba6 419
dad02c36 420=head1 Known Problems
5b2f1ba6 421
dad02c36
KE
422XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
423tests that had to be C<TODO>ed for the release would be noted here. Unfixed
424platform specific bugs also go here.
0367cc1a 425
dad02c36 426[ List each fix as an =item entry ]
0367cc1a 427
dad02c36 428=over 4
84ab3b69 429
fa068f6d
TC
430=item *
431
cb561db1
SH
432The VC++ 6.0 build on Windows is currently broken.
433
434=item *
435
436Tests 9-11 in F<t/op/blocks.t> currently fail on Windows.
437[perl #134295]
fa068f6d 438
8424e368
S
439=back
440
dad02c36 441=head1 Errata From Previous Releases
8424e368 442
dad02c36 443=over 4
a0348300 444
dad02c36 445=item *
a0348300 446
dad02c36
KE
447XXX Add anything here that we forgot to add, or were mistaken about, in
448the perldelta of a previous release.
a0348300 449
dad02c36 450=back
a0348300 451
dad02c36
KE
452=head1 Obituary
453
454XXX If any significant core contributor or member of the CPAN community has
455died, add a short obituary here.
456
457=head1 Acknowledgements
a0348300 458
dad02c36 459XXX Generate this with:
8424e368 460
dad02c36 461 perl Porting/acknowledgements.pl v5.31.1..HEAD
8424e368 462
44691e6f
AB
463=head1 Reporting Bugs
464
373fec1e 465If you find what you think is a bug, you might check the perl bug database
15f62f05
KE
466at L<https://rt.perl.org/>. There may also be information at
467L<http://www.perl.org/>, the Perl Home Page.
44691e6f 468
e08634c5
SH
469If you believe you have an unreported bug, please run the L<perlbug> program
470included with your release. Be sure to trim your bug down to a tiny but
471sufficient test case. Your bug report, along with the output of C<perl -V>,
0e18d1c4 472will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f 473
87c118b9
DM
474If the bug you are reporting has security implications which make it
475inappropriate to send to a publicly archived mailing list, then see
373fec1e
SH
476L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
477for details of how to report the issue.
44691e6f 478
390ae6f9
S
479=head1 Give Thanks
480
373fec1e
SH
481If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
482you can do so by running the C<perlthanks> program:
390ae6f9
S
483
484 perlthanks
485
486This will send an email to the Perl 5 Porters list with your show of thanks.
487
44691e6f
AB
488=head1 SEE ALSO
489
e08634c5
SH
490The F<Changes> file for an explanation of how to view exhaustive details on
491what changed.
44691e6f
AB
492
493The F<INSTALL> file for how to build Perl.
494
495The F<README> file for general stuff.
496
497The F<Artistic> and F<Copying> files for copyright information.
498
499=cut