This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta - Documentation updates
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
e5998677
SH
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.21.11
c68523cb 9
238894db 10=head1 DESCRIPTION
c68523cb 11
e5998677 12This document describes differences between the 5.21.10 release and the 5.21.11
238894db 13release.
c68523cb 14
e5998677
SH
15If you are upgrading from an earlier release such as 5.21.9, first read
16L<perl52110delta>, which describes differences between 5.21.9 and 5.21.10.
2ec11c70 17
e5998677 18=head1 Notice
ef8784b7 19
e5998677 20XXX Any important notices here
6798c95d 21
e5998677 22=head1 Core Enhancements
6798c95d 23
e5998677
SH
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.
cd7bac54 27
e5998677 28[ List each enhancement as a =head2 entry ]
cd7bac54 29
e5998677 30=head1 Security
0939a951 31
e5998677
SH
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.
cd7bac54 35
e5998677 36[ List each security issue as a =head2 entry ]
cd7bac54 37
e5998677 38=head1 Incompatible Changes
cd7bac54 39
e5998677 40XXX For a release on a stable branch, this section aspires to be:
83a5d6b6 41
e5998677
SH
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.
83a5d6b6 45
e5998677 46[ List each incompatible change as a =head2 entry ]
b9c683b3 47
e5998677 48=head1 Deprecations
b9c683b3 49
e5998677 50XXX Any deprecated features, syntax, modules etc. should be listed here.
b9c683b3 51
2e4abf26
DG
52=head2 Making all warnings fatal is discouraged
53
54The documentation for L<fatal warnings|warnings/Fatal Warnings> notes
55that C<< use warnings FATAL => 'all' >> is discouraged
56and provides stronger language about the risks of fatal warnings
57in general.
58
e5998677 59=head2 Module removals
b05565aa 60
e5998677 61XXX Remove this section if inapplicable.
b05565aa 62
e5998677
SH
63The following modules will be removed from the core distribution in a
64future release, and will at that time need to be installed from CPAN.
65Distributions on CPAN which require these modules will need to list them as
66prerequisites.
79116533 67
e5998677
SH
68The core versions of these modules will now issue C<"deprecated">-category
69warnings to alert you to this fact. To silence these deprecation warnings,
70install the modules in question from CPAN.
79116533 71
e5998677
SH
72Note that these are (with rare exceptions) fine modules that you are encouraged
73to continue to use. Their disinclusion from core primarily hinges on their
74necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
75not usually on concerns over their design.
79116533 76
e5998677 77=over
79116533 78
e5998677 79=item XXX
79116533 80
e5998677
SH
81XXX Note that deprecated modules should be listed here even if they are listed
82as an updated module in the L</Modules and Pragmata> section.
79116533 83
e5998677 84=back
79116533 85
e5998677 86[ List each other deprecation as a =head2 entry ]
79116533 87
e5998677 88=head1 Performance Enhancements
79116533 89
e5998677
SH
90XXX Changes which enhance performance without changing behaviour go here.
91There may well be none in a stable release.
79116533 92
e5998677 93[ List each enhancement as a =item entry ]
79116533 94
e5998677 95=over 4
79116533
SH
96
97=item *
98
e5998677 99XXX
79116533
SH
100
101=back
0939a951 102
e5998677 103=head1 Modules and Pragmata
fea59588 104
e5998677
SH
105XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
106go here. If Module::CoreList is updated, generate an initial draft of the
107following sections using F<Porting/corelist-perldelta.pl>. A paragraph summary
108for important changes should then be added by hand. In an ideal world,
109dual-life modules would have a F<Changes> file that could be cribbed.
fea59588 110
e5998677 111[ Within each section, list entries as a =item entry ]
83a5d6b6 112
e5998677 113=head2 New Modules and Pragmata
83a5d6b6 114
e5998677 115=over 4
338906ce
SH
116
117=item *
118
e5998677 119XXX
b05565aa 120
e5998677 121=back
83a5d6b6 122
e5998677 123=head2 Updated Modules and Pragmata
83a5d6b6 124
e5998677 125=over 4
e455391f
SH
126
127=item *
128
79a77127 129L<attributes> has been upgraded from version 0.26 to 0.27.
53902397 130
79a77127
SH
131=item *
132
c14a43b7
SH
133L<B> has been upgraded from version 1.57 to 1.58.
134
135=item *
136
137L<B::Deparse> has been upgraded from version 1.34 to 1.35.
138
139=item *
140
141L<Config::Perl::V> has been upgraded from version 0.23 to 0.24.
142
143=item *
144
79a77127 145L<Cwd> has been upgraded from version 3.55 to 3.56.
83a5d6b6 146
abec5bed
DIM
147=item *
148
149L<ExtUtils::Miniperl> has been upgraded from version 1.04 to 1.05.
150
151=item *
152
c14a43b7
SH
153L<ExtUtils::ParseXS> has been upgraded from version 3.27 to 3.28.
154
155=item *
156
157L<ExtUtils::Typemaps> has been upgraded from version 3.25 to 3.28.
158
159=item *
160
161L<File::Spec> has been upgraded from version 3.55 to 3.56.
162
163=item *
164
165L<if> has been upgraded from version 0.0603 to 0.0604.
166
167=item *
168
60dcce55
SH
169L<IO::Socket::IP> has been upgraded from version 0.36 to 0.37.
170
171=item *
172
79a77127
SH
173L<Module::CoreList> has been upgraded from version 5.20150320 to 5.20150420.
174
175Updated to cover the latest releases of Perl.
abec5bed
DIM
176
177=item *
178
9749148e
TC
179L<perl5db.pl> has been upgraded from 1.48 to 1.49.
180
181The debugger would cause an assertion failure. [perl #124127]
182
183=item *
184
abec5bed
DIM
185L<PerlIO::mmap> has been upgraded from version 0.013 to 0.014.
186
187=item *
188
79a77127 189L<utf8> has been upgraded from version 1.15 to 1.16.
abec5bed 190
2e4abf26
DG
191=item *
192
193L<warnings> has been upgraded from version 1.31 to 1.32.
194
e5998677 195=back
83a5d6b6 196
e5998677 197=head2 Removed Modules and Pragmata
83a5d6b6 198
e5998677 199=over 4
83a5d6b6
SH
200
201=item *
202
e5998677 203XXX
83a5d6b6 204
e5998677 205=back
83a5d6b6 206
e5998677 207=head1 Documentation
83a5d6b6 208
e5998677
SH
209XXX Changes to files in F<pod/> go here. Consider grouping entries by
210file and be sure to link to the appropriate page, e.g. L<perlfunc>.
83a5d6b6 211
e5998677 212=head2 New Documentation
b367c45d 213
e5998677 214XXX Changes which create B<new> files in F<pod/> go here.
b367c45d 215
e5998677 216=head3 L<XXX>
b367c45d 217
e5998677 218XXX Description of the purpose of the new file here
338906ce 219
e5998677 220=head2 Changes to Existing Documentation
338906ce 221
e5998677
SH
222XXX Changes which significantly change existing files in F<pod/> go here.
223However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
224section.
83a5d6b6 225
5de148ee
SH
226=head3 L<perlebcdic>
227
228=over 4
229
230=item *
231
232This document has been significantly updated in the light of recent
233improvements to EBCDIC support.
234
235=back
236
237=head3 L<perlhacktips>
238
239=over 4
240
241=item *
242
243Documentation has been added illustrating the perils of assuming the contents of
244static memory pointed to by the return values of Perl wrappers for C library
245functions doesn't change.
246
247=back
248
249=head3 L<perlvms>
83a5d6b6 250
e5998677 251=over 4
83a5d6b6
SH
252
253=item *
254
5de148ee 255Out-of-date and/or incorrect material has been removed.
83a5d6b6 256
e5998677 257=back
338906ce 258
e5998677 259=head1 Diagnostics
338906ce 260
e5998677
SH
261The following additions or changes have been made to diagnostic output,
262including warnings and fatal error messages. For the complete list of
263diagnostic messages, see L<perldiag>.
338906ce 264
e5998677
SH
265XXX New or changed warnings emitted by the core's C<C> code go here. Also
266include any changes in L<perldiag> that reconcile it to the C<C> code.
338906ce 267
e5998677 268=head2 New Diagnostics
9409f752 269
e5998677
SH
270XXX Newly added diagnostic messages go under here, separated into New Errors
271and New Warnings
9409f752 272
e5998677 273=head3 New Errors
03a97c81 274
e5998677 275=over 4
03a97c81
SH
276
277=item *
278
e5998677 279XXX L<message|perldiag/"message">
a790e348 280
e5998677 281=back
83a5d6b6 282
e5998677 283=head3 New Warnings
83a5d6b6 284
e5998677 285=over 4
126be117
JH
286
287=item *
288
e5998677 289XXX L<message|perldiag/"message">
83a5d6b6 290
a9c3e753 291=back
0939a951 292
e5998677 293=head2 Changes to Existing Diagnostics
d2fff9f6 294
e5998677 295XXX Changes (i.e. rewording) of diagnostic messages go here
e329daf3 296
cd7bac54 297=over 4
e329daf3 298
cd7bac54 299=item *
e329daf3 300
e5998677 301XXX Describe change here
83a5d6b6
SH
302
303=back
304
e5998677 305=head1 Utility Changes
83a5d6b6 306
e5998677
SH
307XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
308Most of these are built within the directory F<utils>.
83a5d6b6 309
e5998677
SH
310[ List utility changes as a =head2 entry for each utility and =item
311entries for each change
312Use L<XXX> with program names to get proper documentation linking. ]
83a5d6b6 313
e5998677 314=head2 L<XXX>
83a5d6b6
SH
315
316=over 4
317
318=item *
319
e5998677 320XXX
ba31029d 321
cd7bac54
S
322=back
323
e5998677 324=head1 Configuration and Compilation
cd7bac54 325
e5998677
SH
326XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
327go here. Any other changes to the Perl build process should be listed here.
328However, any platform-specific changes should be listed in the
329L</Platform Support> section, instead.
cd7bac54 330
e5998677 331[ List changes as a =item entry ].
cd7bac54
S
332
333=over 4
334
335=item *
336
e5998677 337XXX
cd7bac54
S
338
339=back
541e1e0d 340
a9c3e753 341=head1 Testing
cd7bac54 342
e5998677
SH
343XXX Any significant changes to the testing of a freshly built perl should be
344listed here. Changes which create B<new> files in F<t/> go here as do any
345large changes to the testing harness (e.g. when parallel testing was added).
346Changes to existing files in F<t/> aren't worth summarizing, although the bugs
347that they represent may be covered elsewhere.
348
349[ List each test improvement as a =item entry ]
350
b5d4d3b9 351=over 4
83b69bfd
DD
352
353=item *
354
e5998677 355XXX
13adb056 356
b5d4d3b9 357=back
391823f2 358
a9c3e753 359=head1 Platform Support
6c8457e9 360
e5998677 361XXX Any changes to platform support should be listed in the sections below.
fdcaecb7 362
e5998677
SH
363[ Within the sections, list each platform as a =item entry with specific
364changes as paragraphs below it. ]
ce1e892e 365
e5998677 366=head2 New Platforms
2af7c6b6 367
e5998677
SH
368XXX List any platforms that this version of perl compiles on, that previous
369versions did not. These will either be enabled by new files in the F<hints/>
370directories, or new subdirectories and F<README> files at the top level of the
371source tree.
8c847e66 372
2ff1ebfe 373=over 4
d345f487 374
e5998677 375=item XXX-some-platform
d345f487 376
e5998677 377XXX
cd7bac54 378
4dc623f0 379=back
353075a0 380
e5998677 381=head2 Discontinued Platforms
9f122eef 382
e5998677 383XXX List any platforms that this version of perl no longer compiles on.
2ec11c70 384
e5998677 385=over 4
2ec11c70 386
e5998677 387=item XXX-some-platform
2683609f 388
e5998677 389XXX
338906ce 390
4dc623f0 391=back
c7f058f0 392
e5998677 393=head2 Platform-Specific Notes
2bf83140 394
e5998677
SH
395XXX List any changes for specific platforms. This could include configuration
396and compilation changes or changes in portability/compatibility. However,
397changes within modules for platforms should generally be listed in the
398L</Modules and Pragmata> section.
041a5927 399
e5998677 400=over 4
041a5927 401
86e0176a 402=item Win32
69e954a5 403
86e0176a
TC
404F<miniperl.exe> is now built with C<-fno-strict-aliasing>, allowing
40564-bit builds to complete on GCC 4.8. [perl #123976]
406
407C<test-prep> again depends on C<test-prep-gcc> for GCC builds. [perl
408#124221]
69e954a5 409
e5998677 410=back
20b5e916 411
e5998677 412=head1 Internal Changes
d76c14eb 413
532ecd00
DM
414=over 4
415
416=item *
d76c14eb 417
532ecd00
DM
4185.21.2 introduced a new build option, C<-DPERL_OP_PARENT>, which causes
419the last C<op_sibling> pointer to refer back to the parent rather than
420being C<NULL>, and where instead a new flag indicates the end of the
421chain. In this release, the new implementation has been revised; in
422particular:
d547bad0 423
e5998677 424=over 4
d547bad0 425
8a95d307
FC
426=item *
427
532ecd00
DM
428On C<PERL_OP_PARENT> builds, the C<op_sibling> field has been renamed
429C<op_sibparent> to reflect its new dual purpose. Since the intention is that
430this field should primarily be accessed via macros, this change should be
431transparent for code written to work under C<PERL_OP_PARENT>.
432
433=item *
434
435The newly-introduced C<op_lastsib> flag bit has been renamed C<op_moresib>
436and its logic inverted; i.e. it is initialised to zero in a new op, and is
437changed to 1 when an op gains a sibling.
438
439=item *
440
441The function C<Perl_op_parent> is now only available on C<PERL_OP_PARENT>
442builds. Using it on a plain build will be a compile-timer error.
443
444=item *
445
446Three new macros, C<OpMORESIB_set>, C<OpLASTSIB_set>, C<OpMAYBESIB_set>
447have been added, which are intended to be be a low-level portable way to
448set C<op_sibling> / C<op_sibparent> while also updating C<op_moresib>.
449The first sets the sibling pointer to a new sibling, the second makes the
450op the last sibling, and the third conditionally does the first or second
451action. The C<op_sibling_splice()> function is retained as a higher-level
452interface that can also maintain consistency in the parent at the same time
453(e.g. by updating C<op_first> and C<op_last> where appropriate).
454
455=item *
456
457The macro C<OpSIBLING_set>, added in 5.21.2, has been removed. It didn't
458manipulate C<op_moresib> and has been superseded by C<OpMORESIB_set> et
459al.
460
461=item *
462
463The C<op_sibling_splice> function now accepts a null C<parent> argument
464where the splicing doesn't affect the first or last ops in the sibling
465chain, and thus where the parent doesn't need to be updated accordingly.
466
467=back
468
8a95d307 469
e5998677 470=back
338906ce 471
e5998677 472=head1 Selected Bug Fixes
338906ce 473
e5998677
SH
474XXX Important bug fixes in the core language are summarized here. Bug fixes in
475files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
338906ce 476
e5998677 477[ List each fix as a =item entry ]
338906ce 478
e5998677 479=over 4
338906ce
SH
480
481=item *
482
e42530d2
TC
483C<pack("D", $x)> and C<pack("F", $x)> now zero the padding on x86 long
484double builds. GCC 4.8 and later, under some build options, would
485either overwrite the zero-initialized padding, or bypass the
486initialized buffer entirely. This caused F<op/pack.t> to fail. [perl
487#123971]
2f304be9 488
9749148e
TC
489=item *
490
491Extending an array cloned from a parent thread could result in
492"Modification of a read-only value attempted" errors when attempting
493to modify the new elements. [perl #124127]
494
a9c3e753 495=back
ea13b07e 496
a9c3e753 497=head1 Known Problems
b65adbec 498
e5998677
SH
499XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
500tests that had to be C<TODO>ed for the release would be noted here. Unfixed
501platform specific bugs also go here.
b94c7836 502
e5998677 503[ List each fix as a =item entry ]
ce1e892e
KW
504
505=over 4
506
507=item *
508
e5998677 509XXX
ce1e892e 510
e5998677 511=back
ce1e892e 512
e5998677 513=head1 Errata From Previous Releases
ce1e892e 514
e5998677 515=over 4
ce1e892e 516
e5998677 517=item *
ce1e892e 518
e5998677
SH
519XXX Add anything here that we forgot to add, or were mistaken about, in
520the perldelta of a previous release.
ce1e892e 521
a9c3e753 522=back
e3e8f263 523
e5998677 524=head1 Obituary
0d42058e 525
e5998677
SH
526XXX If any significant core contributor has died, we've added a short obituary
527here.
0d42058e 528
e5998677 529=head1 Acknowledgements
0d42058e 530
e5998677 531XXX Generate this with:
0d42058e 532
e5998677 533 perl Porting/acknowledgements.pl v5.21.10..HEAD
f5b73711 534
44691e6f
AB
535=head1 Reporting Bugs
536
e08634c5
SH
537If you find what you think is a bug, you might check the articles recently
538posted to the comp.lang.perl.misc newsgroup and the perl bug database at
e5998677
SH
539https://rt.perl.org/ . There may also be information at
540http://www.perl.org/ , the Perl Home Page.
44691e6f 541
e08634c5
SH
542If you believe you have an unreported bug, please run the L<perlbug> program
543included with your release. Be sure to trim your bug down to a tiny but
544sufficient test case. Your bug report, along with the output of C<perl -V>,
545will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
546
547If the bug you are reporting has security implications, which make it
e08634c5
SH
548inappropriate to send to a publicly archived mailing list, then please send it
549to perl5-security-report@perl.org. This points to a closed subscription
550unarchived mailing list, which includes all the core committers, who will be
551able to help assess the impact of issues, figure out a resolution, and help
f9001595 552co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
553platforms on which Perl is supported. Please only use this address for
554security issues in the Perl core, not for modules independently distributed on
555CPAN.
44691e6f
AB
556
557=head1 SEE ALSO
558
e08634c5
SH
559The F<Changes> file for an explanation of how to view exhaustive details on
560what changed.
44691e6f
AB
561
562The F<INSTALL> file for how to build Perl.
563
564The F<README> file for general stuff.
565
566The F<Artistic> and F<Copying> files for copyright information.
567
568=cut