Quick Start Guide For TH3

This note is a guide to using TH3 on a generic platform. See also notes for:

  1. Assemble your tools. You will need the following items on your development workstation:
    1. A cross-compiler for C that runs on your development platform and generates binaries for your target platform.

    2. A working version of the TCL programming language shell "tclsh". You need this for your development workstation only - not for your target platform. Your best bet is to download and install ActiveTcl or a Tclkit.

    3. A version of the SQLite library suitable for use on your target platform. We recommend using the SQLite amalgamation source code file to generate this library, but you are free to use any compilation process you are comfortable with.

    4. The TH3 source code. Unzip the ZIP archive into a directory on your development machine.

  2. Create test program source code by running a command like the following:

    tclsh mkth3.tcl cfg/*.cfg cov1/*.test >th3.c
    The "tclsh mkth3.tcl" part of this command is what runs the TH3 builder program. The output will appear on standard output. You can see that we have redirected that output into a file named "th3.c". (You can substitute any other filename you want, of course.) The arguments describe various test configuration files and test modules to be included as part of the test. The example above specifies the subset of the available test cases which provides 100% branch test coverage. The example loads 21 different configurations and over 600 different test modules and results in a test program that is over 100,000 lines and 6 megabytes in size. If the target platform is able to handle such large program, then all is well. If not, you may want to break the testing up into several smaller units.

  3. (OPTIONAL) Customize the operating-system interface: If the target does not support standard C-library interfaces such as exit() or fopen(), it might be necessary to customize the os interface by providing a small interface wrapper file.

  4. Compile your test program and link it against SQLite. A typical command-line will be something like this:

    cc -o th3 th3.c sqlite3.c -ldl -lpthreads
    The way you compile the program will depend heavily one what compiler you are using. The key point is that you need to compile the "th3.c" program created in the previous step and link it against the SQLite library.

  5. Run your test program on the target. Simply copy the output of the compiler onto the target and launch it. The program takes no command-line arguments. Testing status will appear on standard output. On a typical test arrangement, expect to see around a quarter megabyte of output from the test program. A summary of the results including a total error count appears at the end.