perf/README

   1 General info
   2 ============
   3
   4 A couple of parts make up the performance suite:
   5
   6 * perf-suite-tool - a simple tool that runs a given (HTML) test with given
   7   settings (passed via command line) and outputs the results to an XML file.
   8
   9 * perf-suite-runner - the main tool that runs the whole performance suite
  10   according to the drtlist.xml file describing the tests and puts the results
  11   in the database.
  12
  13 * perf-suite-generator - generates an up-to-date HTML report file by
  14   processing the current data in the database.
  15
  16 * perf-suite-set - contains the tests. Index in drtlist.xml.
  17
  18 * perf-report - the index.html file is generated here by the
  19   perf-suite-generator.
  20
  21
  22 Running the suite
  23 =================
  24
  25 To run an iteration of the performance tests (and generate the results) one
  26 needs to run the perf-suite-runner and later perf-suite-generator. The easiest
  27 way to do that is:
  28
  29   $> make run-perf
  30
  31 To view the results, open perf-report/index.html in your web browser.
  32
  33
  34 Configuring runs (passes)
  35 =========================
  36
  37 Each iteration of the performance tests (a "pass") can have some data
  38 associated with it. This data (if available) is displayed in the report. The
  39 basic pass data includes:
  40
  41 * Short name - a short name of the pass, ie. revision number ("r1212121")
  42 * Author - author associated with the pass, ie. commiter ("michael")
  43 * ChangeLog - changelog entry associated with the pass
  44
  45 Those options can be specified via command line when running the tools (use
  46 --help switch to get more details). Additionally, one can use env vars to
  47 set them. Respective variables are:
  48
  49 * PERF_SHORT_NAME
  50 * PERF_AUTHOR
  51 * PERF_CHANGE_LOG
  52
  53 So, in example, to set the short name:
  54
  55   $> PERF_SHORT_NAME="r123" PERF_AUTHOR="mdk" make run-perf
  56
  57 Options passed via command line have higher precedence than those passed via
  58 env variables. The `make` command runs the tools with no cmd line options.
  59
  60 Additionally, the PERF_DATABASE_FILE variable can be used to specify a
  61 location for storing the results.
  62
  63
  64 Auto running with SVN data
  65 ==========================
  66
  67 To have all the meta-data fetched automatically from the (current) SVN repository,
  68 run:
  69
  70   $> svn-dispatcher
  71
  72 This is mostly meant for automated scripts.
  73
  74
  75 Running single test
  76 ===================
  77
  78 To run a single test (without storing the results in the database) use the PERF_TEST_ID
  79 variable. In example:
  80
  81   $> PERF_TEST_ID="1" make run-perf
  82
  83 The results of this run will only be printed to the console.