This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
480991647f25725e8c3a6095b3087d19035fcd0a
[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.17.7
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.17.6 release and the 5.17.7
13 release.
14
15 If you are upgrading from an earlier release such as 5.17.5, first read
16 L<perl5176delta>, which describes differences between 5.17.5 and 5.17.6.
17
18 =head1 Notice
19
20 XXX Any important notices here
21
22 =head1 Core Enhancements
23
24 =head2 $&, $` and $' are no longer slow
25
26 These three infamous variables have been redeemed and no longer slow down
27 your program when used.  Hence, the /p regular expression flag now does
28 nothing.
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 =head2 readline() with C<$/ = \N> now reads N characters, not N bytes
41
42 Previously, when reading from a stream with I/O layers such as
43 C<encoding>, the readline() function, otherwise known as the C<< <> >>
44 operator, would read I<N> bytes from the top-most layer. [perl #79960]
45
46 Now, I<N> characters are read instead.
47
48 There is no change in behaviour when reading from streams with no
49 extra layers, since bytes map exactly to characters.
50
51 =head2 Lexical subroutine warnings have moved
52
53 The warning about the use of an experimental feature emitted when lexical
54 subroutines (added in 5.17.4) are used now happens when the subroutine
55 itself is declared, not when the "lexical_subs" feature is activated via
56 C<use feature>.
57
58 This stops C<use feature ':all'> from warning, but causes
59 C<my sub foo; my sub bar> to warn twice.
60
61 =head1 Deprecations
62
63 XXX Any deprecated features, syntax, modules etc. should be listed here.  In
64 particular, deprecated modules should be listed here even if they are listed as
65 an updated module in the L</Modules and Pragmata> section.
66
67 [ List each deprecation as a =head2 entry ]
68
69 =head2 Various XS-callable functions are now deprecated
70
71 The following functions will be removed from a future version of Perl,
72 and should not be used.  With participating C compilers (e.g., gcc),
73 compiling any file that uses any of these will generate a warning.
74 These were not intended for public use; there are equivalent, faster,
75 macros for most of them.  See L<perlapi/Character classes>:
76 C<is_uni_ascii>,
77 C<is_uni_ascii_lc>,
78 C<is_uni_blank>,
79 C<is_uni_blank_lc>,
80 C<is_uni_cntrl>,
81 C<is_uni_cntrl_lc>,
82 C<is_uni_idfirst_lc>,
83 C<is_uni_space>,
84 C<is_uni_space_lc>,
85 C<is_uni_xdigit>,
86 C<is_uni_xdigit_lc>,
87 C<is_utf8_ascii>,
88 C<is_utf8_blank>,
89 C<is_utf8_cntrl>,
90 C<is_utf8_idcont>,
91 C<is_utf8_idfirst>,
92 C<is_utf8_perl_space>,
93 C<is_utf8_perl_word>,
94 C<is_utf8_posix_digit>,
95 C<is_utf8_space>,
96 C<is_utf8_xdigit>.
97 C<is_utf8_xidcont>,
98 C<is_utf8_xidfirst>,
99 C<to_uni_lower_lc>,
100 C<to_uni_title_lc>,
101 and
102 C<to_uni_upper_lc>.
103
104 =head1 Performance Enhancements
105
106 XXX Changes which enhance performance without changing behaviour go here.
107 There may well be none in a stable release.
108
109 [ List each enhancement as a =item entry ]
110
111 =over 4
112
113 =item *
114
115 Perl has a new copy-on-write mechanism that avoids the need to copy the
116 internal string buffer when assigning from one scalar to another.  This
117 makes copying large strings appear much faster.  Modifying one of the two
118 (or more) strings after an assignment will force a copy internally.  This
119 makes it unnecessary to pass strings by reference for efficiency.
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 XXX
142
143 =back
144
145 =head2 Updated Modules and Pragmata
146
147 =over 4
148
149 =item *
150
151 L<GDBM_File> has been upgraded from version 1.14 to 1.15. The undocumented
152 optional fifth parameter to C<TIEHASH> has been removed. This was intended
153 to provide control of the callback used by C<gdbm*> functions in case of
154 fatal errors (such as filesystem problems), but did not work (and could
155 never have worked). No code on CPAN even attempted to use it. The callback
156 is now always the previous default, C<croak>. Problems on some platforms with
157 how the C<C> C<croak> function is called have also been resolved.
158
159 =back
160
161 =head2 Removed Modules and Pragmata
162
163 =over 4
164
165 =item *
166
167 XXX
168
169 =back
170
171 =head1 Documentation
172
173 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
174 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
175
176 =head2 New Documentation
177
178 XXX Changes which create B<new> files in F<pod/> go here.
179
180 =head3 L<XXX>
181
182 XXX Description of the purpose of the new file here
183
184 =head2 Changes to Existing Documentation
185
186 XXX Changes which significantly change existing files in F<pod/> go here.
187 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
188 section.
189
190 =head3 L<perlapi/Character classes>
191
192 =over 4
193
194 =item *
195
196 There are quite a few macros callable from XS modules that classify
197 characters into things like alphabetic, punctuation, etc.  More of these
198 are now documented, including ones which work on characters whose code
199 points are outside the Latin-1 range.
200
201 =back
202
203 =head1 Diagnostics
204
205 The following additions or changes have been made to diagnostic output,
206 including warnings and fatal error messages.  For the complete list of
207 diagnostic messages, see L<perldiag>.
208
209 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
210 include any changes in L<perldiag> that reconcile it to the C<C> code.
211
212 =head2 New Diagnostics
213
214 XXX Newly added diagnostic messages go under here, separated into New Errors
215 and New Warnings
216
217 =head3 New Errors
218
219 =over 4
220
221 =item *
222
223 XXX L<message|perldiag/"message">
224
225 =back
226
227 =head3 New Warnings
228
229 =over 4
230
231 =item *
232
233 XXX L<message|perldiag/"message">
234
235 =back
236
237 =head2 Changes to Existing Diagnostics
238
239 XXX Changes (i.e. rewording) of diagnostic messages go here
240
241 =over 4
242
243 =item *
244
245 XXX Describe change here
246
247 =back
248
249 =head1 Utility Changes
250
251 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
252 Most of these are built within the directories F<utils> and F<x2p>.
253
254 [ List utility changes as a =head3 entry for each utility and =item
255 entries for each change
256 Use L<XXX> with program names to get proper documentation linking. ]
257
258 =head3 L<XXX>
259
260 =over 4
261
262 =item *
263
264 XXX
265
266 =back
267
268 =head1 Configuration and Compilation
269
270 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
271 go here.  Any other changes to the Perl build process should be listed here.
272 However, any platform-specific changes should be listed in the
273 L</Platform Support> section, instead.
274
275 [ List changes as a =item entry ].
276
277 =over 4
278
279 =item *
280
281 XXX
282
283 =back
284
285 =head1 Testing
286
287 XXX Any significant changes to the testing of a freshly built perl should be
288 listed here.  Changes which create B<new> files in F<t/> go here as do any
289 large changes to the testing harness (e.g. when parallel testing was added).
290 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
291 that they represent may be covered elsewhere.
292
293 [ List each test improvement as a =item entry ]
294
295 =over 4
296
297 =item *
298
299 XXX
300
301 =back
302
303 =head1 Platform Support
304
305 XXX Any changes to platform support should be listed in the sections below.
306
307 [ Within the sections, list each platform as a =item entry with specific
308 changes as paragraphs below it. ]
309
310 =head2 New Platforms
311
312 XXX List any platforms that this version of perl compiles on, that previous
313 versions did not.  These will either be enabled by new files in the F<hints/>
314 directories, or new subdirectories and F<README> files at the top level of the
315 source tree.
316
317 =over 4
318
319 =item XXX-some-platform
320
321 XXX
322
323 =back
324
325 =head2 Discontinued Platforms
326
327 =over 4
328
329 =item BeOS
330
331 Support for BeOS has been removed.
332
333 =back
334
335 =head2 Platform-Specific Notes
336
337 XXX List any changes for specific platforms.  This could include configuration
338 and compilation changes or changes in portability/compatibility.  However,
339 changes within modules for platforms should generally be listed in the
340 L</Modules and Pragmata> section.
341
342 =over 4
343
344 =item XXX-some-platform
345
346 XXX
347
348 =back
349
350 =head1 Internal Changes
351
352 XXX Changes which affect the interface available to C<XS> code go here.  Other
353 significant internal changes for future core maintainers should be noted as
354 well.
355
356 [ List each change as a =item entry ]
357
358 =over 4
359
360 =item *
361
362 SvUPGRADE() is no longer an expression. Originally this macro (and its
363 underlying function, sv_upgrade()) were documented as boolean, although
364 in reality they always croaked on error and never returned false. In 2005
365 the documentation was updated to specify a void return value, but
366 SvUPGRADE() was left always returning 1 for backwards compatibility. This
367 has now been removed, and SvUPGRADE() is now a statement with no return
368 value.
369
370 So this is now a syntax error:
371
372     if (!SvUPGRADE(sv)) { croak(...); }
373
374 If you have code like that, simply replace it with
375
376     SvUPGRADE(sv);
377
378 or to to avoid compiler warnings with older perls, possibly
379
380     (void)SvUPGRADE(sv);
381
382 =item *
383
384 Perl has a new copy-on-write mechanism that allows any SvPOK scalar to be
385 upgraded to a copy-on-write scalar.  A reference count on the string buffer
386 is stored in the string buffer itself.
387
388 This breaks a few XS modules by allowing copy-on-write scalars to go
389 through code paths that never encountered them before.
390
391 This behaviour can still be disabled by running F<Configure> with
392 B<-Accflags=-DPERL_NO_COW>.  This option will probably be removed in Perl
393 5.20.
394
395 =item *
396
397 Copy-on-write no longer uses the SvFAKE and SvREADONLY flags.  Hence,
398 SvREADONLY indicates a true read-only SV.
399
400 Use the SvIsCOW macro (as before) to identify a copy-on-write scalar.
401
402 =item *
403
404 C<PL_sawampersand> is now a constant.  The switch this variable provided
405 (to enable/disable the pre-match copy depending on whether C<$&> had been
406 seen) has been removed and replaced with copy-on-write, eliminating a few
407 bugs.
408
409 The previous behaviour can still be enabled by running F<Configure> with
410 B<-Accflags=-DPERL_SAWAMPERSAND>.
411
412 =back
413
414 =head1 Selected Bug Fixes
415
416 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
417 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
418
419 [ List each fix as a =item entry ]
420
421 =over 4
422
423 =item *
424
425 C<sort {undef} ...> under fatal warnings no longer crashes.  It started
426 crashing in Perl 5.16.
427
428 =item *
429
430 Stashes blessed into each other
431 (C<bless \%Foo::, 'Bar'; bless \%Bar::, 'Foo'>) no longer result in double
432 frees.  This bug started happening in Perl 5.16.
433
434 =item *
435
436 Numerous memory leaks have been fixed, mostly involving fatal warnings and
437 syntax errors.
438
439 =item *
440
441 Lexical constants (C<my sub answer () { 42 }>) no longer cause double
442 frees.
443
444 =item *
445
446 Constant subroutine redefinition warns by default, but lexical constants
447 were accidentally exempt from default warnings.  This has been corrected.
448
449 =item *
450
451 Some failed regular expression matches such as C<'f' =~ /../g> were not
452 resetting C<pos>.  Also, "match-once" patterns (C<m?...?g>) failed to reset
453 it, too, when invoked a second time [perl #23180].
454
455 =item *
456
457 Accessing C<$&> after a pattern match now works if it had not been seen
458 before the match.  I.e., this applies to C<${'&'}> (under C<no strict>) and
459 C<eval '$&'>.  The same applies to C<$'> and C<$`> [perl #4289].
460
461 =item *
462
463 Two minor bugs involving C<local *ISA> and C<local *Foo::> causing stale
464 MRO caches have been fixed.  
465
466 =back
467
468 =head1 Known Problems
469
470 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
471 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
472 platform specific bugs also go here.
473
474 [ List each fix as a =item entry ]
475
476 =over 4
477
478 =item *
479
480 XXX
481
482 =back
483
484 =head1 Obituary
485
486 XXX If any significant core contributor has died, we've added a short obituary
487 here.
488
489 =head1 Acknowledgements
490
491 XXX Generate this with:
492
493   perl Porting/acknowledgements.pl v5.17.6..HEAD
494
495 =head1 Reporting Bugs
496
497 If you find what you think is a bug, you might check the articles recently
498 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
499 http://rt.perl.org/perlbug/ .  There may also be information at
500 http://www.perl.org/ , the Perl Home Page.
501
502 If you believe you have an unreported bug, please run the L<perlbug> program
503 included with your release.  Be sure to trim your bug down to a tiny but
504 sufficient test case.  Your bug report, along with the output of C<perl -V>,
505 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
506
507 If the bug you are reporting has security implications, which make it
508 inappropriate to send to a publicly archived mailing list, then please send it
509 to perl5-security-report@perl.org.  This points to a closed subscription
510 unarchived mailing list, which includes all the core committers, who will be
511 able to help assess the impact of issues, figure out a resolution, and help
512 co-ordinate the release of patches to mitigate or fix the problem across all
513 platforms on which Perl is supported.  Please only use this address for
514 security issues in the Perl core, not for modules independently distributed on
515 CPAN.
516
517 =head1 SEE ALSO
518
519 The F<Changes> file for an explanation of how to view exhaustive details on
520 what changed.
521
522 The F<INSTALL> file for how to build Perl.
523
524 The F<README> file for general stuff.
525
526 The F<Artistic> and F<Copying> files for copyright information.
527
528 =cut