From d6ccd114a075dc69b96fd2c0f2e12e2f7d02fcf9 Mon Sep 17 00:00:00 2001
From: haochengxia <xhc_1007@163.com>
Date: Tue, 25 Aug 2026 00:56:37 -0600
Subject: [PATCH 1/2] fix: align cmake flags

---
 CMakeLists.txt | 34 +++++++++++++++++++++-------------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 5c06757..4e49b70 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -29,18 +29,23 @@ set(CMAKE_POSITION_INDEPENDENT_CODE ON)
 set(BASE_C_FLAGS "-fPIC -fno-strict-overflow -fno-strict-aliasing")
 set(BASE_CXX_FLAGS "-fPIC -fno-strict-overflow -fno-strict-aliasing")
 
-# Compiler-specific flags
+# Compiler-specific flags.
 if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
-    set(COMPILER_SPECIFIC_FLAGS "-Wno-cast-user-defined -Wno-array-bounds -Wno-type-limits")
-elseif(CMAKE_CXX_COMPILER_ID STREQUAL "Clang")
-    set(COMPILER_SPECIFIC_FLAGS "-Wno-array-bounds")
+    set(COMPILER_SPECIFIC_C_FLAGS "-Wno-array-bounds -Wno-type-limits")
+    set(COMPILER_SPECIFIC_CXX_FLAGS "-Wno-cast-user-defined ${COMPILER_SPECIFIC_C_FLAGS}")
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+    # GLCache/segment.c stores INT64_MAX into a double field; AppleClang 21 flags the
+    # value change as -Wimplicit-const-int-float-conversion and -Werror makes it fatal.
+    set(COMPILER_SPECIFIC_C_FLAGS "-Wno-array-bounds -Wno-implicit-const-int-float-conversion")
+    set(COMPILER_SPECIFIC_CXX_FLAGS "${COMPILER_SPECIFIC_C_FLAGS}")
 else()
-    set(COMPILER_SPECIFIC_FLAGS "")
+    set(COMPILER_SPECIFIC_C_FLAGS "")
+    set(COMPILER_SPECIFIC_CXX_FLAGS "")
 endif()
 
 # Apply flags
-set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${BASE_C_FLAGS}")
-set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_FLAGS}")
+set(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${BASE_C_FLAGS} ${COMPILER_SPECIFIC_C_FLAGS}")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_CXX_FLAGS}")
 
 # =============================================================================
 # Git Submodule Management
@@ -80,13 +85,16 @@ endif()
 function(build_libcachesim)
     message(STATUS "Building libCacheSim...")
     
-    # Prepare CMake arguments for subproject
+    # Prepare CMake arguments for subproject.
+    # The C flags carry the compiler-specific suppressions too: libCacheSim is mostly
+    # C, and passing them only to the C++ compiler left its C sources exposed to
+    # upstream's -Werror.
     set(CMAKE_ARGS
-        "-DCMAKE_C_FLAGS=${BASE_C_FLAGS}"
-        "-DCMAKE_CXX_FLAGS=${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_FLAGS}"
-        "-DCMAKE_CXX_FLAGS_DEBUG=-g ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_FLAGS}"
-        "-DCMAKE_CXX_FLAGS_RELEASE=-O3 ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_FLAGS}"
-        "-DCMAKE_CXX_FLAGS_RELWITHDEBINFO=-O2 -g -DNDEBUG ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_FLAGS}"
+        "-DCMAKE_C_FLAGS=${BASE_C_FLAGS} ${COMPILER_SPECIFIC_C_FLAGS}"
+        "-DCMAKE_CXX_FLAGS=${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_CXX_FLAGS}"
+        "-DCMAKE_CXX_FLAGS_DEBUG=-g ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_CXX_FLAGS}"
+        "-DCMAKE_CXX_FLAGS_RELEASE=-O3 ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_CXX_FLAGS}"
+        "-DCMAKE_CXX_FLAGS_RELWITHDEBINFO=-O2 -g -DNDEBUG ${BASE_CXX_FLAGS} ${COMPILER_SPECIFIC_CXX_FLAGS}"
     )
     
     # Configure libCacheSim

From b4416e538957ab6164c3a1853cc650043ceac230 Mon Sep 17 00:00:00 2001
From: haochengxia <xhc_1007@163.com>
Date: Wed, 26 Aug 2026 23:21:11 -0600
Subject: [PATCH 2/2] require macos15

---
 .github/workflows/pypi-release.yml          | 2 +-
 docs/src/en/getting_started/installation.md | 6 ++++++
 docs/src/zh/getting_started/installation.md | 5 +++++
 pyproject.toml                              | 4 ++--
 4 files changed, 14 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/pypi-release.yml b/.github/workflows/pypi-release.yml
index 0960f47..c3bd44f 100644
--- a/.github/workflows/pypi-release.yml
+++ b/.github/workflows/pypi-release.yml
@@ -16,7 +16,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest]
+        os: [ubuntu-latest, macos-15]
 
     steps:
     - uses: actions/checkout@v4
diff --git a/docs/src/en/getting_started/installation.md b/docs/src/en/getting_started/installation.md
index 9958bb9..996eb51 100644
--- a/docs/src/en/getting_started/installation.md
+++ b/docs/src/en/getting_started/installation.md
@@ -10,6 +10,12 @@
 
 Windows is not supported.
 
+!!! note "macOS wheels"
+    The published macOS wheels are Apple Silicon (arm64) only and require **macOS 15 or
+    newer**. They bundle Homebrew libraries, which are built for the macOS version of the
+    release runner and set that floor. On an Intel Mac or an older macOS, `pip` falls back
+    to [building from source](#install-from-source).
+
 ## Install from PyPI
 
 Pre-built wheels are published to [PyPI](https://pypi.org/project/libcachesim/), so in most
diff --git a/docs/src/zh/getting_started/installation.md b/docs/src/zh/getting_started/installation.md
index f5aa296..a6d8c52 100644
--- a/docs/src/zh/getting_started/installation.md
+++ b/docs/src/zh/getting_started/installation.md
@@ -10,6 +10,11 @@
 
 不支持 Windows。
 
+!!! note "关于 macOS wheel"
+    发布的 macOS wheel 仅面向 Apple Silicon（arm64），且要求 **macOS 15 及以上**。这些 wheel
+    捆绑了 Homebrew 的动态库，而 Homebrew 只为发布机所用的 macOS 版本构建这些库，因此下限由此
+    决定。在 Intel Mac 或更旧的 macOS 上，`pip` 会回退到“从源码安装”。
+
 ## 从 PyPI 安装
 
 我们已将预编译的 wheel 发布到 [PyPI](https://pypi.org/project/libcachesim/)，因此大多数情况下无需编译器：
diff --git a/pyproject.toml b/pyproject.toml
index 6f6dc36..cdc433b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -65,7 +65,7 @@ build-dir = "build"
 [tool.scikit-build.cmake]
 build-type = "Release"
 args = ["-G", "Ninja"]
-define = { CMAKE_OSX_DEPLOYMENT_TARGET = "11.0" }
+define = { CMAKE_OSX_DEPLOYMENT_TARGET = "15.0" }
 version = ">=3.15"
 source-dir = "."
 
@@ -83,7 +83,7 @@ skip = ["*-win32", "*-manylinux_i686", "*-musllinux*", "pp*"]
 # Set the environment variable for the wheel build step.
 # NOTE(haocheng): we enable all the optional features for the wheel build.
 # And MACOSX_DEPLOYMENT_TARGET should be kept in sync with [tool.scikit-build.cmake].define.CMAKE_OSX_DEPLOYMENT_TARGET
-environment = { LCS_BUILD_DIR = "{project}/src/libCacheSim/build", MACOSX_DEPLOYMENT_TARGET = "11.0", CMAKE_ARGS = "-DENABLE_3L_CACHE=ON -DENABLE_GLCACHE=ON -DENABLE_LRB=ON" }
+environment = { LCS_BUILD_DIR = "{project}/src/libCacheSim/build", MACOSX_DEPLOYMENT_TARGET = "15.0", CMAKE_ARGS = "-DENABLE_3L_CACHE=ON -DENABLE_GLCACHE=ON -DENABLE_LRB=ON" }
 
 # Test that the wheel can be imported
 test-command = "python -c 'import libcachesim; print(\"Import successful\")'; cp -r {project}/tests .; python -m pytest tests/ -v -m 'not optional'; python -m pytest tests/ -v -m 'optional'"