revive-llvm-builder 0.2.0

revive LLVM compiler framework builder
Documentation

revive LLVM builder

Parity fork of the Matter Labs zksync LLVM builder helper utility for compiling revive compatible LLVM builds.

Installation and usage

The LLVM compiler framework for revive must be built with our tool called revive-llvm. This is because the revive compiler has requirements not fullfilled in upstream builds:

  • Special builds for compiling the frontend into statically linked ELF binaries and also Wasm executables
  • The RISC-V target (the PolkaVM target)
  • The compiler-rt builtins for the PolkaVM target
  • We want to leave the assertions always on
  • Various other specific configurations and optimization may be applied

Obtain a compatible build for your host platform from the release section of this repository (TODO). Alternatively follow below steps to get a custom build:

  • Linux (Debian):

    Install the following packages:

    apt install cmake ninja-build curl git libssl-dev pkg-config clang lld

  • Linux (Arch):

    Install the following packages:

    pacman -Syu which cmake ninja curl git pkg-config clang lld

  • MacOS:

    • Install the HomeBrew package manager.

    • Install the following packages:

      brew install cmake ninja coreutils

    • Install your choice of a recent LLVM/Clang compiler, e.g. via Xcode, Apple’s Command Line Tools, or your preferred package manager.

  • Follow the latest [official instructions](https://www.rust-lang.org/tools/install:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
. ${HOME}/.cargo/env

    Currently we are not pinned to any specific version of Rust, so just install the latest stable build for your platform.

  • Install the builder using cargo:

    cargo install --git https://github.com/paritytech/revive-llvm-builder --force --locked

    The builder is not the LLVM framework itself, but a tool that clones its repository and runs a sequence of build commands. By default it is installed in ~/.cargo/bin/, which is recommended to be added to your $PATH.

  • The LLVM.lock dictates the LLVM source tree being used. A default ./LLVM.lock pointing to the release used for development is already provided.

  • Clone and build the LLVM framework using the revive-llvm tool.

    The clang and lld projects are required for the resolc Solidity frontend executable; they are enabled by default. LLVM assertions are also enabled by default.

    revive-llvm clone
revive-llvm build --llvm-projects lld --llvm-projects clang

    Build artifacts end up in the ./target-llvm/gnu/target-final/ directory by default. The gnu directory depends on the supported archticture and will either be gnu, musl or emscripten. You now need to export the final target directory $LLVM_SYS_181_PREFIX: export LLVM_SYS_181_PREFIX=${PWD}/target-llvm/gnu/target-final If built with the --enable-tests option, test tools will be in the ./target-llvm/gnu/build-final/ directory, along with copies of the build artifacts. For all supported build options, run revive-llvm build --help.

Supported target architectures

The following target platforms are supported:

  • Linux GNU (x86)
  • Linux MUSL (x86)
  • MacOS (aarch64)
  • Windows GNU (x86)
  • Emscripten (wasm32)

  • Via a musl build we can build revive into fully static ELF binaries. Which is desirable for reproducible Solidity contracts builds. The resulting binary is also very portable, akin to thesolc frontend binary distribution.

    Clone and build the LLVM framework using the revive-llvm tool:

    revive-llvm --target-env musl clone
revive-llvm --target-env musl build --enable-assertions --llvm-projects clang --llvm-projects lld

  • Via an emsdk build we can run revive in the browser and on node.js.

    Clone and build the LLVM framework using the revive-llvm tool:

    revive-llvm --target-env emscripten clone
revive-llvm --target-env emscripten build --enable-assertions --llvm-projects clang --llvm-projects lld