= repobench(1) =
:doctype: manpage

== NAME ==
repobench - generate and/or display reposurgeon benchmarks

== SYNOPSIS ==

repobench [-h] [-c cmd] [-p datafiles] [-o datafiles] [-s runtime|heap|highwater] [dumpfile min step max]

[[options]]
== OPTIONS ==

-c cmd::
    Pass cmd to reposurgeon before the stream-file read.

-h::
    Display option help

-p::
    Call the gnuplot interpreter to generate a graph

-o::
    Generate a graph in SVG format to stdout

-s style::
    Set which statistic to display in the graph. The
    default is runtime.

[[description]]
== DESCRIPTION ==

This script has two modes; generate or display.  They're
separated so that the expensive result from generate mode
can be kept around for repeated visualization.

=== GENERATE MODE

In generate mode (the default) it runs reposurgeon multiple times with
different readlimit values and writes out performance statistics for
each run to a datafile.  The name of that datafile is reported.

In display (-p) mode, a benchmark-data file is sent to gnuplot to
make a graph. An alternate display mode (with -o) ships the graph to
standard output as an SVG.

Generate mode takes four arguments, the dump file to read followed by
the minimum, step, and maximum values to use for readlimit.  The dump
file may be specified as a path relative to the current directory.
This leaves the following files in the current directory:

* A logfile for each conversion run. Extension .log.

* A *single* data file with lines correlating elapsed time to
  two measures of memory. One entry per run in the readlimit loop.
  Extension .dat.

The data will be recorded in a file named after the current git
revision, as an aid to comparing multiple historical revisions of
the code.

New data is simply appended to the end of the data file, so it is
useful to run this script multiple times with different step
values. For example, the GCC repository had ~280k revisions. Running
this first with a step of 50k to see a rough graph in a shorter
amount of time, followed by runs with smaller step values, such as
10k or 1k, is recommended.

Generate mode uses sudo to instruct the kernel to drop everything
from the file system cache between runs.

To change the behavior of reposurgeon you can user the -c option
to pass it a command-line argument.

=== DISPLAY MODE

Display mode with a single file argument takes a previously generated
datafile and renders it as a graph. Curve fitting is attempted. Use
the -p option for interactive gnuplot, or the -o option to ship an SVG
to stdout.  The -s option can be used to choose which statistic to
graph.

Giving multiple files with display mode suppresses curve fitting
and produces a comparative graph. The -o, -p, and -s options
are interpreted.  This mode is useful in checking for performance
regressions.

[[see_also]]
== SEE ALSO ==

reposurgeon(1).

[[author]]
== AUTHOR ==

Daniel Brooks, Eric S. Raymond. This tool is distributed with
reposurgeon; see the http://www.catb.org/~esr/reposurgeon[project
page].

// end
