From 80795724f1c4e351cef31bb632ae491306b58d2e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=9D=8E=E5=A9=B7=E5=A9=B7?= Date: Sat, 2 May 2020 21:14:19 +0800 Subject: [PATCH] filling up contents from readme --- docs/book.toml | 2 +- docs/src/SUMMARY.md | 9 ++- docs/src/advanced.md | 132 +++++++++++++++++++++++++++++++++++++++ docs/src/api.md | 1 + docs/src/beacon-chain.md | 4 ++ docs/src/chapter_1.md | 1 - docs/src/faq.md | 1 + docs/src/install.md | 47 ++++++++++++++ docs/src/intro.md | 21 +++++++ docs/src/nimbus.md | 6 ++ docs/src/validator.md | 19 ++++++ 11 files changed, 240 insertions(+), 3 deletions(-) create mode 100644 docs/src/advanced.md create mode 100644 docs/src/api.md create mode 100644 docs/src/beacon-chain.md delete mode 100644 docs/src/chapter_1.md create mode 100644 docs/src/faq.md create mode 100644 docs/src/install.md create mode 100644 docs/src/intro.md create mode 100644 docs/src/nimbus.md create mode 100644 docs/src/validator.md diff --git a/docs/book.toml b/docs/book.toml index 9807613d2..4c430b11c 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -1,5 +1,5 @@ [book] -authors = ["李婷婷"] +authors = ["tinaaaaalee"] language = "en" multilingual = false src = "src" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 7390c8289..9b3a59282 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,3 +1,10 @@ # Summary -- [Chapter 1](./chapter_1.md) +- [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) diff --git a/docs/src/advanced.md b/docs/src/advanced.md new file mode 100644 index 000000000..c4bf52603 --- /dev/null +++ b/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 +``` + diff --git a/docs/src/api.md b/docs/src/api.md new file mode 100644 index 000000000..593279293 --- /dev/null +++ b/docs/src/api.md @@ -0,0 +1 @@ +# API diff --git a/docs/src/beacon-chain.md b/docs/src/beacon-chain.md new file mode 100644 index 000000000..67e49763b --- /dev/null +++ b/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/). + \ No newline at end of file diff --git a/docs/src/chapter_1.md b/docs/src/chapter_1.md deleted file mode 100644 index b743fda35..000000000 --- a/docs/src/chapter_1.md +++ /dev/null @@ -1 +0,0 @@ -# Chapter 1 diff --git a/docs/src/faq.md b/docs/src/faq.md new file mode 100644 index 000000000..318b08dc2 --- /dev/null +++ b/docs/src/faq.md @@ -0,0 +1 @@ +# Frequently Asked Questions diff --git a/docs/src/install.md b/docs/src/install.md new file mode 100644 index 000000000..917be6c77 --- /dev/null +++ b/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 +``` diff --git a/docs/src/intro.md b/docs/src/intro.md new file mode 100644 index 000000000..d36f57c83 --- /dev/null +++ b/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. :) + diff --git a/docs/src/nimbus.md b/docs/src/nimbus.md new file mode 100644 index 000000000..59223fd76 --- /dev/null +++ b/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? diff --git a/docs/src/validator.md b/docs/src/validator.md new file mode 100644 index 000000000..5ee7c0e62 --- /dev/null +++ b/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.