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 =item *
 411
 412 Constant subroutine redefinition warns by default, but lexical constants
 413 were accidentally exempt from default warnings.  This has been corrected.
 414
 415 =back
 416
 417 =head1 Known Problems
 418
 419 XXX Descriptions of platform agnostic bugs we know we can't fix go here.  Any
 420 tests that had to be C<TODO>ed for the release would be noted here.  Unfixed
 421 platform specific bugs also go here.
 422
 423 [ List each fix as a =item entry ]
 424
 425 =over 4
 426
 427 =item *
 428
 429 XXX
 430
 431 =back
 432
 433 =head1 Obituary
 434
 435 XXX If any significant core contributor has died, we've added a short obituary
 436 here.
 437
 438 =head1 Acknowledgements
 439
 440 XXX Generate this with:
 441
 442   perl Porting/acknowledgements.pl v5.17.6..HEAD
 443
 444 =head1 Reporting Bugs
 445
 446 If you find what you think is a bug, you might check the articles recently
 447 posted to the comp.lang.perl.misc newsgroup and the perl bug database at
 448 http://rt.perl.org/perlbug/ .  There may also be information at
 449 http://www.perl.org/ , the Perl Home Page.
 450
 451 If you believe you have an unreported bug, please run the L<perlbug> program
 452 included with your release.  Be sure to trim your bug down to a tiny but
 453 sufficient test case.  Your bug report, along with the output of C<perl -V>,
 454 will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
 455
 456 If the bug you are reporting has security implications, which make it
 457 inappropriate to send to a publicly archived mailing list, then please send it
 458 to perl5-security-report@perl.org.  This points to a closed subscription
 459 unarchived mailing list, which includes all the core committers, who will be
 460 able to help assess the impact of issues, figure out a resolution, and help
 461 co-ordinate the release of patches to mitigate or fix the problem across all
 462 platforms on which Perl is supported.  Please only use this address for
 463 security issues in the Perl core, not for modules independently distributed on
 464 CPAN.
 465
 466 =head1 SEE ALSO
 467
 468 The F<Changes> file for an explanation of how to view exhaustive details on
 469 what changed.
 470
 471 The F<INSTALL> file for how to build Perl.
 472
 473 The F<README> file for general stuff.
 474
 475 The F<Artistic> and F<Copying> files for copyright information.
 476
 477 =cut