fix(build): accept GCC 12 for CUDA 12 compatibility (#1019)

* fix(build): accept GCC 12 for CUDA 12 compatibility, update docs

The supraseal build.sh hard-required GCC 13, creating an impossible
build situation for CUDA 12.0–12.5 users (nvcc rejects GCC 13, but
build.sh rejects GCC 12).

The supraseal codebase only uses C++17 features — no GCC 13-specific
code. The GCC 13 requirement was a CI environment decision (Ubuntu 24.04
default), not a code requirement.

Changes:
- build.sh: accept both GCC 12 and GCC 13, prefer 13 then fall back to 12
- supraseal.md: document CUDA/GCC version pairing requirements
- installation.md: update dependency notes for GCC 12/13 and CUDA versions

CUDA / GCC compatibility (per NVIDIA docs):
  CUDA 12.0–12.5 → GCC up to 12.x
  CUDA 12.6+     → GCC up to 13.2
  CUDA 13.0+     → GCC 13+

* docs: fix wording — batch sealing (not supraseal) in build note title

Author: Reiers

documentation/en/installation.md

@@ -53,17 +53,15 @@ You will need the following software installed to install and run Curio.
 Building Curio requires some system dependencies, usually provided by your distribution.
 
 {% hint style="warning" %}
-**Note (batch sealing now builds by default on Linux):** Curio’s Linux build chain now always builds `extern/supraseal` as part of the normal `make deps/build` flow. This means **building Curio on Linux requires batch sealing build dependencies**, including:
+**Note (batch sealing now builds by default on Linux):** Curio's Linux build now compiles `extern/supraseal` as part of the standard `make build` flow (needed for SnapDeals fast TreeR and batch sealing). This adds the following build requirements:
 
-- CUDA Toolkit **13.x or newer** (needs `nvcc`, even if you won’t run batch sealing at runtime)
-- GCC **13** toolchain (`gcc-13` / `g++-13`)
-- Python venv tooling (`python3-venv`) and common build tools (`autoconf`, `automake`, `libtool`, `nasm`, `xxd`, etc.)
+- **CUDA Toolkit 12.x or later** (`nvcc` must be in PATH)
+- **GCC 12 or 13** — pick the version your CUDA toolkit supports:
+  - CUDA 12.0–12.5 → `gcc-12`/`g++-12`
+  - CUDA 12.6+ or 13+ → `gcc-13`/`g++-13`
+- Python venv tooling (`python3-venv`) and build tools (`autoconf`, `automake`, `libtool`, `nasm`, `xxd`)
 
-If you’re troubleshooting whether your machine can run the **fast TreeR** path used by SnapDeals, run:
-
-```bash
-curio test supra system-info
-```
+To skip the supraseal build (e.g. if you don't have CUDA), use: `make build FFI_USE_OPENCL=1` or `make build DISABLE_SUPRASEAL=1`
 {% endhint %}
 
 Arch:
@@ -72,15 +70,14 @@ Arch:
 sudo pacman -Syu opencl-icd-loader gcc git jq pkg-config opencl-headers hwloc libarchive nasm xxd python python-pip python-virtualenv
 # For batch sealing builds (SnapDeals fast TreeR / batch sealing toolchain):
 sudo pacman -Syu cuda
-# GCC 13 may be required depending on your supraseal version; install via your distro/AUR as appropriate.
+# GCC 12 or 13 required — pick based on your CUDA version (see note above).
 ```
 
-Ubuntu 24.04 / Debian:
+Ubuntu/Debian:
 
 ```shell
 sudo apt install -y \
   mesa-opencl-icd ocl-icd-opencl-dev \
-  gcc-13 g++-13 \
   git jq pkg-config curl clang build-essential hwloc libhwloc-dev wget \
   python3 python3-dev python3-pip python3-venv \
   autoconf automake libtool \
@@ -90,8 +87,14 @@ sudo apt install -y \
   libgmp-dev libconfig++-dev \
   && sudo apt upgrade -y
 
-# CUDA Toolkit (batch sealing build requirement; needs nvcc)
-# Install via NVIDIA’s CUDA repository packages for your distro, or use `cuda-toolkit` packages if available.
+# GCC 12 or 13 — pick based on your CUDA version:
+#   CUDA 12.0–12.5: sudo apt install gcc-12 g++-12
+#   CUDA 12.6+/13+: sudo apt install gcc-13 g++-13
+# On older Ubuntu (e.g. 20.04) you may need the toolchain PPA:
+#   sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y && sudo apt update
+
+# CUDA Toolkit (needed for GPU proving and supraseal build; nvcc must be in PATH)
+# Install via NVIDIA's CUDA repository for your distro.
 ```
 
 Fedora:
@@ -131,7 +134,7 @@ wget -c https://go.dev/dl/go1.24.7.linux-amd64.tar.gz -O - | sudo tar -xz -C /us
 ```
 
 {% hint style="info" %}
-You’ll need to add `/usr/local/go/bin` to your path. For most Linux distributions you can run something like:
+You'll need to add `/usr/local/go/bin` to your path. For most Linux distributions you can run something like:
 
 ```shell
 echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc && source ~/.bashrc
@@ -258,13 +261,13 @@ This should output something like:
 /Library/Developer/CommandLineTools
 ```
 
-If this command returns a path, then you have Xcode already installed! You can [move on to installing dependencies with Homebrew](installation.md#homebrew). If the above command doesn’t return a path, install Xcode:
+If this command returns a path, then you have Xcode already installed! You can [move on to installing dependencies with Homebrew](installation.md#homebrew). If the above command doesn't return a path, install Xcode:
 
 ```shell
 xcode-select --install
 ```
 
-Next up is installing Curio’s dependencies using Homebrew.
+Next up is installing Curio's dependencies using Homebrew.
 
 ### **Homebrew**
 

documentation/en/supraseal.md

@@ -34,7 +34,7 @@ Curio’s web UI exposes this as the **CC Scheduler** page/tab.
 * NVMe drives with high IOPS (10-20M total IOPS recommended)
 * GPU for PC2 phase (NVIDIA RTX 3090 or better recommended)
 * 1GB hugepages configured (minimum 36 pages)
-* Ubuntu or compatible Linux distribution (**gcc-13 required**, doesn't need to be system-wide)
+* Ubuntu or compatible Linux distribution (**GCC 12 or 13 required**, doesn't need to be system-wide)
 * At least 256GB RAM, ALL MEMORY CHANNELS POPULATED
   * Without **all** memory channels populated sealing **performance will suffer drastically**
 * NUMA-Per-Socket (NPS) set to 1
@@ -132,11 +132,23 @@ Check that `HugePages_Free` is equal to 36, the kernel can sometimes use some of
 
 ### Dependencies
 
-CUDA 12.x is required, 11.x won't work. The build process depends on GCC 13.x system-wide or `gcc-13`/`g++-13` installed locally.
+CUDA 12.x or later is required (11.x won't work). The build process requires **GCC 12 or 13** — system-wide or as `gcc-12`/`g++-12` (or `gcc-13`/`g++-13`) installed locally.
 
-* On Arch install GCC 13 via your distro/AUR as appropriate
-* On Ubuntu/Debian install `gcc-13` and `g++-13` packages
+{% hint style="warning" %}
+**CUDA / GCC compatibility:** Your CUDA toolkit version determines which GCC it supports as a host compiler:
+* **CUDA 12.0–12.5:** supports GCC up to 12.x only → use `gcc-12`/`g++-12`
+* **CUDA 12.6+:** supports GCC up to 13.2 → either GCC 12 or 13 works
+* **CUDA 13.0+:** supports GCC 13+ → use `gcc-13`/`g++-13`
+
+If you get nvcc errors about unsupported compiler versions, check your CUDA/GCC pairing.
+{% endhint %}
+
+* On Arch install GCC 12 or 13 via your distro/AUR as appropriate
+* On Ubuntu/Debian install `gcc-12` and `g++-12` (or `gcc-13`/`g++-13`)
     ```shell
+    # For CUDA 12.0–12.5:
+    sudo apt install gcc-12 g++-12
+    # For CUDA 12.6+ or CUDA 13+:
     sudo apt install gcc-13 g++-13
     ```
 * In addtion to general build dependencies (listed on the [installation page](installation.md)), you need `libgmp-dev` and `libconfig++-dev`

extern/supraseal/build.sh

@@ -3,7 +3,6 @@
 # Copyright Supranational LLC
 
 set -e
-set -x
 
 SECTOR_SIZE="" # Compile for all sector sizes
 while getopts r flag
@@ -13,38 +12,57 @@ do
     esac
 done
 
-# Function to check GCC version - enforces GCC 13 for compatibility
+# Function to check GCC version - requires GCC 12 or 13 for C++17 compatibility.
+# The supraseal codebase uses C++17 features supported by both GCC 12 and 13.
+# CUDA toolkit compatibility determines which GCC version works with nvcc:
+#   - CUDA 12.0–12.5: supports GCC up to 12.x (nvcc rejects GCC 13)
+#   - CUDA 12.6+:     supports GCC up to 13.2
+#   - CUDA 13.0+:     supports GCC 13+
+# We accept both and let nvcc validate the pairing via -ccbin.
 check_gcc_version() {
     local gcc_version=$(gcc -dumpversion | cut -d. -f1)
-    local target_gcc_version=13
-    
-    # Check if default GCC is version 13
-    if [ "$gcc_version" -eq "$target_gcc_version" ]; then
+
+    # Accept system GCC 12 or 13 directly
+    if [ "$gcc_version" -ge 12 ] && [ "$gcc_version" -le 13 ]; then
         echo "Using GCC $gcc_version"
         return 0
     fi
-    
-    # If not GCC 13, try to find and use gcc-13
-    if command -v gcc-13 &> /dev/null && command -v g++-13 &> /dev/null; then
-        echo "Setting CC, CXX, and NVCC_PREPEND_FLAGS to use GCC 13 for compatibility."
-        export CC=gcc-13
-        export CXX=g++-13
-        export NVCC_PREPEND_FLAGS="-ccbin /usr/bin/g++-13"
-        return 0
-    fi
-    
-    # GCC 13 not found
-    echo "Error: GCC 13 is required but not found."
-    echo "Current GCC version: $gcc_version"
-    echo "Please install GCC 13:"
-    echo "  On Ubuntu/Debian: sudo apt-get install gcc-13 g++-13"
-    echo "  On Fedora: sudo dnf install gcc-13 gcc-c++-13"
+
+    # System GCC is outside 12-13 range; try to find gcc-13 or gcc-12
+    for v in 13 12; do
+        if command -v gcc-$v &> /dev/null && command -v g++-$v &> /dev/null; then
+            echo "Setting CC, CXX, and NVCC_PREPEND_FLAGS to use GCC $v."
+            export CC=gcc-$v
+            export CXX=g++-$v
+            export NVCC_PREPEND_FLAGS="-ccbin /usr/bin/g++-$v"
+            return 0
+        fi
+    done
+
+    # Neither found
+    echo ""
+    echo "=========================================="
+    echo "ERROR: GCC 12 or 13 is required but not found."
+    echo "=========================================="
+    echo ""
+    echo "  Current GCC version: $gcc_version"
+    echo ""
+    echo "  Please install GCC 12 or 13:"
+    echo "    Ubuntu/Debian:  sudo apt-get install gcc-13 g++-13"
+    echo "                or: sudo apt-get install gcc-12 g++-12"
+    echo "    Fedora:         sudo dnf install gcc-13 gcc-c++-13"
+    echo "                or: sudo dnf install gcc-12 gcc-c++-12"
+    echo ""
+    echo "  On older Ubuntu (e.g. 20.04), you may need the toolchain PPA first:"
+    echo "    sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y && sudo apt update"
+    echo ""
     exit 1
 }
 
 # Call the function to check GCC version
 check_gcc_version
 
+# Enable trace logging after the GCC check so error messages are readable
 set -x
 
 CC=${CC:-cc}
@@ -79,13 +97,16 @@ VENV_DIR="$(pwd)/.venv"
 if [ ! -d "$VENV_DIR" ] || [ ! -f "$VENV_DIR/bin/activate" ]; then
     echo "Creating Python virtual environment..."
     if ! python3 -m venv "$VENV_DIR"; then
-        echo "Error: python3-venv is required but not available."
-        echo "Please install it:"
-        echo "  On Ubuntu/Debian: sudo apt-get install python3-venv"
-        echo "  On Fedora: sudo dnf install python3-virtualenv"
+        PY_VER=$(python3 -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' 2>/dev/null || echo "3")
+        echo ""
+        echo "=========================================="
+        echo "ERROR: python3-venv is required but not available."
+        echo "=========================================="
+        echo ""
+        echo "  Ubuntu/Debian:  sudo apt-get install python3-venv"
+        echo "                  (on older Ubuntu, use: sudo apt-get install python${PY_VER}-venv)"
+        echo "  Fedora:         sudo dnf install python3-virtualenv"
         echo ""
-        echo "Or if you prefer, you can install dependencies manually:"
-        echo "  pip3 install --user meson ninja pyelftools"
         exit 1
     fi
 fi