Merge branch 'readme' into 'master'

Add readme and local integration test running script

See merge request privategrity/integration!20

.gitignore

@@ -5,3 +5,6 @@ bin/*
 *results*
 */.udb-cMix-session
 blob*
+# Vim swap files
+*.swp
+*.swo

README.md

+# Integration
+
+## Purpose
+This is to automatically test all the system's components and make sure they 
+work together correctly. If the integration test passes, it should guarantee
+that clients can send messages all the way through the system, including 
+mixing with multiple nodes and an anonymity set greater than 1. If the 
+integration test fails, look at the logs and narrow down the cause by adding
+more logging statements if necessary.
+
+## How to manually run locally
+
+1. Build the binaries under test for your operating system and place them in 
+the `bin` directory.
+1. `cd` to `basice2e/` and run `run.sh`. Observe the results and inspect the 
+logs if things go wrong.
+1. Make changes to the `run.sh` script, config files, and binaries as needed
+based on your analysis of the logs. You may want to add more logging or build
+the binaries under test with race condition checking to track down problems.
+
+## What runs on continuous integration?
+
+The `master` branch of integration runs whenever you merge anything to the 
+`master` branch of any of the projects that integration tests. The CI server 
+downloads the latest `master` branch binaries that any CI server built and 
+uses them to run `basice2e/run.sh`.
+
+The benchmark branch of integration runs nightly and produces information about
+how fast the software runs. It doesn't provide the full performance picture 
+because it runs on one modest CI server, rather than on a team of powerful 
+servers. However, the information it provides is sometimes useful.
+
+So, if you make changes that break integration and merge the fixes to the 
+`master` branch of integration, you ought to also merge the `master` branch
+into the `benchmark` branch so that the benchmarks will continue to function.
+
+## Automate running locally
+
+`build.sh` generates version information for all repositories under test and
+builds binaries for them in the `bin/` directory.
+
+`update.sh` runs `git pull` for each repo under test, and by uncommenting the
+relevant code, checks out the `master` branch of each repo before pulling. This 
+is the most useful if you're trying to fix an integration breakage in 
+`master` and you want to get started right away.
+
+In the root directory of integration, `run.sh` builds new binaries with
+`build.sh`, runs the `basice2e` integration test, and opens all the log files
+in `gedit` for easy viewing.  If you prefer some other program to view the
+resulting logs, set the INTEGRATION\_EDITOR environment variable:
+
+`INTEGRATION_EDITOR=emacs ./run.sh`
+
+If you need to make a lot of exploratory changes to get things integrated,
+using these utility scripts can speed up the process.
+

run.sh

+#!/bin/bash
+
+# Build
+./build.sh
+
+# Run
+pushd basice2e
+./run.sh
+popd
+
+# View result logs
+# Not using $EDITOR or $VISUAL because many editors that people set those to
+# don't have as easy support for viewing multiple files
+${INTEGRATION_EDITOR:-gedit} ./basice2e/results/clients/*.out ./basice2e/results/servers/*.console ./basice2e/results/gateway.log ./basice2e/results/channelbot.console&