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