This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perldelta for 4ded55f35 (lexical constants)
[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 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 =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 XXX
116
117 =back
118
119 =head1 Modules and Pragmata
120
121 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
122 go here.  If Module::CoreList is updated, generate an initial draft of the
123 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
124 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
125 below.  A paragraph summary for important changes should then be added by hand.
126 In an ideal world, dual-life modules would have a F<Changes> file that could be
127 cribbed.
128
129 [ Within each section, list entries as a =item entry ]
130
131 =head2 New Modules and Pragmata
132
133 =over 4
134
135 =item *
136
137 XXX
138
139 =back
140
141 =head2 Updated Modules and Pragmata
142
143 =over 4
144
145 =item *
146
147 L<GDBM_File> has been upgraded from version 1.14 to 1.15. The undocumented
148 optional fifth parameter to C<TIEHASH> has been removed. This was intended
149 to provide control of the callback used by C<gdbm*> functions in case of
150 fatal errors (such as filesystem problems), but did not work (and could
151 never have worked). No code on CPAN even attempted to use it. The callback
152 is now always the previous default, C<croak>. Problems on some platforms with
153 how the C<C> C<croak> function is called have also been resolved.
154
155 =back
156
157 =head2 Removed Modules and Pragmata
158
159 =over 4
160
161 =item *
162
163 XXX
164
165 =back
166
167 =head1 Documentation
168
169 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
170 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
171
172 =head2 New Documentation
173
174 XXX Changes which create B<new> files in F<pod/> go here.
175
176 =head3 L<XXX>
177
178 XXX Description of the purpose of the new file here
179
180 =head2 Changes to Existing Documentation
181
182 XXX Changes which significantly change existing files in F<pod/> go here.
183 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
184 section.
185
186 =head3 L<perlapi/Character classes>
187
188 =over 4
189
190 =item *
191
192 There are quite a few macros callable from XS modules that classify
193 characters into things like alphabetic, punctuation, etc.  More of these
194 are now documented, including ones which work on characters whose code
195 points are outside the Latin-1 range.
196
197 =back
198
199 =head1 Diagnostics
200
201 The following additions or changes have been made to diagnostic output,
202 including warnings and fatal error messages.  For the complete list of
203 diagnostic messages, see L<perldiag>.
204
205 XXX New or changed warnings emitted by the core's C<C> code go here.  Also
206 include any changes in L<perldiag> that reconcile it to the C<C> code.
207
208 =head2 New Diagnostics
209
210 XXX Newly added diagnostic messages go under here, separated into New Errors
211 and New Warnings
212
213 =head3 New Errors
214
215 =over 4
216
217 =item *
218
219 XXX L<message|perldiag/"message">
220
221 =back
222
223 =head3 New Warnings
224
225 =over 4
226
227 =item *
228
229 XXX L<message|perldiag/"message">
230
231 =back
232
233 =head2 Changes to Existing Diagnostics
234
235 XXX Changes (i.e. rewording) of diagnostic messages go here
236
237 =over 4
238
239 =item *
240
241 XXX Describe change here
242
243 =back
244
245 =head1 Utility Changes
246
247 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
248 Most of these are built within the directories F<utils> and F<x2p>.
249
250 [ List utility changes as a =head3 entry for each utility and =item
251 entries for each change
252 Use L<XXX> with program names to get proper documentation linking. ]
253
254 =head3 L<XXX>
255
256 =over 4
257
258 =item *
259
260 XXX
261
262 =back
263
264 =head1 Configuration and Compilation
265
266 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
267 go here.  Any other changes to the Perl build process should be listed here.
268 However, any platform-specific changes should be listed in the
269 L</Platform Support> section, instead.
270
271 [ List changes as a =item entry ].
272
273 =over 4
274
275 =item *
276
277 XXX
278
279 =back
280
281 =head1 Testing
282
283 XXX Any significant changes to the testing of a freshly built perl should be
284 listed here.  Changes which create B<new> files in F<t/> go here as do any
285 large changes to the testing harness (e.g. when parallel testing was added).
286 Changes to existing files in F<t/> aren't worth summarizing, although the bugs
287 that they represent may be covered elsewhere.
288
289 [ List each test improvement as a =item entry ]
290
291 =over 4
292
293 =item *
294
295 XXX
296
297 =back
298
299 =head1 Platform Support
300
301 XXX Any changes to platform support should be listed in the sections below.
302
303 [ Within the sections, list each platform as a =item entry with specific
304 changes as paragraphs below it. ]
305
306 =head2 New Platforms
307
308 XXX List any platforms that this version of perl compiles on, that previous
309 versions did not.  These will either be enabled by new files in the F<hints/>
310 directories, or new subdirectories and F<README> files at the top level of the
311 source tree.
312
313 =over 4
314
315 =item XXX-some-platform
316
317 XXX
318
319 =back
320
321 =head2 Discontinued Platforms
322
323 =over 4
324
325 =item BeOS
326
327 Support for BeOS has been removed.
328
329 =back
330
331 =head2 Platform-Specific Notes
332
333 XXX List any changes for specific platforms.  This could include configuration
334 and compilation changes or changes in portability/compatibility.  However,
335 changes within modules for platforms should generally be listed in the
336 L</Modules and Pragmata> section.
337
338 =over 4
339
340 =item XXX-some-platform
341
342 XXX
343
344 =back
345
346 =head1 Internal Changes
347
348 XXX Changes which affect the interface available to C<XS> code go here.  Other
349 significant internal changes for future core maintainers should be noted as
350 well.
351
352 [ List each change as a =item entry ]
353
354 =over 4
355
356 =item *
357
358 SvUPGRADE() is no longer an expression. Originally this macro (and its
359 underlying function, sv_upgrade()) were documented as boolean, although
360 in reality they always croaked on error and never returned false. In 2005
361 the documentation was updated to specify a void return value, but
362 SvUPGRADE() was left always returning 1 for backwards compatibility. This
363 has now been removed, and SvUPGRADE() is now a statement with no return
364 value.
365
366 So this is now a syntax error:
367
368     if (!SvUPGRADE(sv)) { croak(...); }
369
370 If you have code like that, simply replace it with
371
372     SvUPGRADE(sv);
373
374 or to to avoid compiler warnings with older perls, possibly
375
376     (void)SvUPGRADE(sv);
377
378 =back
379
380 =head1 Selected Bug Fixes
381
382 XXX Important bug fixes in the core language are summarized here.  Bug fixes in
383 files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
384
385 [ List each fix as a =item entry ]
386
387 =over 4
388
389 =item *
390
391 C<sort {undef} ...> under fatal warnings no longer crashes.  It started
392 crashing in Perl 5.16.
393
394 =item *
395
396 Stashes blessed into each other
397 (C<bless \%Foo::, 'Bar'; bless \%Bar::, 'Foo'>) no longer result in double
398 frees.  This bug started happening in Perl 5.16.
399
400 =item *
401
402 Numerous memory leaks have been fixed, mostly involving fatal warnings and
403 syntax errors.
404
405 =item *
406
407 Lexical constants (C<my sub answer () { 42 }>) no longer cause double
408 frees.
409
410 =back
411
412 =head1 Known Problems
413
414 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
415 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
416 platform specific bugs also go here.
417
418 [ List each fix as a =item entry ]
419
420 =over 4
421
422 =item *
423
424 XXX
425
426 =back
427
428 =head1 Obituary
429
430 XXX If any significant core contributor has died, we've added a short obituary
431 here.
432
433 =head1 Acknowledgements
434
435 XXX Generate this with:
436
437   perl Porting/acknowledgements.pl v5.17.6..HEAD
438
439 =head1 Reporting Bugs
440
441 If you find what you think is a bug, you might check the articles recently
442 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
443 http://rt.perl.org/perlbug/ .  There may also be information at
444 http://www.perl.org/ , the Perl Home Page.
445
446 If you believe you have an unreported bug, please run the L<perlbug> program
447 included with your release.  Be sure to trim your bug down to a tiny but
448 sufficient test case.  Your bug report, along with the output of C<perl -V>,
449 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
450
451 If the bug you are reporting has security implications, which make it
452 inappropriate to send to a publicly archived mailing list, then please send it
453 to perl5-security-report@perl.org.  This points to a closed subscription
454 unarchived mailing list, which includes all the core committers, who will be
455 able to help assess the impact of issues, figure out a resolution, and help
456 co-ordinate the release of patches to mitigate or fix the problem across all
457 platforms on which Perl is supported.  Please only use this address for
458 security issues in the Perl core, not for modules independently distributed on
459 CPAN.
460
461 =head1 SEE ALSO
462
463 The F<Changes> file for an explanation of how to view exhaustive details on
464 what changed.
465
466 The F<INSTALL> file for how to build Perl.
467
468 The F<README> file for general stuff.
469
470 The F<Artistic> and F<Copying> files for copyright information.
471
472 =cut