test_micro/README

   1 # $Id$
   2
   3 A simple framework for core Berkeley DB micro-benchmarks, intended for
   4 two purposes: to certify a port of Berkeley DB to a new platform, and
   5 to provide micro-benchmark information between different Berkeley DB
   6 releases.
   7
   8 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
   9 To run the tests:
  10
  11 1. Unpack and build the Berkeley DB releases you want to run against.
  12 (Note that test_micro is only known to work on release 4.0 and later.)
  13
  14 2. Run the tests:
  15
  16         % sh test_micro
  17
  18    By default, tests are run for all of the Berkeley DB builds found in
  19    the current working directory.  A build is identified by its
  20    top-level name, and is expected to be of the form:
  21
  22            db-<major>.<minor>.<patch>
  23
  24    and the fact the Berkeley DB library has been built in the standard
  25    location in that directory tree (for example, "build_unix/libdb.a".
  26    Directories with other names and directories without a library will
  27    be ignored.
  28
  29    You can run a subset of the tests using command-line arguments:
  30
  31         % sh test_micro 3                       # Run test 3
  32         % sh test_micro 3-5                     # Run tests 3-5
  33         % sh test_micro 3-                      # Run test 3 to the maximum test
  34         % sh test_micro -3                      # Run tests 1-3
  35
  36    You can run on a subset of the releases using the MAJOR and MINOR
  37    environment variables:
  38
  39         % env MAJOR=4 MINOR=2 sh test_micro     # Run on 4.2.XX
  40                                                 # Run on 4.1.XX and 4.2.XX
  41         % env MAJOR=4 MINOR='[12]' sh test_micro
  42
  43 3. If you want to generate the micro-benchmark output build the HTML
  44    page after the run:
  45
  46         % sh report
  47
  48    The output of the tests and the web page are created in the directory
  49    RUN.hostname (for example, "RUN.abyssinian").  The tests are numeric
  50    filenames in that directory (for example, "1", "2", "36").  The web
  51    page output is in the file "hostname.html".
  52
  53 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  54 To run different test configurations:
  55
  56 1. Modify the configuration files in the configs/ directory to run the
  57    tests you want to run.  The configuration file configs/run.std is the
  58    tests that are run by the test_micro shell script.
  59
  60 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
  61 To add a new test program:
  62
  63 1. Add a new file to the SOURCE directory, and build it as part of
  64    building the test_micro program.   This will require changes to
  65    the test_micro shell script, as well as the standard build rules
  66    for all of the Berkeley DB systems, found in the dist/ directory.
  67
  68    The file must output the following line on stdout:
  69
  70         # title
  71         major.minor.patch<tab>operations/second
  72
  73    For example:
  74
  75         # 10000 Btree database open/close pairs
  76         3.0.55  29600.69
  77         3.1.17  30438.25
  78
  79 2. Modify the file test_micro/test_micro.c to exec your new command
  80    (this should only require changing the cmdlist structure at the top
  81    of that file).
  82
  83 3. Modify the test_micro configuration files in the configs/ directory
  84    to run your new command.