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]: python/peps#4889

* NEWS entry

* Document configure option and add to whatsnew

Author: stefanor

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
 ------------------

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
 =============

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" ;; \

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.

configure

@@ -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