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