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