commands/worldstone/worldstone.1

   1 .Dd $Mdocdate: September 22 2011 $
   2 .Dt WORLDSTONE 1
   3 .Os
   4 .Sh NAME
   5 .Nm worldstone
   6 .Nd shell script to consistently execute benchmarks
   7 .Sh SYNOPSIS
   8 .Nm worldstone
   9 .Op Fl n Ar iterations
  10 .Op Fl c Ar command
  11 .Op Fl p Ar command
  12 .Op Fl t Ar tag
  13 .Sh DESCRIPTION
  14 The
  15 .Nm
  16 utility is a shell script and takes care of some of the
  17 grunt work around benchmarking, in order to make it easier
  18 to get consistent and comparable benchmark results. Its basic
  19 operation is: execute the precommand, then execute and time
  20 the command, and do this a set number of iterations, and record
  21 the times in a logfile.
  22
  23 Its features are:
  24 .Bl -tag -width Ds
  25 .It -
  26 It executes the precommand and command once without timing it
  27 in order to mitigate cold cache effects.
  28 .It -
  29 It allows a precommand to run before the command, so that the initial
  30 state can be set up by the precommand without it being part of the timing
  31 (e.g. make clean).
  32 .It -
  33 It redirects the stdout and stderr to /dev/null so that lots of output
  34 going over a network connection doesn't influence timing.
  35 .It -
  36 It does a sync before running the timed command, and makes sure a final
  37 sync is part of the timed command, to make the i/o more consistent.
  38 .It -
  39 It logs the times of each iteration in an easy-to-parse logfile.
  40 .It -
  41 It tries to guess a sensible log file name based on the current git
  42 branch in /usr/src.
  43 .El
  44
  45 The options are as follows:
  46 .Bl -tag -width Ds
  47 .It Fl n Ar iterations
  48 Set the number of iterations to perform, after the initial run.
  49 The default is 5.
  50 .It Fl c Ar command
  51 Set the command to run to be timed. This is passed to sh -c, so shell constructs
  52 like loops etc. are okay to do. Default: make all.
  53 .It Fl p Ar command
  54 Set the pre-command to run. This command gets run before the timed command in order
  55 to make the timed command get a consistent state before it starts.
  56 Default: make clean.
  57 .It Fl t Ar tag
  58 Use the given tag name to modify the logfile that the utility uses
  59 to write its results in. The default is just 'time' plus the git branch you
  60 are currently on in /usr/src. In order for this to be useful you have to make sure the
  61 git branch you are on reflects the system you wish to benchmark of course.
  62 The script checks /usr/src/.git even if you are outside the /usr/src hierarchy
  63 (such as in pkgsrc).
  64 .El
  65
  66 The script executes the commands the set number of iterations, redirecting stdout
  67 and stderr to /dev/null, and records the timed results in the logfile tagged with
  68 the given tag.
  69 .Nm
  70 executes
  71 .Xr time 1
  72 with the -C option, resulting in printing the 64-bit cpu cycle counter
  73 for both HZ-independent high resolution and an easy way not to have to convert minutes
  74 and seconds to seconds when parsing the results.
  75 .Pp
  76 You can feed the two separate logfiles directly to
  77 .Xr ministat 1
  78 to have it tell you the statistical properties of the two datasets, and judge whether
  79 there is a statistically significant difference.
  80 .Sh ENVIRONMENT
  81 The default commands, i.e. make all and make clean, can be modified by supplying a MAKE
  82 environment variable, so e.g. MAKE=bmake worldstone still does something sensible
  83 by default in /usr/pkgsrc directories.
  84 .Sh SEE ALSO
  85 .Xr ministat 1