Project Fairdice
[Home] [Docs] [Users] [Gaming] [Crypto] [Devel] [Download] [Help]

Users

Caveats

The fairdice client and server apps are currently in ALPHA release. (This means: they are unreliable and will crash)

There are no fairdice enabled user or hosts apps. Dummy user and host apps are supplied with the development kit download, but they can only be used for testing the code and the protocol, not for playing actual games.

The development kit (client, server, dummy user, dummy host, test harness) has only been tested on cygwin (a unix emulator that runs under windows). If you don't use exactly the same set up, it many not compile, let alone run.

How to install and use the Fairdice apps

If, after reading the caveats, you still want to have a go at installing and running the fairdice apps, here is a step by step guide. It assumes you have already downloaded the base and external modules. If you have not, go now to the download page and do so first.

Install External

You will need to install: 
Windows

Cygwin (including bash, make and gcc)

Install Tom's Crypt Library (tested against v0.96):
       http://libtomcrypt.org/download.html
       (included in external module)

Install the GNU Multiple Precision Arithmetic Library
       http://www.swox.com/gmp/
       (included in external module)

Install the Expat XML Parser Toolkit
       http://sourceforge.net/projects/expat/
       (included in external module)

Install SCEW
       http://www.nongnu.org/scew/
       (included in external module)

If you want to generate your own docs, you will also need Doxygen
       http://www.stack.nl/~dimitri/doxygen/
       (included in external module)

Install Base

1. sanity check the first section of the the MAKEFILE

2. type "make"

3. pray

Run the tests

All commands should be run from the base directory, as they will refer to other files relative to that.

exec/frdi_test.exe This should give a long output to stdout (and a little to stderr). Some of the tests require human scrutiny for verification (yes, this ought to be changed. It is on the todo list). The actual tests are in the tests/ subdirectory. If you get any fails, examine your installs of the external applications, make sure you have all the include and library files on the relevant paths. You may well need to re-edit the make file and recompile. If you are unlucky you may find yourself having to port the thread code.

Run the scenarios

Scenarios cannot be run simultaneously (due to port usage).

Each one can be run either manually, by running each executable with the appropriate config file from a different bash shell or automatically by running a script which launches all the applications. Note that for timing purposes all the applications in a scenario should be launched within a second or two of each other. (yes, this is bad, please please come write a decent test harness for me.)

To run scenario single call the script scenario/single/bin/scenario_single.sh. (You will probably find it easiest to add each of the scenario specific bin directories to your path or use simlinks).

Check the scenario results

Look in the relevant scenario directory (eg scenario/single) for .stackdump files. Then proceed to look at the log files (eg scenario/single/logs). For each instance of an application there will be three files:
.std Standard out
.err Standard error
.log the user log
What these contains will depend on the flags you set in the XML config file for that instance (look in scenario/single/conf). Each flag may be either "YES" or "NO". For advanced manipulation you can also pass various #define flags to make such as SILENT.
Verbose
YES puts lots of debug information in .std, NO is silent
THREAD
put a thread identifier on each line of .log
TIME
puts a time identifier on each line of .log
MESSAGETEXT
put the exact text of each message sent on the wire to .log
MESSAGEBYTES
records the total bytes sent and received per connection in .log
RESULT
puts a user readable game summary in all three files
In general, if there is a game summary for each game played on each application, and there is a total bytes summary for each connection then the scenario ran correctly. Well done!

If things go wrong

If the software won't install correctly, or they install but crash, then please remember this is ALPHA software, and consider joining the development team to port to your platform or improve stability.

If the software runs without crashing but does the wrong thing (for instance, incorrectly verifies a usertext against a digest you have deliberately corrupted), please see the contact page for how to report the bug.

(TOP)(UP)