This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
5cda1847bf941904bbbf34c987084b8106edbdec
[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.27.7
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.27.6 release and the 5.27.7
13 release.
14
15 If you are upgrading from an earlier release such as 5.27.5, first read
16 L<perl5276delta>, which describes differences between 5.27.5 and 5.27.6.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 XXX New core language features go here.  Summarize user-visible core language
25 enhancements.  Particularly prominent performance optimisations could go
26 here, but most should go in the L</Performance Enhancements> section.
27
28 [ List each enhancement as a =head2 entry ]
29
30 =head2  The C<sprintf> C<%j> format size modifier is now available with
31 pre-C99 compilers
32
33 The actual size used depends on the platform, so remains unportable.
34
35 =head1 Security
36
37 XXX Any security-related notices go here.  In particular, any security
38 vulnerabilities closed should be noted here rather than in the
39 L</Selected Bug Fixes> section.
40
41 [ List each security issue as a =head2 entry ]
42
43 =head1 Incompatible Changes
44
45 XXX For a release on a stable branch, this section aspires to be:
46
47     There are no changes intentionally incompatible with 5.XXX.XXX
48     If any exist, they are bugs, and we request that you submit a
49     report.  See L</Reporting Bugs> below.
50
51 [ List each incompatible change as a =head2 entry ]
52
53 =head2 Over-radix digits in floating point literals
54
55 Octal and binary floating point literals used to permit any hexadecimal
56 digit to appear after the radix point.  The digits are now restricted
57 to those appropriate for the radix, as digits before the radix point
58 always were.
59
60 =head1 Deprecations
61
62 XXX Any deprecated features, syntax, modules etc. should be listed here.
63
64 =head2 Assignment to C<$[> will be fatal in Perl 5.30
65
66 Assigning a non-zero value to L<C<$[>|perlvar/$[> has been deprecated
67 since Perl 5.12, but was never given a deadline for removal.  This has
68 now been scheduled for Perl 5.30.
69
70 =head2 hostname() won't accept arguments in Perl 5.32
71
72 Passing arguments to C<Sys::Hostname::hostname()> was already deprecated,
73 but didn't have a removal date.  This has now been scheduled for Perl
74 5.32.  [perl #124349]
75
76 =head2 Module removals
77
78 XXX Remove this section if not applicable.
79
80 The following modules will be removed from the core distribution in a
81 future release, and will at that time need to be installed from CPAN.
82 Distributions on CPAN which require these modules will need to list them as
83 prerequisites.
84
85 The core versions of these modules will now issue C<"deprecated">-category
86 warnings to alert you to this fact.  To silence these deprecation warnings,
87 install the modules in question from CPAN.
88
89 Note that these are (with rare exceptions) fine modules that you are encouraged
90 to continue to use.  Their disinclusion from core primarily hinges on their
91 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
92 not usually on concerns over their design.
93
94 =over
95
96 =item L<Locale::Codes> and its associated Country, Currency and Language modules
97
98 XXX Note that deprecated modules should be listed here even if they are listed
99 as an updated module in the L</Modules and Pragmata> section.
100
101 =back
102
103 [ List each other deprecation as a =head2 entry ]
104
105 =head1 Performance Enhancements
106
107 XXX Changes which enhance performance without changing behaviour go here.
108 There may well be none in a stable release.
109
110 [ List each enhancement as an =item entry ]
111
112 =over 4
113
114 =item *
115
116 XXX
117
118 =back
119
120 =head1 Modules and Pragmata
121
122 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
123 go here.  If Module::CoreList is updated, generate an initial draft of the
124 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
125 for important changes should then be added by hand.  In an ideal world,
126 dual-life modules would have a F<Changes> file that could be cribbed.
127
128 The list of new and updated modules is modified automatically as part of
129 preparing a Perl release, so the only reason to manually add entries here is if
130 you're summarising the important changes in the module update. (Also, if the
131 manually-added details don't match the automatically-generated ones, the
132 release manager will have to investigate the situation carefully.)
133
134 [ Within each section, list entries as an =item entry ]
135
136 =head2 New Modules and Pragmata
137
138 =over 4
139
140 =item *
141
142 XXX Remove this section if not applicable.
143
144 =back
145
146 =head2 Updated Modules and Pragmata
147
148 =over 4
149
150 =item *
151
152 L<Locale::Codes> has been upgraded from version 3.54 to 3.55
153
154 B<NOTE>: L<Locale::Codes> is deprecated in core and will be removed
155 from Perl 5.30.
156
157 =item *
158
159 L<Data::Dumper> has been upgraded from version 2.167_02 to 2.169.
160 Quoting of glob names now obeys the Useqq option [perl #119831].
161 Attempts to set an option to C<undef> through a combined getter/setter
162 method are no longer mistaken for getter calls [perl #113090].
163
164 =back
165
166 =head2 Removed Modules and Pragmata
167
168 =over 4
169
170 =item *
171
172 XXX
173
174 =back
175
176 =head1 Documentation
177
178 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
179 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
180
181 =head2 New Documentation
182
183 XXX Changes which create B<new> files in F<pod/> go here.
184
185 =head3 L<XXX>
186
187 XXX Description of the purpose of the new file here
188
189 =head2 Changes to Existing Documentation
190
191 We have attempted to update the documentation to reflect the changes
192 listed in this document.  If you find any we have missed, send email
193 to L<perlbug@perl.org|mailto:perlbug@perl.org>.
194
195 XXX Changes which significantly change existing files in F<pod/> go here.
196 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
197 section.
198
199 Additionally, the following selected changes have been made:
200
201 =head3 L<perlapi>
202
203 The API functions C<perl_parse()>, C<perl_run()>, and C<perl_destruct()>
204 are now documented comprehensively, where previously the only
205 documentation was a reference to the L<perlembed> tutorial.
206
207 The documentation of C<newGIVENOP()> has been belatedly updated to
208 account for the removal of lexical C<$_>.
209
210 The API functions C<newCONSTSUB()> and C<newCONSTSUB_flags()> are
211 documented much more comprehensively than before.
212
213 =head3 L<perlop>
214
215 The general explanation of operator precedence and associativity has
216 been corrected and clarified.  [perl #127391]
217
218 The documentation for the C<\> referencing operator now explains the
219 unusual context that it supplies to its operand.  [perl #131061]
220
221 =head3 L<perlsyn>
222
223 The means to disambiguate between code blocks and hash constructors,
224 already documented in L<perlref>, are now documented in L<perlsyn> too.
225 [perl #130958]
226
227 =head3 L<perlfunc>
228
229 The documentation for the C<exists> operator no longer says that
230 autovivification behaviour "may be fixed in a future release".
231 We've determined that we're not going to change the default behaviour.
232 [perl #127712]
233
234 A couple of small details in the documentation for the C<bless> operator
235 have been clarified.  [perl #124428]
236
237 The description of C<@INC> hooks in the documentation for C<require>
238 has been corrected to say that filter subroutines receive a useless
239 first argument.  [perl #115754]
240
241 The documentation of C<use> now explains what syntactically qualifies
242 as a version number for its module version checking feature.
243
244 =head3 L<perluniprops>
245
246 For each binary table or property, the documentation now includes which
247 characters in the range C<\x00-\xFF> it matches, as well as a list of
248 the first few ranges of code points matched above that.
249
250 =head3 L<perlsec>
251
252 The documentation about set-id scripts has been updated and revised.
253 [perl #74142]
254
255 A section about using C<sudo> to run Perl scripts has been added.
256
257 =head3 L<perlembed>
258
259 The examples in L<perlembed> have been made more portable in the way
260 they exit, and the example that gets an exit code from the embedded Perl
261 interpreter now gets it from the right place.  The examples that pass
262 a constructed argv to Perl now show the mandatory null C<argv[argc]>.
263
264 =head3 L<perldebguts>
265
266 The description of the conditions under which C<DB::sub()> will be called
267 has been clarified.  [perl #131672]
268
269 =head3 L<perlintern>
270
271 The internal functions C<newXS_len_flags()> and C<newATTRSUB_x()> are
272 now documented.
273
274 =head3 L<perlgit>
275
276 The precise rules for identifying C<smoke-me> branches are now stated.
277
278 =over 4
279
280 =item *
281
282 XXX Description of the change here
283
284 =back
285
286 =head1 Diagnostics
287
288 The following additions or changes have been made to diagnostic output,
289 including warnings and fatal error messages.  For the complete list of
290 diagnostic messages, see L<perldiag>.
291
292 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
293 include any changes in L<perldiag> that reconcile it to the C<C> code.
294
295 =head2 New Diagnostics
296
297 XXX Newly added diagnostic messages go under here, separated into New Errors
298 and New Warnings
299
300 =head3 New Errors
301
302 =over 4
303
304 =item *
305
306 L<Can't "goto" into a "given" block|perldiag/"Can't E<quot>gotoE<quot> into a E<quot>givenE<quot> block">
307
308 (F) A "goto" statement was executed to jump into the middle of a C<given>
309 block.  You can't get there from here.  See L<perlfunc/goto>.
310
311 =back
312
313 =head3 New Warnings
314
315 =over 4
316
317 =item *
318
319 L<Old package separator used in string|perldiag/"Old package separator used in string">
320
321 (W syntax) You used the old package separator, "'", in a variable
322 named inside a double-quoted string; e.g., C<"In $name's house">.  This
323 is equivalent to C<"In $name::s house">.  If you meant the former, put
324 a backslash before the apostrophe (C<"In $name\'s house">).
325
326 =back
327
328 =head2 Changes to Existing Diagnostics
329
330 XXX Changes (i.e. rewording) of diagnostic messages go here
331
332 =over 4
333
334 =item *
335
336 XXX Describe change here
337
338 =item *
339
340 Warnings that a variable or subroutine "masks earlier declaration in same
341 ...", or that an C<our> variable has been redeclared, have been moved to a
342 new warnings category "shadow".  Previously they were in category "misc".
343
344 =item *
345
346 The deprecation warning from C<Sys::Hostname::hostname()> saying that
347 it doesn't accept arguments now states the Perl version in which the
348 warning will be upgraded to an error.  [perl #124349]
349
350 =item *
351
352 The L<perldiag> entry for the error regarding a set-id script has been
353 expanded to make clear that the error is reporting a specific security
354 vulnerability, and to advise how to fix it.
355
356 =back
357
358 =head1 Utility Changes
359
360 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
361 Most of these are built within the directory F<utils>.
362
363 [ List utility changes as a =head2 entry for each utility and =item
364 entries for each change
365 Use L<XXX> with program names to get proper documentation linking. ]
366
367 =head2 L<XXX>
368
369 =over 4
370
371 =item *
372
373 XXX
374
375 =back
376
377 =head1 Configuration and Compilation
378
379 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
380 go here.  Any other changes to the Perl build process should be listed here.
381 However, any platform-specific changes should be listed in the
382 L</Platform Support> section, instead.
383
384 [ List changes as an =item entry ].
385
386 =over 4
387
388 =item *
389
390 XXX
391
392 =back
393
394 =head1 Testing
395
396 XXX Any significant changes to the testing of a freshly built perl should be
397 listed here.  Changes which create B<new> files in F<t/> go here as do any
398 large changes to the testing harness (e.g. when parallel testing was added).
399 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
400 that they represent may be covered elsewhere.
401
402 XXX If there were no significant test changes, say this:
403
404 Tests were added and changed to reflect the other additions and changes
405 in this release.
406
407 XXX If instead there were significant changes, say this:
408
409 Tests were added and changed to reflect the other additions and
410 changes in this release.  Furthermore, these significant changes were
411 made:
412
413 [ List each test improvement as an =item entry ]
414
415 =over 4
416
417 =item *
418
419 XXX
420
421 =back
422
423 =head1 Platform Support
424
425 XXX Any changes to platform support should be listed in the sections below.
426
427 [ Within the sections, list each platform as an =item entry with specific
428 changes as paragraphs below it. ]
429
430 =head2 New Platforms
431
432 XXX List any platforms that this version of perl compiles on, that previous
433 versions did not.  These will either be enabled by new files in the F<hints/>
434 directories, or new subdirectories and F<README> files at the top level of the
435 source tree.
436
437 =over 4
438
439 =item XXX-some-platform
440
441 XXX
442
443 =back
444
445 =head2 Discontinued Platforms
446
447 XXX List any platforms that this version of perl no longer compiles on.
448
449 =over 4
450
451 =item XXX-some-platform
452
453 XXX
454
455 =back
456
457 =head2 Platform-Specific Notes
458
459 XXX List any changes for specific platforms.  This could include configuration
460 and compilation changes or changes in portability/compatibility.  However,
461 changes within modules for platforms should generally be listed in the
462 L</Modules and Pragmata> section.
463
464 =over 4
465
466 =item Windows
467
468 We now set C<$Config{libpth}> correctly for 64-bit builds using Visual C++
469 versions earlier than 14.1.
470
471 =back
472
473 =head1 Internal Changes
474
475 XXX Changes which affect the interface available to C<XS> code go here.  Other
476 significant internal changes for future core maintainers should be noted as
477 well.
478
479 =over 4
480
481 =item *
482
483 XS modules can now automatically get reentrant versions of system
484 functions on threaded perls.
485
486 By saying
487
488  #define PERL_REENTRANT
489
490 near the beginning of an C<XS> file, it will be compiled so that
491 whatever reentrant functions perl knows about on that system will
492 automatically and invisibly be used instead of the plain, non-reentrant
493 versions.  For example, if you write C<getpwnam()> in your code, on a
494 system that has C<pwnam_r()> all calls to the former will be translated
495 invisibly into the latter.  This does not happen except on threaded
496 perls, as they aren't needed otherwise.  Be aware that which functions
497 have reentrant versions varies from system to system.
498
499 =back
500
501 =head1 Selected Bug Fixes
502
503 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
504 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
505
506 [ List each fix as an =item entry ]
507
508 =over 4
509
510 =item *
511
512 XXX
513
514 =item *
515
516 Digits past the radix point in octal and binary floating point literals
517 now have the correct weight on platforms where a floating point
518 significand doesn't fit into an integer type.
519
520 =item *
521
522 C<exit(0)> in a C<UNITCHECK> or C<CHECK> block no longer permits the
523 main program to run, and C<exit(0)> in a C<BEGIN> block no longer permits
524 C<INIT> blocks to run before exiting.  [perl #2754]
525
526 =item *
527
528 The canonical truth value no longer has a spurious special meaning as
529 a callable.  It used to be a magic placeholder for a missing C<import>
530 or C<unimport> method.  It is now treated like any other string C<1>.
531 [perl #126042]
532
533 =item *
534
535 The C<readpipe()> built-in function now checks at compile time that
536 it has only one parameter expression, and puts it in scalar context,
537 thus ensuring that it doesn't corrupt the stack at runtime.  [perl #4574]
538
539 =item *
540
541 C<sort> now performs correct reference counting when aliasing C<$a> and
542 C<$b>, thus avoiding premature destruction and leakage of scalars if they
543 are re-aliased during execution of the sort comparator.  [perl #92264]
544
545 =item *
546
547 Perl's own C<malloc> no longer gets confused by attempts to allocate
548 more than a gigabyte on a 64-bit platform.  [perl #119829]
549
550 =item *
551
552 Stacked file test operators in a sort comparator expression no longer
553 cause a crash.  [perl #129347]
554
555 =item *
556
557 An identity C<tr///> transformation on a reference is no longer mistaken
558 for that reference for the purposes of deciding whether it can be
559 assigned to.  [perl #130578]
560
561 =item *
562
563 Lengthy hexadecimal, octal, or binary floating point literals no
564 longer cause undefined behaviour when parsing digits that are of such
565 low significance that they can't affect the floating point value.
566 [perl #131894]
567
568 =item *
569
570 C<open $$scalarref...> and similar invocations no longer leak the file
571 handle.  [perl #115814]
572
573 =item *
574
575 Some convoluted kinds of regexp no longer cause an arithmetic overflow
576 when compiled.  [perl #131893]
577
578 =item *
579
580 The default typemap, by avoiding C<newGVgen>, now no longer leaks when
581 XSUBs return file handles (C<PerlIO *> or C<FILE *>).  [perl #115814]
582
583 =item *
584
585 Creating a C<BEGIN> block as an XS subroutine with a prototype no longer
586 crashes because of the early freeing of the subroutine.
587
588 =back
589
590 =head1 Known Problems
591
592 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
593 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
594 platform specific bugs also go here.
595
596 [ List each fix as an =item entry ]
597
598 =over 4
599
600 =item *
601
602 XXX
603
604 =back
605
606 =head1 Errata From Previous Releases
607
608 =over 4
609
610 =item *
611
612 XXX Add anything here that we forgot to add, or were mistaken about, in
613 the perldelta of a previous release.
614
615 =back
616
617 =head1 Obituary
618
619 XXX If any significant core contributor or member of the CPAN community has
620 died, add a short obituary here.
621
622 =head1 Acknowledgements
623
624 XXX Generate this with:
625
626   perl Porting/acknowledgements.pl v5.27.6..HEAD
627
628 =head1 Reporting Bugs
629
630 If you find what you think is a bug, you might check the perl bug database
631 at L<https://rt.perl.org/> .  There may also be information at
632 L<http://www.perl.org/> , the Perl Home Page.
633
634 If you believe you have an unreported bug, please run the L<perlbug> program
635 included with your release.  Be sure to trim your bug down to a tiny but
636 sufficient test case.  Your bug report, along with the output of C<perl -V>,
637 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
638
639 If the bug you are reporting has security implications which make it
640 inappropriate to send to a publicly archived mailing list, then see
641 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
642 for details of how to report the issue.
643
644 =head1 Give Thanks
645
646 If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
647 you can do so by running the C<perlthanks> program:
648
649     perlthanks
650
651 This will send an email to the Perl 5 Porters list with your show of thanks.
652
653 =head1 SEE ALSO
654
655 The F<Changes> file for an explanation of how to view exhaustive details on
656 what changed.
657
658 The F<INSTALL> file for how to build Perl.
659
660 The F<README> file for general stuff.
661
662 The F<Artistic> and F<Copying> files for copyright information.
663
664 =cut