Merge pull request runziggurat#86 from eqlabs/docs/readme

readme: add prerequesite and logging, improve config

README.md

@@ -16,28 +16,74 @@ and [zebra](https://github.com/ZcashFoundation/zebra) devs with this reliable fo
 
 *Note:* This project is a work in progress.
 
+## Prerequisites
+
+Ziggurat is written in stable Rust; you can install the Rust toolchain by following the official instructions [here](*https://www.rust-lang.org/learn/get-started).
+
+You also need to install at least one node implementation to test.
+
+### ZCashd
+
+`zcashd` can be installed by using the [official instructions](https://zcash.readthedocs.io/en/latest/rtd_pages/zcashd.html) for your operating system. We recommend building from source for consistency and to ensure you're using the right versions. Alternatively, you can use ECC's Debian/Ubuntu package or the binary tarball.
+
+However, **please note that** **Docker is not supported** as it can theoretically produce unreliable test results and increases network complexity.
+
+```bash
+# After installing dependencies
+$ git clone https://github.com/zcash/zcash
+$ cd zcash
+$ git checkout v4.4.1            # optional, or use master
+$ ./zcutil/fetch-params.sh
+$ ./zcutil/clean.sh
+$ ./zcutil/build.sh -j$(nproc)   # or number of cores
+```
+
+After completing the above, you can skip the configuration steps, i.e. creating `~/.zcashd/zcash.conf` as Ziggurat will create new configuration files for each test run. Also, syncing the blockchain is not required.
+
+### `zebra`
+
+`zebra` can be installed from its [source code](https://github.com/ZcashFoundation/zebra) on GitHub. Although a Dockerfile is provided, **Docker is not supported.** We suggest following the instructions below, or similar.
+
+```bash
+# After installing dependencies
+$ git clone https://github.com/ZcashFoundation/zebra
+$ cd zebra
+$ cargo +stable build
+```
+
+Similarly to `zcashd`, configuration is not necessary since Ziggurat generates new configurations for each test run.
+
 ## Configuration
 
-Ziggurat is configured with a `config.toml` file in the root.
+Ziggurat is configured via a `config.toml` file in the root directory. It must contain the following fields:
 
+- `kind`: one of `zebra` or `zcashd`.
+- `path`: absolute path in which to run the start command.
+- `start_command`: the command used to start the node
+
+We recommend using the following ZCashd config:
+```toml
+kind = "zcashd"
+path = "path/to/zcash/repo"
+start_command = "./src/zcashd -debug=1 -printtoconsole -logips=1 -dnsseed=0 -dns=0 -listenonion=0"
+# debug=1           enables debug logging
+# logips=1          adds connection IP spans to the logs
+# printtoconsole    logs to stdout
+# dnsseed=0         disables looking for hardcoded DNS seeding nodes (we want to isolate our node to just the test)
+# dns=0             disables DNS lookup
+# listenonion=0     disables the Tor network
+```
+and for Zebra:
 ```toml
 kind = "zebra"
 path = "path/to/zebra/repo"
 start_command = "cargo +stable r -- --verbose start"
-
-# kind = "zcashd"
-# path = "path/to/zcash/repo"
-# start_command = "./src/zcashd -debug=1 -dnsseed=0 -printtoconsole -logips=1 -listenonion=0 -dns=0"
+# cargo +stable r   run Zebra using stable Rust
+# --                all args after this will get passed to Zebra
+# verbose           enables verbose logging
+# start             starts the node
 ```
 
-Information about the node to be tested can be set under the `[node]` table:
-
-- `kind`: one of `zebra` or `zcashd`
-- `path`: absolute path in which to run the start and stop commands.
-- `start_command`: the command used to start the node (args inline).
-
-When starting the node, this information and the configuration provided in the tests will be written to a configuration file compatible with and read by the node under test.
-
 ## Building the docs
 
 Ziggurat's documentation can be built with `cargo doc --no-deps --open`.
@@ -46,6 +92,23 @@ Ziggurat's documentation can be built with `cargo doc --no-deps --open`.
 
 Ziggurat currently uses rust's standard test runner, a simple `cargo test -- --test-threads=1` should suffice. We use the single threaded executor as spinning up multiple test nodes isn't currently supported.
 
+### Logging
+
+Logs are disabled by default, as they usually just add noise and slow down the test. They can be very useful for debugging and can be enabled on a test case level.
+
+Ziggurat's `SyntheticNode` supports `tracing` - this can be enabled by inserting a call to `synthetic_node::enable_tracing()` inside the test case.
+
+The test node's `stdout` and `stderr` logs can be piped to `stdout` by inserting a call to `node.log_to_stdout(true)` before starting the node. Note that logs will need to be enabled for the node as detailed in [Configuration](##Configuration).
+
+```Rust
+let mut node = Node::new().unwrap();
+node.initial_action(Action::WaitForConnection)
+    .log_to_stdout(true)    // pipe's the node's `stdout` and `stderr` to `stdout`
+    .start()
+    .await
+    .unwrap();
+```
+
 ## Test Status
 
 Short overview of test cases and their current status. In case of failure, the behaviour observed for `zebra` and `zcashd` is usually documented in the test case.