Consider removing some unused build flags

[johnslavik]

Description

Tripped up by --with-readline in our configure file while debugging GH-142353, I was curious if we have any other unused build flags.

Removing them could slightly shorten preprocessing work, reduce cognitive load when debugging platform‑specific issues, and reduce the risk of accidentally relying on dead configuration paths.

After running make regen-configure, I put together this script with ripgrep:

# t.sh
FLAGS="$(rg '#\s*define\s+(\w+)' -g pyconfig.h -g pyconfig.h.in -or '$1' --no-line-number --no-filename)"
for flag in $FLAGS
do    
    rg "\b$flag\b" -g !pyconfig.h -g !pyconfig.h.in . --stats | rg '\b0 matches' -r "$flag"
done

Then I ran this command:

bash t.sh | sort | uniq

I got the following results:

Expand results

DIRENT
DONT_HAVE_SIG_ALARM
DONT_HAVE_SIG_PAUSE
HAVE_ACOSH
HAVE_ASINH
HAVE_ATANH
HAVE_ERF
HAVE_ERFC
HAVE_EXPM1
HAVE_INTPTR_T
HAVE_LIBSOCKET
HAVE_LOG1P
HAVE_LOG2
HAVE_PUTENV
HAVE_STRERROR
HAVE_UINTPTR_T
HAVE_X509_VERIFY_PARAM_SET1_HOST
Py_CONFIG_H
Py_NTDDI
_Py_PASTE_VERSION
Py_SOCKET_FD_CAN_BE_GE_FD_SETSIZE
_Py_STRINGIZE
_Py_STRINGIZE1
SIZEOF_HKEY
USE_SOCKET
_W64
WITH_READLINE
WORD_BIT

These macros are not referenced by any CPython source files outside configuration headers (pyconfig.h, PC/pyconfig.h and pyconfig.h.in files) and are not part of the documented public API.

A few of them are actually used and cannot be removed. Most of them, however, weren't used in years (or decades) and appear to be safely removable, because they no longer affect the behavior of Python.

Here's what I found about every single one of them.

PC/pyconfig.h and pyconfig.h

• HAVE_ERF, HAVE_ERFC

  Unused since 5839575.

PC/pyconfig.h

• DIRENT (gh-144228: Remove DIRENT build flag comment #144229)

  This is commented out:
  

  cpython/PC/pyconfig.h

  Lines 444 to 445 in e66597d

  	/* Define if you have dirent.h. */
  	/* #define DIRENT 1 */

  But we already have HAVE_DIRENT_H 1 for that:

  cpython/pyconfig.h.in

  Lines 290 to 292 in e66597d

  	/* Define to 1 if you have the <dirent.h> header file, and it defines 'DIR'.
  	*/
  	#undef HAVE_DIRENT_H

  which is used. Let's remove the DIRENT comment.

• DONT_HAVE_SIG_ALARM, DONT_HAVE_SIG_PAUSE (gh-144228: Remove DONT_HAVE_SIG_ALARM and DONT_HAVE_SIG_PAUSE build flags #144230)

  Superseded by HAVE_ALARM and HAVE_PAUSE since 1997, see 1171ee6.
  Removed from PC/os2vacpp/pyconfig.h in ab70e2a (when OS/2 support was dropped).

• USE_SOCKET (gh-144228: Remove USE_SOCKET build flag #144231)

  Unused since ab70e2a (when OS/2 support was dropped).

• HAVE_STRERROR (gh-144228: Remove HAVE_STRERROR build flag #144232)

  Last occurences removed in ab70e2a as well.
  This was meant to be removed in 2008 according to the description of ada8c3b:

  r61523 | brett.cannon | 2008-03-18 16:35:58 +0100 (Di, 18 Mär 2008) | 5 lines
    
  Remove all traces of HAVE_STRERROR.
    
  The removal of strerror.c led to the function check being removed from configure.in.
  

• HAVE_LIBSOCKET

  I'm not sure if it was or was not ever used, because I haven't bisected this.
  Seems unused at the moment.
  First added in 61fe861.

• HAVE_PUTENV (gh-144228: Remove HAVE_PUTENV build flag #144236)

  Unused since b8d1262 (when putenv() and unsetenv() became universally available).

• HAVE_X509_VERIFY_PARAM_SET1_HOST (gh-144228: Remove HAVE_X509_VERIFY_PARAM_SET1_HOST build flag #144235)

  Unused since 39258d3 (when OpenSSL was bumped to 1.1.1).

• SIZEOF_HKEY

  No longer used since 11fc411.

• WITH_READLINE

  Obsolete since 1997, see b06df27.
  The presence of this flag was very confusing to me when I was debugging Readline-reliant tests are not isolated from personal init files #142353.

pyconfig.h

• HAVE_ACOSH, HAVE_ASINH, HAVE_ATANH, HAVE_EXPM1, HAVE_LOG1P

  Unused since fa26245.

• HAVE_LOG2

  Unused since 5839575.

Ambiguous

Not touching these before I get additional feedback.
Consider them out of the scope of my proposal for now!

• HAVE_INTPTR_T, HAVE_UINTPTR_T (PC/pyconfig.h)

  Added in fe393f4, never used since. Maybe it's intentionally reserved for future use?

  cc: @zooba, @loewis, can this be removed?

• Py_SOCKET_FD_CAN_BE_GE_FD_SETSIZE (PC/pyconfig.h)

  Allowing this seems to have caused a stack corruption fixed in aa26b27. Since the fix, the flag has not been used.

  cc: @zooba, @cf-natali, can this be removed?

• WORD_BIT (PC/pyconfig.h)

  Standardized by POSIX.1 (IEEE Std 1003.1).

  Not sure if it should be in PC/.
  Maybe it is used downstream?

  cc: @zooba, @mhammond, do we need this in PC/pyconfig.h?

Still used or won't fix

• Py_CONFIG_H (PC/pyconfig.h)

  This was identified by the script, but it's an include guard.

• _W64 (PC/pyconfig.h)

  Used in PC/pyconfig.h to define Py_ssize_t.

• Py_NTDDI (PC/pyconfig)

  Used for defining NTDDI_VERSION.

• _Py_PASTE_VERSION (PC/pyconfig.h)

  Used for defining _Py_COMPILER.

• _Py_STRINGIZE, _Py_STRINGIZE1 (PC/pyconfig.h)

  I'd not touch these, as they are used for defining _Py_COMPILER.
  These correspond to Py_STRINGIFY and _Py_XSTRINGIFY from the pymacro.h header.
  Making PC/pyconfig.h include pymacro.h just for Py_STRINGIFY doesn't seem like a sensible option.

Conclusion

I'm going to start from PRs one per every item (grouping one or more related macros) in the bullet lists of flags certainly removable.

Going forward, I'll appreciate feedback about the ambiguous flags or any things that I've overlooked.

Are there any flags listed for removal that still have known downstream or platform‑specific uses? I pinged some changeset authors to help decide the most ambiguous cases.

Finally, I considered adding automated checks for unused configuration macros, but given the amount of variables involved, this seems non-trivial and not worth it.

Thanks for reading through all of this!

cc @vstinner @encukou I think you will have useful insights into this one.

Linked PRs

• gh-144228: Remove DIRENT build flag comment #144229
• gh-144228: Remove DONT_HAVE_SIG_ALARM and DONT_HAVE_SIG_PAUSE build flags #144230
• gh-144228: Remove USE_SOCKET build flag #144231
• gh-144228: Remove HAVE_STRERROR build flag #144232
• gh-144228: Remove HAVE_X509_VERIFY_PARAM_SET1_HOST build flag #144235
• gh-144228: Remove HAVE_PUTENV build flag #144236

[vstinner]

If we remove macros, I would suggest to document these removals in the C API category of the Changelog, since the macros are sadly part of the public C API. Some applications may directly or indirectly rely on these macros.

[vstinner]

I'm going to start from PRs one per every item (grouping one or more related macros) in the bullet lists of flags certainly removable.

I would prefer a single PR to remove most macros at once.

[encukou]

These are, accidentally, part of the public API (except the _Py-prefixed ones). I don't think removing them is worth the potential breakage.

Are there any flags listed for removal that still have known downstream or platform‑specific uses?

You have to consider the unknown uses as well.
I think this needs a Discourse topic if you want to push this cleanup forward (but again, I don't think it's worth it).

[johnslavik]

I would prefer a single PR to remove most macros at once.

@vstinner, sorry for rushing with patches :/ I will wait next time. I opened 5 pull requests for nothing. FWIW, we can merge GH-144229 because it just removes a confusing comment and has zero effect on compilation.

These are, accidentally, part of the public API (except the _Py-prefixed ones). I don't think removing them is worth the potential breakage.

Hmmm, do you know if it was a concern in the past? Or is it just that in the past removing one flag had been less risky than bulk-removing leftovers that could break things, which is exactly what I'm proposing?

You have to consider the unknown uses as well.
I think this needs a Discourse topic if you want to push this cleanup forward (but again, I don't think it's worth it).

@encukou, I'd rather trust you this isn't worth it. When I was writing this up, I thought this was very unrealistic people's projects would break because of removing dead pyconfig.h macros. I did not appreciate the concern.

While curious about how flag removal was handled in the past, I'm not planning to push this forward myself, given your worries.

Thank you for quick replies. And again, sorry for the spam. I'll clean up these 5 draft PRs soon.

[encukou]

How were flags removed in the past? Well, accidentally, as far as I know.

Not saying that it wouldn't be nice to clean these macros up. See also #105813. But deprecating/removing macros isn't easy; it's more of a change management/policy change task than something that needs PRs.

[johnslavik]

Yeah, I accept that some things are just not easy to change outright. I definitely could have waited for a green light prior to pushing stuff. PRs closed, lesson learned. Thanks!