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