From 17a2d2f9f2d52e5fb3b26144d27ff65771d3e6f5 Mon Sep 17 00:00:00 2001 From: xermicus Date: Fri, 21 Feb 2025 10:51:40 +0100 Subject: [PATCH] update README.md (#223) Signed-off-by: xermicus --- .github/workflows/release-llvm.yml | 2 +- README.md | 58 +++++++++++++++++++++--------- 2 files changed, 43 insertions(+), 17 deletions(-) diff --git a/.github/workflows/release-llvm.yml b/.github/workflows/release-llvm.yml index 47a11d4..0e436a8 100644 --- a/.github/workflows/release-llvm.yml +++ b/.github/workflows/release-llvm.yml @@ -146,7 +146,7 @@ jobs: rm -rf diagtool llvm-libtool-darwin llvm-lipo llvm-pdbutil llvm-dwarfdump llvm-nm llvm-readobj llvm-cfi-verify \ sancov llvm-debuginfo-analyzer llvm-objdump llvm-profgen llvm-extract llvm-jitlink llvm-c-test llvm-gsymutil llvm-dwp \ dsymutil llvm-dwarfutil llvm-exegesis lli clang-rename bugpoint clang-extdef-mapping clang-refactor c-index-test \ - llvm-reduce llvm-lto clang-linker-wrapper llc llvm-lto2 + llvm-reduce llvm-lto clang-linker-wrapper llc llvm-lto2 llvm-otool llvm-readelf cd - done diff --git a/README.md b/README.md index 5a97160..55ab1ef 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ ![CI](https://github.com/paritytech/revive/actions/workflows/rust.yml/badge.svg) -[![Docs](https://img.shields.io/badge/Docs-contracts.polkadot.io-brightgreen.svg)](https://contracts.polkadot.io) +[![Docs](https://img.shields.io/badge/Docs-contracts.polkadot.io-brightgreen.svg)](https://contracts.polkadot.io/revive_compiler/) # revive @@ -14,10 +14,7 @@ This is experimental software in active development and not ready just yet for p Discussion around the development is hosted on the [Polkadot Forum](https://forum.polkadot.network/t/contracts-update-solidity-on-polkavm/6949#a-new-solidity-compiler-1). ## Installation - -`resolc` depends on the [solc](https://github.com/ethereum/solidity) binary installed on your system. - -Download and install the `resolc` frontend executable for your platform from our [releases](https://github.com/paritytech/revive/releases). +Please consult [the documentation](https://contracts.polkadot.io/revive_compiler/installation) for installation instructions. ## Building from source @@ -25,22 +22,46 @@ Building revive requires a [stable Rust installation](https://rustup.rs/) and a ### LLVM -`revive` depends on a custom build of LLVM `v18.1.8` with the RISC-V _embedded_ target, including the `compiler-rt` builtins. Use the provided [revive-llvm](crates/llvm-builder/README.md) utility to compile a compatible LLVM build locally and point `$LLVM_SYS_181_PREFIX` to the installation afterwards. +`revive` depends on a custom build of LLVM `v18.1.8` with the RISC-V _embedded_ target, including the `compiler-rt` builtins. You can either download a build from our releases (recommended for older hardware) or build it from source. + +
+ Download from our LLVM releases + +Download the [latest LLVM build](https://github.com/paritytech/revive/releases?q=LLVM+binaries+release&expanded=true) from our releases. + +> **MacOS** users need to clear the `downloaded` attribute from all binaries after extracting the archive: +> ```sh +> xattr -rc /target-llvm/gnu/target-final/bin/* +> ``` + +After extracting the archive, point `$LLVM_SYS_181_PREFIX` to it: +```sh +export LLVM_SYS_181_PREFIX=/target-llvm/gnu/target-final +``` + +
+ +
+ Building from source + + Use the provided [revive-llvm](crates/llvm-builder/README.md) utility to compile a compatible LLVM build locally and point `$LLVM_SYS_181_PREFIX` to the installation afterwards. The `Makefile` provides a shortcut target to obtain a compatible LLVM build: -```bash +```sh make install-llvm export LLVM_SYS_181_PREFIX=${PWD}/target-llvm/gnu/target-final ``` +
+ ### The `resolc` Solidity frontend -To build the `resolc` Solidity frontend executable, make sure you have obtained a compatible LLVM build using [revive-llvm](crates/llvm-builder/README.md) and did export the `LLVM_SYS_181_PREFIX` environment variable pointing to it (see [above](#LLVM)). +To build the `resolc` Solidity frontend executable, make sure you have obtained a compatible LLVM build and did export the `LLVM_SYS_181_PREFIX` environment variable pointing to it (see [above](#LLVM)). To install the `resolc` Solidity frontend executable: -```bash +```sh make install-bin resolc --version ``` @@ -49,7 +70,10 @@ resolc --version Cross-compile the `resolc.js` frontend executable to Wasm for running it in a Node.js or browser environment. The `REVIVE_LLVM_TARGET_PREFIX` environment variable is used to control the target environment LLVM dependency. -```bash +
+ Instructions for cross-compilation to wasm32-unknown-emscripten + +```sh # Build the host LLVM dependency with PolkaVM target support make install-llvm export LLVM_SYS_181_PREFIX=${PWD}/target-llvm/gnu/target-final @@ -65,21 +89,23 @@ make install-wasm make test-wasm ``` -### Development +
+ +## Development Please consult the [Makefile](Makefile) targets to learn how to run tests and benchmarks. Ensure that your branch passes `make test` locally when submitting a pull request. -## Design overview +### Design overview +See the [relevant section in our documentation](https://contracts.polkadot.io/revive_compiler/architecture) to learn more about how the compiler works. -`revive` uses [solc](https://github.com/ethereum/solidity/), the Ethereum Solidity compiler, as the [Solidity frontend](crates/solidity/src/lib.rs) to process smart contracts written in Solidity. The YUL IR code (or legacy EVM assembly as a fallback for older `solc` versions) emitted by `solc` is then translated to LLVM IR, targetting [Polkadots `revive` pallet](https://docs.rs/pallet-revive/latest/pallet_revive/trait.SyscallDoc.html). -[Frontend](https://github.com/matter-labs/era-compiler-solidity) and [code generator](https://github.com/matter-labs/era-compiler-llvm-context) are based of ZKSync `zksolc`. +[Frontend](https://github.com/matter-labs/era-compiler-solidity) and [code generator](https://github.com/matter-labs/era-compiler-llvm-context) are based of ZKSync `zksolc` (the project started as a fork of the era compiler). -## Tests +### Tests Before running the tests, ensure that Geth (Go Ethereum) is installed on your system. Follow the installation guide here: [Installing Geth](https://geth.ethereum.org/docs/getting-started/installing-geth). Once Geth is installed, you can run the tests using the following command: -```bash +```sh make test ```