This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
4a9b9b91933d589ec4f47ffdb01817fab458a6ed
[perl5.git] / pod / perldelta.pod
1 =encoding utf8
2
3 =head1 NAME
4
5 [ this is a template for a new perldelta file.  Any text flagged as XXX needs
6 to be processed before release. ]
7
8 perldelta - what is new for perl v5.19.1
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.19.0 release and the 5.19.1
13 release.
14
15 =head1 Notice
16
17 XXX Any important notices here
18
19 =head1 Core Enhancements
20
21 XXX New core language features go here.  Summarize user-visible core language
22 enhancements.  Particularly prominent performance optimisations could go
23 here, but most should go in the L</Performance Enhancements> section.
24
25 [ List each enhancement as a =head2 entry ]
26
27 =head1 Security
28
29 XXX Any security-related notices go here.  In particular, any security
30 vulnerabilities closed should be noted here rather than in the
31 L</Selected Bug Fixes> section.
32
33 [ List each security issue as a =head2 entry ]
34
35 =head1 Incompatible Changes
36
37 XXX For a release on a stable branch, this section aspires to be:
38
39     There are no changes intentionally incompatible with 5.XXX.XXX
40     If any exist, they are bugs, and we request that you submit a
41     report.  See L</Reporting Bugs> below.
42
43 [ List each incompatible change as a =head2 entry ]
44
45 =head2 Most regex engine global state eliminated
46
47 As part of this series of fixes it was necessary to change the API of
48 Perl_re_intuit_start().  See L</Internal Changes> for more.
49
50 =head2 Locale decimal point character no longer leaks outside of S<C<use locale>> scope
51
52 This is actually a bug fix, but some code has come to rely on the bug
53 being present, so this change is listed here.  The current locale that
54 the program is running under is not supposed to be visible to Perl code
55 except within the scope of a S<C<use locale>>.  However, until now under
56 certain circumstances, the character used for a decimal point (often a
57 comma) leaked outside the scope.  If your code is affected by this
58 change, simply add a S<C<use locale>>.
59
60 =head1 Deprecations
61
62 XXX Any deprecated features, syntax, modules etc. should be listed here.
63
64 =head2 Module removals
65
66 XXX Remove this section if inapplicable.
67
68 The following modules will be removed from the core distribution in a future
69 release, and will at that time need to be installed from CPAN. Distributions
70 on CPAN which require these modules will need to list them as prerequisites.
71
72 The core versions of these modules will now issue C<"deprecated">-category
73 warnings to alert you to this fact. To silence these deprecation warnings,
74 install the modules in question from CPAN.
75
76 Note that these are (with rare exceptions) fine modules that you are encouraged
77 to continue to use. Their disinclusion from core primarily hinges on their
78 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
79 not usually on concerns over their design.
80
81 XXX Note that deprecated modules should be listed here even if they are listed
82 as an updated module in the L</Modules and Pragmata> section.
83
84 =over
85
86 =item *
87
88 XXXX
89
90 =back
91
92 [ List each other deprecation as a =head2 entry ]
93
94 =head1 Performance Enhancements
95
96 XXX Changes which enhance performance without changing behaviour go here.
97 There may well be none in a stable release.
98
99 [ List each enhancement as a =item entry ]
100
101 =over 4
102
103 =item *
104
105 Perl has a new copy-on-write mechanism that avoids the need to copy the
106 internal string buffer when assigning from one scalar to another. This
107 makes copying large strings appear much faster.  Modifying one of the two
108 (or more) strings after an assignment will force a copy internally. This
109 makes it unnecessary to pass strings by reference for efficiency.
110
111 This feature was already available in 5.18.0, but wasn't enabled by
112 default. It is the default now, and so you no longer need build perl with
113 the F<Configure> argument:
114
115     -Accflags=PERL_NEW_COPY_ON_WRITE
116
117 It can be disabled (for now) in a perl build with:
118
119     -Accflags=PERL_NO_COW
120
121 =back
122
123 =head1 Modules and Pragmata
124
125 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
126 go here.  If Module::CoreList is updated, generate an initial draft of the
127 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
128 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
129 below.  A paragraph summary for important changes should then be added by hand.
130 In an ideal world, dual-life modules would have a F<Changes> file that could be
131 cribbed.
132
133 [ Within each section, list entries as a =item entry ]
134
135 =head2 New Modules and Pragmata
136
137 =over 4
138
139 =item *
140
141 L<Module::CoreList::Utils> which provides information on which core and
142 dual-life utilities shipped with each version of L<perl>.
143
144 =back
145
146 =head2 Updated Modules and Pragmata
147
148 =over 4
149
150 =item *
151
152 L<B::Deparse> has been upgraded from version 1.20 to 1.21.
153
154 C<foreach my $lexical> is now deparsed correctly with the B<-p> option.
155 [RT #117081]
156
157 The B<-l> option no longer puts form feeds in the middle of a line when
158 outputting C<map> and C<grep> blocks. [RT #117311]
159
160 Elements of C<%#>, such as C<$# {foo}> and C<${#}{foo}> are now deparsed
161 correctly. [RT #117531]
162
163 =item *
164
165 L<DB> has been updated from 1.05 to 1.06 and L<perl5db.pl> from 1.39_10
166 to 1.40.  The call depth allowed by default in the debugger is now 1000
167 rather than 100.
168
169 =item *
170
171 L<File::Spec> has been upgraded from version 3.40 to 3.41.
172
173 C<tmpdir> now respects changes to environment variables from which the
174 temporary directory is derived. [RT #88940]
175
176 =item *
177
178 L<Test::Harness> has been upgraded from version 3.26 to 3.28
179
180 Memory usage is dramatically reduced. t/harness now uses about 10% of the
181 memory used by 3.26 and earlier.
182
183 C<PERL5LIB> is always propagated to a test's C<@INC>, even under C<-T>.
184
185 =item *
186
187 L<Unicode::UCD> has been upgraded from version 0.51 to 0.52.
188
189 A function, L<Unicode::UCD/search_invlist()> is now available to do
190 search an inversion list or map for a code point.
191
192 =back
193
194 =head2 Removed Modules and Pragmata
195
196 =over 4
197
198 =item *
199
200 XXX
201
202 =back
203
204 =head1 Documentation
205
206 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
207 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
208
209 =head2 New Documentation
210
211 XXX Changes which create B<new> files in F<pod/> go here.
212
213 =head3 L<XXX>
214
215 XXX Description of the purpose of the new file here
216
217 =head2 Changes to Existing Documentation
218
219 XXX Changes which significantly change existing files in F<pod/> go here.
220 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
221 section.
222
223 =head3 L<perllocale>
224
225 =over
226
227 =item *
228
229 Update to mention fc(), \F
230
231 =back
232
233 =head3 L<perltrap>
234
235 =over 4
236
237 =item *
238
239 There is now a L<JavaScript|perltrap/JavaScript Traps> section.
240
241 =back
242
243 =head1 Diagnostics
244
245 The following additions or changes have been made to diagnostic output,
246 including warnings and fatal error messages.  For the complete list of
247 diagnostic messages, see L<perldiag>.
248
249 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
250 include any changes in L<perldiag> that reconcile it to the C<C> code.
251
252 =head2 New Diagnostics
253
254 XXX Newly added diagnostic messages go under here, separated into New Errors
255 and New Warnings
256
257 =head3 New Errors
258
259 =over 4
260
261 =item *
262
263 XXX L<message|perldiag/"message">
264
265 =back
266
267 =head3 New Warnings
268
269 =over 4
270
271 =item *
272
273 L<A sequence of multiple spaces in a charnames alias definition is deprecated|perldiag/"A sequence of multiple spaces in a charnames alias definition is deprecated">
274
275 L<Trailing white-space in a charnames alias definition is deprecated|perldiag/"Trailing white-space in a charnames alias definition is deprecated">
276
277 These two deprecation warnings involving C<\N{...}> were incorrectly
278 implemented.  They did not warn by default (now they do) and could not be
279 made fatal via C<use warnings FATAL => 'deprecated'> (now they can).
280
281 =back
282
283 =head2 Changes to Existing Diagnostics
284
285 XXX Changes (i.e. rewording) of diagnostic messages go here
286
287 =over 4
288
289 =item *
290
291 XXX Describe change here
292
293 =back
294
295 =head1 Utility Changes
296
297 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
298 Most of these are built within the directories F<utils> and F<x2p>.
299
300 [ List utility changes as a =head3 entry for each utility and =item
301 entries for each change
302 Use L<XXX> with program names to get proper documentation linking. ]
303
304 =head3 F<bisect.pl> enhancements
305
306 The git bisection tool F<Porting/bisect.pl> has had many enhancements.
307
308 =over 4
309
310 =item *
311
312 Can optionally run the test case with a timeout.
313
314 =item *
315
316 Can now run in-place in a clean git checkout.
317
318 =item *
319
320 Can run the test case under C<valgrind>.
321
322 =item *
323
324 Can apply user supplied patches and fixes to the source checkout before
325 building.
326
327 =item *
328
329 Now has fixups to enable building several more historical ranges of bleadperl,
330 which can be useful for pinpointing the origins of bugs or behaviour changes.
331
332 =back
333
334 It is provided as part of the source distribution but not installed because
335 it is not self-contained as it relies on being run from within a git
336 checkout. Note also that it makes no attempt to fix tests, correct runtime
337 bugs or make something useful to install - its purpose is to make minimal
338 changes to get any historical revision of interest to build and run as close
339 as possible to "as-was", and thereby make C<git bisect> easy to use.
340
341 =head1 Configuration and Compilation
342
343 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
344 go here.  Any other changes to the Perl build process should be listed here.
345 However, any platform-specific changes should be listed in the
346 L</Platform Support> section, instead.
347
348 [ List changes as a =item entry ].
349
350 =over 4
351
352 =item *
353
354 XXX
355
356 =back
357
358 =head1 Testing
359
360 XXX Any significant changes to the testing of a freshly built perl should be
361 listed here.  Changes which create B<new> files in F<t/> go here as do any
362 large changes to the testing harness (e.g. when parallel testing was added).
363 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
364 that they represent may be covered elsewhere.
365
366 [ List each test improvement as a =item entry ]
367
368 =over 4
369
370 =item *
371
372 XXX
373
374 =back
375
376 =head1 Platform Support
377
378 XXX Any changes to platform support should be listed in the sections below.
379
380 [ Within the sections, list each platform as a =item entry with specific
381 changes as paragraphs below it. ]
382
383 =head2 New Platforms
384
385 XXX List any platforms that this version of perl compiles on, that previous
386 versions did not.  These will either be enabled by new files in the F<hints/>
387 directories, or new subdirectories and F<README> files at the top level of the
388 source tree.
389
390 =over 4
391
392 =item XXX-some-platform
393
394 XXX
395
396 =back
397
398 =head2 Discontinued Platforms
399
400 XXX List any platforms that this version of perl no longer compiles on.
401
402 =over 4
403
404 =item DG/UX
405
406 DG/UX was a Unix sold by Data General. The last release was in April 2001.
407 It only runs on Data General's own hardware.
408
409 =item XXX-some-platform
410
411 XXX
412
413 =back
414
415 =head2 Platform-Specific Notes
416
417 XXX List any changes for specific platforms.  This could include configuration
418 and compilation changes or changes in portability/compatibility.  However,
419 changes within modules for platforms should generally be listed in the
420 L</Modules and Pragmata> section.
421
422 =over 4
423
424 =item Mixed-endian platforms
425
426 The code supporting C<pack> and C<unpack> operations on mixed endian
427 platforms has been removed. We believe that Perl has long been unable to
428 build on mixed endian architectures (such as PDP-11s), so we don't think
429 that this change will affect any platforms which are able to build v5.18.0.
430
431 =item Windows
432
433 The BUILD_STATIC and ALL_STATIC makefile options for linking some or (nearly)
434 all extensions statically (into perl519.dll, and into a separate
435 perl-static.exe too) were broken for MinGW builds. This has now been fixed.
436
437 The ALL_STATIC option has also been improved to include the Encode and Win32
438 extensions (for both VC++ and MinGW builds).
439
440 =back
441
442 =head1 Internal Changes
443
444 XXX Changes which affect the interface available to C<XS> code go here.  Other
445 significant internal changes for future core maintainers should be noted as
446 well.
447
448 =over 4
449
450 =item *
451
452 Perl's new copy-on-write mechanism  (which is now enabled by default),
453 allows any C<SvPOK> scalar to be automatically upgraded to a copy-on-write
454 scalar when copied. A reference count on the string buffer is stored in
455 the string buffer itself.
456
457 For example:
458
459     $ perl -MDevel::Peek -e'$a="abc"; $b = $a; Dump $a; Dump $b'
460     SV = PV(0x260cd80) at 0x2620ad8
461       REFCNT = 1
462       FLAGS = (POK,IsCOW,pPOK)
463       PV = 0x2619bc0 "abc"\0
464       CUR = 3
465       LEN = 16
466       COW_REFCNT = 1
467     SV = PV(0x260ce30) at 0x2620b20
468       REFCNT = 1
469       FLAGS = (POK,IsCOW,pPOK)
470       PV = 0x2619bc0 "abc"\0
471       CUR = 3
472       LEN = 16
473       COW_REFCNT = 1
474
475 Note that both scalars share the same PV buffer and have a COW_REFCNT
476 greater than zero.
477
478 This means that XS code which wishes to modify the C<SvPVX()> buffer of an
479 SV should call C<SvPV_force()> or similar first, to ensure a valid (and
480 unshared) buffer, and to call C<SvSETMAGIC()> afterwards. This in fact has
481 always been the case (for example hash keys were already copy-on-write);
482 this change just spreads the COW behaviour to a wider variety of SVs.
483
484 One important difference is that before 5.18.0, shared hash-key scalars
485 used to have the C<SvREADONLY> flag set; this is no longer the case.
486
487 This new behaviour can still be disabled by running F<Configure> with
488 B<-Accflags=-DPERL_NO_COW>.  This option will probably be removed in Perl
489 5.22.
490
491 =item *
492
493 C<PL_sawampersand> is now a constant.  The switch this variable provided
494 (to enable/disable the pre-match copy depending on whether C<$&> had been
495 seen) has been removed and replaced with copy-on-write, eliminating a few
496 bugs.
497
498 The previous behaviour can still be enabled by running F<Configure> with
499 B<-Accflags=-DPERL_SAWAMPERSAND>.
500
501 =item *
502
503 The functions C<my_swap>, C<my_htonl> and C<my_ntohl> have been removed.
504 It is unclear why these functions were ever marked as I<A>, part of the
505 API. XS code can't call them directly, as it can't rely on them being
506 compiled. Unsurprisingly, no code on CPAN references them.
507
508 =item *
509
510 The signature of the C<Perl_re_intuit_start()> regex function has changed;
511 the function pointer C<intuit> in the regex engine plugin structure
512 has also changed accordingly. A new parameter, C<strbeg> has been added;
513 this has the same meaning as the same-named parameter in
514 C<Perl_regexec_flags>. Previously intuit would try to guess the start of
515 the string from the passed SV (if any), and would sometimes get it wrong
516 (e.g. with an overloaded SV).
517
518 =item *
519
520 XS code may use various macros to change the case of a character or code
521 point (for example C<toLOWER_utf8()>).  Only a couple of these were
522 documented until now;
523 and now they should be used in preference to calling the underlying
524 functions.  See L<perlapi/Character case changing>.
525
526 =item *
527
528 The code dealt rather inconsistently with uids and gids. Some
529 places assumed that they could be safely stored in UVs, others
530 in IVs, others in ints. Four new macros are introduced:
531 SvUID(), sv_setuid(), SvGID(), and sv_setgid()
532
533 =back
534
535 =head1 Selected Bug Fixes
536
537 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
538 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
539
540 [ List each fix as a =item entry ]
541
542 =over 4
543
544 =item *
545
546 The OP allocation code now returns correctly aligned memory in all cases
547 for C<struct pmop>. Previously it could return memory only aligned to a
548 4-byte boundary, which is not correct for an ithreads build with 64 bit IVs
549 on some 32 bit platforms. Notably, this caused the build to fail completely
550 on sparc GNU/Linux. [RT #118055]
551
552 =item *
553
554 The debugger's C<man> command been fixed. It was broken in the v5.18.0
555 release. The C<man> command is aliased to the names C<doc> and C<perldoc> -
556 all now work again.
557
558 =item *
559
560 C<@_> is now correctly visible in the debugger, fixing a regression
561 introduced in v5.18.0's debugger. [RT #118169]
562
563 =item *
564
565 Evaluating large hashes in scalar context is now much faster, as the number
566 of used chains in the hash is now cached for larger hashes. Smaller hashes
567 continue not to store it and calculate it when needed, as this saves one IV.
568 That would be 1 IV overhead for every object built from a hash. [RT #114576]
569
570 =item *
571
572 Fixed a small number of regexp constructions that could either fail to
573 match or crash perl when the string being matched against was
574 allocated above the 2GB line on 32-bit systems. [RT #118175]
575
576 =item *
577
578 Perl v5.16 inadvertently introduced a bug whereby calls to XSUBs that were
579 not visible at compile time were treated as lvalues and could be assigned
580 to, even when the subroutine was not an lvalue sub.  This has been fixed.
581 [RT #117947]
582
583 =item *
584
585 In Perl v5.18.0 dualvars that had an empty string for the string part but a
586 non-zero number for the number part starting being treated as true.  In
587 previous versions they were treated as false, the string representation
588 taking precedeence.  The old behaviour has been restored. [RT #118159]
589
590 =item *
591
592 Since Perl v5.12, inlining of constants that override built-in keywords of
593 the same name had countermanded C<use subs>, causing subsequent mentions of
594 the constant to use the built-in keyword instead.  This has been fixed.
595
596 =item *
597
598 Lexical constants (C<my sub a() { 42 }>) no longer crash when inlined.
599
600 =item *
601
602 Parameter prototypes attached to lexical subroutines are now respected when
603 compiling sub calls without parentheses.  Previously, the prototypes were
604 honoured only for calls I<with> parentheses. [RT #116735]
605
606 =item *
607
608 Syntax errors in lexical subroutines in combination with calls to the same
609 subroutines no longer cause crashes at compile time.
610
611 =item *
612
613 The warning produced by C<-l $handle> now applies to IO refs and globs, not
614 just to glob refs.  That warning is also now UTF8-clean. [RT #117595]
615
616 =item *
617
618 Various memory leaks involving the parsing of the C<(?[...])> regular
619 expression construct have been fixed.
620
621 =item *
622
623 C<(?[...])> now allows interpolation of precompiled patterns consisting of
624 C<(?[...])> with bracketed character classes inside (C<$pat =
625 S<qr/(?[ [a] ])/;> S</(?[ $pat ])/>>).  Formerly, the brackets would
626 confuse the regular expression parser.
627
628 =item *
629
630 The "Quantifier unexpected on zero-length expression" warning message could
631 appear twice starting in Perl v5.10 for a regular expression also
632 containing alternations (e.g., "a|b") triggering the trie optimisation.
633
634 =item *
635
636 C<delete local $ENV{nonexistent_env_var}> no longer leaks memory.
637
638 =item *
639
640 C<sort> and C<require> followed by a keyword prefixed with C<CORE::> now
641 treat it as a keyword, and not as a subroutine or module name. [RT #24482]
642
643 =item *
644
645 Through certain conundrums, it is possible to cause the current package to
646 be freed.  Certain operators (C<bless>, C<reset>, C<open>, C<eval>) could
647 not cope and would crash.  They have been made more resilient. [RT #117941]
648
649 =item *
650
651 Aliasing filehandles through glob-to-glob assignment would not update
652 internal method caches properly if a package of the same name as the
653 filehandle existed, resulting in filehandle method calls going to the
654 package instead.  This has been fixed.
655
656 =item *
657
658 C<./Configure -de -Dusevendorprefix> didn't default [RT #64126]
659
660 =item *
661
662 The C<Statement unlikely to be reached> warning was listed in
663 L<perldiag> as an C<exec>-category warning, but was enabled and disabled
664 by the C<syntax> category.  On the other hand, the C<exec> category
665 controlled its fatal-ness.  It is now entirely handled by the C<exec>
666 category.
667
668 =item *
669
670 Perl v5.18 inadvertently introduced a bug whereby interpolating mixed up-
671 and down-graded UTF-8 strings in a regex could result in malformed UTF-8
672 in the pattern: specifically if a downgraded character in the range
673 C<\x80..\xff> followed a UTF-8 string, e.g.
674
675     utf8::upgrade(  my $u = "\x{e5}");
676     utf8::downgrade(my $d = "\x{e5}");
677     /$u$d/
678
679 [RT #118297]
680
681 =back
682
683 =head1 Known Problems
684
685 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
686 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
687 platform specific bugs also go here.
688
689 [ List each fix as a =item entry ]
690
691 =over 4
692
693 =item *
694
695 XXX
696
697 =back
698
699 =head1 Obituary
700
701 XXX If any significant core contributor has died, we've added a short obituary
702 here.
703
704 =head1 Acknowledgements
705
706 XXX Generate this with:
707
708   perl Porting/acknowledgements.pl v5.19.1..HEAD
709
710 =head1 Reporting Bugs
711
712 If you find what you think is a bug, you might check the articles recently
713 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
714 http://rt.perl.org/perlbug/ .  There may also be information at
715 http://www.perl.org/ , the Perl Home Page.
716
717 If you believe you have an unreported bug, please run the L<perlbug> program
718 included with your release.  Be sure to trim your bug down to a tiny but
719 sufficient test case.  Your bug report, along with the output of C<perl -V>,
720 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
721
722 If the bug you are reporting has security implications, which make it
723 inappropriate to send to a publicly archived mailing list, then please send it
724 to perl5-security-report@perl.org.  This points to a closed subscription
725 unarchived mailing list, which includes all the core committers, who will be
726 able to help assess the impact of issues, figure out a resolution, and help
727 co-ordinate the release of patches to mitigate or fix the problem across all
728 platforms on which Perl is supported.  Please only use this address for
729 security issues in the Perl core, not for modules independently distributed on
730 CPAN.
731
732 =head1 SEE ALSO
733
734 The F<Changes> file for an explanation of how to view exhaustive details on
735 what changed.
736
737 The F<INSTALL> file for how to build Perl.
738
739 The F<README> file for general stuff.
740
741 The F<Artistic> and F<Copying> files for copyright information.
742
743 =cut