Add a README outlining contents of Porting directory.
authorJames E Keenan <jkeenan@cpan.org>
Thu, 7 Mar 2013 02:02:34 +0000 (21:02 -0500)
committerJames E Keenan <jkeenan@cpan.org>
Thu, 7 Mar 2013 02:02:34 +0000 (21:02 -0500)
For: RT #116477

MANIFEST
Porting/README.pod [new file with mode: 0644]

index 832dc9c..8ec86be 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -4888,6 +4888,7 @@ Porting/pod_lib.pl                Code for handling generated pods
 Porting/pod_rules.pl           generate lists of pod files for Makefiles
 Porting/podtidy                        Reformat pod using Pod::Tidy
 Porting/pumpkin.pod            Guidelines and hints for Perl maintainers
+Porting/README.pod                     Outline of contents of Porting directory
 Porting/README.y2038           Perl notes for the 2038 fix
 Porting/release_announcement_template.txt
 Porting/release_managers_guide.pod     Release Manager's Guide
diff --git a/Porting/README.pod b/Porting/README.pod
new file mode 100644 (file)
index 0000000..b68f2a1
--- /dev/null
@@ -0,0 +1,359 @@
+=head1 NAME
+
+README.pod - README for the F<Porting/> directory in the Perl 5 core distribution.
+
+=head1 FILES
+
+=head2 F<acknowledgements.pl>
+
+Generates the text which goes in the Acknowledgements section in
+a perldelta. You pass in the previous version and it guesses the next
+version, fetches information from the repository and outputs the
+text.
+
+=head2 F<add-package.pl>
+
+Program to prepare dual-life distributions for insertion into the Perl 5
+F<lib/> and F<t/> directories.  Now thought to be largely superseded.
+
+=head2 F<bisect-example.sh>
+
+=head2 F<bisect-runner.pl> and F<bisect.pl>
+
+Use C<git bisect> to pinpoint changes.
+
+=head2 F<bump-perl-version>
+
+A utility to find, and optionally bump, references to the perl version
+number in various files within the perl source.
+
+=head2 F<check83.pl>
+
+Performs pathname portability checks, including whether there are naming
+conflicts when names are truncated to the DOSish, case-ignoring 8.3 format.
+
+=head2 F<checkAUTHORS.pl>
+
+Used by F<t/porting/authors.t> to ensure the F<AUTHORS> list is up to date.
+
+=head2 F<checkURL.pl>
+
+Checks that all the URLs in the Perl source are valid.
+
+=head2 F<checkVERSION.pl>
+
+Used by F<t/porting/cmp_version.t> to ensure changed modules have had their
+versions updated.
+
+=head2 F<checkansi.pl>
+
+Check source code for ANSI-C violations.
+
+=head2 F<checkcfgvar.pl>
+
+Check that the various F<config.sh>-clones have (at least) all the same
+symbols as the top-level F<config_h.SH> so that the (potentially) needed
+symbols are not lagging after how F<Configure> thinks the world is laid out.
+VMS is probably not handled properly here, due to their own rather elaborate
+DCL scripting.
+
+=head2 F<check-cpan-pollution>
+
+Scans the commit logs for commits that are potentially, illegitimately
+touching modules that are primarily maintained outside of the perl core.  Also
+checks for commits that span multiple distributions in F<cpan/> or F<dist/>.
+Makes sure that updated CPAN distributions also update
+F<Porting/Maintainers.pl>, but otherwise ignores changes to that file (and
+F<MANIFEST>).
+
+=head2 F<checkpodencoding.pl>
+
+Check if POD files contain non-ASCII without specifying
+encoding. Run it as: C<perl Porting/checkpodencoding.pl>.
+
+=head2 F<cherrymaint>
+
+Command line tool to update cherrymaint; a tool for selecting commits from 
+blead to cherry-pick into stable perl versions.
+
+=head2 F<cmpVERSION.pl>
+
+Compare the current Perl source tree and a given tag for modules that have
+identical version numbers but different contents.
+
+=head2 F<config_H>
+
+This file is a sample F<config.h> file.  If you are unable to successfully run
+F<Configure>, copy this file to F<config.h> and edit it to suit your system.
+
+=head2 F<config_h.pl>
+
+Used when importing changes from F<metaconfig>.  This script reorders
+F<config_h.SH> after metaconfig.
+
+=head2 F<config.sh>
+
+This file was produced by running the F<Configure> script. It holds all the
+definitions figured out by F<Configure>.  Should you modify one of these
+values, do not forget to propagate your changes by running C<Configure -der>.
+You may instead choose to run each of the F<.SH> files by yourself, or
+C<Configure -S>.
+
+=head2 F<core-cpan-diff>
+
+Compare CPAN modules with their equivalent in core. 
+Originally based on App::DualLivedDiff by Steffen Mueller.
+
+=head2 F<corecpan.pl>
+
+Reports, in a perl source tree, which dual-lived core modules have not the
+same version than the corresponding module on CPAN.
+
+=head2 F<corelist-diff>
+
+Prints a table of differences between two Perl versions with respect to
+modules included in the distribution.
+
+=head2 F<corelist.pl>
+
+Generates info for Module::CoreList from this perl tree.
+
+=head2 F<corelist-perldelta.pl>
+
+Generates a list of the module changes for the Perl you are currently
+building.  Also generates a diff between the corelist sections of two
+F<perldelta*> files.
+
+=head2 F<curliff.pl>
+
+Convert certain files in the Perl distribution that need to be in CR-LF format
+to CR-LF, or back to LF format (with the -r option).  The CR-LF format is NOT
+to be used for checking in files to the Perforce repository, but it IS to be
+used when making Perl snapshots or releases.
+
+=head2 F<epigraphs.pod>
+
+List of Perl release epigraphs.
+
+=head2 F<exec-bit.txt>
+
+This file contains a list of files that F<makerel> will ensure get an
+executable bit.
+
+=head2 F<exercise_makedef.pl>
+
+Brute force testing for F<makedef.pl>.
+
+=head2 F<expand-macro.pl>
+
+Expand C macros using the C preprocessor.
+
+=head2 F<findrfuncs>
+
+This script finds reentrant variants of functions used in an executable and
+shared objects.
+
+=head2 F<GitUtils.pm>
+
+This script contains the subroutine to generate a F<.patch file> for a
+committish (the SHA1 checksum of a commit, a number made of 40 hexadecimal
+digits which acts the internal unique identifier for this commit
+(lilypond.org).  Related file: F<make_dot_patch.pl>
+
+=head2 F<git-deltatool>
+
+This script, a rough draft, aids in generating a perldelta file
+from a series of git commits.
+
+=head2 F<git-find-p4-change>
+
+This script, given a Perforce change number, outputs the equivalent git commit
+id.
+
+=head2 F<git-make-p4-refs>
+
+This script creates a tag for every p4raw-id.
+
+=head2 F<Glossary>
+
+This file is built by F<metaconfig>. This file contains a description of all
+the shell variables whose value is determined by the Configure script. 
+
+=head2 F<how_to_write_a_perldelta.pod> 
+
+This file contains a specification as to how to write a perldelta pod.
+Related file: F<perldelta_template.pod>
+
+=head2 F<leakfinder.pl>
+
+This script executes every line in every file in the build directory and its
+subdirectories to determine if the number of SVs goes up and reports it as a
+leak to STDOUT.  WARNING! some harm could be done if a line contains something
+similar to C<`rm *`>.
+
+=head2 F<Maintainers>
+
+This script shows information about the maintainers of core files/modules.
+
+Related files: F<Maintainers.pl>, F<Maintainers.pm>
+
+=head2 F<Maintainers.pl>
+
+A package associating core files/modules with maintainers.  Related files:
+F<Maintainers>, F<Maintainers.pm>
+
+=head2 F<Maintainers.pm>
+
+A package to search and show information about which core files/modules are
+associated with maintainers.  Related files: F<Maintainers>, F<Maintainers.pl>
+
+=head2 F<make-rmg-checklist>
+
+This script creates a release checklist as a simple HTML document.
+
+=head2 F<make_dot_patch.pl>
+
+Generate a F<.patch> file to STDOUT for a commit ID specified on the
+command-line.
+
+=head2 F<make_modlib_cpan.pl>
+
+This script generates the list of registered CPAN sites in F<perlmodlib.PL>.
+
+=head2 F<make_snapshot.pl>
+
+This script is a quick and dirty snapshot generator for the perl5.git.perl.org
+web page to use to generate the snapshot files. 
+
+=head2 F<makemeta>
+
+This script creates F<META.yml> and F<META.json> files.
+
+=head2 F<makerel>
+
+This script builds a Perl release tarball.
+
+=head2 F<manicheck>
+
+This script outputs a list of files in F<MANIFEST> which don't exist and a
+list of files that exist and aren't in F<MANIFEST>.
+
+=head2 F<manisort>
+
+This script sorts the files in F<MANIFEST>.
+
+=head2 F<new-perldelta.pl>
+
+This script automates the process for creating perldelta.pl.
+
+=head2 F<newtests-perldelta.pl>
+
+This script outputs the added tests between the two versions of Perl.
+
+=head2 F<perldelta_template.pod>
+
+Template for F<perldelta>.
+
+=head2 F<perlhist_calculate.pl>
+
+Generates info for F<perlhist> from this perl tree.
+
+=head2 F<pod_lib.pl>
+
+When C<require>d into other programs in the Perl 5 core
+distribution, provides functions useful during testing.
+
+=head2 F<pod_rules.pl>
+
+Generate the sections of files listed in C<%Targets> from F<pod/perl.pod>.
+Mostly these are rules in Makefiles.
+
+ --verbose gives slightly more output
+ --build-all tries to build everything
+ --build-foo updates foo as follows
+ --showfiles shows the files to be changed
+ --test exit if perl.pod, MANIFEST are consistent, and regenerated
+   files are up to date, die otherwise.
+
+=head2 F<podtidy>
+
+Applies F<podtidy> to a file.
+
+=head2 F<pumpkin.pod>
+
+Pumpkin - Notes on handling the Perl Patch Pumpkin And Porting Perl.
+
+=head2 F<README.y2038>
+
+The y2038 implementation for perl. This is an implementation of POSIX time.h
+which solves the year 2038 bug on systems where time_t is only 32 bits.  It is
+implemented in bog-standard ANSI C. The latest version can be found at
+L<http://y2038.googlecode.com/>.
+
+=head2 F<release_announcement_template.txt>
+
+Release announcment for minor releasements of the 5.17 development series.
+
+=head2 F<release_managers_guide.pod>
+
+Releasing a new version of perl 5.x. Note that things change at each release,
+so there may be new things not covered here, or tools may need updating.
+
+=head2 F<release_schedule.pod>
+
+This schedule lists the projected or historical development and release
+schedules for the next, current and previous stable versions of Perl. Dates
+with all question marks will only be releases if deemed necessary by the
+Pumpking.
+
+=head2 F<rt_list_patches>
+
+Shell script to list patches in RT.
+
+=head2 F<sort_perldiag.pl>
+
+This is a script for sorting the warning and error messages in
+F<perldiag.pod>.  POD formatting, printf-style escapes, non-letter characters,
+and case are ignored, as explained in L<perldiag>.
+
+=head2 F<testall.atom>
+
+Test suite profiling on Tru 64.
+
+=head2 F<thirdclean>
+
+Script for cleaning out the "known noise" from Third Degree reports: either
+noise caused by F<libc> itself, or F<Perl_yyparse> leaks.
+
+=head2 F<time>
+
+A helper tool for perl's 2038 support. See F<Porting/README.y2038> for details.
+
+=head2 F<timecheck2.c>
+
+A little program to test the limits of your system's time functions. See
+F<Porting/README.y2038> for details.
+
+=head2 F<timecheck.c>
+
+A helper tool for perl's 2038 support See F<Porting/README.y2038> for details.
+
+=head2 F<todo.pod>
+
+This is a list of wishes for Perl. The most up-to-date version of this file is
+at L<http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/Porting/todo.pod>.
+The tasks we think are smaller or easier are listed first.  Anyone is welcome
+to work on any of these, but it's a good idea to first contact
+F<perl5-porters@perl.org> to avoid duplication of effort, and to learn from
+any previous attempts.
+
+=head2 F<valgrindpp.pl>
+
+A post-processor for C<make test.valgrind>.  F<valgrindpp.pl> is a
+post-processor for F<.valgrind> files created during C<make test.valgrind>. It
+collects all these files, extracts most of the information and produces a
+significantly shorter summary of all detected memory access errors and memory
+leaks.
+
+=cut
+