docs(getting_started,fill): add solc instructions for arm64 users with fill issues (#1217)

* docs(getting_started,fill): added solc building instructions for arm64 users with fill issues

* Clarified instructions

Co-authored-by: danceratopz <[email protected]>

* Clarified instructions

Co-authored-by: danceratopz <[email protected]>

* Clarified that we refer to Linux ARM, not to macOS

Co-authored-by: danceratopz <[email protected]>

* Update docs/getting_started/installation.md

Co-authored-by: danceratopz <[email protected]>

---------

Co-authored-by: danceratopz <[email protected]>
Co-authored-by: Mario Vega <[email protected]>

Author: 3 people

docs/getting_started/installation.md

@@ -22,16 +22,27 @@ The latest version of `uv` can be installed via `curl` (recommended; can self-up
 
 If installed via `curl`, `uv` will download Python for your target platform if one of the required versions (Python 3.10, 3.11 or 3.12) is not available natively.
 
-## Installation
+## Installation Commands
 
-Clone [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) and install its dependencies:
+Clone [execution-spec-tests](https://github.com/ethereum/execution-spec-tests) and install its dependencies.
 
-```console
-git clone https://github.com/ethereum/execution-spec-tests
-cd execution-spec-tests
-uv sync --all-extras
-uv run solc-select use 0.8.24 --always-install
-```
+=== "All x86-64 platforms and ARM64 macOS"
+
+    ```console
+    git clone https://github.com/ethereum/execution-spec-tests
+    cd execution-spec-tests
+    uv sync --all-extras
+    uv run solc-select use 0.8.24 --always-install
+    ```
+
+=== "ARM64 Linux"
+
+    ```console
+    git clone https://github.com/ethereum/execution-spec-tests
+    cd execution-spec-tests
+    uv sync --all-extras
+    ```
+    Then follow [this guide](./installation_troubleshooting.md#problem-exception-failed-to-compile-yul-source) to build the `solc` binary from source and copy it to the expected location.
 
 ## Installation Troubleshooting
 

docs/getting_started/installation_troubleshooting.md

@@ -36,6 +36,8 @@ This page provides guidance on how to troubleshoot common issues that may arise
 
 ## Problem: `solc` Installation issues
 
+### Problem: `CERTIFICATE_VERIFY_FAILED`
+
 !!! danger "Problem: `Failed to install solc ... CERTIFICATE_VERIFY_FAILED`"
     When running either `uv run solc-select use 0.8.24 --always-install` or `fill` you encounter the following error:
 
@@ -62,6 +64,32 @@ This page provides guidance on how to troubleshoot common issues that may arise
         /Applications/Python\ 3.11/Install\ Certificates.command
         ```
 
+### Problem: `Exception: failed to compile yul source`
+
+!!! danger "Problem: `Running fill fails with tests that contain yul source code` on ARM platforms"
+    If you're using `x86_64`, try to manually run `solc-select` to install the required version of the `solc` binary:
+
+    ```shell
+    uv run solc-select use 0.8.24 --always-install
+    ```
+
+    Otherwise, this can happen when you're using an ARM64 OS but followed the x86-64 installation guide.
+    To resolve the issue you must build solidity from source (avoid 0.8.24 as it might require building z3 from source as well).
+
+!!! success "Solution: Build solc from source"
+    The following steps have been tested on Ubuntu 24.04.2 LTS ARM64:
+    ```bash
+    git clone --branch v0.8.28 --depth 1 https://github.com/ethereum/solidity.git
+    cd solidity && mkdir build && cd build
+    sudo apt install build-essential libboost-all-dev z3
+    cmake ..
+    make
+    mv $HOME/Documents/execution-spec-tests/.venv/bin/solc $HOME/Documents/execution-spec-tests/.venv/bin/solc-x86-64
+    cp ./solc/solc $HOME/Documents/execution-spec-tests/.venv/bin/
+    chmod +x $HOME/Documents/execution-spec-tests/.venv/bin/solc
+    ```
+    Running `uv run solc --version` should now return the expected version. Verify that `fill` works by running `uv run fill -m yul_test` in the execution-spec-tests root folder.
+
 ## Problem: `ValueError: unsupported hash type ripemd160`
 
 !!! danger "Problem: `Running fill fails with tests that use the RIPEMD160 precompile (0x03)`"

whitelist.txt

@@ -277,6 +277,7 @@ listdir
 lll
 lllc
 london
+LTS
 macOS
 mainnet
 makefiles