[docs] add BUILDING.md and link from root README.md

and make a few other touch ups in BUILDING.md and README.md, e.g. updating the
CLI options section in README.md

closes #216

BUILDING.md

@@ -0,0 +1,143 @@
+# Building Codex
+
+## Table of Contents
+
+- [Install developer tools](#prerequisites)
+  - [Linux](#linux)
+  - [macOS](#macos)
+  - [Windows + MSYS2](#windows--msys2)
+  - [Other](#other)
+- [Clone and prepare the Git repository](#repository)
+- [Build the executable](#executable)
+- [Run the example](#example-usage)
+
+**Optional**
+- [Run the tests](#tests)
+
+## Prerequisites
+
+To build nim-codex, developer tools need to be installed and accessible in the OS.
+
+Instructions below correspond roughly to environmental setups in nim-codex's [CI workflow](https://github.com/status-im/nim-codex/blob/main/.github/workflows/ci.yml) and are known to work.
+
+Other approaches may be viable. On macOS, some users may prefer [MacPorts](https://www.macports.org/) to [Homebrew](https://brew.sh/). On Windows, rather than use MSYS2, some users may prefer to install developer tools with [winget](https://docs.microsoft.com/en-us/windows/package-manager/winget/), [Scoop](https://scoop.sh/), or [Chocolatey](https://chocolatey.org/), or download installers for e.g. Make and CMake while otherwise relying on official Windows developer tools. Community contributions to these docs and our build system are welcome!
+
+### Linux
+
+*Package manager commands may require `sudo` depending on OS setup.*
+
+On a bare bones installation of Debian (or a distribution derived from Debian, such as Ubuntu), run
+
+```text
+$ apt-get update && apt-get install build-essential cmake curl git
+```
+
+Non-Debian distributions have different package managers: `apk`, `dnf`, `pacman`, `rpm`, `yum`, etc.
+
+For example, on a bare bones installation of Fedora, run
+
+```text
+$ dnf install @development-tools cmake gcc-c++ which
+```
+
+### macOS
+
+Install the [Xcode Command Line Tools](https://mac.install.guide/commandlinetools/index.html) by opening a terminal and running
+```text
+$ xcode-select --install
+```
+
+Install [Homebrew (`brew`)](https://brew.sh/) and in a new terminal run
+```text
+$ brew install bash cmake
+```
+
+Check that `PATH` is setup correctly
+```text
+$ which bash cmake
+/usr/local/bin/bash
+/usr/local/bin/cmake
+```
+
+### Windows + MSYS2
+
+*Instructions below assume the OS is 64-bit Windows and that the hardware or VM is [x86-64](https://en.wikipedia.org/wiki/X86-64) compatible.*
+
+Download and run the installer from [msys2.org](https://www.msys2.org/).
+
+Launch an MSYS2 [environment](https://www.msys2.org/docs/environments/). UCRT64 is generally recommended: from the Windows *Start menu* select `MSYS2 MinGW UCRT x64`.
+
+Assuming a UCRT64 environment, in Bash run
+```text
+$ pacman -S base-devel git unzip mingw-w64-ucrt-x86_64-toolchain mingw-w64-ucrt-x86_64-cmake
+```
+
+<!-- #### Headless Windows container -->
+<!-- add instructions re: getting setup with MSYS2 in a Windows container -->
+<!-- https://github.com/StefanScherer/windows-docker-machine -->
+
+### Other
+
+It is possible that nim-codex can be built and run on other platforms supported by the [Nim](https://nim-lang.org/) language: BSD family, older versions of Windows, etc. There has not been sufficient experimentation with nim-codex on such platforms, so instructions are not provided. Community contributions to these docs and our build system are welcome!
+
+## Repository
+
+In Bash run
+```text
+$ git clone https://github.com/status-im/nim-codex.git repos/nim-codex && cd repos/nim-codex
+```
+
+nim-codex uses the [nimbus-build-system](https://github.com/status-im/nimbus-build-system#readme), so next run
+```text
+$ make update
+```
+
+This step can take a while to complete because by default it builds the [Nim compiler](https://nim-lang.org/docs/nimc.html).
+
+To see more output from `make` pass `V=1`. This works for all `make` targets in projects using the nimbus-build-system
+```text
+$ make V=1 update
+```
+
+## Executable
+
+In Bash run
+```text
+$ make exec
+```
+
+The `exec` target creates the `build/codex` executable.
+
+## Example usage
+
+See the [instructions](README.md#cli-options) in the main readme.
+
+## Tests
+
+In Bash run
+```text
+$ make test
+```
+
+### testAll
+
+The `testAll` target runs the same tests as `make test` and also runs tests for nim-codex's Ethereum contracts, as well a basic suite of integration tests.
+
+To run `make testAll`, Node.js needs to be installed. [Node Version Manager (`nvm`)](https://github.com/nvm-sh/nvm#readme) is a flexible means to do that and it works on Linux, macOS, and Windows + MSYS2.
+
+With `nvm` installed, launch a separate terminal and download the latest LTS version of Node.js
+```text
+$ nvm install --lts
+```
+
+In that same terminal run
+```text
+$ cd repos/nim-codex/vendor/dagger-contracts && npm install && npm start
+```
+
+Those commands install and launch a [Hardhat](https://hardhat.org/) environment with nim-codex's Ethereum contracts.
+
+In the other terminal run
+```text
+$ make testAll
+```

README.md

@@ -14,6 +14,8 @@
 
 ## Build and Run
 
+For detailed instructions on preparing to build nim-codex see [*Building Codex*](BUILDING.md).
+
 To build the project, clone it and run:
 
 ```bash
@@ -25,13 +27,13 @@ The executable will be placed under the `build` directory under the project root
 Run the client with:
 
 ```bash
-./build/codex
+build/codex
 ```
 
 ### CLI Options
 
 ```
-./build/codex --help
+build/codex --help
 Usage:
 
 codex [OPTIONS]... command
@@ -52,9 +54,10 @@ The following options are available:
      --agent-string         Node agent string which is used as identifier in network [=Codex].
  -p, --api-port             The REST Api port [=8080].
  -c, --cache-size           The size in MiB of the block cache, 0 disables the cache [=100].
+     --persistence          Enables persistence mechanism, requires an Ethereum node [=false].
      --eth-provider         The URL of the JSON-RPC API of the Ethereum node [=ws://localhost:8545].
-     --eth-account          The Ethereum account that is used for storage contracts [=EthAddress.default].
+     --eth-account          The Ethereum account that is used for storage contracts [=EthAddress.none].
-     --eth-deployment       The json file describing the contract deployment [=string.default].
+     --eth-deployment       The json file describing the contract deployment [=string.none].
 
 Available sub-commands:
 
@@ -64,10 +67,10 @@ codex initNode
 ### Example: running two Codex clients
 
 ```bash
-./build/codex --data-dir="$(pwd)/Codex1" -i=127.0.0.1
+build/codex --data-dir="$(pwd)/Codex1" -i=127.0.0.1
 ```
 
-This will start codex with a data directory pointing to `Codex` under the current execution directory and announce itself on the DHT under `127.0.0.1`.
+This will start codex with a data directory pointing to `Codex1` under the current execution directory and announce itself on the DHT under `127.0.0.1`.
 
 To run a second client that automatically discovers nodes on the network, we need to get the Signed Peer Record (SPR) of first client, Client1. We can do this by querying the `/info` endpoint of the node's REST API.
 
@@ -90,7 +93,7 @@ This should output information about Client1, including its PeerID, TCP/UDP addr
 Now, let's start a second client, Client2. Because we're already using the default ports TCP (:8080) and UDP (:8090) for the first client, we have to specify new ports to avoid a collision. Additionally, we can specify the SPR from Client1 as the bootstrap node for discovery purposes, allowing Client2 to determine where content is located in the network.
 
 ```bash
-./build/codex --data-dir="$(pwd)/Codex2" -i=127.0.0.1 --api-port=8081 --udp-port=8091 --bootstrap-node=spr:CiUIAhIhAmqg5fVU2yxPStLdUOWgwrkWZMHW2MHf6i6l8IjA4tssEgIDARpICicAJQgCEiECaqDl9VTbLE9K0t1Q5aDCuRZkwdbYwd_qLqXwiMDi2ywQ5v2VlAYaCwoJBH8AAAGRAh-aGgoKCAR_AAABBts3KkcwRQIhAPOKl38CviplVbMVnA_9q3N1K_nk5oGuNp7DWeOqiJzzAiATQ2acPyQvPxLU9YS-TiVo4RUXndRcwMFMX2Yjhw8k3A
+build/codex --data-dir="$(pwd)/Codex2" -i=127.0.0.1 --api-port=8081 --udp-port=8091 --bootstrap-node=spr:CiUIAhIhAmqg5fVU2yxPStLdUOWgwrkWZMHW2MHf6i6l8IjA4tssEgIDARpICicAJQgCEiECaqDl9VTbLE9K0t1Q5aDCuRZkwdbYwd_qLqXwiMDi2ywQ5v2VlAYaCwoJBH8AAAGRAh-aGgoKCAR_AAABBts3KkcwRQIhAPOKl38CviplVbMVnA_9q3N1K_nk5oGuNp7DWeOqiJzzAiATQ2acPyQvPxLU9YS-TiVo4RUXndRcwMFMX2Yjhw8k3A
 ```
 
 There are now two clients running. We could upload a file to Client1 and download that file (given its CID) using Client2, by using the clients' REST API.