feat(wheels): add configurable build tag hook for wheel filenames

docs/customization.md

@@ -393,6 +393,88 @@ $ tox -e cli -- canonicalize flit-core
 flit_core
 ```
 
+## Global settings
+
+Global settings are configured in the `settings.yaml` file passed via the
+`--settings-file` flag. These settings apply to all packages being built.
+
+### Wheel build tag hook
+
+The `build_tag_hook` is a configuration option that allows you to customize
+wheel filenames by appending configuration-specific suffixes to the build tag.
+This is useful for creating unique, deterministic filenames that reflect the
+build configuration and distinguish wheels built for different variants.
+
+Configure the hook in your global `settings.yaml`:
+
+```yaml
+wheels:
+  build_tag_hook: "myproject.hooks:build_tag_hook"
+```
+
+The hook function receives keyword-only arguments and returns a sequence of
+suffix segments (strings) to append to the wheel build tag:
+
+```python
+from typing import Sequence
+from packaging.requirements import Requirement
+from packaging.version import Version
+from packaging.tags import Tag
+
+from fromager import context
+
+
+def build_tag_hook(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    version: Version,
+    wheel_tags: frozenset[Tag],
+) -> Sequence[str]:
+    """Return suffix segments for the wheel build tag.
+
+    The segments are joined with underscores and appended to the numeric
+    build tag. For example, returning ["cpu"] produces the build tag:
+    {numeric_base}_cpu, while returning ["gpu", "cuda"] produces
+    {numeric_base}_gpu_cuda.
+
+    The hook must return identical suffix segments when called with the same
+    configuration, ensuring that wheels built on different machines with the
+    same build configuration have identical filenames. This allows wheel caches
+    to work correctly across builders.
+
+    Args:
+        ctx: The build context, containing variant and settings information
+        req: The package requirement being built
+        version: The version being built
+        wheel_tags: Frozenset of wheel tags (use to distinguish platform-specific
+                   wheels from pure-python wheels; don't use for platform decisions)
+
+    Returns:
+        A sequence of suffix segments (alphanumeric + dots only).
+        Must not return a single string or bytes object.
+
+    Raises:
+        ValueError: If segments contain invalid characters or types
+    """
+    # Example: Return variant-specific suffix
+    return [ctx.variant]
+```
+
+**Important notes:**
+
+- The hook is only invoked when the package has a non-empty build tag from
+  its changelog entry. Pure-python packages without a build tag skip the hook.
+- Each segment must contain only alphanumeric ASCII characters or dots
+  (`[a-zA-Z0-9.]`). Invalid characters cause a build error.
+- The hook must be deterministic and independent of wheel contents, build
+  environment, or ELF metadata, so that fresh builds and cache lookups
+  produce identical tags.
+- Use `wheel_tags` only to distinguish platform-specific wheels (`platlib`)
+  from pure-python wheels (`py3-none-any`). Don't use it for platform-specific
+  decisions—the hook must return identical results across architectures for
+  the same variant.
+
 ## Process hooks
 
 Fromager supports plugging in Python hooks to be run after build events.

docs/reference/config-reference.rst

@@ -96,3 +96,5 @@ If you prefer managing a single settings file, per-package settings can also be
 kept in this file.
 
 .. autopydantic_model:: fromager.packagesettings.SettingsFile
+
+.. autopydantic_model:: fromager.packagesettings.WheelSettings

src/fromager/bootstrapper/_cache.py

@@ -86,22 +86,27 @@ def _look_for_existing_wheel(
     search_in: pathlib.Path,
 ) -> tuple[pathlib.Path | None, pathlib.Path | None]:
     pbi = ctx.package_build_info(req)
-    expected_build_tag = pbi.build_tag(resolved_version)
+    base_build_tag = pbi.build_tag(resolved_version)
     logger.info(
-        f"looking for existing wheel for version {resolved_version} with build tag {expected_build_tag} in {search_in}"
+        f"looking for existing wheel for version {resolved_version} with build tag {base_build_tag} in {search_in}"
     )
     wheel_filename = finders.find_wheel(
         downloads_dir=search_in,
         req=req,
         dist_version=str(resolved_version),
-        build_tag=expected_build_tag,
+        build_tag=base_build_tag,
     )
     if not wheel_filename:
         return None, None
-    _, _, build_tag, _ = wheels.extract_info_from_wheel_file(req, wheel_filename)
-    if expected_build_tag and expected_build_tag != build_tag:
+    _, _, actual_build_tag, wheel_tags = wheels.extract_info_from_wheel_file(
+        req, wheel_filename
+    )
+    expected_build_tag = wheels.get_build_tag(
+        ctx=ctx, req=req, version=resolved_version, wheel_tags=wheel_tags
+    )
+    if expected_build_tag and expected_build_tag != actual_build_tag:
         logger.info(
-            f"found wheel for {resolved_version} in {wheel_filename} but build tag does not match. Got {build_tag} but expected {expected_build_tag}"
+            f"found wheel for {resolved_version} in {wheel_filename} but build tag does not match. Got {actual_build_tag} but expected {expected_build_tag}"
         )
         return None, None
     logger.info(f"found existing wheel {wheel_filename}")
@@ -129,16 +134,20 @@ def _download_wheel_from_cache(
         results = resolver.find_all_matching_from_provider(provider, pinned_req)
         wheel_url, _ = results[0]
         wheelfile_name = pathlib.Path(urlparse(wheel_url).path)
+        _, _, actual_build_tag, wheel_tags = wheels.extract_info_from_wheel_file(
+            req, wheelfile_name
+        )
         pbi = ctx.package_build_info(req)
-        expected_build_tag = pbi.build_tag(resolved_version)
+        expected_build_tag = wheels.get_build_tag(
+            ctx=ctx, req=req, version=resolved_version, wheel_tags=wheel_tags
+        )
         logger.info(f"has expected build tag {expected_build_tag}")
         changelogs = pbi.get_changelog(resolved_version)
         logger.debug(f"has change logs {changelogs}")
 
-        _, _, build_tag, _ = wheels.extract_info_from_wheel_file(req, wheelfile_name)
-        if expected_build_tag and expected_build_tag != build_tag:
+        if expected_build_tag and expected_build_tag != actual_build_tag:
             logger.info(
-                f"found wheel for {resolved_version} in cache but build tag does not match. Got {build_tag} but expected {expected_build_tag}"
+                f"found wheel for {resolved_version} in cache but build tag does not match. Got {actual_build_tag} but expected {expected_build_tag}"
             )
             return None, None
 

src/fromager/commands/build.py

@@ -485,11 +485,25 @@ def _is_wheel_built(
             wheel_server_urls=wheel_server_urls,
         )
         logger.info("found candidate wheel %s", url)
-        pbi = wkctx.package_build_info(req)
-        build_tag_from_settings = pbi.build_tag(resolved_version)
-        build_tag = build_tag_from_settings if build_tag_from_settings else (0, "")
         wheel_basename = downloads.extract_filename_from_url(url)
-        _, _, build_tag_from_name, _ = parse_wheel_filename(wheel_basename)
+        _, _, build_tag_from_name, wheel_tags = parse_wheel_filename(wheel_basename)
+    except Exception:
+        logger.debug(
+            "could not locate prebuilt wheel %s-%s on %s",
+            dist_name,
+            resolved_version,
+            wheel_server_urls,
+            exc_info=True,
+        )
+        logger.info("could not locate prebuilt wheel")
+        return None
+    else:
+        # Compute expected build tag in the else clause so hook
+        # validation errors propagate instead of being swallowed.
+        expected_tag = wheels.get_build_tag(
+            ctx=wkctx, req=req, version=resolved_version, wheel_tags=wheel_tags
+        )
+        build_tag = expected_tag if expected_tag else (0, "")
         existing_build_tag = build_tag_from_name if build_tag_from_name else (0, "")
         if (
             existing_build_tag[0] > build_tag[0]
@@ -513,21 +527,20 @@ def _is_wheel_built(
                 wheel_filename = None
 
         if not wheel_filename:
-            # if the found wheel was on an external server, then download it
-            logger.info("downloading wheel from %s", url)
-            wheel_filename = wheels.download_wheel(req, url, wkctx.wheels_downloads)
+            try:
+                logger.info("downloading wheel from %s", url)
+                wheel_filename = wheels.download_wheel(req, url, wkctx.wheels_downloads)
+            except Exception:
+                logger.debug(
+                    "failed to download prebuilt wheel %s-%s",
+                    dist_name,
+                    resolved_version,
+                    exc_info=True,
+                )
+                logger.info("could not download prebuilt wheel")
+                return None
 
         return wheel_filename
-    except Exception:
-        logger.debug(
-            "could not locate prebuilt wheel %s-%s on %s",
-            dist_name,
-            resolved_version,
-            wheel_server_urls,
-            exc_info=True,
-        )
-        logger.info("could not locate prebuilt wheel")
-        return None
 
 
 def _build_parallel(

src/fromager/finders.py

@@ -162,30 +162,27 @@ def find_wheel(
     """
     filename_prefix = _dist_name_to_filename(req.name)
     canonical_name = canonicalize_name(req.name)
-    # if build tag is 0 then we can ignore to handle non tagged wheels for backward compatibility
-    candidate_bases_build_tag = f"{build_tag[0]}{build_tag[1]}-" if build_tag else ""
 
-    candidate_bases = set(
-        [
-            # First check if the file is there using the canonically
-            # transformed name.
-            f"{filename_prefix}-{dist_version}-{candidate_bases_build_tag}",
-            # If that didn't work, try the canonical dist name. That's not
-            # "correct" but we do see it. (charset-normalizer-3.3.2-
-            # and setuptools-scm-8.0.4-) for example
-            f"{canonical_name}-{dist_version}-{candidate_bases_build_tag}",
-            # If *that* didn't work, try the dist name we've been
-            # given as a dependency. That's not "correct", either but we do
-            # see it. (oslo.messaging-14.7.0-) for example
-            f"{req.name}-{dist_version}-{candidate_bases_build_tag}",
-            # Sometimes the sdist uses '.' instead of '-' in the
-            # package name portion.
-            f"{req.name.replace('-', '.')}-{dist_version}-{candidate_bases_build_tag}",
-        ]
-    )
-    # Case-insensitive globbing was added to Python 3.12, but we
-    # have to run with older versions, too, so do our own name
-    # comparison.
+    build_tag_prefixes: list[str] = []
+    if build_tag:
+        build_tag_prefixes.append(f"{build_tag[0]}{build_tag[1]}-")
+        if not build_tag[1]:
+            build_tag_prefixes.append(f"{build_tag[0]}_")
+    else:
+        build_tag_prefixes.append("")
+
+    name_variants = [
+        filename_prefix,
+        canonical_name,
+        req.name,
+        req.name.replace("-", "."),
+    ]
+
+    candidate_bases: set[str] = set()
+    for name in name_variants:
+        for btp in build_tag_prefixes:
+            candidate_bases.add(f"{name}-{dist_version}-{btp}")
+
     for base in candidate_bases:
         logger.debug('looking for wheel as "%s"', base)
         for filename in downloads_dir.glob("*.whl"):

src/fromager/packagesettings/__init__.py

@@ -12,6 +12,7 @@
     ResolverDist,
     SbomSettings,
     VariantInfo,
+    WheelSettings,
 )
 from ._pbi import PackageBuildInfo
 from ._resolver import (
@@ -88,6 +89,7 @@
     "Variant",
     "VariantChangelog",
     "VariantInfo",
+    "WheelSettings",
     "default_update_extra_environ",
     "get_extra_environ",
     "pep440_tag_matcher",

src/fromager/packagesettings/_models.py

@@ -33,6 +33,48 @@
 logger = logging.getLogger(__name__)
 
 
+class WheelSettings(pydantic.BaseModel):
+    """Global wheel build settings
+
+    ::
+
+      wheels:
+        build_tag_hook: "mypackage.hooks:build_tag_hook"
+
+    .. versionadded:: 0.95.0
+    """
+
+    model_config = MODEL_CONFIG
+
+    build_tag_hook: pydantic.ImportString[typing.Callable[..., typing.Any]] | None = (
+        None
+    )
+    """Callable that returns suffix segments for the wheel build tag.
+
+    The callable receives keyword-only arguments ``ctx``, ``req``,
+    ``version``, and ``wheel_tags`` and returns
+    ``Sequence[str]`` of suffix segments.
+
+    Only invoked when the package already has a non-empty build tag
+    from its changelog entry for the given version; otherwise the hook
+    is skipped and no build tag is added.  The callable must be
+    deterministic and independent of wheel contents, build environment,
+    or ELF metadata so fresh builds and cache lookups compute the same
+    tag.
+
+    .. note::
+
+       The ``wheel_tags`` argument should only be used to distinguish
+       platlib wheels (platform-specific) from purelib wheels
+       (``py3-none-any``), for example to skip environment suffixes on
+       pure-python packages.  Do not use it for platform-specific
+       decisions -- the hook must produce identical results across
+       architectures for the same variant.
+
+    .. versionadded:: 0.95.0
+    """
+
+
 class SbomSettings(pydantic.BaseModel):
     """Global SBOM generation settings
 

src/fromager/packagesettings/_settings.py

@@ -13,7 +13,7 @@
 from pydantic import Field
 
 from .. import overrides
-from ._models import ExternalCommands, PackageSettings, SbomSettings
+from ._models import ExternalCommands, PackageSettings, SbomSettings, WheelSettings
 from ._pbi import PackageBuildInfo
 from ._typedefs import MODEL_CONFIG, GlobalChangelog, Package, Variant
 
@@ -55,6 +55,14 @@ class SettingsFile(pydantic.BaseModel):
     .. versionadded:: 0.92.0
     """
 
+    wheels: WheelSettings | None = None
+    """Wheel build settings
+
+    Configures wheel build tag hooks and other wheel-specific options.
+
+    .. versionadded:: 0.95.0
+    """
+
     @classmethod
     def from_string(
         cls,
@@ -193,6 +201,16 @@ def external_commands(self) -> ExternalCommands:
         """
         return self._settings.external_commands
 
+    @property
+    def build_tag_hook(self) -> typing.Callable[..., typing.Any] | None:
+        """Get the wheel build tag hook callable, or None if not configured.
+
+        .. versionadded:: 0.95.0
+        """
+        if self._settings.wheels is None:
+            return None
+        return self._settings.wheels.build_tag_hook
+
     def variant_changelog(self) -> list[str]:
         """Get global changelog for current variant"""
         return list(self._settings.changelog.get(self.variant, []))