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<add-pod-file>
  20
  21 Program to facilitate addition of new F<.pod> files to F<pod/>.
  22
  23 =head2 F<bench.pl>
  24
  25 Do performance analysis on the code snippets in F<t/perf/benchmarks>.
  26
  27 =head2 F<bisect-example.sh>, F<bisect.pl> and F<bisect-runner.pl>
  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
  41 =head2 F<checkansi.pl>
  42
  43 Check source code for ANSI-C violations.
  44
  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
  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
  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
  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
  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
 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.
 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
 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
 131 =head2 F<corelist.pl>
 132
 133 Generates info for Module::CoreList from this perl tree.
 134
 135 =head2 F<core-team.json>
 136
 137 The canonical list of Perl Core Team members, used to build perlgov.pod,
 138 produce election mailings, and all that sort of thing.
 139
 140 =head2 F<deparse-skips.txt>
 141
 142 List of test files to ignore/skip for deparse tests.
 143
 144 =head2 F<docs-team-charter.pod>
 145
 146 The charter of the Perl Documentation Team
 147
 148 =head2 F<epigraphs.pod>
 149
 150 List of Perl release epigraphs.
 151
 152 =head2 F<exec-bit.txt>
 153
 154 This file contains a list of files that F<makerel> will ensure get an
 155 executable bit.
 156
 157 =head2 F<exercise_makedef.pl>
 158
 159 Brute force testing for F<makedef.pl>.
 160
 161 =head2 F<expand-macro.pl>
 162
 163 Expand C macros using the C preprocessor.
 164
 165 =head2 F<findrfuncs>
 166
 167 This script finds reentrant variants of functions used in an executable and
 168 shared objects.
 169
 170 =head2 F<git-deltatool>
 171
 172 This script, a rough draft, aids in generating a perldelta file
 173 from a series of git commits.
 174
 175 =head2 F<git-find-p4-change>
 176
 177 This script, given a Perforce change number, outputs the equivalent git commit
 178 id.
 179
 180 =head2 F<git-make-p4-refs>
 181
 182 This script creates a tag for every p4raw-id.
 183
 184 =head2 F<GitUtils.pm>
 185
 186 This script contains the subroutine to generate a F<.patch file> for a
 187 committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
 188 digits which acts the internal unique identifier for this commit
 189 (lilypond.org).  Related file: F<make_dot_patch.pl>
 190
 191 =head2 F<Glossary>
 192
 193 This file is built by F<metaconfig>. This file contains a description of all
 194 the shell variables whose value is determined by the Configure script.
 195 It later gets incorporated into the pod for F<Config.pm>.
 196
 197 =head2 F<harness-timer-report.pl>
 198
 199 For analyzing the output of "env HARNESS_TIMER=1 make test", to find
 200 outliers of test execution times.
 201
 202 =head2 F<how_to_write_a_perldelta.pod>
 203
 204 This file contains a specification as to how to write a perldelta pod.
 205 Related file: F<perldelta_template.pod>
 206
 207 =head2 F<leakfinder.pl>
 208
 209 This script executes every line in every file in the build directory and its
 210 subdirectories to determine if the number of SVs goes up and reports it as a
 211 leak to STDOUT.  WARNING! some harm could be done if a line contains something
 212 similar to C<`rm *`>.
 213
 214 =head2 F<Maintainers>
 215
 216 This script shows information about the maintainers of core files/modules.
 217
 218 Related files: F<Maintainers.pl>, F<Maintainers.pm>
 219
 220 =head2 F<Maintainers.pl>
 221
 222 A package associating core files/modules with maintainers.  Related files:
 223 F<Maintainers>, F<Maintainers.pm>
 224
 225 =head2 F<Maintainers.pm>
 226
 227 A package to search and show information about which core files/modules are
 228 associated with maintainers.  Related files: F<Maintainers>, F<Maintainers.pl>
 229
 230 =head2 F<make_dot_patch.pl>
 231
 232 Generate a F<.patch> file to STDOUT for a commit ID specified on the
 233 command-line.
 234
 235 =head2 F<makemeta>
 236
 237 This script creates F<META.yml> and F<META.json> files.
 238
 239 =head2 F<makerel>
 240
 241 This script builds a Perl release tarball.
 242
 243 =head2 F<make-rmg-checklist>
 244
 245 This script creates a release checklist as a simple HTML document.
 246
 247 =head2 F<make_snapshot.pl>
 248
 249 This script is a quick and dirty snapshot generator for the perl5.git.perl.org
 250 web page to use to generate the snapshot files.
 251
 252 =head2 F<manicheck>
 253
 254 This script outputs a list of files in F<MANIFEST> which don't exist and a
 255 list of files that exist and aren't in F<MANIFEST>.
 256
 257 =head2 F<manifest_lib.pl>
 258
 259 This library provides functions used in checking and sorting the F<MANIFEST>.
 260
 261 =head2 F<manisort>
 262
 263 This script sorts the files in F<MANIFEST>.
 264
 265 =head2 F<mksample>
 266
 267 This script regenerates F<Porting/config.sh> and F<Porting/config_H>.
 268
 269 =head2 F<new-perldelta.pl>
 270
 271 This script automates the process for creating perldelta.pl.
 272
 273 =head2 F<newtests-perldelta.pl>
 274
 275 This script outputs the added tests between the two versions of Perl.
 276
 277 =head2 F<perldelta_template.pod>
 278
 279 Template for F<perldelta>.
 280
 281 =head2 F<perlgov-team-update>
 282
 283 This produces a new team list for F<perlgov.pod>, but does not, at present,
 284 insert that content into the file.
 285
 286 =head2 F<perlhist_calculate.pl>
 287
 288 Generates info for F<perlhist> from this perl tree.
 289
 290 =head2 F<pod_lib.pl>
 291
 292 When C<require>d into other programs in the Perl 5 core
 293 distribution, provides functions useful during testing.
 294
 295 =head2 F<pod_rules.pl>
 296
 297 Generate the sections of files listed in C<%Targets> from F<pod/perl.pod>.
 298 Mostly these are rules in Makefiles.
 299
 300  --verbose gives slightly more output
 301  --build-all tries to build everything
 302  --build-foo updates foo as follows
 303  --showfiles shows the files to be changed
 304  --test exit if perl.pod, MANIFEST are consistent, and regenerated
 305    files are up to date, die otherwise.
 306
 307 =head2 F<podtidy>
 308
 309 Applies F<podtidy> to a file.
 310
 311 =head2 F<pumpkin.pod>
 312
 313 Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl.
 314 Many of these are out of date or superseded by other documents in
 315 this directory.
 316
 317 =head2 F<README.pod>
 318
 319 This file.  An exhaustive list of the contents of the F<Porting/>
 320 directory along with a description of each file.
 321 The test F<t/porting/readme.t> ensures that this lists every file
 322 and that every file is listed.
 323
 324 =head2 F<README.y2038>
 325
 326 The y2038 implementation for perl. This is an implementation of POSIX time.h
 327 which solves the year 2038 bug on systems where time_t is only 32 bits.  It is
 328 implemented in bog-standard ANSI C. The latest version can be found at
 329 L<https://github.com/evalEmpire/y2038>.
 330
 331 =head2 F<release_announcement_template.txt>
 332
 333 Release announcement for minor releasements of the 5.19 development series.
 334
 335 =head2 F<release_managers_guide.pod>
 336
 337 Releasing a new version of perl 5.x. Note that things change at each release,
 338 so there may be new things not covered here, or tools may need updating.
 339
 340 =head2 F<release_schedule.pod>
 341
 342 This schedule lists the projected or historical development and release
 343 schedules for the next, current and previous stable versions of Perl. Dates
 344 with all question marks will only be releases if deemed necessary by the
 345 Steering Council.
 346
 347 =head2 F<rt_list_patches>
 348
 349 Shell script to list patches in RT.
 350
 351 =head1 F<security_template.pod>
 352
 353 Template to guide writers of a perl 5 security vulnerability
 354 announcement.
 355
 356 =head2 F<sort_perldiag.pl>
 357
 358 This is a script for sorting the warning and error messages in
 359 F<perldiag.pod>.  POD formatting, printf-style escapes, non-letter characters,
 360 and case are ignored, as explained in L<perldiag>.
 361
 362 =head2 F<sync-with-cpan>
 363
 364 Script to help out with syncing cpan distros.
 365
 366 =head2 F<timecheck2.c>
 367
 368 A little program to test the limits of your system's time functions. See
 369 F<Porting/README.y2038> for details.
 370
 371 =head2 F<timecheck.c>
 372
 373 A helper tool for perl's 2038 support See F<Porting/README.y2038> for details.
 374
 375 =head2 F<todo.pod>
 376
 377 This is a list of wishes for Perl. The most up-to-date version of this file is
 378 at L<https://github.com/Perl/perl5/blob/blead/Porting/todo.pod>.
 379 The tasks we think are smaller or easier are listed first.  Anyone is welcome
 380 to work on any of these, but it's a good idea to first contact
 381 I<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
 382 any previous attempts.
 383
 384 =head2 F<valgrindpp.pl>
 385
 386 A post-processor for C<make test.valgrind>.  F<valgrindpp.pl> is a
 387 post-processor for F<.valgrind> files created during C<make test.valgrind>. It
 388 collects all these files, extracts most of the information and produces a
 389 significantly shorter summary of all detected memory access errors and memory
 390 leaks.
 391
 392 =head2 F<vote_admin_guide.pod>
 393
 394 Guide for Vote Administrators for running Steering Council elections.
 395
 396 =cut
 397