3 README.pod - README for the F<Porting/> directory in the Perl 5 core distribution.
7 =head2 F<acknowledgements.pl>
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
14 =head2 F<add-package.pl>
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.
19 =head2 F<add-pod-file>
21 Program to facilitate addition of new F<.pod> files to F<pod/>.
25 Do performance analysis on the code snippets in F<t/perf/benchmarks>.
27 =head2 F<bisect-example.sh>, F<bisect.pl> and F<bisect-runner.pl>
29 Use C<git bisect> to pinpoint changes.
31 =head2 F<bump-perl-version>
33 A utility to find, and optionally bump, references to the perl version
34 number in various files within the perl source.
38 Performs pathname portability checks, including whether there are naming
39 conflicts when names are truncated to the DOSish, case-ignoring 8.3 format.
41 =head2 F<checkansi.pl>
43 Check source code for ANSI-C violations.
45 =head2 F<checkAUTHORS.pl>
47 Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date.
49 =head2 F<checkcfguse.pl>
51 Check where the symbols defined in the various F<config.sh>-clones
52 are being used. VMS is probably not handled properly here.
54 =head2 F<checkcfgvar.pl>
56 Check that the various F<config.sh>-clones have (at least) all the same
57 symbols as the top-level F<config_h.SH> so that the (potentially) needed
58 symbols are not lagging after how F<Configure> thinks the world is laid out.
59 VMS is probably not handled properly here, due to their own rather elaborate
62 =head2 F<check-cpan-pollution>
64 Scans the commit logs for commits that are potentially, illegitimately
65 touching modules that are primarily maintained outside of the perl core. Also
66 checks for commits that span multiple distributions in F<cpan/> or F<dist/>.
67 Makes sure that updated CPAN distributions also update
68 F<Porting/Maintainers.pl>, but otherwise ignores changes to that file (and
71 =head2 F<checkpodencoding.pl>
73 Check if POD files contain non-ASCII without specifying
74 encoding. Run it as: C<perl Porting/checkpodencoding.pl>.
78 Checks that all the URLs in the Perl source are valid.
80 =head2 F<checkVERSION.pl>
82 Used by F<t/porting/cmp_version.t> to ensure changed modules have had their
85 =head2 F<cmpVERSION.pl>
87 Compare the current Perl source tree and a given tag for modules that have
88 identical version numbers but different contents.
92 This file is a sample F<config.h> file. If you are unable to successfully run
93 F<Configure>, copy this file to F<config.h> and edit it to suit your system.
97 Used when importing changes from F<metaconfig>. This script reorders
98 F<config_h.SH> after metaconfig.
102 This file is a sample F<config.sh> file. F<config.sh> is normally
103 produced by running the F<Configure> script. It holds all the definitions
104 figured out by F<Configure>. If you are unable to successfully run
105 F<Configure> on your system, copy this sample file to F<config.sh>
106 at the top of the perl source tree and edit it to suit your system.
107 Then propagate those values by running C<Configure -S>. This sample
108 file is normally updated each time F<Configure> is updated.
110 =head2 F<core-cpan-diff>
112 Compare CPAN modules with their equivalent in core.
113 Originally based on App::DualLivedDiff by Steffen Mueller.
115 =head2 F<corecpan.pl>
117 Reports, in a perl source tree, which dual-lived core modules have not the
118 same version than the corresponding module on CPAN.
120 =head2 F<corelist-diff>
122 Prints a table of differences between two Perl versions with respect to
123 modules included in the distribution.
125 =head2 F<corelist-perldelta.pl>
127 Generates a list of the module changes for the Perl you are currently
128 building. Also generates a diff between the corelist sections of two
131 =head2 F<corelist.pl>
133 Generates info for Module::CoreList from this perl tree.
135 =head2 F<deparse-skips.txt>
137 List of test files to ignore/skip for deparse tests.
139 =head2 F<docs-team-charter.pod>
141 The charter of the Perl Documentation Team
143 =head2 F<epigraphs.pod>
145 List of Perl release epigraphs.
147 =head2 F<exec-bit.txt>
149 This file contains a list of files that F<makerel> will ensure get an
152 =head2 F<exercise_makedef.pl>
154 Brute force testing for F<makedef.pl>.
156 =head2 F<expand-macro.pl>
158 Expand C macros using the C preprocessor.
162 This script finds reentrant variants of functions used in an executable and
165 =head2 F<git-deltatool>
167 This script, a rough draft, aids in generating a perldelta file
168 from a series of git commits.
170 =head2 F<git-find-p4-change>
172 This script, given a Perforce change number, outputs the equivalent git commit
175 =head2 F<git-make-p4-refs>
177 This script creates a tag for every p4raw-id.
179 =head2 F<GitUtils.pm>
181 This script contains the subroutine to generate a F<.patch file> for a
182 committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
183 digits which acts the internal unique identifier for this commit
184 (lilypond.org). Related file: F<make_dot_patch.pl>
188 This file is built by F<metaconfig>. This file contains a description of all
189 the shell variables whose value is determined by the Configure script.
190 It later gets incorporated into the pod for F<Config.pm>.
192 =head2 F<harness-timer-report.pl>
194 For analyzing the output of "env HARNESS_TIMER=1 make test", to find
195 outliers of test execution times.
197 =head2 F<how_to_write_a_perldelta.pod>
199 This file contains a specification as to how to write a perldelta pod.
200 Related file: F<perldelta_template.pod>
202 =head2 F<leakfinder.pl>
204 This script executes every line in every file in the build directory and its
205 subdirectories to determine if the number of SVs goes up and reports it as a
206 leak to STDOUT. WARNING! some harm could be done if a line contains something
207 similar to C<`rm *`>.
209 =head2 F<Maintainers>
211 This script shows information about the maintainers of core files/modules.
213 Related files: F<Maintainers.pl>, F<Maintainers.pm>
215 =head2 F<Maintainers.pl>
217 A package associating core files/modules with maintainers. Related files:
218 F<Maintainers>, F<Maintainers.pm>
220 =head2 F<Maintainers.pm>
222 A package to search and show information about which core files/modules are
223 associated with maintainers. Related files: F<Maintainers>, F<Maintainers.pl>
225 =head2 F<make_dot_patch.pl>
227 Generate a F<.patch> file to STDOUT for a commit ID specified on the
232 This script creates F<META.yml> and F<META.json> files.
236 This script builds a Perl release tarball.
238 =head2 F<make-rmg-checklist>
240 This script creates a release checklist as a simple HTML document.
242 =head2 F<make_snapshot.pl>
244 This script is a quick and dirty snapshot generator for the perl5.git.perl.org
245 web page to use to generate the snapshot files.
249 This script outputs a list of files in F<MANIFEST> which don't exist and a
250 list of files that exist and aren't in F<MANIFEST>.
252 =head2 F<manifest_lib.pl>
254 This library provides functions used in checking and sorting the F<MANIFEST>.
258 This script sorts the files in F<MANIFEST>.
262 This script regenerates F<Porting/config.sh> and F<Porting/config_H>.
264 =head2 F<new-perldelta.pl>
266 This script automates the process for creating perldelta.pl.
268 =head2 F<newtests-perldelta.pl>
270 This script outputs the added tests between the two versions of Perl.
272 =head2 F<perldelta_template.pod>
274 Template for F<perldelta>.
276 =head2 F<perlhist_calculate.pl>
278 Generates info for F<perlhist> from this perl tree.
282 When C<require>d into other programs in the Perl 5 core
283 distribution, provides functions useful during testing.
285 =head2 F<pod_rules.pl>
287 Generate the sections of files listed in C<%Targets> from F<pod/perl.pod>.
288 Mostly these are rules in Makefiles.
290 --verbose gives slightly more output
291 --build-all tries to build everything
292 --build-foo updates foo as follows
293 --showfiles shows the files to be changed
294 --test exit if perl.pod, MANIFEST are consistent, and regenerated
295 files are up to date, die otherwise.
299 Applies F<podtidy> to a file.
301 =head2 F<pumpkin.pod>
303 Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl.
304 Many of these are out of date or superseded by other documents in
309 This file. An exhaustive list of the contents of the F<Porting/>
310 directory along with a description of each file.
311 The test F<t/porting/readme.t> ensures that this lists every file
312 and that every file is listed.
314 =head2 F<README.y2038>
316 The y2038 implementation for perl. This is an implementation of POSIX time.h
317 which solves the year 2038 bug on systems where time_t is only 32 bits. It is
318 implemented in bog-standard ANSI C. The latest version can be found at
319 L<https://github.com/evalEmpire/y2038>.
321 =head2 F<release_announcement_template.txt>
323 Release announcement for minor releasements of the 5.19 development series.
325 =head2 F<release_managers_guide.pod>
327 Releasing a new version of perl 5.x. Note that things change at each release,
328 so there may be new things not covered here, or tools may need updating.
330 =head2 F<release_schedule.pod>
332 This schedule lists the projected or historical development and release
333 schedules for the next, current and previous stable versions of Perl. Dates
334 with all question marks will only be releases if deemed necessary by the
337 =head2 F<rt_list_patches>
339 Shell script to list patches in RT.
341 =head1 F<security_template.pod>
343 Template to guide writers of a perl 5 security vulnerability
346 =head2 F<sort_perldiag.pl>
348 This is a script for sorting the warning and error messages in
349 F<perldiag.pod>. POD formatting, printf-style escapes, non-letter characters,
350 and case are ignored, as explained in L<perldiag>.
352 =head2 F<sync-with-cpan>
354 Script to help out with syncing cpan distros.
356 =head2 F<timecheck2.c>
358 A little program to test the limits of your system's time functions. See
359 F<Porting/README.y2038> for details.
361 =head2 F<timecheck.c>
363 A helper tool for perl's 2038 support See F<Porting/README.y2038> for details.
367 This is a list of wishes for Perl. The most up-to-date version of this file is
368 at L<https://github.com/Perl/perl5/blob/blead/Porting/todo.pod>.
369 The tasks we think are smaller or easier are listed first. Anyone is welcome
370 to work on any of these, but it's a good idea to first contact
371 I<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
372 any previous attempts.
374 =head2 F<valgrindpp.pl>
376 A post-processor for C<make test.valgrind>. F<valgrindpp.pl> is a
377 post-processor for F<.valgrind> files created during C<make test.valgrind>. It
378 collects all these files, extracts most of the information and produces a
379 significantly shorter summary of all detected memory access errors and memory
382 =head2 F<vote_admin_guide.pod>
384 Guide for Vote Administrators for running Steering Council elections.