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
  20 Getting set up to run tests:
  21 ----------------------------
  22
  23 First, you need to get the corpus.  If you don't already have the gpg
  24 key for David Bremner, run
  25
  26    % gpg --search 'david@tethera.net'
  27
  28 This should get you a key with fingerprint
  29
  30     815B 6398 2A79 F8E7 C727  86C4 762B 57BB 7842 06AD
  31
  32 (the last 8 digits are printed as the "key id").
  33
  34 To fetch the actual corpus it should work to run
  35
  36    % make download-corpus
  37
  38 In case that fails or is too slow, check
  39
  40    http://notmuchmail.org/corpus
  41
  42 for a list of mirrors.
  43
  44 Running tests
  45 -------------
  46
  47 The easiest way to run performance tests is to say "make perf-test".
  48 This will run all time and memory tests.  Be aware that the memory
  49 tests are quite time consuming when run on the full corpus, and that
  50 depending on your interests it may be more sensible to run "make
  51 time-test" or "make memory-test".  You can also invoke one of the
  52 scripts notmuch-time-test or notmuch-memory-test or run a more
  53 specific subset of tests by simply invoking one of the executable
  54 scripts in this directory, (such as ./T00-new).  Each test script
  55 supports the following arguments
  56
  57 --small / --medium / --large    Choose corpus size.
  58 --debug                         Enable debugging. In particular don't delete
  59                                 temporary directories.
  60
  61 When using the make targets, you can pass arguments to all test
  62 scripts by defining the make variable OPTIONS.
  63
  64 Writing tests
  65 -------------
  66
  67 Have a look at "T01-dump-restore" for an example time test and
  68 "M00-new" for an example memory test. In both cases sourcing
  69 "perf-test-lib.sh" is mandatory.
  70
  71 Basics:
  72
  73 - '(time|memory)_start' unpacks the mail corpus and calls notmuch new if it
  74    cannot find a cache of the appropriate corpus.
  75 - '(time|memory)_run' runs the command under time or valgrind. Currently
  76   "memory_run" does not support i/o redirection in the command.
  77 - '(time|memory)_done' does the cleanup; comment it out or pass --debug to the
  78   script to leave the temporary files around.
  79
  80 Utility functions include
  81
  82 - 'add_email_corpus' unpacks a set of messages and tags
  83 - 'cache_database': makes a snapshot of the current database
  84 - 'uncache_database': forces the next '(time|memory)_start' to rebuild the
  85   database.
  86
  87 Scripts are run in the order specified in notmuch-perf-test. In the
  88 future this order might be chosen automatically so please follow the
  89 convention of starting the name with 'T' or 'M' followed by two digits
  90 to specify the order.