notmuch-mutt: replace shell pipeline with internal pipe processing
[notmuch] / 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    https://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.