
How to Install, Configure, and Run the CRUND Benchmark
======================================================

The benchmark consists of generic Driver and multiple *Load "backend"
classes that implement the benchmark's operations against different
persistence APIs, like ndbapi, clusterj, jdbc and more.

Certain APIs have external software dependencies whose paths need to be
adjusted in a global configuration file: ./env.properties

As build tools, plain make' and 'ant' are used for the Java, C++ sources
(no use of autoconf or cmake, edit Makefile.defaults if needed).

0) Required: [g]make, ant, JDK, C/C++ compiler

1) Configure CRUND

--> Copy the sample configuration files (*.properties, *.cnf, and *.ini)
        $ cp config_samples/* .

--> Edit the configuration file for paths and software dependencies:
        ./env.properties

    See in ./env.properties which sections are mandatory, which optional
    depending on which *Load classes are to be build and run.

--> Check the other files for cluster setup and benchmark run parameters:
        *.properties, *.cnf, *.ini

2) Build CRUND

--> Build dependencies once:
        $ make dep

--> Build debug or optimized binaries, classes:
        $ make dbg
        $ make opt

--> Lisdt supported make, ant targets:
        $ make help
        $ ant help

3) Start the Cluster and load benchmark schema

    CRUND's schema file:
        ./src/crund_schema.sql

    (Convenience scripts using ./env.properties in ./scripts)

4) Run CRUND

--> Configure the benchmark's dataset size and number of iterations in
        ./crundRun.properties

    Edit load-specific connection and run settings:
        ./crundNdbapi.properties
        ./crundNdbjtie.properties
        ./crundClusterj.properties
        ./crundMysql.properties
        ./crundOpenjpaMysql.properties

--> Run the benchmark's C++ or Java driver for specific loads:
        $ make run.ndbapi
        $ ant run.ndbjtie
        $ ant run.clusterj
        $ ant run.mysql
        $ ant run.clusterjdbc
        $ ant run.openjpa.mysql
        $ ant run.openjpa.clusterj

    For directly running binaries or Java classes, see classpath/libpath
    settings printed by the run.* targets; provide properties files as
    arguments, e.g.: ... -p crundRun.properties -p crundMysql.properties

--> Inspect the result files

    CRUND writes all measured time/memory values into a local log file:
        ./log_<dtate>_<time>.txt

    The data format is a tab-separated list, which can be easily imported
    into a spreadsheet application for further processing or charting.

5) Additional tips

--> Scripts for automated benchmark runs

     Run the Java/C++ driver on a *Load class and save the log files:
        $ cd ./scripts
        $ ./run_test.sh
        $ ./run_testcxx.sh

     Runs the Java driver on multiple *Load classes:
        $ ./run_tests.sh

--> The C++ classes can be build separately from
        src/crundndb/

--> The load-specific Java classes can be build separatly:
        $ ant compile.ndbjtie
        $ ant compile.clusterj
        $ ant compile.jdbc
        $ ant compile.jpa
        $ ant compile      // builds all, skips on unconfigured dependencies
        $ ant compile.all  // builds all, fails on unconfigured dependencies

--> For possibly better timer resolution, see
    	martins_little_helpers/README.txt

    The MLH utilities are self-contained and can be build locally.
