doc: HACKING: add a bit about faster testing

`make test' is annoyingly slow, and `make check-run' works
wonders for improving the edit && test cycle.

diff --git a/Documentation/txt2pre b/Documentation/txt2pre
index c3a7657e6157a216c864d6f22bb1c514fe4eb817..cf58bad820f3adc6d83a0d46f36add4c820e404a 100755 (executable)
--- a/Documentation/txt2pre
+++ b/Documentation/txt2pre
@@ -39,9 +39,9 @@ for (qw[copydatabase(1) xapian-compact(1)]) {
        $xurls{$_} = ".$n.1.html"
 }
 
-for (qw[flock(2) setrlimit(2) vfork(2)]) {
+for (qw[make(1) flock(2) setrlimit(2) vfork(2) tmpfs(5)]) {
        my ($n, $s) = (/([\w\-]+)\((\d)\)/);
-       $xurls{$_} = "http://www.man7.org/linux/man-pages/man2/$n.$s.html";
+       $xurls{$_} = "http://www.man7.org/linux/man-pages/man$s/$n.$s.html";
 }
 
 for (qw[git(1)
@@ -82,6 +82,7 @@ $xurls{'git-filter-repo(1)'} = 'https://github.com/newren/git-filter-repo'.
                        './blob/master/Documentation/git-filter-repo.txt';
 $xurls{'ssoma(1)'} = 'https://ssoma.public-inbox.org/ssoma.txt';
 $xurls{'cgitrc(5)'} = 'https://git.zx2c4.com/cgit/tree/cgitrc.5.txt';
+$xurls{'prove(1)'} = 'https://perldoc.perl.org/prove.html';
 
 my $str = do { local $/; <STDIN> };
 my ($title) = ($str =~ /\A([^\n]+)/);

diff --git a/HACKING b/HACKING
index cceb686f2e83e41e07b14beae70fd96fc60d745d..74a3096f5318749f547b28c6f4ba784ebc0acfed 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -59,6 +59,24 @@ directory for design decisions made during development.
 See Documentation/technical/ in the source tree for more details
 on specific topics, in particular data_structures.txt
 
+Faster tests
+------------
+
+The `make test' target provided by MakeMaker does not run in
+parallel.  Our `make check' target supports parallel runs, and
+it also creates a `.prove' file to optimize `make check-run'.
+
+The prove(1) command (distributed with Perl) may also be used
+for finer-grained testing: prove -bvw t/foo.t
+
+If using a make(1) (e.g. GNU make) with `include' support, the
+`config.mak' Makefile snippet can be used to set environment
+variables such as PERL_INLINE_DIRECTORY and TMPDIR.
+
+With PERL_INLINE_DIRECTORY set to enable Inline::C support and
+TMPDIR pointed to a tmpfs(5) mount, `make check-run' takes 6-10s
+(load-dependent) on a busy workstation built in 2010.
+
 Perl notes
 ----------
 

diff --git a/INSTALL b/INSTALL
index 3984df718f95684c28865fba89812d18a42b8ef9..2dd7dcff7013303091575e3c7e818a1fd50a6c8a 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -191,7 +191,7 @@ install the system (into /usr/local) with:
 
         perl Makefile.PL
         make
-        make test
+        make test    # see HACKING for faster tests for hackers
         make install # root permissions may be needed
 
 When installing Search::Xapian, make sure the underlying Xapian