gnosis/lighthouse
1
0
Fork 0
mirror of https://github.com/sigp/lighthouse.git synced 2026-05-07 16:55:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update book

Browse Source
This commit is contained in:
Paul Hauner
2019-11-23 12:08:56 +11:00
parent cbf9b94f69
commit 9e5a9cefe2
6 changed files with 112 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
book/src/SUMMARY.md
View File

@@ -1,6 +1,8 @@
# Summary # Summary
* [Introduction](./intro.md) * [Introduction](./intro.md)
* [Installation](./installation.md)
* [Docker](./docker.md)
* [CLI](./cli.md) * [CLI](./cli.md)
* [Testnets](./testnets.md) * [Testnets](./testnets.md)
* [Simple Local Testnet](./simple-testnet.md) * [Simple Local Testnet](./simple-testnet.md)
@@ -9,4 +11,3 @@
* [WebSocket](./websockets.md) * [WebSocket](./websockets.md)
* [Contributing](./contributing.md) * [Contributing](./contributing.md)
* [Development Environment](./setup.md) * [Development Environment](./setup.md)
* [CI & Testing](./ci.md)

34
book/src/ci.md
View File

@@ -1,33 +1 @@
# Contiguous Integration (CI) and Testing # CI & Testing
Lighthouse uses a self-hosted Gitlab CI server to run tests and deploy docs.
For security reasons, **CI will only be run automatically for Lighthouse
maintainers.** Contributors without maintainer privileges will need to have CI
triggered for them prior to a PR being merged.
You can see the full set of tests we run in the
[gitlab-ci.yml](https://github.com/sigp/lighthouse/blob/master/.gitlab-ci.yml)
file. The following two commands should complete successfully before CI can
pass:
```bash
$ cargo test --all --all-features
$ cargo fmt --all --check
```
_Note: Travis CI is also used, however it does not run the full test suite._
### Ethereum 2.0 Spec Tests
The
[ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests/)
repository contains a large set of tests that verify Lighthouse behaviour
against the Ethereum Foundation specifications.
These tests are quite large (100's of MB), so we don't download them by
default. Developers should ensure they have downloaded these tests using the
`Makefile` in
[tests/ef_tests](https://github.com/sigp/lighthouse/tree/master/tests/ef_tests).
**Failures in these tests should prevent CI from passing.**

19
book/src/docker.md Normal file
View File

@@ -0,0 +1,19 @@
# Docker Guide
This repository has a `Dockerfile` in the root which builds an image with the
`lighthouse` binary installed.
To use the image, first build it (this will likely take several minutes):
```bash
$ docker build . -t lighthouse
```
Once it's built, run it with:
```bash
$ docker run lighthouse lighthouse --help
```
_Note: the first `lighthouse` is the name of the tag we created earlier. The
second `lighthouse` refers to the binary installed in the image._

48
book/src/installation.md Normal file
View File

@@ -0,0 +1,48 @@
# 📦 Installation
Lighthouse runs on Linux, MacOS and Windows. Installation should be easy. In
fact, if you already have Rust installed all you need is:
- `$ git clone https://github.com/sigp/lighthouse.git`
- `$ cd lighthouse`
- `$ make`
If this doesn't work or is not clear enough, see the [Detailed Instructions](#detailed-instructions). If you have further issues, see [Troubleshooting](#troubleshooting). If you'd prefer to use Docker, see the [Docker Guide](./docker.md).
## Detailed Instructions
1. Install Rust and Cargo with [rustup](https://rustup.rs/).
- Use the `stable` toolchain (it's the default).
1. Clone the Lighthouse repository.
- Run `$ git clone https://github.com/sigp/lighthouse.git`
- Change into the newly created directory with `$ cd lighthouse`
1. Build Lighthouse with `$ make`.
1. Installation was successful if `$ lighthouse --help` displays the
command-line documentation.
> First time compilation may take several minutes. If you experience any
> failures, please reach out on [discord](https://discord.gg/cyAszAh) or
> [create an issue](https://github.com/sigp/lighthouse/issues/new).
## Troubleshooting
### Command is not found
Lighthouse will be installed to `CARGO_HOME` or `$HOME/.cargo`. This directory
needs to be on your `PATH` before you can run `$ lighthouse`.
See ["Configuring the `PATH` environment variable"
(rust-lang.org)](https://www.rust-lang.org/tools/install) for more information.
### OpenSSL
If you get a build failure relating to OpenSSL, try installing `openssl-dev` or
`libssl-dev` using your OS package manager.
- Ubuntu: `$ apt-get install openssl-dev`.
- Arch Linux: `$ pacman -S libssl-dev`.
### Perl for Windows
Perl may also be required to build Lighthouse. You can install [Strawberry
Perl](http://strawberryperl.com/), or alternatively if you're using the [Chocolatey](https://chocolatey.org/) package manager for Windows, use the following choco install command: `choco install strawberryperl`.

3
book/src/intro.md
View File

@@ -19,7 +19,8 @@ We implement the specification as defined in the
You may read this book from start to finish, or jump to some of these topics: You may read this book from start to finish, or jump to some of these topics:
- Get started with [development environment setup](./setup.md). - Follow the [Installation Guide](./installation.md) to install Lighthouse.
- Get hacking with the [Development Environment Guide](./setup.md).
- Utilize the whole stack by starting a [simple local testnet](./simple-testnet.md). - Utilize the whole stack by starting a [simple local testnet](./simple-testnet.md).
- Query the [RESTful HTTP API](./http.md) using `curl`. - Query the [RESTful HTTP API](./http.md) using `curl`.
- Listen to events with the [JSON WebSocket API](./websockets.md). - Listen to events with the [JSON WebSocket API](./websockets.md).

71
book/src/setup.md
View File

@@ -1,41 +1,50 @@
# Development Environment Setup # Development Environment
## Linux, MacOS & Windows Most Lighthouse developers work on Linux or MacOS, however Windows should still
be suitable.
1. Install Rust and Cargo with [rustup](https://rustup.rs/). First, follow the [`Installation Guide`](./installation.md) to install
- Use the `stable` toolchain (it's the default). Lighthouse. This will install Lighthouse to your `PATH`, which is not
1. Install build dependencies using your package manager. particularly useful for development but still a good way to ensure you have the
- `clang`, `protobuf`, `libssl-dev`, `cmake` base dependencies.
1. Clone the [github.com/sigp/lighthouse](https://github.com/sigp/lighthouse)
repository.
1. Run `$ make` to build Lighthouse.
1. Run `$ make test` to run the test suite
- If you experience any failures, please reach out on
[discord](https://discord.gg/cyAszAh).
- Developers use `$ make test-full` to ensure you have the full set of
test vectors.
> - The `beacon_node`, `validator_client` and other binaries are created in The only additional requirement for developers is
> `target/release` directory. [`ganache-cli`](https://github.com/trufflesuite/ganache-cli). This is used to
> - First-time compilation may take several minutes. simulate the Eth1 chain during tests. You'll get failures during tests if you
don't have `ganache-cli` available on your `PATH`.
### Installing to `PATH` ## Testing
Use `cargo install --path lighthouse` from the root of the repository to Lighthouse uses `cargo test` for running the test suite. This is the
install the compiled binary to `CARGO_HOME` or `$HOME/.cargo`. If this recommended work-flow for testing during development. For example, test the
directory is on your `PATH`, you can run `$ lighthouse ..` from anywhere. `ssz` crate with:
See ["Configuring the `PATH` environment ```bash
variable" (rust-lang.org)](https://www.rust-lang.org/tools/install) for more information. cd eth2/utils/ssz
cargo test
```
> If you _don't_ install `lighthouse` to the path, you'll need to run the We also wrap some of these commands and expose them via the `Makefile` in the
> binaries directly from the `target` directory or using `cargo run ...`. project root for the benefit of CI/CD. We list some of these commands below so
you can run them locally and avoid CI failures:
### Windows - `$ make cargo-fmt`: (fast) runs a Rust code linter.
- `$ make test`: (medium) runs unit tests across the whole project.
- `$ make test-ef`: (medium) runs the Ethereum Foundation test vectors.
- `$ make test-full`: (slow) runs the full test suite (including all previous
commands). This is approximately everything
that is required to pass CI.
Perl may also be required to build Lighthouse. You can install [Strawberry _The lighthouse test suite is quite extensive, running the whole suite may take 30+ minutes._
Perl](http://strawberryperl.com/), or alternatively if you're using the [Chocolatey](https://chocolatey.org/) package manager for Windows, use the following choco install command: `choco install strawberryperl`.
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues ### Ethereum 2.0 Spec Tests
compiling in Windows. You can specify a known working version by editing
version in `protos/Cargo.toml` section to `protoc-grpcio = "<=0.3.0"`. The
[ethereum/eth2.0-spec-tests](https://github.com/ethereum/eth2.0-spec-tests/)
repository contains a large set of tests that verify Lighthouse behaviour
against the Ethereum Foundation specifications.
These tests are quite large (100's of MB) so they're only downloaded if you run
the `$ make test-ef` command (or anything that calls it). You may want to avoid
these if you're on a slow or metered Internet connection, CI will
require them to pass though.