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