# Build from Source

Lighthouse builds on Linux, macOS, and Windows. Install the [Dependencies](#dependencies) using
the instructions below, and then proceed to [Building Lighthouse](#build-lighthouse).

## Dependencies

First, **install Rust** using [rustup](https://rustup.rs/)：

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

The rustup installer provides an easy way to update the Rust compiler, and works on all platforms.

> Tips:
>
> - During installation, when prompted, enter `1` for the default installation.
> - After Rust installation completes, try running `cargo version` . If it cannot
>   be found, run `source $HOME/.cargo/env`. After that, running `cargo version` should return the version, for example `cargo 1.68.2`.
> - It's generally advisable to append `source $HOME/.cargo/env` to `~/.bashrc`.

With Rust installed, follow the instructions below to install dependencies relevant to your
operating system.

> Note: For Linux OS, general Linux File Systems such as Ext4 or XFS are fine. We recommend to avoid using Btrfs file system as it has been reported to be slow and the node will suffer from performance degradation as a result.

### Ubuntu

Install the following packages:

```bash
sudo apt update && sudo apt install -y git gcc g++ make cmake pkg-config llvm-dev libclang-dev clang
```

> Tips:
>
> - If there are difficulties, try updating the package manager with `sudo apt
>   update`.

> Note: Lighthouse requires CMake v3.12 or newer, which isn't available in the package repositories
> of Ubuntu 18.04 or earlier. On these distributions CMake can still be installed via PPA:
> [https://apt.kitware.com/](https://apt.kitware.com)

After this, you are ready to [build Lighthouse](#build-lighthouse).

### Fedora/RHEL/CentOS

Install the following packages:

```bash
yum -y install git make perl clang cmake
```

After this, you are ready to [build Lighthouse](#build-lighthouse).

### macOS

1. Install the [Homebrew][] package manager.
1. Install CMake using Homebrew:

```
brew install cmake
```

[Homebrew]: https://brew.sh/

After this, you are ready to [build Lighthouse](#build-lighthouse).

### Windows

1. Install [Git](https://git-scm.com/download/win).
1. Install the [Chocolatey](https://chocolatey.org/install) package manager for Windows.
    > Tips:
    > - Use PowerShell to install. In Windows, search for PowerShell and run as administrator.
    > - You must ensure `Get-ExecutionPolicy` is not Restricted. To test this, run `Get-ExecutionPolicy` in PowerShell. If it returns `restricted`, then run `Set-ExecutionPolicy AllSigned`, and then run

    ```bash
    Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
    ```

    > - To verify that Chocolatey is ready, run `choco` and it should return the version.
1. Install Make, CMake and LLVM using Chocolatey:

```
choco install make
```

```
choco install cmake --installargs 'ADD_CMAKE_TO_PATH=System'
```

```
choco install llvm
```

These dependencies are for compiling Lighthouse natively on Windows. Lighthouse can also run
successfully under the [Windows Subsystem for Linux (WSL)][WSL]. If using Ubuntu under WSL, you
should follow the instructions for Ubuntu listed in the [Dependencies (Ubuntu)](#ubuntu) section.

[WSL]: https://docs.microsoft.com/en-us/windows/wsl/about

After this, you are ready to [build Lighthouse](#build-lighthouse).

## Build Lighthouse

Once you have Rust and the build dependencies you're ready to build Lighthouse:

```
git clone https://github.com/sigp/lighthouse.git
```

```
cd lighthouse
```

```
git checkout stable
```

```
make
```

Compilation may take around 10 minutes. Installation was successful if `lighthouse --help` displays
the command-line documentation.

If you run into any issues, please check the [Troubleshooting](#troubleshooting) section, or reach
out to us on [Discord](https://discord.gg/cyAszAh).

## Update Lighthouse

You can update Lighthouse to a specific version by running the commands below. The `lighthouse`
directory will be the location you cloned Lighthouse to during the installation process.
`${VERSION}` will be the version you wish to build in the format `vX.X.X`.

```
cd lighthouse
```

```
git fetch
```

```
git checkout ${VERSION}
```

```
make
```

## Feature Flags

You can customise the features that Lighthouse is built with using the `FEATURES` environment
variable. E.g.

```
FEATURES=gnosis,slasher-lmdb,beacon-node-leveldb make
```

Commonly used features include:

- `gnosis`: support for the Gnosis Beacon Chain.
- `portable`: the default feature as Lighthouse now uses runtime detection of hardware CPU features.
- `slasher-lmdb`: support for the LMDB slasher backend. Enabled by default.
- `slasher-mdbx`: support for the MDBX slasher backend.
- `beacon-node-leveldb`: support for the leveldb backend. Enabled by default.
- `jemalloc`: use [`jemalloc`][jemalloc] to allocate memory. Enabled by default on Linux and macOS.
  Not supported on Windows.
- `spec-minimal`: support for the minimal preset (useful for testing).

Default features (e.g. `slasher-lmdb`, `beacon-node-leveldb`) may be opted out of using the `--no-default-features`
argument for `cargo`, which can be plumbed in via the `CARGO_INSTALL_EXTRA_FLAGS` environment variable.
E.g.

```
CARGO_INSTALL_EXTRA_FLAGS="--no-default-features" make
```

[jemalloc]: https://jemalloc.net/

## Compilation Profiles

You can customise the compiler settings used to compile Lighthouse via
[Cargo profiles](https://doc.rust-lang.org/cargo/reference/profiles.html).

Lighthouse includes several profiles which can be selected via the `PROFILE` environment variable.

- `release`: default for source builds, enables most optimisations while not taking too long to
  compile.
- `maxperf`: default for binary releases, enables aggressive optimisations including full LTO.
  Although compiling with this profile improves some benchmarks by around 20% compared to `release`,
  it imposes a _significant_ cost at compile time and is only recommended if you have a fast CPU.

To compile with `maxperf`:

```
PROFILE=maxperf make
```

## 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"](https://www.rust-lang.org/tools/install) for more information.

### Compilation error

Make sure you are running the latest version of Rust. If you have installed Rust using rustup, simply run `rustup update`.

If you can't install the latest version of Rust you can instead compile using the Minimum Supported
Rust Version (MSRV) which is listed under the `rust-version` key in Lighthouse's
[Cargo.toml](https://github.com/sigp/lighthouse/blob/stable/lighthouse/Cargo.toml).

If compilation fails with `(signal: 9, SIGKILL: kill)`, this could mean your machine ran out of
memory during compilation. If you are on a resource-constrained device you can
look into [cross compilation](./installation_cross_compiling.md), or use a [pre-built
binary](https://github.com/sigp/lighthouse/releases).

If compilation fails with `error: linking with cc failed: exit code: 1`, try running `cargo clean`.