Add comments from configure.ac.

The original translation to conf_*.py lost some comments.  Add them
back.

Author: nascheme

Tools/configure/conf_buildopts.py

@@ -115,7 +115,7 @@
 
 
 def setup_disable_gil(v):
-    """Handle --disable-gil option."""
+    # Check for --disable-gil
     if DISABLE_GIL.process_bool(v):
         pyconf.define(
             "Py_GIL_DISABLED", 1, "Define if you want to disable the GIL"
@@ -125,7 +125,7 @@ def setup_disable_gil(v):
 
 
 def setup_pydebug(v):
-    """Handle --with-pydebug option."""
+    # Check for --with-pydebug
     if WITH_PYDEBUG.process_bool(v):
         pyconf.define(
             "Py_DEBUG",
@@ -136,7 +136,7 @@ def setup_pydebug(v):
 
 
 def setup_trace_refs(v):
-    """Handle --with-trace-refs option."""
+    # Check for --with-trace-refs
     WITH_TRACE_REFS.process_value(v)
 
     if WITH_TRACE_REFS.is_yes():
@@ -151,7 +151,7 @@ def setup_trace_refs(v):
 
 
 def setup_pystats(v):
-    """Handle --enable-pystats option."""
+    # Check for --enable-pystats
     ENABLE_PYSTATS.process_value(v)
 
     if ENABLE_PYSTATS.is_yes():
@@ -163,7 +163,7 @@ def setup_pystats(v):
 
 
 def setup_assertions(v):
-    """Handle --with-assertions option."""
+    # Check for --with-assertions (allows enabling assertions without Py_DEBUG)
     assertions_bool = WITH_ASSERTIONS.process_bool()
     v.assertions = "true" if assertions_bool else "false"
 
@@ -186,6 +186,7 @@ def setup_optimizations(v):
 
     if v.Py_OPT is True:
         if "-O0" in v.CFLAGS:
+            # Check for conflicting CFLAGS=-O0 and --enable-optimizations
             pyconf.warn(
                 "CFLAGS contains -O0 which may conflict with --enable-optimizations. "
                 "Consider removing -O0 from CFLAGS for optimal performance."
@@ -215,7 +216,7 @@ def setup_optimizations(v):
 
 
 def setup_experimental_jit(v):
-    """Handle --enable-experimental-jit, compiler-specific flags, NDEBUG, arch flags."""
+    # Handle --enable-experimental-jit, compiler-specific flags, NDEBUG, arch flags
     pyconf.checking("for --enable-experimental-jit")
     jit = ENABLE_EXPERIMENTAL_JIT.value
     if jit is None or jit is False or jit == "no":
@@ -256,13 +257,16 @@ def setup_experimental_jit(v):
     pyconf.result(f"{tier2_flags} {jit_flags}")
 
     if v.disable_gil and jit is not False:
+        # GH-133171: This configuration builds the JIT but never actually uses it,
+        # which is surprising (and strictly worse than not building it at all):
         pyconf.warn(
             "--enable-experimental-jit does not work correctly with --disable-gil."
         )
 
     if v.ac_cv_cc_name == "mpicc":
         pass
     elif v.ac_cv_cc_name == "icc":
+        # ICC needs -fp-model strict or floats behave badly
         v.CFLAGS_NODIST += " -fp-model strict"
     elif v.ac_cv_cc_name == "xlc":
         v.CFLAGS_NODIST += " -qalias=noansi -qmaxmem=-1"
@@ -275,10 +279,7 @@ def setup_experimental_jit(v):
 
 
 def check_jit_stencils(v):
-    # ---------------------------------------------------------------------------
     # JIT stencils header selection
-    # ---------------------------------------------------------------------------
-
     v.JIT_STENCILS_H = ""
     if ENABLE_EXPERIMENTAL_JIT.given and not ENABLE_EXPERIMENTAL_JIT.is_no():
         host = v.host
@@ -334,10 +335,7 @@ def setup_sanitizers(v):
 
 
 def check_tail_call_interp(v):
-    # ---------------------------------------------------------------------------
-    # --with-tail-call-interp
-    # ---------------------------------------------------------------------------
-
+    # Check for --with-tail-call-interp
     if WITH_TAIL_CALL_INTERP.is_yes():
         pyconf.define(
             "_Py_TAIL_CALL_INTERP",
@@ -353,10 +351,7 @@ def check_tail_call_interp(v):
 
 
 def check_remote_debug(v):
-    # ---------------------------------------------------------------------------
-    # --with-remote-debug
-    # ---------------------------------------------------------------------------
-
+    # Check for --with-remote-debug
     with_rd = WITH_REMOTE_DEBUG.value_or("yes")
     if with_rd == "yes":
         pyconf.define(
@@ -367,10 +362,7 @@ def check_remote_debug(v):
 
 
 def check_ensurepip(v):
-    # ---------------------------------------------------------------------------
-    # --with-ensurepip
-    # ---------------------------------------------------------------------------
-
+    # ensurepip option
     default_ensurepip = (
         False
         if v.ac_sys_system in ("Emscripten", "WASI", "iOS")
@@ -451,6 +443,8 @@ def setup_pymalloc(v):
     pyconf.checking("for --with-pymalloc-hugepages")
     with_pymalloc_hugepages = WITH_PYMALLOC_HUGEPAGES.value_or("no")
     if with_pymalloc_hugepages == "yes":
+        # configure only runs on Unix-like systems; Windows uses MEM_LARGE_PAGES
+        # via VirtualAlloc but does not use configure. Only check MAP_HUGETLB here.
         if pyconf.compile_check(
             preamble="#include <sys/mman.h>",
             body="int flags = MAP_PRIVATE | MAP_ANONYMOUS | MAP_HUGETLB;\n"
@@ -487,7 +481,7 @@ def setup_valgrind(v):
 
 
 def setup_dtrace(v):
-    """Handle --with-dtrace option."""
+    # Handle --with-dtrace option
     with_dtrace = WITH_DTRACE.process_value(None)
 
     v.export("DTRACE", "")
@@ -505,7 +499,13 @@ def setup_dtrace(v):
         )
         v.DTRACE_HEADERS = "Include/pydtrace_probes.h"
 
-        # Check if DTrace probes require linking (ELF generation via -G flag)
+        # On OS X, DTrace providers do not need to be explicitly compiled and
+        # linked into the binary. Correspondingly, dtrace(1) is missing the ELF
+        # generation flag '-G'. We check for presence of this flag, rather than
+        # hardcoding support by OS, in the interest of robustness.
+        #
+        # NetBSD DTrace requires the -x nolibs flag to avoid system library conflicts
+        # and uses header generation for testing instead of object generation.
         pyconf.checking("whether DTrace probes require linking")
         ac_cv_dtrace_link = False
         host = v.host
@@ -529,13 +529,14 @@ def setup_dtrace(v):
         if ac_cv_dtrace_link:
             v.DTRACE_OBJS = "Python/pydtrace.o"
 
-        # NetBSD-specific DTrace flags
+        # Set NetBSD-specific DTrace flags in DFLAGS
         if "netbsd" in host.lower():
             v.DFLAGS += " -x nolibs"
 
 
 def setup_perf_trampoline(v):
-    """Check and configure perf trampoline support."""
+    # perf trampoline is Linux and macOS specific and requires an arch-specific
+    # trampoline in assembly
     pyconf.checking("perf trampoline")
     if v.PLATFORM_TRIPLET in ("x86_64-linux-gnu", "aarch64-linux-gnu"):
         perf_trampoline = True
@@ -557,6 +558,7 @@ def setup_perf_trampoline(v):
         )
         PERF_TRAMPOLINE_OBJ = "Python/asm_trampoline.o"
         if v.Py_DEBUG is True:
+            # perf needs frame pointers for unwinding, include compiler option in debug builds
             v.BASECFLAGS += (
                 " -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer"
             )

Tools/configure/conf_compiler.py

@@ -95,7 +95,7 @@ def setup_cxx(v):
 
 
 def setup_stack_direction(v):
-    """Determine stack growth direction."""
+    # Guess C stack growth direction
     v._Py_STACK_GROWS_DOWN = 0 if v.host.startswith("hppa") else 1
     pyconf.define(
         "_Py_STACK_GROWS_DOWN",
@@ -115,6 +115,8 @@ def check_compiler_bugs(v):
     # ---------------------------------------------------------------------------
     # glibc _FORTIFY_SOURCE / memmove bug
     # ---------------------------------------------------------------------------
+    # _FORTIFY_SOURCE wrappers for memmove and bcopy are incorrect:
+    # http://sourceware.org/ml/libc-alpha/2010-12/msg00009.html
 
     memmove_cflags = "-O2 -D_FORTIFY_SOURCE=2" if have_o2 else ""
     memmove_result = pyconf.run_check(
@@ -151,6 +153,9 @@ def check_compiler_bugs(v):
     # ---------------------------------------------------------------------------
     # GCC ipa-pure-const inline asm bug
     # ---------------------------------------------------------------------------
+    # Some versions of gcc miscompile inline asm:
+    # http://gcc.gnu.org/bugzilla/show_bug.cgi?id=46491
+    # http://gcc.gnu.org/ml/gcc/2010-11/msg00366.html
 
     if v.ac_cv_gcc_asm_for_x87 is True:
         if v.ac_cv_cc_name == "gcc":
@@ -190,6 +195,8 @@ def check_sign_extension_and_getc(v):
     # ---------------------------------------------------------------------------
     # Sign-extension / right-shift
     # ---------------------------------------------------------------------------
+    # Check whether right shifting a negative integer extends the sign bit
+    # or fills with zeros (like the Cray J90, according to Tim Peters).
 
     pyconf.checking("whether right shift extends the sign bit")
     ac_cv_rshift_extends_sign = pyconf.run_check(
@@ -208,6 +215,7 @@ def check_sign_extension_and_getc(v):
     # ---------------------------------------------------------------------------
     # getc_unlocked and friends
     # ---------------------------------------------------------------------------
+    # check for getc_unlocked and related locking functions
 
     pyconf.checking("for getc_unlocked() and friends")
     ac_cv_have_getc_unlocked = pyconf.link_check(
@@ -406,6 +414,7 @@ def check_compiler_characteristics(v):
     # ---------------------------------------------------------------------------
     # Compiler characteristics
     # ---------------------------------------------------------------------------
+    # checks for compiler characteristics
 
     pyconf.check_c_const()
 
@@ -433,10 +442,10 @@ def check_compiler_characteristics(v):
             "Define if your compiler supports function prototype",
         )
 
-    # socketpair
+    # check for socketpair
     pyconf.check_func("socketpair", includes=["sys/types.h", "sys/socket.h"])
 
-    # sockaddr.sa_len
+    # check if sockaddr has sa_len member
     pyconf.checking("if sockaddr has sa_len member")
     ac_cv_struct_sockaddr_sa_len = pyconf.compile_check(
         preamble="#include <sys/types.h>\n#include <sys/socket.h>",
@@ -454,6 +463,7 @@ def check_mbstowcs(v):
     # ---------------------------------------------------------------------------
     # mbstowcs bug check
     # ---------------------------------------------------------------------------
+    # Check for broken mbstowcs implementation
 
     if pyconf.run_check(
         "for broken mbstowcs",
@@ -484,6 +494,7 @@ def check_computed_gotos(v):
     # ---------------------------------------------------------------------------
     # --with-computed-gotos
     # ---------------------------------------------------------------------------
+    # Check for --with-computed-gotos
 
     if WITH_COMPUTED_GOTOS.is_yes():
         pyconf.define(
@@ -499,6 +510,7 @@ def check_computed_gotos(v):
         )
 
     # Runtime probe: does the C compiler support computed gotos?
+    # ac_cv_computed_gotos: check whether the C compiler supports computed gotos
     cg_result = pyconf.run_check(
         f"whether {v.CC} supports computed gotos",
         """
@@ -523,7 +535,7 @@ def check_computed_gotos(v):
 
 
 def check_stdatomic(v):
-    """Check for stdatomic.h and builtin atomic functions."""
+    # Check for stdatomic.h and builtin atomic functions (required for mimalloc)
     pyconf.checking("for stdatomic.h")
     ac_cv_header_stdatomic_h = pyconf.link_check(
         "#include <stdatomic.h>\n"
@@ -568,6 +580,7 @@ def check_stdatomic(v):
     # Check for __builtin_shufflevector with 128-bit vector support on an
     # architecture where it compiles to worthwhile native SIMD instructions.
     # Used for SIMD-accelerated bytes.hex() in Python/pystrhex.c.
+    # Check if compiler supports __builtin_shufflevector with 128-bit vector support
     pyconf.checking("for __builtin_shufflevector")
     ac_cv_efficient_builtin_shufflevector = pyconf.link_check(
         source=(
@@ -615,6 +628,7 @@ def check_sizes(v):
     pyconf.check_alignof("max_align_t")
     # AC_TYPE_LONG_DOUBLE: check that long double exists (sizeof >= sizeof(double))
     # autoconf uses <=, not >: "sizeof(double) <= sizeof(long double)"
+    # Check that the C compiler supports long double.
     if pyconf.compile_check(
         preamble="",
         body="typedef int test_array[1 - 2 * !(sizeof(double) <= sizeof(long double))];",
@@ -653,6 +667,7 @@ def check_sizes(v):
     elif v.ac_cv_pthread:
         v.CC = f"{v.CC} -pthread"
 
+    # if have pthread_t then define SIZEOF_PTHREAD_T
     ac_cv_have_pthread_t = pyconf.compile_check(
         preamble="#include <pthread.h>",
         body="pthread_t x; x = *(pthread_t*)0;",
@@ -661,6 +676,7 @@ def check_sizes(v):
         pyconf.check_sizeof("pthread_t", headers=["pthread.h"])
 
     pyconf.check_sizeof("pthread_key_t", headers=["pthread.h"])
+    # Check if pthread_key_t is compatible with int
     if pyconf.sizeof("pthread_key_t") == pyconf.sizeof(
         "int"
     ) and pyconf.compile_check(