[perl #112924] [PATCH] Clarify test instructions in INSTALL

[Andy Dougherty]

# New Ticket Created by Andy Dougherty
# Please include the string: [perl #112924]
# in the subject line of all future correspondence about this issue.
# <URL: https://rt.perl.org:443/rt3/Ticket/Display.html?id=112924 >


While trying to track down a failed test, I found the instructions
in the INSTALL file to be less than optimal.

This patch re-orders the suggestions to put the ones most likely
to work first, clarifies which directory you should be in, and
moves a "see-also" type reference to where it is more likely to be
useful.

The catalyst for this was that

./perl -MTestInit cpan/Archive-Extract/t/01/Archive-Extract.t

fails because it can't find strict.pm. (I'll file a separate report
for that.) Since it's probably not the only such case, I thought it
useful and prudent to advise using t/harness instead as a first recourse.

I'd just apply this myself, but I don't know where we are in the RC
process, and don't want to mess anything up.


--- perl-5.16.0-RC0/INSTALL 2012-05-10 14:38:09.000000000 -0400
+++ perl-andy/INSTALL.new 2012-05-14 08:48:40.000000000 -0400
@@ -1865,7 +1865,7 @@

This will run the regression tests on the perl you just made. If
'make test' doesn't say "All tests successful" then something went
-wrong. See the file t/README in the t subdirectory.
+wrong.

Note that you can't run the tests in background if this disables
opening of /dev/tty. You can use 'make test-notty' in that case but
@@ -1874,13 +1874,10 @@
=head2 What if make test doesn't work?

If make test bombs out, just cd to the t directory and run ./TEST
-by hand to see if it makes any difference. If individual tests
-bomb, you can run them by hand, e.g.,
+by hand to see if it makes any difference.

- ./perl -MTestInit t/op/groups.t
-
-Another way to get more detailed information about failed tests and
-individual subtests is to cd to the t directory and run
+One way to get more detailed information about failed tests and
+individual subtests is to run the harness from the t directory:

cd t ; ./perl harness <list of tests>

@@ -1888,12 +1885,20 @@
complicated constructs). If no list of tests is provided, harness
will run all tests.

+If individual tests fail, you can often run them by hand (from the main
+perl directory), e.g.,
+
+ ./perl -MTestInit t/op/groups.t
+
You should also read the individual tests to see if there are any helpful
comments that apply to your system. You may also need to setup your
shared library path if you get errors like:

/sbin/loader: Fatal Error: cannot map libperl.so

+The file t/README in the t subdirectory contains more information about
+running and modifying tests.
+
See L</"Building a shared Perl library"> earlier in this document.

=over 4


--
Andy Dougherty doug...@lafayette.edu

[James E Keenan via RT]

On Mon May 14 06:02:08 2012, doughera wrote:
> While trying to track down a failed test, I found the instructions
> in the INSTALL file to be less than optimal.
>
> This patch re-orders the suggestions to put the ones most likely
> to work first, clarifies which directory you should be in, and
> moves a "see-also" type reference to where it is more likely to be
> useful.
>

+1 to this patch.

In other contexts (e.g., Parrot), people are accustomed to running a
program called some variation of "harness" and often expect that program
to be what, in some sense, "'make test' does."

In contrast, having to say something like '-MTest::Init' is more arcane.
It certainly took me months to wrap my head around it.

Thank you very much.
Jim Keenan


---
via perlbug: queue: perl5 status: new
https://rt.perl.org:443/rt3/Ticket/Display.html?id=112924

[Andy Dougherty]

On Tue, 15 May 2012, James E Keenan via RT wrote:

> On Mon May 14 06:02:08 2012, doughera wrote:
> > While trying to track down a failed test, I found the instructions
> > in the INSTALL file to be less than optimal.
> >
> > This patch re-orders the suggestions to put the ones most likely
> > to work first, clarifies which directory you should be in, and
> > moves a "see-also" type reference to where it is more likely to be
> > useful.
> >
>
> +1 to this patch.
>
> In other contexts (e.g., Parrot), people are accustomed to running a
> program called some variation of "harness" and often expect that program
> to be what, in some sense, "'make test' does."
>
> In contrast, having to say something like '-MTest::Init' is more arcane.
> It certainly took me months to wrap my head around it.

For me, it was more a question of what worked vs. what didn't always
work.

I've applied that patch to blead as
commit 36bded947b191af9d49762ac9409f96f0d5905d7

--
Andy Dougherty doug...@lafayette.edu