feat(packagesettings): add ${__version__} template variable to env settings

Inject the resolved package version into template_env as __version__,
so package env settings can reference it via ${__version__}.

Closes: #946

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Lalatendu Mohanty <lmohanty@redhat.com>

Author: LalatenduMohanty

docs/customization.md

@@ -215,9 +215,86 @@ implemented. A literal `$` must be quoted as `$$`.
 Added support for default value syntax `${NAME:-}`.
 ```
 
+```{versionchanged} 0.76.0
+
+Added the `${__version__}` template variable.
+```
+
+#### The `__version__` variable
+
+When fromager resolves the version of a package it injects the version
+string into the template environment as `__version__`. You can
+reference it in env values with `${__version__}`.
+
+##### Fixing setuptools-scm / flit_scm builds
+
+Packages that use `setuptools-scm` or `flit_scm` for version detection fail
+when built from source archives without `.git` metadata. The build backend
+raises a `LookupError` during import because it cannot determine the version.
+
+Setting `SETUPTOOLS_SCM_PRETEND_VERSION_FOR_{DIST_NAME}` tells
+setuptools-scm to use the provided version instead of reading from SCM.
+This is checked before any `.git` or `PKG-INFO` lookup, so the error is
+avoided entirely.
+
+Use the **per-package** form with the distribution name normalized to
+uppercase with hyphens, dots, and underscores replaced by a single `_`
+(adapted [PEP 503](https://peps.python.org/pep-0503/) semantics). For
+example, for a package named `foo`:
+
+```yaml
+env:
+    SETUPTOOLS_SCM_PRETEND_VERSION_FOR_FOO: "${__version__}"
+```
+
+The per-package form is
+[preferred by setuptools-scm](https://setuptools-scm.readthedocs.io/en/latest/config/)
+over the generic `SETUPTOOLS_SCM_PRETEND_VERSION`, which can leak into
+other setuptools-scm packages in the same build environment.
+
+This is simpler than writing a custom `prepare_source` plugin override
+to inject version metadata.
+
+##### Availability
+
+`__version__` is set for `build_sdist`, `build_wheel`, and all
+dependency hooks (`get_build_backend_dependencies`,
+`get_build_sdist_dependencies`, etc.) that run *after* version
+resolution.
+
+It is **not** available:
+
+- During the `resolve` phase itself — the version has not yet been
+  determined.
+- When bootstrapping from a **git URL whose reference is not a valid
+  PEP 440 version** (for example
+  `pkg @ git+https://host/repo.git` or
+  `pkg @ git+https://host/repo.git@main`). In this case fromager
+  must build the package metadata just to discover the version, so
+  the early dependency-resolution hooks run with `version=None`.
+
+If your env var is used in a phase where the version might be
+unknown, add a fallback default so the substitution does not fail:
+
+```yaml
+env:
+    # safe — falls back to empty string when version is not yet known
+    MY_VAR: "${__version__:-}"
+```
+
+Without the fallback, a bare `${__version__}` raises an error when
+the version is unavailable.
+
+##### Examples
+
 ```yaml
-# example
 env:
+    # fix setuptools-scm builds from source archives (use per-package form)
+    SETUPTOOLS_SCM_PRETEND_VERSION_FOR_FOO: "${__version__}"
+    # use the resolved package version in a download URL
+    LIB_URL: "https://github.com/org/lib/archive/v${__version__}.tar.gz"
+    # safe for git-URL bootstrapping where version may not yet be known
+    OPTIONAL_URL: "https://example.com/lib-${__version__:-latest}.tar.gz"
     # pre-pend '/global/bin' to PATH
     PATH: "/global/bin:$PATH"
     # default CFLAGS to empty string and append " -g"

e2e/ci_bootstrap_suite.sh

@@ -29,5 +29,6 @@ run_test "bootstrap_sdist_only"
 test_section "bootstrap git URL tests"
 run_test "bootstrap_git_url"
 run_test "bootstrap_git_url_tag"
+run_test "version_env_git_url"
 
 finish_suite

e2e/stevedore_override/src/package_plugins/stevedore.py

@@ -23,6 +23,11 @@ def update_extra_environ(
     marker = ctx.work_dir / "update_extra_environ.txt"
     with marker.open(encoding="utf-8", mode="a") as f:
         f.write(f"{version}\n")
+    version_var = extra_environ.get("TEST_VERSION_VAR")
+    if version_var is not None:
+        version_var_marker = ctx.work_dir / "test_version_var.txt"
+        with version_var_marker.open(encoding="utf-8", mode="w") as f:
+            f.write(f"{version_var}\n")
     return None
 
 

e2e/test_pep517_build_sdist.sh

@@ -38,18 +38,20 @@ fromager \
     --wheels-repo "$OUTDIR/wheels-repo" \
     step prepare-build --wheel-server-url "https://pypi.org/simple/" "$DIST" "$VERSION"
 
-# Build an updated sdist
+# Build an updated sdist (with settings that exercise ${__version__} in env)
 rm -rf "$OUTDIR/sdists-repo/builds"
 fromager \
     --log-file "$OUTDIR/build-logs/${DIST}-build-sdist.log" \
     --work-dir "$OUTDIR/work-dir" \
     --sdists-repo "$OUTDIR/sdists-repo" \
     --wheels-repo "$OUTDIR/wheels-repo" \
+    --settings-dir="$SCRIPTDIR/version_env_settings" \
     step build-sdist "$DIST" "$VERSION"
 
 EXPECTED_FILES="
 $OUTDIR/sdists-repo/builds/stevedore-*.tar.gz
 $OUTDIR/work-dir/update_extra_environ.txt
+$OUTDIR/work-dir/test_version_var.txt
 "
 
 pass=true
@@ -60,6 +62,13 @@ for pattern in $EXPECTED_FILES; do
   fi
 done
 
+# Verify ${__version__} was correctly substituted in the env var
+actual_version=$(cat "$OUTDIR/work-dir/test_version_var.txt" | tr -d '[:space:]')
+if [ "$actual_version" != "$VERSION" ]; then
+  echo "FAIL: TEST_VERSION_VAR='$actual_version', expected '$VERSION'" 1>&2
+  pass=false
+fi
+
 $pass
 
 twine check $OUTDIR/sdists-repo/builds/*.tar.gz

e2e/test_version_env_git_url.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+# -*- indent-tabs-mode: nil; tab-width: 2; sh-indentation: 2; -*-
+
+# Test that ${__version__} in env settings fails when bootstrapping from
+# a git URL without a PEP 440 version tag, and succeeds when a fallback
+# default is provided via ${__version__:-...}.
+
+SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+source "$SCRIPTDIR/common.sh"
+
+GIT_REPO_URL="https://github.com/python-wheel-build/stevedore-test-repo.git"
+
+pass=true
+
+# --- Part 1: ${__version__} WITHOUT default should fail ---
+
+echo "=== Part 1: expect failure with \${__version__} (no default) ==="
+
+if fromager \
+    --log-file="$OUTDIR/bootstrap-no-default.log" \
+    --error-log-file="$OUTDIR/fromager-errors-no-default.log" \
+    --sdists-repo="$OUTDIR/sdists-repo" \
+    --wheels-repo="$OUTDIR/wheels-repo" \
+    --work-dir="$OUTDIR/work-dir" \
+    --settings-dir="$SCRIPTDIR/version_env_settings_no_default" \
+    bootstrap "stevedore @ git+${GIT_REPO_URL}" 2>&1; then
+  echo "FAIL: bootstrap with \${__version__} (no default) should have failed" 1>&2
+  pass=false
+else
+  echo "OK: bootstrap with \${__version__} (no default) failed as expected"
+  if grep -q "__version__" "$OUTDIR/fromager-errors-no-default.log" 2>/dev/null || \
+     grep -q "__version__" "$OUTDIR/bootstrap-no-default.log" 2>/dev/null; then
+    echo "OK: error message mentions __version__"
+  else
+    echo "WARN: error log does not mention __version__; check logs manually"
+  fi
+fi
+
+# --- Part 2: ${__version__:-unresolved} WITH default should succeed ---
+
+echo "=== Part 2: expect success with \${__version__:-unresolved} ==="
+
+rm -rf "$OUTDIR/work-dir" "$OUTDIR/sdists-repo" "$OUTDIR/wheels-repo"
+mkdir -p "$OUTDIR/build-logs"
+
+fromager \
+    --log-file="$OUTDIR/bootstrap-with-default.log" \
+    --error-log-file="$OUTDIR/fromager-errors-with-default.log" \
+    --sdists-repo="$OUTDIR/sdists-repo" \
+    --wheels-repo="$OUTDIR/wheels-repo" \
+    --work-dir="$OUTDIR/work-dir" \
+    --settings-dir="$SCRIPTDIR/version_env_settings_with_default" \
+    bootstrap "stevedore @ git+${GIT_REPO_URL}"
+
+EXPECTED_FILES="
+$OUTDIR/wheels-repo/downloads/stevedore-*.whl
+$OUTDIR/sdists-repo/builds/stevedore-*.tar.gz
+"
+
+for pattern in $EXPECTED_FILES; do
+  if [ ! -f "${pattern}" ]; then
+    echo "FAIL: Did not find $pattern" 1>&2
+    pass=false
+  fi
+done
+
+$pass

e2e/version_env_settings/stevedore.yaml

@@ -0,0 +1,2 @@
+env:
+    TEST_VERSION_VAR: "${__version__}"

e2e/version_env_settings_no_default/stevedore.yaml

@@ -0,0 +1,2 @@
+env:
+    TEST_VERSION_VAR: "${__version__}"

e2e/version_env_settings_with_default/stevedore.yaml

@@ -0,0 +1,2 @@
+env:
+    TEST_VERSION_VAR: "${__version__:-unresolved}"

src/fromager/packagesettings.py

@@ -899,6 +899,13 @@ def get_extra_environ(
         else:
             template_env = template_env.copy()
 
+        if version is not None:
+            template_env["__version__"] = str(version)
+        else:
+            # Prevent a stray __version__ in os.environ from being
+            # silently used when the real version is unknown.
+            template_env.pop("__version__", None)
+
         # configure max jobs settings, settings depend on package, available
         # CPU cores, and available virtual memory.
         jobs = self.parallel_jobs()