# $Id: README,v 1.5 2007/05/29 17:32:27 bostic Exp $

A simple framework for core Berkeley DB micro-benchmarks, intended for
two purposes: to certify a port of Berkeley DB to a new platform, and
to provide micro-benchmark information between different Berkeley DB
releases.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
To run the tests:

1. Unpack and build the Berkeley DB releases you want to run against.

2. Run the tests:

	% sh test_micro

   By default, tests are run for all of the Berkeley DB builds found in
   the current working directory.  A build is identified by its top-level
   name, and is expected to be of the form:

	   db-<major>.<minor>.<patch>

   and the fact the Berkeley DB library has been built in the standard
   location in that directory tree (for example, in "build_unix".
   Directories with other names and directories without a library will
   be ignored.

   You can run a subset of the tests using command-line arguments:

	% sh test_micro 3			# Run test 3
	% sh test_micro 3-5			# Run tests 3-5
	% sh test_micro 3-			# Run test 3 to the maximum test
	% sh test_micro -3			# Run tests 1-3

   You can run on a subset of the releases using the MAJOR and MINOR
   environment variables:

	% env MAJOR=4 MINOR=2 sh test_micro	# Run on 4.2.XX
						# Run on 4.1.XX and 4.2.XX
	% env MAJOR=4 MINOR='[12]' sh test_micro

3. If you want to generate the micro-benchmark output build the HTML
   page after the run:

	% sh test_micro html

   The output of the tests and the web page are created in the directory
   RUN.hostname (for example, "RUN.abyssinian").  The tests are numeric
   filenames (for example, "1", "2", "36").  The web page output is in the
   file "test_micro.html".

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
To add a new test program:

1. Add a new file to the SOURCE directory.  If you're using gcc as your
   compiler, the default compile line is:

	gcc -O3 -Wall -lpthread -I. source.c -o t libdb.a

   otherwise, the default compile line is

	cc -O2 -I. source.c -o t libdb.a

   If your compiler offers different or better optimization, and you're
   running the script to output benchmark results, you should change the
   run script to take advantage of your compiler's optimization options.

   The file must output the following line on stdout:

	# title
	major.minor.patch<tab>operations/second

   For example:

	# 10000 Btree database open/close pairs
	3.0.55  29600.69
	3.1.17  30438.25

2. Add a new line to the "runone" function in the shell script "test_micro"
   as follows:

	#) runone $1 source-file "./t command-line";;

   For example:

	27) runone $1 b_curwalk.c "./t -c 100000 -t btree -w 100";;
	28) runone $1 b_curwalk.c "./t -c 100000 -t hash" -w 100;;
	29) runone $1 b_curwalk.c "./t -c 100000 -t queue" -w 100;;
	30) runone $1 b_curwalk.c "./t -c 100000 -t recno" -w 100;;

3. Update the value of the shell script "test_micro" variable "maxtest" to
   be the new maximum test number.
