(perl #131836) avoid a use-after-free after parsing a "sub" keyword
[perl.git] / Porting / README.pod
1 =head1 NAME
2
3 README.pod - README for the F<Porting/> directory in the Perl 5 core distribution.
4
5 =head1 FILES
6
7 =head2 F<acknowledgements.pl>
8
9 Generates the text which goes in the Acknowledgements section in
10 a perldelta. You pass in the previous version and it guesses the next
11 version, fetches information from the repository and outputs the
12 text.
13
14 =head2 F<add-package.pl>
15
16 Program to prepare dual-life distributions for insertion into the Perl 5
17 F<lib/> and F<t/> directories.  Now thought to be largely superseded.
18
19 =head2 F<bench.pl>
20
21 Do performance analysis on the code snippets in F<t/perf/benchmarks>.
22
23 =head2 F<bisect-example.sh>, F<bisect.pl> and F<bisect-runner.pl>
24
25 Use C<git bisect> to pinpoint changes.
26
27 =head2 F<bump-perl-version>
28
29 A utility to find, and optionally bump, references to the perl version
30 number in various files within the perl source.
31
32 =head2 F<check83.pl>
33
34 Performs pathname portability checks, including whether there are naming
35 conflicts when names are truncated to the DOSish, case-ignoring 8.3 format.
36
37 =head2 F<checkansi.pl>
38
39 Check source code for ANSI-C violations.
40
41 =head2 F<checkAUTHORS.pl>
42
43 Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date.
44
45 =head2 F<checkcfguse.pl>
46
47 Check where the symbols defined in the various F<config.sh>-clones
48 are being used.  VMS is probably not handled properly here.
49
50 =head2 F<checkcfgvar.pl>
51
52 Check that the various F<config.sh>-clones have (at least) all the same
53 symbols as the top-level F<config_h.SH> so that the (potentially) needed
54 symbols are not lagging after how F<Configure> thinks the world is laid out.
55 VMS is probably not handled properly here, due to their own rather elaborate
56 DCL scripting.
57
58 =head2 F<check-cpan-pollution>
59
60 Scans the commit logs for commits that are potentially, illegitimately
61 touching modules that are primarily maintained outside of the perl core.  Also
62 checks for commits that span multiple distributions in F<cpan/> or F<dist/>.
63 Makes sure that updated CPAN distributions also update
64 F<Porting/Maintainers.pl>, but otherwise ignores changes to that file (and
65 F<MANIFEST>).
66
67 =head2 F<checkpodencoding.pl>
68
69 Check if POD files contain non-ASCII without specifying
70 encoding. Run it as: C<perl Porting/checkpodencoding.pl>.
71
72 =head2 F<checkURL.pl>
73
74 Checks that all the URLs in the Perl source are valid.
75
76 =head2 F<checkVERSION.pl>
77
78 Used by F<t/porting/cmp_version.t> to ensure changed modules have had their
79 versions updated.
80
81 =head2 F<cherrymaint>
82
83 Command line tool to update cherrymaint; a tool for selecting commits from 
84 blead to cherry-pick into stable perl versions.
85
86 =head2 F<cmpVERSION.pl>
87
88 Compare the current Perl source tree and a given tag for modules that have
89 identical version numbers but different contents.
90
91 =head2 F<config_H>
92
93 This file is a sample F<config.h> file.  If you are unable to successfully run
94 F<Configure>, copy this file to F<config.h> and edit it to suit your system.
95
96 =head2 F<config_h.pl>
97
98 Used when importing changes from F<metaconfig>.  This script reorders
99 F<config_h.SH> after metaconfig.
100
101 =head2 F<config.sh>
102
103 This file is a sample F<config.sh> file.  F<config.sh> is normally
104 produced by running the F<Configure> script. It holds all the definitions
105 figured out by F<Configure>.  If you are unable to successfully run
106 F<Configure> on your system, copy this sample file to F<config.sh>
107 at the top of the perl source tree and edit it to suit your system.
108 Then propagate those values by running C<Configure -S>.  This sample
109 file is normally updated each time F<Configure> is updated.
110
111 =head2 F<core-cpan-diff>
112
113 Compare CPAN modules with their equivalent in core. 
114 Originally based on App::DualLivedDiff by Steffen Mueller.
115
116 =head2 F<corecpan.pl>
117
118 Reports, in a perl source tree, which dual-lived core modules have not the
119 same version than the corresponding module on CPAN.
120
121 =head2 F<corelist-diff>
122
123 Prints a table of differences between two Perl versions with respect to
124 modules included in the distribution.
125
126 =head2 F<corelist-perldelta.pl>
127
128 Generates a list of the module changes for the Perl you are currently
129 building.  Also generates a diff between the corelist sections of two
130 F<perldelta*> files.
131
132 =head2 F<corelist.pl>
133
134 Generates info for Module::CoreList from this perl tree.
135
136 =head2 F<deparse-skips.txt>
137
138 List of test files to ignore/skip for deparse tests.
139
140 =head2 F<epigraphs.pod>
141
142 List of Perl release epigraphs.
143
144 =head2 F<exec-bit.txt>
145
146 This file contains a list of files that F<makerel> will ensure get an
147 executable bit.
148
149 =head2 F<exercise_makedef.pl>
150
151 Brute force testing for F<makedef.pl>.
152
153 =head2 F<expand-macro.pl>
154
155 Expand C macros using the C preprocessor.
156
157 =head2 F<findrfuncs>
158
159 This script finds reentrant variants of functions used in an executable and
160 shared objects.
161
162 =head2 F<git-deltatool>
163
164 This script, a rough draft, aids in generating a perldelta file
165 from a series of git commits.
166
167 =head2 F<git-find-p4-change>
168
169 This script, given a Perforce change number, outputs the equivalent git commit
170 id.
171
172 =head2 F<git-make-p4-refs>
173
174 This script creates a tag for every p4raw-id.
175
176 =head2 F<GitUtils.pm>
177
178 This script contains the subroutine to generate a F<.patch file> for a
179 committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
180 digits which acts the internal unique identifier for this commit
181 (lilypond.org).  Related file: F<make_dot_patch.pl>
182
183 =head2 F<Glossary>
184
185 This file is built by F<metaconfig>. This file contains a description of all
186 the shell variables whose value is determined by the Configure script. 
187 It later gets incorporated into the pod for F<Config.pm>.
188
189 =head2 F<harness-timer-report.pl>
190
191 For analyzing the output of "env HARNESS_TIMER=1 make test", to find
192 outliers of test execution times.
193
194 =head2 F<how_to_write_a_perldelta.pod> 
195
196 This file contains a specification as to how to write a perldelta pod.
197 Related file: F<perldelta_template.pod>
198
199 =head2 F<leakfinder.pl>
200
201 This script executes every line in every file in the build directory and its
202 subdirectories to determine if the number of SVs goes up and reports it as a
203 leak to STDOUT.  WARNING! some harm could be done if a line contains something
204 similar to C<`rm *`>.
205
206 =head2 F<Maintainers>
207
208 This script shows information about the maintainers of core files/modules.
209
210 Related files: F<Maintainers.pl>, F<Maintainers.pm>
211
212 =head2 F<Maintainers.pl>
213
214 A package associating core files/modules with maintainers.  Related files:
215 F<Maintainers>, F<Maintainers.pm>
216
217 =head2 F<Maintainers.pm>
218
219 A package to search and show information about which core files/modules are
220 associated with maintainers.  Related files: F<Maintainers>, F<Maintainers.pl>
221
222 =head2 F<make_dot_patch.pl>
223
224 Generate a F<.patch> file to STDOUT for a commit ID specified on the
225 command-line.
226
227 =head2 F<makemeta>
228
229 This script creates F<META.yml> and F<META.json> files.
230
231 =head2 F<make_modlib_cpan.pl>
232
233 This script generates the list of registered CPAN sites in F<perlmodlib.PL>.
234
235 =head2 F<makerel>
236
237 This script builds a Perl release tarball.
238
239 =head2 F<make-rmg-checklist>
240
241 This script creates a release checklist as a simple HTML document.
242
243 =head2 F<make_snapshot.pl>
244
245 This script is a quick and dirty snapshot generator for the perl5.git.perl.org
246 web page to use to generate the snapshot files. 
247
248 =head2 F<manicheck>
249
250 This script outputs a list of files in F<MANIFEST> which don't exist and a
251 list of files that exist and aren't in F<MANIFEST>.
252
253 =head2 F<manifest_lib.pl>
254
255 This library provides functions used in checking and sorting the F<MANIFEST>.
256
257 =head2 F<manisort>
258
259 This script sorts the files in F<MANIFEST>.
260
261 =head2 F<new-perldelta.pl>
262
263 This script automates the process for creating perldelta.pl.
264
265 =head2 F<newtests-perldelta.pl>
266
267 This script outputs the added tests between the two versions of Perl.
268
269 =head2 F<perldelta_template.pod>
270
271 Template for F<perldelta>.
272
273 =head2 F<perlhist_calculate.pl>
274
275 Generates info for F<perlhist> from this perl tree.
276
277 =head2 F<pod_lib.pl>
278
279 When C<require>d into other programs in the Perl 5 core
280 distribution, provides functions useful during testing.
281
282 =head2 F<pod_rules.pl>
283
284 Generate the sections of files listed in C<%Targets> from F<pod/perl.pod>.
285 Mostly these are rules in Makefiles.
286
287  --verbose gives slightly more output
288  --build-all tries to build everything
289  --build-foo updates foo as follows
290  --showfiles shows the files to be changed
291  --test exit if perl.pod, MANIFEST are consistent, and regenerated
292    files are up to date, die otherwise.
293
294 =head2 F<podtidy>
295
296 Applies F<podtidy> to a file.
297
298 =head2 F<pumpkin.pod>
299
300 Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl.
301 Many of these are out of date or superseded by other documents in 
302 this directory.
303
304 =head2 F<README.pod>
305
306 This file.  An exhaustive list of the contents of the F<Porting/>
307 directory along with a description of each file.
308 The test F<t/porting/readme.t> ensures that this lists every file
309 and that every file is listed.
310
311 =head2 F<README.y2038>
312
313 The y2038 implementation for perl. This is an implementation of POSIX time.h
314 which solves the year 2038 bug on systems where time_t is only 32 bits.  It is
315 implemented in bog-standard ANSI C. The latest version can be found at
316 L<http://y2038.googlecode.com/>.
317
318 =head2 F<release_announcement_template.txt>
319
320 Release announcement for minor releasements of the 5.19 development series.
321
322 =head2 F<release_managers_guide.pod>
323
324 Releasing a new version of perl 5.x. Note that things change at each release,
325 so there may be new things not covered here, or tools may need updating.
326
327 =head2 F<release_schedule.pod>
328
329 This schedule lists the projected or historical development and release
330 schedules for the next, current and previous stable versions of Perl. Dates
331 with all question marks will only be releases if deemed necessary by the
332 Pumpking.
333
334 =head2 F<rt_list_patches>
335
336 Shell script to list patches in RT.
337
338 =head2 F<sort_perldiag.pl>
339
340 This is a script for sorting the warning and error messages in
341 F<perldiag.pod>.  POD formatting, printf-style escapes, non-letter characters,
342 and case are ignored, as explained in L<perldiag>.
343
344 =head2 F<sync-with-cpan>
345
346 Script to help out with syncing cpan distros.
347
348 =head2 F<timecheck2.c>
349
350 A little program to test the limits of your system's time functions. See
351 F<Porting/README.y2038> for details.
352
353 =head2 F<timecheck.c>
354
355 A helper tool for perl's 2038 support See F<Porting/README.y2038> for details.
356
357 =head2 F<todo.pod>
358
359 This is a list of wishes for Perl. The most up-to-date version of this file is
360 at L<http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/Porting/todo.pod>.
361 The tasks we think are smaller or easier are listed first.  Anyone is welcome
362 to work on any of these, but it's a good idea to first contact
363 I<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
364 any previous attempts.
365
366 =head2 F<valgrindpp.pl>
367
368 A post-processor for C<make test.valgrind>.  F<valgrindpp.pl> is a
369 post-processor for F<.valgrind> files created during C<make test.valgrind>. It
370 collects all these files, extracts most of the information and produces a
371 significantly shorter summary of all detected memory access errors and memory
372 leaks.
373
374 =cut
375