From 8b2d74bb2c75f57168ae266bfd3d4cb9542ab0a0 Mon Sep 17 00:00:00 2001 From: Rjan Date: Wed, 16 Jun 2021 12:26:33 +0200 Subject: [PATCH 1/3] Initial draft: basic build instructions on Readme Inital draft for basic build instructions on the Readme page. Issue: #6348 --- README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 761838834..ee458788b 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Lotus is an implementation of the Filecoin Distributed Storage Network. For more ## Building & Documentation -For instructions on how to build, install and setup lotus, please visit [https://docs.filecoin.io/get-started/lotus](https://docs.filecoin.io/get-started/lotus/). +For complete instructions on how to build, install and setup lotus, please visit [https://docs.filecoin.io/get-started/lotus](https://docs.filecoin.io/get-started/lotus/). Basic build instructions can be found further down in this readme. ## Reporting a Vulnerability @@ -50,6 +50,112 @@ When implementing a change: 7. Title the PR in a meaningful way and describe the rationale and the thought process in the PR description. 8. Write clean, thoughtful, and detailed [commit messages](https://chris.beams.io/posts/git-commit/). This is even more important than the PR description, because commit messages are stored _inside_ the Git history. One good rule is: if you are happy posting the commit message as the PR description, then it's a good commit message. +## Basic Build Instructions +**System-specific Software Dependencies**: + +Building Lotus requires some system dependencies, usually provided by your distribution. + +Ubuntu/Debian: +``` +sudo apt install mesa-opencl-icd ocl-icd-opencl-dev gcc git bzr jq pkg-config curl clang build-essential hwloc libhwloc-dev wget -y && sudo apt upgrade -y +``` + +Fedora: +``` +sudo dnf -y install gcc make git bzr jq pkgconfig mesa-libOpenCL mesa-libOpenCL-devel opencl-headers ocl-icd ocl-icd-devel clang llvm wget hwloc libhwloc-dev +``` + +For other distributions you can find the required dependencies [here.](https://docs.filecoin.io/get-started/lotus/installation/#system-specific) For instructions specific to macOS, you can find them [here.](https://docs.filecoin.io/get-started/lotus/installation/#macos) + +#### Rustup + +Lotus needs [rustup](https://rustup.rs). The easiest way to install it is: + +```bash +wget -c https://golang.org/dl/go1.16.2.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local +``` + +#### Go + +To build Lotus, you need a working installation of [Go 1.15.5 or higher](https://golang.org/dl/): + +```bash +wget -c https://golang.org/dl/go1.16.2.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local +``` + +**TIP:** +You'll need to add `/usr/local/go/bin` to your path. For most Linux distributions you can run something like: + +```shell +echo "export PATH=$PATH:/usr/local/go/bin" >> ~/.bashrc && source ~/.bashrc +``` + +See the [official Golang installation instructions](https://golang.org/doc/install) if you get stuck. + +### Build and install Lotus + +Once all the dependencies are installed, you can build and install the Lotus suite (`lotus`, `lotus-miner`, and `lotus-worker`). + +1. Clone the repository: + + ```sh + git clone https://github.com/filecoin-project/lotus.git + cd lotus/ + ``` + +2. To join mainnet, checkout the [latest release](https://github.com/filecoin-project/lotus/releases). + + If you are changing networks from a previous Lotus installation or there has been a network reset, read the [Switch networks guide](https://docs.filecoin.io/get-started/lotus/switch-networks/) before proceeding. + + For networks other than mainnet, look up the current branch or tag/commit for the network you want to join in the [Filecoin networks dashboard](https://network.filecoin.io), then build Lotus for your specific network below. + + ```sh + git checkout + # For example: + git checkout # tag for a release + ``` + + Currently, the latest code on the _master_ branch corresponds to mainnet. + +3. If you are in China, see "[Lotus: tips when running in China](https://docs.filecoin.io/get-started/lotus/tips-running-in-china/)". +4. Depending on your CPU model, you will want to export additional environment variables: + + If you have **an AMD Zen or Intel Ice Lake CPU (or later)**, enable the use of SHA extensions by adding these two environment variables: + + ```sh + export RUSTFLAGS="-C target-cpu=native -g" + export FFI_BUILD_FROM_SOURCE=1 + ``` + + See the [Native Filecoin FFI section](https://docs.filecoin.io/get-started/lotus/installation/#native-filecoin-ffi) for more details about this process. + + Some older Intel and AMD processors without the ADX instruction support may panic with illegal instruction errors. To fix this, add the `CGO_CFLAGS` environment variable: + + ```sh + export CGO_CFLAGS_ALLOW="-D__BLST_PORTABLE__" + export CGO_CFLAGS="-D__BLST_PORTABLE__" + ``` + + This is due to a Lotus bug that prevents Lotus from running on a processor without `adx` instruction support, and should be fixed soon. + +5. Build and install Lotus: + + ```sh + make clean all + + # Or to join a testnet or devnet: + make clean calibnet # Calibration with min 32GiB sectors + make clean nerpanet # Nerpa with min 512MiB sectors + + sudo make install + ``` + + This will put `lotus`, `lotus-miner` and `lotus-worker` in `/usr/local/bin`. + + `lotus` will use the `$HOME/.lotus` folder by default for storage (configuration, chain data, wallets, etc). See [advanced options](https://docs.filecoin.io/get-started/lotus/configuration-and-advanced-usage/) for information on how to customize the Lotus folder. + +6. You should now have Lotus installed. You can now [start the Lotus daemon and sync the chain](https://docs.filecoin.io/get-started/lotus/installation/#start-the-lotus-daemon-and-sync-the-chain). + ## License Dual-licensed under [MIT](https://github.com/filecoin-project/lotus/blob/master/LICENSE-MIT) + [Apache 2.0](https://github.com/filecoin-project/lotus/blob/master/LICENSE-APACHE) From ca4ca8cbcf9bbb81f7cd93672518c95dbfef3ba4 Mon Sep 17 00:00:00 2001 From: Rjan Date: Wed, 16 Jun 2021 13:15:09 +0200 Subject: [PATCH 2/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ee458788b..4a0adc8c0 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,7 @@ wget -c https://golang.org/dl/go1.16.2.linux-amd64.tar.gz -O - | sudo tar -xz -C #### Go -To build Lotus, you need a working installation of [Go 1.15.5 or higher](https://golang.org/dl/): +To build Lotus, you need a working installation of [Go 1.16.1 or higher](https://golang.org/dl/): ```bash wget -c https://golang.org/dl/go1.16.2.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local From e56a171ab6737be2bf5f89790bb8c23fa771efbb Mon Sep 17 00:00:00 2001 From: Rjan Date: Fri, 18 Jun 2021 10:59:53 +0200 Subject: [PATCH 3/3] Use prebuilt proof binaries when building Make the basic build instructions use the prebuilt proof binaries instead of building them from source. Removed rustup as a dependency, and linked to it in the full docs instead. --- README.md | 36 ++++++------------------------------ 1 file changed, 6 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 4a0adc8c0..0218e87e9 100644 --- a/README.md +++ b/README.md @@ -67,20 +67,12 @@ sudo dnf -y install gcc make git bzr jq pkgconfig mesa-libOpenCL mesa-libOpenCL- For other distributions you can find the required dependencies [here.](https://docs.filecoin.io/get-started/lotus/installation/#system-specific) For instructions specific to macOS, you can find them [here.](https://docs.filecoin.io/get-started/lotus/installation/#macos) -#### Rustup - -Lotus needs [rustup](https://rustup.rs). The easiest way to install it is: - -```bash -wget -c https://golang.org/dl/go1.16.2.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local -``` - #### Go -To build Lotus, you need a working installation of [Go 1.16.1 or higher](https://golang.org/dl/): +To build Lotus, you need a working installation of [Go 1.16.4 or higher](https://golang.org/dl/): ```bash -wget -c https://golang.org/dl/go1.16.2.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local +wget -c https://golang.org/dl/go1.16.4.linux-amd64.tar.gz -O - | sudo tar -xz -C /usr/local ``` **TIP:** @@ -102,6 +94,8 @@ Once all the dependencies are installed, you can build and install the Lotus sui git clone https://github.com/filecoin-project/lotus.git cd lotus/ ``` + +Note: The default branch `master` is the dev branch where the latest new features, bug fixes and improvement are in. However, if you want to run lotus on Filecoin mainnet and want to run a production-ready lotus, get the latest release[ here](https://github.com/filecoin-project/lotus/releases). 2. To join mainnet, checkout the [latest release](https://github.com/filecoin-project/lotus/releases). @@ -118,30 +112,12 @@ Once all the dependencies are installed, you can build and install the Lotus sui Currently, the latest code on the _master_ branch corresponds to mainnet. 3. If you are in China, see "[Lotus: tips when running in China](https://docs.filecoin.io/get-started/lotus/tips-running-in-china/)". -4. Depending on your CPU model, you will want to export additional environment variables: - - If you have **an AMD Zen or Intel Ice Lake CPU (or later)**, enable the use of SHA extensions by adding these two environment variables: - - ```sh - export RUSTFLAGS="-C target-cpu=native -g" - export FFI_BUILD_FROM_SOURCE=1 - ``` - - See the [Native Filecoin FFI section](https://docs.filecoin.io/get-started/lotus/installation/#native-filecoin-ffi) for more details about this process. - - Some older Intel and AMD processors without the ADX instruction support may panic with illegal instruction errors. To fix this, add the `CGO_CFLAGS` environment variable: - - ```sh - export CGO_CFLAGS_ALLOW="-D__BLST_PORTABLE__" - export CGO_CFLAGS="-D__BLST_PORTABLE__" - ``` - - This is due to a Lotus bug that prevents Lotus from running on a processor without `adx` instruction support, and should be fixed soon. +4. This build instruction uses the prebuilt proofs binaries. If you want to build the proof binaries from source check the [complete instructions](https://docs.filecoin.io/get-started/lotus/installation/#build-and-install-lotus). Note, if you are building the proof binaries from source, [installing rustup](https://docs.filecoin.io/get-started/lotus/installation/#rustup) is also needed. 5. Build and install Lotus: ```sh - make clean all + make clean all #mainnet # Or to join a testnet or devnet: make clean calibnet # Calibration with min 32GiB sectors