Building zvec from Source on Bleeding-Edge Linux (GCC 15 / Python 3.14)

[aashish-thapa]

I am just documenting (what i did) on how to build zvec from source on systems with newer toolchains (e.g., Arch Linux with GCC 15 and Python 3.14) where the default pip install . fails due to C++ compilation incompatibilities in third-party dependencies.

The Problem

zvec officially supports Python 3.10-3.12 and its bundled C++ dependencies (RocksDB 8.1.1, antlr4, etc.) don't compile with GCC 15. You'll see errors like:

• RocksDB: Type mismatches (uint32_t vs int) in trace_record.h / trace_record.cc
• antlr4: CMAKE_POLICY(SET ... OLD) rejected by newer CMake
• General: -Wno-unqualified-std-cast-call unrecognized warning flag

Prerequisites

• Docker (recommended) or an older GCC (13/14)
• pyenv (for managing Python versions)
• Git

Step 1: Install pyenv and Python 3.12

Install pyenv

curl https://pyenv.run | bash

Add to your ~/.zshrc (or ~/.bashrc):

# pyenv
export PYENV_ROOT="$HOME/.pyenv"
[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init - zsh)"  # Use "bash" instead of "zsh" if using bash

Note: Make sure pyenv init - has a space before the shell name: pyenv init - zsh, NOT pyenv init -zsh.

Reload your shell:

source ~/.zshrc

Install Python 3.12

pyenv install 3.12.12

The tkinter warning during installation is harmless and can be ignored.

Step 2: Patch antlr4 CMakeLists (Required)

Newer CMake versions reject CMAKE_POLICY(SET ... OLD) directives. Edit thirdparty/antlr/antlr4/runtime/Cpp/CMakeLists.txt and change the OLD policies to NEW:

 if(CMAKE_VERSION VERSION_EQUAL "3.0.0" OR
    CMAKE_VERSION VERSION_GREATER "3.0.0")
   CMAKE_POLICY(SET CMP0026 NEW)
-  CMAKE_POLICY(SET CMP0054 OLD)
-  CMAKE_POLICY(SET CMP0045 OLD)
-  CMAKE_POLICY(SET CMP0042 OLD)
+  CMAKE_POLICY(SET CMP0054 NEW)
+  CMAKE_POLICY(SET CMP0045 NEW)
+  CMAKE_POLICY(SET CMP0042 NEW)
 endif()

 if(CMAKE_VERSION VERSION_EQUAL "3.3.0" OR
    CMAKE_VERSION VERSION_GREATER "3.3.0")
-  CMAKE_POLICY(SET CMP0059 OLD)
-  CMAKE_POLICY(SET CMP0054 OLD)
+  CMAKE_POLICY(SET CMP0059 NEW)
+  CMAKE_POLICY(SET CMP0054 NEW)
 endif()

Step 3: Build the Wheel with Docker

Using Docker avoids all GCC 15 issues — the python:3.12 image ships with GCC 14 which compiles everything cleanly.

Clean any previous build artifacts

# If build/ exists and has root-owned files from a previous Docker build:
docker run --rm -v $(pwd):/src python:3.12 rm -rf /src/build /src/dist

# Otherwise:
rm -rf build/ dist/

Build the wheel

docker run --rm \
  -v $(pwd):/src \
  -w /src \
  python:3.12 bash -c '
    git config --global --add safe.directory "*"
    pip wheel . -w /src/dist/ -v
  '

This will take several minutes (1098 compilation units). The resulting .whl file will be in dist/.

Fix file permissions

Docker creates files as root. Fix ownership:

docker run --rm -v $(pwd):/src python:3.12 chown -R "$(id -u):$(id -g)" /src/dist /src/build

Step 4: Install the Wheel

Create a Python 3.12 virtual environment and install:

# Create venv with Python 3.12 from pyenv
~/.pyenv/versions/3.12.12/bin/python3.12 -m venv .venv

# Activate
source .venv/bin/activate

# Install the built wheel
pip install dist/zvec-*.whl

Step 5: Verify

source .venv/bin/activate
python -c "import zvec; print(zvec.__version__)"

Expected output:

0.2.1.dev5

Alternative: Build Without Docker (GCC 13/14)

If you prefer not to use Docker, install an older GCC alongside your system GCC:

# Arch Linux (AUR)
yay -S gcc13

# Build with the older compiler
~/.pyenv/versions/3.12.12/bin/python3.12 -m venv .venv
source .venv/bin/activate
CC=gcc-13 CXX=g++-13 pip install .

Your system GCC 15 remains the default — gcc-13/g++-13 are only used for this build.

Troubleshooting

Issue	Cause	Fix
CMakeCache.txt directory ... is different	Stale build cache from a previous build with different paths	Delete build/ directory
dubious ownership in repository	Docker runs as root, git detects owner mismatch	git config --global --add safe.directory "*" inside container
zsh: command not found: pyenv	Missing PATH setup or wrong pyenv init syntax	Ensure pyenv init - zsh has a space before zsh
not a supported wheel on this platform	Trying to install cp312 wheel in a Python 3.14 environment	Make sure your venv uses Python 3.12, not the system Python
tkinter warning during pyenv install	Missing Tk development libraries	Safe to ignore — not needed for zvec

Environment Tested

• OS: Arch Linux (kernel 6.18.6)
• System GCC: 15.2.1
• System Python: 3.14.2
• Docker image: python:3.12 (Debian, GCC 14.2.0)
• Build Python: 3.12.12 (via pyenv)
• zvec version: 0.2.1.dev5