gh-131372: Configurable build-details.json name (#150098)

* Configurable build-details.json name

Linux distributions that co-install multiple Python versions in the same
path (e.g. multiarch on Debian, debug builds, and free-threading) need a
way to place multiple build-details.jsons side-by-side.

PEP-739 is being updated [0] to recommend renaming in this situation. To
ensure some standardization, this PR generates appropriate names for
distributions that need to use this feature.

[0]: https://github.com/python/peps/pull/4889

* NEWS entry

* Document configure option and add to whatsnew

diff --git a/Doc/using/configure.rst b/Doc/using/configure.rst
index 5e67d0120c89e02b15b4c34952239d920e14fc00..22a10db976c4fc629fc8edacacacf72122ebe0b1 100644 (file)
--- a/Doc/using/configure.rst
+++ b/Doc/using/configure.rst
@@ -473,6 +473,15 @@ General Options
 
    .. versionadded:: 3.15
 
+.. option:: --with-build-details-suffix=[yes|SUFFIX]
+
+   Rename ``build-details.json`` to permit multiple co-located Python
+   installs. If a custom ``SUFFIX`` is supplied it is used verbatim,
+   otherwise one will be generated from the ``MULTIARCH`` tag with
+   ``-free-threading`` and ``-debug``, as appropriate.
+
+   .. versionadded:: 3.16
+
 
 C compiler options
 ------------------

diff --git a/Doc/whatsnew/3.16.rst b/Doc/whatsnew/3.16.rst
index f1ff4fcf9bafde0919648c2059502b40c135a5b7..8dac804b9519dad24c341b54751aacf76e2001ed 100644 (file)
--- a/Doc/whatsnew/3.16.rst
+++ b/Doc/whatsnew/3.16.rst
@@ -227,6 +227,12 @@ Build changes
 
   .. _libmpdec: https://www.bytereef.org/mpdecimal/
 
+* Add a :option:`--with-build-details-suffix` configure flag to allow
+  Linux distributions that co-install multiple versions of Python in the
+  same tree to avoid ``build-details.json`` clashes.
+
+  (Contributed by Stefano Rivera in :gh:`131372`.)
+
 
 C API changes
 =============

diff --git a/Makefile.pre.in b/Makefile.pre.in
index e8b44c4b874e95407ac569f23775160d102727fd..ea15726a2de548afd6bd8e785549f259279db9bc 100644 (file)
--- a/Makefile.pre.in
+++ b/Makefile.pre.in
@@ -215,6 +215,8 @@ MACOSX_DEPLOYMENT_TARGET=@CONFIGURE_MACOSX_DEPLOYMENT_TARGET@
 # the build, and is only listed here so it will be included in sysconfigdata.
 IPHONEOS_DEPLOYMENT_TARGET=@IPHONEOS_DEPLOYMENT_TARGET@
 
+BUILD_DETAILS=@BUILD_DETAILS@
+
 # Option to install to strip binaries
 STRIPFLAG=-s
 
@@ -774,11 +776,11 @@ list-targets:
 
 .PHONY: build_all
 build_all:     check-clean-src check-app-store-compliance $(BUILDPYTHON) platform sharedmods \
-               gdbhooks Programs/_testembed scripts checksharedmods rundsymutil build-details.json
+               gdbhooks Programs/_testembed scripts checksharedmods rundsymutil $(BUILD_DETAILS)
 
 .PHONY: build_wasm
 build_wasm: check-clean-src $(BUILDPYTHON) platform sharedmods \
-               python-config checksharedmods build-details.json
+               python-config checksharedmods $(BUILD_DETAILS)
 
 .PHONY: build_emscripten
 build_emscripten: build_wasm web_example web_example_pyrepl_jspi
@@ -979,8 +981,8 @@ pybuilddir.txt: $(PYTHON_FOR_BUILD_DEPS)
                exit 1 ; \
        fi
 
-build-details.json: pybuilddir.txt
-       $(RUNSHARED) $(PYTHON_FOR_BUILD) $(srcdir)/Tools/build/generate-build-details.py `cat pybuilddir.txt`/build-details.json
+$(BUILD_DETAILS): pybuilddir.txt
+       $(RUNSHARED) $(PYTHON_FOR_BUILD) $(srcdir)/Tools/build/generate-build-details.py `cat pybuilddir.txt`/$(BUILD_DETAILS)
 
 # Build static library
 $(LIBRARY): $(LIBRARY_OBJS)
@@ -2349,7 +2351,7 @@ multissltest: all
 # Only the main install gets a build-details.json.
 .PHONY: install
 install: @FRAMEWORKINSTALLFIRST@ @INSTALLTARGETS@ @FRAMEWORKINSTALLLAST@
-       $(INSTALL_DATA) `cat pybuilddir.txt`/build-details.json $(DESTDIR)$(LIBDEST); \
+       $(INSTALL_DATA) `cat pybuilddir.txt`/$(BUILD_DETAILS) $(DESTDIR)$(LIBDEST); \
        if test "x$(ENSUREPIP)" != "xno"  ; then \
                case $(ENSUREPIP) in \
                        upgrade) ensurepip="--upgrade" ;; \

diff --git a/Misc/NEWS.d/next/Build/2026-05-19-12-45-23.gh-issue-131372.oJykeB.rst b/Misc/NEWS.d/next/Build/2026-05-19-12-45-23.gh-issue-131372.oJykeB.rst
new file mode 100644 (file)
index 0000000..912f413
--- /dev/null
+++ b/Misc/NEWS.d/next/Build/2026-05-19-12-45-23.gh-issue-131372.oJykeB.rst
@@ -0,0 +1,3 @@
+Add a :option:`--with-build-details-suffix` configure flag to allow Linux
+distributions that co-install multiple versions of Python in the same tree
+to avoid ``build-details.json`` clashes.

diff --git a/configure b/configure
index 00e3ca25c86e8f9633e8b542887e14c8ac57255b..1377b1eff4d2026714d7ad34da403de1b732ea62 100755 (executable)
--- a/configure
+++ b/configure
@@ -828,6 +828,7 @@ MODULE__IO_FALSE
 MODULE__IO_TRUE
 MODULE_BUILDTYPE
 _PYTHREAD_NAME_MAXLEN
+BUILD_DETAILS
 TEST_MODULES
 OPENSSL_LDFLAGS
 OPENSSL_LIBS
@@ -1154,6 +1155,7 @@ with_openssl_rpath
 with_ssl_default_suites
 with_builtin_hashlib_hashes
 enable_test_modules
+with_build_details_suffix
 '
       ac_precious_vars='build_alias
 host_alias
@@ -1989,6 +1991,10 @@ Optional Packages:
   --with-builtin-hashlib-hashes=md5,sha1,sha2,sha3,blake2
                           builtin hash modules, md5, sha1, sha2, sha3 (with
                           shake), blake2
+  --with-build-details-suffix=
+                          rename build-details.json to permit multiple
+                          colocated Python installs; optionally specify a
+                          custom suffix (default: no)
 
 Some influential environment variables:
   PKG_CONFIG  path to pkg-config utility
@@ -31732,6 +31738,50 @@ fi
 printf "%s\n" "$TEST_MODULES" >&6; }
 
 
+# Check for --with-build-details-suffix
+BUILD_DETAILS=build-details.json
+
+# Check whether --with-build-details-suffix was given.
+if test ${with_build_details_suffix+y}
+then :
+  withval=$with_build_details_suffix;
+    { printf "%s\n" "$as_me:${as_lineno-$LINENO}: checking for --with-build-details-suffix" >&5
+printf %s "checking for --with-build-details-suffix... " >&6; }
+    if test "x$with_build_detials_suffix" = xno
+then :
+  as_fn_error $? "invalid --with-build-details-suffix option: expected custom suffix or \"yes\", not \"no\"" "$LINENO" 5
+
+fi
+    if test "x$with_build_details_suffix" = xyes
+then :
+
+        colocated_install=yes
+        threading_suffix=""
+        if [ "$ABI_THREAD" = "t" ]; then
+          threading_suffix=-free-threading
+        fi
+        debug_suffix=""
+        if [ "$Py_DEBUG" = "true" ]; then
+          debug_suffix=-debug
+        fi
+        BUILD_DETAILS=build-details.$MULTIARCH$threading_suffix$debug_suffix.json
+
+else case e in #(
+  e)
+        BUILD_DETAILS=build-details.$with_build_details_suffix.json
+
+     ;;
+esac
+fi
+
+
+fi
+
+{ printf "%s\n" "$as_me:${as_lineno-$LINENO}: result: $with_build_details_suffix" >&5
+printf "%s\n" "$with_build_details_suffix" >&6; }
+BUILD_DETAILS=$BUILD_DETAILS
+
+
 # gh-109054: Check if -latomic is needed to get <pyatomic.h> atomic functions.
 # On Linux aarch64, GCC may require programs and libraries to be linked
 # explicitly to libatomic. Call _Py_atomic_or_uint64() which may require

diff --git a/configure.ac b/configure.ac
index bb2a7eee9a116e333e10f8a842d2f3f5438798f2..0c339c3c3a3a01310d91095c27c530f0098af026 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -7840,6 +7840,40 @@ AC_ARG_ENABLE([test-modules],
 AC_MSG_RESULT([$TEST_MODULES])
 AC_SUBST([TEST_MODULES])
 
+# Check for --with-build-details-suffix
+BUILD_DETAILS=build-details.json
+AC_ARG_WITH([build-details-suffix],
+  [AS_HELP_STRING(
+    [--with-build-details-suffix=],
+    [rename build-details.json to permit multiple colocated Python installs; optionally specify a custom suffix (default: no)]
+  )],
+  [
+    AC_MSG_CHECKING([for --with-build-details-suffix])
+    AS_VAR_IF(
+      [with_build_detials_suffix], [no],
+      [AC_MSG_ERROR([invalid --with-build-details-suffix option: expected custom suffix or "yes", not "no"])]
+    )
+    AS_VAR_IF(
+      [with_build_details_suffix], [yes], [
+        colocated_install=yes
+        threading_suffix=""
+        if [[ "$ABI_THREAD" = "t" ]]; then
+          threading_suffix=-free-threading
+        fi
+        debug_suffix=""
+        if [[ "$Py_DEBUG" = "true" ]]; then
+          debug_suffix=-debug
+        fi
+        BUILD_DETAILS=build-details.$MULTIARCH$threading_suffix$debug_suffix.json
+      ], [
+        BUILD_DETAILS=build-details.$with_build_details_suffix.json
+      ]
+    )
+  ]
+)
+AC_MSG_RESULT([$with_build_details_suffix])
+AC_SUBST([BUILD_DETAILS], [$BUILD_DETAILS])
+
 # gh-109054: Check if -latomic is needed to get <pyatomic.h> atomic functions.
 # On Linux aarch64, GCC may require programs and libraries to be linked
 # explicitly to libatomic. Call _Py_atomic_or_uint64() which may require