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

   1 Pre-requisites
   2 --------------
   3
   4 In addition to having notmuch, you need:
   5
   6 - gpg
   7 - gnu tar
   8 - gnu time
   9 - xz. Some speedup can be gotten by installing "pixz", but this is
  10   probably only worthwhile if you are debugging the tests.
  11
  12 Getting set up to run tests:
  13 ----------------------------
  14
  15 First, you need to get the corpus.  If you don't already have the gpg
  16 key for David Bremner, run
  17
  18    % gpg --search 'david@tethera.net'
  19
  20 This should get you a key with fingerprint
  21
  22     815B 6398 2A79 F8E7 C727  86C4 762B 57BB 7842 06AD
  23
  24 (the last 8 digits are printed as the "key id").
  25
  26 To fetch the actual corpus it should work to run
  27
  28    % make download-corpus
  29
  30 In case that fails or is too slow, check
  31
  32    http://notmuchmail.org/corpus
  33
  34 for a list of mirrors.
  35
  36 Running tests
  37 -------------
  38
  39 The easiest way to run performance tests is to say "make time-test", (or
  40 simply run the notmuch-time-test script). Either command will run all
  41 available performance tests.
  42
  43 Alternately, you can run a specific subset of tests by simply invoking
  44 one of the executable scripts in this directory, (such as ./basic).
  45 Each test script supports the following arguments
  46
  47 --small / --medium / --large    Choose corpus size.
  48 --debug                         Enable debugging. In particular don't delete
  49                                 temporary directories.
  50
  51 Writing tests
  52 -------------
  53
  54 Have a look at "T01-dump-restore" for an example. Sourcing
  55 "perf-test-lib.sh" is mandatory.  Utility functions include
  56
  57 - 'add_email_corpus' unpacks a set of messages and adds them to the database.
  58 - 'cache_database': makes a snapshot of the current database
  59 - 'uncache_database': forces the next 'add_email_corpus' to rebuild the
  60   database.
  61 - 'time_start' unpacks the mail corpus and calls notmuch new if it
  62    cannot find a cache of the appropriate corpus.
  63 - 'time_done' does the cleanup; comment it out or pass --debug to the
  64   script to leave the temporary files around.
  65
  66 Scripts are run in the order specified in notmuch-perf-test. In the
  67 future this order might be chosen automatically so please follow the
  68 convention of starting the name with 'T' followed by two digits to
  69 specify the order.