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