File: README.pod

package info (click to toggle)
perl 5.24.1-3+deb9u5
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 103,716 kB
  • sloc: perl: 559,611; ansic: 293,886; sh: 67,316; pascal: 7,632; cpp: 3,895; makefile: 2,436; xml: 2,410; yacc: 989; sed: 6; lisp: 1
file content (366 lines) | stat: -rw-r--r-- 10,871 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
=head1 NAME

README.pod - README for the F<Porting/> directory in the Perl 5 core distribution.

=head1 FILES

=head2 F<acknowledgements.pl>

Generates the text which goes in the Acknowledgements section in
a perldelta. You pass in the previous version and it guesses the next
version, fetches information from the repository and outputs the
text.

=head2 F<add-package.pl>

Program to prepare dual-life distributions for insertion into the Perl 5
F<lib/> and F<t/> directories.  Now thought to be largely superseded.

=head2 F<bench.pl>

Do performance analysis on the code snippets in F<t/perf/benchmarks>.

=head2 F<bisect-example.sh>, F<bisect.pl> and F<bisect-runner.pl>

Use C<git bisect> to pinpoint changes.

=head2 F<bump-perl-version>

A utility to find, and optionally bump, references to the perl version
number in various files within the perl source.

=head2 F<check83.pl>

Performs pathname portability checks, including whether there are naming
conflicts when names are truncated to the DOSish, case-ignoring 8.3 format.

=head2 F<checkansi.pl>

Check source code for ANSI-C violations.

=head2 F<checkAUTHORS.pl>

Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date.

=head2 F<checkcfguse.pl>

Check where the symbols defined in the various F<config.sh>-clones
are being used.  VMS is probably not handled properly here.

=head2 F<checkcfgvar.pl>

Check that the various F<config.sh>-clones have (at least) all the same
symbols as the top-level F<config_h.SH> so that the (potentially) needed
symbols are not lagging after how F<Configure> thinks the world is laid out.
VMS is probably not handled properly here, due to their own rather elaborate
DCL scripting.

=head2 F<check-cpan-pollution>

Scans the commit logs for commits that are potentially, illegitimately
touching modules that are primarily maintained outside of the perl core.  Also
checks for commits that span multiple distributions in F<cpan/> or F<dist/>.
Makes sure that updated CPAN distributions also update
F<Porting/Maintainers.pl>, but otherwise ignores changes to that file (and
F<MANIFEST>).

=head2 F<checkpodencoding.pl>

Check if POD files contain non-ASCII without specifying
encoding. Run it as: C<perl Porting/checkpodencoding.pl>.

=head2 F<checkURL.pl>

Checks that all the URLs in the Perl source are valid.

=head2 F<checkVERSION.pl>

Used by F<t/porting/cmp_version.t> to ensure changed modules have had their
versions updated.

=head2 F<cherrymaint>

Command line tool to update cherrymaint; a tool for selecting commits from 
blead to cherry-pick into stable perl versions.

=head2 F<cmpVERSION.pl>

Compare the current Perl source tree and a given tag for modules that have
identical version numbers but different contents.

=head2 F<config_H>

This file is a sample F<config.h> file.  If you are unable to successfully run
F<Configure>, copy this file to F<config.h> and edit it to suit your system.

=head2 F<config_h.pl>

Used when importing changes from F<metaconfig>.  This script reorders
F<config_h.SH> after metaconfig.

=head2 F<config.sh>

This file is a sample F<config.sh> file.  F<config.sh> is normally
produced by running the F<Configure> script. It holds all the definitions
figured out by F<Configure>.  If you are unable to successfully run
F<Configure> on your system, copy this sample file to F<config.sh>
at the top of the perl source tree and edit it to suit your system.
Then propagate those values by running C<Configure -S>.  This sample
file is normally updated each time F<Configure> is updated.

=head2 F<core-cpan-diff>

Compare CPAN modules with their equivalent in core. 
Originally based on App::DualLivedDiff by Steffen Mueller.

=head2 F<corecpan.pl>

Reports, in a perl source tree, which dual-lived core modules have not the
same version than the corresponding module on CPAN.

=head2 F<corelist-diff>

Prints a table of differences between two Perl versions with respect to
modules included in the distribution.

=head2 F<corelist-perldelta.pl>

Generates a list of the module changes for the Perl you are currently
building.  Also generates a diff between the corelist sections of two
F<perldelta*> files.

=head2 F<corelist.pl>

Generates info for Module::CoreList from this perl tree.

=head2 F<deparse-skips.txt>

List of test files to ignore/skip for deparse tests.

=head2 F<epigraphs.pod>

List of Perl release epigraphs.

=head2 F<exec-bit.txt>

This file contains a list of files that F<makerel> will ensure get an
executable bit.

=head2 F<exercise_makedef.pl>

Brute force testing for F<makedef.pl>.

=head2 F<expand-macro.pl>

Expand C macros using the C preprocessor.

=head2 F<findrfuncs>

This script finds reentrant variants of functions used in an executable and
shared objects.

=head2 F<git-deltatool>

This script, a rough draft, aids in generating a perldelta file
from a series of git commits.

=head2 F<git-find-p4-change>

This script, given a Perforce change number, outputs the equivalent git commit
id.

=head2 F<git-make-p4-refs>

This script creates a tag for every p4raw-id.

=head2 F<GitUtils.pm>

This script contains the subroutine to generate a F<.patch file> for a
committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
digits which acts the internal unique identifier for this commit
(lilypond.org).  Related file: F<make_dot_patch.pl>

=head2 F<Glossary>

This file is built by F<metaconfig>. This file contains a description of all
the shell variables whose value is determined by the Configure script. 
It later gets incorporated into the pod for F<Config.pm>.

=head2 F<how_to_write_a_perldelta.pod> 

This file contains a specification as to how to write a perldelta pod.
Related file: F<perldelta_template.pod>

=head2 F<leakfinder.pl>

This script executes every line in every file in the build directory and its
subdirectories to determine if the number of SVs goes up and reports it as a
leak to STDOUT.  WARNING! some harm could be done if a line contains something
similar to C<`rm *`>.

=head2 F<Maintainers>

This script shows information about the maintainers of core files/modules.

Related files: F<Maintainers.pl>, F<Maintainers.pm>

=head2 F<Maintainers.pl>

A package associating core files/modules with maintainers.  Related files:
F<Maintainers>, F<Maintainers.pm>

=head2 F<Maintainers.pm>

A package to search and show information about which core files/modules are
associated with maintainers.  Related files: F<Maintainers>, F<Maintainers.pl>

=head2 F<make_dot_patch.pl>

Generate a F<.patch> file to STDOUT for a commit ID specified on the
command-line.

=head2 F<makemeta>

This script creates F<META.yml> and F<META.json> files.

=head2 F<make_modlib_cpan.pl>

This script generates the list of registered CPAN sites in F<perlmodlib.PL>.

=head2 F<makerel>

This script builds a Perl release tarball.

=head2 F<make-rmg-checklist>

This script creates a release checklist as a simple HTML document.

=head2 F<make_snapshot.pl>

This script is a quick and dirty snapshot generator for the perl5.git.perl.org
web page to use to generate the snapshot files. 

=head2 F<manicheck>

This script outputs a list of files in F<MANIFEST> which don't exist and a
list of files that exist and aren't in F<MANIFEST>.

=head2 F<manisort>

This script sorts the files in F<MANIFEST>.

=head2 F<new-perldelta.pl>

This script automates the process for creating perldelta.pl.

=head2 F<newtests-perldelta.pl>

This script outputs the added tests between the two versions of Perl.

=head2 F<perldelta_template.pod>

Template for F<perldelta>.

=head2 F<perlhist_calculate.pl>

Generates info for F<perlhist> from this perl tree.

=head2 F<pod_lib.pl>

When C<require>d into other programs in the Perl 5 core
distribution, provides functions useful during testing.

=head2 F<pod_rules.pl>

Generate the sections of files listed in C<%Targets> from F<pod/perl.pod>.
Mostly these are rules in Makefiles.

 --verbose gives slightly more output
 --build-all tries to build everything
 --build-foo updates foo as follows
 --showfiles shows the files to be changed
 --test exit if perl.pod, MANIFEST are consistent, and regenerated
   files are up to date, die otherwise.

=head2 F<podtidy>

Applies F<podtidy> to a file.

=head2 F<pumpkin.pod>

Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl.
Many of these are out of date or superseded by other documents in 
this directory.

=head2 F<README.pod>

This file.  An exhaustive list of the contents of the F<Porting/>
directory along with a description of each file.
The test F<t/porting/readme.t> ensures that this lists every file
and that every file is listed.

=head2 F<README.y2038>

The y2038 implementation for perl. This is an implementation of POSIX time.h
which solves the year 2038 bug on systems where time_t is only 32 bits.  It is
implemented in bog-standard ANSI C. The latest version can be found at
L<http://y2038.googlecode.com/>.

=head2 F<release_announcement_template.txt>

Release announcement for minor releasements of the 5.19 development series.

=head2 F<release_managers_guide.pod>

Releasing a new version of perl 5.x. Note that things change at each release,
so there may be new things not covered here, or tools may need updating.

=head2 F<release_schedule.pod>

This schedule lists the projected or historical development and release
schedules for the next, current and previous stable versions of Perl. Dates
with all question marks will only be releases if deemed necessary by the
Pumpking.

=head2 F<rt_list_patches>

Shell script to list patches in RT.

=head2 F<sort_perldiag.pl>

This is a script for sorting the warning and error messages in
F<perldiag.pod>.  POD formatting, printf-style escapes, non-letter characters,
and case are ignored, as explained in L<perldiag>.

=head2 F<sync-with-cpan>

Script to help out with syncing cpan distros.

=head2 F<timecheck2.c>

A little program to test the limits of your system's time functions. See
F<Porting/README.y2038> for details.

=head2 F<timecheck.c>

A helper tool for perl's 2038 support See F<Porting/README.y2038> for details.

=head2 F<todo.pod>

This is a list of wishes for Perl. The most up-to-date version of this file is
at L<http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/Porting/todo.pod>.
The tasks we think are smaller or easier are listed first.  Anyone is welcome
to work on any of these, but it's a good idea to first contact
I<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
any previous attempts.

=head2 F<valgrindpp.pl>

A post-processor for C<make test.valgrind>.  F<valgrindpp.pl> is a
post-processor for F<.valgrind> files created during C<make test.valgrind>. It
collects all these files, extracts most of the information and produces a
significantly shorter summary of all detected memory access errors and memory
leaks.

=cut