This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for changed AMAGIC table mechanism
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
f9001595
RS
5[ this is a template for a new perldelta file. Any text flagged as
6XXX needs to be processed before release. ]
2630d42b 7
f9001595 8perldelta - what is new for perl v5.17.0
27f00e3d 9
f9001595 10=head1 DESCRIPTION
2630d42b 11
f9001595
RS
12This document describes differences between the 5.16.0 release and
13the 5.17.0 release.
7620cb10 14
f9001595
RS
15If you are upgrading from an earlier release such as 5.16.0, first read
16L<perl5160delta>, which describes differences between 5.15.0 and
175.16.0.
d7c042c9 18
f9001595 19=head1 Notice
d7c042c9 20
f9001595 21XXX Any important notices here
d7c042c9 22
f9001595 23=head1 Core Enhancements
985213f2 24
f9001595
RS
25XXX New core language features go here. Summarise user-visible core language
26enhancements. Particularly prominent performance optimisations could go
27here, but most should go in the L</Performance Enhancements> section.
977c1d31 28
f9001595 29[ List each enhancement as a =head2 entry ]
977c1d31 30
f9001595 31=head1 Security
985213f2 32
f9001595
RS
33XXX Any security-related notices go here. In particular, any security
34vulnerabilities closed should be noted here rather than in the
35L</Selected Bug Fixes> section.
985213f2 36
f9001595 37[ List each security issue as a =head2 entry ]
2e2b2571 38
f9001595 39=head1 Incompatible Changes
2e2b2571 40
f9001595 41XXX For a release on a stable branch, this section aspires to be:
b240fc0f 42
f9001595
RS
43 There are no changes intentionally incompatible with 5.XXX.XXX
44 If any exist, they are bugs, and we request that you submit a
45 report. See L</Reporting Bugs> below.
27f00e3d 46
f9001595 47[ List each incompatible change as a =head2 entry ]
27f00e3d 48
f9001595 49=head1 Deprecations
cadced9f 50
f9001595
RS
51XXX Any deprecated features, syntax, modules etc. should be listed here.
52In particular, deprecated modules should be listed here even if they are
53listed as an updated module in the L</Modules and Pragmata> section.
cadced9f 54
f9001595 55[ List each deprecation as a =head2 entry ]
05c8f9ed 56
f9001595 57=head1 Performance Enhancements
05c8f9ed 58
f9001595
RS
59XXX Changes which enhance performance without changing behaviour go here. There
60may well be none in a stable release.
632c5d30 61
f9001595 62[ List each enhancement as a =item entry ]
632c5d30 63
f9001595 64=over 4
05c8f9ed
RS
65
66=item *
67
f9001595 68XXX
95ce428c 69
2630d42b 70=back
95ce428c 71
f9001595 72=head1 Modules and Pragmata
c11980ad 73
f9001595
RS
74XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
75go here. If Module::CoreList is updated, generate an initial draft of the
76following sections using F<Porting/corelist-perldelta.pl>, which prints stub
77entries to STDOUT. Results can be pasted in place of the '=head2' entries
78below. A paragraph summary for important changes should then be added by hand.
79In an ideal world, dual-life modules would have a F<Changes> file that could be
80cribbed.
c88a046d 81
f9001595 82[ Within each section, list entries as a =item entry ]
6c69e197 83
f9001595 84=head2 New Modules and Pragmata
c88a046d 85
f9001595 86=over 4
c88a046d
A
87
88=item *
89
f9001595 90XXX
c88a046d 91
2630d42b 92=back
c88a046d 93
f9001595 94=head2 Updated Modules and Pragmata
05c8f9ed 95
f9001595 96=over 4
75ff5956 97
2630d42b 98=item *
c11980ad 99
435b0bdb
FC
100L<File::stat> has been upgraded from version 1.05 to 1.06.
101
102C<File::stat> ignores the L<filetest> pragma, and warns when used in
103combination therewith. But it was not warning for C<-r>. This has been
104fixed [perl #111640].
105
be8dfbf7
FC
106C<-p> now works, and does not return false for pipes [perl #111638].
107
435b0bdb
FC
108=item *
109
110L<Hash::Util> has been upgraded from version 0.11 to 0.12.
83fb037c
FC
111
112C<hash_unlocked> and C<hashref_unlocked> now returns true if the hash is
113unlocked, instead of always returning false [perl #112126].
114
115C<hash_unlocked>, C<hashref_unlocked>, C<lock_hash_recurse> and
116C<unlock_hash_recurse> are now exportable [perl #112126].
117
118Two new functions, C<hash_locked> and C<hashref_locked>, have been added.
119Oddly enough, these two functions were already exported, even though they
120did not exist [perl #112126].
121
122=item *
123
435b0bdb 124L<Storable> has been upgraded from version 2.34 to 2.35.
18d0dfa8
FC
125
126Modifying C<$_[0]> within C<STORABLE_freeze> no longer results in crashes
127[perl #112358].
843331c7 128
2630d42b 129=back
c11980ad 130
f9001595 131=head2 Removed Modules and Pragmata
ecd144ea 132
f9001595 133=over 4
05c8f9ed
RS
134
135=item *
136
f9001595 137XXX
9dea6244 138
204b72a4 139=back
9dea6244 140
f9001595 141=head1 Documentation
2a7afa74 142
f9001595
RS
143XXX Changes to files in F<pod/> go here. Consider grouping entries by
144file and be sure to link to the appropriate page, e.g. L<perlfunc>.
e9e4ee62 145
f9001595 146=head2 New Documentation
937a45d0 147
f9001595 148XXX Changes which create B<new> files in F<pod/> go here.
ef337e16 149
f9001595 150=head3 L<XXX>
ef337e16 151
f9001595 152XXX Description of the purpose of the new file here
679b54e7 153
f9001595 154=head2 Changes to Existing Documentation
39de7394 155
f9001595
RS
156XXX Changes which significantly change existing files in F<pod/> go here.
157However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
158section.
2630d42b 159
f9001595 160=head3 L<XXX>
2630d42b 161
f9001595 162=over 4
52272450 163
84ecb73f
SM
164=item *
165
f9001595 166XXX Description of the change here
84ecb73f 167
52deee2e 168=back
5dd80d85 169
f9001595 170=head1 Diagnostics
52272450 171
f9001595
RS
172The following additions or changes have been made to diagnostic output,
173including warnings and fatal error messages. For the complete list of
174diagnostic messages, see L<perldiag>.
249950d7 175
f9001595
RS
176XXX New or changed warnings emitted by the core's C<C> code go here. Also
177include any changes in L<perldiag> that reconcile it to the C<C> code.
05c8f9ed 178
f9001595
RS
179[ Within each section, list entries as a =item entry that links to perldiag,
180 e.g.
a1d95121 181
f9001595 182 =item *
977c1d31 183
f9001595
RS
184 L<Invalid version object|perldiag/"Invalid version object">
185]
977c1d31 186
f9001595 187=head2 New Diagnostics
05c8f9ed 188
f9001595 189XXX Newly added diagnostic messages go here
05c8f9ed 190
f9001595 191=head3 New Errors
977c1d31 192
f9001595 193=over 4
39ea6a4b 194
05c8f9ed
RS
195=item *
196
f9001595 197XXX L<message|perldiag/"message">
39ea6a4b 198
977c1d31 199=back
ea317ccb 200
f9001595 201=head3 New Warnings
05c8f9ed 202
f9001595 203=over 4
05c8f9ed
RS
204
205=item *
d5dc7001 206
f9001595 207XXX L<message|perldiag/"message">
d5dc7001 208
2630d42b 209=back
d5dc7001 210
f9001595 211=head2 Changes to Existing Diagnostics
05c8f9ed 212
f9001595 213XXX Changes (i.e. rewording) of diagnostic messages go here
05c8f9ed 214
f9001595 215=over 4
05c8f9ed
RS
216
217=item *
218
f9001595 219XXX Describe change here
05c8f9ed 220
f9001595 221=back
05c8f9ed 222
f9001595 223=head1 Utility Changes
05c8f9ed 224
f9001595
RS
225XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
226here. Most of these are built within the directories F<utils> and F<x2p>.
05c8f9ed 227
f9001595
RS
228[ List utility changes as a =head3 entry for each utility and =item
229entries for each change
230Use L<XXX> with program names to get proper documentation linking. ]
05c8f9ed 231
f9001595 232=head3 L<XXX>
05c8f9ed 233
f9001595 234=over 4
05c8f9ed
RS
235
236=item *
237
f9001595 238XXX
05c8f9ed 239
f9001595 240=back
05c8f9ed 241
f9001595 242=head1 Configuration and Compilation
05c8f9ed 243
f9001595
RS
244XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
245go here. Any other changes to the Perl build process should be listed here.
246However, any platform-specific changes should be listed in the
247L</Platform Support> section, instead.
05c8f9ed 248
f9001595 249[ List changes as a =item entry ].
05c8f9ed 250
f9001595 251=over 4
05c8f9ed
RS
252
253=item *
254
f9001595 255XXX
05c8f9ed 256
f9001595 257=back
05c8f9ed 258
f9001595 259=head1 Testing
05c8f9ed 260
f9001595
RS
261XXX Any significant changes to the testing of a freshly built perl should be
262listed here. Changes which create B<new> files in F<t/> go here as do any
263large changes to the testing harness (e.g. when parallel testing was added).
264Changes to existing files in F<t/> aren't worth summarising, although the bugs
265that they represent may be covered elsewhere.
05c8f9ed 266
f9001595 267[ List each test improvement as a =item entry ]
05c8f9ed 268
f9001595 269=over 4
05c8f9ed
RS
270
271=item *
272
f9001595 273XXX
05c8f9ed 274
f9001595 275=back
05c8f9ed 276
f9001595 277=head1 Platform Support
05c8f9ed 278
f9001595 279XXX Any changes to platform support should be listed in the sections below.
05c8f9ed 280
f9001595
RS
281[ Within the sections, list each platform as a =item entry with specific
282changes as paragraphs below it. ]
05c8f9ed 283
f9001595 284=head2 New Platforms
05c8f9ed 285
f9001595
RS
286XXX List any platforms that this version of perl compiles on, that previous
287versions did not. These will either be enabled by new files in the F<hints/>
288directories, or new subdirectories and F<README> files at the top level of the
289source tree.
05c8f9ed 290
f9001595 291=over 4
05c8f9ed 292
f9001595 293=item XXX-some-platform
05c8f9ed 294
f9001595 295XXX
05c8f9ed 296
f9001595 297=back
05c8f9ed 298
f9001595 299=head2 Discontinued Platforms
05c8f9ed 300
f9001595 301XXX List any platforms that this version of perl no longer compiles on.
05c8f9ed 302
f9001595 303=over 4
05c8f9ed 304
f9001595 305=item XXX-some-platform
05c8f9ed 306
f9001595 307XXX
05c8f9ed 308
f9001595 309=back
05c8f9ed 310
f9001595 311=head2 Platform-Specific Notes
05c8f9ed 312
f9001595
RS
313XXX List any changes for specific platforms. This could include configuration
314and compilation changes or changes in portability/compatibility. However,
315changes within modules for platforms should generally be listed in the
316L</Modules and Pragmata> section.
05c8f9ed 317
f9001595 318=over 4
05c8f9ed 319
f9001595 320=item XXX-some-platform
05c8f9ed 321
f9001595 322XXX
05c8f9ed 323
f9001595 324=back
05c8f9ed 325
f9001595 326=head1 Internal Changes
05c8f9ed 327
f9001595
RS
328XXX Changes which affect the interface available to C<XS> code go here.
329Other significant internal changes for future core maintainers should
330be noted as well.
05c8f9ed 331
f9001595 332[ List each change as a =item entry ]
05c8f9ed 333
f9001595 334=over 4
05c8f9ed
RS
335
336=item *
337
a3367fba
FC
338The C<SVf_AMAGIC> flag to indicate overloading is now on the stash, not the
339object. It is now set automatically whenever a method or @ISA changes, so
340its meaning has changed, too. It now means "potentially overloaded". When
341the overload table is calculated, the flag is automatically turned off if
342there is no overloading, so there should be no noticeable slowdown.
343
344The staleness of the overload tables is now checked when overload methods
345are invoked, rather than during C<bless>.
346
347"A" magic is gone. The changes to the handling of the C<SVf_AMAGIC> flag
348eliminate the need for it.
349
350The core no longer increments C<PL_amagic_generation> (it doesn't need to).
351But an XS module can still increment it to mark all overload tables as
352stale. (It is still not part of the API, though.) Do not rely on this.
353It may be deleted in the next release.
354
355The fallback overload setting is now stored in its own stash entry, called
356"(fallback".
05c8f9ed 357
f9001595 358=back
05c8f9ed 359
f9001595 360=head1 Selected Bug Fixes
05c8f9ed 361
f9001595
RS
362XXX Important bug fixes in the core language are summarised here.
363Bug fixes in files in F<ext/> and F<lib/> are best summarised in
364L</Modules and Pragmata>.
e2e06450 365
f9001595 366[ List each fix as a =item entry ]
e2e06450 367
f9001595 368=over 4
05c8f9ed
RS
369
370=item *
371
cba2262a
FC
372C<goto ''> now looks for an empty label, producing the "goto must have
373label" error message, instead of exiting the program [perl #111794].
e2e06450 374
b9b99128
FC
375=item *
376
377C<goto "\0"> now dies with "Can't find label" instead of "goto must have
378label".
379
47fb883d
FC
380=item *
381
382The C function C<hv_store> used to result in crashes when used on C<%^H>
383[perl #111000].
384
5f0f4bc0
FC
385=item *
386
387A call checker attached to a closure prototype via C<cv_set_call_checker>
388is now copied to closures cloned from it. So C<cv_set_call_checker> now
389works inside an attribute handler for a closure.
390
ba0d99ee
FC
391=item *
392
393Writing to C<$^N> used to have no effect. Now it croaks with "Modification
394of a read-only value" by default, but that can be overridden by a custom
395regular expression engine, as with C<$1> [perl #112184].
396
72035cb1
FC
397=item *
398
399C<undef> on a control character glob (C<undef *^H>) no longer emits an
400erroneous warning about ambiguity [perl #112456].
401
ceb0881c
FC
402=item *
403
404For efficiency's sake, many operators and built-in functions return the
405same scalar each time. Lvalue subroutines and subroutines in the CORE::
406namespace were allowing this implementation detail to leak through.
407C<print &CORE::uc("a"), &CORE::uc("b")> used to print "BB". The same thing
408would happen with an lvalue subroutine returning the return value of C<uc>.
409Now the value is copied in such cases.
410
89cbc6b8
FC
411=item *
412
413C<method {}> syntax with an empty block or a block returning an empty list
414used to crash or use some random value left on the stack as its invocant.
415Now it produces an error.
416
c6b15a5a
FC
417=item *
418
419C<vec> now works with extremely large offsets (>2 GB) [perl #111730].
420
2630d42b 421=back
e2e06450 422
2630d42b 423=head1 Known Problems
e2e06450 424
f9001595
RS
425XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
426tests that had to be C<TODO>ed for the release would be noted here, unless
427they were specific to a particular platform (see below).
fcc3aaa8 428
f9001595
RS
429This is a list of some significant unfixed bugs, which are regressions
430from either 5.XXX.XXX or 5.XXX.XXX.
05c8f9ed 431
f9001595 432[ List each fix as a =item entry ]
05c8f9ed 433
f9001595 434=over 4
05c8f9ed
RS
435
436=item *
437
f9001595 438XXX
c0154fe2 439
05c8f9ed 440=back
d5dc7001 441
f9001595
RS
442=head1 Obituary
443
444XXX If any significant core contributor has died, we've added a short obituary
445here.
d5dc7001 446
2630d42b 447=head1 Acknowledgements
d5dc7001 448
f9001595
RS
449XXX Generate this with:
450
451 perl Porting/acknowledgements.pl v5.16.0..HEAD
29cf780c 452
44691e6f
AB
453=head1 Reporting Bugs
454
455If you find what you think is a bug, you might check the articles
52deee2e 456recently posted to the comp.lang.perl.misc newsgroup and the perl
f9001595
RS
457bug database at http://rt.perl.org/perlbug/ . There may also be
458information at http://www.perl.org/ , the Perl Home Page.
44691e6f
AB
459
460If you believe you have an unreported bug, please run the L<perlbug>
52deee2e
DR
461program included with your release. Be sure to trim your bug down
462to a tiny but sufficient test case. Your bug report, along with the
463output of C<perl -V>, will be sent off to perlbug@perl.org to be
464analysed by the Perl porting team.
44691e6f
AB
465
466If the bug you are reporting has security implications, which make it
f9001595
RS
467inappropriate to send to a publicly archived mailing list, then please send
468it to perl5-security-report@perl.org. This points to a closed subscription
469unarchived mailing list, which includes
470all the core committers, who will be able
471to help assess the impact of issues, figure out a resolution, and help
472co-ordinate the release of patches to mitigate or fix the problem across all
473platforms on which Perl is supported. Please only use this address for
474security issues in the Perl core, not for modules independently
475distributed on CPAN.
44691e6f
AB
476
477=head1 SEE ALSO
478
52deee2e
DR
479The F<Changes> file for an explanation of how to view exhaustive details
480on what changed.
44691e6f
AB
481
482The F<INSTALL> file for how to build Perl.
483
484The F<README> file for general stuff.
485
486The F<Artistic> and F<Copying> files for copyright information.
487
488=cut