Control concurrency and cancel in-progress runs when re-triggered.

Merge branch 'main' into lj/ci-benchmarks
The revive compiler documentation (#424 )
2026-06-14 22:41:07 +00:00 · 2025-12-02 16:38:06 +01:00 · 2025-12-02 08:13:11 +01:00 · 2025-12-01 14:58:02 +01:00 · 2025-11-29 11:06:30 +01:00 · 2025-11-27 21:36:28 -05:00
157 changed files with 15934 additions and 905 deletions
@@ -7,23 +7,56 @@ name: "Download LLVM"
 inputs:
  target:
    required: true
+  version:
+    description: "LLVM release version (e.g., 'llvm-18.1.8'). If not specified, uses the latest LLVM release."
+    required: false
+    default: ""

 runs:
  using: "composite"
  steps:
+    - name: detect llvm version from submodule
+      id: detect-version
+      shell: bash
+      run: |
+        if [ -z "${{ inputs.version }}" ]; then
+          # Extract branch from .gitmodules (e.g., "release/18.x")
+          BRANCH=$(git config -f .gitmodules submodule.llvm.branch)
+          if [ -n "$BRANCH" ]; then
+            # Extract version from branch name (e.g., "18.x" from "release/18.x")
+            VERSION_PREFIX=$(echo "$BRANCH" | sed 's|release/||' | sed 's|\.x$||')
+            echo "Detected LLVM version prefix from submodule branch: $VERSION_PREFIX"
+            
+            # Special case: pin LLVM 18 to specific version 18.1.8
+            if [ "$VERSION_PREFIX" = "18" ]; then
+              echo "Using pinned version for LLVM 18: llvm-18.1.8"
+              echo "version_prefix=llvm-18.1.8" >> $GITHUB_OUTPUT
+            else
+              echo "version_prefix=llvm-$VERSION_PREFIX" >> $GITHUB_OUTPUT
+            fi
+          else
+            echo "No branch found in .gitmodules, will use latest release"
+            echo "version_prefix=" >> $GITHUB_OUTPUT
+          fi
+        else
+          echo "Using explicitly provided version: ${{ inputs.version }}"
+          echo "version_prefix=${{ inputs.version }}" >> $GITHUB_OUTPUT
+        fi
+    
    - name: find asset
      id: find
      uses: actions/github-script@v7
      env:
        target: ${{ inputs.target }}
+        version_prefix: ${{ steps.detect-version.outputs.version_prefix }}
      with:
        result-encoding: string
        script: |
          let page = 1;
          let releases = [];

-          let releasePrefix = "llvm-"
          let target = process.env.target
+          let versionPrefix = process.env.version_prefix

          do {
            const res = await github.rest.repos.listReleases({
@@ -38,15 +71,31 @@ runs:
              return (a.published_at < b.published_at) ? 1 : ((a.published_at > b.published_at) ? -1 : 0);
            });

-            let llvmLatestRelease = releases.find(release => {
-              return release.tag_name.startsWith(releasePrefix);
-            });
-            if (llvmLatestRelease){
-                let asset = llvmLatestRelease.assets.find(asset =>{
+            let llvmRelease;
+            if (versionPrefix) {
+              // Search for latest release matching the version prefix
+              llvmRelease = releases.find(release => {
+                return release.tag_name.startsWith(versionPrefix);
+              });
+              if (llvmRelease) {
+                core.info(`Found LLVM release matching prefix '${versionPrefix}': ${llvmRelease.tag_name}`);
+              }
+            } else {
+              // Find latest LLVM release
+              llvmRelease = releases.find(release => {
+                return release.tag_name.startsWith('llvm-');
+              });
+              if (llvmRelease) {
+                core.info(`Found latest LLVM version: ${llvmRelease.tag_name}`);
+              }
+            }
+
+            if (llvmRelease){
+                let asset = llvmRelease.assets.find(asset =>{
                    return asset.name.includes(target);
                });
                if (!asset){
-                  core.setFailed(`Artifact for '${target}' not found in release ${llvmLatestRelease.tag_name} (${llvmLatestRelease.html_url})`);
+                  core.setFailed(`Artifact for '${target}' not found in release ${llvmRelease.tag_name} (${llvmRelease.html_url})`);
                  process.exit();
                }
                return asset.browser_download_url;
@@ -55,7 +104,11 @@ runs:
            page++;
          } while(releases.length > 0);

-          core.setFailed(`No LLVM releases with '${releasePrefix}' atifacts found! Please release LLVM before running this workflow.`);
+          if (versionPrefix) {
+            core.setFailed(`No LLVM releases matching prefix '${versionPrefix}' found! Please check the version.`);
+          } else {
+            core.setFailed(`No LLVM releases found! Please release LLVM before running this workflow.`);
+          }
          process.exit();

    - name: download
@@ -0,0 +1,123 @@
+# This workflow will run on the default branch when triggered by a `workflow_run` event.
+
+name: Benchmark
+
+on:
+  workflow_run:
+    workflows: [Test]
+    types: [completed]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: true
+
+jobs:
+  benchmark:
+    runs-on: ubuntu-24.04
+    if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.event == 'pull_request' }}
+    permissions:
+      pull-requests: write
+    steps:
+      - name: Checkout PR Branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Set Up Rust Toolchain
+        uses: actions-rust-lang/setup-rust-toolchain@v1
+        with:
+          # Without this it will override our rust flags.
+          rustflags: ""
+
+      - name: Install Solc
+        uses: ./.github/actions/get-solc
+
+      - name: Download LLVM
+        uses: ./.github/actions/get-llvm
+        with:
+          target: x86_64-unknown-linux-gnu
+
+      - name: Set LLVM Environment Variables
+        run: |
+          echo "LLVM_SYS_181_PREFIX=$(pwd)/llvm-x86_64-unknown-linux-gnu" >> $GITHUB_ENV
+
+      - name: Install Benchmarking Tools
+        run: |
+          cargo install critcmp
+
+      - name: Checkout and Compile Main Branch
+        run: |
+          git fetch origin main
+          git checkout -f main
+          make install
+
+      - name: Run Benchmarks on Main Branch
+        run: |
+          cargo bench --package resolc --bench compile -- --save-baseline main_resolc
+          cargo bench --package revive-yul --bench parse -- --save-baseline main_yul_parse
+          cargo bench --package revive-yul --bench lower -- --save-baseline main_yul_lower
+        timeout-minutes: 20
+
+      - name: Checkout and Compile PR Branch
+        run: |
+          git checkout -f ${{ github.event.workflow_run.head_sha }}
+          make install
+
+      - name: Run Benchmarks on PR Branch
+        run: |
+          cargo bench --package resolc --bench compile -- --save-baseline pr_resolc
+          cargo bench --package revive-yul --bench parse -- --save-baseline pr_yul_parse
+          cargo bench --package revive-yul --bench lower -- --save-baseline pr_yul_lower
+        timeout-minutes: 20
+
+      - name: Compare Benchmarks
+        run: |
+          critcmp main_resolc pr_resolc > benchmarks_resolc
+          critcmp main_yul_parse pr_yul_parse > benchmarks_yul_parse
+          critcmp main_yul_lower pr_yul_lower > benchmarks_yul_lower
+
+      - name: Create Report
+        run: |
+          cat > BENCHMARK_REPORT.md << EOF
+          # Benchmarks
+
+          ## Compile E2E
+
+          <details>
+              <summary>Results</summary>
+
+          \`\`\`
+          $(cat benchmarks_resolc)
+          \`\`\`
+
+          </details>
+
+          ## Parse Yul
+
+          <details>
+              <summary>Results</summary>
+
+          \`\`\`
+          $(cat benchmarks_yul_parse)
+          \`\`\`
+
+          </details>
+
+          ## Lower Yul
+
+          <details>
+              <summary>Results</summary>
+
+          \`\`\`
+          $(cat benchmarks_yul_lower)
+          \`\`\`
+
+          </details>
+          EOF
+
+      - name: Post PR Comment with Benchmark Report
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: benchmark
+          number: ${{ github.event.workflow_run.pull_requests[0].number }}
+          path: BENCHMARK_REPORT.md
@@ -0,0 +1,39 @@
+name: Check docs up-to-date
+on:
+  push:
+    branches: ["main"]
+    paths:
+      - 'book/**'
+      - 'docs/**'
+      - '.gitignore'
+      - 'Makefile'
+      - '.github/workflows/book.yml'
+  pull_request:
+    branches: ["main"]
+    types: [opened, synchronize]
+    paths:
+      - 'book/**'
+      - 'docs/**'
+      - '.gitignore'
+      - 'Makefile'
+      - '.github/workflows/book.yml'
+
+jobs:
+  check-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+
+      - name: Install mdBook
+        run: make test-book
+
+      - name: Build book to tmp
+        run: mdbook build book -d docs-tmp
+
+      - name: Compare with committed docs
+        run: |
+          if ! diff -r docs-tmp docs 2>/dev/null; then
+            echo "docs/ is not up-to-date. Run make test-book and commit the docs/ directory"
+            exit 1
+          fi
@@ -54,11 +54,13 @@ jobs:
          - target: aarch64-apple-darwin
            builder-arg: gnu
            host: macos
-            runner: macos-14
+            runner: macos-15
          - target: x86_64-apple-darwin
            builder-arg: gnu
            host: macos
-            runner: macos-13
+            # `macos-15-intel` will be the last x86_64 `macos` image supported by GHA.
+            # It will be available until Aug. 2027 (see https://github.com/actions/runner-images/issues/13045).
+            runner: macos-15-intel
          - target: x86_64-pc-windows-msvc
            builder-arg: gnu
            host: windows
@@ -96,10 +98,6 @@ jobs:
        run: |
          cargo install --locked --force --path crates/llvm-builder

-      - name: Clone LLVM
-        run: |
-          revive-llvm --target-env ${{ matrix.builder-arg }} clone
-
      - name: Build LLVM
        if: ${{ matrix.target != 'wasm32-unknown-emscripten' }}
        run: |
@@ -108,6 +106,7 @@ jobs:
      - name: Build LLVM
        if: ${{ matrix.target == 'wasm32-unknown-emscripten' }}
        run: |
+          revive-llvm emsdk
          source emsdk/emsdk_env.sh
          revive-llvm --target-env ${{ matrix.builder-arg }} build --llvm-projects lld

@@ -59,7 +59,7 @@ jobs:
    outputs:
      resolc-universal-apple-darwin_url: ${{ steps.set-output.outputs.resolc-universal-apple-darwin_url }}
      resolc-universal-apple-darwin_sha: ${{ steps.set-output.outputs.resolc-universal-apple-darwin_sha }}
-    runs-on: macos-14
+    runs-on: macos-15
    steps:
      - uses: actions/download-artifact@v4
        with:
@@ -69,7 +69,7 @@ jobs:
  create-release:
    if: startsWith(github.ref_name, 'v')
    needs: [check-version-changed, build]
-    runs-on: macos-14
+    runs-on: macos-15
    environment: tags
    steps:
      - name: Download Artifacts
@@ -126,7 +126,7 @@ jobs:

  npm-release:
    needs: [create-release]
-    runs-on: macos-14
+    runs-on: macos-15
    environment: tags
    steps:
      - uses: actions/checkout@v4
@@ -66,10 +66,12 @@ jobs:
            runner: ubuntu-24.04
          - target: aarch64-apple-darwin
            type: native
-            runner: macos-14
+            runner: macos-15
          - target: x86_64-apple-darwin
            type: native
-            runner: macos-13
+            # `macos-15-intel` will be the last x86_64 `macos` image supported by GHA.
+            # It will be available until Aug. 2027 (see https://github.com/actions/runner-images/issues/13045).
+            runner: macos-15-intel
          - target: x86_64-pc-windows-msvc
            type: native
            runner: windows-2022
@@ -4,11 +4,8 @@ on:
    branches: ["main"]
    types: [opened, synchronize]
    paths:
-      - 'LLVM.lock'
      - 'crates/llvm-builder/**'
      - '.github/workflows/test-llvm-builder.yml'
-    paths-ignore:
-      - "**.md"

 concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
@@ -21,10 +18,12 @@ jobs:
  test:
    strategy:
      matrix:
-        runner: [parity-large, macos-14, windows-2022]
+        runner: [parity-large, macos-15, windows-2022]
    runs-on: ${{ matrix.runner }}
    steps:
      - uses: actions/checkout@v4
+        with:
+          submodules: true
      - uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          # without this it will override our rust flags
@@ -37,7 +36,7 @@ jobs:
          sudo apt update && sudo apt-get install -y cmake ninja-build curl git libssl-dev pkg-config clang lld musl

      - name: Install Dependencies
-        if: matrix.runner == 'macos-14'
+        if: matrix.runner == 'macos-15'
        run: |
          brew install ninja

@@ -68,7 +68,7 @@ jobs:
    needs: build
    strategy:
      matrix:
-        os: ["ubuntu-24.04", "macos-14", "windows-2022"]
+        os: ["ubuntu-24.04", "macos-15", "windows-2022"]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
@@ -3,12 +3,15 @@
 target-llvm
 *.dot
 .vscode/
+.zed/
 .DS_Store
 /*.sol
 /*.yul
 /*.ll
 /*.s
-/llvm*
+/llvm-*
+# Allow llvm submodule directory
+!/llvm
 node_modules
 artifacts
 tmp
@@ -19,3 +22,4 @@ test-results
 playwright-report
 .cache
 emsdk
+docs-tmp
@@ -0,0 +1,4 @@
+[submodule "llvm"]
+	path = llvm
+	url = https://github.com/llvm/llvm-project.git
+	branch = release/18.x
@@ -0,0 +1,3 @@
+# This is no longer in .gitignore; we add it here (honored by tools like rg and fd).
+llvm/
+docs/
@@ -6,6 +6,16 @@ This is a development pre-release.

 Supported `polkadot-sdk` rev: `2509.0.0`

+### Added
+- The comprehensive revive compiler book documentation page: https://paritytech.github.io/revive/
+
+### Changed
+- Instruct the LLVM backend and linker to `--relax` (may lead to smaller contract code size).
+- Standard JSON mode: Don't forward EVM bytecode related output selections to solc.
+
+### Fixed:
+- The missing `STOP` instruction at the end of `code` blocks.
+
 ## v0.5.0

 This is a development pre-release.
@@ -34,13 +34,13 @@ revive-yul = { version = "0.4.0", path = "crates/yul" }
 hex = "0.4.3"
 cc = "1.2"
 libc = "0.2.172"
-tempfile = "3.20"
+tempfile = "3.23"
 anyhow = "1.0"
 semver = { version = "1.0", features = ["serde"] }
 itertools = "0.14"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = { version = "1.0", features = ["arbitrary_precision"] }
-regex = "1.11"
+regex = "1.12"
 once_cell = "1.21"
 num = "0.4.3"
 sha1 = "0.10"
@@ -48,20 +48,20 @@ sha3 = "0.10"
 thiserror = "2.0"
 which = "8.0"
 path-slash = "0.2"
-rayon = "1.10"
+rayon = "1.11"
 clap = { version = "4", default-features = false, features = ["derive"] }
-polkavm-common = "0.29.0"
-polkavm-linker = "0.29.0"
-polkavm-disassembler = "0.29.0"
-polkavm = "0.29.0"
-alloy-primitives = { version = "1.1", features = ["serde"] }
-alloy-sol-types = "1.1"
-alloy-genesis = "1.0.41"
-alloy-serde = "1.0"
+polkavm-common = "0.30.0"
+polkavm-linker = "0.30.0"
+polkavm-disassembler = "0.30.0"
+polkavm = "0.30.0"
+alloy-primitives = { version = "1.4", features = ["serde"] }
+alloy-sol-types = "1.4"
+alloy-genesis = "1.1.2"
+alloy-serde = "1.1"
 env_logger = { version = "0.11.8", default-features = false }
-serde_stacker = "0.1.12"
+serde_stacker = "0.1.14"
 criterion = { version = "0.7", features = ["html_reports"] }
-log = { version = "0.4.27" }
+log = { version = "0.4.28" }
 git2 = { version = "0.20.2", default-features = false }
 downloader = "0.2.8"
 flate2 = "1.1"
@@ -71,7 +71,7 @@ tar = "0.4"
 toml = "0.9"
 assert_cmd = "2"
 assert_fs = "1.1"
-normpath = "1.3"
+normpath = "1.5"

 # polkadot-sdk and friends
 codec = { version = "3.7.5", default-features = false, package = "parity-scale-codec" }
@@ -1,3 +0,0 @@
-url = "https://github.com/llvm/llvm-project.git"
-branch = "release/18.x"
-ref = "3b5b5c1ec4a3095ab096dd780e84d7ab81f3d7ff"
@@ -10,16 +10,21 @@
 	format \
 	clippy \
 	doc \
+	book \
 	machete \
 	test \
 	test-integration \
 	test-resolc \
+	test-yul \
 	test-workspace \
 	test-wasm \
-	test-llvm-builder
+	test-llvm-builder \
+	test-book \
 	bench \
 	bench-pvm \
 	bench-evm \
+	bench-resolc \
+	bench-yul \
 	clean

 install: install-bin install-npm
@@ -38,7 +43,7 @@ install-llvm-builder:
 	cargo install --force --locked --path crates/llvm-builder

 install-llvm: install-llvm-builder
-	revive-llvm clone
+	git submodule update --init --recursive --depth 1
 	revive-llvm build --llvm-projects lld --llvm-projects clang

 install-revive-runner:
@@ -56,20 +61,26 @@ clippy:
 doc:
 	cargo doc --all-features --workspace --document-private-items --no-deps

+book: test-book
+	mdbook serve book --open
+
 machete:
 	cargo install cargo-machete
 	cargo machete

-test: format clippy machete test-workspace install-revive-runner install-revive-explorer doc
+test: format clippy machete test-workspace install-revive-runner install-revive-explorer doc test-book

 test-integration: install-bin
 	cargo test --package revive-integration

 test-resolc: install
-	cargo test --package resolc
+	cargo test --package resolc --all-targets
+
+test-yul:
+	cargo test --package revive-yul --all-targets

 test-workspace: install
-	cargo test --workspace --exclude revive-llvm-builder
+	cargo test --workspace --all-targets --exclude revive-llvm-builder

 test-wasm: install-wasm
 	npm run test:wasm
@@ -78,6 +89,11 @@ test-llvm-builder:
 	@echo "warning: the llvm-builder tests will take many hours"
 	cargo test --package revive-llvm-builder -- --test-threads=1

+test-book:
+	cargo install mdbook --version 0.5.1 --locked
+	mdbook test book
+	mdbook build book
+
 bench: install-bin
 	cargo criterion --all --all-features --message-format=json \
 	| criterion-table > crates/benchmarks/BENCHMARKS.md
@@ -90,6 +106,16 @@ bench-evm: install-bin
 	cargo criterion --bench execute --features bench-evm --message-format=json \
 	| criterion-table > crates/benchmarks/EVM.md

+bench-resolc: test-resolc
+	cargo criterion --package resolc --bench compile --message-format=json \
+	| criterion-table > crates/resolc/BENCHMARKS_M4PRO.md
+
+bench-yul: test-yul
+	cargo criterion --package revive-yul --bench parse --message-format=json \
+	| criterion-table > crates/yul/BENCHMARKS_PARSE_M4PRO.md
+	cargo criterion --package revive-yul --bench lower --message-format=json \
+	| criterion-table > crates/yul/BENCHMARKS_LOWER_M4PRO.md
+
 clean:
 	cargo clean ; \
 	revive-llvm clean ; \
@@ -97,3 +123,4 @@ clean:
 	rm -rf crates/resolc/src/tests/cli/artifacts ; \
 	cargo uninstall resolc ; \
 	cargo uninstall revive-llvm-builder ;
+	mdbook clean book
@@ -1,11 +1,11 @@
 ![CI](https://github.com/paritytech/revive/actions/workflows/test.yml/badge.svg)
-[![Docs](https://img.shields.io/badge/Docs-contracts.polkadot.io-brightgreen.svg)](https://contracts.polkadot.io/revive_compiler/)
+[![Docs](https://img.shields.io/badge/paritytech.github.io/revive-brightgreen.svg)](https://paritytech.github.io/revive/)

 # revive

-YUL recompiler to LLVM, targetting RISC-V on [PolkaVM](https://github.com/koute/polkavm).
+Yul recompiler to LLVM, targetting RISC-V on [PolkaVM](https://github.com/koute/polkavm).

-Visit [contracts.polkadot.io](https://contracts.polkadot.io) to learn more about contracts on Polkadot!
+Check the [docs](https://paritytech.github.io/revive/) or visit [contracts.polkadot.io](https://docs.polkadot.com/develop/smart-contracts/) to learn more about `revive` and contracts on Polkadot!

 ## Status

@@ -14,11 +14,13 @@ 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
+
 Building Solidity contracts for PolkaVM requires installing the following two compilers:
- `resolc`: The revive Solidity compiler YUL frontend and PolkaVM code generator (provided by this repository).
+- `resolc`: The revive Solidity compiler Yul frontend and PolkaVM code generator (provided by this repository).
 - `solc`: The [Ethereum Solidity reference compiler](https://github.com/ethereum/solidity/) implemenation.`resolc` uses `solc` during the compilation process, please refer to the [Ethereum Solidity documentation](https://docs.soliditylang.org/en/latest/installing-solidity.html) for installation instructions.

 ### `resolc` binary releases
+
 `resolc` is distributed as a standalone binary (with `solc` as the only external dependency). Please download one of our [binary releases](https://github.com/paritytech/revive/releases) for your target platform and mind the platform specific instructions below.

 <details>
@@ -44,6 +46,7 @@ Building Solidity contracts for PolkaVM requires installing the following two co


 ### `resolc` NPM package
+
 We distribute the revive compiler as [node.js module](https://www.npmjs.com/package/@parity/resolc) and [hardhat plugin](https://www.npmjs.com/package/@parity/hardhat-polkadot-resolc).

 Note: The `solc` dependency is bundled via NPM packaging and defaults to the latest supported version.
@@ -96,47 +99,10 @@ make install-bin
 resolc --version
 ```

-### Cross-compilation to Wasm
-
-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.
-
-<details>
-  <summary>Instructions for cross-compilation to wasm32-unknown-emscripten</summary>
-
-```sh
-# Build the host LLVM dependency with PolkaVM target support
-make install-llvm
-export LLVM_SYS_181_PREFIX=${PWD}/target-llvm/gnu/target-final
-
-# Build the target LLVM dependency with PolkaVM target support
-revive-llvm --target-env emscripten clone
-source emsdk/emsdk_env.sh
-revive-llvm --target-env emscripten build --llvm-projects lld
-export REVIVE_LLVM_TARGET_PREFIX=${PWD}/target-llvm/emscripten/target-final
-
-# Build the resolc frontend executable
-make install-wasm
-make test-wasm
-```
-
-</details>
-
 ## 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.
+Please consult the [Developer Guide](https://paritytech.github.io/revive/developer_guide/contributing.html) to learn more about how contribute to the project.

-### Design overview
-See the [relevant section in our documentation](https://contracts.polkadot.io/revive_compiler/architecture) to learn more about how the compiler works. 
-
-### 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:
-
-```sh
-make test
-```
 # Acknowledgements

 The revive compiler project, after some early experiments with EVM bytecode translations, decided to fork the `era-compiler` framework.
@@ -0,0 +1 @@
+book
@@ -0,0 +1,7 @@
+[book]
+title = "revive compiler book"
+authors = ["xermicus"]
+language = "en"
+
+[build]
+build-dir = "../docs"
@@ -0,0 +1,21 @@
+# Summary
+
+- [Welcome](./welcome.md)
+- [`resolc` user guide](./user_guide.md)
+  - [Installation](./user_guide/installation.md)
+  - [Command Line Interface](./user_guide/cli.md)
+  - [JS NPM package](./user_guide/js.md)
+  - [Tooling integration](./user_guide/tooling.md)
+  - [Standard JSON interface](./user_guide/std_json.md)
+  - [Differences to EVM](./user_guide/differences.md)
+  - [Rust contract libraries](./user_guide/rust_libraries.md)
+- [`revive-runner` sandbox](./revive_runner.md)
+- [Developer Guide](./developer_guide.md)
+  - [Contributor guide](./developer_guide/contributing.md)
+  - [Compiler architecture](./developer_guide/architecture.md)
+  - [PVM and the pallet-revive runtime target](./developer_guide/target.md)
+  - [Testing strategy](./developer_guide/testing.md)
+  - [Cross compilation](./developer_guide/cross_compilation.md)
+- [FAQ](./faq.md)
+- [Roadmap and Vision](./roadmap.md)
+
@@ -0,0 +1,4 @@
+# Developer guide
+
+This chapter covers internal aspects of the compiler and helps contributors getting started with the `revive` codebase.
+
@@ -0,0 +1,55 @@
+# Compiler architecture and internals
+
+`revive` relies on `solc`, the [Ethereum Solidity compiler](https://github.com/argotorg/solidity), as the Solidity frontend to process smart contracts written in Solidity. [LLVM](https://github.com/llvm/llvm-project), a popular and powerful compiler framework, is used as the compiler backend and does the heavy lifting in terms of optimizitations and RISC-V code generation.
+
+`revive` mainly takes care of lowering the Yul intermediate representation (IR) produced by `solc` to LLVM IR. This approach provides a good balance between maintaining a high level of Ethereum compatibility, good contract performance and feasible engineering efforts.
+
+## `resolc`
+
+`resolc` is the overarching compiler driver library and binary.
+
+When compiling a Solidity source file with `resolc`, the following steps happen under the hood:
+1. `solc` is used to lower the Solidity source code into [YUL intermediate representation](https://docs.soliditylang.org/en/latest/yul.html).
+2. `revive` lowers the YUL IR into LLVM IR.
+3. LLVM optimizes the code and emits a RISC-V ELF shared object (through LLD).
+4. The [PolkaVM](https://github.com/paritytech/polkavm) linker finally links the ELF shared object into a PolkaVM blob.
+
+This compilation process can be visualized as follows:
+
+![Architecture Overview](images/resolc.svg)
+
+## Reproducible contract builds
+
+Because on-chain contract code is identified via its code blob hash, it is crucial to maintain reproducible contract builds. A given compiler version must reproduce the contract build _exactly_ on every target platform `resolc` supports via the official binary releases.
+
+To ensure this, we employ the following measures:
+- The code generation must be fully deterministic. For example iterating over standard `HashMap` invalidates this due to its internal state, making it an invalid operation in `revive`. To circumvent that, a `BTreeMap` can be used instead.
+- We release fully statically linked `resolc` binaries. This prevents dynamic linking of potentially differentiating libraries.
+- The only non-bundled dependency is the `solc` compiler. This is considered fine because the same properties apply to `solc`.
+
+## The `revive` compiler libraries
+
+The main compiler logic is implemented in the `revive-yul` and `revive-llvm-context` crates.
+
+The Yul library implements a lexer and parser and lowers the resulting tree into LLVM IR. It does so by emitting LL using the LLVM builder and our own `revive-llvm-context` compiler context crate. The revive LLVM context crate encapsulates code generation logic (decoupled from the parser).
+
+The Yul library also implements a simple [visitor](https://en.wikipedia.org/wiki/Visitor_pattern) interface (see [visitor.rs](https://github.com/paritytech/revive/blob/main/crates/yul/src/visitor.rs)). If you want to work with the AST, it is strongly recommended to implement visitors. The LLVM code generation is implemented using a dedicated trait for historical reasons only.
+
+## EVM heap memory
+
+PVM doesn't offer a similar API. Hence the emitted contract code emulates the linear EVM heap memory using a static byte buffer. Data inside this byte buffer is kept big endian for EVM compatibility reasons (unaligned access is allowed and makes optimizing this non-trivial).
+
+Unlike with the EVM, where heap memory usage is gas metered, our heap size is static (the size is user controllable via a setting flag). The compiler emits bound checks to prevent overflows.
+
+## The LLVM dependency
+
+LLVM is a special non Rust dependency. We interface its builder interface via the [inkwell](https://crates.io/crates/inkwell) wrapper crate.
+
+We use upstream LLVM, but release and use our custom builds. We require the compiler builtins specifically built for the PVM rv64e target and always leave assertions on. Furthermore, we need cross builds because `resolc` itself targets emscripten and musl. The [revive-llvm-builer](https://crates.io/crates/revive-llvm-builder) functions as a cross-platform build script and is used to build and release the LLVM dependency.
+
+We also maintain the [lld-sys crate](https://crates.io/crates/lld-sys) for interfacing with `LLD`. The LLVM linker is used during the compilation process, but we don't want to distribute another binary.
+
+
+## Custom optimizations
+
+At the moment, no significant custom optimizations are implemented. Thus, we are missing some optimization opportunities that neither `solc` nor LLVM can realize (due to their lack of domain specific knowledge about the semantics of our target environment). Furthermore, `solc` optimizes for EVM gas and a target machine orthogonal to our target (BE 256-bit stack machine EVM vs. 64-bit LE RISC architecture PVM). We have started working on an additional IR layer between Yul and LLVM to capture missed optimization opportunities, though.
@@ -0,0 +1,65 @@
+# Contributor guide
+
+The `revive` compiler is an open source software project and we gladly accept quality contributions from anyone!
+
+## Getting started
+
+A quick reference on how to build the Solidity compiler is maintained in the project's [README.md](https://github.com/paritytech/revive?tab=readme-ov-file#building-from-source).
+
+### Using the `Makefile`
+
+The [Makefile](https://github.com/paritytech/revive/blob/main/Makefile) comprehensively encapsulates all development aspects of this codebase. It is kept concise and readable. Please read and use it! You'll learn for example:
+
+- How to build and install a `resolc` development version.
+- How to run tests and benchmarks.
+- How to cross-compile `resolc`.
+
+As a general rule-of-thumb: If `make test` runs fine locally, chances for green CI pipelines are good.
+
+### Codebase organization
+
+For the most parts, `revive` is a rather standard Rust workspace codebase. There are some non-Rust dependencies, which sometimes complicates things a little bit.
+
+#### The `crates/` dir
+
+All Rust crates live under the `crates/` directory. The workspace automatically considers any crate found therein. If you need to add a new create, please implement it there.
+
+Compiler library crates should be named with the `revive-` prefix. The crate location doesn't need the prefix.
+
+#### Dependencies
+
+Dependencies should be added as workspace dependencies. Try to avoid pinning dependencies whenever possible. If possible, add dev dependencies as `dev-dependencies` only.
+
+Please do always include the `Cargo.lock` dependency lock file with your PR. Please don't run `cargo update` together with other changes (it is preferred to update the lock file in a dedicated dependency update PR).
+
+## Contribution rules
+
+1. Changes must be submitted via a pull request (PR) to the github upstream repository.
+2. Ensure that your branch passes `make test` locally when submitting a pull request.
+3. A PR must not be merged until CI fully passes. Exceptions can be made (for example to fix CI issues itself).
+4. No force pushes to the `main` branch and open PR branches.
+5. Maintainers can request changes or deny contributions at their own discretion.
+
+## Style guide
+
+We require the official Rust formatter and clippy linter. In addition to that, please also consider the following best-effort aspects:
+
+- Avoid [magic numbers](https://en.wikipedia.org/wiki/Magic_number_(programming)) and strings. Instead, add them as module constants.
+- Avoid abbreviated variable and function names. Always provide meaningful and readable symbols.
+- Don't write macros and don't use third party macros for things that can easily be expressed in few lines of code or outlined into functions.
+- Avoid import aliasing. Please use the parent or fully qualified path for conflicting symbols.
+- Any inline comments must provide additional semantic meaning, explain counter-intuitive behavior or highlight non-obvious design decisions. In other words, try to make the code expressive enough to a degree it doesn't need comments expressing the same thing again in the English language. Delete such comments if your AI assistant generated them.
+- Public items must have a meaningful doc comment.
+- Provide meaningful panic messages to `.expect()` or just use `.unwrap()`.
+
+## AI policy
+
+Contributors may use whatever AI assistance tools they wish to whatever degree they wish in the process of creating their contribution, __given they acknowledge the following__:
+
+_Project maintainers may reject any contribution (or portions of it) if the contribution shows signs of problematic involvement of generative AI_.
+
+Judgement of "problematic involvement" lies at the sole discretion of project maintainers. No proof (whether a contribution was in fact AI generated or not) is required. Rationale:
+
+- No one enjoys reading soulless and uncanny LLM slop. Please review and fix any AI slop yourself prior to submitting a PR.
+- A Solidity compiler is security sensitive software. Even miniscule mistakes can ultimately lead to loss of funds. AI models are inherently stochastic. They regurarly fail to capture important nuances or produce straight hallucinations. Code that was "blindly" generated has no home here.
+- `revive` is a large codebase. Generative AI assistants may not have enough "context window" to sufficiently capture correctness, consistency and style aspects of the codebase. We'd like to keep this codebase maintainable _by humans_ for the forseeable future.
@@ -0,0 +1,30 @@
+# Cross compilation
+
+We cross-compile the `resolc.js` frontend executable to Wasm for running it in a Node.js or browser environment.
+
+The [musl](https://www.musl-libc.org/) target is used to obtain statically linked ELF binaries for Linux.
+
+## Wasm via emscripten
+
+The `REVIVE_LLVM_TARGET_PREFIX` environment variable is used to control the target environment LLVM dependency. This requires a compatible LLVM build, obtainable via the `revive-llvm` build script. Example:
+
+```sh
+# Build the host LLVM dependency with PolkaVM target support
+make install-llvm
+export LLVM_SYS_181_PREFIX=${PWD}/target-llvm/gnu/target-final
+
+# Build the target LLVM dependency with PolkaVM target support
+revive-llvm emsdk
+source emsdk/emsdk_env.sh
+revive-llvm --target-env emscripten build --llvm-projects lld
+export REVIVE_LLVM_TARGET_PREFIX=${PWD}/target-llvm/emscripten/target-final
+
+# Build the resolc frontend executable
+make install-wasm
+make test-wasm
+```
+
+## musl libc
+
+[rust-musl-cross](https://github.com/rust-cross/rust-musl-cross) is a straightforward way to cross compile Rust to musl. The [Dockerfile](https://github.com/paritytech/revive/blob/main/Dockerfile) is an executable example of how to do that. 
+
@@ -0,0 +1,29 @@
+# PVM and the pallet-revive runtime target
+
+The `revive` compiler targets [PolkaVM (PVM)](https://github.com/paritytech/polkavm) via [pallet-revive](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive) on Polkadot.
+
+## Target CPU configuration
+
+The exact target CPU configuration can be found [here](https://github.com/paritytech/revive/blob/8cd10a613625428956eb33c39c9022a91bfbf103/crates/llvm-context/src/target_machine/mod.rs#L22-L32).
+
+> [!NOTE]
+>
+> The PVM linker requires fully relocatable ELF objects.
+
+## Why PVM
+
+PVM is a RISC-V based VM designed to overcome the flaws of [WebAssebmly (Wasm)](https://webassembly.org/). Wasm was believed to be a more efficient successor to the rather slow EVM. However, Wasm is far from an ideal target for smart contracts as some of its design decisions are unfavorable for short-lived workloads. The main problem is on-chain Wasm bytecode compilation or interpretation overhead. Prior benchmarks consistently ignoring this overhead seeded the blockchain industry with flawed assumptions: _Only when ignoring the startup overhead_ Wasm is much faster than the slow computing EVM. In practice however, gains are nullified entirely and Wasm loses completely even against very slow VMs like the EVM. Executing Wasm contracts is in fact so inefficient that typical contract workloads are _orders of magnitude_ more expensive than the equivalent EVM variant.
+
+On the other hand, since RISC-V is similar to CPUs found in validator hardware (x86 and ARM), bytecode translation mostly boils down to a linear mapping from one instruction to another. The _embedded_ ISA specification reduces the number of general purpose registers, in turn removing the need for expensive register allocation. This guarantees single-pass `O(n)` JIT compilation of contract bytecode. The close proximity of PVM bytecode with actual validator CPU bytecode effectively allows to move all expensive compilation workload off-chain. Benchmarks ([1](https://hackmd.io/@XXX9CM1uSSCWVNFRYaSB5g/HJarTUhJA#Results-execute), [2](https://github.com/paritytech/polkavm/blob/master/BENCHMARKS.md)) show that with the PVM JIT, sandboxed PVM code executes at around half the speed of native code, which falls into the same ballpark of the state-of-the-art `wasmtime` Wasm implementation (while EVM sits somewhere around 1/10 to less than 1/100 of native speed). However, the PVM JIT compiler only uses a fraction of the time `wasmtime` requires to compile the code.
+
+> [!NOTE]
+>
+> The PVM JIT isn't available yet in `pallet-revive`. At the time of writing, the contract code is interpreted, which is orders of magnitude slower than the JIT.
+
+## Host environment: `pallet-revive`
+
+The `revive` compiler targets the [`pallet-revive` runtime environment](https://docs.rs/pallet-revive/).
+
+`pallet-revive` exposes a [syscall like interface](https://docs.rs/pallet-revive/latest/pallet_revive/trait.SyscallDoc.html) for contract interactions with the host environment. This is provided by the [revive-runtime-api](https://crates.io/crates/revive-runtime-api) library. 
+
+After the initial launch on the Polkadot Asset Hub blockchain, the runtime API is considered stable and backwards compatible indefinitively.
@@ -0,0 +1,67 @@
+# Testing strategy
+
+Contributors are encouraged to implement some appropriate unit and integration tests together with any bug fixes or new feature implementations. However, when it comes to testing the code generation logic, our testing strategy goes way beyond simple unit and integration tests. This chapter explains how the `revive` compiler implementation is tested for correctness and how we define correctness.
+
+> [!TIP]
+>
+> Running the integration tests require the `evm` tool from `go-ethereum` in your `$PATH`.
+>
+> Either install it using your package manager or to build it from source:
+> ```bash
+> git clone https://github.com/ethereum/go-ethereum/
+> cd go-ethereum
+> make all
+> export PATH=/path/to/go-ethereum/build/bin/:$PATH
+> ```
+
+## Bug compatibility with Ethereum Solidity
+
+As a Solidity compiler, we aim to preserve contract code semantics as close as possible to Solidity compiled to EVM with the `solc` reference implementation. As highlighted in the user guide, due to the underlying target difference, this isn't always possible. However, wherever it is possible, we follow the philosophy of [**bug compatibility**](https://en.wikipedia.org/wiki/Bug_compatibility) with the Ethereum contracts stack.
+
+## Differential integration tests
+
+A high level of bug compatibility with Ethereum is ensured through [**differential testing**](https://en.wikipedia.org/wiki/Differential_testing) with the Ethereum `solc` and EVM contracts stack. The [revive-integration](https://crates.io/crates/revive-integration) library is the central integration test utility, providing a set of Solidity integration test cases. Further, it implements differential tests against the reference implementation by combining the [revive-runner](https://crates.io/crates/revive-runner) sandbox, the [go-ethereum EVM tool](https://github.com/ethereum/go-ethereum/tree/master/cmd/evm) and the [revive-differential](https://crates.io/crates/revive-differential).
+  
+The `revive-runner` library provides a [**declarative**](https://en.wikipedia.org/wiki/Declarative_programming) test [specification format](https://github.com/paritytech/revive/blob/main/crates/runner/src/specs.rs). This vastly simplifies writing differential test cases and removes a lot of room for errors in test logic. Example:
+
+```json
+{
+    "differential": true,
+    "actions": [
+        {
+            "Instantiate": {
+                "code": {
+                    "Solidity": {
+                        "contract": "Bitwise"
+                    }
+                }
+            }
+        },
+        {
+            "Call": {
+                "dest": {
+                    "Instantiated": 0
+                },
+                "data": "3fa4f245"
+            }
+        }
+    ]
+}
+```
+
+Above example instantiates the `Bitwise` contract and calls it with some defined calldata. The `revive-runner` library implements a helper wrapper to execute test specs on the go-ethereum standalone `evm` tool. This allows the `revive-runner` to execute specs against the EVM and the `pallet-revive` runtime. Key to differential testing is setting `"differential": true`, resulting in the following:
+
+1. The `Bitwise` contract is compiled to EVM and PVM code.
+2. The runner executes the defined `actions` on the EVM and collects all state changes (storage, balance) and execution results.
+3. The runner executes each action on the PVM. Observed state changes _after each step_ as well as the final execution result is asserted to  match the EVM counterparts __exactly__.
+
+__Note how we never defined any expected outcome manually.__ Instead, we simply observe and collect the data defining the "correct" outcome.
+
+Differential testing in combination with declarative test specifications proved to be simple, yet very effective, in ensuring expected Ethereum Solidity semantics on `pallet-revive`.
+
+## The differential testing utility
+
+A lot of nuanced bugs caused by tiny implementation details inside the `revive` compiler _and_ the `pallet-revive` runtime could be identified and eliminated early on thanks to the differential testing strategy. Thus, we decided to take this approach further and created a comprehensive test runner and a large suite of more complex test cases.
+
+The [Revive Differential Tests](https://github.com/paritytech/revive-differential-tests/) follow the exact same strategy but implement a much more powerful test spec format, spec runner and reports. This allows differentially testing much more complex test cases (for example testing Uniswap pair creations and swaps), executed via transactions sent to actual blockchain nodes.
+
@@ -0,0 +1,28 @@
+# FAQ
+
+## What EVM version do you support?
+
+We neither do nor don't support any EVM version. We support Solidity versions, starting from `solc` version 0.8.0 onwards.
+
+## Is inline assembly supported
+
+Yes, almost all inline assembly features are supported ([see the differences in Yul translation chapter](user_guide/differences.md)).
+
+## Do you support opcode `XY`?
+
+See above, the same applies.
+
+## In what Solidity version should I write my dApp?
+
+We generally recommend to always use the latest supported version to profit from latest bugfixes, features and performance improvements.
+
+Find out about the latest supported version by running `resolc --supported-solc-versions` or checking [here](https://github.com/paritytech/resolc-bin).
+
+## Tool `XY` says the contract size is larger than 24kb and will fail to deploy?
+
+The 24kb code size restriction only exist for the EVM. Our limit is currently around 1mb and may increase further in the future.
+
+## Is `resolc` a drop-in replacement for `solc`?
+
+No. `resolc` aims to work similarly to `solc`, but it's not considered a drop-in replacement.
+
@@ -0,0 +1,45 @@
+# `revive-runner` sandbox
+
+Running contract code usually requires a blockchain node. While local dev nodes can be used, sometimes it's just not desirable to do so. Instead, it can be much more convenient to run and debug contract code with a stripped down environment.
+
+This is where the `revive-runner` comes in handy. In a nutshell, it is a single-binary no-blockchain `pallet-revive` runtime.
+
+## Installation and usage
+
+Inside the root `revive` repository directory, install it from source (requires Rust installed):
+
+```bash
+make install-revive-runner
+```
+
+After installing, see `revive-runner --help` for usage help.
+
+## Trace logs
+
+The standard `RUST_LOG` environment variable controls the log output from the contract execution. This includes `revive` runtime logs and PVM execution trace logs. Sometimes it's convenient to have more fine granular insight. Some useful filters:
+- `RUST_LOG=runtime=trace`: The `pallet-revive` runtime trace logs.
+- `RUST_LOG=polkavm=trace`: Low level PolkaVM instruction tracing.
+
+## Automatic contract instantiation
+
+To avoid running the constract in an unitialized state, `revive-runner` automatically instantiates the contract before calling it (constructor arguments can be provided).
+
+## Example
+
+Suppose we want to trace the syscalls of the execution of a compiled contract file `Flipper.pvm`:
+
+```bash
+RUST_LOG=runtime=trace revive-runner -f Flipper.pvm
+[DEBUG runtime::revive] Contract memory usage: purgable=6144/3145728 KB baseline=103063/1572864
+[TRACE runtime::revive::strace] call_data_size() = Ok(0) gas_consumed: Weight { ref_time: 985209, proof_size: 0 }
+[TRACE runtime::revive::strace] value_transferred(out_ptr: 4294836096) = Ok(()) gas_consumed: Weight { ref_time: 2937634, proof_size: 0 }
+[TRACE runtime::revive::strace] call_data_copy(out_ptr: 131216, out_len: 0, offset: 0) = Ok(()) gas_consumed: Weight { ref_time: 4084483, proof_size: 0 }
+[TRACE runtime::revive::strace] seal_return(flags: 0, data_ptr: 131216, data_len: 0) = Err(TrapReason::Return(ReturnData { flags: 0, data: [] })) gas_consumed: Weight { ref_time: 5510615, proof_size: 0 }
+[TRACE runtime::revive] frame finished with: Ok(ExecReturnValue { flags: (empty), data: [] })
+[TRACE runtime::revive::strace] call_data_size() = Ok(0) gas_consumed: Weight { ref_time: 985209, proof_size: 0 }
+[TRACE runtime::revive::strace] seal_return(flags: 1, data_ptr: 131088, data_len: 0) = Err(TrapReason::Return(ReturnData { flags: 1, data: [] })) gas_consumed: Weight { ref_time: 2456669, proof_size: 0 }
+[TRACE runtime::revive] frame finished with: Ok(ExecReturnValue { flags: REVERT, data: [] })
+```
+
+
+
@@ -0,0 +1,16 @@
+# Roadmap and Vision
+
+The `revive` compiler speeds up Solidity contracts by orders of magnitude. `revive` provides a decisive edge over other contract platforms. Notably, the compiler eliminates the need of rewriting Solidity dApps as single dApp parachains for scaling reasons. Retaining as high compatibility with Ethereum Solidity as possible keeps entry barriers low.
+
+We believe in Dr. Gavin Wood's [ĐApps: What Web 3.0 Looks Like](https://gavwood.com/dappsweb3.html) manifesto and the ecosystem of the Solidity programming language. Our motivation lies in the realization that for a _true_ web3 revolution, significant scaling efforts, like the ones provided by the PVM and this project, are necessary to unfold.
+
+## Roadmap
+
+The first major release, `resolc` v1.0.0, emits functional PVM code from given Solidity sources. It relies on `solc` and LLVM for optimizations. The main priority of this release was delivering a mostly feature complete and safe Solidity v0.8.0 compiler.
+
+Focus for the second major release is on the custom optimization pipeline, which aims to significantly improve emitted code blob sizes.
+
+The below roadmap gives a rough overview of the project's development timeline.
+
+![Roadmap](images/roadmap.svg)
+
@@ -0,0 +1,11 @@
+# `resolc` user guide
+
+`resolc` is a Solidity `v0.8` compiler for [Polkadot `native` smart contracts](https://docs.polkadot.com/develop/smart-contracts/overview/#native-smart-contracts). Solidity compiled with `resolc` executes orders of magnitude faster than the EVM. `resolc`  also supports almost all Solidity `v0.8` features including inline assembly, offering a high level of comptability with the Ethereum Solidity reference implementation.
+
+## `revive` vs. `resolc` nomenclature
+
+`revive` is the name of the overarching "Solidity to PolkaVM" compiler project, which contains multiple components (for example the Yul parser, the code generation library, the `resolc` executable itself, and many more things).
+
+`resolc` is the name of the compiler driver executable, combining many `revive` components in a single and easy to use binary application.
+
+In other words, `revive` is the whole compiler infrastructure (more like `LLVM`) and `resolc` is a user-facing single-entrypoint compiler frontend (more like `clang`).
@@ -0,0 +1,113 @@
+# CLI usage
+
+We aim to keep the `resolc` CLI usage close to `solc`. There are a few things and options worthwhile to know about in `resolc` which do not exist in the Ethereum world. This chapter explains those in more detail than the CLI help message.
+
+> [!TIP]
+>
+> For the complete help about CLI options, please see `resolc --help`.
+
+### LLVM optimization levels
+```bash
+-O, --optimization <OPTIMIZATION>
+```
+
+`resolc` exposes the optimization level setting for the LLVM backend. The performance and size of compiled contracts varies wiedly between different optimization levels.
+
+Valid levels are the following:
+- `0`: No optimizations are applied.
+- `1`: Basic optimizations for execution time.
+- `2`: Advanced optimizations for execution time.
+- `3`: Aggressive optimizations for execution time.
+- `s`: Optimize for code size.
+- `z`: Aggressively optimize for code size.
+
+By default, `-O3` is applied.
+
+### Stack size
+```bash
+--stack-size <STACK_SIZE>
+```
+
+PVM is a register machine with a traditional stack memory space for local variables. This controls the total amount of stack space the contract can use.
+          
+You are incentivized to keep this value as small as possible:
+1. Increasing the stack size will increase startup costs.
+2. The stack size contributes to the total memory size a contract can use, which includes the contract's code size.
+
+Default value: 32768
+          
+> [!WARNING]
+>
+> If the contract uses more stack memory than configured, it will compile fine but eventually revert execution at runtime!
+
+### Heap size
+```bash
+--heap-size <HEAP_SIZE>
+```
+
+Unlike the EVM, due to the lack of dynamic memory metering, PVM contracts emulate the EVM heap memory with a static buffer. Consequentially, instead of infinite memory with exponentially growing gas costs, PVM contracts have a finite amount of memory with constant gas costs available.
+
+You are incentivized to keep this value as small as possible:
+1.Increasing the heap size will increase startup costs.
+2.The heap size contributes to the total memory size a contract can use, which includes the contract's code size
+
+Default value: 65536
+          
+> [!WARNING]
+>
+> If the contract uses more heap memory than configured, it will compile fine but eventually revert execution at runtime!
+
+### solc
+```bash
+--solc <SOLC>
+```
+
+Specify the path to the `solc` executable. By default, the one in `${PATH}` is used.
+
+### Debug artifacts
+```bash
+--debug-output-dir <DEBUG_OUTPUT_DIRECTORY>
+```
+
+Dump all intermediary compiler artifacts to files in the specified directory. This includes the YUL IR, optimized and unoptimized LLVM IR, the ELF object and the PVM assembly. Useful for debugging and development purposes.
+
+### Debug info
+```bash
+-g
+```
+Generate source based debug information in the output code file. Useful for debugging and development purposes and disabled by default.
+
+### Deploy time linking
+```bash
+--link [--libraries <LIBRARIES>] <INPUT_FILES>
+```
+
+In Solidity, 3 things can happen with libraries:
+
+1. They are not `extern`ally callable and thus can be inlined.
+    1. The solc Solidity optimizer inlines those (usually the case). Note: `resolc` always activates the solc Solidity optimizer.
+    2. If the solc Solidity optimizer is disabled or for some reason fails to inline them (both rare), they are not inlined and require linking.
+2. They are `extern`ally callable but still linked at compile time. This is the case if at compile time the library address is known (i.e. `--libraries` supplied in CLI or the corresponding setting in STD JSON input).
+3. They are linked at deploy time. This happens when the compiler does not know the library address (i.e. `--libraries` flag is missing or the provided libraries are incomplete, same for STD JSON input). This case is rare because it's discourage and should never be used by production dApps.
+
+In cases `1.2` and `3`:
+- Some of the produced code blobs will be in the "unlinked" raw `ELF` object format and not yet deployable.
+- To make them deployable, they need to be "linked" (done using the `resolc --link` linker mode explained below).
+- The compiler emitted `DELEGATECALL` instructions to call non-inlined (unlinked) libraries. The contract deployer must make sure to deploy any libraries prior to contract deployment.
+
+> [!WARNING]
+> 
+> Using deploy time linking is officially **discouraged**. Mainly due to bytecode hashes changing after the fact. We decided to support it in `resolc` regardless, due to popular request.
+
+Similar to how it works in `solc`, `--libraries` may be used to provide libraries during linking mode.
+
+Unlike with `solc`, where linking implies a simple string substitution mechanism, `resolc` needs to resolve actual missing `ELF` symbols. This is due to how factory dependencies work in PVM. As a consequence, it isn't sufficient to just provide the unlinked blobs to the linker. Instead, they must be provided in the exact same directory structure the Solidity source code was found during compile time.
+
+Example:
+- The contract `src/foo/bar.sol:Bar` is involved in deploy time linking. It may be a factory dependency.
+- The contract blob needs to be provided inside a relative `src/foo/` directory to `--link`. Otherwise symbol resolution may fail.
+
+> [!NOTE]
+>
+> Tooling is supposed to take care of this. In the future, we may append explicit linkage data to simplify the deploy time linking feature.
+
@@ -0,0 +1,94 @@
+# Differences to EVM
+
+This section highlights some potentially observable differences in the [YUL EVM dialect](https://docs.soliditylang.org/en/latest/yul.html#evm-dialect) translation compared to Ethereum Solidity.
+
+Solidity developers deploying dApps to [`pallet-revive`](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/revive) ought to read and understand this section well.
+
+## Deploy code vs. runtime code
+
+Our contract runtime does not differentiate between runtime code and deploy (constructor) code.
+Instead, both are emitted into a single PVM contract code blob and live on-chain.
+Therefore, in EVM terminology, the deploy code equals the runtime code.
+
+> [!TIP]
+>
+> In constructor code, the `codesize` instruction will return the call data size instead of the actual code blob size.
+
+## Solidity
+
+We are aware of the following differences in the translation of Solidity code.
+
+### `address.creationCode`
+
+This returns the bytecode keccak256 hash instead.
+
+## YUL functions
+
+The below list contains noteworthy differences in the translation of YUL functions.
+
+> [!NOTE]
+>
+> Many functions receive memory buffer offset pointer or size arguments. Since the PVM pointer size is 32 bit, supplying memory offset or buffer size values above `2^32-1` will trap the contract immediately.
+
+The `solc` compiler ought to always emit valid memory references, so Solidity dApp authors don't need to worry about this unless they deal with low level `assembly` code.
+
+### `mload`, `mstore`, `msize`, `mcopy` (memory related functions) 
+
+In general, revive preserves the memory layout, meaning low level memory operations are supported. However, a few caveats apply:
+- The EVM linear heap memory is emulated using a fixed byte buffer of 64kb. This implies that the maximum memory a contract can use is limited to 64kbit (on Ethereum, contract memory is capped by gas and therefore varies).
+- Thus, accessing memory offsets larger than the fixed buffer size will trap the contract at runtime with an `OutOfBound` error.
+- The compiler might detect and optimize unused memory reads and writes, leading to a different `msize` compared to what the EVM would see. 
+
+### `calldataload`, `calldatacopy`
+
+In the constructor code, the offset is ignored and this always returns `0`.
+
+### `codecopy`
+
+Only supported in constructor code.
+
+### `invalid`
+
+Traps the contract but does not consume the remaining gas.
+
+### `create`, `create2`
+
+Deployments on revive work different than on EVM. In a nutshell: Instead of supplying the deploy code concatenated with the constructor arguments (the EVM deploy model), the [revive runtime expects two pointers](https://docs.rs/pallet-revive/latest/pallet_revive/trait.SyscallDoc.html#tymethod.instantiate):
+1. A buffer containing the code hash to deploy.
+2. The constructor arguments buffer.
+
+To make contract instantiation using the `new` keyword in Solidity work seamlessly,
+`revive` translates the `dataoffset` and `datasize` instructions so that they assume the contract hash instead of the contract code.
+The hash is always of constant size.
+Thus, `revive` is able to supply the expected code hash and constructor arguments pointer to the runtime. 
+
+> [!WARNING]
+>
+> This might fall apart in code creating contracts inside `assembly` blocks. **We strongly discourage using the `create` family opcodes to manually craft deployments in `assembly` blocks!** Usually, the reason for using `assembly` blocks is to save gas, which is futile on revive anyways due to lower transaction costs.
+
+### `dataoffset`
+
+Returns the contract hash.
+
+### `datasize`
+
+Returns the contract hash size (constant value of `32`).
+
+### `prevrandao`, `difficulty`
+
+Translates to a constant value of `2500000000000000`.
+
+### `pc`, `extcodecopy`
+
+Only valid to use in EVM (they also have no use case in PVM) and produce a compile time error.
+
+### `blobhash`, `blobbasefee`
+
+Related to the Ethereum rollup model and produce a compile time error. Polkadot offers a superior rollup model, removing the use case for blob data related opcodes.
+
+## Difference regarding the `solc` `via-ir` mode
+
+There are two different compilation pipelines available in `solc` and [there are small differences between them](https://docs.soliditylang.org/en/latest/ir-breaking-changes.html).
+
+Since `resolc` processes the YUL IR, always assume the `solc` IR based codegen behavior for contracts compiled with the `revive` compiler.
+
@@ -0,0 +1,27 @@
+# Installation
+
+Building Solidity contracts for PolkaVM requires installing the following two compilers:
+- `solc`: The [Ethereum Solidity reference compiler](https://github.com/argotorg/solidity) implementation. 
+- `resolc`: The revive Solidity compiler YUL frontend and PolkaVM code generator.
+
+## `resolc` binary releases
+
+`resolc` is supported an all major operating systems and installation is straightforward.
+Please find our [binary releases](https://github.com/paritytech/revive/releases) for the following platforms:
+- Linux (MUSL)
+- MacOS (universal)
+- Windows
+- Wasm via emscripten
+
+## Installing the `solc` dependency
+
+`resolc` uses `solc` during the compilation process, please refer to the [Ethereum Solidity documentation](https://docs.soliditylang.org/en/latest/installing-solidity.html) for installation instructions.
+
+## `revive` NPM package
+
+We distribute the revive compiler as [node.js module](https://github.com/paritytech/revive/tree/main/js/resolc).
+
+## Buidling `resolc` from source
+
+Please follow the build [instructions in the revive `README.md`](https://github.com/paritytech/revive?tab=readme-ov-file#building-from-source).
+
@@ -0,0 +1,13 @@
+# JS NPM package
+
+The `resolc` compiler driver is published as an NPM package under [@parity/resolc](https://www.npmjs.com/package/@parity/resolc). 
+
+It's usable from `Node.js` code or directly from the command line:
+
+```shell
+npx @parity/resolc@latest --bin crates/integration/contracts/flipper.sol -o /tmp/out
+```
+
+> [!NOTE]
+>
+> While the npm package makes a nice portable option, it doesn't expose all options.
@@ -0,0 +1,15 @@
+# Rust contract libraries
+
+> [!NOTE]
+>
+> This is not yet implemented but something for consideration on the roadmap.
+
+Solidity - tightly coupled to the EVM - introduces some inherent inefficiencies that are by design and either needs to be followed or can't be easily worked around, even with efforts like better optimized compiler and VM implementations. This represents a technical dead end. So far the EVM sees no adoption beyond the blockchain industry. Chances are that [the EVM end up deprecated](https://ethereum-magicians.org/t/long-term-l1-execution-layer-proposal-replace-the-evm-with-risc-v) for technical reasons (or maybe not and the RISC-V idea gets abandoned, who knows).
+
+PVM, however, is a general purpose VM. It supports LLVM based mainstream programming languages like Rust. It's a common software engineering practice to compose applications from pieces written in multiple languages, using each to their own strength. For example, AI solutions traditionally use the python scripting language for convenient developer experience, while the underlying AI models get implemented in a lower level language such as C++.
+
+The same pattern can of course be applied to dApps, where we'd expect application specific languages like Solidity mixed with libraries implementing computationally complex algorithms in a lower level language. Business logic and user interfaces are naturally implemented as regular Solidity dApps which can include (link against) Rust libraries. Rust is a fast, safe low level language and the Polkadot SDK is written in Rust itself, making it an excellent choice.
+
+For example, [ZK proof verifiers](https://en.wikipedia.org/wiki/Zero-knowledge_proof) or expensive [DeFi](https://en.wikipedia.org/wiki/Decentralized_finance) primitives would benefit greatly from Rust implementations. 
+
+`revive` provides tooling support and a small Rust contracts SDK for seamless integration with Rust libraries.
@@ -0,0 +1,36 @@
+# Standard JSON interface
+
+The `revive` compiler is mostly compatible with the `solc` standard JSON interface. There are a few additional (PVM related) __input__ configurations:
+
+## The `settings.polkavm` object
+
+Used to configure PVM specific compiler settings.
+
+### `settings.polkavm.debugInformation`
+
+A boolean value allowing to enable debug information. Corresponds to `resolc -g`.
+
+### The `settings.polkavm.memoryConfig` object
+
+Used to apply PVM specific memory configuration settings.
+
+#### `settings.polkavm.heapSize`
+
+A numerical value allowing to configure the contract heap size. Corresponds to `resolc --heap-size`.
+
+#### `settings.polkavm.stackSize`
+
+A numerical value allowing to configure the contract stack size. Corresponds to `resolc --stack-size`.
+
+## The `settings.optimizer` object
+
+The `settings.optimizer` object is augmented with support for PVM specific optimization settings.
+
+### `settings.optimizer.mode`
+
+A single char value to configure the LLVM optimizer settings. Corresponds to `resolc -O`.
+
+## `settings.llvmArguments`
+
+Allows to specify arbitrary command line arguments to LLVM initialization. Used mainly for development and debugging purposes.
+
@@ -0,0 +1,19 @@
+# Tooling integration
+
+`resolc` achieved successful integration with a variety of third party developer tools.
+
+## Solidity toolkits
+
+Support for `resolc` is available in forks of the [hardhat](https://hardhat.org) and [foundry](https://getfoundry.sh) Solidity toolkits:
+
+- [The Parity Hardhat fork](https://github.com/paritytech/hardhat-polkadot)
+- [The Parity Foundry fork](https://github.com/paritytech/foundry-polkadot?tab=readme-ov-file#2-resolc-compiler-integration)
+
+## Compiler explorer
+
+`resolc` is available on [godbolt.org](https://godbolt.org/z/6GM6n4Ka3) for the Solidity and Yul input languages. See also the announcement post on the [forum](https://forum.polkadot.network/t/resolc-is-live-on-compiler-explorer).
+
+## Remix IDE
+
+There is remix IDE fork with `resolc` support at [remix.polkadot.io](https://remix.polkadot.io). Unfortunately this is no longer actively maintained (there might be bugs and outdated `resolc` versions).
+
@@ -0,0 +1,16 @@
+# Welcome
+
+Hello and a warm welcome to the `revive` Solidity compiler book!
+
+## Target audience
+
+- **Solidity dApp developers** should read the [user guide](./user_guide.md). Solidity on PolkaVM introduces important differences to EVM which should be well understood.
+- **Contributors** will find the [developer guide](./developer_guide.md) helpful for getting up to speed.
+
+## Other Polkadot contracts resources
+
+Head to [contracts.polkadot.io](https://docs.polkadot.com/develop/smart-contracts/) for more general information about contracts on Polkadot.
+
+## About
+
+This [mdBook](https://github.com/rust-lang/mdBook) documents the revive Solidity compiler project. The content is found under `book/`. Run `make book` to observe changes.
@@ -4,7 +4,7 @@

 - [Benchmark Results](#benchmark-results)
    - [Baseline](#baseline)
-    - [OddPorduct](#oddporduct)
+    - [OddProduct](#oddproduct)
    - [TriangleNumber](#trianglenumber)
    - [FibonacciRecursive](#fibonaccirecursive)
    - [FibonacciIterative](#fibonacciiterative)
@@ -19,7 +19,7 @@
 |:--------|:-------------------------|:-------------------------------- |
 | **`0`** | `10.08 us` (✅ **1.00x**) | `10.32 us` (✅ **1.02x slower**)  |

-### OddPorduct
+### OddProduct

 |              | `EVM`                     | `PVMInterpreter`                 |
 |:-------------|:--------------------------|:-------------------------------- |
@@ -70,4 +70,3 @@

 ---
 Made with [criterion-table](https://github.com/nu11ptr/criterion-table)
-
@@ -57,7 +57,7 @@ fn bench_baseline(c: &mut Criterion) {
 }

 fn bench_odd_product(c: &mut Criterion) {
-    let group = group(c, "OddPorduct");
+    let group = group(c, "OddProduct");
    let parameters = &[10_000, 100_000, 300000];

    bench(group, parameters, parameters, Contract::odd_product);
@@ -1,10 +1,10 @@
 {
-  "Baseline": 914,
-  "Computation": 2295,
-  "DivisionArithmetics": 14496,
-  "ERC20": 17482,
-  "Events": 1674,
-  "FibonacciIterative": 1490,
-  "Flipper": 2086,
-  "SHA1": 8158
+  "Baseline": 905,
+  "Computation": 2286,
+  "DivisionArithmetics": 14347,
+  "ERC20": 16929,
+  "Events": 1665,
+  "FibonacciIterative": 1447,
+  "Flipper": 2077,
+  "SHA1": 7721
 }
@@ -10,6 +10,7 @@ pub struct Contract {
    pub evm_runtime: Vec<u8>,
    pub pvm_runtime: Vec<u8>,
    pub calldata: Vec<u8>,
+    pub yul: String,
 }

 impl Contract {
@@ -19,6 +20,7 @@ impl Contract {
            evm_runtime: compile_evm_bin_runtime(name, code),
            pvm_runtime: compile_blob(name, code),
            calldata,
+            yul: compile_to_yul(name, code, true),
        }
    }

@@ -28,6 +30,7 @@ impl Contract {
            evm_runtime: compile_evm_bin_runtime(name, code),
            pvm_runtime: compile_blob_with_options(name, code, true, OptimizerSettings::size()),
            calldata,
+            yul: compile_to_yul(name, code, true),
        }
    }
 }
@@ -1,6 +1,7 @@
 use std::str::FromStr;

 use alloy_primitives::*;
+use resolc::test_utils::build_yul;
 use revive_runner::*;
 use SpecsAction::*;

@@ -520,3 +521,101 @@ fn create2_salt() {
    }
    .run();
 }
+
+#[test]
+fn code_block_stops() {
+    let code = &build_yul(&[(
+        "poc.yul",
+        r#"object "Test"{
+  code {
+    tstore(0x7fd9d641,0x7b1e022)
+    returndatacopy(0x0,0x0,returndatasize())
+  }
+  object "Test_deployed" { code{} }
+}"#,
+    )])
+    .unwrap()["poc.yul:Test"];
+
+    Specs {
+        actions: vec![
+            Instantiate {
+                origin: TestAddress::Alice,
+                value: 0,
+                gas_limit: Some(GAS_LIMIT),
+                storage_deposit_limit: None,
+                code: Code::Bytes(code.to_vec()),
+                data: Default::default(),
+                salt: OptionalHex::default(),
+            },
+            Call {
+                origin: TestAddress::Alice,
+                dest: TestAddress::Instantiated(0),
+                value: Default::default(),
+                gas_limit: None,
+                storage_deposit_limit: None,
+                data: Default::default(),
+            },
+            VerifyCall(Default::default()),
+        ],
+        differential: false,
+        ..Default::default()
+    }
+    .run();
+}
+
+#[test]
+fn code_block_with_nested_object_stops() {
+    let code = &build_yul(&[(
+        "poc.yul",
+        r#"object "Test" {
+    code {
+        function allocate(size) -> ptr {
+            ptr := mload(0x40)
+            if iszero(ptr) { ptr := 0x60 }
+            mstore(0x40, add(ptr, size))
+        }
+        let size := datasize("Test_deployed")
+        let offset := allocate(size)
+        datacopy(offset, dataoffset("Test_deployed"), size)
+        return(offset, size)
+    }
+    object "Test_deployed" {
+        code {
+            sstore(0, 100)
+	 }
+        object "Test" {
+            code {
+	    revert(0,0)
+            }
+        }
+    }
+}"#,
+    )])
+    .unwrap()["poc.yul:Test"];
+
+    Specs {
+        actions: vec![
+            Instantiate {
+                origin: TestAddress::Alice,
+                value: 0,
+                gas_limit: Some(GAS_LIMIT),
+                storage_deposit_limit: None,
+                code: Code::Bytes(code.to_vec()),
+                data: Default::default(),
+                salt: OptionalHex::default(),
+            },
+            Call {
+                origin: TestAddress::Alice,
+                dest: TestAddress::Instantiated(0),
+                value: Default::default(),
+                gas_limit: None,
+                storage_deposit_limit: None,
+                data: Default::default(),
+            },
+            VerifyCall(Default::default()),
+        ],
+        differential: false,
+        ..Default::default()
+    }
+    .run();
+}
@@ -78,7 +78,7 @@ SECTIONS {
            "--error-limit=0",
            "--relocatable",
            "--emit-relocs",
-            "--no-relax",
+            "--relax",
            "--unique",
            "--gc-sections",
            self.linker_script_path.to_str().expect("should be utf8"),
@@ -5,6 +5,10 @@ pub fn polkavm_linker<T: AsRef<[u8]>>(code: T, strip_binary: bool) -> anyhow::Re
    config.set_strip(strip_binary);
    config.set_optimize(true);

-    polkavm_linker::program_from_elf(config, code.as_ref())
-        .map_err(|reason| anyhow::anyhow!("polkavm linker failed: {}", reason))
+    polkavm_linker::program_from_elf(
+        config,
+        polkavm_linker::TargetInstructionSet::ReviveV1,
+        code.as_ref(),
+    )
+    .map_err(|reason| anyhow::anyhow!("polkavm linker failed: {}", reason))
 }
@@ -21,8 +21,6 @@ doctest = false
 [dependencies]
 clap = { workspace = true, features = ["help", "std", "derive"] }
 anyhow = { workspace = true }
-serde = { workspace = true, features = [ "derive" ] }
-toml = { workspace = true }
 num_cpus = { workspace = true }
 fs_extra = { workspace = true }
 path-slash = { workspace = true }
@@ -67,12 +67,6 @@ Obtain a compatible build for your host platform from the release section of thi
 </details>

 <details>
-<summary>4. (Optional) Create the `LLVM.lock` file.</summary>
-
-   * The `LLVM.lock` dictates the LLVM source tree being used.
-     A default `./LLVM.lock` pointing to the release used for development is already provided.
-
-</details>

 <details>
 <summary>5. Build LLVM.</summary>
@@ -4,13 +4,14 @@ use crate::utils::path_windows_to_unix as to_unix;
 use std::{env::consts::EXE_EXTENSION, process::Command};

 /// Static CFLAGS variable passed to the compiler building the compiler-rt builtins.
-const C_FLAGS: [&str; 6] = [
+const C_FLAGS: [&str; 7] = [
    "--target=riscv64",
    "-march=rv64emac",
    "-mabi=lp64e",
    "-mcpu=generic-rv64",
    "-nostdlib",
    "-nodefaultlibs",
+    "-fuse-ld=lld",
 ];

 /// Static CMAKE arguments for building the compiler-rt builtins.
@@ -5,7 +5,6 @@ pub mod builtins;
 pub mod ccache_variant;
 pub mod llvm_path;
 pub mod llvm_project;
-pub mod lock;
 pub mod platforms;
 pub mod sanitizer;
 pub mod target_env;
@@ -14,7 +13,6 @@ pub mod utils;

 pub use self::build_type::BuildType;
 pub use self::llvm_path::LLVMPath;
-pub use self::lock::Lock;
 pub use self::platforms::Platform;

 use std::collections::HashSet;
@@ -23,87 +21,25 @@ use std::process::Command;
 pub use target_env::TargetEnv;
 pub use target_triple::TargetTriple;

-/// Executes the LLVM repository cloning.
-pub fn clone(lock: Lock, deep: bool, target_env: TargetEnv) -> anyhow::Result<()> {
+/// Initializes the LLVM submodule if not already done.
+pub fn init(init_emscripten: bool) -> anyhow::Result<()> {
    utils::check_presence("git")?;

-    if target_env == TargetEnv::Emscripten {
+    if init_emscripten {
        utils::install_emsdk()?;
    }

    let destination_path = PathBuf::from(LLVMPath::DIRECTORY_LLVM_SOURCE);
-    if destination_path.exists() {
-        log::warn!(
-            "LLVM repository directory {} already exists, falling back to checkout",
-            destination_path.display()
-        );
-        return checkout(lock, false);
-    }
-
-    let mut clone_args = vec!["clone", "--branch", lock.branch.as_str()];
-    if !deep {
-        clone_args.push("--depth");
-        clone_args.push("1");
+    if destination_path.join(".git").exists() {
+        log::info!("LLVM submodule already initialized");
+        return Ok(());
    }

    utils::command(
-        Command::new("git")
-            .args(clone_args)
-            .arg(lock.url.as_str())
-            .arg(destination_path.to_string_lossy().as_ref()),
-        "LLVM repository cloning",
+        Command::new("git").args(["submodule", "update", "--init", "--recursive"]),
+        "LLVM submodule initialization",
    )?;

-    if let Some(r#ref) = lock.r#ref {
-        utils::command(
-            Command::new("git")
-                .args(["checkout", r#ref.as_str()])
-                .current_dir(destination_path.to_string_lossy().as_ref()),
-            "LLVM repository commit checking out",
-        )?;
-    }
-
-    Ok(())
-}
-
-/// Executes the checkout of the specified branch.
-pub fn checkout(lock: Lock, force: bool) -> anyhow::Result<()> {
-    let destination_path = PathBuf::from(LLVMPath::DIRECTORY_LLVM_SOURCE);
-
-    utils::command(
-        Command::new("git")
-            .current_dir(destination_path.as_path())
-            .args(["fetch", "--all", "--tags"]),
-        "LLVM repository data fetching",
-    )?;
-
-    if force {
-        utils::command(
-            Command::new("git")
-                .current_dir(destination_path.as_path())
-                .args(["clean", "-d", "-x", "--force"]),
-            "LLVM repository cleaning",
-        )?;
-    }
-
-    utils::command(
-        Command::new("git")
-            .current_dir(destination_path.as_path())
-            .args(["checkout", "--force", lock.branch.as_str()]),
-        "LLVM repository data pulling",
-    )?;
-
-    if let Some(r#ref) = lock.r#ref {
-        let mut checkout_command = Command::new("git");
-        checkout_command.current_dir(destination_path.as_path());
-        checkout_command.arg("checkout");
-        if force {
-            checkout_command.arg("--force");
-        }
-        checkout_command.arg(r#ref);
-        utils::command(&mut checkout_command, "LLVM repository checking out")?;
-    }
-
    Ok(())
 }

@@ -332,8 +268,6 @@ pub fn clean() -> anyhow::Result<()> {
            .expect("target_env parent directory is target-llvm"),
    )?;
    remove_if_exists(&PathBuf::from(LLVMPath::DIRECTORY_EMSDK_SOURCE))?;
-    remove_if_exists(&PathBuf::from(LLVMPath::DIRECTORY_LLVM_SOURCE))?;
-    remove_if_exists(&PathBuf::from(LLVMPath::DIRECTORY_LLVM_HOST_SOURCE))?;

    Ok(())
 }
@@ -1,37 +0,0 @@
-//! The revive LLVM builder lock file.
-
-use anyhow::Context;
-use std::fs::File;
-use std::io::Read;
-use std::path::PathBuf;
-
-use serde::Deserialize;
-use serde::Serialize;
-
-/// The default lock file location.
-pub const LLVM_LOCK_DEFAULT_PATH: &str = "LLVM.lock";
-
-/// The lock file data.
-///
-/// This file describes the exact reference of the LLVM framework.
-#[derive(Debug, Deserialize, Serialize)]
-pub struct Lock {
-    /// The LLVM repository URL.
-    pub url: String,
-    /// The LLVM repository branch.
-    pub branch: String,
-    /// The LLVM repository commit reference.
-    pub r#ref: Option<String>,
-}
-
-impl TryFrom<&PathBuf> for Lock {
-    type Error = anyhow::Error;
-
-    fn try_from(path: &PathBuf) -> Result<Self, Self::Error> {
-        let mut config_str = String::new();
-        let mut config_file =
-            File::open(path).with_context(|| format!("Error opening {path:?} file"))?;
-        config_file.read_to_string(&mut config_str)?;
-        Ok(toml::from_str(&config_str)?)
-    }
-}
@@ -18,13 +18,6 @@ pub struct Arguments {
 /// The revive LLVM builder arguments.
 #[derive(Debug, clap::Subcommand)]
 pub enum Subcommand {
-    /// Clone the branch specified in `LLVM.lock`.
-    Clone {
-        /// Clone with full commits history.
-        #[arg(long)]
-        deep: bool,
-    },
-
    /// Build the LLVM framework.
    Build {
        /// LLVM build type (`Debug`, `Release`, `RelWithDebInfo`, or `MinSizeRel`).
@@ -77,12 +70,8 @@ pub enum Subcommand {
        enable_valgrind: bool,
    },

-    /// Checkout the branch specified in `LLVM.lock`.
-    Checkout {
-        /// Remove all artifacts preventing the checkout (removes all local changes!).
-        #[arg(long)]
-        force: bool,
-    },
+    /// Install emsdk
+    Emsdk,

    /// Clean the build artifacts.
    Clean,
@@ -3,7 +3,6 @@
 pub(crate) mod arguments;

 use std::collections::HashSet;
-use std::path::PathBuf;
 use std::str::FromStr;

 use anyhow::Context;
@@ -29,13 +28,6 @@ fn main_inner() -> anyhow::Result<()> {
    revive_llvm_builder::utils::directory_target_llvm(arguments.target_env);

    match arguments.subcommand {
-        Subcommand::Clone { deep } => {
-            let lock = revive_llvm_builder::Lock::try_from(&PathBuf::from(
-                revive_llvm_builder::lock::LLVM_LOCK_DEFAULT_PATH,
-            ))?;
-            revive_llvm_builder::clone(lock, deep, arguments.target_env)?;
-        }
-
        Subcommand::Build {
            build_type,
            targets,
@@ -50,6 +42,8 @@ fn main_inner() -> anyhow::Result<()> {
            sanitizer,
            enable_valgrind,
        } => {
+            revive_llvm_builder::init(false)?;
+
            let mut targets = targets
                .into_iter()
                .map(|target| revive_llvm_builder::Platform::from_str(target.as_str()))
@@ -107,11 +101,8 @@ fn main_inner() -> anyhow::Result<()> {
            )?;
        }

-        Subcommand::Checkout { force } => {
-            let lock = revive_llvm_builder::Lock::try_from(&PathBuf::from(
-                revive_llvm_builder::lock::LLVM_LOCK_DEFAULT_PATH,
-            ))?;
-            revive_llvm_builder::checkout(lock, force)?;
+        Subcommand::Emsdk => {
+            revive_llvm_builder::init(true)?;
        }

        Subcommand::Clean => {
@@ -4,16 +4,10 @@ use std::process::Command;

 use assert_cmd::{cargo, prelude::*};

-/// This test verifies that the LLVM repository can be successfully cloned, built, and cleaned.
+/// This test verifies that the LLVM repository can be successfully built and cleaned.
 #[test]
-fn clone_build_and_clean() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
-        .assert()
-        .success();
+fn build_and_clean() -> anyhow::Result<()> {
+    let test_dir = common::TestDir::new()?;

    Command::new(cargo::cargo_bin!("revive-llvm"))
        .current_dir(test_dir.path())
@@ -40,18 +34,12 @@ fn clone_build_and_clean() -> anyhow::Result<()> {
    Ok(())
 }

-/// This test verifies that the LLVM repository can be successfully cloned, built, and cleaned
+/// This test verifies that the LLVM repository can be successfully built and cleaned
 /// with 2-staged build using MUSL as sysroot.
 #[test]
 #[cfg(target_os = "linux")]
-fn clone_build_and_clean_musl() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .arg("clone")
-        .current_dir(test_dir.path())
-        .assert()
-        .success();
+fn build_and_clean_musl() -> anyhow::Result<()> {
+    let test_dir = common::TestDir::new()?;

    Command::new(cargo::cargo_bin!("revive-llvm"))
        .current_dir(test_dir.path())
@@ -84,18 +72,12 @@ fn clone_build_and_clean_musl() -> anyhow::Result<()> {
    Ok(())
 }

-/// This test verifies that the LLVM repository can be successfully cloned and built in debug mode
+/// This test verifies that the LLVM repository can be successfully built in debug mode
 /// with tests and coverage enabled.
 #[test]
 #[cfg(target_os = "linux")]
 fn debug_build_with_tests_coverage() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
-        .assert()
-        .success();
+    let test_dir = common::TestDir::new()?;

    Command::new(cargo::cargo_bin!("revive-llvm"))
        .current_dir(test_dir.path())
@@ -118,13 +100,7 @@ fn debug_build_with_tests_coverage() -> anyhow::Result<()> {
 #[test]
 #[cfg(target_os = "linux")]
 fn build_with_sanitizers() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
-        .assert()
-        .success();
+    let test_dir = common::TestDir::new()?;

    Command::new(cargo::cargo_bin!("revive-llvm"))
        .current_dir(test_dir.path())
@@ -141,27 +117,28 @@ fn build_with_sanitizers() -> anyhow::Result<()> {
    Ok(())
 }

-/// Tests the clone, build, and clean process of the LLVM repository for the emscripten target.
+/// Tests the build and clean process of the LLVM repository for the emscripten target.
 #[test]
 #[cfg(target_os = "linux")]
-fn clone_build_and_clean_emscripten() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
+fn build_and_clean_emscripten() -> anyhow::Result<()> {
+    let test_dir = common::TestDir::new()?;
    let command = Command::new(cargo::cargo_bin!("revive-llvm"));
    let program = command.get_program().to_string_lossy();
+    let path = test_dir.path();

    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
+        .current_dir(path)
+        .arg("build")
+        .arg("--llvm-projects")
+        .arg("clang")
+        .arg("--llvm-projects")
+        .arg("lld")
        .assert()
        .success();

    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("build")
-        .arg("--llvm-projects")
-        .arg("lld")
-        .arg("--llvm-projects")
-        .arg("clang")
+        .current_dir(path)
+        .arg("emsdk")
        .assert()
        .success();

@@ -170,22 +147,20 @@ fn clone_build_and_clean_emscripten() -> anyhow::Result<()> {
    // `cd {} && . ./emsdk_env.sh && cd ..` helps the script to locate `emsdk.py`
    // @see https://github.com/emscripten-core/emsdk/blob/9dbdc4b3437750b85d16931c7c801bb71a782122/emsdk_env.sh#L61-L69
    let emsdk_wrapped_build_command = format!(
-        "{program} --target-env emscripten clone && \
-        cd {} && . ./emsdk_env.sh && cd .. && \
+        "cd {} && . ./emsdk_env.sh && cd .. && \
        {program} --target-env emscripten build --llvm-projects lld",
        revive_llvm_builder::LLVMPath::DIRECTORY_EMSDK_SOURCE,
    );
-
    Command::new("sh")
        .arg("-c")
        .arg(emsdk_wrapped_build_command)
-        .current_dir(test_dir.path())
+        .current_dir(path)
        .assert()
        .success();

    Command::new(cargo::cargo_bin!("revive-llvm"))
        .arg("clean")
-        .current_dir(test_dir.path())
+        .current_dir(path)
        .assert()
        .success();

@@ -1,48 +0,0 @@
-pub mod common;
-
-use std::process::Command;
-
-use assert_cmd::{cargo, prelude::*};
-
-/// This test verifies that after cloning the LLVM repository, checking out a specific branch
-/// or reference works as expected.
-#[test]
-fn checkout_after_clone() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
-        .assert()
-        .success();
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("checkout")
-        .assert()
-        .success();
-
-    Ok(())
-}
-
-/// This test verifies that after cloning the LLVM repository, checking out a specific branch
-/// or reference with the `--force` option works as expected.
-#[test]
-fn force_checkout() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
-        .assert()
-        .success();
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("checkout")
-        .arg("--force")
-        .assert()
-        .success();
-
-    Ok(())
-}
@@ -1,36 +0,0 @@
-pub mod common;
-
-use std::process::Command;
-
-use assert_cmd::{cargo, prelude::*};
-
-/// This test verifies that the LLVM repository can be successfully cloned using a specific branch
-/// and reference.
-#[test]
-fn clone() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
-        .assert()
-        .success();
-
-    Ok(())
-}
-
-/// This test verifies that the LLVM repository can be successfully cloned using a specific branch
-/// and reference with --deep option.
-#[test]
-fn clone_deep() -> anyhow::Result<()> {
-    let test_dir = common::TestDir::with_lockfile(None)?;
-
-    Command::new(cargo::cargo_bin!("revive-llvm"))
-        .current_dir(test_dir.path())
-        .arg("clone")
-        .arg("--deep")
-        .assert()
-        .success();
-
-    Ok(())
-}
@@ -1,32 +1,51 @@
-use assert_fs::fixture::FileWriteStr;
+use assert_fs::TempDir;

 pub const REVIVE_LLVM: &str = "revive-llvm";
-pub const REVIVE_LLVM_REPO_URL: &str = "https://github.com/llvm/llvm-project";
-pub const REVIVE_LLVM_REPO_TEST_BRANCH: &str = "release/18.x";

 pub struct TestDir {
-    _lockfile: assert_fs::NamedTempFile,
+    _tempdir: TempDir,
    path: std::path::PathBuf,
 }

-/// Creates a temporary lock file for testing.
+/// Creates a temporary directory for testing with submodule setup.
 impl TestDir {
-    pub fn with_lockfile(reference: Option<String>) -> anyhow::Result<Self> {
-        let file =
-            assert_fs::NamedTempFile::new(revive_llvm_builder::lock::LLVM_LOCK_DEFAULT_PATH)?;
-        let lock = revive_llvm_builder::Lock {
-            url: REVIVE_LLVM_REPO_URL.to_string(),
-            branch: REVIVE_LLVM_REPO_TEST_BRANCH.to_string(),
-            r#ref: reference,
-        };
-        file.write_str(toml::to_string(&lock)?.as_str())?;
+    pub fn new() -> anyhow::Result<Self> {
+        let tempdir = TempDir::new()?;
+        let tmppath = tempdir.path();
+
+        // Initialize a git repo and add the LLVM submodule
+        std::process::Command::new("git")
+            .args(["init"])
+            .current_dir(tmppath)
+            .output()?;
+
+        std::process::Command::new("git")
+            .args([
+                "submodule",
+                "add",
+                "-b",
+                "release/18.x",
+                "https://github.com/llvm/llvm-project.git",
+                "llvm",
+            ])
+            .current_dir(tmppath)
+            .output()?;
+
+        std::process::Command::new("git")
+            .args([
+                "submodule",
+                "update",
+                "--init",
+                "--recursive",
+                "--force",
+                "--depth 1",
+            ])
+            .current_dir(tmppath)
+            .output()?;

        Ok(Self {
-            path: file
-                .parent()
-                .expect("lockfile parent dir always exists")
-                .into(),
-            _lockfile: file,
+            path: tmppath.to_path_buf(),
+            _tempdir: tempdir,
        })
    }

@@ -35,7 +35,7 @@ impl<'ctx> Global<'ctx> {
            .add_global(r#type, Some(address_space.into()), name);
        let global = Self { r#type, value };

-        global.value.set_linkage(inkwell::module::Linkage::External);
+        global.value.set_linkage(inkwell::module::Linkage::Internal);
        global
            .value
            .set_visibility(inkwell::GlobalVisibility::Default);
@@ -134,7 +134,7 @@ impl<'ctx> Context<'ctx> {
            module
                .get_function(import)
                .unwrap_or_else(|| panic!("{import} import should be declared"))
-                .set_linkage(inkwell::module::Linkage::External);
+                .set_linkage(inkwell::module::Linkage::Internal);
        }
    }

@@ -256,6 +256,22 @@ impl<'ctx> Context<'ctx> {
        }
    }

+    /// Initializes a new dummy LLVM context.
+    ///
+    /// Omits the LLVM module initialization; use this only in tests and benchmarks.
+    pub fn new_dummy(
+        llvm: &'ctx inkwell::context::Context,
+        optimizer_settings: OptimizerSettings,
+    ) -> Self {
+        Self::new(
+            llvm,
+            llvm.create_module("dummy"),
+            Optimizer::new(optimizer_settings),
+            Default::default(),
+            Default::default(),
+        )
+    }
+
    /// Builds the LLVM IR module, returning the build artifacts.
    pub fn build(
        self,
@@ -1,33 +1,21 @@
 //! The LLVM IR generator context tests.

 use crate::optimizer::settings::Settings as OptimizerSettings;
-use crate::optimizer::Optimizer;
 use crate::polkavm::context::attribute::Attribute;
 use crate::polkavm::context::Context;
 use crate::PolkaVMTarget;

-pub fn create_context(
-    llvm: &inkwell::context::Context,
-    optimizer_settings: OptimizerSettings,
-) -> Context<'_> {
+/// Initializes the LLVM compiler backend.
+fn initialize_llvm() {
    crate::initialize_llvm(PolkaVMTarget::PVM, "resolc", Default::default());
-
-    let module = llvm.create_module("test");
-    let optimizer = Optimizer::new(optimizer_settings);
-
-    Context::new(
-        llvm,
-        module,
-        optimizer,
-        Default::default(),
-        Default::default(),
-    )
 }

 #[test]
 pub fn check_attribute_null_pointer_is_invalid() {
+    initialize_llvm();
+
    let llvm = inkwell::context::Context::create();
-    let mut context = create_context(&llvm, OptimizerSettings::cycles());
+    let mut context = Context::new_dummy(&llvm, OptimizerSettings::cycles());

    let function = context
        .add_function(
@@ -51,8 +39,10 @@ pub fn check_attribute_null_pointer_is_invalid() {

 #[test]
 pub fn check_attribute_optimize_for_size_mode_3() {
+    initialize_llvm();
+
    let llvm = inkwell::context::Context::create();
-    let mut context = create_context(&llvm, OptimizerSettings::cycles());
+    let mut context = Context::new_dummy(&llvm, OptimizerSettings::cycles());

    let function = context
        .add_function(
@@ -76,8 +66,10 @@ pub fn check_attribute_optimize_for_size_mode_3() {

 #[test]
 pub fn check_attribute_optimize_for_size_mode_z() {
+    initialize_llvm();
+
    let llvm = inkwell::context::Context::create();
-    let mut context = create_context(&llvm, OptimizerSettings::size());
+    let mut context = Context::new_dummy(&llvm, OptimizerSettings::size());

    let function = context
        .add_function(
@@ -101,8 +93,10 @@ pub fn check_attribute_optimize_for_size_mode_z() {

 #[test]
 pub fn check_attribute_min_size_mode_3() {
+    initialize_llvm();
+
    let llvm = inkwell::context::Context::create();
-    let mut context = create_context(&llvm, OptimizerSettings::cycles());
+    let mut context = Context::new_dummy(&llvm, OptimizerSettings::cycles());

    let function = context
        .add_function(
@@ -126,8 +120,10 @@ pub fn check_attribute_min_size_mode_3() {

 #[test]
 pub fn check_attribute_min_size_mode_z() {
+    initialize_llvm();
+
    let llvm = inkwell::context::Context::create();
-    let mut context = create_context(&llvm, OptimizerSettings::size());
+    let mut context = Context::new_dummy(&llvm, OptimizerSettings::size());

    let function = context
        .add_function(
@@ -29,7 +29,7 @@ impl TargetMachine {

    /// LLVM target features.
    pub const VM_FEATURES: &'static str =
-        "+e,+m,+a,+c,+zbb,+auipc-addi-fusion,+ld-add-fusion,+lui-addi-fusion,+xtheadcondmov";
+        "+e,+m,+a,+c,+zbb,+auipc-addi-fusion,+ld-add-fusion,+lui-addi-fusion,+xtheadcondmov,+relax";

    /// A shortcut constructor.
    /// A separate instance for every optimization level is created.
@@ -0,0 +1,53 @@
+# Benchmarks
+
+## Table of Contents
+
+- [Benchmark Results](#benchmark-results)
+    - [Empty](#empty)
+    - [Dependency](#dependency)
+    - [LargeDivRem](#largedivrem)
+    - [Memset (`--yul`)](#memset-(`--yul`))
+    - [Return (`--yul`)](#return-(`--yul`))
+    - [Multiple Contracts (`--standard-json`)](#multiple-contracts-(`--standard-json`))
+
+## Benchmark Results
+
+### Empty
+
+|        | `resolc`                 | `solc`                          |
+|:-------|:-------------------------|:------------------------------- |
+|        | `62.77 ms` (✅ **1.00x**) | `9.63 ms` (🚀 **6.52x faster**)  |
+
+### Dependency
+
+|        | `resolc`                  | `solc`                           |
+|:-------|:--------------------------|:-------------------------------- |
+|        | `142.28 ms` (✅ **1.00x**) | `57.57 ms` (🚀 **2.47x faster**)  |
+
+### LargeDivRem
+
+|        | `resolc`                  | `solc`                           |
+|:-------|:--------------------------|:-------------------------------- |
+|        | `110.80 ms` (✅ **1.00x**) | `20.96 ms` (🚀 **5.29x faster**)  |
+
+### Memset (`--yul`)
+
+|        | `resolc`                 | `solc`                          |
+|:-------|:-------------------------|:------------------------------- |
+|        | `58.39 ms` (✅ **1.00x**) | `8.84 ms` (🚀 **6.61x faster**)  |
+
+### Return (`--yul`)
+
+|        | `resolc`                 | `solc`                          |
+|:-------|:-------------------------|:------------------------------- |
+|        | `52.83 ms` (✅ **1.00x**) | `8.04 ms` (🚀 **6.57x faster**)  |
+
+### Multiple Contracts (`--standard-json`)
+
+|        | `resolc`               | `solc`                            |
+|:-------|:-----------------------|:--------------------------------- |
+|        | `1.52 s` (✅ **1.00x**) | `623.91 ms` (🚀 **2.44x faster**)  |
+
+---
+Made with [criterion-table](https://github.com/nu11ptr/criterion-table)
+
@@ -22,6 +22,7 @@ anyhow = { workspace = true }
 clap = { workspace = true }
 hex = { workspace = true }
 inkwell = { workspace = true }
+log = { workspace = true }
 once_cell = { workspace = true }
 path-slash = { workspace = true }
 rayon = { workspace = true, optional = true }
@@ -47,9 +48,13 @@ inkwell = { workspace = true, features = ["target-riscv", "llvm18-1-no-llvm-link
 git2 = { workspace = true, default-features = false }

 [dev-dependencies]
+criterion = { workspace = true }
 tempfile = { workspace = true }

 [features]
 parallel = ["rayon", "revive-solc-json-interface/parallel"]
 default = ["parallel"]

+[[bench]]
+name = "compile"
+harness = false
@@ -0,0 +1,177 @@
+//! The `resolc` compilation benchmarks.
+//! The tests mimicking the commands run by these benchmarks exist in `src/tests/cli/bin.rs`.
+
+use std::time::Duration;
+
+use criterion::{
+    criterion_group, criterion_main,
+    measurement::{Measurement, WallTime},
+    BenchmarkGroup, Criterion,
+};
+use resolc::{
+    self,
+    cli_utils::{
+        absolute_path, execute_command, ResolcOptSettings, SolcOptSettings, SOLIDITY_CONTRACT_PATH,
+        SOLIDITY_DEPENDENCY_CONTRACT_PATH, SOLIDITY_LARGE_DIV_REM_CONTRACT_PATH,
+        STANDARD_JSON_CONTRACTS_PATH, YUL_MEMSET_CONTRACT_PATH, YUL_RETURN_CONTRACT_PATH,
+    },
+    SolcCompiler,
+};
+
+/// The function under test executes the `resolc` executable.
+fn execute_resolc(arguments: &[&str], stdin_file_path: Option<&str>) {
+    execute_command(resolc::DEFAULT_EXECUTABLE_NAME, arguments, stdin_file_path);
+}
+
+/// The function under test executes the `solc` executable.
+fn execute_solc(arguments: &[&str], stdin_file_path: Option<&str>) {
+    execute_command(
+        SolcCompiler::DEFAULT_EXECUTABLE_NAME,
+        arguments,
+        stdin_file_path,
+    );
+}
+
+fn group<'error, M>(c: &'error mut Criterion<M>, group_name: &str) -> BenchmarkGroup<'error, M>
+where
+    M: Measurement,
+{
+    c.benchmark_group(group_name)
+}
+
+fn bench(
+    mut group: BenchmarkGroup<'_, WallTime>,
+    resolc_arguments: &[&str],
+    solc_arguments: &[&str],
+    stdin_file_path: Option<&str>,
+) {
+    group.bench_function("resolc", |b| {
+        b.iter(|| execute_resolc(resolc_arguments, stdin_file_path));
+    });
+
+    group.bench_function("solc", |b| {
+        b.iter(|| execute_solc(solc_arguments, stdin_file_path));
+    });
+
+    group.finish();
+}
+
+fn bench_empty(c: &mut Criterion) {
+    let mut group = group(c, "Empty");
+    group
+        .sample_size(100)
+        .measurement_time(Duration::from_secs(8));
+    let path = absolute_path(SOLIDITY_CONTRACT_PATH);
+    let resolc_arguments = &[&path, "--bin", ResolcOptSettings::PERFORMANCE];
+    let solc_arguments = &[
+        &path,
+        "--bin",
+        "--via-ir",
+        "--optimize",
+        "--optimize-runs",
+        SolcOptSettings::PERFORMANCE,
+    ];
+
+    bench(group, resolc_arguments, solc_arguments, None);
+}
+
+fn bench_dependency(c: &mut Criterion) {
+    let mut group = group(c, "Dependency");
+    group
+        .sample_size(50)
+        .measurement_time(Duration::from_secs(9));
+    let path = absolute_path(SOLIDITY_DEPENDENCY_CONTRACT_PATH);
+    let resolc_arguments = &[&path, "--bin", ResolcOptSettings::PERFORMANCE];
+    let solc_arguments = &[
+        &path,
+        "--bin",
+        "--via-ir",
+        "--optimize",
+        "--optimize-runs",
+        SolcOptSettings::PERFORMANCE,
+    ];
+
+    bench(group, resolc_arguments, solc_arguments, None);
+}
+
+fn bench_large_div_rem(c: &mut Criterion) {
+    let mut group = group(c, "LargeDivRem");
+    group
+        .sample_size(45)
+        .measurement_time(Duration::from_secs(9));
+    let path = absolute_path(SOLIDITY_LARGE_DIV_REM_CONTRACT_PATH);
+    let resolc_arguments = &[&path, "--bin", ResolcOptSettings::PERFORMANCE];
+    let solc_arguments = &[
+        &path,
+        "--bin",
+        "--via-ir",
+        "--optimize",
+        "--optimize-runs",
+        SolcOptSettings::PERFORMANCE,
+    ];
+
+    bench(group, resolc_arguments, solc_arguments, None);
+}
+
+fn bench_memset(c: &mut Criterion) {
+    let mut group = group(c, "Memset (`--yul`)");
+    group
+        .sample_size(100)
+        .measurement_time(Duration::from_secs(7));
+    let path = absolute_path(YUL_MEMSET_CONTRACT_PATH);
+    let resolc_arguments = &[&path, "--yul", "--bin", ResolcOptSettings::PERFORMANCE];
+    let solc_arguments = &[
+        &path,
+        "--strict-assembly",
+        "--bin",
+        "--optimize",
+        "--optimize-runs",
+        SolcOptSettings::PERFORMANCE,
+    ];
+
+    bench(group, resolc_arguments, solc_arguments, None);
+}
+
+fn bench_return(c: &mut Criterion) {
+    let mut group = group(c, "Return (`--yul`)");
+    group
+        .sample_size(100)
+        .measurement_time(Duration::from_secs(6));
+    let path = absolute_path(YUL_RETURN_CONTRACT_PATH);
+    let resolc_arguments = &[&path, "--yul", "--bin", ResolcOptSettings::PERFORMANCE];
+    let solc_arguments = &[
+        &path,
+        "--strict-assembly",
+        "--bin",
+        "--optimize",
+        "--optimize-runs",
+        SolcOptSettings::PERFORMANCE,
+    ];
+
+    bench(group, resolc_arguments, solc_arguments, None);
+}
+
+fn bench_standard_json_contracts(c: &mut Criterion) {
+    let mut group = group(c, "Multiple Contracts (`--standard-json`)");
+    group
+        .sample_size(20)
+        .measurement_time(Duration::from_secs(35));
+    let path = absolute_path(STANDARD_JSON_CONTRACTS_PATH);
+    let resolc_arguments = &["--standard-json"];
+    let solc_arguments = &["--standard-json"];
+
+    bench(group, resolc_arguments, solc_arguments, Some(&path));
+}
+
+criterion_group!(
+    name = benches;
+    config = Criterion::default();
+    targets =
+        bench_empty,
+        bench_dependency,
+        bench_large_div_rem,
+        bench_memset,
+        bench_return,
+        bench_standard_json_contracts,
+);
+criterion_main!(benches);
@@ -2,6 +2,7 @@

 use std::{
    fs::File,
+    path::PathBuf,
    process::{Command, Stdio},
 };

@@ -10,28 +11,53 @@ use crate::SolcCompiler;
 /// The simple Solidity contract test fixture path.
 pub const SOLIDITY_CONTRACT_PATH: &str = "src/tests/data/solidity/contract.sol";
 /// The dependency Solidity contract test fixture path.
-pub const DEPENDENCY_CONTRACT_PATH: &str = "src/tests/data/solidity/dependency.sol";
+pub const SOLIDITY_DEPENDENCY_CONTRACT_PATH: &str = "src/tests/data/solidity/dependency.sol";
+/// The simple Solidity contract containing i256 divisions and remains
+/// that should be compiled correctly.
+pub const SOLIDITY_LARGE_DIV_REM_CONTRACT_PATH: &str = "src/tests/data/solidity/large_div_rem.sol";

 /// The simple YUL contract test fixture path.
 pub const YUL_CONTRACT_PATH: &str = "src/tests/data/yul/contract.yul";
-
 /// The memeset YUL contract test fixture path.
 pub const YUL_MEMSET_CONTRACT_PATH: &str = "src/tests/data/yul/memset.yul";
+/// The return YUL contract test fixture path.
+pub const YUL_RETURN_CONTRACT_PATH: &str = "src/tests/data/yul/return.yul";
+
 /// The standard JSON contracts test fixture path.
-///
 pub const STANDARD_JSON_CONTRACTS_PATH: &str =
    "src/tests/data/standard_json/solidity_contracts.json";
-
-/// The simple Solidity contract containing i256 divisions and remains that should be compiled
-/// correctly
-pub const SOLIDITY_LARGE_DIV_REM_CONTRACT_PATH: &str = "src/tests/data/solidity/large_div_rem.sol";
+/// The standard JSON no EVM codegen test fixture path.
+///
+/// This contains EVM bytecode selection flags with provided code
+/// that doesn't compile without `viaIr`. Because we remove those
+/// selection flags, it should compile fine regardless.
+pub const STANDARD_JSON_NO_EVM_CODEGEN_PATH: &str =
+    "src/tests/data/standard_json/no_evm_codegen.json";

 /// The `resolc` YUL mode flag.
 pub const RESOLC_YUL_FLAG: &str = "--yul";
 /// The `--yul` option was deprecated in Solidity 0.8.27 in favor of `--strict-assembly`.
-/// See section `--strict-assembly vs. --yul` in https://soliditylang.org/blog/2024/09/04/solidity-0.8.27-release-announcement/
+/// See section `--strict-assembly vs. --yul` in the [release announcement](https://soliditylang.org/blog/2024/09/04/solidity-0.8.27-release-announcement/).
 pub const SOLC_YUL_FLAG: &str = "--strict-assembly";

+/// Common `resolc` CLI optimization settings.
+pub struct ResolcOptSettings;
+
+impl ResolcOptSettings {
+    pub const NONE: &'static str = "-O0";
+    pub const PERFORMANCE: &'static str = "-O3";
+    pub const SIZE: &'static str = "-Oz";
+}
+
+/// Common `solc` CLI optimization settings for `--optimize-runs`.
+pub struct SolcOptSettings;
+
+impl SolcOptSettings {
+    pub const NONE: &'static str = "0";
+    pub const PERFORMANCE: &'static str = "20000";
+    pub const SIZE: &'static str = "1";
+}
+
 /// The result of executing a command.
 pub struct CommandResult {
    /// The data written to `stdout`.
@@ -44,18 +70,22 @@ pub struct CommandResult {
    pub code: i32,
 }

+/// Executes the `resolc` command with the given `arguments`.
 pub fn execute_resolc(arguments: &[&str]) -> CommandResult {
    execute_command("resolc", arguments, None)
 }

+/// Executes the `resolc` command with the given `arguments` and file path passed to `stdin`.
 pub fn execute_resolc_with_stdin_input(arguments: &[&str], stdin_file_path: &str) -> CommandResult {
    execute_command("resolc", arguments, Some(stdin_file_path))
 }

+/// Executes the `solc` command with the given `arguments`.
 pub fn execute_solc(arguments: &[&str]) -> CommandResult {
    execute_command(SolcCompiler::DEFAULT_EXECUTABLE_NAME, arguments, None)
 }

+/// Executes the `solc` command with the given `arguments` and file path passed to `stdin`.
 pub fn execute_solc_with_stdin_input(arguments: &[&str], stdin_file_path: &str) -> CommandResult {
    execute_command(
        SolcCompiler::DEFAULT_EXECUTABLE_NAME,
@@ -64,12 +94,13 @@ pub fn execute_solc_with_stdin_input(arguments: &[&str], stdin_file_path: &str)
    )
 }

-fn execute_command(
+/// Executes the `command` with the given `arguments` and optional file path passed to `stdin`.
+pub fn execute_command(
    command: &str,
    arguments: &[&str],
    stdin_file_path: Option<&str>,
 ) -> CommandResult {
-    println!(
+    log::trace!(
        "executing command: '{command} {}{}'",
        arguments.join(" "),
        stdin_file_path
@@ -97,10 +128,12 @@ fn execute_command(
    }
 }

+/// Asserts that the exit codes of executing `solc` and `resolc` are equal.
 pub fn assert_equal_exit_codes(solc_result: &CommandResult, resolc_result: &CommandResult) {
    assert_eq!(solc_result.code, resolc_result.code,);
 }

+/// Asserts that the command terminated successfully with a `0` exit code.
 pub fn assert_command_success(result: &CommandResult, error_message_prefix: &str) {
    assert!(
        result.success,
@@ -111,6 +144,7 @@ pub fn assert_command_success(result: &CommandResult, error_message_prefix: &str
    );
 }

+/// Asserts that the command terminated with an error and a non-`0` exit code.
 pub fn assert_command_failure(result: &CommandResult, error_message_prefix: &str) {
    assert!(
        !result.success,
@@ -119,3 +153,15 @@ pub fn assert_command_failure(result: &CommandResult, error_message_prefix: &str
        result.code
    );
 }
+
+/// Gets the absolute path of a file. The `relative_path` must
+/// be relative to the `resolc` crate.
+/// Panics if the path does not exist or is not an accessible file.
+pub fn absolute_path(relative_path: &str) -> String {
+    let absolute_path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join(relative_path);
+    if !absolute_path.is_file() {
+        panic!("expected a file at `{}`", absolute_path.display());
+    }
+
+    absolute_path.to_string_lossy().into_owned()
+}
@@ -55,6 +55,8 @@ pub use self::solc::LAST_SUPPORTED_VERSION as SolcLastSupportedVersion;
 pub use self::version::Version as ResolcVersion;

 pub(crate) mod build;
+#[cfg(not(target_os = "emscripten"))]
+pub mod cli_utils;
 pub(crate) mod r#const;
 pub(crate) mod linker;
 pub(crate) mod missing_libraries;
@@ -209,6 +211,7 @@ pub fn standard_json<T: Compiler>(
        .debug_information
        .unwrap_or(false);
    solc_input.extend_selection(SolcStandardJsonInputSettingsSelection::new_required());
+    solc_input.retain_output_selection();
    let mut solc_output = solc.standard_json(
        &mut solc_input,
        messages,
@@ -8,7 +8,7 @@ use serde::Serialize;

 use revive_yul::parser::statement::object::Object;

-/// he contract Yul source code.
+/// The contract Yul source code.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct Yul {
    /// The Yul AST object.
@@ -33,6 +33,7 @@ static PVM_BLOB_CACHE: Lazy<Mutex<HashMap<CachedBlob, Vec<u8>>>> = Lazy::new(Def
 static EVM_BLOB_CACHE: Lazy<Mutex<HashMap<CachedBlob, Vec<u8>>>> = Lazy::new(Default::default);
 static EVM_RUNTIME_BLOB_CACHE: Lazy<Mutex<HashMap<CachedBlob, Vec<u8>>>> =
    Lazy::new(Default::default);
+static YUL_IR_CACHE: Lazy<Mutex<HashMap<CachedBlob, String>>> = Lazy::new(Default::default);

 const DEBUG_CONFIG: revive_llvm_context::DebugConfig = DebugConfig::new(None, true);

@@ -241,47 +242,52 @@ pub fn build_solidity_and_detect_missing_libraries<T: ToString>(
 }

 /// Checks if the Yul project can be built without errors.
-pub fn build_yul<T: ToString + Display>(sources: &[(T, T)]) -> anyhow::Result<()> {
+pub fn build_yul<T: ToString + Display>(
+    sources: &[(T, T)],
+) -> anyhow::Result<BTreeMap<String, Vec<u8>>> {
    check_dependencies();
-
    inkwell::support::enable_llvm_pretty_stack_trace();
    initialize_llvm(PolkaVMTarget::PVM, crate::DEFAULT_EXECUTABLE_NAME, &[]);
-    let optimizer_settings = OptimizerSettings::none();

-    let sources = sources
-        .iter()
-        .map(|(path, source)| {
-            (
-                path.to_string(),
-                SolcStandardJsonInputSource::from(source.to_string()),
-            )
-        })
-        .collect();
-    let mut output = SolcStandardJsonOutput::new(&sources, &mut vec![]);
+    let _ = crate::process::native_process::EXECUTABLE
+        .set(PathBuf::from(crate::r#const::DEFAULT_EXECUTABLE_NAME));

-    let project = Project::try_from_yul_sources(
-        sources,
+    let mut build = Project::try_from_yul_sources(
+        sources
+            .iter()
+            .map(|(path, source)| {
+                (
+                    path.to_string(),
+                    SolcStandardJsonInputSource::from(source.to_string()),
+                )
+            })
+            .collect(),
        Default::default(),
-        Some(&mut output),
-        &Default::default(),
-    )?;
-    let build = project.compile(
+        None,
+        &DEBUG_CONFIG,
+    )?
+    .compile(
        &mut vec![],
-        optimizer_settings,
-        MetadataHash::None,
+        OptimizerSettings::size(),
+        MetadataHash::Keccak256,
        &DEBUG_CONFIG,
        Default::default(),
        Default::default(),
    )?;
+    build.take_and_write_warnings();
    build.check_errors()?;

-    let build = build.link(BTreeMap::new(), &DEBUG_CONFIG);
+    let mut build = build.link(Default::default(), &DEBUG_CONFIG);
+    build.take_and_write_warnings();
    build.check_errors()?;

-    let solc = SolcCompiler::new(SolcCompiler::DEFAULT_EXECUTABLE_NAME.to_owned())?;
-    build.write_to_standard_json(&mut output, &solc.version()?)?;
-    output.check_errors()?;
-    Ok(())
+    Ok(build
+        .results
+        .into_iter()
+        .fold(BTreeMap::new(), |mut init, (path, result)| {
+            init.insert(path.to_string(), result.unwrap().build.bytecode);
+            init
+        }))
 }

 /// Builds the Yul standard JSON and returns the standard JSON output.
@@ -292,13 +298,19 @@ pub fn build_yul_standard_json(
    inkwell::support::enable_llvm_pretty_stack_trace();
    initialize_llvm(PolkaVMTarget::PVM, crate::DEFAULT_EXECUTABLE_NAME, &[]);

+    let _ = crate::process::native_process::EXECUTABLE
+        .set(PathBuf::from(crate::r#const::DEFAULT_EXECUTABLE_NAME));
+
    let solc = SolcCompiler::new(SolcCompiler::DEFAULT_EXECUTABLE_NAME.to_owned())?;
    let mut output = solc.validate_yul_standard_json(&mut solc_input, &mut vec![])?;
+    if output.has_errors() {
+        return Ok(output);
+    }
    let build = Project::try_from_yul_sources(
        solc_input.sources,
        Default::default(),
        Some(&mut output),
-        &Default::default(),
+        &DEBUG_CONFIG,
    )?
    .compile(
        &mut vec![],
@@ -314,7 +326,6 @@ pub fn build_yul_standard_json(
    build.check_errors()?;
    build.write_to_standard_json(&mut output, &solc.version()?)?;

-    output.check_errors()?;
    Ok(output)
 }

@@ -465,3 +476,95 @@ fn compile_evm(

    blob
 }
+
+/// Compiles the Solidity source code into Yul IR and returns
+/// the Yul IR code of the contract named `contract_name`.
+pub fn compile_to_yul(
+    contract_name: &str,
+    source_code: &str,
+    solc_optimizer_enabled: bool,
+) -> String {
+    check_dependencies();
+
+    let optimizer = SolcStandardJsonInputSettingsOptimizer::new(
+        solc_optimizer_enabled,
+        Default::default(),
+        Default::default(),
+    );
+    let id = CachedBlob {
+        contract_name: contract_name.to_owned(),
+        solc_optimizer_enabled,
+        solidity: source_code.to_owned(),
+        opt: optimizer.mode.into(),
+    };
+
+    if let Some(yul) = YUL_IR_CACHE.lock().unwrap().get(&id) {
+        return yul.clone();
+    }
+
+    let file_name = "contract.sol";
+    let sources = BTreeMap::from([(
+        file_name.to_owned(),
+        SolcStandardJsonInputSource::from(source_code.to_owned()),
+    )]);
+    let mut input = SolcStandardJsonInput::try_from_solidity_sources(
+        None,
+        sources.clone(),
+        Default::default(),
+        Default::default(),
+        SolcStandardJsonInputSettingsSelection::new_required_for_tests(),
+        optimizer,
+        Default::default(),
+        Default::default(),
+        Default::default(),
+        Default::default(),
+        false,
+    )
+    .unwrap();
+
+    let solc = SolcCompiler::new(SolcCompiler::DEFAULT_EXECUTABLE_NAME.to_owned()).unwrap();
+    let output = solc
+        .standard_json(&mut input, &mut vec![], None, vec![], None)
+        .unwrap();
+    output.check_errors().unwrap();
+
+    let yul = output
+        .contracts
+        .get(file_name)
+        .unwrap_or_else(|| panic!("file `{file_name}` not found in solc output"))
+        .get(contract_name)
+        .unwrap_or_else(|| panic!("contract `{contract_name}` not found in solc output"))
+        .ir_optimized
+        .to_owned();
+
+    YUL_IR_CACHE.lock().unwrap().insert(id, yul.clone());
+
+    yul
+}
+
+#[cfg(test)]
+mod tests {
+    use std::fs::read_to_string;
+
+    use super::compile_to_yul;
+    use crate::cli_utils::SOLIDITY_DEPENDENCY_CONTRACT_PATH;
+
+    #[test]
+    fn compiles_to_yul() {
+        let contract_name = "Dependency";
+        let source_code = read_to_string(SOLIDITY_DEPENDENCY_CONTRACT_PATH).unwrap();
+        let yul = compile_to_yul(contract_name, &source_code, true);
+        assert!(
+            yul.contains(&format!("object \"{contract_name}")),
+            "the `{contract_name}` contract IR code should contain a Yul object"
+        );
+    }
+
+    #[test]
+    #[should_panic(expected = "contract `Nonexistent` not found in solc output")]
+    fn error_nonexistent_contract_in_yul() {
+        let contract_name = "Nonexistent";
+        let source_code = read_to_string(SOLIDITY_DEPENDENCY_CONTRACT_PATH).unwrap();
+        compile_to_yul(contract_name, &source_code, true);
+    }
+}
@@ -1,14 +1,17 @@
 //! The tests for running resolc with asm option.

-use crate::tests::cli::utils;
+use crate::cli_utils::{
+    assert_command_failure, assert_command_success, assert_equal_exit_codes, execute_resolc,
+    execute_solc, SOLIDITY_CONTRACT_PATH,
+};

 const ASM_OPTION: &str = "--asm";

 #[test]
 fn runs_with_valid_input_file() {
-    let arguments = &[utils::SOLIDITY_CONTRACT_PATH, ASM_OPTION];
-    let resolc_result = utils::execute_resolc(arguments);
-    utils::assert_command_success(&resolc_result, "Providing a valid input file");
+    let arguments = &[SOLIDITY_CONTRACT_PATH, ASM_OPTION];
+    let resolc_result = execute_resolc(arguments);
+    assert_command_success(&resolc_result, "Providing a valid input file");

    for pattern in &["deploy", "call", "seal_return"] {
        assert!(
@@ -17,19 +20,19 @@ fn runs_with_valid_input_file() {
        );
    }

-    let solc_result = utils::execute_solc(arguments);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(arguments);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }

 #[test]
 fn fails_without_input_file() {
    let arguments = &[ASM_OPTION];
-    let resolc_result = utils::execute_resolc(arguments);
-    utils::assert_command_failure(&resolc_result, "Omitting an input file");
+    let resolc_result = execute_resolc(arguments);
+    assert_command_failure(&resolc_result, "Omitting an input file");

    let output = resolc_result.stderr.to_lowercase();
    assert!(output.contains("no input sources specified"));

-    let solc_result = utils::execute_solc(arguments);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(arguments);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }
@@ -0,0 +1,188 @@
+//! The tests for running `resolc` with bin option.
+
+use crate::{
+    cli_utils::{
+        absolute_path, assert_command_success, execute_command, CommandResult, ResolcOptSettings,
+        SolcOptSettings, SOLIDITY_CONTRACT_PATH, STANDARD_JSON_CONTRACTS_PATH,
+        YUL_MEMSET_CONTRACT_PATH,
+    },
+    SolcCompiler,
+};
+
+/// The starting hex value of a PVM blob (encoding of `"PVM"`).
+const PVM_BLOB_START: &str = "50564d";
+
+/// The starting hex value of an EVM blob compiled from Solidity.
+const EVM_BLOB_START_FROM_SOLIDITY: &str = "6080";
+
+/// The starting hex value of an EVM blob compiled from Yul.
+/// (Blobs compiled from Yul do not have consistent starting hex values.)
+const EVM_BLOB_START_FROM_YUL: &str = "";
+
+/// Asserts that the `resolc` output contains a PVM blob.
+fn assert_pvm_blob(result: &CommandResult) {
+    assert_binary_blob(result, "Binary:\n", PVM_BLOB_START);
+}
+
+/// Asserts that the `solc` output from compiling Solidity contains an EVM blob.
+fn assert_evm_blob_from_solidity(result: &CommandResult) {
+    assert_binary_blob(result, "Binary:\n", EVM_BLOB_START_FROM_SOLIDITY);
+}
+
+/// Asserts that the `solc` output from compiling Yul contains an EVM blob.
+fn assert_evm_blob_from_yul(result: &CommandResult) {
+    assert_binary_blob(result, "Binary representation:\n", EVM_BLOB_START_FROM_YUL);
+}
+
+/// Asserts that the `resolc` output of compiling Solidity from JSON input contains a PVM blob.
+/// - `result`: The result of running the command.
+/// - `file_name`: The file name of the contract to verify the existence of a PVM blob for (corresponds to the name specified as a `source` in the JSON input).
+/// - `contract_name`: The name of the contract to verify the existence of a PVM blob for.
+fn assert_pvm_blob_from_json(result: &CommandResult, file_name: &str, contract_name: &str) {
+    assert_binary_blob_from_json(result, file_name, contract_name, PVM_BLOB_START);
+}
+
+/// Asserts that the `solc` output of compiling Solidity from JSON input contains an EVM blob.
+/// - `result`: The result of running the command.
+/// - `file_name`: The file name of the contract to verify the existence of an EVM blob for (corresponds to the name specified as a `source` in the JSON input).
+/// - `contract_name`: The name of the contract to verify the existence of an EVM blob for.
+fn assert_evm_blob_from_json(result: &CommandResult, file_name: &str, contract_name: &str) {
+    assert_binary_blob_from_json(
+        result,
+        file_name,
+        contract_name,
+        EVM_BLOB_START_FROM_SOLIDITY,
+    );
+}
+
+/// Asserts that the output of a compilation contains a binary blob.
+/// - `result`: The result of running the command.
+/// - `blob_prefix`: The `stdout` message immediately preceding the binary blob representation.
+/// - `blob_start`: The starting hex value of the binary blob.
+fn assert_binary_blob(result: &CommandResult, blob_prefix: &str, blob_start: &str) {
+    assert_command_success(result, "Executing the command");
+
+    let is_blob = result
+        .stdout
+        .split(blob_prefix)
+        .collect::<Vec<&str>>()
+        .get(1)
+        .is_some_and(|blob| blob.starts_with(blob_start));
+
+    assert!(
+        is_blob,
+        "expected a binary blob starting with `{blob_start}`",
+    );
+}
+
+/// Asserts that the output of compiling Solidity from JSON input contains a binary blob.
+/// - `result`: The result of running the command.
+/// - `file_name`: The file name of the contract to verify the existence of a binary blob for (corresponds to the name specified as a `source` in the JSON input).
+/// - `contract_name`: The name of the contract to verify the existence of a binary blob for.
+/// - `blob_start`: The starting hex value of the binary blob.
+///
+/// See [output description](https://docs.soliditylang.org/en/latest/using-the-compiler.html#output-description)
+/// for more details on the JSON output format.
+fn assert_binary_blob_from_json(
+    result: &CommandResult,
+    file_name: &str,
+    contract_name: &str,
+    blob_start: &str,
+) {
+    assert_command_success(result, "Executing the command with stdin JSON input");
+
+    let parsed_output: serde_json::Value =
+        serde_json::from_str(&result.stdout).expect("expected valid JSON output");
+    let contract = &parsed_output["contracts"][file_name][contract_name];
+
+    let errors = contract["errors"].as_array();
+    assert!(
+        errors.is_none(),
+        "errors found for JSON-provided contract `{contract_name}` in `{file_name}`: {}",
+        get_first_json_error(errors.unwrap()),
+    );
+
+    let blob = contract["evm"]["bytecode"]["object"]
+        .as_str()
+        .unwrap_or_else(|| {
+            panic!(
+                "expected a binary blob for JSON-provided contract `{contract_name}` in `{file_name}`",
+            )
+        });
+    assert!(
+        blob.starts_with(blob_start),
+        "expected a binary blob starting with `{blob_start}`",
+    );
+}
+
+/// Gets the first error message reported when compiling from JSON input.
+///
+/// See [output description](https://docs.soliditylang.org/en/latest/using-the-compiler.html#output-description)
+/// for more details on the JSON output format.
+fn get_first_json_error(errors: &[serde_json::Value]) -> &str {
+    errors.first().unwrap()["message"].as_str().unwrap()
+}
+
+/// This test mimics the command used in the `resolc` benchmarks when compiling Solidity.
+#[test]
+fn compiles_solidity_to_binary_blob() {
+    let path = absolute_path(SOLIDITY_CONTRACT_PATH);
+    let resolc_arguments = &[&path, "--bin", ResolcOptSettings::PERFORMANCE];
+    let solc_arguments = &[
+        &path,
+        "--bin",
+        "--via-ir",
+        "--optimize",
+        "--optimize-runs",
+        SolcOptSettings::PERFORMANCE,
+    ];
+
+    let resolc_result = execute_command(crate::DEFAULT_EXECUTABLE_NAME, resolc_arguments, None);
+    assert_pvm_blob(&resolc_result);
+
+    let solc_result = execute_command(SolcCompiler::DEFAULT_EXECUTABLE_NAME, solc_arguments, None);
+    assert_evm_blob_from_solidity(&solc_result);
+}
+
+/// This test mimics the command used in the `resolc` benchmarks when compiling Yul.
+#[test]
+fn compiles_yul_to_binary_blob() {
+    let path = absolute_path(YUL_MEMSET_CONTRACT_PATH);
+    let resolc_arguments = &[&path, "--yul", "--bin", ResolcOptSettings::PERFORMANCE];
+    let solc_arguments = &[
+        &path,
+        "--strict-assembly",
+        "--bin",
+        "--optimize",
+        "--optimize-runs",
+        SolcOptSettings::PERFORMANCE,
+    ];
+
+    let resolc_result = execute_command(crate::DEFAULT_EXECUTABLE_NAME, resolc_arguments, None);
+    assert_pvm_blob(&resolc_result);
+
+    let solc_result = execute_command(SolcCompiler::DEFAULT_EXECUTABLE_NAME, solc_arguments, None);
+    assert_evm_blob_from_yul(&solc_result);
+}
+
+/// This test mimics the command used in the `resolc` benchmarks when compiling Solidity via standard JSON input.
+#[test]
+fn compiles_json_to_binary_blob() {
+    let path = absolute_path(STANDARD_JSON_CONTRACTS_PATH);
+    let resolc_arguments = &["--standard-json"];
+    let solc_arguments = &["--standard-json"];
+
+    let resolc_result = execute_command(
+        crate::DEFAULT_EXECUTABLE_NAME,
+        resolc_arguments,
+        Some(&path),
+    );
+    assert_pvm_blob_from_json(&resolc_result, "src/Counter.sol", "Counter");
+
+    let solc_result = execute_command(
+        SolcCompiler::DEFAULT_EXECUTABLE_NAME,
+        solc_arguments,
+        Some(&path),
+    );
+    assert_evm_blob_from_json(&solc_result, "src/Counter.sol", "Counter");
+}
@@ -2,7 +2,10 @@

 use revive_solc_json_interface::CombinedJsonInvalidSelectorMessage;

-use crate::tests::cli::utils;
+use crate::cli_utils::{
+    assert_command_failure, assert_equal_exit_codes, execute_resolc, execute_solc,
+    SOLIDITY_CONTRACT_PATH, YUL_CONTRACT_PATH,
+};

 const JSON_OPTION: &str = "--combined-json";
 const JSON_ARGUMENTS: &[&str] = &[
@@ -21,8 +24,8 @@ const JSON_ARGUMENTS: &[&str] = &[
 #[test]
 fn runs_with_valid_json_argument() {
    for json_argument in JSON_ARGUMENTS {
-        let arguments = &[utils::SOLIDITY_CONTRACT_PATH, JSON_OPTION, json_argument];
-        let resolc_result = utils::execute_resolc(arguments);
+        let arguments = &[SOLIDITY_CONTRACT_PATH, JSON_OPTION, json_argument];
+        let resolc_result = execute_resolc(arguments);
        assert!(
            resolc_result.success,
            "Providing the `{json_argument}` argument should succeed with exit code {}, got {}.\nDetails: {}",
@@ -36,86 +39,82 @@ fn runs_with_valid_json_argument() {
            "Expected the output to contain a `contracts` field when using the `{json_argument}` argument."
        );

-        let solc_result = utils::execute_solc(arguments);
-        utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+        let solc_result = execute_solc(arguments);
+        assert_equal_exit_codes(&solc_result, &resolc_result);
    }
 }

 #[test]
 fn fails_with_invalid_json_argument() {
-    let arguments = &[
-        utils::SOLIDITY_CONTRACT_PATH,
-        JSON_OPTION,
-        "invalid-argument",
-    ];
-    let resolc_result = utils::execute_resolc(arguments);
-    utils::assert_command_failure(&resolc_result, "Providing an invalid json argument");
+    let arguments = &[SOLIDITY_CONTRACT_PATH, JSON_OPTION, "invalid-argument"];
+    let resolc_result = execute_resolc(arguments);
+    assert_command_failure(&resolc_result, "Providing an invalid json argument");

    assert!(resolc_result
        .stderr
        .contains(CombinedJsonInvalidSelectorMessage));

-    let solc_result = utils::execute_solc(arguments);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(arguments);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }

 #[test]
 fn fails_with_multiple_json_arguments() {
    let arguments = &[
-        utils::SOLIDITY_CONTRACT_PATH,
+        SOLIDITY_CONTRACT_PATH,
        JSON_OPTION,
        JSON_ARGUMENTS[0],
        JSON_ARGUMENTS[1],
    ];
-    let resolc_result = utils::execute_resolc(arguments);
-    utils::assert_command_failure(&resolc_result, "Providing multiple json arguments");
+    let resolc_result = execute_resolc(arguments);
+    assert_command_failure(&resolc_result, "Providing multiple json arguments");

    assert!(resolc_result
        .stderr
        .contains(&format!("Error: \"{}\" is not found.", JSON_ARGUMENTS[1])),);

-    let solc_result = utils::execute_solc(arguments);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(arguments);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }

 #[test]
 fn fails_without_json_argument() {
-    let arguments = &[utils::SOLIDITY_CONTRACT_PATH, JSON_OPTION];
-    let resolc_result = utils::execute_resolc(arguments);
-    utils::assert_command_failure(&resolc_result, "Omitting a JSON argument");
+    let arguments = &[SOLIDITY_CONTRACT_PATH, JSON_OPTION];
+    let resolc_result = execute_resolc(arguments);
+    assert_command_failure(&resolc_result, "Omitting a JSON argument");

    assert!(resolc_result.stderr.contains(
        "a value is required for '--combined-json <COMBINED_JSON>' but none was supplied"
    ));

-    let solc_result = utils::execute_solc(arguments);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(arguments);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }

 #[test]
 fn fails_without_solidity_input_file() {
    let arguments = &[JSON_OPTION, JSON_ARGUMENTS[0]];
-    let resolc_result = utils::execute_resolc(arguments);
-    utils::assert_command_failure(&resolc_result, "Omitting a Solidity input file");
+    let resolc_result = execute_resolc(arguments);
+    assert_command_failure(&resolc_result, "Omitting a Solidity input file");

    assert!(resolc_result.stderr.contains("Error: No input files given"),);

-    let solc_result = utils::execute_solc(arguments);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(arguments);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }

 #[test]
 fn fails_with_yul_input_file() {
    for json_argument in JSON_ARGUMENTS {
-        let arguments = &[utils::YUL_CONTRACT_PATH, JSON_OPTION, json_argument];
-        let resolc_result = utils::execute_resolc(arguments);
-        utils::assert_command_failure(&resolc_result, "Providing a Yul input file");
+        let arguments = &[YUL_CONTRACT_PATH, JSON_OPTION, json_argument];
+        let resolc_result = execute_resolc(arguments);
+        assert_command_failure(&resolc_result, "Providing a Yul input file");

        assert!(resolc_result
            .stderr
            .contains("Error: Expected identifier but got 'StringLiteral'"));

-        let solc_result = utils::execute_solc(arguments);
-        utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+        let solc_result = execute_solc(arguments);
+        assert_equal_exit_codes(&solc_result, &resolc_result);
    }
 }
@@ -1,4 +1,4 @@
-use crate::tests::cli::utils::{assert_command_success, execute_resolc, DEPENDENCY_CONTRACT_PATH};
+use crate::cli_utils::{assert_command_success, execute_resolc, SOLIDITY_DEPENDENCY_CONTRACT_PATH};

 /// Test deploy time linking a contract with unresolved factory dependencies.
 #[test]
@@ -6,7 +6,7 @@ fn deploy_time_linking_works() {
    let temp_dir = tempfile::TempDir::new().unwrap();
    let output_directory = temp_dir.path().to_path_buf();
    let source_path = temp_dir.path().to_path_buf().join("dependency.sol");
-    std::fs::copy(DEPENDENCY_CONTRACT_PATH, &source_path).unwrap();
+    std::fs::copy(SOLIDITY_DEPENDENCY_CONTRACT_PATH, &source_path).unwrap();

    assert_command_success(
        &execute_resolc(&[
@@ -58,7 +58,7 @@ fn deploy_time_linking_works() {

 #[test]
 fn emits_unlinked_binary_warning() {
-    let output = execute_resolc(&[DEPENDENCY_CONTRACT_PATH, "--bin"]);
+    let output = execute_resolc(&[SOLIDITY_DEPENDENCY_CONTRACT_PATH, "--bin"]);
    assert_command_success(&output, "Missing libraries should compile fine");
    assert!(output.stderr.contains("is unlinked"));
 }
@@ -1,4 +1,4 @@
-use crate::tests::cli::utils::{
+use crate::cli_utils::{
    assert_command_success, execute_resolc, RESOLC_YUL_FLAG, YUL_CONTRACT_PATH,
 };

@@ -1,6 +1,7 @@
 //! The `resolc` CLI tests.

 mod asm;
+mod bin;
 mod combined_json;
 mod linker;
 mod llvm_arguments;
@@ -8,5 +9,4 @@ mod optimization;
 mod output_dir;
 mod standard_json;
 mod usage;
-mod utils;
 mod yul;
@@ -1,7 +1,7 @@
 //! The tests for running resolc with explicit optimization.

-use crate::tests::cli::utils::{
-    self, assert_command_failure, assert_command_success, assert_equal_exit_codes, execute_resolc,
+use crate::cli_utils::{
+    assert_command_failure, assert_command_success, assert_equal_exit_codes, execute_resolc,
    execute_solc, RESOLC_YUL_FLAG, SOLIDITY_CONTRACT_PATH, SOLIDITY_LARGE_DIV_REM_CONTRACT_PATH,
    YUL_MEMSET_CONTRACT_PATH,
 };
@@ -13,7 +13,7 @@ fn runs_with_valid_level() {
    for level in LEVELS {
        let optimization_argument = format!("-O{level}");
        let arguments = &[YUL_MEMSET_CONTRACT_PATH, "--yul", &optimization_argument];
-        let resolc_result = utils::execute_resolc(arguments);
+        let resolc_result = execute_resolc(arguments);
        assert!(
            resolc_result.success,
            "Providing the level `{optimization_argument}` should succeed with exit code {}, got {}.\nDetails: {}",
@@ -63,7 +63,7 @@ fn test_large_div_rem_expansion() {
    for level in LEVELS {
        let optimization_argument = format!("-O{level}");
        let arguments = &[SOLIDITY_LARGE_DIV_REM_CONTRACT_PATH, &optimization_argument];
-        let resolc_result = utils::execute_resolc(arguments);
+        let resolc_result = execute_resolc(arguments);
        assert!(
            resolc_result.success,
            "Providing the level `{optimization_argument}` should succeed with exit code {}, got {}.\nDetails: {}",
@@ -4,7 +4,9 @@ use std::path::Path;

 use tempfile::tempdir;

-use crate::tests::cli::utils;
+use crate::cli_utils::{
+    assert_command_success, execute_resolc, CommandResult, SOLIDITY_CONTRACT_PATH,
+};

 const OUTPUT_BIN_FILE_PATH: &str = "contract.sol:C.pvm";
 const OUTPUT_ASM_FILE_PATH: &str = "contract.sol:C.pvmasm";
@@ -13,11 +15,11 @@ const OUTPUT_LLVM_UNOPTIMIZED_FILE_PATH: &str =
    "src_tests_data_solidity_contract.sol.C.unoptimized.ll";

 fn assert_valid_output_file(
-    result: &utils::CommandResult,
+    result: &CommandResult,
    debug_output_directory: &Path,
    output_file_name: &str,
 ) {
-    utils::assert_command_success(result, "Providing an output directory");
+    assert_command_success(result, "Providing an output directory");

    assert!(result.stderr.contains("Compiler run successful"),);

@@ -37,7 +39,7 @@ fn assert_valid_output_file(
 fn writes_to_file() {
    let temp_dir = tempdir().unwrap();
    let arguments = &[
-        utils::SOLIDITY_CONTRACT_PATH,
+        SOLIDITY_CONTRACT_PATH,
        "--overwrite",
        "-O3",
        "--bin",
@@ -45,7 +47,7 @@ fn writes_to_file() {
        "--output-dir",
        temp_dir.path().to_str().unwrap(),
    ];
-    let result = utils::execute_resolc(arguments);
+    let result = execute_resolc(arguments);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_BIN_FILE_PATH);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_ASM_FILE_PATH);
 }
@@ -54,7 +56,7 @@ fn writes_to_file() {
 fn writes_debug_info_to_file_unoptimized() {
    let temp_dir = tempdir().unwrap();
    let arguments = &[
-        utils::SOLIDITY_CONTRACT_PATH,
+        SOLIDITY_CONTRACT_PATH,
        "-g",
        "--disable-solc-optimizer",
        "--overwrite",
@@ -63,7 +65,7 @@ fn writes_debug_info_to_file_unoptimized() {
        "--output-dir",
        temp_dir.path().to_str().unwrap(),
    ];
-    let result = utils::execute_resolc(arguments);
+    let result = execute_resolc(arguments);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_BIN_FILE_PATH);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_ASM_FILE_PATH);
 }
@@ -72,7 +74,7 @@ fn writes_debug_info_to_file_unoptimized() {
 fn writes_debug_info_to_file_optimized() {
    let temp_dir = tempdir().unwrap();
    let arguments = &[
-        utils::SOLIDITY_CONTRACT_PATH,
+        SOLIDITY_CONTRACT_PATH,
        "-g",
        "--overwrite",
        "--bin",
@@ -80,7 +82,7 @@ fn writes_debug_info_to_file_optimized() {
        "--output-dir",
        temp_dir.path().to_str().unwrap(),
    ];
-    let result = utils::execute_resolc(arguments);
+    let result = execute_resolc(arguments);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_BIN_FILE_PATH);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_ASM_FILE_PATH);
 }
@@ -89,14 +91,14 @@ fn writes_debug_info_to_file_optimized() {
 fn writes_llvm_debug_info_to_file_unoptimized() {
    let temp_dir = tempdir().unwrap();
    let arguments = &[
-        utils::SOLIDITY_CONTRACT_PATH,
+        SOLIDITY_CONTRACT_PATH,
        "-g",
        "--disable-solc-optimizer",
        "--overwrite",
        "--debug-output-dir",
        temp_dir.path().to_str().unwrap(),
    ];
-    let result = utils::execute_resolc(arguments);
+    let result = execute_resolc(arguments);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_LLVM_UNOPTIMIZED_FILE_PATH);
 }

@@ -104,12 +106,12 @@ fn writes_llvm_debug_info_to_file_unoptimized() {
 fn writes_llvm_debug_info_to_file_optimized() {
    let temp_dir = tempdir().unwrap();
    let arguments = &[
-        utils::SOLIDITY_CONTRACT_PATH,
+        SOLIDITY_CONTRACT_PATH,
        "-g",
        "--overwrite",
        "--debug-output-dir",
        temp_dir.path().to_str().unwrap(),
    ];
-    let result = utils::execute_resolc(arguments);
+    let result = execute_resolc(arguments);
    assert_valid_output_file(&result, temp_dir.path(), OUTPUT_LLVM_OPTIMIZED_FILE_PATH);
 }
@@ -1,8 +1,10 @@
 //! The tests for running resolc with standard JSON option.

-use crate::tests::cli::utils::{
+use revive_solc_json_interface::SolcStandardJsonOutput;
+
+use crate::cli_utils::{
    assert_command_success, assert_equal_exit_codes, execute_resolc_with_stdin_input,
-    execute_solc_with_stdin_input, STANDARD_JSON_CONTRACTS_PATH,
+    execute_solc_with_stdin_input, STANDARD_JSON_CONTRACTS_PATH, STANDARD_JSON_NO_EVM_CODEGEN_PATH,
 };

 const JSON_OPTION: &str = "--standard-json";
@@ -21,3 +23,12 @@ fn runs_with_valid_input_file() {
    let solc_result = execute_solc_with_stdin_input(arguments, STANDARD_JSON_CONTRACTS_PATH);
    assert_equal_exit_codes(&solc_result, &resolc_result);
 }
+
+#[test]
+fn no_evm_codegen_requested() {
+    let result = execute_resolc_with_stdin_input(&[JSON_OPTION], STANDARD_JSON_NO_EVM_CODEGEN_PATH);
+    assert_command_success(&result, "EVM codegen std json input fixture should build");
+
+    let output: SolcStandardJsonOutput = serde_json::from_str(&result.stdout).unwrap();
+    assert!(!output.errors.iter().any(|msg| msg.severity == "error"))
+}
@@ -1,26 +1,29 @@
 //! The tests for running resolc when expecting usage output.

-use crate::tests::cli::utils;
+use crate::cli_utils::{
+    assert_command_failure, assert_command_success, assert_equal_exit_codes, execute_resolc,
+    execute_solc,
+};

 #[test]
 fn shows_usage_with_help() {
    let arguments = &["--help"];
-    let resolc_result = utils::execute_resolc(arguments);
-    utils::assert_command_success(&resolc_result, "Providing the `--help` option");
+    let resolc_result = execute_resolc(arguments);
+    assert_command_success(&resolc_result, "Providing the `--help` option");

    assert!(resolc_result.stdout.contains("Usage: resolc"));

-    let solc_result = utils::execute_solc(arguments);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(arguments);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }

 #[test]
 fn fails_without_options() {
-    let resolc_result = utils::execute_resolc(&[]);
-    utils::assert_command_failure(&resolc_result, "Omitting options");
+    let resolc_result = execute_resolc(&[]);
+    assert_command_failure(&resolc_result, "Omitting options");

    assert!(resolc_result.stderr.contains("Usage: resolc"));

-    let solc_result = utils::execute_solc(&[]);
-    utils::assert_equal_exit_codes(&solc_result, &resolc_result);
+    let solc_result = execute_solc(&[]);
+    assert_equal_exit_codes(&solc_result, &resolc_result);
 }
@@ -1,6 +1,6 @@
 //! The tests for running resolc with yul option.

-use crate::tests::cli::utils::{
+use crate::cli_utils::{
    assert_command_success, assert_equal_exit_codes, execute_resolc, execute_solc, RESOLC_YUL_FLAG,
    SOLC_YUL_FLAG, YUL_CONTRACT_PATH,
 };
@@ -0,0 +1,37 @@
+{
+    "language": "Solidity",
+    "sources": {
+        "/Users/omarabdulla/parity/revive-dt/resolc-compiler-tests/fixtures/solidity/translated_semantic_tests/array/copying/array_of_struct_memory_to_storage/array_of_struct_memory_to_storage.sol": {
+            "content": "contract C {\n    struct S {\n        uint128 a;\n        uint64 b;\n        uint128 c;\n    }\n    uint128[137] unused;\n    S[] s;\n    function f() public returns (uint128, uint64, uint128) {\n        S[] memory m = new S[](3);\n        m[2].a = 10;\n        m[1].b = 11;\n        m[0].c = 12;\n        s = m;\n        return (s[2].a, s[1].b, s[0].c);\n    }\n}"
+        }
+    },
+    "settings": {
+        "libraries": {},
+        "outputSelection": {
+            "*": {
+                "": [
+                    "ast"
+                ],
+                "*": [
+                    "metadata",
+                    "evm.methodIdentifiers",
+                    "irOptimized",
+                    "evm.bytecode",
+                    "evm.deployedBytecode"
+                ]
+            }
+        },
+        "viaIR": true,
+        "optimizer": {
+            "enabled": false,
+            "details": {
+                "peephole": false,
+                "jumpdestRemover": false,
+                "orderLiterals": false,
+                "deduplicate": false,
+                "cse": false,
+                "constantOptimizer": false
+            }
+        }
+    }
+}
@@ -2,9 +2,7 @@
  "language": "Yul",
  "sources": {
    "Test": {
-      "urls": [
-        "src/tests/data/yul/Test.yul"
-      ]
+      "urls": ["src/tests/data/yul/return.yul"]
    }
  },
  "settings": {
@@ -210,4 +210,9 @@ impl Input {
            let _ = source.try_resolve();
        });
    }
+
+    /// Removes unneded output selections.
+    pub fn retain_output_selection(&mut self) {
+        self.settings.retain_output_selection();
+    }
 }
@@ -112,4 +112,9 @@ impl Settings {
    pub fn selection_to_prune(&self) -> Selection {
        self.output_selection.selection_to_prune()
    }
+
+    /// Removes unneeded selections.
+    pub fn retain_output_selection(&mut self) {
+        self.output_selection.retain();
+    }
 }
@@ -47,3 +47,16 @@ pub enum Flag {
    #[serde(rename = "ir")]
    Ir,
 }
+
+impl Flag {
+    /// Whether this selection flag is required for the revive codegen.
+    ///
+    /// Specifically, EVM bytecode and related flags should never be requested.
+    /// It will be replaced by PVM code anyways.
+    pub fn is_required_for_codegen(&self) -> bool {
+        !matches!(
+            self,
+            Flag::EVMBC | Flag::EVMDBC | Flag::EVMLA | Flag::EVM | Flag::Assembly
+        )
+    }
+}
@@ -56,6 +56,14 @@ impl PerFileSelection {
    pub fn is_empty(&self) -> bool {
        self.files.is_empty()
    }
+
+    /// Removes unneeded selections.
+    pub fn retain(&mut self) {
+        for file in self.files.values_mut() {
+            file.per_contract.retain(Flag::is_required_for_codegen);
+            file.per_file.retain(Flag::is_required_for_codegen);
+        }
+    }
 }

 /// The `solc --standard-json` output selection.
@@ -125,4 +133,11 @@ impl Selection {
            .contains(path, flag)
            .unwrap_or(self.all.contains(flag))
    }
+
+    /// Removes unneeded selections.
+    pub fn retain(&mut self) {
+        self.all.per_file.retain(Flag::is_required_for_codegen);
+        self.all.per_contract.retain(Flag::is_required_for_codegen);
+        self.files.retain();
+    }
 }
@@ -0,0 +1,46 @@
+# Benchmarks
+
+## Table of Contents
+
+- [Benchmark Results](#benchmark-results)
+    - [Baseline](#baseline)
+    - [ERC20](#erc20)
+    - [SHA1](#sha1)
+    - [Storage](#storage)
+    - [Transfer](#transfer)
+
+## Benchmark Results
+
+### Baseline
+
+|        | `lower`                    |
+|:-------|:-------------------------- |
+|        | `110.18 us` (✅ **1.00x**)  |
+
+### ERC20
+
+|        | `lower`                    |
+|:-------|:-------------------------- |
+|        | `623.57 us` (✅ **1.00x**)  |
+
+### SHA1
+
+|        | `lower`                    |
+|:-------|:-------------------------- |
+|        | `357.61 us` (✅ **1.00x**)  |
+
+### Storage
+
+|        | `lower`                    |
+|:-------|:-------------------------- |
+|        | `161.24 us` (✅ **1.00x**)  |
+
+### Transfer
+
+|        | `lower`                    |
+|:-------|:-------------------------- |
+|        | `162.35 us` (✅ **1.00x**)  |
+
+---
+Made with [criterion-table](https://github.com/nu11ptr/criterion-table)
+
@@ -0,0 +1,46 @@
+# Benchmarks
+
+## Table of Contents
+
+- [Benchmark Results](#benchmark-results)
+    - [Baseline](#baseline)
+    - [ERC20](#erc20)
+    - [SHA1](#sha1)
+    - [Storage](#storage)
+    - [Transfer](#transfer)
+
+## Benchmark Results
+
+### Baseline
+
+|        | `parse`                  |
+|:-------|:------------------------ |
+|        | `8.20 us` (✅ **1.00x**)  |
+
+### ERC20
+
+|        | `parse`                    |
+|:-------|:-------------------------- |
+|        | `155.02 us` (✅ **1.00x**)  |
+
+### SHA1
+
+|        | `parse`                   |
+|:-------|:------------------------- |
+|        | `74.76 us` (✅ **1.00x**)  |
+
+### Storage
+
+|        | `parse`                   |
+|:-------|:------------------------- |
+|        | `17.05 us` (✅ **1.00x**)  |
+
+### Transfer
+
+|        | `parse`                   |
+|:-------|:------------------------- |
+|        | `19.37 us` (✅ **1.00x**)  |
+
+---
+Made with [criterion-table](https://github.com/nu11ptr/criterion-table)
+
@@ -18,3 +18,16 @@ thiserror = { workspace = true }

 revive-common = { workspace = true }
 revive-llvm-context = { workspace = true }
+
+[dev-dependencies]
+alloy-primitives = { workspace = true }
+criterion = { workspace = true }
+revive-integration = { workspace = true }
+
+[[bench]]
+name = "parse"
+harness = false
+
+[[bench]]
+name = "lower"
+harness = false
@@ -0,0 +1,102 @@
+use std::time::Duration;
+
+use alloy_primitives::U256;
+use criterion::{
+    criterion_group, criterion_main,
+    measurement::{Measurement, WallTime},
+    BatchSize, BenchmarkGroup, Criterion,
+};
+use inkwell::context::Context as InkwellContext;
+use revive_integration::cases::Contract;
+use revive_llvm_context::{
+    initialize_llvm, OptimizerSettings, PolkaVMContext, PolkaVMTarget, PolkaVMWriteLLVM,
+};
+use revive_yul::{lexer::Lexer, parser::statement::object::Object};
+
+/// The function under test lowers the Yul `Object` into unoptimized LLVM IR.
+fn lower(mut ast: Object, mut llvm_context: PolkaVMContext) {
+    ast.declare(&mut llvm_context)
+        .expect("the AST should be valid");
+    ast.into_llvm(&mut llvm_context)
+        .expect("the AST should lower to LLVM IR");
+}
+
+fn parse(source_code: &str) -> Object {
+    let mut lexer = Lexer::new(source_code.to_owned());
+    Object::parse(&mut lexer, None).expect("the Yul source should parse")
+}
+
+fn group<'error, M>(c: &'error mut Criterion<M>, group_name: &str) -> BenchmarkGroup<'error, M>
+where
+    M: Measurement,
+{
+    c.benchmark_group(group_name)
+}
+
+fn bench<F>(mut group: BenchmarkGroup<'_, WallTime>, contract: F)
+where
+    F: Fn() -> Contract,
+{
+    let ast = parse(&contract().yul);
+    let llvm = InkwellContext::create();
+    // The optimizer settings will not affect the benchmarks since we're
+    // not running the optimization passes.
+    let optimizer_settings = OptimizerSettings::none();
+
+    initialize_llvm(PolkaVMTarget::PVM, "resolc", Default::default());
+
+    group
+        .sample_size(90)
+        .measurement_time(Duration::from_secs(6));
+
+    group.bench_function("lower", |b| {
+        b.iter_batched(
+            || {
+                (
+                    ast.clone(),
+                    PolkaVMContext::new_dummy(&llvm, optimizer_settings.to_owned()),
+                )
+            },
+            |(ast, llvm_context)| lower(ast, llvm_context),
+            BatchSize::SmallInput,
+        );
+    });
+
+    group.finish();
+}
+
+fn bench_baseline(c: &mut Criterion) {
+    bench(group(c, "Baseline"), Contract::baseline);
+}
+
+fn bench_erc20(c: &mut Criterion) {
+    bench(group(c, "ERC20"), Contract::erc20);
+}
+
+fn bench_sha1(c: &mut Criterion) {
+    bench(group(c, "SHA1"), || Contract::sha1(vec![0xff].into()));
+}
+
+fn bench_storage(c: &mut Criterion) {
+    bench(group(c, "Storage"), || {
+        Contract::storage_transient(U256::from(0))
+    });
+}
+
+fn bench_transfer(c: &mut Criterion) {
+    bench(group(c, "Transfer"), || {
+        Contract::transfer_self(U256::from(0))
+    });
+}
+
+criterion_group!(
+    name = benches_lower;
+    config = Criterion::default();
+    targets =
+        bench_baseline,
+        bench_erc20,
+        bench_sha1,
+        bench_storage,
+        bench_transfer,
+);
+criterion_main!(benches_lower);
@@ -0,0 +1,72 @@
+use alloy_primitives::U256;
+use criterion::{
+    criterion_group, criterion_main,
+    measurement::{Measurement, WallTime},
+    BenchmarkGroup, Criterion,
+};
+use revive_integration::cases::Contract;
+use revive_yul::{lexer::Lexer, parser::statement::object::Object};
+
+/// The function under test parses the Yul `source_code`.
+fn parse(source_code: &str) {
+    let mut lexer = Lexer::new(source_code.to_owned());
+    Object::parse(&mut lexer, None).expect("the Yul source should parse");
+}
+
+fn group<'error, M>(c: &'error mut Criterion<M>, group_name: &str) -> BenchmarkGroup<'error, M>
+where
+    M: Measurement,
+{
+    c.benchmark_group(group_name)
+}
+
+fn bench<F>(mut group: BenchmarkGroup<'_, WallTime>, contract: F)
+where
+    F: Fn() -> Contract,
+{
+    let source_code = contract().yul;
+
+    group.sample_size(200);
+
+    group.bench_function("parse", |b| {
+        b.iter(|| parse(&source_code));
+    });
+
+    group.finish();
+}
+
+fn bench_baseline(c: &mut Criterion) {
+    bench(group(c, "Baseline"), Contract::baseline);
+}
+
+fn bench_erc20(c: &mut Criterion) {
+    bench(group(c, "ERC20"), Contract::erc20);
+}
+
+fn bench_sha1(c: &mut Criterion) {
+    bench(group(c, "SHA1"), || Contract::sha1(vec![0xff].into()));
+}
+
+fn bench_storage(c: &mut Criterion) {
+    bench(group(c, "Storage"), || {
+        Contract::storage_transient(U256::from(0))
+    });
+}
+
+fn bench_transfer(c: &mut Criterion) {
+    bench(group(c, "Transfer"), || {
+        Contract::transfer_self(U256::from(0))
+    });
+}
+
+criterion_group!(
+    name = benches_parse;
+    config = Criterion::default();
+    targets =
+        bench_baseline,
+        bench_erc20,
+        bench_sha1,
+        bench_storage,
+        bench_transfer,
+);
+criterion_main!(benches_parse);
@@ -64,6 +64,9 @@ impl PolkaVMWriteLLVM for Code {
    fn into_llvm(self, context: &mut PolkaVMContext) -> anyhow::Result<()> {
        self.block.into_llvm(context)?;

+        // The EVM lets the code return implicitly.
+        revive_llvm_context::polkavm_evm_return::stop(context)?;
+
        Ok(())
    }
 }
@@ -215,7 +215,7 @@ impl PolkaVMWriteLLVM for FunctionDefinition {
            self.identifier.as_str(),
            function_type,
            self.result.len(),
-            Some(inkwell::module::Linkage::External),
+            Some(inkwell::module::Linkage::Internal),
            Some((self.location.line, self.location.column)),
            true,
        )?;
@@ -0,0 +1 @@
+This file makes sure that Github Pages doesn't process mdBook's output.
@@ -0,0 +1,241 @@
+<!DOCTYPE HTML>
+<html lang="en" class="light sidebar-visible" dir="ltr">
+    <head>
+        <!-- Book generated using mdBook -->
+        <meta charset="UTF-8">
+        <title>Page not found - revive compiler book</title>
+        <base href="/">
+
+
+        <!-- Custom HTML head -->
+
+        <meta name="description" content="">
+        <meta name="viewport" content="width=device-width, initial-scale=1">
+        <meta name="theme-color" content="#ffffff">
+
+        <link rel="icon" href="favicon-de23e50b.svg">
+        <link rel="shortcut icon" href="favicon-8114d1fc.png">
+        <link rel="stylesheet" href="css/variables-8adf115d.css">
+        <link rel="stylesheet" href="css/general-2459343d.css">
+        <link rel="stylesheet" href="css/chrome-ae938929.css">
+        <link rel="stylesheet" href="css/print-9e4910d8.css" media="print">
+
+        <!-- Fonts -->
+        <link rel="stylesheet" href="fonts/fonts-9644e21d.css">
+
+        <!-- Highlight.js Stylesheets -->
+        <link rel="stylesheet" id="mdbook-highlight-css" href="highlight-493f70e1.css">
+        <link rel="stylesheet" id="mdbook-tomorrow-night-css" href="tomorrow-night-4c0ae647.css">
+        <link rel="stylesheet" id="mdbook-ayu-highlight-css" href="ayu-highlight-3fdfc3ac.css">
+
+        <!-- Custom theme stylesheets -->
+
+
+        <!-- Provide site root and default themes to javascript -->
+        <script>
+            const path_to_root = "";
+            const default_light_theme = "light";
+            const default_dark_theme = "navy";
+            window.path_to_searchindex_js = "searchindex-756a6899.js";
+        </script>
+        <!-- Start loading toc.js asap -->
+        <script src="toc-6f3f265e.js"></script>
+    </head>
+    <body>
+    <div id="mdbook-help-container">
+        <div id="mdbook-help-popup">
+            <h2 class="mdbook-help-title">Keyboard shortcuts</h2>
+            <div>
+                <p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
+                <p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
+                <p>Press <kbd>?</kbd> to show this help</p>
+                <p>Press <kbd>Esc</kbd> to hide this help</p>
+            </div>
+        </div>
+    </div>
+    <div id="mdbook-body-container">
+        <!-- Work around some values being stored in localStorage wrapped in quotes -->
+        <script>
+            try {
+                let theme = localStorage.getItem('mdbook-theme');
+                let sidebar = localStorage.getItem('mdbook-sidebar');
+
+                if (theme.startsWith('"') && theme.endsWith('"')) {
+                    localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
+                }
+
+                if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
+                    localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
+                }
+            } catch (e) { }
+        </script>
+
+        <!-- Set the theme before any content is loaded, prevents flash -->
+        <script>
+            const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
+            let theme;
+            try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
+            if (theme === null || theme === undefined) { theme = default_theme; }
+            const html = document.documentElement;
+            html.classList.remove('light')
+            html.classList.add(theme);
+            html.classList.add("js");
+        </script>
+
+        <input type="checkbox" id="mdbook-sidebar-toggle-anchor" class="hidden">
+
+        <!-- Hide / unhide sidebar before it is displayed -->
+        <script>
+            let sidebar = null;
+            const sidebar_toggle = document.getElementById("mdbook-sidebar-toggle-anchor");
+            if (document.body.clientWidth >= 1080) {
+                try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
+                sidebar = sidebar || 'visible';
+            } else {
+                sidebar = 'hidden';
+                sidebar_toggle.checked = false;
+            }
+            if (sidebar === 'visible') {
+                sidebar_toggle.checked = true;
+            } else {
+                html.classList.remove('sidebar-visible');
+            }
+        </script>
+
+        <nav id="mdbook-sidebar" class="sidebar" aria-label="Table of contents">
+            <!-- populated by js -->
+            <mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
+            <noscript>
+                <iframe class="sidebar-iframe-outer" src="toc.html"></iframe>
+            </noscript>
+            <div id="mdbook-sidebar-resize-handle" class="sidebar-resize-handle">
+                <div class="sidebar-resize-indicator"></div>
+            </div>
+        </nav>
+
+        <div id="mdbook-page-wrapper" class="page-wrapper">
+
+            <div class="page">
+                <div id="mdbook-menu-bar-hover-placeholder"></div>
+                <div id="mdbook-menu-bar" class="menu-bar sticky">
+                    <div class="left-buttons">
+                        <label id="mdbook-sidebar-toggle" class="icon-button" for="mdbook-sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="mdbook-sidebar">
+                            <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M0 96C0 78.3 14.3 64 32 64H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32C14.3 128 0 113.7 0 96zM0 256c0-17.7 14.3-32 32-32H416c17.7 0 32 14.3 32 32s-14.3 32-32 32H32c-17.7 0-32-14.3-32-32zM448 416c0 17.7-14.3 32-32 32H32c-17.7 0-32-14.3-32-32s14.3-32 32-32H416c17.7 0 32 14.3 32 32z"/></svg></span>
+                        </label>
+                        <button id="mdbook-theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="mdbook-theme-list">
+                            <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M371.3 367.1c27.3-3.9 51.9-19.4 67.2-42.9L600.2 74.1c12.6-19.5 9.4-45.3-7.6-61.2S549.7-4.4 531.1 9.6L294.4 187.2c-24 18-38.2 46.1-38.4 76.1L371.3 367.1zm-19.6 25.4l-116-104.4C175.9 290.3 128 339.6 128 400c0 3.9 .2 7.8 .6 11.6c1.8 17.5-10.2 36.4-27.8 36.4H96c-17.7 0-32 14.3-32 32s14.3 32 32 32H240c61.9 0 112-50.1 112-112c0-2.5-.1-5-.2-7.5z"/></svg></span>
+                        </button>
+                        <ul id="mdbook-theme-list" class="theme-popup" aria-label="Themes" role="menu">
+                            <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-default_theme">Auto</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-light">Light</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-rust">Rust</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-coal">Coal</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-navy">Navy</button></li>
+                            <li role="none"><button role="menuitem" class="theme" id="mdbook-theme-ayu">Ayu</button></li>
+                        </ul>
+                        <button id="mdbook-search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="mdbook-searchbar">
+                            <span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M416 208c0 45.9-14.9 88.3-40 122.7L502.6 457.4c12.5 12.5 12.5 32.8 0 45.3s-32.8 12.5-45.3 0L330.7 376c-34.4 25.2-76.8 40-122.7 40C93.1 416 0 322.9 0 208S93.1 0 208 0S416 93.1 416 208zM208 352c79.5 0 144-64.5 144-144s-64.5-144-144-144S64 128.5 64 208s64.5 144 144 144z"/></svg></span>
+                        </button>
+                    </div>
+
+                    <h1 class="menu-title">revive compiler book</h1>
+
+                    <div class="right-buttons">
+                        <a href="print.html" title="Print this book" aria-label="Print this book">
+                            <span class=fa-svg id="print-button"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M128 0C92.7 0 64 28.7 64 64v96h64V64H354.7L384 93.3V160h64V93.3c0-17-6.7-33.3-18.7-45.3L400 18.7C388 6.7 371.7 0 354.7 0H128zM384 352v32 64H128V384 368 352H384zm64 32h32c17.7 0 32-14.3 32-32V256c0-35.3-28.7-64-64-64H64c-35.3 0-64 28.7-64 64v96c0 17.7 14.3 32 32 32H64v64c0 35.3 28.7 64 64 64H384c35.3 0 64-28.7 64-64V384zm-16-88c-13.3 0-24-10.7-24-24s10.7-24 24-24s24 10.7 24 24s-10.7 24-24 24z"/></svg></span>
+                        </a>
+
+                    </div>
+                </div>
+
+                <div id="mdbook-search-wrapper" class="hidden">
+                    <form id="mdbook-searchbar-outer" class="searchbar-outer">
+                        <div class="search-wrapper">
+                            <input type="search" id="mdbook-searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="mdbook-searchresults-outer" aria-describedby="searchresults-header">
+                            <div class="spinner-wrapper">
+                                <span class=fa-svg id="fa-spin"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M304 48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zm0 416c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM48 304c26.5 0 48-21.5 48-48s-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48zm464-48c0-26.5-21.5-48-48-48s-48 21.5-48 48s21.5 48 48 48s48-21.5 48-48zM142.9 437c18.7-18.7 18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zm0-294.2c18.7-18.7 18.7-49.1 0-67.9S93.7 56.2 75 75s-18.7 49.1 0 67.9s49.1 18.7 67.9 0zM369.1 437c18.7 18.7 49.1 18.7 67.9 0s18.7-49.1 0-67.9s-49.1-18.7-67.9 0s-18.7 49.1 0 67.9z"/></svg></span>
+                            </div>
+                        </div>
+                    </form>
+                    <div id="mdbook-searchresults-outer" class="searchresults-outer hidden">
+                        <div id="mdbook-searchresults-header" class="searchresults-header"></div>
+                        <ul id="mdbook-searchresults">
+                        </ul>
+                    </div>
+                </div>
+
+                <!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
+                <script>
+                    document.getElementById('mdbook-sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
+                    document.getElementById('mdbook-sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
+                    Array.from(document.querySelectorAll('#mdbook-sidebar a')).forEach(function(link) {
+                        link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
+                    });
+                </script>
+
+                <div id="mdbook-content" class="content">
+                    <main>
+                        <h1 id="document-not-found-404"><a class="header" href="#document-not-found-404">Document not found (404)</a></h1>
+<p>This URL is invalid, sorry. Please use the navigation bar or search to continue.</p>
+
+                    </main>
+
+                    <nav class="nav-wrapper" aria-label="Page navigation">
+                        <!-- Mobile navigation buttons -->
+
+
+                        <div style="clear: both"></div>
+                    </nav>
+                </div>
+            </div>
+
+            <nav class="nav-wide-wrapper" aria-label="Page navigation">
+
+            </nav>
+
+        </div>
+
+        <template id=fa-eye><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M288 32c-80.8 0-145.5 36.8-192.6 80.6C48.6 156 17.3 208 2.5 243.7c-3.3 7.9-3.3 16.7 0 24.6C17.3 304 48.6 356 95.4 399.4C142.5 443.2 207.2 480 288 480s145.5-36.8 192.6-80.6c46.8-43.5 78.1-95.4 93-131.1c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C433.5 68.8 368.8 32 288 32zM432 256c0 79.5-64.5 144-144 144s-144-64.5-144-144s64.5-144 144-144s144 64.5 144 144zM288 192c0 35.3-28.7 64-64 64c-11.5 0-22.3-3-31.6-8.4c-.2 2.8-.4 5.5-.4 8.4c0 53 43 96 96 96s96-43 96-96s-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6z"/></svg></span></template>
+        <template id=fa-eye-slash><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 640 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M38.8 5.1C28.4-3.1 13.3-1.2 5.1 9.2S-1.2 34.7 9.2 42.9l592 464c10.4 8.2 25.5 6.3 33.7-4.1s6.3-25.5-4.1-33.7L525.6 386.7c39.6-40.6 66.4-86.1 79.9-118.4c3.3-7.9 3.3-16.7 0-24.6c-14.9-35.7-46.2-87.7-93-131.1C465.5 68.8 400.8 32 320 32c-68.2 0-125 26.3-169.3 60.8L38.8 5.1zM223.1 149.5C248.6 126.2 282.7 112 320 112c79.5 0 144 64.5 144 144c0 24.9-6.3 48.3-17.4 68.7L408 294.5c5.2-11.8 8-24.8 8-38.5c0-53-43-96-96-96c-2.8 0-5.6 .1-8.4 .4c5.3 9.3 8.4 20.1 8.4 31.6c0 10.2-2.4 19.8-6.6 28.3l-90.3-70.8zm223.1 298L373 389.9c-16.4 6.5-34.3 10.1-53 10.1c-79.5 0-144-64.5-144-144c0-6.9 .5-13.6 1.4-20.2L83.1 161.5C60.3 191.2 44 220.8 34.5 243.7c-3.3 7.9-3.3 16.7 0 24.6c14.9 35.7 46.2 87.7 93 131.1C174.5 443.2 239.2 480 320 480c47.8 0 89.9-12.9 126.2-32.5z"/></svg></span></template>
+        <template id=fa-copy><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M502.6 70.63l-61.25-61.25C435.4 3.371 427.2 0 418.7 0H255.1c-35.35 0-64 28.66-64 64l.0195 256C192 355.4 220.7 384 256 384h192c35.2 0 64-28.8 64-64V93.25C512 84.77 508.6 76.63 502.6 70.63zM464 320c0 8.836-7.164 16-16 16H255.1c-8.838 0-16-7.164-16-16L239.1 64.13c0-8.836 7.164-16 16-16h128L384 96c0 17.67 14.33 32 32 32h47.1V320zM272 448c0 8.836-7.164 16-16 16H63.1c-8.838 0-16-7.164-16-16L47.98 192.1c0-8.836 7.164-16 16-16H160V128H63.99c-35.35 0-64 28.65-64 64l.0098 256C.002 483.3 28.66 512 64 512h192c35.2 0 64-28.8 64-64v-32h-47.1L272 448z"/></svg></span></template>
+        <template id=fa-play><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 384 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M73 39c-14.8-9.1-33.4-9.4-48.5-.9S0 62.6 0 80V432c0 17.4 9.4 33.4 24.5 41.9s33.7 8.1 48.5-.9L361 297c14.3-8.7 23-24.2 23-41s-8.7-32.2-23-41L73 39z"/></svg></span></template>
+        <template id=fa-clock-rotate-left><span class=fa-svg><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 6.2.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2022 Fonticons, Inc. --><path d="M75 75L41 41C25.9 25.9 0 36.6 0 57.9V168c0 13.3 10.7 24 24 24H134.1c21.4 0 32.1-25.9 17-41l-30.8-30.8C155 85.5 203 64 256 64c106 0 192 86 192 192s-86 192-192 192c-40.8 0-78.6-12.7-109.7-34.4c-14.5-10.1-34.4-6.6-44.6 7.9s-6.6 34.4 7.9 44.6C151.2 495 201.7 512 256 512c141.4 0 256-114.6 256-256S397.4 0 256 0C185.3 0 121.3 28.7 75 75zm181 53c-13.3 0-24 10.7-24 24V256c0 6.4 2.5 12.5 7 17l72 72c9.4 9.4 24.6 9.4 33.9 0s9.4-24.6 0-33.9l-65-65V152c0-13.3-10.7-24-24-24z"/></svg></span></template>
+
+        <!-- Livereload script (if served using the cli tool) -->
+        <script>
+            const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsAddress = wsProtocol + "//" + location.host + "/" + "__livereload";
+            const socket = new WebSocket(wsAddress);
+            socket.onmessage = function (event) {
+                if (event.data === "reload") {
+                    socket.close();
+                    location.reload();
+                }
+            };
+
+            window.onbeforeunload = function() {
+                socket.close();
+            }
+        </script>
+
+
+        <script>
+            window.playground_copyable = true;
+        </script>
+
+
+        <script src="elasticlunr-ef4e11c1.min.js"></script>
+        <script src="mark-09e88c2c.min.js"></script>
+        <script src="searcher-c2a407aa.js"></script>
+
+        <script src="clipboard-1626706a.min.js"></script>
+        <script src="highlight-abc7f01d.js"></script>
+        <script src="book-a0b12cfe.js"></script>
+
+        <!-- Custom JS scripts -->
+
+
+
+    </div>
+    </body>
+</html>
@@ -0,0 +1,77 @@
+/*
+Based off of the Ayu theme
+Original by Dempfi (https://github.com/dempfi/ayu)
+*/
+
+.hljs {
+  display: block;
+  overflow-x: auto;
+  background: #191f26;
+  color: #e6e1cf;
+}
+
+.hljs-comment,
+.hljs-quote {
+  color: #5c6773;
+}
+
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute,
+.hljs-attr,
+.hljs-regexp,
+.hljs-link,
+.hljs-selector-id,
+.hljs-selector-class {
+  color: #ff7733;
+}
+
+.hljs-number,
+.hljs-meta,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params {
+  color: #ffee99;
+}
+
+.hljs-string,
+.hljs-bullet {
+  color: #b8cc52;
+}
+
+.hljs-title,
+.hljs-built_in,
+.hljs-section {
+  color: #ffb454;
+}
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-symbol {
+  color: #ff7733;
+}
+
+.hljs-name {
+    color: #36a3d9;
+}
+
+.hljs-tag {
+    color: #00568d;
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: bold;
+}
+
+.hljs-addition {
+  color: #91b362;
+}
+
+.hljs-deletion {
+  color: #d96c75;
+}
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
elle-j	6187f76d63	Control concurrency and cancel in-progress runs when re-triggered.	2025-12-02 16:38:06 +01:00
LJ	e6ccaa0bab	Merge branch 'main' into lj/ci-benchmarks	2025-12-02 08:13:11 +01:00
xermicus	e7e40a0ded	The `revive` compiler documentation (#424 ) This PR adds comprehensive project documentation in the form of an mdBook. --------- Signed-off-by: xermicus <cyrill@parity.io> Signed-off-by: Cyrill Leutwiler <bigcyrill@hotmail.com> Co-authored-by: LJ <81748770+elle-j@users.noreply.github.com> Co-authored-by: PG Herveou <pgherveou@gmail.com>	2025-12-01 14:58:02 +01:00
LJ	94b14b079b	ci: Bump `macos` runner images (#417 ) Closes #416. Workflows using x86_64-apple-darwin target with a `macos-13` runner image have been migrated to `macos-15-intel` due to deprecation (see #416), and `macos-14` images have been migrated to `macos-15`.	2025-11-29 11:06:30 +01:00
kvpanch	8cd10a6136	Clone emsdk for release-llvm CI action (#423 ) Cloning of emsdk has been accidentally removed, that caused inability to build LLVM release with current main. The change adds this cloning back before emsdk script is sourced.	2025-11-27 21:36:28 -05:00
elle-j	7cc1921c01	Update naming.	2025-11-27 21:31:31 +01:00
elle-j	3446aaa238	Update checkouts and report generation.	2025-11-27 17:21:41 +01:00
elle-j	0847b99a7d	Implement initial workflow to run benchmarks.	2025-11-26 11:35:30 +01:00
LJ	0742227c5a	Implement Yul to LLVM IR compilation benchmarks (#407 ) # Description Closes [#404](https://github.com/paritytech/revive/issues/404) Adds compilation time benchmarks for: * Parsing of Yul source code -> AST Object * Lowering of AST Object -> LLVM IR (unoptimized) The benchmarks can be run from the root via: ```sh # Run all benchmarks in the revive-yul crate (parsing + lowering) make bench-yul ``` HTML reports will be generated under `target/criterion`, and a summary of the results at [crates/yul/BENCHMARKS_PARSE_M4PRO.md](https://github.com/paritytech/revive/blob/lj/compilation-benchmarks-yul/crates/yul/BENCHMARKS_PARSE_M4PRO.md) and [crates/yul/BENCHMARKS_LOWER_M4PRO.md](https://github.com/paritytech/revive/blob/lj/compilation-benchmarks-yul/crates/yul/BENCHMARKS_LOWER_M4PRO.md) (currently from running on a Mac M4 Pro). --------- Co-authored-by: xermicus <cyrill@parity.io>	2025-11-25 12:00:06 +01:00
xermicus	1e0cce0fa8	Fix the Makefile (#421 ) Fix the Makefile	2025-11-24 16:17:54 +01:00
kvpanch	b6a19c97b1	Fetch LLVM release according to branch in llvm submodule (#418 ) This change is essential first step to unblock gracefully enable LLVM 21 in revive compiler as current action blindly fetched latest LLVM binary from the list of releases on our page. The change queries release version from the submodule and uses it. Next step: build LLVM 21 release binary Next next step: switch revive compile to LLVM 21 after all issues are fixed	2025-11-21 11:12:00 -05:00
xermicus	d97d094a8a	Update the Rust dependencies (#420 ) The `Cargo.lock` kept changing locally on all my hosts. Not sure why exactly - maybe it got forgotten in a recent PR. I took it as an opportunity to quickly update the Rust dependencies. --------- Signed-off-by: xermicus <bigcyrill@hotmail.com>	2025-11-21 15:34:21 +01:00
xermicus	975b610d9f	Add the LLVM dir to the `.ignore` file (#419 ) LLVM is now a submodule and no longer in `.gitignore`. Thus, some dev tools I use, like `rg` and `fd`, now consider the `llvm/` directory. This PR fixes that by adding `llvm/` to the `.ignore` file. Signed-off-by: xermicus <bigcyrill@hotmail.com>	2025-11-21 14:43:44 +01:00
LJ	ad61b6e3c9	Implement `resolc` end-to-end compilation benchmarks (#406 ) # Description Closes [#403](https://github.com/paritytech/revive/issues/403) Adds compilation time benchmarks for resolc end-to-end. The benchmarks can be run from the root via: ```sh make bench-resolc ``` HTML reports will be generated under `target/criterion`, and a summary of the results at [crates/resolc/BENCHMARKS_M4PRO.md](https://github.com/paritytech/revive/blob/lj/compilation-benchmarks/crates/resolc/BENCHMARKS_M4PRO.md) (currently from running on a Mac M4 Pro).	2025-11-19 12:16:07 +01:00
kvpanch	e78f3cc419	add LLVM 18.x as a git submodule (#399 ) This changeset is based on https://github.com/paritytech/revive/pull/346	2025-11-18 16:10:15 -05:00
xermicus	a1090cfa5a	revive-yul: fix the code block exit (#414 ) This PR fixes the missing `STOP` instruction at the end of `code` blocks. --------- Signed-off-by: xermicus <bigcyrill@hotmail.com>	2025-11-17 18:47:58 +01:00
xermicus	dd48baadc7	resolc: fix the Yul test utils (#413 ) - Fixes multiple bugs in the Yul test util helpers. - The simple Yul builder utility helper now returns the contract builds. Signed-off-by: xermicus <bigcyrill@hotmail.com>	2025-11-17 17:45:03 +01:00
dependabot[bot]	a3a5c7380d	Bump js-yaml from 4.1.0 to 4.1.1 (#412 ) Bumps [js-yaml](https://github.com/nodeca/js-yaml) from 4.1.0 to 4.1.1. <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/nodeca/js-yaml/blob/master/CHANGELOG.md">js-yaml's changelog</a>.</em></p> <blockquote> <h2>[4.1.1] - 2025-11-12</h2> <h3>Security</h3> <ul> <li>Fix prototype pollution issue in yaml merge (<<) operator.</li> </ul> </blockquote> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/nodeca/js-yaml/commit/cc482e775913e6625137572a3712d2826170e53a"><code>cc482e7</code></a> 4.1.1 released</li> <li><a href="https://github.com/nodeca/js-yaml/commit/50968b862e75866ef90e626572fe0b2f97b55f9f"><code>50968b8</code></a> dist rebuild</li> <li><a href="https://github.com/nodeca/js-yaml/commit/d092d866031751cb27c12d93f3e2470ad74d678b"><code>d092d86</code></a> lint fix</li> <li><a href="https://github.com/nodeca/js-yaml/commit/383665ff4248ec2192d1274e934462bb30426879"><code>383665f</code></a> fix prototype pollution in merge (<<)</li> <li><a href="https://github.com/nodeca/js-yaml/commit/0d3ca7a27b03a6c974790a30a89e456007d62976"><code>0d3ca7a</code></a> README.md: HTTP => HTTPS (<a href="https://redirect.github.com/nodeca/js-yaml/issues/678">#678</a>)</li> <li><a href="https://github.com/nodeca/js-yaml/commit/49baadd52af887d2991e2c39a6639baa56d6c71b"><code>49baadd</code></a> doc: 'empty' style option for !!null</li> <li><a href="https://github.com/nodeca/js-yaml/commit/ba3460eb9d3e4478edcbc29edabe17c2157fc9ce"><code>ba3460e</code></a> Fix demo link (<a href="https://redirect.github.com/nodeca/js-yaml/issues/618">#618</a>)</li> <li>See full diff in <a href="https://github.com/nodeca/js-yaml/compare/4.1.0...4.1.1">compare view</a></li> </ul> </details> <br /> [![Dependabot compatibility score](https://dependabot-badges.githubapp.com/badges/compatibility_score?dependency-name=js-yaml&package-manager=npm_and_yarn&previous-version=4.1.0&new-version=4.1.1)](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot merge` will merge this PR after your CI passes on it - `@dependabot squash and merge` will squash and merge this PR after your CI passes on it - `@dependabot cancel merge` will cancel a previously requested merge and block automerging - `@dependabot reopen` will reopen this PR if it is closed - `@dependabot close` will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) You can disable automated security fix PRs for this repo from the [Security Alerts page](https://github.com/paritytech/revive/network/alerts). </details> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>	2025-11-17 10:54:36 +01:00
xermicus	79aaca1a85	std json: do not request EVM bytecode (#410 ) These compiler outputs are irrelevant for the `resolc` compilation pipeline. It can also break the compilation pipeline. For example, solc may reject the code without via-ir or fail during the EVM codegen phase with stack too deep errors - which is not relevant to us. --------- Signed-off-by: xermicus <cyrill@parity.io>	2025-11-13 10:32:32 +01:00
PG Herveou	8ee1860f12	js: rm default process.env.RESOLC_BIN (#411 ) Ran into this today, my env was set and pointing to an old version so it's a breaking change, but I think we are better off not hardcoding the env here, the user can do whatever they want when they invoke compile	2025-11-13 10:16:34 +01:00
xermicus	878ca91689	RISCV relaxations (#408 ) This PR enables RISC-V relaxations and changes to internal linkage for internal function and global symbols. See also: https://github.com/llvm/llvm-project/issues/167381#issuecomment-3513830043 Signed-off-by: xermicus <cyrill@parity.io>	2025-11-11 17:27:53 +01:00
				`@@ -0,0 +1 @@`
				`This file makes sure that Github Pages doesn't process mdBook's output.`