Validate git tags availability before setuptools-scm runs

Add pre-build validation that checks git tag availability directly to ensure
builds fail early with clear error messages before setuptools-scm silently
falls back to version '0.1.x'.

Changes:
- cuda_bindings/setup.py: Validate tags at import time (before setuptools-scm)
- cuda_core/build_hooks.py: Validate tags in _build_cuda_core() before building
- cuda_pathfinder/build_hooks.py: New custom build backend that validates tags
  before delegating to setuptools.build_meta
- cuda_pathfinder/pyproject.toml: Configure custom build backend

Benefits:
- Fails immediately when pip install -e . is run, not during build
- More direct: tests what setuptools-scm actually needs (git describe)
- Cleaner: no dependency on generated files
- Better UX: clear error messages with actionable fixes

Error messages include:
- Clear explanation of the problem
- The actual git error output
- Common causes (tags not fetched, wrong directory, etc.)
- Package-specific debugging commands
- Actionable fix: git fetch --tags

Author: rwgk

cuda_bindings/setup.py

@@ -23,6 +23,69 @@
 from setuptools.command.editable_wheel import _TopLevelFinder, editable_wheel
 from setuptools.extension import Extension
 
+
+# ----------------------------------------------------------------------
+# Validate git tags are available (fail early before setuptools-scm runs)
+def _validate_git_tags_available():
+    """Verify that git tags are available for setuptools-scm version detection."""
+    import subprocess
+
+    # Check if git is available
+    try:
+        subprocess.run(["git", "--version"], capture_output=True, check=True, timeout=5)  # noqa: S607
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        raise RuntimeError(
+            "Git is not available in PATH. setuptools-scm requires git to determine version from tags.\n"
+            "Please ensure git is installed and available in your PATH."
+        ) from None
+
+    # Check if we're in a git repository
+    try:
+        subprocess.run(
+            ["git", "rev-parse", "--git-dir"],  # noqa: S607
+            capture_output=True,
+            check=True,
+            timeout=5,
+        )
+    except subprocess.CalledProcessError:
+        raise RuntimeError(
+            "Not in a git repository. setuptools-scm requires git tags to determine version.\n"
+            "Please run this from within the cuda-python git repository."
+        ) from None
+
+    # Check if git describe works (this is what setuptools-scm uses)
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--long", "--match", "v*[0-9]*"],  # noqa: S607
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"git describe failed! This means setuptools-scm will fall back to version '0.1.x'.\n"
+                f"\n"
+                f"Error: {result.stderr.strip()}\n"
+                f"\n"
+                f"This usually means:\n"
+                f"  1. Git tags are not fetched (run: git fetch --tags)\n"
+                f"  2. Running from wrong directory (setuptools_scm root='..')\n"
+                f"  3. No matching tags found\n"
+                f"\n"
+                f"To fix:\n"
+                f"  git fetch --tags\n"
+                f"\n"
+                f"To debug, run: git describe --tags --long --match 'v*[0-9]*'"
+            ) from None
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(
+            "git describe command timed out. This may indicate git repository issues.\n"
+            "Please check your git repository state."
+        ) from None
+
+
+_validate_git_tags_available()
+
 # ----------------------------------------------------------------------
 # Fetch configuration options
 

cuda_core/build_hooks.py

@@ -86,6 +86,52 @@ def _determine_cuda_major_version() -> str:
 
 
 def _build_cuda_core():
+    # Validate git tags are available (fail early before setuptools-scm runs)
+    import subprocess
+
+    # Check if git is available
+    try:
+        subprocess.run(["git", "--version"], capture_output=True, check=True, timeout=5)  # noqa: S607
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        raise RuntimeError(
+            "Git is not available in PATH. setuptools-scm requires git to determine version from tags.\n"
+            "Please ensure git is installed and available in your PATH."
+        ) from None
+
+    # Find git repository root (setuptools_scm root='..')
+    repo_root = os.path.dirname(os.path.dirname(__file__))
+
+    # Check if git describe works (this is what setuptools-scm uses)
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--long", "--match", "cuda-core-v*[0-9]*"],  # noqa: S607
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"git describe failed! This means setuptools-scm will fall back to version '0.1.x'.\n"
+                f"\n"
+                f"Error: {result.stderr.strip()}\n"
+                f"\n"
+                f"This usually means:\n"
+                f"  1. Git tags are not fetched (run: git fetch --tags)\n"
+                f"  2. Running from wrong directory (setuptools_scm root='..')\n"
+                f"  3. No matching tags found\n"
+                f"\n"
+                f"To fix:\n"
+                f"  git fetch --tags\n"
+                f"\n"
+                f"To debug, run: git describe --tags --long --match 'cuda-core-v*[0-9]*'"
+            ) from None
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(
+            "git describe command timed out. This may indicate git repository issues.\n"
+            "Please check your git repository state."
+        ) from None
+
     # Customizing the build hooks is needed because we must defer cythonization until cuda-bindings,
     # now a required build-time dependency that's dynamically installed via the other hook below,
     # is installed. Otherwise, cimport any cuda.bindings modules would fail!

cuda_pathfinder/build_hooks.py

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Custom build hooks for cuda-pathfinder.
+
+This module validates git tags are available before setuptools-scm runs,
+ensuring proper version detection during pip install. All PEP 517 build
+hooks are delegated to setuptools.build_meta.
+"""
+
+import os
+import subprocess
+
+
+# Validate tags before importing setuptools.build_meta (which will use setuptools-scm)
+def _validate_git_tags_available():
+    """Verify that git tags are available for setuptools-scm version detection."""
+    # Check if git is available
+    try:
+        subprocess.run(["git", "--version"], capture_output=True, check=True, timeout=5)  # noqa: S607
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        raise RuntimeError(
+            "Git is not available in PATH. setuptools-scm requires git to determine version from tags.\n"
+            "Please ensure git is installed and available in your PATH."
+        ) from None
+
+    # Find git repository root (setuptools_scm root='..')
+    repo_root = os.path.dirname(os.path.dirname(__file__))
+
+    # Check if git describe works (this is what setuptools-scm uses)
+    try:
+        result = subprocess.run(
+            ["git", "describe", "--tags", "--long", "--match", "cuda-pathfinder-v*[0-9]*"],  # noqa: S607
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(
+                f"git describe failed! This means setuptools-scm will fall back to version '0.1.x'.\n"
+                f"\n"
+                f"Error: {result.stderr.strip()}\n"
+                f"\n"
+                f"This usually means:\n"
+                f"  1. Git tags are not fetched (run: git fetch --tags)\n"
+                f"  2. Running from wrong directory (setuptools_scm root='..')\n"
+                f"  3. No matching tags found\n"
+                f"\n"
+                f"To fix:\n"
+                f"  git fetch --tags\n"
+                f"\n"
+                f"To debug, run: git describe --tags --long --match 'cuda-pathfinder-v*[0-9]*'"
+            ) from None
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(
+            "git describe command timed out. This may indicate git repository issues.\n"
+            "Please check your git repository state."
+        ) from None
+
+
+# Validate tags before any build operations
+_validate_git_tags_available()
+
+# Import and re-export all PEP 517 hooks from setuptools.build_meta
+from setuptools.build_meta import *  # noqa: F403, E402

cuda_pathfinder/pyproject.toml

@@ -70,7 +70,8 @@ requires = [
     "setuptools_scm[simple]>=8",
     "wheel"
 ]
-build-backend = "setuptools.build_meta"
+build-backend = "build_hooks"
+backend-path = ["."]
 
 [tool.setuptools_scm]
 root = ".."