git.notmuchmail.org Git - notmuch/blob - performance-test/README

   1 Performance Tests
   2 -----------------
   3
   4 This directory contains two kinds of performance tests: time tests,
   5 and memory tests. The former use gnu time, and the latter use
   6 valgrind.
   7
   8 Pre-requisites
   9 --------------
  10
  11 In addition to having notmuch, you need:
  12
  13 - gpg
  14 - gnu tar
  15 - gnu time (for the time tests)
  16 - xz. Some speedup can be gotten by installing "pixz", but this is
  17   probably only worthwhile if you are debugging the tests.
  18 - valgrind (for the memory tests)
  19 - perf (optional, for more fine-grained timing)
  20
  21 Getting set up to run tests:
  22 ----------------------------
  23
  24 First, you need to get the corpus.  If you don't already have the gpg
  25 key for David Bremner, run
  26
  27    % gpg --search 'david@tethera.net'
  28
  29 This should get you a key with fingerprint
  30
  31     815B 6398 2A79 F8E7 C727  86C4 762B 57BB 7842 06AD
  32
  33 (the last 8 digits are printed as the "key id").
  34
  35 To fetch the actual corpus it should work to run
  36
  37    % make download-corpus
  38
  39 In case that fails or is too slow, check
  40
  41    https://notmuchmail.org/corpus
  42
  43 for a list of mirrors.
  44
  45 Running tests
  46 -------------
  47
  48 The easiest way to run performance tests is to say "make perf-test".
  49 This will run all time and memory tests.  Be aware that the memory
  50 tests are quite time consuming when run on the full corpus, and that
  51 depending on your interests it may be more sensible to run "make
  52 time-test" or "make memory-test".  You can also invoke one of the
  53 scripts notmuch-time-test or notmuch-memory-test or run a more
  54 specific subset of tests by simply invoking one of the executable
  55 scripts in this directory, (such as ./T00-new).  Each test script
  56 supports the following arguments
  57
  58 --small / --medium / --large    Choose corpus size.
  59 --debug                         Enable debugging. In particular don't delete
  60                                 temporary directories.
  61 --perf                          Run perf record in place of /usr/bin/time. Perf output can be
  62                                 found in a log directory.
  63 --call-graph {fp,lbr,dwarf}     Call graph option for perf record. Default is 'lbr'.
  64
  65 When using the make targets, you can pass arguments to all test
  66 scripts by defining the make variable OPTIONS.
  67
  68 Log Directory
  69 -------------
  70
  71 The memory tests, and the time tests when option '--perf' is given
  72 save their output in a directory named as follows
  73
  74      log.$test_name-$corpus_size-$timestamp
  75
  76 These directories are removed by "make clean".
  77
  78 Writing tests
  79 -------------
  80
  81 Have a look at "T01-dump-restore" for an example time test and
  82 "M00-new" for an example memory test. In both cases sourcing
  83 "perf-test-lib.sh" is mandatory.
  84
  85 Basics:
  86
  87 - '(time|memory)_start' unpacks the mail corpus and calls notmuch new if it
  88    cannot find a cache of the appropriate corpus.
  89 - '(time|memory)_run' runs the command under time or valgrind. Currently
  90   "memory_run" does not support i/o redirection in the command.
  91 - '(time|memory)_done' does the cleanup; comment it out or pass --debug to the
  92   script to leave the temporary files around.
  93
  94 Utility functions include
  95
  96 - 'add_email_corpus' unpacks a set of messages and tags
  97 - 'cache_database': makes a snapshot of the current database
  98 - 'uncache_database': forces the next '(time|memory)_start' to rebuild the
  99   database.
 100
 101 Scripts are run in the order specified in notmuch-perf-test. In the
 102 future this order might be chosen automatically so please follow the
 103 convention of starting the name with 'T' or 'M' followed by two digits
 104 to specify the order.