This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 60041a0991 (split constant mangling)
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
38663f11
DG
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.19.2
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
38663f11 12This document describes differences between the 5.19.1 release and the 5.19.2
e08634c5 13release.
6db9054f 14
38663f11
DG
15If you are upgrading from an earlier release such as 5.19.0, first read
16L<perl5191delta>, which describes differences between 5.19.0 and 5.19.1.
42bff0d9 17
38663f11 18=head1 Notice
42bff0d9 19
38663f11 20XXX Any important notices here
d69d1f92 21
38663f11 22=head1 Core Enhancements
287d2d21 23
38663f11
DG
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.
287d2d21 27
ba90f48b
FC
28=head2 More consistent prototype parsing
29
30Multiple semicolons in subroutine prototypes have long been tolerated and
31treated as a single semicolon. There was one case where this did not
32happen. A subroutine whose prototype begins with "*" or ";*" can affect
33whether a bareword is considered a method name or sub call. This now
34applies also to ";;;*".
35
36Whitespace has long been allowed inside subroutine prototypes, so
37C<sub( $ $ )> is equivalent to C<sub($$)>. But it was stripped when the
38subroutine was parse. Hence, whitespace was I<not> allowed in prototypes
39set by C<Scalar::Util::set_prototype>. Now it is permitted, and the parser
40no longer strips whitespace. This means C<prototype &mysub> returns the
41original prototype, whitespace and all.
287d2d21 42
38663f11 43=head1 Security
42bff0d9 44
38663f11
DG
45XXX Any security-related notices go here. In particular, any security
46vulnerabilities closed should be noted here rather than in the
47L</Selected Bug Fixes> section.
42bff0d9 48
38663f11 49[ List each security issue as a =head2 entry ]
42bff0d9 50
38663f11 51=head1 Incompatible Changes
42bff0d9 52
38663f11 53XXX For a release on a stable branch, this section aspires to be:
42bff0d9 54
38663f11
DG
55 There are no changes intentionally incompatible with 5.XXX.XXX
56 If any exist, they are bugs, and we request that you submit a
57 report. See L</Reporting Bugs> below.
42bff0d9 58
38663f11 59[ List each incompatible change as a =head2 entry ]
42bff0d9 60
38663f11 61=head1 Deprecations
42bff0d9 62
38663f11 63XXX Any deprecated features, syntax, modules etc. should be listed here.
42bff0d9 64
38663f11 65=head2 Module removals
42bff0d9 66
38663f11 67XXX Remove this section if inapplicable.
42bff0d9 68
8c33633d
FC
69The following modules will be removed from the core distribution in a
70future release, and will at that time need to be installed from CPAN.
71Distributions on CPAN which require these modules will need to list them as
72prerequisites.
42bff0d9 73
38663f11 74The core versions of these modules will now issue C<"deprecated">-category
8c33633d 75warnings to alert you to this fact. To silence these deprecation warnings,
38663f11 76install the modules in question from CPAN.
42bff0d9 77
38663f11 78Note that these are (with rare exceptions) fine modules that you are encouraged
8c33633d 79to continue to use. Their disinclusion from core primarily hinges on their
38663f11
DG
80necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
81not usually on concerns over their design.
42bff0d9 82
38663f11 83=over
42bff0d9 84
38663f11
DG
85XXX Note that deprecated modules should be listed here even if they are listed
86as an updated module in the L</Modules and Pragmata> section.
42bff0d9 87
38663f11 88=back
42bff0d9 89
38663f11 90[ List each other deprecation as a =head2 entry ]
42bff0d9 91
38663f11 92=head1 Performance Enhancements
42bff0d9 93
38663f11
DG
94XXX Changes which enhance performance without changing behaviour go here.
95There may well be none in a stable release.
42bff0d9 96
38663f11 97[ List each enhancement as a =item entry ]
42bff0d9 98
38663f11 99=over 4
42bff0d9
DG
100
101=item *
102
38663f11 103XXX
42bff0d9 104
38663f11 105=back
42bff0d9 106
38663f11 107=head1 Modules and Pragmata
42bff0d9 108
38663f11
DG
109XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
110go here. If Module::CoreList is updated, generate an initial draft of the
111following sections using F<Porting/corelist-perldelta.pl>, which prints stub
112entries to STDOUT. Results can be pasted in place of the '=head2' entries
113below. A paragraph summary for important changes should then be added by hand.
114In an ideal world, dual-life modules would have a F<Changes> file that could be
115cribbed.
42bff0d9 116
38663f11 117[ Within each section, list entries as a =item entry ]
42bff0d9 118
38663f11 119=head2 New Modules and Pragmata
42bff0d9 120
38663f11 121=over 4
42bff0d9
DG
122
123=item *
124
38663f11 125XXX
42bff0d9 126
38663f11 127=back
42bff0d9 128
38663f11 129=head2 Updated Modules and Pragmata
42bff0d9 130
38663f11 131=over 4
42bff0d9
DG
132
133=item *
134
893b07a1
NC
135L<ExtUtils::Embed> has been upgraded from version 1.30 to 1.31
136
137The generated C<C> code now incorporates bug fixes present in
138F<miniperlmain.c>, and has whitespace changes. It now uses
139C<#include "..."> for header files instead of C<< #include <...> >>.
140This should not make any difference, unless programs embedding C<libperl>
141happen to have local and incompatible files named F<EXTERN.h>, F<XSUB.h> or
142F<perl.h>, as these will now be picked up instead of the installed Perl
143headers.
144
145=item *
146
147L<ExtUtils::Miniperl> has been upgraded and given a version of 1.
148Previously it did not have a version number.
149
150C<writemain()> now takes an optional first argument. A reference to a scalar
151is treated as a filename to be opened and written to. Any other reference is
152used as the filehandle to write to. Otherwise the existing default remains,
153to write to C<STDOUT>.
154
155C<writemain()> has been refactored to use functions from L<ExtUtils::Embed>,
156reducing code size and duplication. The internal function C<canon()> has been
157deleted.
158
159=item *
160
70ba8092
TC
161L<POSIX> has been upgraded from version 1.33 to 1.34.
162
163C<POSIX::AUTOLOAD> will no longer infinitely recurse if the shared
164object fails to load.
42bff0d9 165
6e4979f3
TC
166=item *
167
168L<Storable> has been upgraded from version 2.43 to 2.44.
169
170Calling C<STORABLE_attach> hooks no longer leaks memory. [perl #118829]
171
38663f11 172=back
42bff0d9 173
38663f11 174=head2 Removed Modules and Pragmata
42bff0d9 175
38663f11 176=over 4
42bff0d9
DG
177
178=item *
179
38663f11 180XXX
42bff0d9 181
38663f11 182=back
42bff0d9 183
38663f11 184=head1 Documentation
42bff0d9 185
38663f11
DG
186XXX Changes to files in F<pod/> go here. Consider grouping entries by
187file and be sure to link to the appropriate page, e.g. L<perlfunc>.
42bff0d9 188
38663f11 189=head2 New Documentation
42bff0d9 190
38663f11 191XXX Changes which create B<new> files in F<pod/> go here.
42bff0d9 192
38663f11 193=head3 L<XXX>
42bff0d9 194
38663f11 195XXX Description of the purpose of the new file here
42bff0d9 196
38663f11 197=head2 Changes to Existing Documentation
42bff0d9 198
38663f11
DG
199XXX Changes which significantly change existing files in F<pod/> go here.
200However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
201section.
dbd04185 202
41f6d116 203=head3 L<perlexperiment>
dbd04185 204
38663f11 205=over 4
583aa5c2 206
1fdd5e53
KW
207=item *
208
41f6d116
RS
209Code in regular expressions, regular expression backtracking verbs,
210and lvalue subroutines are no longer listed as experimental. (This
211also affects L<perlre> and L<perlsub>.)
42bff0d9 212
38663f11 213=back
42bff0d9 214
38663f11 215=head1 Diagnostics
42bff0d9 216
38663f11
DG
217The following additions or changes have been made to diagnostic output,
218including warnings and fatal error messages. For the complete list of
219diagnostic messages, see L<perldiag>.
42bff0d9 220
38663f11
DG
221XXX New or changed warnings emitted by the core's C<C> code go here. Also
222include any changes in L<perldiag> that reconcile it to the C<C> code.
42bff0d9 223
38663f11 224=head2 New Diagnostics
42bff0d9 225
38663f11
DG
226XXX Newly added diagnostic messages go under here, separated into New Errors
227and New Warnings
42bff0d9 228
38663f11 229=head3 New Errors
42bff0d9 230
38663f11 231=over 4
42bff0d9
DG
232
233=item *
234
38663f11 235XXX L<message|perldiag/"message">
1fdd5e53 236
583aa5c2
RS
237=back
238
38663f11 239=head3 New Warnings
583aa5c2 240
38663f11 241=over 4
583aa5c2 242
b8a02ff1 243=item *
583aa5c2 244
38663f11 245XXX L<message|perldiag/"message">
583aa5c2 246
b8a02ff1 247=back
583aa5c2 248
38663f11 249=head2 Changes to Existing Diagnostics
96d496e4 250
38663f11 251XXX Changes (i.e. rewording) of diagnostic messages go here
b8a02ff1 252
38663f11 253=over 4
b8a02ff1
DG
254
255=item *
256
38663f11 257XXX Describe change here
96d496e4
RS
258
259=back
260
38663f11 261=head1 Utility Changes
d7bfa554 262
38663f11
DG
263XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
264Most of these are built within the directories F<utils> and F<x2p>.
d7bfa554 265
38663f11
DG
266[ List utility changes as a =head3 entry for each utility and =item
267entries for each change
268Use L<XXX> with program names to get proper documentation linking. ]
d7bfa554 269
38663f11 270=head3 L<XXX>
583aa5c2
RS
271
272=over 4
1993add8 273
e9912eaa 274=item *
ec985017 275
38663f11 276XXX
583aa5c2
RS
277
278=back
279
38663f11 280=head1 Configuration and Compilation
583aa5c2 281
38663f11
DG
282XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
283go here. Any other changes to the Perl build process should be listed here.
284However, any platform-specific changes should be listed in the
285L</Platform Support> section, instead.
583aa5c2 286
38663f11 287[ List changes as a =item entry ].
583aa5c2
RS
288
289=over 4
71e6aba6 290
d5f315e8
KW
291=item *
292
e38fc308
NC
293F<installperl> and F<installman>'s option handling has been refactored to use
294L<Getopt::Long>. Both are used by the F<Makefile> C<install> targets, and
295are not installed, so these changes are only likely to affect custom
296installation scripts.
297
298=over 4
299
300=item *
301
302single letter options now also have long names
303
304=item *
305
306invalid options are now rejected
307
308=item *
309
310command line arguments that are not options are now rejected
311
312=item *
313
314Each now has a C<--help> option to display the usage message.
315
316=back
317
318The behaviour for all valid documented invocations is unchanged.
d5f315e8 319
337fb649 320=back
2426c394 321
38663f11 322=head1 Testing
357b01df 323
38663f11
DG
324XXX Any significant changes to the testing of a freshly built perl should be
325listed here. Changes which create B<new> files in F<t/> go here as do any
326large changes to the testing harness (e.g. when parallel testing was added).
327Changes to existing files in F<t/> aren't worth summarizing, although the bugs
328that they represent may be covered elsewhere.
4724da03 329
38663f11 330[ List each test improvement as a =item entry ]
357b01df 331
583aa5c2 332=over 4
357b01df 333
583aa5c2 334=item *
357b01df 335
38663f11 336XXX
4724da03 337
38663f11 338=back
4724da03 339
38663f11 340=head1 Platform Support
4724da03 341
38663f11 342XXX Any changes to platform support should be listed in the sections below.
4724da03 343
38663f11
DG
344[ Within the sections, list each platform as a =item entry with specific
345changes as paragraphs below it. ]
4724da03 346
38663f11 347=head2 New Platforms
4724da03 348
38663f11
DG
349XXX List any platforms that this version of perl compiles on, that previous
350versions did not. These will either be enabled by new files in the F<hints/>
351directories, or new subdirectories and F<README> files at the top level of the
352source tree.
4724da03 353
38663f11 354=over 4
357b01df 355
38663f11 356=item XXX-some-platform
583aa5c2 357
38663f11 358XXX
4724da03 359
38663f11 360=back
583aa5c2 361
583aa5c2
RS
362=head2 Discontinued Platforms
363
38663f11
DG
364XXX List any platforms that this version of perl no longer compiles on.
365
583aa5c2
RS
366=over 4
367
38663f11 368=item XXX-some-platform
d7bfa554 369
38663f11 370XXX
d7bfa554 371
583aa5c2
RS
372=back
373
374=head2 Platform-Specific Notes
375
38663f11
DG
376XXX List any changes for specific platforms. This could include configuration
377and compilation changes or changes in portability/compatibility. However,
378changes within modules for platforms should generally be listed in the
379L</Modules and Pragmata> section.
583aa5c2 380
38663f11 381=over 4
a34da6c4 382
3a0b4597 383=item MidnightBSD
a34da6c4 384
3a0b4597 385C<objformat> was removed from version 0.4-RELEASE of MidnightBSD and had been
8c33633d
FC
386deprecated on earlier versions. This caused the build environment to be
387erroneously configured for C<a.out> rather than C<elf>. This has been now
3a0b4597 388been corrected.
a34da6c4 389
583aa5c2
RS
390=back
391
392=head1 Internal Changes
393
38663f11
DG
394XXX Changes which affect the interface available to C<XS> code go here. Other
395significant internal changes for future core maintainers should be noted as
396well.
583aa5c2 397
38663f11 398[ List each change as a =item entry ]
583aa5c2 399
38663f11 400=over 4
1de7c8e6 401
d7bfa554
DG
402=item *
403
eca6ff41
NC
404The Makefile shortcut targets for many rarely (or never) used testing and
405profiling targets have been removed, or merged into the only other Makefile
8c33633d 406target that uses them. Specifically, these targets are gone, along with
eca6ff41
NC
407documentation that referenced them or explained how to use them:
408
9d4d67dd
NC
409 check.third check.utf16 check.utf8 coretest minitest.prep
410 minitest.utf16 perl.config.dashg perl.config.dashpg
411 perl.config.gcov perl.gcov perl.gprof perl.gprof.config
412 perl.pixie perl.pixie.atom perl.pixie.config perl.pixie.irix
413 perl.third perl.third.config perl.valgrind.config purecovperl
414 pureperl quantperl test.deparse test.taintwarn test.third
415 test.torture test.utf16 test.utf8 test_notty.deparse
416 test_notty.third test_notty.valgrind test_prep.third
417 test_prep.valgrind torturetest ucheck ucheck.third ucheck.utf16
418 ucheck.valgrind utest utest.third utest.utf16 utest.valgrind
eca6ff41
NC
419
420It's still possible to run the relevant commands by "hand" - no underlying
421functionality has been removed.
d7bfa554 422
9c800862
KW
423=item *
424
425It is now possible to keep Perl from initializing locale handling.
426For the most part, Perl doesn't pay attention to locale. (See
427L<perllocale>.) Nonetheless, until now, on startup, it has always
428initialized locale handling to the system default, just in case the
429program being executed ends up using locales. (This is one of the first
430things a locale-aware program should do, long before Perl knows if it
431will actually be needed or not.) This works well except when Perl is
432embedded in another application which wants a locale that isn't the
433system default. Now, if the environment variable
434C<PERL_SKIP_LOCALE_INIT> is set at the time Perl is started, this
435initialization step is skipped. Prior to this, on Windows platforms,
436the only workaround for this deficiency was to use a hacked-up copy of
437internal Perl code. Applications that need to use older Perls can
438discover if the embedded Perl they are using needs the workaround by
439testing that the C preprocessor symbol C<HAS_SKIP_LOCALE_INIT> is not
440defined. (RT #38193)
441
aaf54772
FC
442=item *
443
444C<BmRARE> and C<BmPREVIOUS> have been removed. They were not used anywhere
445and are not part of the API. For XS modules, they are now #defined as 0.
446
583aa5c2
RS
447=back
448
449=head1 Selected Bug Fixes
450
38663f11
DG
451XXX Important bug fixes in the core language are summarized here. Bug fixes in
452files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
acfe52c8 453
38663f11 454[ List each fix as a =item entry ]
a2ef523e 455
38663f11 456=over 4
42dd67ca 457
e0d46238
FC
458=item *
459
9c800862
KW
460There have been several fixes related to Perl's handling of locales. RT
461#38193 was described above in L</Internal Changes>.
462Also fixed is #112208 in which the error string in C<$!> displayed as
463garbage in many UTF-8 locales;
464#118197, where the radix (decimal point) character had to be an ASCII
465character (which doesn't work for some non-Western languages);
466and #115808] in which C<POSIX::setlocale()> on failure returned an
467C<undef> which didn't warn about not being defined even if those
468warnings were enabled.
d7bfa554 469
81d3ed5a
FC
470=item *
471
472The dtrace sub-entry probe now works with lexical subs, instead of
473crashing [perl #118305].
474
0b023496
FC
475=item *
476
477Compiling a C<split> operator whose third argument is a named constant
478evaulating to 0 no longer causes the constant's value to change.
479
38663f11 480=back
d7bfa554 481
38663f11 482=head1 Known Problems
6810f0ad 483
38663f11
DG
484XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
485tests that had to be C<TODO>ed for the release would be noted here. Unfixed
486platform specific bugs also go here.
6810f0ad 487
38663f11 488[ List each fix as a =item entry ]
0e417e4d 489
38663f11 490=over 4
14fd9356
FC
491
492=item *
493
38663f11 494XXX
0e417e4d 495
38663f11 496=back
583aa5c2 497
38663f11 498=head1 Obituary
583aa5c2 499
38663f11
DG
500XXX If any significant core contributor has died, we've added a short obituary
501here.
583aa5c2 502
583aa5c2 503=head1 Acknowledgements
a75569c0 504
38663f11
DG
505XXX Generate this with:
506
507 perl Porting/acknowledgements.pl v5.19.1..HEAD
f5b73711 508
44691e6f
AB
509=head1 Reporting Bugs
510
e08634c5
SH
511If you find what you think is a bug, you might check the articles recently
512posted to the comp.lang.perl.misc newsgroup and the perl bug database at
513http://rt.perl.org/perlbug/ . There may also be information at
514http://www.perl.org/ , the Perl Home Page.
44691e6f 515
e08634c5
SH
516If you believe you have an unreported bug, please run the L<perlbug> program
517included with your release. Be sure to trim your bug down to a tiny but
518sufficient test case. Your bug report, along with the output of C<perl -V>,
519will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
520
521If the bug you are reporting has security implications, which make it
e08634c5
SH
522inappropriate to send to a publicly archived mailing list, then please send it
523to perl5-security-report@perl.org. This points to a closed subscription
524unarchived mailing list, which includes all the core committers, who will be
525able to help assess the impact of issues, figure out a resolution, and help
f9001595 526co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
527platforms on which Perl is supported. Please only use this address for
528security issues in the Perl core, not for modules independently distributed on
529CPAN.
44691e6f
AB
530
531=head1 SEE ALSO
532
e08634c5
SH
533The F<Changes> file for an explanation of how to view exhaustive details on
534what changed.
44691e6f
AB
535
536The F<INSTALL> file for how to build Perl.
537
538The F<README> file for general stuff.
539
540The F<Artistic> and F<Copying> files for copyright information.
541
542=cut