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