This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
diag.t, perldiag.pod: Make sure S is used for Perl_warn
[perl5.git] / pod / perldelta.pod
CommitLineData
44691e6f
AB
1=encoding utf8
2
3=head1 NAME
4
583aa5c2
RS
5[ this is a template for a new perldelta file. Any text flagged as XXX needs
6to be processed before release. ]
7
8perldelta - what is new for perl v5.19.1
e128ab2c 9
4eabcf70 10=head1 DESCRIPTION
6db9054f 11
583aa5c2 12This document describes differences between the 5.19.0 release and the 5.19.1
e08634c5 13release.
6db9054f 14
e9912eaa 15=head1 Notice
5ed58cbd 16
583aa5c2
RS
17XXX Any important notices here
18
19=head1 Core Enhancements
20
21XXX New core language features go here. Summarize user-visible core language
22enhancements. Particularly prominent performance optimisations could go
23here, but most should go in the L</Performance Enhancements> section.
24
25[ List each enhancement as a =head2 entry ]
26
27=head1 Security
28
29XXX Any security-related notices go here. In particular, any security
30vulnerabilities closed should be noted here rather than in the
31L</Selected Bug Fixes> section.
32
33[ List each security issue as a =head2 entry ]
34
35=head1 Incompatible Changes
36
37XXX For a release on a stable branch, this section aspires to be:
38
39 There are no changes intentionally incompatible with 5.XXX.XXX
40 If any exist, they are bugs, and we request that you submit a
41 report. See L</Reporting Bugs> below.
42
43[ List each incompatible change as a =head2 entry ]
44
45=head1 Deprecations
46
47XXX Any deprecated features, syntax, modules etc. should be listed here.
48
49=head2 Module removals
50
51XXX Remove this section if inapplicable.
52
53The following modules will be removed from the core distribution in a future
54release, and will at that time need to be installed from CPAN. Distributions
55on CPAN which require these modules will need to list them as prerequisites.
56
57The core versions of these modules will now issue C<"deprecated">-category
58warnings to alert you to this fact. To silence these deprecation warnings,
59install the modules in question from CPAN.
60
61Note that these are (with rare exceptions) fine modules that you are encouraged
62to continue to use. Their disinclusion from core primarily hinges on their
63necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
64not usually on concerns over their design.
65
66XXX Note that deprecated modules should be listed here even if they are listed
67as an updated module in the L</Modules and Pragmata> section.
68
69=over
70
71=item *
72
73...
74
75=back
76
77[ List each other deprecation as a =head2 entry ]
78
79=head1 Performance Enhancements
80
81XXX Changes which enhance performance without changing behaviour go here.
82There may well be none in a stable release.
83
84[ List each enhancement as a =item entry ]
85
86=over 4
87
88=item *
89
13b0f67d
DM
90Perl has a new copy-on-write mechanism that avoids the need to copy the
91internal string buffer when assigning from one scalar to another. This
92makes copying large strings appear much faster. Modifying one of the two
93(or more) strings after an assignment will force a copy internally. This
94makes it unnecessary to pass strings by reference for efficiency.
95
96This feature was already available in 5.18.0, but wasn't enabled by
97default. It is the default now, and so you no longer need build perl with
98the F<Configure> argument:
99
100 -Accflags=PERL_NEW_COPY_ON_WRITE
101
102It can be disabled (for now) in a perl build with:
103
104 -Accflags=PERL_NO_COW
583aa5c2
RS
105
106=back
5ed58cbd 107
e9912eaa 108=head1 Modules and Pragmata
5ed58cbd 109
583aa5c2
RS
110XXX All changes to installed files in F<cpan/>, F<dist/>, F<ext/> and F<lib/>
111go here. If Module::CoreList is updated, generate an initial draft of the
112following sections using F<Porting/corelist-perldelta.pl>, which prints stub
113entries to STDOUT. Results can be pasted in place of the '=head2' entries
114below. A paragraph summary for important changes should then be added by hand.
115In an ideal world, dual-life modules would have a F<Changes> file that could be
116cribbed.
117
118[ Within each section, list entries as a =item entry ]
119
120=head2 New Modules and Pragmata
121
122=over 4
123
124=item *
125
126XXX
127
128=back
129
e9912eaa 130=head2 Updated Modules and Pragmata
5ed58cbd 131
e9912eaa 132=over 4
5ed58cbd 133
e9912eaa 134=item *
5ed58cbd 135
dbd04185
NC
136Test::Harness has been upgraded from version 3.26 to 3.28
137
138Memory usage is dramatically reduced. t/harness now uses about 10% of the
139memory used by 3.26 and earlier.
140
141C<PERL5LIB> is always propagated to a test's C<@INC>, even under C<-T>.
583aa5c2 142
1fdd5e53
KW
143=item *
144
145Unicode::UCD has been upgraded from version 0.51 to 0.52.
146
147A function, L<Unicode::UCD/search_invlist()> is now available to do
148search an inversion list or map for a code point.
149
583aa5c2
RS
150=back
151
152=head2 Removed Modules and Pragmata
153
154=over 4
5ed58cbd 155
e9912eaa 156=item *
5ed58cbd 157
583aa5c2
RS
158XXX
159
160=back
161
162=head1 Documentation
163
164XXX Changes to files in F<pod/> go here. Consider grouping entries by
165file and be sure to link to the appropriate page, e.g. L<perlfunc>.
166
167=head2 New Documentation
168
169XXX Changes which create B<new> files in F<pod/> go here.
170
171=head3 L<XXX>
172
173XXX Description of the purpose of the new file here
174
175=head2 Changes to Existing Documentation
176
177XXX Changes which significantly change existing files in F<pod/> go here.
178However, any changes to F<pod/perldiag.pod> should go in the L</Diagnostics>
179section.
180
181=head3 L<XXX>
182
183=over 4
1993add8 184
e9912eaa 185=item *
ec985017 186
583aa5c2
RS
187XXX Description of the change here
188
189=back
190
191=head1 Diagnostics
192
193The following additions or changes have been made to diagnostic output,
194including warnings and fatal error messages. For the complete list of
195diagnostic messages, see L<perldiag>.
196
197XXX New or changed warnings emitted by the core's C<C> code go here. Also
198include any changes in L<perldiag> that reconcile it to the C<C> code.
199
200=head2 New Diagnostics
201
202XXX Newly added diagnostic messages go under here, separated into New Errors
203and New Warnings
204
205=head3 New Errors
206
207=over 4
71e6aba6
RS
208
209=item *
210
583aa5c2
RS
211XXX L<message|perldiag/"message">
212
213=back
214
215=head3 New Warnings
216
217=over 4
71e6aba6 218
d5f315e8
KW
219=item *
220
583aa5c2 221XXX L<message|perldiag/"message">
d5f315e8 222
337fb649 223=back
2426c394 224
583aa5c2 225=head2 Changes to Existing Diagnostics
e9912eaa 226
583aa5c2 227XXX Changes (i.e. rewording) of diagnostic messages go here
357b01df 228
583aa5c2 229=over 4
357b01df 230
583aa5c2 231=item *
357b01df 232
583aa5c2 233XXX Describe change here
357b01df 234
583aa5c2 235=back
357b01df 236
583aa5c2 237=head1 Utility Changes
357b01df 238
583aa5c2
RS
239XXX Changes to installed programs such as F<perlbug> and F<xsubpp> go here.
240Most of these are built within the directories F<utils> and F<x2p>.
357b01df 241
583aa5c2
RS
242[ List utility changes as a =head3 entry for each utility and =item
243entries for each change
244Use L<XXX> with program names to get proper documentation linking. ]
357b01df 245
583aa5c2 246=head3 L<XXX>
357b01df 247
583aa5c2 248=over 4
357b01df 249
583aa5c2 250=item *
357b01df 251
583aa5c2 252XXX
357b01df 253
583aa5c2
RS
254=back
255
256=head1 Configuration and Compilation
257
258XXX Changes to F<Configure>, F<installperl>, F<installman>, and analogous tools
259go here. Any other changes to the Perl build process should be listed here.
260However, any platform-specific changes should be listed in the
261L</Platform Support> section, instead.
262
263[ List changes as a =item entry ].
264
265=over 4
266
267=item *
268
269XXX
357b01df 270
e9912eaa 271=back
357b01df 272
583aa5c2
RS
273=head1 Testing
274
275XXX Any significant changes to the testing of a freshly built perl should be
276listed here. Changes which create B<new> files in F<t/> go here as do any
277large changes to the testing harness (e.g. when parallel testing was added).
278Changes to existing files in F<t/> aren't worth summarizing, although the bugs
279that they represent may be covered elsewhere.
280
281[ List each test improvement as a =item entry ]
282
283=over 4
284
285=item *
286
287XXX
288
289=back
290
291=head1 Platform Support
292
293XXX Any changes to platform support should be listed in the sections below.
294
295[ Within the sections, list each platform as a =item entry with specific
296changes as paragraphs below it. ]
297
298=head2 New Platforms
299
300XXX List any platforms that this version of perl compiles on, that previous
301versions did not. These will either be enabled by new files in the F<hints/>
302directories, or new subdirectories and F<README> files at the top level of the
303source tree.
304
305=over 4
306
307=item XXX-some-platform
308
309XXX
310
311=back
312
313=head2 Discontinued Platforms
314
315XXX List any platforms that this version of perl no longer compiles on.
316
317=over 4
318
319=item XXX-some-platform
357b01df 320
583aa5c2 321XXX
5ed58cbd 322
583aa5c2
RS
323=back
324
325=head2 Platform-Specific Notes
326
327XXX List any changes for specific platforms. This could include configuration
328and compilation changes or changes in portability/compatibility. However,
329changes within modules for platforms should generally be listed in the
330L</Modules and Pragmata> section.
331
332=over 4
333
7df6ffa3 334=item Mixed-endian platforms
583aa5c2 335
7df6ffa3
NC
336The code supporting C<pack> and C<unpack> operations on mixed endian
337platforms has been removed. We believe that Perl has long been unable to
338build on mixed endian architectures (such as PDP-11s), so we don't think
339that this change will affect any platforms which are able to build v5.18.0.
583aa5c2
RS
340
341=back
342
343=head1 Internal Changes
344
345XXX Changes which affect the interface available to C<XS> code go here. Other
346significant internal changes for future core maintainers should be noted as
347well.
348
349[ List each change as a =item entry ]
350
351=over 4
352
353=item *
354
13b0f67d
DM
355Perl's new copy-on-write mechanism (which is now enabled by default),
356allows any C<SvPOK> scalar to be automatically upgraded to a copy-on-write
357scalar when copied. A reference count on the string buffer is stored in
358the string buffer itself.
359
360For example:
361
362 $ perl -MDevel::Peek -e'$a="abc"; $b = $a; Dump $a; Dump $b'
363 SV = PV(0x260cd80) at 0x2620ad8
364 REFCNT = 1
365 FLAGS = (POK,IsCOW,pPOK)
366 PV = 0x2619bc0 "abc"\0
367 CUR = 3
368 LEN = 16
369 COW_REFCNT = 1
370 SV = PV(0x260ce30) at 0x2620b20
371 REFCNT = 1
372 FLAGS = (POK,IsCOW,pPOK)
373 PV = 0x2619bc0 "abc"\0
374 CUR = 3
375 LEN = 16
376 COW_REFCNT = 1
377
378Note that both scalars share the same PV buffer and have a COW_REFCNT
379greater than zero.
380
381This means that XS code which wishes to modify the C<SvPVX()> buffer of an
382SV should call C<SvPV_force()> or similar first, to ensure a valid (and
383unshared) buffer, and to call C<SvSETMAGIC()> afterwards. This in fact has
384always been the case (for example hash keys were already copy-on-write);
385this change just spreads the COW behaviour to a wider variety of SVs.
386
387One important difference is that before 5.18.0, shared hash-key scalars
388used to have the C<SvREADONLY> flag set; this is no longer the case.
389
390This new behaviour can still be disabled by running F<Configure> with
391B<-Accflags=-DPERL_NO_COW>. This option will probably be removed in Perl
3925.22.
393
394=item *
395
396C<PL_sawampersand> is now a constant. The switch this variable provided
397(to enable/disable the pre-match copy depending on whether C<$&> had been
398seen) has been removed and replaced with copy-on-write, eliminating a few
399bugs.
400
401The previous behaviour can still be enabled by running F<Configure> with
402B<-Accflags=-DPERL_SAWAMPERSAND>.
403
404=item *
405
7df6ffa3
NC
406The functions C<my_swap>, C<my_htonl> and C<my_ntohl> have been removed.
407It is unclear why these functions were ever marked as I<A>, part of the
408API. XS code can't call them directly, as it can't rely on them being
409compiled. Unsurprisingly, no code on CPAN references them.
583aa5c2
RS
410
411=back
412
413=head1 Selected Bug Fixes
414
415XXX Important bug fixes in the core language are summarized here. Bug fixes in
416files in F<ext/> and F<lib/> are best summarized in L</Modules and Pragmata>.
5ed58cbd 417
583aa5c2 418[ List each fix as a =item entry ]
32b79602 419
583aa5c2
RS
420=over 4
421
422=item *
423
c2a50ddb
NC
424The OP allocation code now returns correctly aligned memory in all cases
425for C<struct pmop>. Previously it could return memory only aligned to a
4264-byte boundary, which is not correct for an ithreads build with 64 bit IVs
427on some 32 bit platforms. Notably, this caused the build to fail completely
428on sparc GNU/Linux. [RT #118055]
583aa5c2 429
b019bbd2
NC
430=item *
431
432The debugger's C<man> command been fixed. It was broken in the v5.18.0
433release. The C<man> command is aliased to the names C<doc> and C<perldoc> -
434all now work again.
435
583aa5c2
RS
436=back
437
438=head1 Known Problems
439
440XXX Descriptions of platform agnostic bugs we know we can't fix go here. Any
441tests that had to be C<TODO>ed for the release would be noted here. Unfixed
442platform specific bugs also go here.
443
444[ List each fix as a =item entry ]
445
446=over 4
447
448=item *
449
450XXX
451
452=back
453
454=head1 Obituary
455
456XXX If any significant core contributor has died, we've added a short obituary
457here.
458
459=head1 Acknowledgements
a75569c0 460
583aa5c2 461XXX Generate this with:
e9912eaa 462
583aa5c2 463 perl Porting/acknowledgements.pl v5.19.1..HEAD
f5b73711 464
44691e6f
AB
465=head1 Reporting Bugs
466
e08634c5
SH
467If you find what you think is a bug, you might check the articles recently
468posted to the comp.lang.perl.misc newsgroup and the perl bug database at
469http://rt.perl.org/perlbug/ . There may also be information at
470http://www.perl.org/ , the Perl Home Page.
44691e6f 471
e08634c5
SH
472If you believe you have an unreported bug, please run the L<perlbug> program
473included with your release. Be sure to trim your bug down to a tiny but
474sufficient test case. Your bug report, along with the output of C<perl -V>,
475will be sent off to perlbug@perl.org to be analysed by the Perl porting team.
44691e6f
AB
476
477If the bug you are reporting has security implications, which make it
e08634c5
SH
478inappropriate to send to a publicly archived mailing list, then please send it
479to perl5-security-report@perl.org. This points to a closed subscription
480unarchived mailing list, which includes all the core committers, who will be
481able to help assess the impact of issues, figure out a resolution, and help
f9001595 482co-ordinate the release of patches to mitigate or fix the problem across all
e08634c5
SH
483platforms on which Perl is supported. Please only use this address for
484security issues in the Perl core, not for modules independently distributed on
485CPAN.
44691e6f
AB
486
487=head1 SEE ALSO
488
e08634c5
SH
489The F<Changes> file for an explanation of how to view exhaustive details on
490what changed.
44691e6f
AB
491
492The F<INSTALL> file for how to build Perl.
493
494The F<README> file for general stuff.
495
496The F<Artistic> and F<Copying> files for copyright information.
497
498=cut