all: pull in dependencies, write up usage readme

README.md

@@ -14,9 +14,36 @@ adherence to official specs or behaviours under different circumstances.
 Most importantly, it is essential to be able to run this test suite as part of the CI workflow! To
 this effect the entire suite is based on docker containers.
 
+# Installing the hive validator
+
+The `hive` project is based on Go. Although there are plans to make running `hive` possible using
+only docker, for now you'll need a valid Go (1.6 and upwards) installation available.
+
+You can install `hive` via:
+
+```
+$ go get github.com/karalabe/hive
+```
+
+*Note: For now `hive` requires running from the repository root as it needs access to quite a number
+of resource files to build the corrent docker images and containers. This requirement will be removed
+in the future.*
+
 # Validating clients
 
-todo
+You can run the full suite of `hive` validation tests against all the known implementations tagged
+`master` by simply running `hive` from the repository root. It will build a docker image for every
+known client as well as one for every known validation test. **As this make take a while, you can
+track the detailed progress in the `log.txt` file.
+
+The end result should be a JSON report, detailing for each client the list of validations failed and
+those passed. If you wish to explore the reasons of failure, full logs from all clients and testers
+are pushed into the `log.txt` log file.
+
+You may request a different set of clients to be validated via the `--validate` regexp flag (e.g.
+validating all `go-ethereum` versions would be `--validate go-ethereum:`). Similarly you may request
+only a subset of validation tests to be run via the `--validators` regexp flag (e.g. running only the
+smoke tests would be `--validators smoke/.`).
 
 # Adding new clients
 

hive.go

@@ -22,12 +22,13 @@ const (
 )
 
 var (
-	dockerEndpoint = flag.String("docker-endpoint", "unix:///var/run/docker.sock", "Unix socket to th local Docker daemon")
-	smokeClient    = flag.String("smoke", "", "Regexp selecting the client(s) to smoke-test")
-	validateClient = flag.String("validate", "[^:]+:develop", "Regexp selecting the client(s) to validate")
-	overrideClient = flag.String("override", "", "Client binary to override the default one with")
-	noImageCache   = flag.Bool("nocache", false, "Disabled image caching, rebuilding all modified docker images")
-	loglevelFlag   = flag.Int("loglevel", 3, "Log level to use for displaying system events")
+	dockerEndpoint   = flag.String("docker-endpoint", "unix:///var/run/docker.sock", "Unix socket to th local Docker daemon")
+	smokePattern     = flag.String("smoke", "", "Regexp selecting the client(s) to smoke-test")
+	validatePattern  = flag.String("validate", "[^:]+:master", "Regexp selecting the client(s) to validate")
+	validatorPattern = flag.String("validators", ".", "Regexp selecting the validation tests to run")
+	overrideClient   = flag.String("override", "", "Client binary to override the default one with")
+	noImageCache     = flag.Bool("nocache", false, "Disabled image caching, rebuilding all modified docker images")
+	loglevelFlag     = flag.Int("loglevel", 3, "Log level to use for displaying system events")
 )
 
 func main() {
@@ -54,16 +55,16 @@ func main() {
 	log15.Info("docker daemon online", "version", env.Get("Version"))
 
 	switch {
-	case *smokeClient != "":
+	case *smokePattern != "":
 		// If smoke testing is requested, run only part of the validators
-		if err := validateClients(daemon, *smokeClient, "smoke/.", *overrideClient, true); err != nil {
+		if err := validateClients(daemon, *smokePattern, "smoke/.", *overrideClient, true); err != nil {
 			log15.Crit("failed to smoke-test client images", "error", err)
 			return
 		}
 
-	case *validateClient != "":
+	case *validatePattern != "":
 		// If validation is requested, run only the standalone tests
-		if err := validateClients(daemon, *validateClient, ".", *overrideClient, *noImageCache); err != nil {
+		if err := validateClients(daemon, *validatePattern, *validatorPattern, *overrideClient, *noImageCache); err != nil {
 			log15.Crit("failed to validate client images", "error", err)
 			return
 		}