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