Commit | Line | Data |
---|---|---|
7ad311ab JK |
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 | ||
9e7973fa DM |
19 | =head2 F<bench.pl> |
20 | ||
21 | Do performance analysis on the code snippets in F<t/perf/benchmarks>. | |
22 | ||
9bd30288 | 23 | =head2 F<bisect-example.sh>, F<bisect.pl> and F<bisect-runner.pl> |
7ad311ab JK |
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 | ||
7ad311ab JK |
37 | =head2 F<checkansi.pl> |
38 | ||
39 | Check source code for ANSI-C violations. | |
40 | ||
9bd30288 BG |
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 | ||
95318fb6 JH |
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 | ||
7ad311ab JK |
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 | ||
9bd30288 BG |
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 | ||
7ad311ab JK |
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 | ||
3b2d1478 AD |
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. | |
7ad311ab JK |
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 | ||
7ad311ab JK |
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 | ||
9bd30288 BG |
132 | =head2 F<corelist.pl> |
133 | ||
134 | Generates info for Module::CoreList from this perl tree. | |
135 | ||
2722144b MH |
136 | =head2 F<deparse-skips.txt> |
137 | ||
138 | List of test files to ignore/skip for deparse tests. | |
139 | ||
7ad311ab JK |
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 | ||
7ad311ab JK |
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 | ||
9bd30288 BG |
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 | ||
7ad311ab JK |
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. | |
3b2d1478 | 187 | It later gets incorporated into the pod for F<Config.pm>. |
7ad311ab | 188 | |
87af8d55 JH |
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 | ||
7ad311ab JK |
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 | ||
7ad311ab JK |
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 | ||
9bd30288 BG |
227 | =head2 F<makemeta> |
228 | ||
229 | This script creates F<META.yml> and F<META.json> files. | |
230 | ||
7ad311ab JK |
231 | =head2 F<make_modlib_cpan.pl> |
232 | ||
233 | This script generates the list of registered CPAN sites in F<perlmodlib.PL>. | |
234 | ||
9bd30288 | 235 | =head2 F<makerel> |
7ad311ab | 236 | |
9bd30288 | 237 | This script builds a Perl release tarball. |
7ad311ab | 238 | |
9bd30288 | 239 | =head2 F<make-rmg-checklist> |
7ad311ab | 240 | |
9bd30288 | 241 | This script creates a release checklist as a simple HTML document. |
7ad311ab | 242 | |
9bd30288 | 243 | =head2 F<make_snapshot.pl> |
7ad311ab | 244 | |
9bd30288 BG |
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. | |
7ad311ab JK |
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 | ||
4a591814 AC |
253 | =head2 F<manifest_lib.pl> |
254 | ||
255 | This library provides functions used in checking and sorting the F<MANIFEST>. | |
256 | ||
7ad311ab JK |
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. | |
20a5039a | 301 | Many of these are out of date or superseded by other documents in |
3b2d1478 | 302 | this directory. |
7ad311ab | 303 | |
9bd30288 BG |
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 | ||
7ad311ab JK |
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 | ||
c5fb089a | 320 | Release announcement for minor releasements of the 5.19 development series. |
7ad311ab JK |
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 | ||
9bd30288 BG |
344 | =head2 F<sync-with-cpan> |
345 | ||
346 | Script to help out with syncing cpan distros. | |
347 | ||
7ad311ab JK |
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 | |
9bd30288 | 363 | I<perl5-porters@perl.org> to avoid duplication of effort, and to learn from |
7ad311ab JK |
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 |