mirror of
https://github.com/sigp/lighthouse.git
synced 2026-03-14 02:12:33 +00:00
Update book
This commit is contained in:
Paul Hauner
@@ -1,6 +1,8 @@
|
||||
# Summary
|
||||
|
||||
* [Introduction](./intro.md)
|
||||
* [Installation](./installation.md)
|
||||
* [Docker](./docker.md)
|
||||
* [CLI](./cli.md)
|
||||
* [Testnets](./testnets.md)
|
||||
* [Simple Local Testnet](./simple-testnet.md)
|
||||
@@ -9,4 +11,3 @@
|
||||
* [WebSocket](./websockets.md)
|
||||
* [Contributing](./contributing.md)
|
||||
* [Development Environment](./setup.md)
|
||||
* [CI & Testing](./ci.md)
|
||||
|
||||
@@ -1,33 +1 @@
|
||||
# Contiguous Integration (CI) and 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.**
|
||||
# CI & Testing
|
||||
|
||||
19
book/src/docker.md
Normal file
19
book/src/docker.md
Normal 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
48
book/src/installation.md
Normal 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`.
|
||||
@@ -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:
|
||||
|
||||
- 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).
|
||||
- Query the [RESTful HTTP API](./http.md) using `curl`.
|
||||
- Listen to events with the [JSON WebSocket API](./websockets.md).
|
||||
|
||||
@@ -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/).
|
||||
- Use the `stable` toolchain (it's the default).
|
||||
1. Install build dependencies using your package manager.
|
||||
- `clang`, `protobuf`, `libssl-dev`, `cmake`
|
||||
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.
|
||||
First, follow the [`Installation Guide`](./installation.md) to install
|
||||
Lighthouse. This will install Lighthouse to your `PATH`, which is not
|
||||
particularly useful for development but still a good way to ensure you have the
|
||||
base dependencies.
|
||||
|
||||
> - The `beacon_node`, `validator_client` and other binaries are created in
|
||||
> `target/release` directory.
|
||||
> - First-time compilation may take several minutes.
|
||||
The only additional requirement for developers is
|
||||
[`ganache-cli`](https://github.com/trufflesuite/ganache-cli). This is used to
|
||||
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
|
||||
install the compiled binary to `CARGO_HOME` or `$HOME/.cargo`. If this
|
||||
directory is on your `PATH`, you can run `$ lighthouse ..` from anywhere.
|
||||
Lighthouse uses `cargo test` for running the test suite. This is the
|
||||
recommended work-flow for testing during development. For example, test the
|
||||
`ssz` crate with:
|
||||
|
||||
See ["Configuring the `PATH` environment
|
||||
variable" (rust-lang.org)](https://www.rust-lang.org/tools/install) for more information.
|
||||
```bash
|
||||
cd eth2/utils/ssz
|
||||
cargo test
|
||||
```
|
||||
|
||||
> If you _don't_ install `lighthouse` to the path, you'll need to run the
|
||||
> binaries directly from the `target` directory or using `cargo run ...`.
|
||||
We also wrap some of these commands and expose them via the `Makefile` in the
|
||||
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
|
||||
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`.
|
||||
_The lighthouse test suite is quite extensive, running the whole suite may take 30+ minutes._
|
||||
|
||||
Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues
|
||||
compiling in Windows. You can specify a known working version by editing
|
||||
version in `protos/Cargo.toml` section to `protoc-grpcio = "<=0.3.0"`.
|
||||
### 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 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.
|
||||
|
||||
Reference in New Issue
Block a user