From 9e5a9cefe2049ddfd08ecc977d04237dca0f9ae1 Mon Sep 17 00:00:00 2001 From: Paul Hauner Date: Sat, 23 Nov 2019 12:08:56 +1100 Subject: [PATCH] Update book --- book/src/SUMMARY.md | 3 +- book/src/ci.md | 34 +------------------ book/src/docker.md | 19 +++++++++++ book/src/installation.md | 48 +++++++++++++++++++++++++++ book/src/intro.md | 3 +- book/src/setup.md | 71 ++++++++++++++++++++++------------------ 6 files changed, 112 insertions(+), 66 deletions(-) create mode 100644 book/src/docker.md create mode 100644 book/src/installation.md diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 9f49ea95e6..8882bead75 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -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) diff --git a/book/src/ci.md b/book/src/ci.md index e89864276c..02289a8d00 100644 --- a/book/src/ci.md +++ b/book/src/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 diff --git a/book/src/docker.md b/book/src/docker.md new file mode 100644 index 0000000000..f7f2872c47 --- /dev/null +++ b/book/src/docker.md @@ -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._ diff --git a/book/src/installation.md b/book/src/installation.md new file mode 100644 index 0000000000..92bfef68fe --- /dev/null +++ b/book/src/installation.md @@ -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`. diff --git a/book/src/intro.md b/book/src/intro.md index 2e06256bc6..8198c9886e 100644 --- a/book/src/intro.md +++ b/book/src/intro.md @@ -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). diff --git a/book/src/setup.md b/book/src/setup.md index 5293947d55..bd3a8259e3 100644 --- a/book/src/setup.md +++ b/book/src/setup.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.