Document the ExtUtils::ParseXS changes in perldelta
[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
6 XXX needs to be processed before release. ]
7
8 perldelta - what is new for perl v5.15.1
9
10 =head1 DESCRIPTION
11
12 This document describes differences between the 5.15.1 release and
13 the 5.15.0 release.
14
15 If you are upgrading from an earlier release such as 5.14.0, first read
16 L<perl5150delta>, which describes differences between 5.14.0 and
17 5.15.0.
18
19 =head1 Notice
20
21 XXX Any important notices here
22
23 =head1 Core Enhancements
24
25 XXX New core language features go here. Summarise user-visible core language
26 enhancements. Particularly prominent performance optimisations could go
27 here, but most should go in the L</Performance Enhancements> section.
28
29 [ List each enhancement as a =head2 entry ]
30
31 =head2 C<splice()> doesn't warn when truncating
32
33 You can now limit the size of an array using C<splice(@a,MAX_LEN)> without
34 worrying about warnings.
35
36 =head2 The C<\$> prototype accepts any scalar lvalue
37
38 The C<\$> and C<\[$]> subroutine prototypes now accept any scalar lvalue
39 argument.  Previously they only accepted scalars beginning with C<$> and
40 hash and array elements.  This change makes them consistent with the way
41 the built-in C<read> and C<recv> functions (among others) parse their
42 arguments. This means that one can override the built-in functions with
43 custom subroutines that parse their arguments the same way.
44
45 =head2 You can now C<study> more than one string
46
47 The restriction that you can only have one C<study> active at a time has been
48 removed. You can now usefully C<study> as many strings as you want (until you
49 exhaust memory).
50
51 =head2 The Unicode C<Script_Extensions> property is now supported.
52
53 New in Unicode 6.0, this is an improved C<Script> property.  Details
54 are in L<perlunicode/Scripts>.
55
56 =head2 DTrace probes for interpreter phase change
57
58 The C<phase-change> probes will fire when the interpreter's phase
59 changes, which tracks the C<${^GLOBAL_PHASE}> variable. C<arg0> is
60 the new phase name; C<arg1> is the old one. This is useful mostly
61 for limiting your instrumentation to one or more of: compile time,
62 run time, destruct time.
63
64 =head1 Security
65
66 XXX Any security-related notices go here.  In particular, any security
67 vulnerabilities closed should be noted here rather than in the
68 L</Selected Bug Fixes> section.
69
70 [ List each security issue as a =head2 entry ]
71
72 =head1 Incompatible Changes
73
74 XXX For a release on a stable branch, this section aspires to be:
75
76     There are no changes intentionally incompatible with 5.XXX.XXX
77     If any exist, they are bugs and reports are welcome.
78
79 [ List each incompatible change as a =head2 entry ]
80
81 =head1 Deprecations
82
83 XXX Any deprecated features, syntax, modules etc. should be listed here.
84 In particular, deprecated modules should be listed here even if they are
85 listed as an updated module in the L</Modules and Pragmata> section.
86
87 [ List each deprecation as a =head2 entry ]
88
89 =head1 Performance Enhancements
90
91 XXX Changes which enhance performance without changing behaviour go here. There
92 may well be none in a stable release.
93
94 [ List each enhancement as a =item entry ]
95
96 =over 4
97
98 =item *
99
100 The implementation of C<s///r> makes one less copy of the scalar's value.
101
102 =item *
103
104 If a studied scalar is C<split> with a regex, the engine will now take
105 advantage of the C<study> data.
106
107 =item *
108
109 C<study> now uses considerably less memory for shorter strings. Strings shorter
110 than 65535 characters use roughly half the memory than previously, strings
111 shorter than 255 characters use roughly one quarter of the memory.
112
113 =item *
114
115 Recursive calls to lvalue subroutines in lvalue scalar context use less
116 memory.
117
118 =back
119
120 =head1 Modules and Pragmata
121
122 XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
123 go here.  If Module::CoreList is updated, generate an initial draft of the
124 following sections using F<Porting/corelist-perldelta.pl>, which prints stub
125 entries to STDOUT.  Results can be pasted in place of the '=head2' entries
126 below.  A paragraph summary for important changes should then be added by hand.
127 In an ideal world, dual-life modules would have a F<Changes> file that could be
128 cribbed.
129
130 [ Within each section, list entries as a =item entry ]
131
132 =head2 New Modules and Pragmata
133
134 =over 4
135
136 =item *
137
138 XXX
139
140 =back
141
142 =head2 Updated Modules and Pragmata
143
144 =over 4
145
146 =item *
147
148 L<ExtUtils::ParseXS> has been upgraded from version XXX to version XXX.
149
150 Much of L<ExtUtils::ParseXS>, the module behind the XS compiler C<xsubpp>,
151 was rewritten and cleaned up. It has been made somewhat more extensible
152 and now finally uses strictures.
153
154 The logic for parsing, merging, and dumping XS typemaps was extracted
155 from C<ExtUtils::ParseXS> into a module of its own, L<ExtUtils::Typemaps>.
156 C<ExtUtils::Typemaps> offers an interface to typemap handling outside of
157 the scope of the XS compiler itself.
158
159 As a first use case of the improved API an extensibility, typemaps can now
160 be included inline into XS code with a HEREDOC-like syntax:
161
162   TYPEMAP: <<END_TYPEMAP
163   MyType        T_IV
164   END_TYPEMAP
165
166 =item *
167
168 L<CGI> has been upgraded from version 3.54 to version 3.55
169
170 [THINGS THAT MAY BREAK YOUR CODE]
171
172 C<url()> was fixed to return C<PATH_INFO> when it is explicitly requested
173 with either the path=>1 or path_info=>1 flag.
174
175 If your code is running under mod_rewrite (or compatible) and you are calling C<self_url()> or
176 you are calling C<url()> and passing path_info=>1, These methods will actually be
177 returning C<PATH_INFO> now, as you have explicitly requested, or has C<self_url()>
178 has requested on your behalf.
179
180 The C<PATH_INFO> has been omitted in such URLs since the issue was introduced
181 in the 3.12 release in December, 2005.
182
183 This bug is so old your application may have come to depend on it or
184 workaround it. Check for application before upgrading to this release.
185
186 Examples of affected method calls:
187
188   $q->url(-absolute => 1, -query => 1, -path_info => 1 )
189   $q->url(-path=>1)
190   $q->url(-full=>1,-path=>1)
191   $q->url(-rewrite=>1,-path=>1)
192   $q->self_url();
193
194 =item *
195
196 L<Compress::Raw::Bzip2> has been upgraded from version 2.035 to version 2.037
197
198 =item *
199
200 L<Compress::Raw::Zlib> has been upgraded from version 2.035 to version 2.037
201
202 Added offset parameter to CRC32
203
204 =item *
205
206 L<Compress::Zlib> has been upgraded from version 2.035 to version 2.037
207
208 IO::Compress::Zip and IO::Uncompress::Unzip now have support for LZMA (method 14).
209 There is a fix for a CRC issue in IO::Compress::Unzip and it supports Streamed
210 Stored context now. And fixed a Zip64 issue in
211 IO::Compress::Zip when the content size was exactly 0xFFFFFFFF.
212
213 =item *
214
215 L<CPANPLUS> has been upgraded from version 0.9105 to version 0.9107
216
217 =item *
218
219 L<ExtUtils::MakeMaker> has been upgraded from version 6.57_05 to version 6.58
220
221 =item *
222
223 L<IPC::Cmd> has been upgraded from version 0.70 to version 0.72
224
225 Capturing of command output (both C<STDOUT> and C<STDERR>) is now supported
226 using L<IPC::Open3> on MSWin32 without requiring L<IPC::Run>.
227
228 =item *
229
230 L<Locale::Codes> has been upgraded from version 3.16 to version 3.17
231
232 Added Language Extension codes (langext) and Language Variation codes
233 (langvar) as defined in the IANA language registry.
234
235 Added language codes from ISO 639-5
236
237 Added language/script codes from the IANA language subtag
238 registry
239
240 Fixed an uninitialized value warning.  RT 67438
241
242 Fixed the return value for the all_XXX_codes and all_XXX_names functions.  RT 69100
243
244 Reorganized modules to move Locale::MODULE to Locale::Codes::MODULE to
245 allow for cleaner future additions.  The original four modules (Locale::Language,
246 Locale::Currency, Locale::Country, Locale::Script) will continue to work, but
247 all new sets of codes will be added in the Locale::Codes namespace.
248
249 =item *
250
251 L<attributes> has been upgraded from version 0.14 to 0.15, as part of the
252 lvalue attribute warnings fix.  See L</Selected Bug Fixes>, below.
253
254 =item *
255
256 L<Math::BigInt::FastCalc> has been upgraded from version 0.28 to version 0.29.
257
258 The XS code is now compiled with C<PERL_NO_GET_CONTEXT>, which will aid
259 performance under ithreads.
260
261 =item *
262
263 L<Pod::Simple> has been upgraded from version 3.16 to version 3.17
264
265 =item *
266
267 L<Unicode::Collate> has been upgraded from version 0.76 to version 0.77
268
269 Applied [perl #93470] silencing compiler warnings with -Wwrite-strings
270
271 =item *
272
273 L<Win32API::File> has been upgraded from version 0.1101 to version 0.1200
274
275 Added SetStdHandle and GetStdHandle functions
276
277 =item *
278
279 L<threads> has been upgraded from version 1.83 to 1.84
280
281 An unused variable was removed from the XS code.
282
283 =back
284
285 =head2 Removed Modules and Pragmata
286
287 =over 4
288
289 =item *
290
291 Perl 4-era .pl libraries
292
293 Perl used to bundle a handful of library files that predate Perl 5. Most of
294 these files, which have been deprecated since version 5.14.0, have now been
295 removed. If your code still relies on these libraries, you can install them
296 again from C<Perl4::CoreLibs> on CPAN.
297
298 =back
299
300 =head1 Documentation
301
302 XXX Changes to files in F<pod/> go here.  Consider grouping entries by
303 file and be sure to link to the appropriate page, e.g. L<perlfunc>.
304
305 =head2 New Documentation
306
307 XXX Changes which create B<new> files in F<pod/> go here.
308
309 =head3 L<perldtrace>
310
311 L<perldtrace> describes Perl's DTrace support, listing the provided probes
312 and gives examples of their use.
313
314 =head2 Changes to Existing Documentation
315
316 XXX Changes which significantly change existing files in F<pod/> go here.
317 However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
318 section.
319
320 =head3 L<XXX>
321
322 =over 4
323
324 =item *
325
326 XXX Description of the change here
327
328 =item *
329
330 L<perlxs> was extended with documentation on inline typemaps.
331
332 =back
333
334 =head1 Diagnostics
335
336 The following additions or changes have been made to diagnostic output,
337 including warnings and fatal error messages.  For the complete list of
338 diagnostic messages, see L<perldiag>.
339
340 XXX New or changed warnings emitted by the core's C<C> code go here. Also
341 include any changes in L<perldiag> that reconcile it to the C<C> code.
342
343 [ Within each section, list entries as a =item entry that links to perldiag,
344   e.g.
345
346   =item *
347
348   L<Invalid version object|perldiag/"Invalid version object">
349 ]
350
351 =head2 New Diagnostics
352
353 XXX Newly added diagnostic messages go here
354
355 =head3 New Errors
356
357 =over 4
358
359 =item *
360
361 XXX L<message|perldiag/"message">
362
363 =back
364
365 =head3 New Warnings
366
367 =over 4
368
369 =item *
370
371 XXX L<message|perldiag/"message">
372
373 =back
374
375 =head2 Changes to Existing Diagnostics
376
377 XXX Changes (i.e. rewording) of diagnostic messages go here
378
379 =over 4
380
381 =item *
382
383 XXX Describe change here
384
385 =back
386
387 =head1 Utility Changes
388
389 XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go
390 here. Most of these are built within the directories F<utils> and F<x2p>.
391
392 [ List utility changes as a =head3 entry for each utility and =item
393 entries for each change
394 Use L<XXX> with program names to get proper documentation linking. ]
395
396 =head3 L<XXX>
397
398 =over 4
399
400 =item *
401
402 XXX
403
404 =back
405
406 =head1 Configuration and Compilation
407
408 XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
409 go here.  Any other changes to the Perl build process should be listed here.
410 However, any platform-specific changes should be listed in the
411 L</Platform Support> section, instead.
412
413 [ List changes as a =item entry ].
414
415 =over 4
416
417 =item *
418
419 XXX
420
421 =back
422
423 =head1 Testing
424
425 XXX Any significant changes to the testing of a freshly built perl should be
426 listed here.  Changes which create B<new> files in F<t/> go here as do any
427 large changes to the testing harness (e.g. when parallel testing was added).
428 Changes to existing files in F<t/> aren't worth summarising, although the bugs
429 that they represent may be covered elsewhere.
430
431 [ List each test improvement as a =item entry ]
432
433 =over 4
434
435 =item *
436
437 F<t/run/dtrace.t> was added to test Perl's DTrace support. This
438 test will only be run if your Perl was built with C<-Dusedtrace>
439 and if calling C<dtrace> actually lets you instrument code. This
440 generally requires being run as root, so this test file is primarily
441 intended for use by the dtrace subcommittee of p5p.
442
443 =back
444
445 =head1 Platform Support
446
447 XXX Any changes to platform support should be listed in the sections below.
448
449 [ Within the sections, list each platform as a =item entry with specific
450 changes as paragraphs below it. ]
451
452 =head2 New Platforms
453
454 XXX List any platforms that this version of perl compiles on, that previous
455 versions did not. These will either be enabled by new files in the F<hints/>
456 directories, or new subdirectories and F<README> files at the top level of the
457 source tree.
458
459 =over 4
460
461 =item XXX-some-platform
462
463 XXX
464
465 =back
466
467 =head2 Discontinued Platforms
468
469 XXX List any platforms that this version of perl no longer compiles on.
470
471 =over 4
472
473 =item XXX-some-platform
474
475 XXX
476
477 =back
478
479 =head2 Platform-Specific Notes
480
481 XXX List any changes for specific platforms. This could include configuration
482 and compilation changes or changes in portability/compatibility.  However,
483 changes within modules for platforms should generally be listed in the
484 L</Modules and Pragmata> section.
485
486 =over 4
487
488 =item XXX-some-platform
489
490 XXX
491
492 =back
493
494 =head1 Internal Changes
495
496 XXX Changes which affect the interface available to C<XS> code go here.
497 Other significant internal changes for future core maintainers should
498 be noted as well.
499
500 [ List each change as a =item entry ]
501
502 =over 4
503
504 =item *
505
506 XXX
507
508 =back
509
510 =head1 Selected Bug Fixes
511
512 XXX Important bug fixes in the core language are summarised here.
513 Bug fixes in files in F<ext/> and F<lib/> are best summarised in
514 L</Modules and Pragmata>.
515
516 [ List each fix as a =item entry ]
517
518 =over 4
519
520 =item *
521
522 Applying the :lvalue attribute to subroutine that is already defined does
523 not work properly, as the attribute changes the way the sub is compiled.
524 Hence, Perl 5.12 began warning when an attempt is made to apply the
525 attribute to an already defined sub.  In such cases, the attribute is
526 discarded.
527
528 But the change in 5.12 missed the case where custom attributes are also
529 present: that case still silently and ineffectively applied the attribute.
530 That omission has now been corrected.  C<sub foo :lvalue :Whatever> (when
531 C<foo> is already defined) now warns about the :lvalue attribute, and does
532 not apply it.
533
534 L<attributes.pm|attributes> has likewise been updated to warn and not apply
535 the attribute.
536
537 =item *
538
539 =for comment
540 Not necessary for perl5160delta
541
542 The remaining discrepancies between explicit and implicit return from
543 lvalue subroutines have been resolved.  They mainly involved which error
544 message to display when a read-only value is returned in lvalue context.
545 Also, returning a PADTMP (the result of most built-ins, like C<index>) in
546 lvalue context is now forbidden for explicit return, as it always has been
547 for implicit return.  This is not a regression from 5.14, as all the cases
548 in which it could happen where previously syntax errors.
549
550 =item *
551
552 =for comment
553 Not necessary for perl5160delta
554
555 Explicitly returning a tied C<my> variable from an lvalue subroutine in
556 list lvalue context used to clear the variable before the assignment could
557 happen.  This is something that was missed when explicit return was made to
558 work in 5.15.0.
559
560 =item *
561
562 =for comment
563 Not necessary for perl5160delta
564
565 A minor memory leak, introduced in 5.15.0, has been fixed.  It would occur
566 when a hash is freed that has had its current iterator deleted
567 [perl #93454].
568
569 =item *
570
571 The C<prototype> function now returns a prototype (the empty string) for
572 the C<__FILE__>, C<__LINE__> and C<__PACKAGE__> directives, instead of
573 dying, as they are indistinguishable syntactically from nullary functions
574 like C<time>.
575
576 =item *
577
578 A bug affecting lvalue context propagation through nested lvalue subroutine
579 calls has been fixed.  Previously, returning a value in nested rvalue
580 context would be treated as lvalue context by the inner subroutine call,
581 resulting in some values (such as read-only values) being rejected.
582
583 =back
584
585 =head1 Known Problems
586
587 XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
588 tests that had to be C<TODO>ed for the release would be noted here, unless
589 they were specific to a particular platform (see below).
590
591 This is a list of some significant unfixed bugs, which are regressions
592 from either 5.XXX.XXX or 5.XXX.XXX.
593
594 [ List each fix as a =item entry ]
595
596 =over 4
597
598 =item *
599
600 XXX
601
602 =back
603
604 =head1 Obituary
605
606 XXX If any significant core contributor has died, we've added a short obituary
607 here.
608
609 =head1 Acknowledgements
610
611 XXX The list of people to thank goes here.
612
613 =head1 Reporting Bugs
614
615 If you find what you think is a bug, you might check the articles
616 recently posted to the comp.lang.perl.misc newsgroup and the perl
617 bug database at http://rt.perl.org/perlbug/ .  There may also be
618 information at http://www.perl.org/ , the Perl Home Page.
619
620 If you believe you have an unreported bug, please run the L<perlbug>
621 program included with your release.  Be sure to trim your bug down
622 to a tiny but sufficient test case.  Your bug report, along with the
623 output of C<perl -V>, will be sent off to perlbug@perl.org to be
624 analysed by the Perl porting team.
625
626 If the bug you are reporting has security implications, which make it
627 inappropriate to send to a publicly archived mailing list, then please send
628 it to perl5-security-report@perl.org. This points to a closed subscription
629 unarchived mailing list, which includes
630 all the core committers, who will be able
631 to help assess the impact of issues, figure out a resolution, and help
632 co-ordinate the release of patches to mitigate or fix the problem across all
633 platforms on which Perl is supported. Please only use this address for
634 security issues in the Perl core, not for modules independently
635 distributed on CPAN.
636
637 =head1 SEE ALSO
638
639 The F<Changes> file for an explanation of how to view exhaustive details
640 on what changed.
641
642 The F<INSTALL> file for how to build Perl.
643
644 The F<README> file for general stuff.
645
646 The F<Artistic> and F<Copying> files for copyright information.
647
648 =cut