This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Change syntax of script runs
[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.9
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.27.8 release and the 5.27.9
13 release.
14
15 If you are upgrading from an earlier release such as 5.27.7, first read
16 L<perl5278delta>, which describes differences between 5.27.7 and 5.27.8.
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 New read-only predefined variable C<${^SAFE_LOCALES}>
31
32 This variable is 1 if the Perl interpreter is operating in an
33 environment where it is safe to use and change locales (see
34 L<perllocale>.)  This variable is true when the perl is
35 unthreaded, or compiled in a platform that supports thread-safe locale
36 operation (see next item).
37
38 =head2 Locales are now thread-safe on systems that support them
39
40 These systems include Windows starting with Visual Studio 2005, and in
41 POSIX 2008 systems.
42
43 The implication is that you are now free to use locales and changes them
44 in a threaded environment.  Your changes affect only your thread.
45 See L<perllocale/Multi-threaded operation>
46
47 =head2 Script runs now are specified with a different syntax
48
49 This isn't really an enhancement, but is being put in this category
50 because it changes an enhancement from 5.27.8, and there is a new
51 abbreviated form for it.  The syntax is now either of:
52
53  (*script_run:...)
54  (*sr:...)
55
56 Previously a C<"+"> was used instead of the C<"*">.
57
58 =head1 Security
59
60 XXX Any security-related notices go here.  In particular, any security
61 vulnerabilities closed should be noted here rather than in the
62 L</Selected Bug Fixes> section.
63
64 [ List each security issue as a =head2 entry ]
65
66 =head1 Incompatible Changes
67
68 XXX For a release on a stable branch, this section aspires to be:
69
70     There are no changes intentionally incompatible with 5.XXX.XXX
71     If any exist, they are bugs, and we request that you submit a
72     report.  See L</Reporting Bugs> below.
73
74 [ List each incompatible change as a =head2 entry ]
75
76 =head1 Deprecations
77
78 XXX Any deprecated features, syntax, modules etc. should be listed here.
79
80 =head2 Module removals
81
82 XXX Remove this section if not applicable.
83
84 The following modules will be removed from the core distribution in a
85 future release, and will at that time need to be installed from CPAN.
86 Distributions on CPAN which require these modules will need to list them as
87 prerequisites.
88
89 The core versions of these modules will now issue C<"deprecated">-category
90 warnings to alert you to this fact.  To silence these deprecation warnings,
91 install the modules in question from CPAN.
92
93 Note that these are (with rare exceptions) fine modules that you are encouraged
94 to continue to use.  Their disinclusion from core primarily hinges on their
95 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
96 not usually on concerns over their design.
97
98 =over
99
100 =item XXX
101
102 XXX Note that deprecated modules should be listed here even if they are listed
103 as an updated module in the L</Modules and Pragmata> section.
104
105 =back
106
107 [ List each other deprecation as a =head2 entry ]
108
109 =head1 Performance Enhancements
110
111 XXX Changes which enhance performance without changing behaviour go here.
112 There may well be none in a stable release.
113
114 [ List each enhancement as an =item entry ]
115
116 =over 4
117
118 =item *
119
120 XXX
121
122 =back
123
124 =head1 Modules and Pragmata
125
126 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
127 go here.  If Module::CoreList is updated, generate an initial draft of the
128 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
129 for important changes should then be added by hand.  In an ideal world,
130 dual-life modules would have a F<Changes> file that could be cribbed.
131
132 The list of new and updated modules is modified automatically as part of
133 preparing a Perl release, so the only reason to manually add entries here is if
134 you're summarising the important changes in the module update. (Also, if the
135 manually-added details don't match the automatically-generated ones, the
136 release manager will have to investigate the situation carefully.)
137
138 [ Within each section, list entries as an =item entry ]
139
140 =head2 New Modules and Pragmata
141
142 =over 4
143
144 =item *
145
146 XXX Remove this section if not applicable.
147
148 =back
149
150 =head2 Updated Modules and Pragmata
151
152 =over 4
153
154 =item *
155
156 L<XXX> has been upgraded from version A.xx to B.yy.
157
158 If there was something important to note about this change, include that here.
159
160 =back
161
162 =head2 Removed Modules and Pragmata
163
164 =over 4
165
166 =item *
167
168 XXX
169
170 =back
171
172 =head1 Documentation
173
174 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
175 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
176
177 =head2 New Documentation
178
179 XXX Changes which create B<new> files in F<pod/> go here.
180
181 =head3 L<XXX>
182
183 XXX Description of the purpose of the new file here
184
185 =head2 Changes to Existing Documentation
186
187 We have attempted to update the documentation to reflect the changes
188 listed in this document.  If you find any we have missed, send email
189 to L<perlbug@perl.org|mailto:perlbug@perl.org>.
190
191 XXX Changes which significantly change existing files in F<pod/> go here.
192 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
193 section.
194
195 Additionally, the following selected changes have been made:
196
197 =head3 L<XXX>
198
199 =over 4
200
201 =item *
202
203 XXX Description of the change here
204
205 =back
206
207 =head1 Diagnostics
208
209 The following additions or changes have been made to diagnostic output,
210 including warnings and fatal error messages.  For the complete list of
211 diagnostic messages, see L<perldiag>.
212
213 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
214 include any changes in L<perldiag> that reconcile it to the C<C> code.
215
216 =head2 New Diagnostics
217
218 XXX Newly added diagnostic messages go under here, separated into New Errors
219 and New Warnings
220
221 =head3 New Errors
222
223 =over 4
224
225 =item *
226
227 XXX L<message|perldiag/"message">
228
229 =back
230
231 =head3 New Warnings
232
233 =over 4
234
235 =item *
236
237 L<Locale '%s' contains (at least) the following characters which have
238 non-standard meanings: %s  The Perl program will use the standard
239 meanings|perldiag/"Locale '%s' contains (at least) the following
240 characters which have non-standard meanings: %s  The Perl program will
241 use the standard meanings">.
242
243 =back
244
245 =head2 Changes to Existing Diagnostics
246
247 XXX Changes (i.e. rewording) of diagnostic messages go here
248
249 =over 4
250
251 =item *
252
253 XXX Describe change here
254
255 =back
256
257 =head1 Utility Changes
258
259 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
260 Most of these are built within the directory F<utils>.
261
262 [ List utility changes as a =head2 entry for each utility and =item
263 entries for each change
264 Use L<XXX> with program names to get proper documentation linking. ]
265
266 =head2 L<XXX>
267
268 =over 4
269
270 =item *
271
272 XXX
273
274 =back
275
276 =head1 Configuration and Compilation
277
278 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
279 go here.  Any other changes to the Perl build process should be listed here.
280 However, any platform-specific changes should be listed in the
281 L</Platform Support> section, instead.
282
283 [ List changes as an =item entry ].
284
285 =over 4
286
287 =item *
288
289 XXX
290
291 =back
292
293 =head1 Testing
294
295 XXX Any significant changes to the testing of a freshly built perl should be
296 listed here.  Changes which create B<new> files in F<t/> go here as do any
297 large changes to the testing harness (e.g. when parallel testing was added).
298 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
299 that they represent may be covered elsewhere.
300
301 XXX If there were no significant test changes, say this:
302
303 Tests were added and changed to reflect the other additions and changes
304 in this release.
305
306 XXX If instead there were significant changes, say this:
307
308 Tests were added and changed to reflect the other additions and
309 changes in this release.  Furthermore, these significant changes were
310 made:
311
312 [ List each test improvement as an =item entry ]
313
314 =over 4
315
316 =item *
317
318 F<harness> no longer waits for 30 seconds when running
319 F<t/io/openpid.t>.  [perl #121028][perl #132867]
320
321 =back
322
323 =head1 Platform Support
324
325 XXX Any changes to platform support should be listed in the sections below.
326
327 [ Within the sections, list each platform as an =item entry with specific
328 changes as paragraphs below it. ]
329
330 =head2 New Platforms
331
332 XXX List any platforms that this version of perl compiles on, that previous
333 versions did not.  These will either be enabled by new files in the F<hints/>
334 directories, or new subdirectories and F<README> files at the top level of the
335 source tree.
336
337 =over 4
338
339 =item XXX-some-platform
340
341 XXX
342
343 =item VMS
344
345 CRTL features can now be set by embedders before invoking Perl by using the
346 C<decc$feature_set> and C<decc$feature_set_value> functions.  Previously any attempt
347 to set features after image initialization were ignored.
348
349 =back
350
351 =head2 Discontinued Platforms
352
353 XXX List any platforms that this version of perl no longer compiles on.
354
355 =over 4
356
357 =item XXX-some-platform
358
359 XXX
360
361 =back
362
363 =head2 Platform-Specific Notes
364
365 XXX List any changes for specific platforms.  This could include configuration
366 and compilation changes or changes in portability/compatibility.  However,
367 changes within modules for platforms should generally be listed in the
368 L</Modules and Pragmata> section.
369
370 =over 4
371
372 =item XXX-some-platform
373
374 XXX
375
376 =back
377
378 =head1 Internal Changes
379
380 XXX Changes which affect the interface available to C<XS> code go here.  Other
381 significant internal changes for future core maintainers should be noted as
382 well.
383
384 [ List each change as an =item entry ]
385
386 =over 4
387
388 =item *
389
390 A new compiler C<#define>, C<dTHX_DEBUGGING>. has been added.  This is
391 useful for XS or C code that only need the thread context because their
392 debugging statements that get compiled only under C<-DDEBUGGING> need
393 one.
394
395 =item *
396
397 A new API function L<perlapi/Perl_setlocale> has been added.
398
399 =item *
400
401 L<perlapi/sync_locale> has been revised to return a boolean as to
402 whether the system was using the global locale or not.
403
404 =item *
405
406 A new kind of magic scalar, called a "nonelem" scalar, has been introduced.
407 It is stored in an array to denote a nonexistent element, whenever such an
408 element is accessed in a potential lvalue context.  It replaces the
409 existing "defelem" (deferred element) magic wherever this is possible,
410 being significantly more efficient.  This means that
411 C<some_sub($sparse_array[$nonelem])> no longer has to create a new magic
412 defelem scalar each time, as long as the element is within the array.
413
414 It partially fixes the rare bug of deferred elements getting out of synch
415 with their arrays when the array is shifted or unshifted.  [perl #132729]
416
417 =back
418
419 =head1 Selected Bug Fixes
420
421 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
422 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
423
424 [ List each fix as an =item entry ]
425
426 =over 4
427
428 =item *
429
430 Failures while compiling code within other constructs, such as with
431 string interpolation and the right part of C<s///e> now cause
432 compilation to abort earlier.
433
434 Previously compilation could continue in order to report other errors,
435 but the failed sub-parse could leave partly parsed constructs on the
436 parser shift-reduce stack, confusing the parser, leading to perl
437 crashes. [perl #125351]
438
439 =item *
440
441 On threaded perls where the decimal point (radix) character is not a
442 dot, it has been possible for a race to occur between threads when one
443 needs to use the real radix character.  This has now been fixed by use
444 of a mutex on systems without thread-safe locales, and the problem just
445 doesn't come up on those with thread-safe locales.
446
447 =back
448
449 =head1 Known Problems
450
451 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
452 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
453 platform specific bugs also go here.
454
455 [ List each fix as an =item entry ]
456
457 =over 4
458
459 =item *
460
461 XXX
462
463 =back
464
465 =head1 Errata From Previous Releases
466
467 =over 4
468
469 =item *
470
471 XXX Add anything here that we forgot to add, or were mistaken about, in
472 the perldelta of a previous release.
473
474 =back
475
476 =head1 Obituary
477
478 XXX If any significant core contributor or member of the CPAN community has
479 died, add a short obituary here.
480
481 =head1 Acknowledgements
482
483 XXX Generate this with:
484
485   perl Porting/acknowledgements.pl v5.27.8..HEAD
486
487 =head1 Reporting Bugs
488
489 If you find what you think is a bug, you might check the perl bug database
490 at L<https://rt.perl.org/> .  There may also be information at
491 L<http://www.perl.org/> , the Perl Home Page.
492
493 If you believe you have an unreported bug, please run the L<perlbug> program
494 included with your release.  Be sure to trim your bug down to a tiny but
495 sufficient test case.  Your bug report, along with the output of C<perl -V>,
496 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
497
498 If the bug you are reporting has security implications which make it
499 inappropriate to send to a publicly archived mailing list, then see
500 L<perlsec/SECURITY VULNERABILITY CONTACT INFORMATION>
501 for details of how to report the issue.
502
503 =head1 Give Thanks
504
505 If you wish to thank the Perl 5 Porters for the work we had done in Perl 5,
506 you can do so by running the C<perlthanks> program:
507
508     perlthanks
509
510 This will send an email to the Perl 5 Porters list with your show of thanks.
511
512 =head1 SEE ALSO
513
514 The F<Changes> file for an explanation of how to view exhaustive details on
515 what changed.
516
517 The F<INSTALL> file for how to build Perl.
518
519 The F<README> file for general stuff.
520
521 The F<Artistic> and F<Copying> files for copyright information.
522
523 =cut