write a Porting/README explaining Porting contents #12721
Comments
From @rjbsThe ./Porting directory in perl.git contains a bunch of stuff used to build, Add a README (or something) file to ./Porting that lists each file and its For extra credit, add a test to t/porting that asserts that every file in |
From @jkeenanOn Mon Jan 21 08:00:50 2013, rjbs wrote:
We're starting to plan a New York Perl Hackathon and this looks like a However, since that event may be several weeks off, if someone else Thank you very much. |
|
The RT System itself - Status changed from 'new' to 'open' |
From @jkeenanOn Wed Jan 23 15:59:49 2013, jkeenan wrote:
The patch is the work of Matthew Ryder, Arthur Goldstein and myself at (1) Rule out obvious errors. (2) Improvements in descriptions of files in Porting/. (3) Stylistic/grammatical/typographical corrections. When you read this document, you will no doubt spot references to Perl We'll have to decide whether this README is sufficiently useful to be Thank you very much. |
From @jkeenanFrom dd980c21ed49b0b681d3447104b49bac19d4dbc9 Mon Sep 17 00:00:00 2001 Includes work by Matthew Ryder and Arthur Goldstein at New York Perl For: RT #116477 Porting/README.pod | 366 ++++++++++++++++++++++++++++++++++++++++++++++++++++ Inline Patchdiff --git a/Porting/README.pod b/Porting/README.pod
new file mode 100644
index 0000000..fbb01e4
--- /dev/null
+++ b/Porting/README.pod
@@ -0,0 +1,366 @@
+=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<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 cpan/ or 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<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>
+
+Performs quality checks on F<AUTHORS> including rectifying cases where
+contributors have submitted contributions from different email addresses.
+
+=head2 F<checkURL.pl>
+
+Checks that all the URLs in the Perl source are valid.
+
+=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 check-cpan-polution
+
+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<checkURL.pl>
+
+Check that all the URLs in the Perl source are valid
+
+=head2 F<checkVERSION.pl>
+
+Check the tree against missing VERSIONs.
+
+=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>
+
+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>
+
+This script reorders F<config_h.SH> after metaconfig. Changing F<metaconfig>
+is too complicated This script is run just after F<metaconfig>, and it is run
+ONLY ONCE. Not to be used afterwards
+
+=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-perldelta.pl>
+
+Generates info for Module::CoreList from this perl tree run this from the root
+of a perl tree Data is on STDOUT. With an optional arg specifying the root of
+a CPAN mirror, outputs the %upstream and %bug_tracker hashes too.
+
+=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>.
+
+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 directy 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>
+
+This script reads sha1 from C<@ARGV> and then prints GitUtils::gen_dot_patch
+to STDOUT to determine which primary branch sha1 can be found on.
+
+=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<perl5180delta.pod>
+
+This is a template for a new perldelta file 5.18 description of what the file
+does.
+
+=head2 F<perldelta_template.pod>
+
+This seems to be the same file when diffed with the perl5180delta.pod except
+that the previous is focused on 5.18.1.
+
+=head2 F<perlhist_calculate.pl>
+
+Generates info for F<perlhist> from this perl tree.
+
+=head2 F<pod_lib.pl>
+
+Make it clearer when we haven't run to completion, as we can be quite noisy
+when things are working ok write_or_die,pods_to_install does not seem to be
+called within in this file. However pods_to_install does call a lot of
+libraries inside this file.
+
+=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 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>
+
+ 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
+ |
From @tonycozOn Sat, Mar 02, 2013 at 12:31:47PM -0800, James E Keenan via RT wrote:
A few notes: Some headings are missing the F<> markup:
There's a missing newline before one heading:
The notes on pod_lib.pl are a little confusing:
The note for config_h.pl is missing a comma or a period (or has some There is no such file as cmpVersion (presumably it should be
Typo:
The headings are vaguely in alphabetical order, but there are several corelist-diff, corelist.pl aren't documented. There is text describing expand-macro.pl and More generally, some documentation on when some of the scripts are or - config_h.pl - used when importing changes from metaconfig (it's - checkAUTHORS.pl - used by porting/authors.t to ensure the authors - cmpVERSION.pl - used by porting/cmp_version.t to ensure changed but it's valuable without this. Tony |
From @jkeenanOn Sun Mar 03 15:04:48 2013, tonyc wrote:
[snip] Thanks for the feedback. Second version attached. Since this is a new Thank you very much. |
From @tonycozOn Sun, Mar 03, 2013 at 04:31:41PM -0800, James E Keenan via RT wrote:
All the errors I mentioned have been fixed except for: - the cmpVersion heading was changed to cmpVersion.pl but it's
Perhaps: Generate a C<.patch> file to STDOUT for the specified commit id.
This isn't a template, but is a work-in-progress perldelta for 5.18.0.
This one is the template. Neither file mentions 5.18.1.
I don't think this should be indented. Tony |
From @jkeenanOn Sun Mar 03 17:18:41 2013, tonyc wrote:
version 3 attached. |
From @tonycozOn Sun, Mar 03, 2013 at 06:20:01PM -0800, James E Keenan via RT wrote:
I'm happy. Tony |
From @jkeenanOn Mon Mar 04 14:14:24 2013, tonyc wrote:
Anyone else want to chime in? Otherwise, I'll commit this to blead in Thank you very much. |
From @b2gillsOn Mon, Mar 4, 2013 at 6:25 PM, James E Keenan via RT
=head2 F<curliff.pl> Convert certain files in the Perl distribution that need to be in CR-LF format Perl is now maintained using git not Perforce. Slightly unrelated: That file can probably go ( git handles this ) I don't think this should be in there: =head2 F<perl5180delta.pod> F<perldelta> for Perl 5.18.0: a work-in-progress file. |
From @rjbs* James E Keenan via RT <perlbug-followup@perl.org> [2013-03-04T19:25:55]
I do want to give it a look-over and maybe futz with it, but I don't see any Do we have a test (for t/Porting) that all files in ./Porting are in the index? -- |
From @jkeenanOn 3/4/13 9:07 PM, Brad Gilbert wrote:
Please open an RT for the removal of that file.
Do you mean: It should not be in Porting/README.pod ... or it shouldn't Thank you very much. |
From @tonycozOn Mon, Mar 04, 2013 at 10:46:06PM -0500, James E Keenan wrote:
I don't think it belongs in the README.pod. Tony |
From @jkeenanOn Mon Mar 04 19:30:27 2013, rjbs wrote:
In 7ad311a, I committed something which Are there still inaccuracies in this README? Undoubtedly. For example,
No, I didn't want to hold up submission of this patch for that purpose. Thanks again to Matt and Arthur for their work on this at the NY Perl Closing ticket. Thank you very much. |
|
@jkeenan - Status changed from 'open' to 'resolved' |
Migrated from rt.perl.org#116477 (status was 'resolved')
Searchable as RT116477$
The text was updated successfully, but these errors were encountered: