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 | ||
36 | =head2 F<check83.pl> | |
37 | ||
38 | Performs pathname portability checks, including whether there are naming | |
39 | conflicts when names are truncated to the DOSish, case-ignoring 8.3 format. | |
40 | ||
7ad311ab JK |
41 | =head2 F<checkansi.pl> |
42 | ||
43 | Check source code for ANSI-C violations. | |
44 | ||
9bd30288 BG |
45 | =head2 F<checkAUTHORS.pl> |
46 | ||
47 | Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date. | |
48 | ||
95318fb6 JH |
49 | =head2 F<checkcfguse.pl> |
50 | ||
51 | Check where the symbols defined in the various F<config.sh>-clones | |
52 | are being used. VMS is probably not handled properly here. | |
53 | ||
7ad311ab JK |
54 | =head2 F<checkcfgvar.pl> |
55 | ||
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 | |
60 | DCL scripting. | |
61 | ||
62 | =head2 F<check-cpan-pollution> | |
63 | ||
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 | |
69 | F<MANIFEST>). | |
70 | ||
71 | =head2 F<checkpodencoding.pl> | |
72 | ||
73 | Check if POD files contain non-ASCII without specifying | |
74 | encoding. Run it as: C<perl Porting/checkpodencoding.pl>. | |
75 | ||
9bd30288 BG |
76 | =head2 F<checkURL.pl> |
77 | ||
78 | Checks that all the URLs in the Perl source are valid. | |
79 | ||
80 | =head2 F<checkVERSION.pl> | |
81 | ||
82 | Used by F<t/porting/cmp_version.t> to ensure changed modules have had their | |
83 | versions updated. | |
84 | ||
7ad311ab JK |
85 | =head2 F<cmpVERSION.pl> |
86 | ||
87 | Compare the current Perl source tree and a given tag for modules that have | |
88 | identical version numbers but different contents. | |
89 | ||
90 | =head2 F<config_H> | |
91 | ||
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. | |
94 | ||
95 | =head2 F<config_h.pl> | |
96 | ||
97 | Used when importing changes from F<metaconfig>. This script reorders | |
98 | F<config_h.SH> after metaconfig. | |
99 | ||
100 | =head2 F<config.sh> | |
101 | ||
3b2d1478 AD |
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. | |
7ad311ab JK |
109 | |
110 | =head2 F<core-cpan-diff> | |
111 | ||
112 | Compare CPAN modules with their equivalent in core. | |
113 | Originally based on App::DualLivedDiff by Steffen Mueller. | |
114 | ||
115 | =head2 F<corecpan.pl> | |
116 | ||
117 | Reports, in a perl source tree, which dual-lived core modules have not the | |
118 | same version than the corresponding module on CPAN. | |
119 | ||
120 | =head2 F<corelist-diff> | |
121 | ||
122 | Prints a table of differences between two Perl versions with respect to | |
123 | modules included in the distribution. | |
124 | ||
7ad311ab JK |
125 | =head2 F<corelist-perldelta.pl> |
126 | ||
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 | |
129 | F<perldelta*> files. | |
130 | ||
9bd30288 BG |
131 | =head2 F<corelist.pl> |
132 | ||
133 | Generates info for Module::CoreList from this perl tree. | |
134 | ||
2722144b MH |
135 | =head2 F<deparse-skips.txt> |
136 | ||
137 | List of test files to ignore/skip for deparse tests. | |
138 | ||
c3e80dec RS |
139 | =head2 F<docs-team-charter.pod> |
140 | ||
141 | The charter of the Perl Documentation Team | |
142 | ||
7ad311ab JK |
143 | =head2 F<epigraphs.pod> |
144 | ||
145 | List of Perl release epigraphs. | |
146 | ||
147 | =head2 F<exec-bit.txt> | |
148 | ||
149 | This file contains a list of files that F<makerel> will ensure get an | |
150 | executable bit. | |
151 | ||
152 | =head2 F<exercise_makedef.pl> | |
153 | ||
154 | Brute force testing for F<makedef.pl>. | |
155 | ||
156 | =head2 F<expand-macro.pl> | |
157 | ||
158 | Expand C macros using the C preprocessor. | |
159 | ||
160 | =head2 F<findrfuncs> | |
161 | ||
162 | This script finds reentrant variants of functions used in an executable and | |
163 | shared objects. | |
164 | ||
7ad311ab JK |
165 | =head2 F<git-deltatool> |
166 | ||
167 | This script, a rough draft, aids in generating a perldelta file | |
168 | from a series of git commits. | |
169 | ||
170 | =head2 F<git-find-p4-change> | |
171 | ||
172 | This script, given a Perforce change number, outputs the equivalent git commit | |
173 | id. | |
174 | ||
175 | =head2 F<git-make-p4-refs> | |
176 | ||
177 | This script creates a tag for every p4raw-id. | |
178 | ||
9bd30288 BG |
179 | =head2 F<GitUtils.pm> |
180 | ||
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> | |
185 | ||
7ad311ab JK |
186 | =head2 F<Glossary> |
187 | ||
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. | |
3b2d1478 | 190 | It later gets incorporated into the pod for F<Config.pm>. |
7ad311ab | 191 | |
87af8d55 JH |
192 | =head2 F<harness-timer-report.pl> |
193 | ||
194 | For analyzing the output of "env HARNESS_TIMER=1 make test", to find | |
195 | outliers of test execution times. | |
196 | ||
7ad311ab JK |
197 | =head2 F<how_to_write_a_perldelta.pod> |
198 | ||
199 | This file contains a specification as to how to write a perldelta pod. | |
200 | Related file: F<perldelta_template.pod> | |
201 | ||
202 | =head2 F<leakfinder.pl> | |
203 | ||
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 *`>. | |
208 | ||
209 | =head2 F<Maintainers> | |
210 | ||
211 | This script shows information about the maintainers of core files/modules. | |
212 | ||
213 | Related files: F<Maintainers.pl>, F<Maintainers.pm> | |
214 | ||
215 | =head2 F<Maintainers.pl> | |
216 | ||
217 | A package associating core files/modules with maintainers. Related files: | |
218 | F<Maintainers>, F<Maintainers.pm> | |
219 | ||
220 | =head2 F<Maintainers.pm> | |
221 | ||
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> | |
224 | ||
7ad311ab JK |
225 | =head2 F<make_dot_patch.pl> |
226 | ||
227 | Generate a F<.patch> file to STDOUT for a commit ID specified on the | |
228 | command-line. | |
229 | ||
9bd30288 BG |
230 | =head2 F<makemeta> |
231 | ||
232 | This script creates F<META.yml> and F<META.json> files. | |
233 | ||
9bd30288 | 234 | =head2 F<makerel> |
7ad311ab | 235 | |
9bd30288 | 236 | This script builds a Perl release tarball. |
7ad311ab | 237 | |
9bd30288 | 238 | =head2 F<make-rmg-checklist> |
7ad311ab | 239 | |
9bd30288 | 240 | This script creates a release checklist as a simple HTML document. |
7ad311ab | 241 | |
9bd30288 | 242 | =head2 F<make_snapshot.pl> |
7ad311ab | 243 | |
9bd30288 BG |
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. | |
7ad311ab JK |
246 | |
247 | =head2 F<manicheck> | |
248 | ||
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>. | |
251 | ||
4a591814 AC |
252 | =head2 F<manifest_lib.pl> |
253 | ||
254 | This library provides functions used in checking and sorting the F<MANIFEST>. | |
255 | ||
7ad311ab JK |
256 | =head2 F<manisort> |
257 | ||
258 | This script sorts the files in F<MANIFEST>. | |
259 | ||
9f8eb2ef DH |
260 | =head2 F<mksample> |
261 | ||
262 | This script regenerates F<Porting/config.sh> and F<Porting/config_H>. | |
263 | ||
7ad311ab JK |
264 | =head2 F<new-perldelta.pl> |
265 | ||
266 | This script automates the process for creating perldelta.pl. | |
267 | ||
268 | =head2 F<newtests-perldelta.pl> | |
269 | ||
270 | This script outputs the added tests between the two versions of Perl. | |
271 | ||
272 | =head2 F<perldelta_template.pod> | |
273 | ||
274 | Template for F<perldelta>. | |
275 | ||
276 | =head2 F<perlhist_calculate.pl> | |
277 | ||
278 | Generates info for F<perlhist> from this perl tree. | |
279 | ||
280 | =head2 F<pod_lib.pl> | |
281 | ||
282 | When C<require>d into other programs in the Perl 5 core | |
283 | distribution, provides functions useful during testing. | |
284 | ||
285 | =head2 F<pod_rules.pl> | |
286 | ||
287 | Generate the sections of files listed in C<%Targets> from F<pod/perl.pod>. | |
288 | Mostly these are rules in Makefiles. | |
289 | ||
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. | |
296 | ||
297 | =head2 F<podtidy> | |
298 | ||
299 | Applies F<podtidy> to a file. | |
300 | ||
301 | =head2 F<pumpkin.pod> | |
302 | ||
303 | Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl. | |
20a5039a | 304 | Many of these are out of date or superseded by other documents in |
3b2d1478 | 305 | this directory. |
7ad311ab | 306 | |
9bd30288 BG |
307 | =head2 F<README.pod> |
308 | ||
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. | |
313 | ||
7ad311ab JK |
314 | =head2 F<README.y2038> |
315 | ||
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 | |
5d0d7ae4 | 319 | L<https://github.com/evalEmpire/y2038>. |
7ad311ab JK |
320 | |
321 | =head2 F<release_announcement_template.txt> | |
322 | ||
c5fb089a | 323 | Release announcement for minor releasements of the 5.19 development series. |
7ad311ab JK |
324 | |
325 | =head2 F<release_managers_guide.pod> | |
326 | ||
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. | |
329 | ||
330 | =head2 F<release_schedule.pod> | |
331 | ||
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 | |
5e770dfc | 335 | Steering Council. |
7ad311ab JK |
336 | |
337 | =head2 F<rt_list_patches> | |
338 | ||
339 | Shell script to list patches in RT. | |
340 | ||
1f3be43f TC |
341 | =head1 F<security_template.pod> |
342 | ||
343 | Template to guide writers of a perl 5 security vulnerability | |
344 | announcement. | |
345 | ||
7ad311ab JK |
346 | =head2 F<sort_perldiag.pl> |
347 | ||
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>. | |
351 | ||
9bd30288 BG |
352 | =head2 F<sync-with-cpan> |
353 | ||
354 | Script to help out with syncing cpan distros. | |
355 | ||
7ad311ab JK |
356 | =head2 F<timecheck2.c> |
357 | ||
358 | A little program to test the limits of your system's time functions. See | |
359 | F<Porting/README.y2038> for details. | |
360 | ||
361 | =head2 F<timecheck.c> | |
362 | ||
363 | A helper tool for perl's 2038 support See F<Porting/README.y2038> for details. | |
364 | ||
365 | =head2 F<todo.pod> | |
366 | ||
367 | This is a list of wishes for Perl. The most up-to-date version of this file is | |
47ef154c | 368 | at L<https://github.com/Perl/perl5/blob/blead/Porting/todo.pod>. |
7ad311ab JK |
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 | |
9bd30288 | 371 | I<perl5-porters@perl.org> to avoid duplication of effort, and to learn from |
7ad311ab JK |
372 | any previous attempts. |
373 | ||
374 | =head2 F<valgrindpp.pl> | |
375 | ||
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 | |
380 | leaks. | |
381 | ||
382 | =cut | |
383 |