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