Re: [perl #127885] [patches] enhance bench.pl to test same perlunder different options/args

From ad87327bb240bd41ab1199b1cce38cf79f369571 Mon Sep 17 00:00:00 2001
From: Jim Cromie <jim.cromie@gmail.com>
Date: Sun, 10 Apr 2016 07:46:40 -0600
Subject: [PATCH 14/14] add pod for PUT

add =head2 PERLS UNDER TEST, right after DESCRIPTION

Its a bit light on =markup.
C<=label> didnt work (markup) for me.
Its also light on noting ':' vs '=' separator
---
 Porting/bench.pl | 47 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/Porting/bench.pl b/Porting/bench.pl
index a03b5d5..1009bc0 100755
--- a/Porting/bench.pl
+++ b/Porting/bench.pl
@@ -21,6 +21,20 @@ perls.
 
     bench.pl [options] -- perlA=fast PerlA=slow -Mstrict -Dpsltoc 
 
+    # run tests on ./perl, in several ways
+    # use per PUT ENV and args to modify workload
+
+    export PBENCH_PL=' --verbose --write=./bench-runs/ --git '
+    bench.pl [opts] -- \
+	./perl=+bare \
+	./perl=+Dq -Dq \
+	./perl:+traceops:PERL_TRACE_OPS=0 \
+	./perl:+memlog:PERL_MEM_LOG=3mst \
+	./perl:+trcDq:PERL_TRACE_OPS=0 -Dq \
+	./perl:+memDq:PERL_MEM_LOG=3mst -Dq \
+	./perl:+trcmem:PERL_TRACE_OPS=0,PERL_MEM_LOG=3mst \
+	./perl:+trcmemDq:PERL_TRACE_OPS=0,PERL_MEM_LOG=3mst -Dq
+
     # Run bench.pl's own built-in sanity tests
 
     bench.pl --action=selftest
@@ -44,8 +58,37 @@ There are options to write the raw data to a file, and to read it back.
 This means that you can view the same run data in different views with
 different selection and sort options.
 
-The optional C<=label> after each perl executable is used in the display
-output.
+=head2 PERLS UNDER TEST
+
+One or more perls-under-test (PUTs) are expected on the command-line,
+after '--' terminates option processing.
+
+each PUT consists of:
+
+  a perl name or executable (path etc)
+  an optional =label (or :label :+label )
+  an optional ENV spec:
+    :PERL_MEM_LOG=3mst,PERL_TRACE_OPS=0
+
+  0 or more additional arguments, options
+  for example:
+    -Dq -Ilib -MDevel::Peek -e'"BEGIN{runops_debug(1)}"'
+
+The label defaults to perl-name, and must be unique.  It is used to
+store and display the results.  :+label appends the label, rather than
+overriding the default.
+
+Arguments and Environment can be given to alter the workload imposed
+by the tests.  See the 2nd SYNOPSIS example, and note the following:
+
+ each line after -- is a separate PUT
+ all PUTs are using ./perl, other perls on $PATH work too
+ 1st 2 PUTs use '=' to define labels
+ other PUTs use ':' alternative
+ all PUTs have distinct labels (required)
+ all PUTs use +label to append rather than override the default
+ 2nd PUT has -Dq option.  this has surprising cost.
+ PERL_MEM_LOG=3mst is quite expensive (as one would expect)
 
 =head1 OPTIONS
 
-- 
2.5.5

• [perl #127885] [patches] enhance bench.pl to test same perl underdifferent options/args by Tony Cook via RT
• Re: [perl #127885] [patches] enhance bench.pl to test same perlunder different options/args by Jim Cromie