[MERGE] update PERL_OP_PARENT implementation
[perl.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.21.11
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.21.10 release and the 5.21.11
13 release.
14
15 If you are upgrading from an earlier release such as 5.21.9, first read
16 L<perl52110delta>, which describes differences between 5.21.9 and 5.21.10.
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 =head1 Security
31
32 XXX Any security-related notices go here.  In particular, any security
33 vulnerabilities closed should be noted here rather than in the
34 L</Selected Bug Fixes> section.
35
36 [ List each security issue as a =head2 entry ]
37
38 =head1 Incompatible Changes
39
40 XXX For a release on a stable branch, this section aspires to be:
41
42     There are no changes intentionally incompatible with 5.XXX.XXX
43     If any exist, they are bugs, and we request that you submit a
44     report.  See L</Reporting Bugs> below.
45
46 [ List each incompatible change as a =head2 entry ]
47
48 =head1 Deprecations
49
50 XXX Any deprecated features, syntax, modules etc. should be listed here.
51
52 =head2 Making all warnings fatal is discouraged
53
54 The documentation for L<fatal warnings|warnings/Fatal Warnings> notes
55 that C<< use warnings FATAL => 'all' >> is discouraged
56 and provides stronger language about the risks of fatal warnings
57 in general.
58
59 =head2 Module removals
60
61 XXX Remove this section if inapplicable.
62
63 The following modules will be removed from the core distribution in a
64 future release, and will at that time need to be installed from CPAN.
65 Distributions on CPAN which require these modules will need to list them as
66 prerequisites.
67
68 The core versions of these modules will now issue C<"deprecated">-category
69 warnings to alert you to this fact.  To silence these deprecation warnings,
70 install the modules in question from CPAN.
71
72 Note that these are (with rare exceptions) fine modules that you are encouraged
73 to continue to use.  Their disinclusion from core primarily hinges on their
74 necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
75 not usually on concerns over their design.
76
77 =over
78
79 =item XXX
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 =back
85
86 [ List each other deprecation as a =head2 entry ]
87
88 =head1 Performance Enhancements
89
90 XXX Changes which enhance performance without changing behaviour go here.
91 There may well be none in a stable release.
92
93 [ List each enhancement as a =item entry ]
94
95 =over 4
96
97 =item *
98
99 XXX
100
101 =back
102
103 =head1 Modules and Pragmata
104
105 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
106 go here.  If Module::CoreList is updated, generate an initial draft of the
107 following sections using F<Porting/corelist-perldelta.pl>.  A paragraph summary
108 for important changes should then be added by hand.  In an ideal world,
109 dual-life modules would have a F<Changes> file that could be cribbed.
110
111 [ Within each section, list entries as a =item entry ]
112
113 =head2 New Modules and Pragmata
114
115 =over 4
116
117 =item *
118
119 XXX
120
121 =back
122
123 =head2 Updated Modules and Pragmata
124
125 =over 4
126
127 =item *
128
129 L<attributes> has been upgraded from version 0.26 to 0.27.
130
131 =item *
132
133 L<Cwd> has been upgraded from version 3.55 to 3.56.
134
135 =item *
136
137 L<ExtUtils::Miniperl> has been upgraded from version 1.04 to 1.05.
138
139 =item *
140
141 L<IO::Socket::IP> has been upgraded from version 0.36 to 0.37.
142
143 =item *
144
145 L<Module::CoreList> has been upgraded from version 5.20150320 to 5.20150420.
146
147 Updated to cover the latest releases of Perl.
148
149 =item *
150
151 L<perl5db.pl> has been upgraded from 1.48 to 1.49.
152
153 The debugger would cause an assertion failure.  [perl #124127]
154
155 =item *
156
157 L<PerlIO::mmap> has been upgraded from version 0.013 to 0.014.
158
159 =item *
160
161 L<utf8> has been upgraded from version 1.15 to 1.16.
162
163 =item *
164
165 L<warnings> has been upgraded from version 1.31 to 1.32.
166
167 =item *
168
169 L<ExtUtils::ParseXS> has been upgraded from version 3.27 (with certain
170 components which were at version 3.25) to version 3.28.
171
172 =back
173
174 =head2 Removed Modules and Pragmata
175
176 =over 4
177
178 =item *
179
180 XXX
181
182 =back
183
184 =head1 Documentation
185
186 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
187 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
188
189 =head2 New Documentation
190
191 XXX Changes which create B<new> files in F<pod/> go here.
192
193 =head3 L<XXX>
194
195 XXX Description of the purpose of the new file here
196
197 =head2 Changes to Existing Documentation
198
199 XXX Changes which significantly change existing files in F<pod/> go here.
200 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
201 section.
202
203 =head3 L<XXX>
204
205 =over 4
206
207 =item *
208
209 XXX Description of the change here
210
211 =back
212
213 =head1 Diagnostics
214
215 The following additions or changes have been made to diagnostic output,
216 including warnings and fatal error messages.  For the complete list of
217 diagnostic messages, see L<perldiag>.
218
219 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
220 include any changes in L<perldiag> that reconcile it to the C<C> code.
221
222 =head2 New Diagnostics
223
224 XXX Newly added diagnostic messages go under here, separated into New Errors
225 and New Warnings
226
227 =head3 New Errors
228
229 =over 4
230
231 =item *
232
233 XXX L<message|perldiag/"message">
234
235 =back
236
237 =head3 New Warnings
238
239 =over 4
240
241 =item *
242
243 XXX L<message|perldiag/"message">
244
245 =back
246
247 =head2 Changes to Existing Diagnostics
248
249 XXX Changes (i.e. rewording) of diagnostic messages go here
250
251 =over 4
252
253 =item *
254
255 XXX Describe change here
256
257 =back
258
259 =head1 Utility Changes
260
261 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
262 Most of these are built within the directory F<utils>.
263
264 [ List utility changes as a =head2 entry for each utility and =item
265 entries for each change
266 Use L<XXX> with program names to get proper documentation linking. ]
267
268 =head2 L<XXX>
269
270 =over 4
271
272 =item *
273
274 XXX
275
276 =back
277
278 =head1 Configuration and Compilation
279
280 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
281 go here.  Any other changes to the Perl build process should be listed here.
282 However, any platform-specific changes should be listed in the
283 L</Platform Support> section, instead.
284
285 [ List changes as a =item entry ].
286
287 =over 4
288
289 =item *
290
291 XXX
292
293 =back
294
295 =head1 Testing
296
297 XXX Any significant changes to the testing of a freshly built perl should be
298 listed here.  Changes which create B<new> files in F<t/> go here as do any
299 large changes to the testing harness (e.g. when parallel testing was added).
300 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
301 that they represent may be covered elsewhere.
302
303 [ List each test improvement as a =item entry ]
304
305 =over 4
306
307 =item *
308
309 XXX
310
311 =back
312
313 =head1 Platform Support
314
315 XXX Any changes to platform support should be listed in the sections below.
316
317 [ Within the sections, list each platform as a =item entry with specific
318 changes as paragraphs below it. ]
319
320 =head2 New Platforms
321
322 XXX List any platforms that this version of perl compiles on, that previous
323 versions did not.  These will either be enabled by new files in the F<hints/>
324 directories, or new subdirectories and F<README> files at the top level of the
325 source tree.
326
327 =over 4
328
329 =item XXX-some-platform
330
331 XXX
332
333 =back
334
335 =head2 Discontinued Platforms
336
337 XXX List any platforms that this version of perl no longer compiles on.
338
339 =over 4
340
341 =item XXX-some-platform
342
343 XXX
344
345 =back
346
347 =head2 Platform-Specific Notes
348
349 XXX List any changes for specific platforms.  This could include configuration
350 and compilation changes or changes in portability/compatibility.  However,
351 changes within modules for platforms should generally be listed in the
352 L</Modules and Pragmata> section.
353
354 =over 4
355
356 =item Win32
357
358 F<miniperl.exe> is now built with C<-fno-strict-aliasing>, allowing
359 64-bit builds to complete on GCC 4.8. [perl #123976]
360
361 C<test-prep> again depends on C<test-prep-gcc> for GCC builds. [perl
362 #124221]
363
364 =back
365
366 =head1 Internal Changes
367
368 =over 4
369
370 =item *
371
372 5.21.2 introduced a new build option, C<-DPERL_OP_PARENT>, which causes
373 the last C<op_sibling> pointer to refer back to the parent rather than
374 being C<NULL>, and where instead a new flag indicates the end of the
375 chain. In this release, the new implementation has been revised; in
376 particular:
377
378 =over 4
379
380 =item *
381
382 On C<PERL_OP_PARENT> builds, the C<op_sibling> field has been renamed
383 C<op_sibparent> to reflect its new dual purpose. Since the intention is that
384 this field should primarily be accessed via macros, this change should be
385 transparent for code written to work under C<PERL_OP_PARENT>.
386
387 =item *
388
389 The newly-introduced C<op_lastsib> flag bit has been renamed C<op_moresib>
390 and its logic inverted; i.e. it is initialised to zero in a new op, and is
391 changed to 1 when an op gains a sibling.
392
393 =item *
394
395 The function C<Perl_op_parent> is now only available on C<PERL_OP_PARENT>
396 builds. Using it on a plain build will be a compile-timer error.
397
398 =item *
399
400 Three new macros, C<OpMORESIB_set>, C<OpLASTSIB_set>, C<OpMAYBESIB_set>
401 have been added, which are intended to be be a low-level portable way to
402 set C<op_sibling> / C<op_sibparent> while also updating C<op_moresib>.
403 The first sets the sibling pointer to a new sibling, the second makes the
404 op the last sibling, and the third conditionally does the first or second
405 action. The C<op_sibling_splice()> function is retained as a higher-level
406 interface that can also maintain consistency in the parent at the same time
407 (e.g. by updating C<op_first> and C<op_last> where appropriate).
408
409 =item *
410
411 The macro C<OpSIBLING_set>, added in 5.21.2, has been removed. It didn't
412 manipulate C<op_moresib> and has been superseded by C<OpMORESIB_set> et
413 al.
414
415 =item *
416
417 The C<op_sibling_splice> function now accepts a null C<parent> argument
418 where the splicing doesn't affect the first or last ops in the sibling
419 chain, and thus where the parent doesn't need to be updated accordingly.
420
421 =back
422
423
424 =back
425
426 =head1 Selected Bug Fixes
427
428 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
429 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
430
431 [ List each fix as a =item entry ]
432
433 =over 4
434
435 =item *
436
437 C<pack("D", $x)> and C<pack("F", $x)> now zero the padding on x86 long
438 double builds.  GCC 4.8 and later, under some build options, would
439 either overwrite the zero-initialized padding, or bypass the
440 initialized buffer entirely.  This caused F<op/pack.t> to fail.  [perl
441 #123971]
442
443 =item *
444
445 Extending an array cloned from a parent thread could result in
446 "Modification of a read-only value attempted" errors when attempting
447 to modify the new elements. [perl #124127]
448
449 =back
450
451 =head1 Known Problems
452
453 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
454 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
455 platform specific bugs also go here.
456
457 [ List each fix as a =item entry ]
458
459 =over 4
460
461 =item *
462
463 XXX
464
465 =back
466
467 =head1 Errata From Previous Releases
468
469 =over 4
470
471 =item *
472
473 XXX Add anything here that we forgot to add, or were mistaken about, in
474 the perldelta of a previous release.
475
476 =back
477
478 =head1 Obituary
479
480 XXX If any significant core contributor has died, we've added a short obituary
481 here.
482
483 =head1 Acknowledgements
484
485 XXX Generate this with:
486
487   perl Porting/acknowledgements.pl v5.21.10..HEAD
488
489 =head1 Reporting Bugs
490
491 If you find what you think is a bug, you might check the articles recently
492 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
493 https://rt.perl.org/ .  There may also be information at
494 http://www.perl.org/ , the Perl Home Page.
495
496 If you believe you have an unreported bug, please run the L<perlbug> program
497 included with your release.  Be sure to trim your bug down to a tiny but
498 sufficient test case.  Your bug report, along with the output of C<perl -V>,
499 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
500
501 If the bug you are reporting has security implications, which make it
502 inappropriate to send to a publicly archived mailing list, then please send it
503 to perl5-security-report@perl.org.  This points to a closed subscription
504 unarchived mailing list, which includes all the core committers, who will be
505 able to help assess the impact of issues, figure out a resolution, and help
506 co-ordinate the release of patches to mitigate or fix the problem across all
507 platforms on which Perl is supported.  Please only use this address for
508 security issues in the Perl core, not for modules independently distributed on
509 CPAN.
510
511 =head1 SEE ALSO
512
513 The F<Changes> file for an explanation of how to view exhaustive details on
514 what changed.
515
516 The F<INSTALL> file for how to build Perl.
517
518 The F<README> file for general stuff.
519
520 The F<Artistic> and F<Copying> files for copyright information.
521
522 =cut