Merge pull request #958 from status-im/readme

Make gitbook for the manual

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["tinaaaaalee"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The Nimbus Beacon Chain Book"

docs/src/SUMMARY.md

@@ -0,0 +1,10 @@
+# Summary
+
+- [Introduction](./intro.md)
+  - [What is Beacon Chain?](./beacon-chain.md)
+  - [What is Nimbus?](./nimbus.md)
+- [Become a Validator](./validator.md)
+- [Installation](./install.md)
+- [API](./api.md)
+- [Advanced Usage for Developers](./advanced.md)
+- [FAQs](./faq.md)

docs/src/advanced.md

@@ -0,0 +1,132 @@
+# Advanced Usage for Developers
+
+Latest updates happen in the `devel` branch which is merged into `master` every week on Tuesday before deploying a new testnets
+The following sections explain how to setup your build environment on your platform.
+
+### Windows dev environment
+
+Install Mingw-w64 for your architecture using the "[MinGW-W64 Online
+Installer](https://sourceforge.net/projects/mingw-w64/files/)" (first link
+under the directory listing). Run it and select your architecture in the setup
+menu ("i686" on 32-bit, "x86\_64" on 64-bit), set the threads to "win32" and
+the exceptions to "dwarf" on 32-bit and "seh" on 64-bit. Change the
+installation directory to "C:\mingw-w64" and add it to your system PATH in "My
+Computer"/"This PC" -> Properties -> Advanced system settings -> Environment
+Variables -> Path -> Edit -> New -> C:\mingw-w64\mingw64\bin (it's "C:\mingw-w64\mingw32\bin" on 32-bit)
+
+Install [Git for Windows](https://gitforwindows.org/) and use a "Git Bash" shell to clone and build nim-beacon-chain.
+
+If you don't want to compile PCRE separately, you can fetch pre-compiled DLLs with:
+```bash
+mingw32-make # this first invocation will update the Git submodules
+mingw32-make fetch-dlls # this will place the right DLLs for your architecture in the "build/" directory
+```
+
+> If you were following the Windows testnet instructions, you can jump back to [Connecting to testnets](#connecting-to-testnets) now
+
+You can now follow those instructions in the previous section by replacing `make` with `mingw32-make` (regardless of your 32-bit or 64-bit architecture):
+
+```bash
+mingw32-make test # run the test suite
+```
+
+### Linux, MacOS
+
+After cloning the repo:
+
+```bash
+make # The first `make` invocation will update all Git submodules and prompt you to run `make` again.
+     # It's only required once per Git clone. You'll run `make update` after each `git pull`, in the future,
+     # to keep those submodules up to date.
+
+# Run tests
+make test
+
+# Update to latest version
+git pull
+make update
+```
+
+To run a command that might use binaries from the Status Nim fork:
+```bash
+./env.sh bash # start a new interactive shell with the right env vars set
+which nim
+nim --version # Nimbus is tested and supported on 1.0.2 at the moment
+
+# or without starting a new interactive shell:
+./env.sh which nim
+./env.sh nim --version
+```
+
+### Raspberry Pi
+
+We recommend you remove any cover or use a fan; the Raspberry Pi will get hot (85°C) and throttle.
+
+* Raspberry PI 3b+ or Raspberry Pi 4b.
+* 64gb SD Card (less might work too, but the default recommended 4-8GB will probably be too small)
+* [Rasbian Buster Lite](https://www.raspberrypi.org/downloads/raspbian/) - Lite version is enough to get going and will save some disk space!
+
+Assuming you're working with a freshly written image:
+
+```bash
+
+# Start by increasing swap size to 2gb:
+sudo vi /etc/dphys-swapfile
+# Set CONF_SWAPSIZE=2048
+# :wq
+sudo reboot
+
+# Install prerequisites
+sudo apt-get install git libgflags-dev libsnappy-dev libpcre3-dev
+
+# Then you can follow instructions for Linux.
+
+```
+
+### Makefile tips and tricks for developers
+
+- build all those tools known to the Makefile:
+
+```bash
+# $(nproc) corresponds to the number of cores you have
+make -j$(nproc)
+```
+
+- build a specific tool:
+
+```bash
+make state_sim
+```
+
+- you can control the Makefile's verbosity with the V variable (defaults to 0):
+
+```bash
+make V=1 # verbose
+make V=2 test # even more verbose
+```
+
+- same for the [Chronicles log level](https://github.com/status-im/nim-chronicles#chronicles_log_level):
+
+```bash
+make LOG_LEVEL=DEBUG bench_bls_sig_agggregation # this is the default
+make LOG_LEVEL=TRACE beacon_node # log everything
+```
+
+- pass arbitrary parameters to the Nim compiler:
+
+```bash
+make NIMFLAGS="-d:release"
+```
+
+- you can freely combine those variables on the `make` command line:
+
+```bash
+make -j$(nproc) NIMFLAGS="-d:release" USE_MULTITAIL=yes eth2_network_simulation
+```
+
+- don't use the [lightweight stack tracing implementation from nim-libbacktrace](https://github.com/status-im/nim-beacon-chain/pull/745):
+
+```bash
+make USE_LIBBACKTRACE=0 # expect the resulting binaries to be 2-3 times slower
+```
+

docs/src/api.md

@@ -0,0 +1 @@
+# API

docs/src/beacon-chain.md

@@ -0,0 +1,4 @@
+# What is Beacon Chain?
+
+More introduction about beacon chain can be found in the [Ethereum 2.0 blog series](https://our.status.im/two-point-oh-the-beacon-chain/).
+ 

docs/src/faq.md

@@ -0,0 +1 @@
+# Frequently Asked Questions

docs/src/install.md

@@ -0,0 +1,47 @@
+# Installation
+
+Nimbus beacon chain can run on Linux, MacOS, Windows, and Andriod. At the moment, Nimbus has to be built from source.
+
+## External Dependencies 
+- Developer tools (C compiler, Make, Bash, Git)
+- PCRE
+Nim is not an external dependency, Nimbus will build its own local copy.
+
+## Linux
+
+On common Linux distributions the dependencies can be installed with:
+```sh
+# Debian and Ubuntu
+sudo apt-get install build-essential git libpcre3-dev
+
+# Fedora
+dnf install @development-tools pcre
+
+# Archlinux, using an AUR manager for pcre-static
+yourAURmanager -S base-devel pcre-static
+```
+
+### MacOS
+
+Assuming you use [Homebrew](https://brew.sh/) to manage packages
+
+```sh
+brew install pcre
+```
+
+### Windows
+
+You can install the developer tools by following the instruction in our [Windows dev environment section](./advanced.md#windows-dev-environment).
+It also provides a downloading script for prebuilt PCRE.
+
+### Android
+
+* Install the [Termux](https://termux.com) app from FDroid or the Google Play store
+* Install a [PRoot](https://wiki.termux.com/wiki/PRoot) of your choice following the instructions for your preferred distribution. 
+Note, the Ubuntu PRoot is known to contain all Nimbus prerequisites compiled on Arm64 architecture (common architecture for Android devices).  
+
+*Assuming Ubuntu PRoot is used*
+
+```sh
+apt install build-essential git libpcre3-dev
+```

docs/src/intro.md

@@ -0,0 +1,21 @@
+# Nimbus Beacon Chain Book
+
+_Documentation for Nimbus Beacon Chain users and developers._
+
+Nimbus beacon chain is a research implementation of the beacon chain component of the upcoming Ethereum Serenity upgrade, aka Eth2. 
+
+- Open sourced at [github.com/status-im/nim-beacon-chain/docs](github.com/status-im/nim-beacon-chain/docs).
+- Specification of our implementation can be found at [ethereum/eth2.0-specs](https://github.com/ethereum/eth2.0-specs/tree/v0.11.1#phase-0).
+
+## Overview
+In this book, we will cover:
+1. [What is beacon chain](./beacon-chain.md) and [what is Nimbus](./nimbus.md) to equip you with the basic knowledge. 
+2. How to [become a validator](./validator.md) in Ethereum as a user. 
+3. [Installation steps](./install.md) for nimbus beacon chain.
+4. The [api documentation](./api.md) for interested developers.
+5. [Advanced usage](./advanced.md) for developers.  
+6. Common [questions and answers](./faq.md) to satisfy your curiosity. 
+
+
+Feel free to give us feedback on how to improve as well as contribute to our book on github. :)
+

docs/src/nimbus.md

@@ -0,0 +1,6 @@
+# What is Nimbus?
+In a sentence, Nimbus is an Ethereum 1.0 & 2.0 Client for Resource-Restricted Devices.
+
+It is open sourced at [github.com/status-im/nimbus](github.com/status-im/nimbus). Development progress and updates can be viewed at the [Nimbus blog](https://our.status.im/tag/nimbus/). 
+
+## Why should you choose Nimbus?

docs/src/validator.md

@@ -0,0 +1,19 @@
+# Become a Validator
+
+To become a validator, you have to first connect to a testnet.
+
+### Connecting to testnets
+
+Nimbus connects to any of the testnets published in the [eth2-clients/eth2-testnets repo](https://github.com/eth2-clients/eth2-testnets/tree/master/nimbus).
+
+Once the [prerequisites](#prerequisites) are installed you can connect to testnet0 with the following commands:
+
+```bash
+git clone https://github.com/status-im/nim-beacon-chain
+cd nim-beacon-chain
+make                 # This invocation will bootstrap the build system with additional Makefiles
+make testnet0        # This will build Nimbus and all other dependencies
+                     # and connect you to testnet0
+```
+
+The testnets are restarted once per week, usually on Monday evenings (UTC)) and integrate the changes for the past week.