readme updates

README.md

@@ -6,6 +6,7 @@
 ![Stability: experimental](https://img.shields.io/badge/stability-experimental-orange.svg)
 
 Join the Status community chats:
+[![Gitter: #status-im/nimbus](https://img.shields.io/badge/gitter-status--im%2Fnimbus-orange.svg)](https://gitter.im/status-im/nimbus)
 [![Riot: #dev-status](https://img.shields.io/badge/riot-%23dev--status%3Astatus.im-orange.svg)](https://chat.status.im/#/room/#dev-status:status.im)
 [![Riot: #nimbus](https://img.shields.io/badge/riot-%23nimbus%3Astatus.im-orange.svg)](https://chat.status.im/#/room/#nimbus:status.im)
 
@@ -17,11 +18,12 @@ Join the Status community chats:
 
 ### Prerequisites
 
-Please install a recent version of Facebook's RocksDB following the instructions here:
+* A recent version of Nim
-
+  * We use the version in the [Status fork](https://github.com/status-im/Nim)
-https://github.com/facebook/rocksdb/blob/master/INSTALL.md
+  * Normally, this is the latest released version of Nim but it may also include custom patches
-
+  * Follow the Nim installation instructions or use [choosenim](https://github.com/dom96/choosenim) to manage your Nim versions
-Currently Nimbus requires the latest development version of the Nim programming language. Follow the [installation steps](https://github.com/nim-lang/Nim) or use [choosenim](https://github.com/dom96/choosenim).
+* A recent version of Facebook's [RocksDB](https://github.com/facebook/rocksdb/)
+  * Compile [from source](https://github.com/facebook/rocksdb/blob/master/INSTALL.md) or use the package manager of your OS
 
 ### Obtaining the prerequisites through the Nix package manager
 
@@ -33,19 +35,40 @@ nix-shell nimbus.nix
 
 ### Build
 
-You can build the package and run the tests using `nimble test`. You can run the example using `nim compile --run examples/decompile_smart_contract.nim`.
+We use [Nimble](https://github.com/nim-lang/nimble) to manage dependencies and run tests.
 
-You can run the official Ethereum JSON tests for the EVM this way:
+To build and run test suite:
-
+```bash
-create a `./build` directory with `mkdir build` in your cloned repository.
+nimble test
-
-Run
-
-```
-nim c -r --nimcache:nimcache -o:build/test tests/test_vm_json.nim
 ```
 
-The executable will be put in `build`, and nim compilation cache will use `nimcache`.
+Based on our config, Nimble will write binaries to `build/` - you can do this manually also, as in the following examples:
+
+Run example:
+```bash
+mkdir -p build
+nim c -o:build/decompile_smart_contract -r examples/decompile_smart_contract.nim
+```
+
+Run Ethereum [JSON-based VM tests](https://github.com/ethereum/tests/):
+```
+mkdir -p build
+nim c -o:build/test_vm_json -r tests/test_vm_json.nim
+```
+
+#### Troubleshooting
+
+Sometimes, the build will fail even though the latest CI is green - here are a few tips to handle this:
+
+* Wrong Nim version
+  * We depend on many bleeding-edge features - Nim regressions often happen
+  * Use the [Status fork](https://github.com/status-im/Nim) of Nim
+* Wrong versions of dependencies
+  * nimble dependency tracking often breaks due to its global registry
+  * wipe the nimble folder and try again
+* C compile or link fails
+  * Nim compile cache is pretty buggy and sometimes will fail to recompile
+  * wipe your nimcache folder
 
 ## License