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<bisect-example.sh>, F<bisect-runner.pl> and F<bisect.pl>
21 Use C<git bisect> to pinpoint changes.
23 =head2 F<bump-perl-version>
25 A utility to find, and optionally bump, references to the perl version
26 number in various files within the perl source.
30 Performs pathname portability checks, including whether there are naming
31 conflicts when names are truncated to the DOSish, case-ignoring 8.3 format.
33 =head2 F<checkAUTHORS.pl>
35 Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date.
39 Checks that all the URLs in the Perl source are valid.
41 =head2 F<checkVERSION.pl>
43 Used by F<t/porting/cmp_version.t> to ensure changed modules have had their
46 =head2 F<checkansi.pl>
48 Check source code for ANSI-C violations.
50 =head2 F<checkcfgvar.pl>
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
58 =head2 F<check-cpan-pollution>
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
67 =head2 F<checkpodencoding.pl>
69 Check if POD files contain non-ASCII without specifying
70 encoding. Run it as: C<perl Porting/checkpodencoding.pl>.
74 Command line tool to update cherrymaint; a tool for selecting commits from
75 blead to cherry-pick into stable perl versions.
77 =head2 F<cmpVERSION.pl>
79 Compare the current Perl source tree and a given tag for modules that have
80 identical version numbers but different contents.
84 This file is a sample F<config.h> file. If you are unable to successfully run
85 F<Configure>, copy this file to F<config.h> and edit it to suit your system.
89 Used when importing changes from F<metaconfig>. This script reorders
90 F<config_h.SH> after metaconfig.
94 This file is a sample F<config.sh> file. F<config.sh> is normally
95 produced by running the F<Configure> script. It holds all the definitions
96 figured out by F<Configure>. If you are unable to successfully run
97 F<Configure> on your system, copy this sample file to F<config.sh>
98 at the top of the perl source tree and edit it to suit your system.
99 Then propagate those values by running C<Configure -S>. This sample
100 file is normally updated each time F<Configure> is updated.
102 =head2 F<core-cpan-diff>
104 Compare CPAN modules with their equivalent in core.
105 Originally based on App::DualLivedDiff by Steffen Mueller.
107 =head2 F<corecpan.pl>
109 Reports, in a perl source tree, which dual-lived core modules have not the
110 same version than the corresponding module on CPAN.
112 =head2 F<corelist-diff>
114 Prints a table of differences between two Perl versions with respect to
115 modules included in the distribution.
117 =head2 F<corelist.pl>
119 Generates info for Module::CoreList from this perl tree.
121 =head2 F<corelist-perldelta.pl>
123 Generates a list of the module changes for the Perl you are currently
124 building. Also generates a diff between the corelist sections of two
127 =head2 F<epigraphs.pod>
129 List of Perl release epigraphs.
131 =head2 F<exec-bit.txt>
133 This file contains a list of files that F<makerel> will ensure get an
136 =head2 F<exercise_makedef.pl>
138 Brute force testing for F<makedef.pl>.
140 =head2 F<expand-macro.pl>
142 Expand C macros using the C preprocessor.
146 This script finds reentrant variants of functions used in an executable and
149 =head2 F<GitUtils.pm>
151 This script contains the subroutine to generate a F<.patch file> for a
152 committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
153 digits which acts the internal unique identifier for this commit
154 (lilypond.org). Related file: F<make_dot_patch.pl>
156 =head2 F<git-deltatool>
158 This script, a rough draft, aids in generating a perldelta file
159 from a series of git commits.
161 =head2 F<git-find-p4-change>
163 This script, given a Perforce change number, outputs the equivalent git commit
166 =head2 F<git-make-p4-refs>
168 This script creates a tag for every p4raw-id.
172 This file is built by F<metaconfig>. This file contains a description of all
173 the shell variables whose value is determined by the Configure script.
174 It later gets incorporated into the pod for F<Config.pm>.
176 =head2 F<how_to_write_a_perldelta.pod>
178 This file contains a specification as to how to write a perldelta pod.
179 Related file: F<perldelta_template.pod>
181 =head2 F<leakfinder.pl>
183 This script executes every line in every file in the build directory and its
184 subdirectories to determine if the number of SVs goes up and reports it as a
185 leak to STDOUT. WARNING! some harm could be done if a line contains something
186 similar to C<`rm *`>.
188 =head2 F<Maintainers>
190 This script shows information about the maintainers of core files/modules.
192 Related files: F<Maintainers.pl>, F<Maintainers.pm>
194 =head2 F<Maintainers.pl>
196 A package associating core files/modules with maintainers. Related files:
197 F<Maintainers>, F<Maintainers.pm>
199 =head2 F<Maintainers.pm>
201 A package to search and show information about which core files/modules are
202 associated with maintainers. Related files: F<Maintainers>, F<Maintainers.pl>
204 =head2 F<make-rmg-checklist>
206 This script creates a release checklist as a simple HTML document.
208 =head2 F<make_dot_patch.pl>
210 Generate a F<.patch> file to STDOUT for a commit ID specified on the
213 =head2 F<make_modlib_cpan.pl>
215 This script generates the list of registered CPAN sites in F<perlmodlib.PL>.
217 =head2 F<make_snapshot.pl>
219 This script is a quick and dirty snapshot generator for the perl5.git.perl.org
220 web page to use to generate the snapshot files.
224 This script creates F<META.yml> and F<META.json> files.
228 This script builds a Perl release tarball.
232 This script outputs a list of files in F<MANIFEST> which don't exist and a
233 list of files that exist and aren't in F<MANIFEST>.
237 This script sorts the files in F<MANIFEST>.
239 =head2 F<new-perldelta.pl>
241 This script automates the process for creating perldelta.pl.
243 =head2 F<newtests-perldelta.pl>
245 This script outputs the added tests between the two versions of Perl.
247 =head2 F<perldelta_template.pod>
249 Template for F<perldelta>.
251 =head2 F<perlhist_calculate.pl>
253 Generates info for F<perlhist> from this perl tree.
257 When C<require>d into other programs in the Perl 5 core
258 distribution, provides functions useful during testing.
260 =head2 F<pod_rules.pl>
262 Generate the sections of files listed in C<%Targets> from F<pod/perl.pod>.
263 Mostly these are rules in Makefiles.
265 --verbose gives slightly more output
266 --build-all tries to build everything
267 --build-foo updates foo as follows
268 --showfiles shows the files to be changed
269 --test exit if perl.pod, MANIFEST are consistent, and regenerated
270 files are up to date, die otherwise.
274 Applies F<podtidy> to a file.
276 =head2 F<pumpkin.pod>
278 Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl.
279 Many of these are out of date or superseded by other documents in
282 =head2 F<README.y2038>
284 The y2038 implementation for perl. This is an implementation of POSIX time.h
285 which solves the year 2038 bug on systems where time_t is only 32 bits. It is
286 implemented in bog-standard ANSI C. The latest version can be found at
287 L<http://y2038.googlecode.com/>.
289 =head2 F<release_announcement_template.txt>
291 Release announcement for minor releasements of the 5.19 development series.
293 =head2 F<release_managers_guide.pod>
295 Releasing a new version of perl 5.x. Note that things change at each release,
296 so there may be new things not covered here, or tools may need updating.
298 =head2 F<release_schedule.pod>
300 This schedule lists the projected or historical development and release
301 schedules for the next, current and previous stable versions of Perl. Dates
302 with all question marks will only be releases if deemed necessary by the
305 =head2 F<rt_list_patches>
307 Shell script to list patches in RT.
309 =head2 F<sort_perldiag.pl>
311 This is a script for sorting the warning and error messages in
312 F<perldiag.pod>. POD formatting, printf-style escapes, non-letter characters,
313 and case are ignored, as explained in L<perldiag>.
315 =head2 F<testall.atom>
317 Test suite profiling on Tru 64.
321 Script for cleaning out the "known noise" from Third Degree reports: either
322 noise caused by F<libc> itself, or F<Perl_yyparse> leaks.
326 A helper tool for perl's 2038 support. See F<Porting/README.y2038> for details.
328 =head2 F<timecheck2.c>
330 A little program to test the limits of your system's time functions. See
331 F<Porting/README.y2038> for details.
333 =head2 F<timecheck.c>
335 A helper tool for perl's 2038 support See F<Porting/README.y2038> for details.
339 This is a list of wishes for Perl. The most up-to-date version of this file is
340 at L<http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/Porting/todo.pod>.
341 The tasks we think are smaller or easier are listed first. Anyone is welcome
342 to work on any of these, but it's a good idea to first contact
343 F<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
344 any previous attempts.
346 =head2 F<valgrindpp.pl>
348 A post-processor for C<make test.valgrind>. F<valgrindpp.pl> is a
349 post-processor for F<.valgrind> files created during C<make test.valgrind>. It
350 collects all these files, extracts most of the information and produces a
351 significantly shorter summary of all detected memory access errors and memory